Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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) {