@jobshimo/browser-link 0.21.0 → 0.22.0

package/dist/extension/inpage/recorder.js

@@ -0,0 +1,333 @@
+/**
+ * In-page flow recorder — injected via CDP `Runtime.evaluate` ONLY while a
+ * recording is active (see `background.ts`'s `startRecording`/
+ * `stopRecording`). Never present on a page unless the user opted in via
+ * the popup toggle AND pressed Record on that specific tab.
+ *
+ * Communicates with background.ts over a CDP binding (`Runtime.addBinding`
+ * / `Runtime.bindingCalled`, wired in background.ts) rather than a WS/fetch
+ * call — the binding is the one channel CDP gives an in-page script to
+ * reach the extension without any page-visible network traffic. Each
+ * captured user action is emitted as ONE compact JSON string:
+ *
+ *   { nonce, kind: 'click', selector, ambiguous? }
+ *   { nonce, kind: 'type', selector, ambiguous? }
+ *   { nonce, kind: 'press', key }
+ *
+ * THREAT MODEL — the binding function is reachable by EVERY script running
+ * in the page (the page's own code, ads, third-party widgets, injected
+ * XSS). Two layered defenses keep hostile page scripts from fabricating
+ * steps or using the channel for exfiltration:
+ *
+ *  1. PER-SESSION NONCE: background.ts generates a random nonce for each
+ *     recording session and interpolates it into this script at injection
+ *     time. Every emitted payload carries it, and background.ts REJECTS any
+ *     binding call whose nonce does not match the active session — a page
+ *     script calling the binding blind produces zero recorded steps,
+ *     because it cannot know the nonce (it lives only inside this closure
+ *     and in the extension process). The binding NAME is likewise
+ *     randomized per session (see `generateRecordingSession` in
+ *     `recording.ts`) so a page cannot even cheaply probe a well-known
+ *     global to detect that recording is active.
+ *  2. TRUSTED EVENTS ONLY: every listener bails on `!ev.isTrusted`, so
+ *     synthetic events a page dispatches programmatically (`el.click()`,
+ *     `dispatchEvent(new KeyboardEvent(...))`) are never captured as user
+ *     actions. Deliberate tradeoff: page code that activates its OWN
+ *     widgets via `.click()` during a demonstration will not be captured
+ *     either — record the underlying real gesture instead.
+ *  3. GESTURE CORRELATION for type-commits: `isTrusted` alone is NOT
+ *     enough for the focus/blur path — per the HTML spec, programmatic
+ *     `element.focus()` / `.blur()` from page script DO fire
+ *     focus/focusin/blur/focusout events with `isTrusted:true` (unlike
+ *     `.click()`, which fires untrusted). So a hostile page could call
+ *     `attackerInput.focus(); attackerInput.blur()` to walk
+ *     focusin->focusout and fabricate a `{type: selector}` step for an
+ *     attacker-chosen replay target. Defeated by CORRELATION rather than by
+ *     trusting the focus event: a type-commit is emitted only when the
+ *     field's focus was driven by a real user gesture — a trusted
+ *     pointerdown/mousedown that landed on the field just before focus, OR
+ *     a trusted key event on the field while focused. A field that focuses
+ *     and blurs with no such gesture is dropped. (A page cannot forge the
+ *     gesture: synthetic pointer/key events are `isTrusted:false`.)
+ *
+ * Residual risk (documented in the README's privacy section): a script
+ * that can read THIS closure's variables could learn the nonce — but any
+ * script with that power already owns the page outright. The nonce closes
+ * the realistic blind-injection hole, not a hypothetical full-compromise.
+ *
+ * PRIVACY-CRITICAL: the `type` payload NEVER carries the field's value —
+ * there is no field for it in the shape above. `recording.ts` (the
+ * background-side pure step builder) is the ONLY place a placeholder
+ * string is attached, and it always uses the constant `"<TEXT>"` — the
+ * recorder itself has no code path capable of reading, let alone
+ * transmitting, what the user typed. No keystroke-level listener exists
+ * anywhere in this file.
+ *
+ * Idempotent: re-running this expression on a document that already has
+ * the recorder installed is a no-op — matters because `background.ts`
+ * re-injects after every navigation detected while recording, and the two
+ * injections could in principle race on the same document. All three
+ * page-visible globals (the binding function, the active flag, the stop
+ * function) derive from the per-session binding name, so none of them is a
+ * stable, guessable fingerprinting surface. `buildStopRecorderJs()` builds
+ * the companion teardown expression background.ts evaluates on
+ * stop/disconnect/navigation-away.
+ */
+import { DEEP_QUERY_JS } from './deep-query.js';
+import { DOM_HELPERS_JS } from './dom-helpers.js';
+export function buildRecorderJs(opts) {
+    const ACTIVE_FLAG = JSON.stringify(opts.activeFlag);
+    const STOP_FN = JSON.stringify(opts.stopFn);
+    return `
+(() => {
+  if (window[${ACTIVE_FLAG}]) return;
+  window[${ACTIVE_FLAG}] = true;
+  ${DEEP_QUERY_JS}
+  ${DOM_HELPERS_JS}
+
+  const BINDING_NAME = ${JSON.stringify(opts.bindingName)};
+  const NONCE = ${JSON.stringify(opts.nonce)};
+  // Non-text special keys that get their own {press:{key}} step, EXCEPT
+  // Enter — Enter's handling depends on focus (see the keydown listener
+  // below), so it is deliberately not in this list.
+  const SPECIAL_KEYS = ['Escape', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'];
+  // A physical mouse click fires pointerdown then click in quick
+  // succession; this window is how long a click is considered "the same
+  // gesture" as the pointerdown that preceded it, for dedupe purposes.
+  const CLICK_DEDUPE_MS = 800;
+
+  function emit(payload) {
+    try {
+      const fn = window[BINDING_NAME];
+      payload.nonce = NONCE;
+      if (typeof fn === 'function') fn(JSON.stringify(payload));
+    } catch (_) {
+      // Binding gone (recording stopped mid-flight) or serialization
+      // failed — never let the recorder throw into page code.
+    }
+  }
+
+  function deepestTarget(ev) {
+    const path = typeof ev.composedPath === 'function' ? ev.composedPath() : null;
+    const el = path && path.length > 0 ? path[0] : ev.target;
+    return el instanceof Element ? el : null;
+  }
+
+  function isTextField(el) {
+    if (!el) return false;
+    if (el.isContentEditable) return true;
+    // Fall back to the raw attribute — belt-and-braces for engines/test
+    // environments where the isContentEditable computed property is not
+    // fully implemented, and for the (rare) contenteditable="plaintext-only"
+    // spelling some editors use.
+    const ce = el.getAttribute ? el.getAttribute('contenteditable') : null;
+    if (ce === 'true' || ce === '' || ce === 'plaintext-only') return true;
+    const tag = el.tagName;
+    if (tag === 'TEXTAREA') return true;
+    if (tag !== 'INPUT') return false;
+    const type = (el.getAttribute('type') || 'text').toLowerCase();
+    const TEXTY = ['text', 'search', 'email', 'tel', 'url', 'password', 'number', ''];
+    return TEXTY.indexOf(type) !== -1;
+  }
+
+  function emitClickFor(el) {
+    const info = genSelectorInfo(el);
+    const payload = { kind: 'click', selector: info.selector };
+    if (info.ambiguous) payload.ambiguous = true;
+    emit(payload);
+  }
+
+  // === trusted-gesture tracking ===
+  // Records the element + time of the most recent TRUSTED
+  // pointerdown/mousedown, and marks a focused field as "gestured" when a
+  // trusted key event lands on it. Used by the type-commit gate below to
+  // reject fabricated focus/blur sequences (see the THREAT MODEL doc:
+  // element.focus()/.blur() from page script fire focus/blur events with
+  // isTrusted:TRUE — unlike .click() — so the isTrusted guard alone does
+  // NOT stop a page from walking focusin->focusout to fabricate a type
+  // step for an attacker-chosen selector). A window bounds the
+  // pointer-gesture-before-focus correlation; the key-on-field signal is a
+  // per-session boolean, no window needed.
+  const GESTURE_WINDOW_MS = 1000;
+  let lastTrustedPointerTarget = null;
+  let lastTrustedPointerAt = 0;
+
+  function noteTrustedPointer(el) {
+    lastTrustedPointerTarget = el;
+    lastTrustedPointerAt = Date.now();
+  }
+
+  // === click: pointerdown is the primary signal (survives an element
+  // that gets removed from the DOM before 'click' would fire — a common
+  // pattern for menu/dropdown items); 'click' is a fallback for
+  // keyboard-driven activation (Enter/Space on a focused button) and is
+  // deduped against a pointerdown on the SAME element within
+  // CLICK_DEDUPE_MS so one physical mouse click is never recorded twice.
+  // Both bail on untrusted events — see the THREAT MODEL note above. ===
+  let lastPointerDownTarget = null;
+  let lastPointerDownAt = 0;
+
+  function onPointerDown(ev) {
+    if (!ev.isTrusted) return;
+    const target = deepestTarget(ev);
+    if (!target) return;
+    noteTrustedPointer(target);
+    emitClickFor(target);
+    lastPointerDownTarget = target;
+    lastPointerDownAt = Date.now();
+  }
+
+  // mousedown is tracked for gesture-correlation ONLY (it never emits a
+  // click — pointerdown already covers that in every modern Chrome). Some
+  // widgets fire mousedown without a preceding pointerdown in edge cases;
+  // recording the gesture here keeps the type-commit gate from dropping a
+  // legitimate field focus in those cases.
+  function onMouseDown(ev) {
+    if (!ev.isTrusted) return;
+    const target = deepestTarget(ev);
+    if (target) noteTrustedPointer(target);
+  }
+
+  function onClick(ev) {
+    if (!ev.isTrusted) return;
+    const target = deepestTarget(ev);
+    if (!target) return;
+    if (target === lastPointerDownTarget && Date.now() - lastPointerDownAt < CLICK_DEDUPE_MS) {
+      // Second half of the physical click already recorded on pointerdown.
+      lastPointerDownTarget = null;
+      return;
+    }
+    emitClickFor(target);
+  }
+
+  window.addEventListener('pointerdown', onPointerDown, true);
+  window.addEventListener('mousedown', onMouseDown, true);
+  window.addEventListener('click', onClick, true);
+
+  // === type: ONE {type:{selector}} step per focused text field, emitted
+  // on commit (blur / change / Enter). The actual value is NEVER read.
+  //
+  // GATE: a commit is emitted ONLY when the field's focus was driven by a
+  // real user gesture — a trusted pointerdown/mousedown that landed on the
+  // field (or a descendant) just before focus, OR a trusted key event on
+  // the field while it held focus (covers Tab-into-then-type). A field
+  // that focuses and blurs with NO such gesture (a page calling
+  // field.focus(); field.blur()) is DROPPED — it was not user-driven, even
+  // though the focus/blur events themselves are isTrusted:true. ===
+  let focusedField = null; // { el, committed, gestured }
+
+  function commitFocusedField() {
+    if (!focusedField || focusedField.committed) return;
+    focusedField.committed = true;
+    if (!focusedField.gestured) return; // fabricated focus/blur — drop it.
+    const info = genSelectorInfo(focusedField.el);
+    const payload = { kind: 'type', selector: info.selector };
+    if (info.ambiguous) payload.ambiguous = true;
+    emit(payload);
+  }
+
+  function onFocusIn(ev) {
+    if (!ev.isTrusted) return;
+    const target = ev.target;
+    if (!isTextField(target)) {
+      focusedField = null;
+      return;
+    }
+    // Correlate with a just-happened trusted pointer gesture ON this field
+    // (or a child of it, for a click inside a contenteditable). The pointer
+    // gesture fires BEFORE focusin, so this is the moment to check it.
+    const gestured =
+      !!lastTrustedPointerTarget &&
+      Date.now() - lastTrustedPointerAt < GESTURE_WINDOW_MS &&
+      (lastTrustedPointerTarget === target || composedContains(target, lastTrustedPointerTarget));
+    focusedField = { el: target, committed: false, gestured: gestured };
+  }
+
+  function onFocusOut(ev) {
+    if (!ev.isTrusted) return;
+    if (focusedField && ev.target === focusedField.el) {
+      commitFocusedField();
+      focusedField = null;
+    }
+  }
+
+  function onChange(ev) {
+    if (!ev.isTrusted) return;
+    if (focusedField && ev.target === focusedField.el) commitFocusedField();
+  }
+
+  window.addEventListener('focusin', onFocusIn, true);
+  window.addEventListener('focusout', onFocusOut, true);
+  window.addEventListener('change', onChange, true);
+
+  // === press: special keys outside text-field commits. Enter's dedupe
+  // rule is deliberate: Enter WHILE a tracked text field has focus belongs
+  // to that field's type-commit (see commitFocusedField above), never a
+  // separate press step — pressing Enter to submit a search box is one
+  // user action, not two. Tab is NOT swallowed the same way: it both
+  // commits any pending text (moving focus away triggers the same commit
+  // a native blur would) AND is recorded as its own {press:{key:"Tab"}}
+  // step, since Tab is a real, independently-replayable navigational
+  // action distinct from "the field lost focus". ===
+  function onKeyDown(ev) {
+    if (!ev.isTrusted) return;
+    const key = ev.key;
+    const inTrackedField = !!focusedField && ev.target === focusedField.el;
+    // A trusted key event ON the focused field is itself a user gesture —
+    // this is what makes the Tab-into-field-then-type path commit even
+    // though no pointer gesture focused it (the typed keystrokes, or the
+    // Tab keydown that navigates through it, are real user actions). A page
+    // cannot forge these: a synthetic keydown is isTrusted:false and bails
+    // at the top of this handler.
+    if (inTrackedField) focusedField.gestured = true;
+
+    if (key === 'Enter') {
+      if (inTrackedField) {
+        commitFocusedField();
+      } else {
+        emit({ kind: 'press', key: 'Enter' });
+      }
+      return;
+    }
+    if (SPECIAL_KEYS.indexOf(key) === -1) return;
+    if (key === 'Tab' && inTrackedField) commitFocusedField();
+    emit({ kind: 'press', key: key });
+  }
+
+  window.addEventListener('keydown', onKeyDown, true);
+
+  window[${STOP_FN}] = () => {
+    window.removeEventListener('pointerdown', onPointerDown, true);
+    window.removeEventListener('mousedown', onMouseDown, true);
+    window.removeEventListener('click', onClick, true);
+    window.removeEventListener('focusin', onFocusIn, true);
+    window.removeEventListener('focusout', onFocusOut, true);
+    window.removeEventListener('change', onChange, true);
+    window.removeEventListener('keydown', onKeyDown, true);
+    window[${ACTIVE_FLAG}] = false;
+    delete window[${STOP_FN}];
+  };
+})()
+`;
+}
+/** Companion teardown expression for the given session: calls the
+ * installed recorder's own stop function (named by the session's random
+ * `stopFn` global) when present, no-op otherwise (e.g. the tab already
+ * navigated away and the recorder was never re-injected into the new
+ * document — in that case there is nothing to tear down, which is itself
+ * the desired end state). background.ts evaluates this on Stop, on
+ * Discard-while-recording, on tab disconnect/removal/idle-sweep cleanup,
+ * and when the flow-recording setting flips off mid-recording —
+ * teardown-on-every-exit-path is part of the documented privacy contract,
+ * not an optimization. Safe to evaluate any number of times. */
+export function buildStopRecorderJs(stopFn) {
+    const STOP_FN = JSON.stringify(stopFn);
+    return `
+(() => {
+  const stop = window[${STOP_FN}];
+  if (typeof stop === 'function') stop();
+  return true;
+})()
+`;
+}
+//# sourceMappingURL=recorder.js.map

