π¬ 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
docs: record the pause invariants and the blur coverage limits
davbio5f297f387333
diff --git a/AGENTS.md b/AGENTS.mdindex 8f5a57f..77e5527 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -97,7 +97,7 @@ src/| Layer | Tool | Purpose ||-------|------|---------|-| Capture lifecycle | xstate | State machine (IDLE β RECORDING) in background service worker |+| Capture lifecycle | xstate | State machine (IDLE β RECORDING β PAUSED) in background service worker || Fullview UI | Zustand | Search modal, guide counts, active guide data || Persistence | Dexie (IndexedDB) | Guides, steps, screenshots, snapshots || Service worker recovery | sessionStorage | xstate machine snapshot persistence |@@ -125,6 +125,8 @@ Content Script ββ Background Service Worker ββ Sidepanel / Fullview- `getState` β current capture state, step count, guide ID- `startRecording({url})` β creates guide, returns guideId- `stopRecording()` β finalizes guide, generates AI title+- `pauseCapture()` / `resumeCapture()` β RECORDING β PAUSED, plus the stop/start broadcast+- `enterBlurMode()` / `exitBlurMode()` β the same pause, with the blur overlay and `pauseReason: 'blur'`- `captureStep({guideId, action, elementMeta, domContext})` β screenshots + creates step- `updateInputStep({stepId, description})` β updates typing step description- `finalizeInputStep({stepId, elementMeta, domContext})` β final screenshot + AI description@@ -133,6 +135,7 @@ Content Script ββ Background Service Worker ββ Sidepanel / Fullview- `PING` / `START_CAPTURE` / `STOP_CAPTURE` β lifecycle- `SHOW_NOTIFICATION` β "Recording started" overlay- `URL_CHANGED` / `GET_ROUTE` β SPA navigation tracking+- `START_BLUR` / `DISMISS_BLUR` / `CLEAR_BLUR` β blur overlay: open, close keeping masks, close removing masks## Capture Pipeline@@ -258,6 +261,14 @@ Font: Poppins (loaded via `@fontsource/poppins`).- **DOM context** sent as text to AI instead of screenshots β 15-30x cheaper per step- **Hover ring** (`lib/hover-ring.ts`) is a closed-Shadow-DOM host marked `data-mimik-ignore`, shared by recording and the blur picker (purple). Recording reads the user's `targetColor` so the live ring matches the dashed target baked into screenshots. Never drawn on `iframe`/`embed`/`object` β a capture inside a subframe can't hide the top frame's ring- **Content script injection** pings first, falls back to `chrome.scripting.executeScript()` for tabs without the script+- **`PAUSED` is a real machine state**, not a flag. It carries a `pauseReason` (`'blur' | 'manual'`) and deliberately does not handle `USER_ACTION`, so nothing can advance `stepCount` while the UI says capture is paused. `CaptureSession.syncWithBackground` only starts on `RECORDING`, so a frame that loads mid-pause stays idle instead of silently resuming. Background step writes are gated on `RECORDING` too, for a frame that missed the stop broadcast+- **Pausing also stops the microphone.** `pauseCapture` flushes and stops narration when it was live, and `resumeCapture` restarts it β otherwise speech during the pause is transcribed and attributed to the step captured after the resume. The mic toggle locks while paused, since narration cannot start outside `RECORDING`+- **Pausing waits for the frames to drain.** `broadcastStopCaptureAndFlush` is answered only once each content script's queue is idle, because `CaptureController.stop()` enqueues the input session's finalize. `handleFinalizeInputStep` is therefore gated on "not IDLE" rather than `RECORDING`: it only ever completes a step the user finished before pausing, and `enterBlurMode` awaits the flush before opening the overlay so that screenshot cannot catch it+- **Navigation listeners treat `PAUSED` as live** (`navigation.ts:isLive`). `URL_CHANGED` has to keep flowing or the first step after a resume is stamped with the pre-pause URL, which Guide Me then replays to; injection has to keep running or a tab opened mid-pause is deaf to the resume broadcast+- **Blur mode pauses via that state**, and a top frame booting into `PAUSED`/`'blur'` re-opens the overlay, so a navigation mid-blur still has a Done button. `exitBlurMode` and the panel's Resume both broadcast `DISMISS_BLUR` before resuming, which closes the overlay but keeps the masks the user just picked; only the end of a recording sends `CLEAR_BLUR` to remove them+- **Smart blur cannot reach** iframes, shadow DOM, canvas/image text, `::before`/`::after`, `<select>`/`<option>`, or attribute-only values like `title`/`alt`; it runs in the top frame only, and a matching input blurs as a whole field. SVG `<text>` *is* blurred. These limits are documented in all five READMEs and *partly* pinned by `core/blur/__tests__/scanner.test.ts` β shadow DOM, `select`/`option`, attribute-only values and whole-field input blur have assertions; canvas/image text, `::before`/`::after` and top-frame-only do not (the last lives in `content.ts`, not the scanner). Move the READMEs with any scanner change+- **Paused-ness is read from the state value, never from `pauseReason`.** A snapshot persisted before `PAUSED` existed has no `pauseReason` key, so it restores as `undefined` β and `undefined !== null` read as paused, which left the panel offering Resume while the machine was still `RECORDING`. `getStateUpdate` normalises the reason to `null`; the reason only picks the wording. The same applies to any context key added later: a restored snapshot will not have it+- **`BlurManager.start()` re-checks `active` after awaiting the presets.** A stop landing inside that await tore down a panel that did not exist yet, and the pending `start()` then mounted it with `active` already `false`, so nothing could ever close it. Any new `await` before the panel mounts needs the same guard- **xstate snapshot** persisted to sessionStorage so the state machine survives service worker restarts- **Recording notification** uses `animationend` event (not hardcoded delays) for timing- **Font loading** uses `@fontsource/poppins` (CSP-safe, no CDN dependency)