@descryy/mcp 0.6.0 → 0.7.1

package/dist/browser/playwright-driver.d.ts

@@ -1,99 +1,26 @@
 /**
- * The real `BrowserDriver`, over `@descryy/runtime-browser`.
- *
- * ## Why the import is still dynamic
- *
- * `@descryy/runtime-browser` is now a declared dependency of `@descryy/mcp`
- * (`mcp-browser-tools.md` §3.1's publish landed) — so the reason this module
- * used to give for a call-time specifier import, "not on the registry yet,"
- * no longer holds. It stays dynamic anyway, for a reason that outgrew that
- * one: `loadRuntimeModule` (`PlaywrightDriverOptions`, below) is a real
- * injection seam that `browser-action-settle.test.ts` uses today to drive
- * this file's settle logic against a fake module shaped like this one,
- * deterministically, with no real browser involved. A static
- * `import … from "@descryy/runtime-browser"` at the top of this file would
- * remove that seam along with the indirection, and nothing here needs
- * removing it — the package being on the registry made the *dependency*
- * declarable, not the import path mandatory. Absence (package missing,
- * import throws, or Chromium missing) is still a **named refusal with a
- * remedy**, exactly as before — see `provider.ts`.
- *
- * ## What this adds over the runtime package, and what it deliberately does not
- *
- * It adds exactly one thing the runtime has no API for: **element refs.** The
- * port's contract is that an action names an element the agent has seen, and
- * `BrowserActionCollector` acts on raw selectors. So this module enumerates
- * the page's interactive elements, holds a Playwright `ElementHandle` per ref,
- * and drops the whole map on navigation. Handles rather than injected `data-`
- * attributes on purpose: stamping the DOM would make the act of observing
- * change the page being observed, and a detached element then fails naturally
- * instead of resolving to whatever took its place.
- *
- * Everything else is composition. Launch, click, type, fill, console capture,
- * network capture, the `fetch()` initiator stack and its source-map rewrite
- * are all the runtime package's, called rather than reimplemented.
- *
- * ## Rule 1
- *
- * No language is named here. The stack-trace parser that turns a raw browser
- * stack into resolved frames is handed in by the caller as a module specifier
- * — the same mechanism `runtime-registry.ts` uses for runtime adapters, for
- * the same reason. Without one, requests are still observed and no caller
- * edge is written; the reply says so.
+ * The real `BrowserDriver`, over `@descryy/runtime-browser`. Import stays
+ * dynamic — `loadRuntimeModule` is a test injection seam (fake module, no
+ * browser needed). Adds only element refs over the runtime; stack-trace parsing is caller-supplied (rule 1: no language named here).
  */
 import type { StackTrace, ServiceRootLookup } from "@descryy/runtime-contracts";
 import type { StackTraceParser } from "@descryy/runtime-backend-observation";
 import type { BrowserDriver, BrowserObservation, ObservedAction, UnsettledAction } from "./driver.ts";
 export interface PlaywrightDriverOptions {
-    /**
-     * Turns a raw browser stack into resolved frames. Supplied by the caller;
-     * this package cannot construct one without naming a language.
-     *
-     * Absent, the initiator capture is not installed at all — the runtime's own
-     * two-halves-or-neither rule — so no request carries a call site and no R4
-     * caller edge can be written.
-     */
+    /** Turns a raw stack into resolved frames; caller-supplied (rule 1: no language named here). Absent, initiator capture isn't installed and no R4 caller edge is written. */
     readonly stackParser?: StackTraceParser;
     /** Maps a page origin to the on-disk root that served it. Absent means script URLs stay unresolved. */
     readonly resolveSourceRoot?: SourceRootResolver;
     /** Which service the evidence is attributed to. */
     readonly service?: string;
-    /**
-     * How the runtime browser module is loaded. Defaults to importing
-     * `@descryy/runtime-browser` by specifier.
-     *
-     * It exists because the settle logic below is timing-dependent and this
-     * build has no browser backend to run it against — the conformance test
-     * that would exercise it skips on every machine without
-     * `@descryy/runtime-browser` and Chromium. A driver-level fake page is the
-     * only way that logic is executable at all here — and a sleep that dropped
-     * evidence shipped in this file with no executable test over it at all,
-     * which is the argument for the seam rather than against it.
-     *
-     * Keep it. Ruled on when it was introduced: exporting `openSession` instead
-     * would widen the public surface to an internal lifecycle, where this
-     * narrows to one injection point with a stated purpose.
-     */
+    /** Loads the runtime browser module; overridable because the settle logic below is timing-dependent and this build has no browser backend to test it against otherwise. Keep narrow — do not export `openSession` instead. */
     readonly loadRuntimeModule?: () => Promise<unknown>;
 }
 type SourceRootResolver = (origin: string) => ServiceRootLookup;
 export declare class BrowserBackendMissingError extends Error {
     constructor(cause: unknown);
 }
