@descryy/runtime-browser 0.4.8 → 0.5.0

package/dist/browser-recording-collector.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Recording: turns a HUMAN's own interactions with an already-open page into
+ * an ordered, timestamped stream a host can hand straight to a scenario
+ * builder -- the descry-core follow-up this package owes
+ * (`documents/decisions-inbox/DEC-NEXT-browser-recording-primitive.md`,
+ * `descry-core`'s `packages/mcp/src/browser/driver.ts`:
+ * `BrowserPageSession.startRecording`/`stopRecording`). Nothing here writes
+ * anything or drives the page itself -- the opposite direction from
+ * `BrowserActionCollector`, which *commands* the page and reports what it
+ * did. This collector only listens.
+ *
+ * Four kinds of interaction, matching the port's own `BrowserActionKind`
+ * vocabulary so the host can forward a captured event as a
+ * `PerformedTarget`/`PerformedStep` with no translation of the action name
+ * itself:
+ *  - `click`, on the same interactive-element set `playwright-driver.ts`'s
+ *    own `INTERACTIVE` constant already uses for a snapshot
+ *    (`a, button, input, select, textarea, [role], [onclick], summary`) --
+ *    clicking a checkbox or radio is captured here, not by the `change`
+ *    listener below (see that listener's own comment on why).
+ *  - `fill`, for a text field's value once it is COMMITTED -- the native
+ *    `change` event, which a text `<input>`/`<textarea>` fires on blur only
+ *    when its value actually changed since focus. Not `input`: capturing
+ *    every keystroke would record a value no scenario replay wants (a
+ *    partially-typed string), and `fill`, not `type`, because a recording
+ *    only ever knows a field's final value, never the keystroke sequence
+ *    that produced it -- the same distinction `browser-action-collector.ts`
+ *    draws between its two text verbs, resolved here the only way it can be.
+ *  - `select`, for a `<select>`'s `change` event -- its own branch, not the
+ *    text-field one, because "a chooser's value changed" and "a field's text
+ *    was committed" are different facts (mirrors `BrowserActionCollector
+ *    .select()`).
+ *  - `navigate`, for a real top-level (main-frame) navigation, observed
+ *    directly off Playwright's own `framenavigated` rather than through the
+ *    page-side script -- the frame that navigated *is* the fact, and asking
+ *    the page to report its own navigation would miss the first instant of
+ *    the new document.
+ *
+ * **Passwords never leave the page.** A field this collector's page-side
+ * script recognises as a password field (`type="password"`, or
+ * `autocomplete="current-password"`/`"new-password"`) reports `secret: true`
+ * and never reads `.value` into the payload it sends across the binding at
+ * all -- not captured-then-redacted, never captured. `text` on the resulting
+ * `RecordedInteraction` is `null` whenever `secret` is `true`; assembling the
+ * actual `${credential:NAME}` placeholder is the host's job
+ * (`recordedSecretCredentialName`/`recordedSecretPlaceholder`,
+ * `descry-core`'s `driver.ts`) because only the host knows this session's
+ * running count of secrets recorded so far -- the ordinal that keeps two
+ * distinct password fields from colliding onto the same credential name.
+ *
+ * **Selector preference** reuses the identical tiered rule
+ * `playwright-driver.ts`'s own `computeSelector` already applies for a
+ * snapshot element: a `data-testid`/`data-test` hook first, then a
+ * non-generated `id`, then a named form control, then an
+ * aria-labelled-and-roled element, then a bounded structural path anchored at
+ * the nearest ancestor carrying one of the above -- each tier accepted only
+ * when it is unique in the element's own root (`document`, or the open
+ * shadow root it lives in). It is restated here, not imported, for the same
+ * reason `driver.ts` restates `PerformedTarget` rather than importing a
+ * scenario type: the string below is serialised into the page verbatim
+ * (`page.addInitScript`/`page.evaluate`), and a page-side script cannot
+ * import a Node module.
+ *
+ * **Listener lifecycle.** `page.exposeFunction` and `page.addInitScript` are
+ * each installed at most once per collector instance (lazily, on the first
+ * `start()`) -- Playwright refuses a second `exposeFunction` under the same
+ * name, and a second `addInitScript` would double-register the in-page
+ * listeners on every navigation after that. Because `addInitScript` "doesn't
+ * reach an already-loaded document" (the same contract every other probe in
+ * this package documents -- `frontend-initiator-capture.ts`,
+ * `identity-grounding`'s probes), `start()` ALSO runs the identical
+ * installer directly via `page.evaluate` against whatever document is
+ * current right now, idempotently (a `window` marker skips a second
+ * install), so a recording that starts mid-session on an already-open page
+ * is not silently missing its first document's events.
+ *
+ * A capturing session can therefore be started and stopped more than once
+ * without re-installing anything: `start()`/`stop()` do not attach or detach
+ * the page-side listeners themselves (Playwright exposes no way to
+ * un-expose a function or un-register an init script), they gate a
+ * `capturing` flag the Node-side binding handler checks before pushing to
+ * the buffer -- the identical "an unattached listener produces nothing"
+ * discipline `descry-core`'s fake driver already documents for its own
+ * `recordHuman*` methods. The one exception is the `framenavigated`
+ * listener, which genuinely is `page.on`/`page.off` in `start()`/`stop()`,
+ * matching `BrowserConsoleCollector`'s own precedent, because Playwright
+ * offers a real way to detach it.
+ */
+import type { BrowserSession } from "./browser-session.ts";
+/** The element actually acted on -- role, accessible name, a selector when one is addressable. Mirrors the port's own `PerformedTarget` field-for-field so a host can forward this unmodified. */
+export interface RecordedTarget {
+    readonly role: string;
+    readonly name: string;
+    /** Null when no candidate was unique in this element's own root -- the same "no guessed selector" rule every other selector computation in this repo follows. */
+    readonly selector: string | null;
+}
+/** One human-driven interaction, in the order it was observed. */
+export interface RecordedInteraction {
+    readonly action: "click" | "fill" | "select" | "navigate";
+    /** The element acted on. Null for `navigate`, which acts on the page, not an element. */
+    readonly target: RecordedTarget | null;
+    /** Where a `navigate` went. Null for every other action. */
+    readonly url: string | null;
+    /** The committed value, for `fill`/`select`. Null for `click`/`navigate`, and ALWAYS null when `secret` is true -- see this module's header. */
+    readonly text: string | null;
+    /** True only for a `fill` whose source field this collector's page-side script recognised as a password field. When true, `text` is null and was never populated from the field's real value in the first place. */
+    readonly secret: boolean;
+    readonly at: string;
+}
+export interface BrowserRecordingCollectorOptions {
+    readonly session: BrowserSession;
+}
+export interface BrowserRecordingCollector {
+    /** Starts (or resumes) capturing. Throws if the session's page has already crashed or closed, or if this collector is already capturing -- call `stop()` first. */
+    start(): Promise<void>;
+    /** Stops capturing and returns every interaction captured since `start()`, in order. Throws if this collector is not currently capturing. */
+    stop(): Promise<readonly RecordedInteraction[]>;
+}
+export declare function createBrowserRecordingCollector(options: BrowserRecordingCollectorOptions): BrowserRecordingCollector;
+//# sourceMappingURL=browser-recording-collector.d.ts.map

package/dist/browser-recording-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-recording-collector.d.ts","sourceRoot":"","sources":["../src/browser-recording-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,kMAAkM;AAClM,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iKAAiK;IACjK,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC1D,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gJAAgJ;IAChJ,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oNAAoN;IACpN,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,mKAAmK;IACnK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,6IAA6I;IAC7I,IAAI,IAAI,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;CACjD;AAqOD,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,gCAAgC,GAAG,yBAAyB,CAuEpH"}

package/dist/browser-recording-collector.js

@@ -0,0 +1,372 @@
+/**
+ * Recording: turns a HUMAN's own interactions with an already-open page into
+ * an ordered, timestamped stream a host can hand straight to a scenario
+ * builder -- the descry-core follow-up this package owes
+ * (`documents/decisions-inbox/DEC-NEXT-browser-recording-primitive.md`,
+ * `descry-core`'s `packages/mcp/src/browser/driver.ts`:
+ * `BrowserPageSession.startRecording`/`stopRecording`). Nothing here writes
+ * anything or drives the page itself -- the opposite direction from
+ * `BrowserActionCollector`, which *commands* the page and reports what it
+ * did. This collector only listens.
+ *
+ * Four kinds of interaction, matching the port's own `BrowserActionKind`
+ * vocabulary so the host can forward a captured event as a
+ * `PerformedTarget`/`PerformedStep` with no translation of the action name
+ * itself:
+ *  - `click`, on the same interactive-element set `playwright-driver.ts`'s
+ *    own `INTERACTIVE` constant already uses for a snapshot
+ *    (`a, button, input, select, textarea, [role], [onclick], summary`) --
+ *    clicking a checkbox or radio is captured here, not by the `change`
+ *    listener below (see that listener's own comment on why).
+ *  - `fill`, for a text field's value once it is COMMITTED -- the native
+ *    `change` event, which a text `<input>`/`<textarea>` fires on blur only
+ *    when its value actually changed since focus. Not `input`: capturing
+ *    every keystroke would record a value no scenario replay wants (a
+ *    partially-typed string), and `fill`, not `type`, because a recording
+ *    only ever knows a field's final value, never the keystroke sequence
+ *    that produced it -- the same distinction `browser-action-collector.ts`
+ *    draws between its two text verbs, resolved here the only way it can be.
+ *  - `select`, for a `<select>`'s `change` event -- its own branch, not the
+ *    text-field one, because "a chooser's value changed" and "a field's text
+ *    was committed" are different facts (mirrors `BrowserActionCollector
+ *    .select()`).
+ *  - `navigate`, for a real top-level (main-frame) navigation, observed
+ *    directly off Playwright's own `framenavigated` rather than through the
+ *    page-side script -- the frame that navigated *is* the fact, and asking
+ *    the page to report its own navigation would miss the first instant of
+ *    the new document.
+ *
+ * **Passwords never leave the page.** A field this collector's page-side
+ * script recognises as a password field (`type="password"`, or
+ * `autocomplete="current-password"`/`"new-password"`) reports `secret: true`
+ * and never reads `.value` into the payload it sends across the binding at
+ * all -- not captured-then-redacted, never captured. `text` on the resulting
+ * `RecordedInteraction` is `null` whenever `secret` is `true`; assembling the
+ * actual `${credential:NAME}` placeholder is the host's job
+ * (`recordedSecretCredentialName`/`recordedSecretPlaceholder`,
+ * `descry-core`'s `driver.ts`) because only the host knows this session's
+ * running count of secrets recorded so far -- the ordinal that keeps two
+ * distinct password fields from colliding onto the same credential name.
+ *
+ * **Selector preference** reuses the identical tiered rule
+ * `playwright-driver.ts`'s own `computeSelector` already applies for a
+ * snapshot element: a `data-testid`/`data-test` hook first, then a
+ * non-generated `id`, then a named form control, then an
+ * aria-labelled-and-roled element, then a bounded structural path anchored at
+ * the nearest ancestor carrying one of the above -- each tier accepted only
+ * when it is unique in the element's own root (`document`, or the open
+ * shadow root it lives in). It is restated here, not imported, for the same
+ * reason `driver.ts` restates `PerformedTarget` rather than importing a
+ * scenario type: the string below is serialised into the page verbatim
+ * (`page.addInitScript`/`page.evaluate`), and a page-side script cannot
+ * import a Node module.
+ *
+ * **Listener lifecycle.** `page.exposeFunction` and `page.addInitScript` are
+ * each installed at most once per collector instance (lazily, on the first
+ * `start()`) -- Playwright refuses a second `exposeFunction` under the same
+ * name, and a second `addInitScript` would double-register the in-page
+ * listeners on every navigation after that. Because `addInitScript` "doesn't
+ * reach an already-loaded document" (the same contract every other probe in
+ * this package documents -- `frontend-initiator-capture.ts`,
+ * `identity-grounding`'s probes), `start()` ALSO runs the identical
+ * installer directly via `page.evaluate` against whatever document is
+ * current right now, idempotently (a `window` marker skips a second
+ * install), so a recording that starts mid-session on an already-open page
+ * is not silently missing its first document's events.
+ *
+ * A capturing session can therefore be started and stopped more than once
+ * without re-installing anything: `start()`/`stop()` do not attach or detach
+ * the page-side listeners themselves (Playwright exposes no way to
+ * un-expose a function or un-register an init script), they gate a
+ * `capturing` flag the Node-side binding handler checks before pushing to
+ * the buffer -- the identical "an unattached listener produces nothing"
+ * discipline `descry-core`'s fake driver already documents for its own
+ * `recordHuman*` methods. The one exception is the `framenavigated`
+ * listener, which genuinely is `page.on`/`page.off` in `start()`/`stop()`,
+ * matching `BrowserConsoleCollector`'s own precedent, because Playwright
+ * offers a real way to detach it.
+ */
+const RECORDING_BINDING_NAME = "__descryRecordInteraction";
+/** The same interactive-element set `playwright-driver.ts`'s `INTERACTIVE` constant already scopes a snapshot to -- kept identical so a click this collector captures is always one a snapshot-based replay could also have resolved. */
+const INTERACTIVE_SELECTOR = "a, button, input, select, textarea, [role], [onclick], summary";
+/**
+ * Serialised and run inside the page (`page.addInitScript`/`page.evaluate`)
+ * -- closes over nothing in this module. Idempotent: re-running it against a
+ * document that already has the listeners installed (the `window` marker)
+ * is a deliberate no-op, so calling it once via `addInitScript`'s
+ * registration and once more directly via `page.evaluate` at `start()` time
+ * (for the document already open when recording starts) never double-fires
+ * an event.
+ */
+function installerScriptSource() {
+    return `(() => {
+    const MARKER = "__descryRecordingInstalled";
+    if (window[MARKER] === true) return;
+    const bind = window[${JSON.stringify(RECORDING_BINDING_NAME)}];
+    if (typeof bind !== "function") return;
+    window[MARKER] = true;
+
+    const GENERATED_ID = /[0-9a-f]{8}|:r[0-9a-z]+:|^\\s*$/i;
+    const FORM_CONTROLS = ["input", "select", "textarea", "button"];
+    const TEXT_INPUT_TYPES = ["", "text", "email", "tel", "url", "search", "number", "password"];
+
+    function escapeAttrValue(value) {
+      return value.replace(/\\\\/g, "\\\\\\\\").replace(/"/g, '\\\\"');
+    }
+
+    function rootOf(el) {
+      return typeof el.getRootNode === "function" ? el.getRootNode() : el.ownerDocument;
+    }
+
+    function isUnique(root, candidate) {
+      try {
+        return root.querySelectorAll(candidate).length === 1;
+      } catch (e) {
+        return false;
+      }
+    }
+
+    function stableHookSelector(node) {
+      const testId = node.getAttribute("data-testid");
+      if (testId && testId.trim() !== "") return '[data-testid="' + escapeAttrValue(testId) + '"]';
+      const testAttr = node.getAttribute("data-test");
+      if (testAttr && testAttr.trim() !== "") return '[data-test="' + escapeAttrValue(testAttr) + '"]';
+      const id = node.getAttribute("id");
+      if (id && !GENERATED_ID.test(id)) return '[id="' + escapeAttrValue(id) + '"]';
+      return null;
+    }
+
+    function nthOfTypeSegment(node, parent) {
+      const tag = node.tagName.toLowerCase();
+      const siblings = parent.querySelectorAll(":scope > " + tag);
+      if (siblings.length <= 1) return tag;
+      for (let i = 0; i < siblings.length; i += 1) {
+        if (siblings[i] === node) return tag + ":nth-of-type(" + (i + 1) + ")";
+      }
+      return tag;
+    }
+
+    function structuralPath(target, root) {
+      const segments = [];
+      let node = target;
+      for (let depth = 0; depth < 6; depth += 1) {
+        const parent = node.parentElement;
+        if (!parent) return null;
+        segments.unshift(nthOfTypeSegment(node, parent));
+        const hook = stableHookSelector(parent);
+        if (hook) {
+          const candidate = hook + " > " + segments.join(" > ");
+          return isUnique(root, candidate) ? candidate : null;
+        }
+        node = parent;
+      }
+      return null;
+    }
+
+    function computeSelector(target) {
+      const root = rootOf(target);
+      const testId = target.getAttribute("data-testid");
+      if (testId && testId.trim() !== "") {
+        const candidate = '[data-testid="' + escapeAttrValue(testId) + '"]';
+        if (isUnique(root, candidate)) return candidate;
+      }
+      const testAttr = target.getAttribute("data-test");
+      if (testAttr && testAttr.trim() !== "") {
+        const candidate = '[data-test="' + escapeAttrValue(testAttr) + '"]';
+        if (isUnique(root, candidate)) return candidate;
+      }
+      const id = target.getAttribute("id");
+      if (id && !GENERATED_ID.test(id)) {
+        const candidate = '[id="' + escapeAttrValue(id) + '"]';
+        if (isUnique(root, candidate)) return candidate;
+      }
+      const tag = target.tagName.toLowerCase();
+      const name = target.getAttribute("name");
+      if (name && name.trim() !== "" && FORM_CONTROLS.indexOf(tag) !== -1) {
+        const candidate = tag + '[name="' + escapeAttrValue(name) + '"]';
+        if (isUnique(root, candidate)) return candidate;
+      }
+      const explicitRole = target.getAttribute("role");
+      const ariaLabel = target.getAttribute("aria-label");
+      if (explicitRole && ariaLabel && ariaLabel.trim() !== "") {
+        const candidate = '[role="' + escapeAttrValue(explicitRole) + '"][aria-label="' + escapeAttrValue(ariaLabel) + '"]';
+        if (isUnique(root, candidate)) return candidate;
+      }
+      return structuralPath(target, root);
+    }
+
+    function derivedRole(el) {
+      const tag = el.tagName.toLowerCase();
+      const explicit = el.getAttribute("role");
+      if (explicit) return explicit;
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      if (tag === "a") return "link";
+      if (tag === "button") return "button";
+      if (tag === "textarea") return "textbox";
+      if (tag === "summary") return "button";
+      if (tag === "select") {
+        const multiple = el.getAttribute("multiple") !== null;
+        const size = Number(el.getAttribute("size") || "1");
+        return multiple || size > 1 ? "listbox" : "combobox";
+      }
+      if (tag !== "input") return tag;
+      switch (type) {
+        case "button":
+        case "submit":
+        case "reset":
+        case "image":
+          return "button";
+        case "checkbox":
+          return "checkbox";
+        case "radio":
+          return "radio";
+        case "range":
+          return "slider";
+        case "number":
+          return "spinbutton";
+        case "search":
+          return "searchbox";
+        default:
+          return "textbox";
+      }
+    }
+
+    function derivedName(el) {
+      const tag = el.tagName.toLowerCase();
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      const aria = el.getAttribute("aria-label");
+      if (aria && aria.trim() !== "") return aria;
+      if (tag !== "select") {
+        const inner = (el.innerText || "").trim();
+        if (inner !== "") return inner;
+        const text = (el.textContent || "").trim();
+        if (text !== "") return text;
+      }
+      if (tag === "input" && (type === "button" || type === "submit" || type === "reset")) {
+        const value = el.getAttribute("value");
+        if (value && value.trim() !== "") return value.trim();
+      }
+      return el.getAttribute("placeholder") || el.getAttribute("title") || el.getAttribute("name") || "";
+    }
+
+    function isPasswordField(el) {
+      if (el.tagName.toLowerCase() !== "input") return false;
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      if (type === "password") return true;
+      const autocomplete = (el.getAttribute("autocomplete") || "").toLowerCase();
+      return autocomplete === "current-password" || autocomplete === "new-password";
+    }
+
+    function describeTarget(el) {
+      return { role: derivedRole(el), name: derivedName(el).slice(0, 200), selector: computeSelector(el) };
+    }
+
+    document.addEventListener(
+      "click",
+      function (ev) {
+        const el = ev.target && typeof ev.target.closest === "function" ? ev.target.closest(${JSON.stringify(INTERACTIVE_SELECTOR)}) : null;
+        if (!el) return;
+        const described = describeTarget(el);
+        bind({ action: "click", role: described.role, name: described.name, selector: described.selector, value: null, secret: false }).catch(function () {});
+      },
+      true,
+    );
+
+    document.addEventListener(
+      "change",
+      function (ev) {
+        const el = ev.target;
+        if (!el || !el.tagName) return;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "select") {
+          const described = describeTarget(el);
+          const value = el.multiple ? Array.prototype.map.call(el.selectedOptions, function (o) { return o.value; }).join(",") : el.value;
+          bind({ action: "select", role: described.role, name: described.name, selector: described.selector, value: value, secret: false }).catch(function () {});
+          return;
+        }
+        if (tag === "input" || tag === "textarea") {
+          const type = (el.getAttribute("type") || "").toLowerCase();
+          // Only a text-shaped control's committed value is a "fill" -- a checkbox/radio's
+          // own change is a state toggle, not a value entered, and is already reported by
+          // the click listener above (the click that toggled it matches INTERACTIVE too).
+          if (tag === "input" && TEXT_INPUT_TYPES.indexOf(type) === -1) return;
+          const secret = isPasswordField(el);
+          const described = describeTarget(el);
+          // The whole point: a password field's real value is never read into this payload at all.
+          bind({ action: "fill", role: described.role, name: described.name, selector: described.selector, value: secret ? null : el.value, secret: secret }).catch(function () {});
+        }
+      },
+      true,
+    );
+  })();`;
+}
+export function createBrowserRecordingCollector(options) {
+    const { session } = options;
+    const page = session.page;
+    let capturing = false;
+    let buffer = [];
+    let bindingInstalled = false;
+    function onRecordedInteraction(payload) {
+        if (!capturing)
+            return; // an unattached listener producing nothing -- see this module's header.
+        buffer.push({
+            action: payload.action,
+            target: { role: payload.role, name: payload.name, selector: payload.selector },
+            url: null,
+            text: payload.secret ? null : payload.value,
+            secret: payload.secret,
+            at: new Date().toISOString(),
+        });
+    }
+    function onFrameNavigated(frame) {
+        if (!capturing)
+            return;
+        if (frame !== page.mainFrame())
+            return; // "top-level" -- an iframe's own navigation is not this session's page moving.
+        buffer.push({ action: "navigate", target: null, url: frame.url(), text: null, secret: false, at: new Date().toISOString() });
+    }
+    async function ensureInstalled() {
+        if (!bindingInstalled) {
+            // Playwright refuses a second `exposeFunction` under the same name and would
+            // double-register in-page listeners on a second `addInitScript` -- both installed
+            // at most once per collector instance, ever.
+            await page.exposeFunction(RECORDING_BINDING_NAME, onRecordedInteraction);
+            await page.addInitScript({ content: installerScriptSource() });
+            bindingInstalled = true;
+        }
+        // `addInitScript` only reaches documents navigated to AFTER it is registered -- this
+        // session may already be sitting on a page when recording starts, so the identical,
+        // idempotent installer also runs directly against whatever document is current now.
+        await page.evaluate(installerScriptSource()).catch(() => {
+            // No accessible document to evaluate against right now (e.g. mid-navigation). Not
+            // fatal: `addInitScript` still covers every document from here forward, so a
+            // human's first observable interaction is only missed if it happens in the exact
+            // instant no document is present to click or type into.
+        });
+    }
+    return {
+        async start() {
+            if (!session.isUsable()) {
+                throw new Error(`browser session ${session.sessionId}: the page has already crashed or closed.`);
+            }
+            if (capturing) {
+                throw new Error(`browser session ${session.sessionId}: already recording. Call stop() before starting again.`);
+            }
+            await ensureInstalled();
+            buffer = [];
+            capturing = true;
+            page.on("framenavigated", onFrameNavigated);
+        },
+        async stop() {
+            if (!capturing) {
+                throw new Error(`browser session ${session.sessionId}: not currently recording. Call start() first.`);
+            }
+            page.off("framenavigated", onFrameNavigated);
+            capturing = false;
+            const captured = buffer;
+            buffer = [];
+            return captured;
+        },
+    };
+}
+//# sourceMappingURL=browser-recording-collector.js.map

package/dist/browser-recording-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-recording-collector.js","sourceRoot":"","sources":["../src/browser-recording-collector.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export type { DomElementSnapshot } from "./dom-evidence.ts";
 export { captureElementSnapshot } from "./dom-evidence.ts";
 export type { BrowserActionCollectorOptions, BrowserActionCollector, WaitForOptions } from "./browser-action-collector.ts";
 export { createBrowserActionCollector } from "./browser-action-collector.ts";
+export type { BrowserRecordingCollectorOptions, BrowserRecordingCollector, RecordedTarget, RecordedInteraction, } from "./browser-recording-collector.ts";
+export { createBrowserRecordingCollector } from "./browser-recording-collector.ts";
 export type { BrowserConsoleCollectorOptions } from "./browser-console-collector.ts";
 export { createBrowserConsoleCollector } from "./browser-console-collector.ts";
 export type { BrowserNetworkCollectorOptions, CapturedResponseBody } from "./browser-network-collector.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EAIvB,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,YAAY,EAAE,6BAA6B,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3H,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAE7E,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAE/E,YAAY,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE7H,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAEvE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EAIvB,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,YAAY,EAAE,6BAA6B,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC3H,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAE7E,YAAY,EACV,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,mBAAmB,GACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAC;AAEnF,YAAY,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAE/E,YAAY,EAAE,8BAA8B,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3G,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE7H,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAEvE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ export { launchBrowserSession, launchBrowserSessionOrRefuse, resolveChromiumExec
 createSharedBrowserManager, SHARED_BROWSER_IDLE_TIMEOUT_MS, } from "./browser-session.js";
 export { captureElementSnapshot } from "./dom-evidence.js";
 export { createBrowserActionCollector } from "./browser-action-collector.js";
+export { createBrowserRecordingCollector } from "./browser-recording-collector.js";
 export { createBrowserConsoleCollector } from "./browser-console-collector.js";
 export { createBrowserNetworkCollector, captureResponseBody, MAX_RESPONSE_BODY_BYTES } from "./browser-network-collector.js";
 export { extractHeaderCorrelationIds } from "./network-correlation.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB;AACvB,8EAA8E;AAC9E,qFAAqF;AACrF,mFAAmF;AACnF,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAG7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAG/E,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAG7H,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB;AACvB,8EAA8E;AAC9E,qFAAqF;AACrF,mFAAmF;AACnF,0BAA0B,EAC1B,8BAA8B,GAC/B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAQ7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAC;AAGnF,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAG/E,OAAO,EAAE,6BAA6B,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAG7H,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descryy/runtime-browser",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "type": "module",
   "description": "Browser runtime: launch, isolated context, navigation, click/type/wait, DOM inspection, screenshots, console/page-error/network capture, all through the Collector contract (plan §7/§8). See documents/decisions-inbox/PROPOSAL-B-playwright-for-browser-runtime.md for the Playwright-vs-CDP call. BrowserSession.injectStorageState (0.4.5) is the mid-session counterpart to the launch-time auth seed -- lands cookies/localStorage into a session that is already open, for a scenario's sign-in step.",
   "license": "UNLICENSED",
@@ -25,17 +25,17 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc -b"
-  },
   "dependencies": {
     "@descryy/runtime-contracts": "0.3.3",
     "@descryy/runtime-backend-observation": "0.3.6",
     "playwright-core": "^1.62.1",
-    "@descryy/runtime-adapter-typescript": "0.3.7"
+    "@descryy/runtime-adapter-typescript": "0.3.8"
   },
   "devDependencies": {
-    "@descryy/runtime-controller": "0.3.7",
+    "@descryy/runtime-controller": "0.3.9",
     "@descryy/runtime-evidence-store": "0.4.2"
+  },
+  "scripts": {
+    "build": "tsc -b"
   }
-}
+}