package/dist/extension/inpage/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/inpage/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA0BlD,MAAM,UAAU,eAAe,CAAC,IAA8B;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO;;eAEM,WAAW;WACf,WAAW;IAClB,aAAa;IACb,cAAc;;yBAEO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC;kBACvC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAkNjC,OAAO;;;;;;;;aAQL,WAAW;oBACJ,OAAO;;;CAG1B,CAAC;AACF,CAAC;AAED;;;;;;;;;gEASgE;AAChE,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACvC,OAAO;;wBAEe,OAAO;;;;CAI9B,CAAC;AACF,CAAC"}

package/dist/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "browser-link",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Bridge between Chrome and an MCP client (Claude Code, OpenCode, GitHub Copilot CLI, …). Per-tab manual activation.",
   "permissions": [
     "debugger",

package/dist/extension/popup.html

@@ -453,6 +453,17 @@
         padding: 4px 6px;
         cursor: pointer;
       }
+
+      /* Flow-recording opt-in toggle — same thin-row treatment as the
+       * idle-ttl select, just with a checkbox instead of a <select>. Off by
+       * default; the Record/Stop controls only ever appear when this is on
+       * AND the current tab is connected (see popup.ts). */
+      .settings-row input[type='checkbox'] {
+        width: 15px;
+        height: 15px;
+        cursor: pointer;
+        accent-color: var(--brand-to);
+      }
     </style>
   </head>
   <body>
