π¬ 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(capture): screenshot the page before the click reaches it
Luis Ortiz1e44e5c0231f
diff --git a/src/core/capture/__tests__/click-intercept.test.ts b/src/core/capture/__tests__/click-intercept.test.tsnew file mode 100644index 0000000..20b78a2--- /dev/null+++ b/src/core/capture/__tests__/click-intercept.test.ts@@ -0,0 +1,90 @@+// @vitest-environment jsdom+import { describe, expect, it } from 'vitest';+import { replayClick, replayInit, shouldInterceptClick } from '@/core/capture/events/click-intercept';++function el(html: string): HTMLElement {+ const host = document.createElement('div');+ host.innerHTML = html;+ document.body.appendChild(host);+ return host.firstElementChild as HTMLElement;+}++function click(over: Partial<MouseEventInit> & { isTrusted?: boolean } = {}): MouseEvent {+ return {+ isTrusted: true,+ shiftKey: false,+ ctrlKey: false,+ altKey: false,+ metaKey: false,+ button: 0,+ buttons: 1,+ detail: 1,+ clientX: 40,+ clientY: 90,+ screenX: 0,+ screenY: 0,+ ...over,+ } as MouseEvent;+}++describe('shouldInterceptClick', () => {+ it('intercepts an ordinary button, which is the whole point', () => {+ expect(shouldInterceptClick(el('<button>Copy link</button>'), click())).toBe(true);+ });++ it('lets our own replayed click through untouched', () => {+ expect(shouldInterceptClick(el('<button>Copy link</button>'), click({ isTrusted: false }))).toBe(false);+ });++ it('steps aside for a shift-click so the real action can happen', () => {+ expect(shouldInterceptClick(el('<button>Copy link</button>'), click({ shiftKey: true }))).toBe(false);+ });++ it('leaves native dropdowns alone, which break when their click is blocked', () => {+ expect(shouldInterceptClick(el('<select><option>a</option></select>'), click())).toBe(false);+ expect(shouldInterceptClick(el('<option>a</option>'), click())).toBe(false);+ });++ it('leaves editable surfaces alone so the caret still lands', () => {+ const editable = el('<div contenteditable="true">notes</div>');+ Object.defineProperty(editable, 'isContentEditable', { value: true });+ expect(shouldInterceptClick(editable, click())).toBe(false);+ });++ it('leaves text fields to the typing session', () => {+ expect(shouldInterceptClick(el('<input type="text">'), click())).toBe(false);+ expect(shouldInterceptClick(el('<textarea></textarea>'), click())).toBe(false);+ });++ it('still intercepts a checkbox, which is a click and not typing', () => {+ expect(shouldInterceptClick(el('<input type="checkbox">'), click())).toBe(true);+ });+});++describe('replayInit', () => {+ it('carries the pointer position through to the replayed click', () => {+ const init = replayInit(click({ clientX: 120, clientY: 340 }));+ expect(init).toMatchObject({ clientX: 120, clientY: 340, bubbles: true, cancelable: true });+ });++ it('preserves the modifier keys the page may branch on', () => {+ const init = replayInit(click({ ctrlKey: true, metaKey: true, altKey: true, button: 1 }));+ expect(init).toMatchObject({ ctrlKey: true, metaKey: true, altKey: true, button: 1 });+ });++ it('reaches a delegated listener on the document as an untrusted click', () => {+ const button = el('<button>Copy link</button>');+ const seen: Array<{ trusted: boolean; x: number }> = [];+ document.addEventListener('click', (e) => seen.push({ trusted: e.isTrusted, x: (e as MouseEvent).clientX }), {+ once: true,+ });+ replayClick(button, replayInit(click({ clientX: 77 })));+ expect(seen).toEqual([{ trusted: false, x: 77 }]);+ });++ it('focuses the target first, the way a real click would', () => {+ const button = el('<button>Copy link</button>');+ replayClick(button, replayInit(click()));+ expect(document.activeElement).toBe(button);+ });+});diff --git a/src/core/capture/events/__tests__/click-replay.test.ts b/src/core/capture/events/__tests__/click-replay.test.tsnew file mode 100644index 0000000..e5abded--- /dev/null+++ b/src/core/capture/events/__tests__/click-replay.test.ts@@ -0,0 +1,159 @@+// @vitest-environment happy-dom+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { sendMessage } from '@/lib/messaging';+import { type CaptureHandle, startCapture } from '../handlers';++vi.mock('@/lib/messaging', () => ({ sendMessage: vi.fn(), onMessage: vi.fn() }));++vi.mock('@/lib/browser-api', () => ({+ localStorage: { get: vi.fn().mockResolvedValue({}), set: vi.fn().mockResolvedValue(undefined) },+}));++interface Deferred {+ promise: Promise<{ stepId: string }>;+ resolve: () => void;+ reject: (err: Error) => void;+}++let pending: Deferred[];+let handle: CaptureHandle;++function deferred(): Deferred {+ let resolve!: () => void;+ let reject!: (err: Error) => void;+ const promise = new Promise<{ stepId: string }>((ok, no) => {+ resolve = () => ok({ stepId: 'step-1' });+ reject = no;+ });+ return { promise, resolve, reject };+}++function place(tag: string): HTMLElement {+ const el = document.createElement(tag);+ Object.defineProperty(el, 'getBoundingClientRect', {+ value: () => ({ x: 4, y: 6, top: 6, left: 4, right: 124, bottom: 46, width: 120, height: 40 }),+ });+ document.body.appendChild(el);+ return el;+}++function userClick(el: Element, over: MouseEventInit = {}) {+ const event = new MouseEvent('click', { bubbles: true, cancelable: true, clientX: 10, clientY: 20, ...over });+ Object.defineProperty(event, 'isTrusted', { configurable: true, value: true });+ el.dispatchEvent(event);+ return event;+}++async function settle(turns = 16) {+ for (let i = 0; i < turns; i++) await new Promise((resolve) => setTimeout(resolve, 0));+}++beforeEach(() => {+ document.body.innerHTML = '';+ vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {+ setTimeout(() => cb(0), 0);+ return 0;+ });+ pending = [];+ vi.mocked(sendMessage).mockClear();+ vi.mocked(sendMessage).mockImplementation((() => {+ const d = deferred();+ pending.push(d);+ return d.promise;+ }) as unknown as typeof sendMessage);+ handle = startCapture('guide-1');+});++afterEach(() => {+ handle.stop();+ for (const d of pending) d.resolve();+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ document.body.innerHTML = '';+});++describe('click interception', () => {+ it('keeps the click from the page until the screenshot has been taken', async () => {+ const button = place('button');+ let seen = 0;+ button.addEventListener('click', () => {+ seen += 1;+ });++ userClick(button);+ await settle();++ expect(seen).toBe(0);+ expect(sendMessage).toHaveBeenCalledWith('captureStep', expect.anything());+ });++ it('performs the click once the capture resolves', async () => {+ const button = place('button');+ let seen = 0;+ button.addEventListener('click', () => {+ seen += 1;+ });++ userClick(button);+ await settle();+ expect(seen).toBe(0);++ for (const d of pending) d.resolve();+ await settle();++ expect(seen).toBe(1);+ });++ it('still performs the click when the capture fails, so nothing is swallowed', async () => {+ const button = place('button');+ let seen = 0;+ button.addEventListener('click', () => {+ seen += 1;+ });++ userClick(button);+ await settle();+ for (const d of pending) d.reject(new Error('background gone'));+ await settle();++ expect(seen).toBe(1);+ });++ it('does not record its own replay as a second step', async () => {+ const button = place('button');++ userClick(button);+ await settle();+ for (const d of pending) d.resolve();+ await settle();++ expect(vi.mocked(sendMessage).mock.calls.filter((c) => c[0] === 'captureStep')).toHaveLength(1);+ });++ it('lets a shift-click through untouched and records nothing', async () => {+ const button = place('button');+ let seen = 0;+ button.addEventListener('click', () => {+ seen += 1;+ });++ userClick(button, { shiftKey: true });+ await settle();++ expect(seen).toBe(1);+ expect(sendMessage).not.toHaveBeenCalled();+ });++ it('leaves a text field click to the typing session rather than replaying it', async () => {+ const field = place('input');+ let seen = 0;+ field.addEventListener('click', () => {+ seen += 1;+ });++ userClick(field);+ await settle();++ expect(seen).toBe(1);+ });+});diff --git a/src/core/capture/events/click-intercept.ts b/src/core/capture/events/click-intercept.tsnew file mode 100644index 0000000..dd3c501--- /dev/null+++ b/src/core/capture/events/click-intercept.ts@@ -0,0 +1,43 @@+import { isTextField } from '../dom/element-utils';++const replayed = new WeakSet<Event>();++export function isReplayedClick(event: Event): boolean {+ return replayed.has(event);+}++export function shouldInterceptClick(target: HTMLElement, event: MouseEvent): boolean {+ if (!event.isTrusted || event.shiftKey) return false;+ if (target instanceof HTMLSelectElement || target instanceof HTMLOptionElement) return false;+ if (target.isContentEditable) return false;+ return !isTextField(target);+}++export function replayInit(event: MouseEvent): PointerEventInit {+ return {+ bubbles: true,+ cancelable: true,+ composed: true,+ detail: event.detail,+ button: event.button,+ buttons: event.buttons,+ clientX: event.clientX,+ clientY: event.clientY,+ screenX: event.screenX,+ screenY: event.screenY,+ ctrlKey: event.ctrlKey,+ altKey: event.altKey,+ shiftKey: event.shiftKey,+ metaKey: event.metaKey,+ pointerId: 1,+ pointerType: 'mouse',+ isPrimary: true,+ };+}++export function replayClick(target: HTMLElement, init: PointerEventInit): void {+ if (target.isConnected && target.tabIndex >= 0) target.focus();+ const event = new PointerEvent('click', init);+ replayed.add(event);+ target.dispatchEvent(event);+}diff --git a/src/core/capture/events/handlers.ts b/src/core/capture/events/handlers.tsindex 9336f1c..0f35040 100644--- a/src/core/capture/events/handlers.ts+++ b/src/core/capture/events/handlers.ts@@ -2,6 +2,7 @@ import PQueue from 'p-queue';import { DEFAULT_TARGET_COLOR } from '@/core/screenshot/types';import { localStorage } from '@/lib/browser-api';import { HoverRing } from '@/lib/hover-ring';+import { logger } from '@/lib/logger';import { sendMessage } from '@/lib/messaging';import { extractDOMContext } from '../dom/context';import { extractElementMeta, freezeRect } from '../dom/element-meta';@@ -12,12 +13,14 @@ import {isTextField,isTooLarge,} from '../dom/element-utils';+import { isReplayedClick, replayClick, replayInit, shouldInterceptClick } from './click-intercept';import { InputSession } from './input-session';const DEDUP_MS = 300;const DRAG_MIN_PX = 30;const INTERCEPT_DELAY_MS = 100;const PAINT_FRAMES = 3;+const CAPTURE_BUDGET_MS = 2500;const EMBED_TAGS = new Set(['IFRAME', 'EMBED', 'OBJECT']);const EMBED_SELECTOR = 'iframe, embed, object';@@ -26,6 +29,10 @@ function focusInEmbed(): boolean {return !!active && EMBED_TAGS.has(active.tagName);}+function sleep(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+}+function waitForPaint(): Promise<void> {return new Promise((resolve) => {let remaining = PAINT_FRAMES;@@ -147,7 +154,7 @@ class CaptureController {private onClick(e: Event) {const me = e as MouseEvent;const raw = me.target;- if (!raw || !(raw instanceof Element)) return;+ if (!raw || !(raw instanceof Element) || isReplayedClick(me) || me.shiftKey) return;const target = findFocusableAncestor(raw);if (isMimikElement(target)) return;@@ -181,7 +188,25 @@ class CaptureController {return;}- this.enqueue(this.capture('click', target, { x: me.clientX, y: me.clientY }));+ const task = this.capture('click', target, { x: me.clientX, y: me.clientY });++ if (!shouldInterceptClick(target, me)) {+ this.enqueue(task);+ return;+ }++ me.preventDefault();+ me.stopImmediatePropagation();+ const init = replayInit(me);+ this.enqueue(async () => {+ try {+ await Promise.race([task(), sleep(CAPTURE_BUDGET_MS)]);+ } catch (err) {+ logger.warn('Capture failed, replaying the click anyway', err);+ } finally {+ replayClick(target, init);+ }+ });}private onAuxClick(e: Event) {