π¬ 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: describe the hover ring and queued step descriptions
Luis Ortiz902fc415f905
diff --git a/AGENTS.md b/AGENTS.mdindex 5a80259..9a2bbb6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -35,7 +35,6 @@ src/β β β βββ element-utils.ts # findFocusableAncestor, isTextField, etc.β β βββ events/ # Event capture systemβ β β βββ handlers.ts # CaptureController class + startCapture-β β β βββ highlight.ts # HighlightManager (dashed border overlay)β β β βββ input-session.ts # InputSession (typing lifecycle)β β βββ machine.ts # xstate capture state machineβ β βββ session.ts # CaptureSession (lifecycle manager)@@ -126,7 +125,6 @@ Content Script ββ Background Service Worker ββ Sidepanel / Fullview**Tab messages** (content script β background, `lib/tab-messages.ts`):- `PING` / `START_CAPTURE` / `STOP_CAPTURE` β lifecycle-- `HIDE_OVERLAY` / `SHOW_OVERLAY` β overlay toggle (fallback, used for non-click captures)- `SHOW_NOTIFICATION` β "Recording started" overlay- `URL_CHANGED` / `GET_ROUTE` β SPA navigation tracking@@ -142,22 +140,22 @@ Content Script ββ Background Service Worker ββ Sidepanel / Fullview**Capture a click:**1. Content script's CaptureController detects click via DOM event listener2. Click handler pushes async work into PQueue (concurrency: 1)-3. Queue processes: hides overlay instantly β sends `captureStep` to background β waits-4. Background calls `captureVisibleTab` (overlay is hidden, page hasn't reacted yet)+3. Enqueueing hides the hover ring (`pointerdown` already did, on mouse paths); queue waits 3 frames then sends `captureStep`+4. Background calls `captureVisibleTab` (ring is hidden, page hasn't reacted yet)5. Saves Screenshot + Step to IndexedDB-6. Optionally generates AI description from DOM context text (not screenshot)-7. Returns `{ stepId }` β content script shows overlay β queue processes next event+6. Queues the AI description from DOM context text (serialized in the background; the step carries `aiPending` until it lands) rather than awaiting it+7. Returns `{ stepId }` β queue processes next event; the ring returns only once the queue is fully drained**Capture text input (typing):**1. Click on text field β CaptureController starts InputSession β `captureStep` with initial screenshot2. Each keystroke β InputSession.update() β `updateInputStep` (description only, fire-and-forget)-3. Enter/Escape/focusout β InputSession.finalize() β `finalizeInputStep` β final screenshot replaces initial + AI description+3. Enter/Escape/focusout β InputSession.finalize() β `finalizeInputStep` β final screenshot replaces initial + queued AI description4. Result: one step for entire typing interaction**Stop recording:**1. Background transitions RECORDING β IDLE2. Broadcasts `STOP_CAPTURE`, content scripts flush pending input sessions-3. Background generates guide title from step descriptions + URLs via AI+3. Background drains queued step descriptions (20s cap), then generates the guide title from step descriptions + URLs via AI4. Opens fullview dashboard with the guide## DOM Context (AI Input)@@ -237,11 +235,11 @@ Font: Poppins (loaded via `@fontsource/poppins`).## Key Technical Details-- **Async event queue** in content script (PQueue, concurrency 1) serializes capture work β each action awaits the full background round-trip before the next starts-- **Overlay hidden from content script side** (instant `display:none`) before sending capture message β no round-trip delay for overlay toggle+- **Async event queue** in content script (PQueue, concurrency 1) serializes capture work β each action awaits the background round-trip (screenshot + step write, not the AI description) before the next starts+- **Hover ring hidden when work is enqueued** (`CaptureController.enqueue`, instant `display:none`), and `show()` stays suppressed until the queue drains β a second click while the first capture is still in flight can't bring the ring back before the screenshot. `pointerdown` hides it earlier still, on top of `captureAction`'s 3-frame wait- **Input session** aggregates all typing on a field into one step β click creates it, keystrokes update description, finalize takes final screenshot- **DOM context** sent as text to AI instead of screenshots β 15-30x cheaper per step-- **Highlight overlay** uses a custom web component (`<mimik-highlight>`) with closed Shadow DOM at max z-index+- **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- **xstate snapshot** persisted to sessionStorage so the state machine survives service worker restarts- **Recording notification** uses `animationend` event (not hardcoded delays) for timing