π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
feat(desktop): zoom in quarter steps normalised to the guide column
Luis Ortize83eff389e19
diff --git a/AGENTS.md b/AGENTS.mdindex 9bef1f6..de97574 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -591,11 +591,13 @@ fraction of the viewport and collapses on a screen grab: a 30 px window button aa crop a few hundred pixels wide, which the card then stretches. Magnification past 1:1 cannot lookgood, because the detail is not in the file.-So `clickZoomViewport` sizes the region from the frame rather than the control β 55% of its width,-floored at 1100 px and capped at the frame β centred on the click and clamped inside. A 2560 Γ 1440-capture yields 1408 Γ 792, about 1.8Γ, which still lands at or below the size it is displayed at; a-1200 px window yields 1100, barely a zoom; anything at or under 1100 px yields the whole frame. Zoom-appears only where there are spare pixels to spend on it.+So the zoom is a level between 1 and 5 in steps of 0.25, `snapZoom` holds it there, and+`clickZoomViewport` divides the frame by it and centres the result on the click, clamped inside the+edges. The level itself is `autoZoom`'s: the capture's width over the guide column's, so every step+renders its content at the same size however it was framed. A 2560 px screen grab at 1.5Γ scaling+gives 2.25, a 1200 px window gives 1, and a small one gives 1 β the same button is the same size on+every page of the guide, which a fixed fraction of the frame cannot do. The level is stored beside+the region in `edits.zoomLevel`, so it can be re-derived or overridden later without recapturing.It goes in `edits.viewport` rather than `bounds` because `resolveViewport` returns that verbatim, sothe region is exactly what was computed rather than what the padding rule makes of it, anddiff --git a/apps/desktop/src/renderer/check-pipeline.ts b/apps/desktop/src/renderer/check-pipeline.tsindex d85ec0a..e3d54f0 100644--- a/apps/desktop/src/renderer/check-pipeline.ts+++ b/apps/desktop/src/renderer/check-pipeline.ts@@ -100,10 +100,12 @@ window.mimik.onRequest('mimik:check:verify', async (payload) => {viewport.x + viewport.width <= shot.width &&viewport.y + viewport.height <= shot.height &&zoom >= 1 &&- zoom <= 2 &&+ zoom <= 5 &&+ (shot.edits?.zoomLevel ?? 0) >= 1 &&+ Math.abs((shot.edits?.zoomLevel ?? 0) * 4 - Math.round((shot.edits?.zoomLevel ?? 0) * 4)) < 1e-9 &&(shot.edits?.target?.width ?? 0) > 0,detail: shot- ? `${zoom.toFixed(2)}x β viewport ${viewport?.width} Γ ${viewport?.height} of ${shot.width} Γ ${shot.height}, inside the frame`+ ? `level ${shot.edits?.zoomLevel}, ${zoom.toFixed(2)}x β viewport ${viewport?.width} Γ ${viewport?.height} of ${shot.width} Γ ${shot.height}, inside the frame`: 'no screenshot',});diff --git a/packages/core/src/screenshot/__tests__/record.test.ts b/packages/core/src/screenshot/__tests__/record.test.tsindex 4c3bb43..e22d41a 100644--- a/packages/core/src/screenshot/__tests__/record.test.ts+++ b/packages/core/src/screenshot/__tests__/record.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from 'vitest';import type { ElementMeta } from '@/core/guides/types';import { resolveViewport } from '@/core/screenshot/geometry';-import { clickZoomViewport, screenshotForElement } from '@/core/screenshot/record';+import { autoZoom, clickZoomViewport, screenshotForElement, snapZoom } from '@/core/screenshot/record';const meta: ElementMeta = {textContent: null,@@ -56,22 +56,40 @@ describe('screenshotForElement', () => {});});+describe('snapZoom', () => {+ it('snaps to quarter steps between 1 and 5', () => {+ expect(snapZoom(2.19)).toBe(2.25);+ expect(snapZoom(1.02)).toBe(1);+ expect(snapZoom(0.4)).toBe(1);+ expect(snapZoom(9)).toBe(5);+ expect(snapZoom(3.37)).toBe(3.25);+ });+});++describe('autoZoom', () => {+ it('picks the level that renders content the same size whatever the capture', () => {+ expect(autoZoom(2560, 1.5)).toBe(2.25);+ expect(autoZoom(1200, 1.5)).toBe(1);+ expect(autoZoom(800, 1)).toBe(1);+ expect(autoZoom(3840, 2)).toBe(2.5);+ });+});+describe('clickZoomViewport', () => {- it('zooms a large screen but never past what its pixels support', () => {- const big = clickZoomViewport(2560, 1440, { x: 1280, y: 720 });- expect(big.width).toBe(1408);- expect(big.height).toBe(792);- expect(2560 / big.width).toBeCloseTo(1.82, 2);+ it('divides the frame by the zoom level', () => {+ const big = clickZoomViewport(2560, 1440, { x: 1280, y: 720 }, 2.25);+ expect(big.width).toBeCloseTo(1137.8, 1);+ expect(big.height).toBeCloseTo(640, 1);});- it('barely zooms a window-sized frame and not at all a small one', () => {- expect(clickZoomViewport(1200, 800, { x: 600, y: 400 }).width).toBe(1100);- expect(clickZoomViewport(800, 600, { x: 400, y: 300 })).toEqual({ x: 0, y: 0, width: 800, height: 600 });+ it('shows the whole frame at 1x and clamps a level past the range', () => {+ expect(clickZoomViewport(1200, 800, { x: 600, y: 400 }, 1)).toEqual({ x: 0, y: 0, width: 1200, height: 800 });+ expect(clickZoomViewport(1200, 800, { x: 600, y: 400 }, 9).width).toBe(240);});it('centres on the click and stays inside the frame', () => {- expect(clickZoomViewport(2560, 1440, { x: 1600, y: 900 })).toMatchObject({ x: 896, y: 504 });- expect(clickZoomViewport(2560, 1440, { x: 10, y: 10 })).toMatchObject({ x: 0, y: 0 });- expect(clickZoomViewport(2560, 1440, { x: 2550, y: 1430 })).toMatchObject({ x: 1152, y: 648 });+ expect(clickZoomViewport(2560, 1440, { x: 1600, y: 900 }, 2)).toMatchObject({ x: 960, y: 540 });+ expect(clickZoomViewport(2560, 1440, { x: 10, y: 10 }, 2)).toMatchObject({ x: 0, y: 0 });+ expect(clickZoomViewport(2560, 1440, { x: 2550, y: 1430 }, 2)).toMatchObject({ x: 1280, y: 720 });});});diff --git a/packages/core/src/screenshot/record.ts b/packages/core/src/screenshot/record.tsindex cebb0af..328304d 100644--- a/packages/core/src/screenshot/record.ts+++ b/packages/core/src/screenshot/record.ts@@ -3,8 +3,11 @@ import { type CursorMark, DEFAULT_TARGET_COLOR } from '@/core/screenshot/types';export type ZoomMode = 'element' | 'click' | 'none';-const CLICK_ZOOM_FRACTION = 0.55;-const MIN_CLICK_ZOOM_WIDTH = 1100;+export const MIN_ZOOM = 1;+export const MAX_ZOOM = 5;+export const ZOOM_STEP = 0.25;++const GUIDE_CONTENT_WIDTH = 780;export interface ScreenshotBytes {id: string;@@ -17,15 +20,29 @@ export interface ScreenshotBytes {cursor?: CursorMark | null;targetColor?: string;zoom?: ZoomMode;+ zoomLevel?: number;}function clamp(value: number, min: number, max: number): number {return Math.max(min, Math.min(max, value));}-export function clickZoomViewport(width: number, height: number, click: { x: number; y: number }): ScreenshotBounds {- const visWidth = Math.min(width, Math.max(width * CLICK_ZOOM_FRACTION, MIN_CLICK_ZOOM_WIDTH));- const visHeight = Math.min(height, (visWidth * height) / width);+export function snapZoom(zoom: number): number {+ return clamp(Math.round(zoom / ZOOM_STEP) * ZOOM_STEP, MIN_ZOOM, MAX_ZOOM);+}++export function autoZoom(width: number, pixelRatio: number): number {+ return snapZoom(width / (GUIDE_CONTENT_WIDTH * (pixelRatio || 1)));+}++export function clickZoomViewport(+ width: number,+ height: number,+ click: { x: number; y: number },+ zoom: number,+): ScreenshotBounds {+ const visWidth = width / snapZoom(zoom);+ const visHeight = (visWidth * height) / width;return {x: clamp(click.x - visWidth / 2, 0, width - visWidth),y: clamp(click.y - visHeight / 2, 0, height - visHeight),@@ -35,9 +52,10 @@ export function clickZoomViewport(width: number, height: number, click: { x: num}export function screenshotForElement(bytes: ScreenshotBytes, meta: ElementMeta): StoredScreenshot {- const { cursor, targetColor, zoom = 'element', ...rest } = bytes;+ const { cursor, targetColor, zoom = 'element', zoomLevel, ...rest } = bytes;const ratio = meta.devicePixelRatio;const click = meta.clickPoint ?? { x: meta.rect.x + meta.rect.width / 2, y: meta.rect.y + meta.rect.height / 2 };+ const level = zoomLevel ?? autoZoom(rest.width, ratio);return {...rest,...(zoom === 'element'@@ -48,7 +66,10 @@ export function screenshotForElement(bytes: ScreenshotBytes, meta: ElementMeta):edits: {...(cursor === undefined ? {} : { cursor }),...(zoom === 'click'- ? { viewport: clickZoomViewport(rest.width, rest.height, { x: click.x * ratio, y: click.y * ratio }) }+ ? {+ zoomLevel: level,+ viewport: clickZoomViewport(rest.width, rest.height, { x: click.x * ratio, y: click.y * ratio }, level),+ }: {}),target: {x: meta.rect.x * ratio,diff --git a/packages/core/src/screenshot/types.ts b/packages/core/src/screenshot/types.tsindex 31446b0..8657392 100644--- a/packages/core/src/screenshot/types.ts+++ b/packages/core/src/screenshot/types.ts@@ -151,6 +151,7 @@ export interface CursorMark {export interface ScreenshotEdits {viewport?: ScreenshotBounds;+ zoomLevel?: number;target?: ClickTarget | null;annotations?: Annotation[];cursor?: CursorMark | null;