@@ -553,6 +564,51 @@
         </select>
       </div>
 
+      <!-- Flow-recording opt-in. Off by default — recording UI (Record /
+           Stop / step review) only renders when this is checked AND the
+           active tab is connected. Nothing is ever captured while this is
+           unchecked; see the README's "Recording flows by demonstration"
+           section for the full privacy contract. -->
+      <div class="settings-row">
+        <label for="flow-recording-toggle">Enable flow recording</label>
+        <input type="checkbox" id="flow-recording-toggle" />
+      </div>
+
+      <!-- Recording controls — hidden unless flow recording is enabled AND
+           the active tab is connected (see popup.ts's refreshRecordingUi). -->
+      <div id="recording-row" class="settings-row" hidden>
+        <span id="recording-indicator" hidden>● Recording…</span>
+        <button id="recording-action" class="primary" style="margin-top: 0; width: auto">
+          Record
+        </button>
+      </div>
+
+      <!-- Review panel — shown after Stop, before Save/Discard. -->
+      <div id="recording-review" class="explanation" hidden>
+        <div style="margin-bottom: 6px; font-weight: 600; color: var(--text)">
+          <span id="recording-step-count">0</span> step(s) captured
+        </div>
+        <ol
+          id="recording-step-list"
+          style="margin: 0 0 10px; padding-left: 18px; max-height: 120px; overflow-y: auto"
+        ></ol>
+        <input
+          id="recording-name-input"
+          class="dialog-prompt"
+          type="text"
+          placeholder="Name this flow (e.g. &quot;open task detail dialog&quot;)"
+        />
+        <div
+          id="recording-error"
+          hidden
+          style="color: var(--error-fg); font-size: 11.5px; margin-bottom: 8px"
+        ></div>
+        <div class="dialog-actions">
+          <button id="recording-save" class="primary">Save</button>
+          <button id="recording-discard" class="danger">Discard</button>
+        </div>
+      </div>
+
       <div class="footer">manual · per-tab · loopback only</div>
     </div>
 

package/dist/extension/popup.js

@@ -3,6 +3,8 @@
 // so a plain relative import works the same way background.ts already
 // imports settle.js/keymap.js.
 import { IDLE_TTL_STORAGE_KEY, IDLE_TTL_UPDATED_AT_STORAGE_KEY, clampIdleTtlMinutes, } from './idle-policy.js';
+import { FLOW_RECORDING_STORAGE_KEY, FLOW_RECORDING_UPDATED_AT_STORAGE_KEY, normalizeFlowRecordingEnabled, } from './flow-recording-policy.js';
+import { describeFlowStep } from './recording.js';
 async function getCurrentTab() {
     const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
     return tab;
@@ -165,6 +167,164 @@ async function refreshPendingDialog(tabId) {
     const result = await send({ action: 'pendingDialog', tabId });
     renderPendingDialog(result.pending);
 }
+/**
+ * Flow-recording opt-in toggle. Reads/writes `chrome.storage.local`
+ * directly, same pattern as `refreshIdleTtlSetting`/`onIdleTtlChange` —
+ * background.ts independently reacts to the same key via
+ * `chrome.storage.onChanged`.
+ */
+async function refreshFlowRecordingToggle() {
+    const checkbox = $('flow-recording-toggle');
+    // Same "don't yank a live edit" guard idle-ttl's select uses.
+    if (document.activeElement === checkbox)
+        return;
+    const data = await chrome.storage.local.get(FLOW_RECORDING_STORAGE_KEY);
+    checkbox.checked = normalizeFlowRecordingEnabled(data[FLOW_RECORDING_STORAGE_KEY]);
+}
+async function onFlowRecordingToggleChange() {
+    const checkbox = $('flow-recording-toggle');
+    await chrome.storage.local.set({
+        [FLOW_RECORDING_STORAGE_KEY]: checkbox.checked,
+        [FLOW_RECORDING_UPDATED_AT_STORAGE_KEY]: Date.now(),
+    });
+    // Turning the toggle off mid-recording is handled entirely on the
+    // background.ts side (chrome.storage.onChanged force-stops + discards) —
+    // this just re-renders the popup's own controls to match.
+    const tab = await getCurrentTab();
+    if (!tab?.id)
+        return;
+    const status = await send({ action: 'status', tabId: tab.id });
+    await refreshRecordingUi(tab.id, status.connected);
+}
+/** Render the step-review panel: count (with a cap notice when the 20-step
+ * limit auto-stopped the recording), one line per step via the SAME
+ * `describeFlowStep` background.ts's `recording.ts` module exports — the
+ * popup never re-derives its own description logic. Steps whose selector
+ * was flagged ambiguous get an inline "may match multiple elements"
+ * caution appended, so the computed safety signal is surfaced to the user
+ * before they save (it also travels into the saved recipe's description —
+ * see background.ts's saveRecording). Does not touch the name input, so
+ * repeated calls (the 800ms poll) never interrupt typing. */
+function renderRecordingReview(steps, capped, ambiguousIndices) {
+    $('recording-review').hidden = false;
+    const capNotice = capped ? ' — stopped: 20-step limit reached' : '';
+    $('recording-step-count').textContent = `${steps.length}${capNotice}`;
+    const ambiguous = new Set(ambiguousIndices);
+    const list = $('recording-step-list');
+    list.innerHTML = '';
+    steps.forEach((step, i) => {
+        const li = document.createElement('li');
+        li.textContent = describeFlowStep(step);
+        if (ambiguous.has(i)) {
+            const warn = document.createElement('span');
+            warn.textContent = ' ⚠ selector may match multiple elements';
+            warn.style.color = 'var(--idle-fg)';
+            li.appendChild(warn);
+        }
+        list.appendChild(li);
+    });
+}
+function setRecordingError(message) {
+    const el = $('recording-error');
+    if (message === null) {
+        el.hidden = true;
+        el.textContent = '';
+        return;
+    }
+    el.hidden = false;
+    el.textContent = message;
+}
+/**
+ * Show/hide and populate the Record/Stop/review controls for `tabId`.
+ * Hidden entirely unless flow recording is enabled AND the tab is
+ * connected — "ALL recording UI is hidden ... when disabled" from the
+ * privacy contract is enforced right here, not just by the recorder never
+ * being injected.
+ */
+async function refreshRecordingUi(tabId, connected) {
+    const recordingRow = $('recording-row');
+    const data = await chrome.storage.local.get(FLOW_RECORDING_STORAGE_KEY);
+    const enabled = normalizeFlowRecordingEnabled(data[FLOW_RECORDING_STORAGE_KEY]);
+    if (!enabled || !connected) {
+        recordingRow.hidden = true;
+        $('recording-review').hidden = true;
+        return;
+    }
+    const status = await send({ action: 'recordingStatus', tabId });
+    recordingRow.hidden = false;
+    const indicator = $('recording-indicator');
+    const actionBtn = $('recording-action');
+    if (status.reviewing) {
+        indicator.hidden = true;
+        actionBtn.hidden = true;
+        renderRecordingReview(status.steps ?? [], status.capped, status.ambiguousStepIndices ?? []);
+        return;
+    }
+    actionBtn.hidden = false;
+    $('recording-review').hidden = true;
+    if (status.active) {
+        indicator.hidden = false;
+        actionBtn.textContent = 'Stop';
+        actionBtn.className = 'danger';
+    }
+    else {
+        indicator.hidden = true;
+        actionBtn.textContent = 'Record';
+        actionBtn.className = 'primary';
+    }
+}
+async function onRecordingAction() {
+    const tab = await getCurrentTab();
+    if (!tab?.id)
+        return;
+    setRecordingError(null);
+    const status = await send({ action: 'recordingStatus', tabId: tab.id });
+    if (status.active) {
+        const result = await send({ action: 'stopRecording', tabId: tab.id });
+        if (!result.ok)
+            setRecordingError(result.error ?? 'Could not stop recording.');
+    }
+    else {
+        const result = await send({ action: 'startRecording', tabId: tab.id });
+        if (!result.ok)
+            setRecordingError(result.error ?? 'Could not start recording.');
+    }
+    await refreshRecordingUi(tab.id, true);
+}
+async function onSaveRecording() {
+    const tab = await getCurrentTab();
+    if (!tab?.id)
+        return;
+    const nameInput = $('recording-name-input');
+    const saveBtn = $('recording-save');
+    setRecordingError(null);
+    saveBtn.disabled = true;
+    try {
+        const result = await send({
+            action: 'saveRecording',
+            tabId: tab.id,
+            name: nameInput.value,
+        });
+        if (!result.ok) {
+            setRecordingError(result.error ?? 'Could not save the flow.');
+            return;
+        }
+        nameInput.value = '';
+        await refreshRecordingUi(tab.id, true);
+    }
+    finally {
+        saveBtn.disabled = false;
+    }
+}
+async function onDiscardRecording() {
+    const tab = await getCurrentTab();
+    if (!tab?.id)
+        return;
+    await send({ action: 'discardRecording', tabId: tab.id });
+    $('recording-name-input').value = '';
+    setRecordingError(null);
+    await refreshRecordingUi(tab.id, true);
+}
 async function refresh() {
     // Always refresh the version banner — it has no dependency on the active
     // tab, only on whether ANY tab has registered with the server.
@@ -177,6 +337,8 @@ async function refresh() {
         urlEl.textContent = '';
         setExplanation(null);
         renderPendingDialog(null);
+        $('recording-row').hidden = true;
+        $('recording-review').hidden = true;
         return;
     }
     urlEl.textContent = tab.url ?? '';
@@ -195,6 +357,7 @@ async function refresh() {
         setAction('Connect this tab', 'primary');
         renderPendingDialog(null);
     }
+    await refreshRecordingUi(tab.id, status.connected);
 }
 async function respondToDialog(accept) {
     const tab = await getCurrentTab();
@@ -271,18 +434,43 @@ $('idle-ttl-select').addEventListener('change', () => {
         // control to whatever actually made it into storage.
     });
 });
-// Poll for pending dialogs, version drift, AND the idle-ttl setting while
-// the popup is open. Cheap (one round trip per concern, fast paths return
-// null/aligned/unchanged) and only runs while the popup window is visible
-// — Chrome unloads the popup on close.
+$('flow-recording-toggle').addEventListener('change', () => {
+    onFlowRecordingToggleChange().catch(() => {
+        // Best effort — the next poll tick re-syncs the checkbox.
+    });
+});
+$('recording-action').addEventListener('click', () => {
+    onRecordingAction().catch((err) => {
+        setRecordingError(err instanceof Error ? err.message : String(err));
+    });
+});
+$('recording-save').addEventListener('click', () => {
+    onSaveRecording().catch((err) => {
+        setRecordingError(err instanceof Error ? err.message : String(err));
+    });
+});
+$('recording-discard').addEventListener('click', () => {
+    onDiscardRecording().catch(() => {
+        // Best effort.
+    });
+});
+// Poll for pending dialogs, version drift, the idle-ttl setting, AND the
+// flow-recording setting/status while the popup is open. Cheap (one round
+// trip per concern, fast paths return null/aligned/unchanged) and only
+// runs while the popup window is visible — Chrome unloads the popup on
+// close. The recording poll is what surfaces a background.ts-side
+// auto-stop (the 20-step cap) without the user having to reopen the popup.
 setInterval(() => {
     void (async () => {
         await refreshVersionBanner();
         await refreshIdleTtlSetting();
+        await refreshFlowRecordingToggle();
         const tab = await getCurrentTab();
         if (!tab?.id)
             return;
         await refreshPendingDialog(tab.id);
+        const status = await send({ action: 'status', tabId: tab.id });
+        await refreshRecordingUi(tab.id, status.connected);
     })();
 }, 800);
 refresh().catch((err) => {
@@ -291,4 +479,7 @@ refresh().catch((err) => {
 refreshIdleTtlSetting().catch(() => {
     // Best effort — the periodic timer above retries every 800ms regardless.
 });
+refreshFlowRecordingToggle().catch(() => {
+    // Best effort — same rationale as refreshIdleTtlSetting above.
+});
 //# sourceMappingURL=popup.js.map