-/**
- * An `Evidence`-shaped record, as the collectors emit it.
- *
- * Typed structurally rather than imported wholesale because only four fields
- * are read: everything else the collectors attach travels to nobody here.
- */
-/**
- * Exported for `browser-request-outcome-mapping.test.ts`, which drives
- * `collect()` directly with synthetic evidence records — the real
- * evidence-to-`ObservedRequest` mapping, not the fake driver's fixtures. That
- * test is the regression test for B3: the fake driver lets a fixture declare
- * `outcome` directly, which let this mapping function ship never populating
- * the field at all while every test still passed.
- */
+/** `Evidence`-shaped record (typed structurally; only 4 fields are read). Exported for `browser-request-outcome-mapping.test.ts` — regression test for B3, where `outcome` shipped never populated despite passing tests. */
 export interface EmittedEvidence {
     readonly eventType: string;
     readonly payload: Record<string, unknown>;
@@ -102,18 +29,7 @@ export interface EmittedEvidence {
     readonly timestamp: string;
 }
 export declare function createPlaywrightBrowserDriver(options?: PlaywrightDriverOptions): Promise<BrowserDriver>;
-/**
- * Turn what the collectors emitted into the port's vocabulary.
- *
- * The request/response join is on `requestId`, because a `NETWORK_REQUEST`
- * carries the method, the URL and the call-site stack while only the matching
- * `NETWORK_RESPONSE` knows the status. A request with no response is kept with
- * `status: null` — "never answered" is a different fact from a 500, and the
- * port says so.
- *
- * Exported for `browser-request-outcome-mapping.test.ts` — see
- * `EmittedEvidence`'s doc comment for why.
- */
+/** Turns collector evidence into the port's vocabulary. Joins request/response on `requestId`, keeping `status: null` (not guessed) when unanswered. Exported for `browser-request-outcome-mapping.test.ts`. */
 export declare function collect(emitted: readonly EmittedEvidence[], actions: readonly ObservedAction[], unsettled: readonly UnsettledAction[]): BrowserObservation;
 export {};
 //# sourceMappingURL=playwright-driver.d.ts.map

package/dist/browser/playwright-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../../src/browser/playwright-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AA+B7E,OAAO,KAAK,EACV,aAAa,EAGb,kBAAkB,EAElB,cAAc,EAOd,eAAe,EAChB,MAAM,aAAa,CAAC;AAgDrB,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;IAChD,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,KAAK,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAAC;AAsDhE,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,KAAK,EAAE,OAAO;CAO3B;AAED;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAsB,6BAA6B,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBjH;AAgXD;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,kBAAkB,CA6FpB"}
+{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../../src/browser/playwright-driver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAgB7E,OAAO,KAAK,EACV,aAAa,EAGb,kBAAkB,EAElB,cAAc,EAQd,eAAe,EAChB,MAAM,aAAa,CAAC;AAuBrB,MAAM,WAAW,uBAAuB;IACtC,4KAA4K;IAC5K,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;IAChD,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8NAA8N;IAC9N,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,KAAK,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAAC;AAgDhE,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,KAAK,EAAE,OAAO;CAO3B;AAED,6NAA6N;AAC7N,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAsB,6BAA6B,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBjH;AAgWD,gNAAgN;AAChN,wBAAgB,OAAO,CACrB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,SAAS,EAAE,SAAS,eAAe,EAAE,GACpC,kBAAkB,CAgFpB"}

package/dist/browser/playwright-driver.js

@@ -1,45 +1,7 @@
 /**
- * The real `BrowserDriver`, over `@descryy/runtime-browser`.
- *
- * ## Why the import is still dynamic
- *
- * `@descryy/runtime-browser` is now a declared dependency of `@descryy/mcp`
- * (`mcp-browser-tools.md` §3.1's publish landed) — so the reason this module
- * used to give for a call-time specifier import, "not on the registry yet,"
- * no longer holds. It stays dynamic anyway, for a reason that outgrew that
- * one: `loadRuntimeModule` (`PlaywrightDriverOptions`, below) is a real
- * injection seam that `browser-action-settle.test.ts` uses today to drive
- * this file's settle logic against a fake module shaped like this one,
- * deterministically, with no real browser involved. A static
- * `import … from "@descryy/runtime-browser"` at the top of this file would
- * remove that seam along with the indirection, and nothing here needs
- * removing it — the package being on the registry made the *dependency*
- * declarable, not the import path mandatory. Absence (package missing,
- * import throws, or Chromium missing) is still a **named refusal with a
- * remedy**, exactly as before — see `provider.ts`.
- *
- * ## What this adds over the runtime package, and what it deliberately does not
- *
- * It adds exactly one thing the runtime has no API for: **element refs.** The
- * port's contract is that an action names an element the agent has seen, and
- * `BrowserActionCollector` acts on raw selectors. So this module enumerates
- * the page's interactive elements, holds a Playwright `ElementHandle` per ref,
- * and drops the whole map on navigation. Handles rather than injected `data-`
- * attributes on purpose: stamping the DOM would make the act of observing
- * change the page being observed, and a detached element then fails naturally
- * instead of resolving to whatever took its place.
- *
- * Everything else is composition. Launch, click, type, fill, console capture,
- * network capture, the `fetch()` initiator stack and its source-map rewrite
- * are all the runtime package's, called rather than reimplemented.
- *
- * ## Rule 1
- *
- * No language is named here. The stack-trace parser that turns a raw browser
- * stack into resolved frames is handed in by the caller as a module specifier
- * — the same mechanism `runtime-registry.ts` uses for runtime adapters, for
- * the same reason. Without one, requests are still observed and no caller
- * edge is written; the reply says so.
+ * The real `BrowserDriver`, over `@descryy/runtime-browser`. Import stays
+ * dynamic — `loadRuntimeModule` is a test injection seam (fake module, no
+ * browser needed). Adds only element refs over the runtime; stack-trace parsing is caller-supplied (rule 1: no language named here).
  */
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
@@ -53,40 +15,15 @@ import { BrowserSessionCrashedError, UnknownElementRefError } from "./driver.js"
 /** The module the driver composes. Named once, imported at call time. */
 const RUNTIME_BROWSER_MODULE = "@descryy/runtime-browser";
 const defaultRuntimeModuleLoader = () => import(__rewriteRelativeImportExtension(RUNTIME_BROWSER_MODULE));
-/**
- * How long an action waits for the page to *start* doing something.
- *
- * This is the one half of the wait that cannot be made conditional: there is
- * no signal for "this click will never issue a request", and proving that
- * negative is proving a negative. It is the old fixed 300ms, kept at its old
- * value so an action that causes nothing observes exactly what it observed
- * before — and it is now a *ceiling* rather than a duration, since any
- * request that starts inside it moves the wait onto the settle condition
- * below.
- */
+/** Ceiling on waiting for network activity to *start* — no signal proves "never will". Kept at the old fixed 300ms so a no-op action observes the same as before. */
 const ACTIVITY_GRACE_MS = 300;
-/**
- * After the last request lifecycle event, how long of nothing counts as
- * settled. Short on purpose: this fires only once activity has been seen, so
- * it measures a gap between requests, not a guess about whether any will come.
- */
+/** How long after the last request event counts as settled; fires only once activity is seen, so it measures a gap, not a guess about more coming. */
 const NETWORK_QUIET_MS = 120;
-/**
- * The ceiling on the whole wait. A page that never stops requesting must not
- * hold a tool call open forever; reaching this is recorded on the observation
- * and disclosed, never swallowed.
- */
+/** Ceiling on the whole wait; reaching it is recorded on the observation and disclosed, never swallowed. */
 const SETTLE_TIMEOUT_MS = 5_000;
 /** How often the settle loop re-checks. Small enough not to add latency of its own. */
 const POLL_INTERVAL_MS = 10;
-/**
- * Elements an agent can act on.
- *
- * Deliberately narrow. A snapshot of every node on the page would be
- * enormous, mostly unactionable, and would push the reply budget into
- * dropping the elements that matter. `[role]` is included so an application
- * that builds its own controls is not invisible.
- */
+/** Elements an agent can act on — deliberately narrow; a full-page snapshot would blow the reply budget. `[role]` included for custom controls. */
 const INTERACTIVE = "a, button, input, select, textarea, [role], [onclick], summary";
 export class BrowserBackendMissingError extends Error {
     constructor(cause) {
@@ -119,9 +56,11 @@ async function openSession(runtime, session, launchOptions, options) {
     const emitted = [];
     const actions = [];
     const unsettled = [];
-    // The request lifecycle, counted rather than slept through. `inFlight` is
-    // what "the page is still doing something" means, and `lastEventAt` is what
-    // separates a gap between two requests from the end of them.
+    // Never cleared, unlike `actions` — the session's whole-lifetime provenance record for
+    // `browser_save_scenario`, not per-drain evidence. Goes out of reach the moment this closure
+    // does (session closed/reaped) — there is no other path back to it.
+    const performed = [];
+    // inFlight/lastEventAt track request activity: counted, not slept through.
     let inFlight = 0;
     let lastEventAt = 0;
     session.page.on("request", () => {
@@ -160,12 +99,9 @@ async function openSession(runtime, session, launchOptions, options) {
         ...(options.service === undefined ? {} : { service: options.service }),
         ...(options.stackParser === undefined ? {} : { stackTraceParser: options.stackParser }),
     });
-    // Started before the first navigation, deliberately. The initiator capture
-    // wraps `fetch` via an init script, and Playwright's own contract is that
-    // an init script does not reach a document already loaded — so a collector
-    // started after navigating would observe a page it could never have
-    // instrumented, and would report an honest-looking empty stack for every
-    // request.
+    // Started before first navigation: Playwright's init-script contract means
+    // a collector started later misses instrumentation, reporting an
+    // honest-looking but empty stack.
     await actionCollector.start(context);
     await consoleCollector.start(context);
     await networkCollector.start(context);
@@ -183,26 +119,10 @@ async function openSession(runtime, session, launchOptions, options) {
     function recordAction(action, ref, mode) {
         actions.push({ action, ref, mode, url: session.page.url(), at: new Date().toISOString() });
     }
-    /**
-     * Waits for the network activity this action caused, and records it when it
-     * does not arrive.
-     *
-     * Two conditions, because there are two different questions:
-     *
-     * - **Did anything start?** There is no signal for "nothing will", so this
-     *   half is a bounded wait — `ACTIVITY_GRACE_MS`, the old fixed sleep's own
-     *   value, so an action that causes nothing observes exactly what it did
-     *   before. It is a ceiling now rather than a duration: the moment a
-     *   request starts, the wait moves onto the second condition.
-     * - **Has it finished?** Nothing in flight, and nothing new for
-     *   `NETWORK_QUIET_MS`. This is the half the fixed sleep got wrong: a
-     *   request that took longer than 300ms was not waited for and its
-     *   evidence was silently absent from the reply.
-     *
-     * Whichever condition is running, the whole wait is capped at
-     * `SETTLE_TIMEOUT_MS` — and reaching that cap is recorded on the
-     * observation, never swallowed.
-     */
+    function recordPerformed(action, target, url, text) {
+        performed.push({ action, target, url, text, at: new Date().toISOString() });
+    }
+    /** Waits for the action's network effect (started within `ACTIVITY_GRACE_MS`, then quiet for `NETWORK_QUIET_MS`), capped at `SETTLE_TIMEOUT_MS` — reaching the cap is recorded, never swallowed. */
     async function settleAfterAction(action, ref) {
         const startedAt = Date.now();
         lastEventAt = startedAt;
@@ -241,6 +161,7 @@ async function openSession(runtime, session, launchOptions, options) {
             await dropRefs();
             await actionCollector.navigate(url);
             recordAction("navigate", null, null);
+            recordPerformed("navigate", null, url, null);
         },
         async snapshot() {
             assertUsable();
@@ -266,25 +187,18 @@ async function openSession(runtime, session, launchOptions, options) {
                                         : tag === "input" && type === "checkbox"
                                             ? "checkbox"
                                             : tag);
-                    // A pragmatic accessible name, not a full AccName implementation:
-                    // the label a person would read, in the order a person would find
-                    // it. Named as an approximation rather than presented as the
-                    // accessibility tree's own answer.
+                    // A pragmatic accessible-name approximation, not a full AccName implementation.
                     const name = el.getAttribute("aria-label") ??
                         el.innerText?.trim() ??
                         el.textContent?.trim() ??
                         el.getAttribute("placeholder") ??
                         el.getAttribute("name") ??
                         "";
-                    // --- a real, re-resolvable selector, computed in this same
-                    // round trip so role/name/selector are all read off one live
-                    // DOM state. Everything below runs *inside the page* — it is
-                    // serialized by Playwright, so it must be entirely self
-                    // contained (no closures over the outer module).
-                    // An id that looks generated rather than authored: a hex run
-                    // (a hashed/uuid-derived id), React's `:r0:`-style useId
-                    // output, or blank. Rejected because "stable across a reload"
-                    // is exactly the property a generated id does not have.
+                    // Computed in this same round trip so role/name/selector read off
+                    // one live DOM state; runs inside the page (serialized by
+                    // Playwright), so it must not close over the outer module.
+                    // Rejects ids that look generated (hex run, React's `:r0:` useId
+                    // style, or blank) — "stable across reload" is what a generated id lacks.
                     const GENERATED_ID = /[0-9a-f]{8}|:r[0-9a-z]+:|^\s*$/i;
                     const FORM_CONTROLS = ["input", "select", "textarea", "button"];
                     function escapeAttrValue(value) {
@@ -295,9 +209,7 @@ async function openSession(runtime, session, launchOptions, options) {
                             return el.ownerDocument.querySelectorAll(candidate).length === 1;
                         }
                         catch {
-                            // An attribute value that produces an invalid selector (rare,
-                            // but not impossible) is treated as "no candidate" rather
-                            // than thrown — the caller falls through to the next tier.
+                            // Invalid selector (rare) is treated as "no candidate", not thrown.
                             return false;
                         }
                     }
@@ -344,12 +256,9 @@ async function openSession(runtime, session, launchOptions, options) {
                         return null;
                     }
                     function computeSelector(target) {
-                        // Priority order: first candidate that is unique in the whole
-                        // document wins. Each tier is checked for uniqueness on its
-                        // own — a data-testid shared by two elements is not
-                        // addressable either, and the next tier gets its turn rather
-                        // than giving up at the first attribute that happens to be
-                        // present.
+                        // Priority order: first unique candidate wins. Each tier is checked
+                        // independently — a shared data-testid isn't addressable either,
+                        // so the next tier gets a turn instead of stopping there.
                         const testId = target.getAttribute("data-testid");
                         if (testId !== null && testId.trim() !== "") {
                             const candidate = `[data-testid="${escapeAttrValue(testId)}"]`;
@@ -405,16 +314,16 @@ async function openSession(runtime, session, launchOptions, options) {
         },
         async click(ref) {
             assertUsable();
-            await resolve(ref).handle.click();
+            const { element, handle } = resolve(ref);
+            await handle.click();
             recordAction("click", ref, null);
-            // `requestfinished` fires after the page's own handler resolves, so a
-            // drain immediately after a click would miss the request the click
-            // caused — which is the request this whole feature exists to witness.
+            recordPerformed("click", { role: element.role, name: element.name, selector: element.selector }, null, null);
+            // requestfinished fires after the page's handler resolves; draining immediately would miss the very request being watched for.
             await settleAfterAction("click", ref);
         },
         async type(ref, text) {
             assertUsable();
-            const { handle } = resolve(ref);
+            const { element, handle } = resolve(ref);
             if (handle.pressSequentially !== undefined)
                 await handle.pressSequentially(text);
             else if (handle.type !== undefined)
@@ -422,12 +331,15 @@ async function openSession(runtime, session, launchOptions, options) {
             else
                 throw new Error("this Playwright build exposes no keystroke-level typing method");
             recordAction("type", ref, "append");
+            recordPerformed("type", { role: element.role, name: element.name, selector: element.selector }, null, text);
             await settleAfterAction("type", ref);
         },
         async fill(ref, text) {
             assertUsable();
-            await resolve(ref).handle.fill(text);
+            const { element, handle } = resolve(ref);
+            await handle.fill(text);
             recordAction("fill", ref, "replace");
+            recordPerformed("fill", { role: element.role, name: element.name, selector: element.selector }, null, text);
             await settleAfterAction("fill", ref);
         },
         async drainEvidence() {
@@ -437,13 +349,15 @@ async function openSession(runtime, session, launchOptions, options) {
             unsettled.length = 0;
             return observation;
         },
+        performedSteps() {
+            return [...performed];
+        },
         async close() {
             if (finalObservation !== null)
                 return finalObservation;
             closed = true;
-            // Collectors are stopped before the observation is taken: a stop
-            // flushes whatever the collector was still holding, and taking the
-            // observation first would drop exactly that.
+            // Stopped before observing: a stop flushes what each collector was
+            // still holding, which observing first would drop.
             await actionCollector.stop().catch(() => { });
             await consoleCollector.stop().catch(() => { });
             await networkCollector.stop().catch(() => { });
@@ -458,33 +372,16 @@ async function openSession(runtime, session, launchOptions, options) {
         },
     };
 }
-/**
- * Turn what the collectors emitted into the port's vocabulary.
- *
- * The request/response join is on `requestId`, because a `NETWORK_REQUEST`
- * carries the method, the URL and the call-site stack while only the matching
- * `NETWORK_RESPONSE` knows the status. A request with no response is kept with
- * `status: null` — "never answered" is a different fact from a 500, and the
- * port says so.
- *
- * Exported for `browser-request-outcome-mapping.test.ts` — see
- * `EmittedEvidence`'s doc comment for why.
- */
+/** Turns collector evidence into the port's vocabulary. Joins request/response on `requestId`, keeping `status: null` (not guessed) when unanswered. Exported for `browser-request-outcome-mapping.test.ts`. */
 export function collect(emitted, actions, unsettled) {
-    // Two joins, in priority order, because `requestId` is a *correlation
-    // header* and not a transport id: it exists only when the application
-    // itself propagates one. The fixture's own delete sets `x-request-id`, so
-    // an id-only join looked correct while silently reporting `status: null`
-    // for every request the page issued without one — which is most of them.
+    // Two joins, by priority: `requestId` is a correlation header the app must
+    // itself propagate, not a transport id — an id-only join silently reported
+    // `status: null` for every request without one, i.e. most of them.
     const statusByRequestId = new Map();
     const statusByUrl = new Map();
-    // B3: the same two joins, for `outcome`. `descry-runtime` stamps
-    // `outcome: "answered"` on every `NETWORK_RESPONSE` and `"unanswered"` on a
-    // paired `HTTP_ERROR` (a real `requestfailed`, a collector timeout, or a
-    // WebSocket `socketerror`); it never emits `"pending"` itself — a request
-    // still open when the drain runs simply has no terminal event at all,
-    // which is why `pairedRequestIds`/`pairedUrls` below track "a terminal
-    // event existed" separately from "and it named a recognisable outcome".
+    // B3: same two joins, for `outcome`. `descry-runtime` stamps "answered" or
+    // "unanswered", never "pending" itself — a still-open request at drain time
+    // has no terminal event, which pairedRequestIds/pairedUrls track separately.
     const outcomeByRequestId = new Map();
     const outcomeByUrl = new Map();
     const pairedRequestIds = new Set();
@@ -502,9 +399,7 @@ export function collect(emitted, actions, unsettled) {
             if (typeof status === "number") {
                 if (evidence.requestId !== null)
                     statusByRequestId.set(evidence.requestId, status);
-                // Last response wins: a page that requests the same URL twice reports
-                // the most recent outcome, which is the one a caller reading this
-                // reply is asking about.
+                // Last response wins: repeat requests report the most recent outcome.
                 if (typeof url === "string")
                     statusByUrl.set(url, status);
             }
@@ -528,12 +423,9 @@ export function collect(emitted, actions, unsettled) {
             const requestId = evidence.requestId;
             const pairedOutcome = (requestId === null ? undefined : outcomeByRequestId.get(requestId)) ?? outcomeByUrl.get(url);
             const wasPaired = (requestId !== null && pairedRequestIds.has(requestId)) || pairedUrls.has(url);
-            // A recognised outcome from the paired terminal event wins; no terminal
-            // event at all means the request was still in flight when the drain
-            // happened, so "pending"; a terminal event that exists but names no
-            // recognisable outcome (an older `descry-runtime` build) leaves the
-            // field undefined rather than guessing — `isFailedRequest`'s documented
-            // fallback is what handles that case, not this function.
+            // Paired outcome wins; no terminal event means still in-flight
+            // ("pending"); an unrecognised outcome (older runtime build) leaves the
+            // field undefined — `isFailedRequest`'s fallback handles that, not this.
             const outcome = pairedOutcome ?? (wasPaired ? undefined : "pending");
             requests.push({
                 method,
@@ -547,9 +439,7 @@ export function collect(emitted, actions, unsettled) {
             });
             continue;
         }
-        // An uncaught page error and a console error are both "the page reported
-        // something went wrong"; a caller triaging them does not need to know
-        // which listener fired.
+        // Uncaught page error and console error both mean "something went wrong"; callers don't need to know which listener fired.
         if (evidence.eventType === "EXCEPTION" || evidence.eventType === "CONSOLE_MESSAGE") {
             const level = evidence.payload["level"] ?? evidence.payload["type"];
             if (evidence.eventType === "CONSOLE_MESSAGE" && level !== "error")
@@ -565,30 +455,14 @@ export function collect(emitted, actions, unsettled) {
     }
     return { actions: [...actions], consoleErrors, requests, unsettled: [...unsettled] };
 }
-/**
- * Reads a terminal event's `outcome` off an untyped payload.
- *
- * Validated rather than cast, exactly like `scriptUrlOutcomesOf` below: this
- * crosses a package boundary — the field is `@descryy/runtime-browser`'s to
- * set, and this build does not depend on that package's types — so an
- * absent or unrecognised value must degrade to "no outcome reported", never
- * be cast through as one of the three known literals it might not actually
- * be.
- */
+/** Reads `outcome` off an untyped cross-package payload; validated not cast, since this build doesn't depend on `@descryy/runtime-browser`'s types — unrecognised values degrade to undefined, never a guessed literal. */
 function requestOutcomeOf(payload) {
     const raw = payload["outcome"];
     if (raw === "answered" || raw === "unanswered" || raw === "pending")
         return raw;
     return undefined;
 }
-/**
- * Reads the collector's `scriptUrlMapping` off an untyped payload.
- *
- * Validated rather than cast. This crosses a package boundary — the shape is
- * `@descryy/runtime-browser`'s and this build does not even depend on it — so
- * a malformed or absent field must degrade to "no mapping was reported",
- * never to a half-populated outcome that reads like a real one.
- */
+/** Reads `scriptUrlMapping` off an untyped cross-package payload; validated not cast, so a malformed/absent field degrades to "no mapping reported" rather than a half-populated result. */
 function scriptUrlOutcomesOf(payload) {
     const raw = payload["scriptUrlMapping"];
     if (!Array.isArray(raw))
@@ -611,19 +485,7 @@ function scriptUrlOutcomesOf(payload) {
     }
     return outcomes;
 }
-/**
- * A short, readable rendering of a parsed stack.
- *
- * `StackTrace` carries frames, not the original text — the raw string is
- * consumed by the parser and deliberately not kept, since a parsed frame with
- * a resolved on-disk path is strictly more useful than the `http://` line it
- * came from. So the port's `stackText` is rendered from the frames rather
- * than passed through, and it is for a human reading the reply: the R4 write
- * uses `stackTrace`, never this.
- *
- * The primary frame is marked, because it is the one a developer should be
- * sent to and it is not always the innermost.
- */
+/** Human-readable rendering of parsed stack frames, for the reply; the R4 write uses `stackTrace` itself, never this. Primary frame marked since it isn't always the innermost. */
 function renderStack(stack) {
     if (stack === null || stack.frames.length === 0)
         return null;