framewatch-mcp-server 0.1.0

package/dist/engine/interaction.js

@@ -0,0 +1,254 @@
+import { z } from "zod";
+import { NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, SWIPE_STEPS, SWIPE_STEP_DELAY_MS } from "../constants.js";
+/**
+ * Interaction executor.
+ *
+ * Turns one declarative interaction step (see CLAUDE.md "Interactions as JSON
+ * script") into real input on a Playwright page. Every step is validated
+ * before anything touches the page, and every Playwright failure is reduced to
+ * a single actionable line naming the step that failed — a recording is a bad
+ * place to surface a 30-line call log.
+ */
+/** Actions `framewatch_capture` can replay during a recording. */
+export const CAPTURE_ACTIONS = ["click", "tap", "type", "scroll", "swipe", "wait", "navigate"];
+/** Actions `framewatch_interact` can perform as a one-off. */
+export const INTERACT_ACTIONS = ["click", "tap", "type", "scroll", "swipe", "navigate", "select", "hover"];
+/** Steps that need a touch-capable browser context (`hasTouch: true`). */
+const TOUCH_ACTIONS = new Set(["tap", "swipe"]);
+/** True when any step needs a touch-enabled browser context. */
+export function needsTouch(interactions) {
+    return interactions.some((i) => TOUCH_ACTIONS.has(i.action));
+}
+/**
+ * Check that a step carries the fields its action needs. Returns a message
+ * naming what is missing, or null when the step is executable. Used both by
+ * the tools (at input-validation time, before a browser is even launched) and
+ * by `executeInteraction` itself.
+ */
+export function validateInteraction(interaction) {
+    const { action, selector, value, x, y, delta_x, delta_y } = interaction;
+    const hasPoint = typeof x === "number" && typeof y === "number";
+    const hasPartialPoint = typeof x === "number" || typeof y === "number";
+    switch (action) {
+        case "click":
+        case "tap":
+        case "hover":
+            if (selector)
+                return null;
+            if (hasPoint)
+                return null;
+            return hasPartialPoint
+                ? `${action} needs both \`x\` and \`y\` (or a \`selector\`)`
+                : `${action} needs a \`selector\`, or \`x\` and \`y\``;
+        case "type":
+            return typeof value === "string" ? null : "type needs a `value` (the text to type)";
+        case "select":
+            if (!selector)
+                return "select needs a `selector` naming the <select> element";
+            return typeof value === "string" ? null : "select needs a `value` (the option to choose)";
+        case "scroll":
+            return typeof delta_x === "number" || typeof delta_y === "number"
+                ? null
+                : "scroll needs `delta_y` (and/or `delta_x`) — the distance to scroll";
+        case "swipe":
+            if (!hasPoint)
+                return "swipe needs `x` and `y` — where the finger goes down";
+            return typeof delta_x === "number" || typeof delta_y === "number"
+                ? null
+                : "swipe needs `delta_x` and/or `delta_y` — how far the finger travels";
+        case "navigate":
+            return typeof value === "string" && value.length > 0 ? null : "navigate needs a `value` (the URL to go to)";
+        case "wait":
+            return null;
+        default:
+            return `unknown action "${String(action)}"`;
+    }
+}
+/** Longest `value` printed in a step description before it is elided. */
+const DESCRIBE_VALUE_MAX = 60;
+/**
+ * One-line, human-readable summary of a step, used in error messages and in
+ * the capture summary. Long values (a pasted token, a password) are elided
+ * rather than echoed in full.
+ */
+export function describeInteraction(interaction) {
+    const { action, selector, value, x, y, delta_x = 0, delta_y = 0, delay_ms } = interaction;
+    const target = selector ? ` "${selector}"` : typeof x === "number" && typeof y === "number" ? ` at ${x},${y}` : "";
+    switch (action) {
+        case "click":
+        case "tap":
+        case "hover":
+            return `${action}${target}`;
+        case "type":
+            return `type "${elide(value)}"${selector ? ` into "${selector}"` : ""}`;
+        case "select":
+            return `select "${elide(value)}"${selector ? ` in "${selector}"` : ""}`;
+        case "scroll":
+            return `scroll${selector ? ` "${selector}"` : ""} by ${delta_x},${delta_y}`;
+        case "swipe":
+            return `swipe${target} by ${delta_x},${delta_y}`;
+        case "navigate":
+            return `navigate to ${elide(value)}`;
+        case "wait":
+            return `wait ${delay_ms ?? 0}ms`;
+        default:
+            return String(action);
+    }
+}
+function elide(value) {
+    if (value === undefined)
+        return "";
+    return value.length > DESCRIBE_VALUE_MAX ? `${value.slice(0, DESCRIBE_VALUE_MAX)}…` : value;
+}
+/**
+ * Perform one interaction on `page`.
+ *
+ * Waits `delay_ms` first (that is what `delay_ms` means: "wait before this
+ * action"), so a `wait` step is simply a step with no action of its own.
+ * Throws a single-line Error naming the step on any failure; the page is never
+ * touched when the step is invalid.
+ */
+export async function executeInteraction(page, interaction, options = {}) {
+    const problem = validateInteraction(interaction);
+    if (problem)
+        throw new Error(problem);
+    const delay = interaction.delay_ms;
+    if (typeof delay === "number" && delay > 0)
+        await sleep(delay);
+    const timeout = options.timeout_ms ?? SELECTOR_TIMEOUT_MS;
+    try {
+        await perform(page, interaction, timeout);
+    }
+    catch (error) {
+        throw new Error(describeFailure(interaction, error), { cause: error });
+    }
+}
+async function perform(page, interaction, timeout) {
+    const { action, selector, value, x, y, delta_x = 0, delta_y = 0 } = interaction;
+    switch (action) {
+        case "click":
+            if (selector)
+                await page.locator(selector).first().click({ timeout });
+            else
+                await page.mouse.click(x, y);
+            return;
+        case "hover":
+            if (selector)
+                await page.locator(selector).first().hover({ timeout });
+            else
+                await page.mouse.move(x, y);
+            return;
+        case "tap":
+            if (selector)
+                await page.locator(selector).first().tap({ timeout });
+            else
+                await page.touchscreen.tap(x, y);
+            return;
+        case "type":
+            // `fill` clears the field first and dispatches a single input event, so
+            // replaying a script twice does not append to what is already there.
+            if (selector)
+                await page.locator(selector).first().fill(value, { timeout });
+            else
+                await page.keyboard.type(value);
+            return;
+        case "select":
+            await page.locator(selector).first().selectOption(value, { timeout });
+            return;
+        case "scroll":
+            // With a selector, put the pointer over that element first so the wheel
+            // scrolls it rather than the page behind it.
+            if (selector)
+                await page.locator(selector).first().hover({ timeout });
+            await page.mouse.wheel(delta_x, delta_y);
+            return;
+        case "swipe":
+            await swipe(page, x, y, delta_x, delta_y);
+            return;
+        case "navigate":
+            // Playwright only resolves relative URLs against a context `baseURL`;
+            // resolve against the current page instead, which is what a script
+            // author means by "navigate to /login".
+            await page.goto(resolveUrl(value, page.url()), { waitUntil: "commit", timeout: NAVIGATION_TIMEOUT_MS });
+            return;
+        case "wait":
+            return;
+    }
+}
+/**
+ * A real finger drag: touchStart, several touchMoves, touchEnd.
+ *
+ * Playwright's Touchscreen can only tap, so the drag goes through CDP (we are
+ * Chromium-only). Intermediate moves matter — a carousel or pull-to-refresh
+ * needs the travel and its velocity, not a teleport — and each one is spaced
+ * about a frame apart so the page's own velocity maths sees a plausible gesture.
+ */
+async function swipe(page, x, y, deltaX, deltaY) {
+    const cdp = await page.context().newCDPSession(page);
+    try {
+        await cdp.send("Input.dispatchTouchEvent", { type: "touchStart", touchPoints: [{ x, y }] });
+        for (let step = 1; step <= SWIPE_STEPS; step++) {
+            await sleep(SWIPE_STEP_DELAY_MS);
+            await cdp.send("Input.dispatchTouchEvent", {
+                // Interpolate from the origin (not from the previous point) so the last
+                // move lands exactly on x + deltaX, y + deltaY.
+                type: "touchMove",
+                touchPoints: [{ x: x + (deltaX * step) / SWIPE_STEPS, y: y + (deltaY * step) / SWIPE_STEPS }],
+            });
+        }
+        await cdp.send("Input.dispatchTouchEvent", { type: "touchEnd", touchPoints: [] });
+    }
+    finally {
+        await cdp.detach().catch(() => { });
+    }
+}
+function resolveUrl(value, base) {
+    try {
+        return new URL(value, base).href;
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Reduce a Playwright error to one actionable line naming the step. Touch
+ * failures get their own wording: the fix is a context option the caller
+ * controls, not anything about the page.
+ */
+function describeFailure(interaction, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split("\n")[0];
+    const step = describeInteraction(interaction);
+    if (/hasTouch|does not support tap/i.test(message)) {
+        return `${step} failed: this page is not touch-enabled. Touch is turned on automatically for tap/swipe steps — if you see this, the page was opened without it.`;
+    }
+    return `${step} failed: ${firstLine}`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * The shared zod fields every interaction step accepts. Both tools build their
+ * own object around these (the action enums differ, and `framewatch_capture`
+ * adds `delay_ms` where `framewatch_interact` adds `wait_ms`).
+ */
+export const interactionFieldShape = {
+    selector: z.string().optional().describe("CSS selector for click/tap/type/select/hover targets, or the scroll container"),
+    value: z.string().optional().describe("Text to type, option value to select, or URL to navigate to"),
+    x: z.number().optional().describe("X coordinate for click/tap/swipe (used when no selector is given)"),
+    y: z.number().optional().describe("Y coordinate for click/tap/swipe (used when no selector is given)"),
+    delta_x: z.number().optional().describe("Horizontal distance for scroll/swipe"),
+    delta_y: z.number().optional().describe("Vertical distance for scroll/swipe"),
+};
+/**
+ * zod `superRefine` hook that rejects a step missing the fields its action
+ * needs, so an unusable script is reported as invalid input instead of failing
+ * half way through a recording.
+ */
+export function refineInteraction(value, ctx) {
+    const problem = validateInteraction(value);
+    if (problem !== null) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem, path: ["action"] });
+    }
+}
+//# sourceMappingURL=interaction.js.map

package/dist/engine/interaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.js","sourceRoot":"","sources":["../../src/engine/interaction.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { Page } from \"playwright\";\nimport { NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, SWIPE_STEPS, SWIPE_STEP_DELAY_MS } from \"../constants.js\";\n\n/**\n * Interaction executor.\n *\n * Turns one declarative interaction step (see CLAUDE.md \"Interactions as JSON\n * script\") into real input on a Playwright page. Every step is validated\n * before anything touches the page, and every Playwright failure is reduced to\n * a single actionable line naming the step that failed — a recording is a bad\n * place to surface a 30-line call log.\n */\n\n/** Actions `framewatch_capture` can replay during a recording. */\nexport const CAPTURE_ACTIONS = [\"click\", \"tap\", \"type\", \"scroll\", \"swipe\", \"wait\", \"navigate\"] as const;\n\n/** Actions `framewatch_interact` can perform as a one-off. */\nexport const INTERACT_ACTIONS = [\"click\", \"tap\", \"type\", \"scroll\", \"swipe\", \"navigate\", \"select\", \"hover\"] as const;\n\nexport type InteractionAction = (typeof CAPTURE_ACTIONS)[number] | (typeof INTERACT_ACTIONS)[number];\n\nexport interface Interaction {\n  action: InteractionAction;\n  /** CSS selector for click/tap/type/select/hover, or the scroll container. */\n  selector?: string;\n  /** Text to type, option value to select, or URL to navigate to. */\n  value?: string;\n  x?: number;\n  y?: number;\n  delta_x?: number;\n  delta_y?: number;\n  /** Wait this long *before* performing the action. */\n  delay_ms?: number;\n}\n\nexport interface ExecuteOptions {\n  /** Timeout for selector-based actions. Default SELECTOR_TIMEOUT_MS. */\n  timeout_ms?: number;\n}\n\n/** Steps that need a touch-capable browser context (`hasTouch: true`). */\nconst TOUCH_ACTIONS = new Set<InteractionAction>([\"tap\", \"swipe\"]);\n\n/** True when any step needs a touch-enabled browser context. */\nexport function needsTouch(interactions: readonly Interaction[]): boolean {\n  return interactions.some((i) => TOUCH_ACTIONS.has(i.action));\n}\n\n/**\n * Check that a step carries the fields its action needs. Returns a message\n * naming what is missing, or null when the step is executable. Used both by\n * the tools (at input-validation time, before a browser is even launched) and\n * by `executeInteraction` itself.\n */\nexport function validateInteraction(interaction: Interaction): string | null {\n  const { action, selector, value, x, y, delta_x, delta_y } = interaction;\n  const hasPoint = typeof x === \"number\" && typeof y === \"number\";\n  const hasPartialPoint = typeof x === \"number\" || typeof y === \"number\";\n\n  switch (action) {\n    case \"click\":\n    case \"tap\":\n    case \"hover\":\n      if (selector) return null;\n      if (hasPoint) return null;\n      return hasPartialPoint\n        ? `${action} needs both \\`x\\` and \\`y\\` (or a \\`selector\\`)`\n        : `${action} needs a \\`selector\\`, or \\`x\\` and \\`y\\``;\n\n    case \"type\":\n      return typeof value === \"string\" ? null : \"type needs a `value` (the text to type)\";\n\n    case \"select\":\n      if (!selector) return \"select needs a `selector` naming the <select> element\";\n      return typeof value === \"string\" ? null : \"select needs a `value` (the option to choose)\";\n\n    case \"scroll\":\n      return typeof delta_x === \"number\" || typeof delta_y === \"number\"\n        ? null\n        : \"scroll needs `delta_y` (and/or `delta_x`) — the distance to scroll\";\n\n    case \"swipe\":\n      if (!hasPoint) return \"swipe needs `x` and `y` — where the finger goes down\";\n      return typeof delta_x === \"number\" || typeof delta_y === \"number\"\n        ? null\n        : \"swipe needs `delta_x` and/or `delta_y` — how far the finger travels\";\n\n    case \"navigate\":\n      return typeof value === \"string\" && value.length > 0 ? null : \"navigate needs a `value` (the URL to go to)\";\n\n    case \"wait\":\n      return null;\n\n    default:\n      return `unknown action \"${String(action)}\"`;\n  }\n}\n\n/** Longest `value` printed in a step description before it is elided. */\nconst DESCRIBE_VALUE_MAX = 60;\n\n/**\n * One-line, human-readable summary of a step, used in error messages and in\n * the capture summary. Long values (a pasted token, a password) are elided\n * rather than echoed in full.\n */\nexport function describeInteraction(interaction: Interaction): string {\n  const { action, selector, value, x, y, delta_x = 0, delta_y = 0, delay_ms } = interaction;\n  const target = selector ? ` \"${selector}\"` : typeof x === \"number\" && typeof y === \"number\" ? ` at ${x},${y}` : \"\";\n\n  switch (action) {\n    case \"click\":\n    case \"tap\":\n    case \"hover\":\n      return `${action}${target}`;\n    case \"type\":\n      return `type \"${elide(value)}\"${selector ? ` into \"${selector}\"` : \"\"}`;\n    case \"select\":\n      return `select \"${elide(value)}\"${selector ? ` in \"${selector}\"` : \"\"}`;\n    case \"scroll\":\n      return `scroll${selector ? ` \"${selector}\"` : \"\"} by ${delta_x},${delta_y}`;\n    case \"swipe\":\n      return `swipe${target} by ${delta_x},${delta_y}`;\n    case \"navigate\":\n      return `navigate to ${elide(value)}`;\n    case \"wait\":\n      return `wait ${delay_ms ?? 0}ms`;\n    default:\n      return String(action);\n  }\n}\n\nfunction elide(value: string | undefined): string {\n  if (value === undefined) return \"\";\n  return value.length > DESCRIBE_VALUE_MAX ? `${value.slice(0, DESCRIBE_VALUE_MAX)}…` : value;\n}\n\n/**\n * Perform one interaction on `page`.\n *\n * Waits `delay_ms` first (that is what `delay_ms` means: \"wait before this\n * action\"), so a `wait` step is simply a step with no action of its own.\n * Throws a single-line Error naming the step on any failure; the page is never\n * touched when the step is invalid.\n */\nexport async function executeInteraction(page: Page, interaction: Interaction, options: ExecuteOptions = {}): Promise<void> {\n  const problem = validateInteraction(interaction);\n  if (problem) throw new Error(problem);\n\n  const delay = interaction.delay_ms;\n  if (typeof delay === \"number\" && delay > 0) await sleep(delay);\n\n  const timeout = options.timeout_ms ?? SELECTOR_TIMEOUT_MS;\n  try {\n    await perform(page, interaction, timeout);\n  } catch (error) {\n    throw new Error(describeFailure(interaction, error), { cause: error });\n  }\n}\n\nasync function perform(page: Page, interaction: Interaction, timeout: number): Promise<void> {\n  const { action, selector, value, x, y, delta_x = 0, delta_y = 0 } = interaction;\n\n  switch (action) {\n    case \"click\":\n      if (selector) await page.locator(selector).first().click({ timeout });\n      else await page.mouse.click(x!, y!);\n      return;\n\n    case \"hover\":\n      if (selector) await page.locator(selector).first().hover({ timeout });\n      else await page.mouse.move(x!, y!);\n      return;\n\n    case \"tap\":\n      if (selector) await page.locator(selector).first().tap({ timeout });\n      else await page.touchscreen.tap(x!, y!);\n      return;\n\n    case \"type\":\n      // `fill` clears the field first and dispatches a single input event, so\n      // replaying a script twice does not append to what is already there.\n      if (selector) await page.locator(selector).first().fill(value!, { timeout });\n      else await page.keyboard.type(value!);\n      return;\n\n    case \"select\":\n      await page.locator(selector!).first().selectOption(value!, { timeout });\n      return;\n\n    case \"scroll\":\n      // With a selector, put the pointer over that element first so the wheel\n      // scrolls it rather than the page behind it.\n      if (selector) await page.locator(selector).first().hover({ timeout });\n      await page.mouse.wheel(delta_x, delta_y);\n      return;\n\n    case \"swipe\":\n      await swipe(page, x!, y!, delta_x, delta_y);\n      return;\n\n    case \"navigate\":\n      // Playwright only resolves relative URLs against a context `baseURL`;\n      // resolve against the current page instead, which is what a script\n      // author means by \"navigate to /login\".\n      await page.goto(resolveUrl(value!, page.url()), { waitUntil: \"commit\", timeout: NAVIGATION_TIMEOUT_MS });\n      return;\n\n    case \"wait\":\n      return;\n  }\n}\n\n/**\n * A real finger drag: touchStart, several touchMoves, touchEnd.\n *\n * Playwright's Touchscreen can only tap, so the drag goes through CDP (we are\n * Chromium-only). Intermediate moves matter — a carousel or pull-to-refresh\n * needs the travel and its velocity, not a teleport — and each one is spaced\n * about a frame apart so the page's own velocity maths sees a plausible gesture.\n */\nasync function swipe(page: Page, x: number, y: number, deltaX: number, deltaY: number): Promise<void> {\n  const cdp = await page.context().newCDPSession(page);\n  try {\n    await cdp.send(\"Input.dispatchTouchEvent\", { type: \"touchStart\", touchPoints: [{ x, y }] });\n    for (let step = 1; step <= SWIPE_STEPS; step++) {\n      await sleep(SWIPE_STEP_DELAY_MS);\n      await cdp.send(\"Input.dispatchTouchEvent\", {\n        // Interpolate from the origin (not from the previous point) so the last\n        // move lands exactly on x + deltaX, y + deltaY.\n        type: \"touchMove\",\n        touchPoints: [{ x: x + (deltaX * step) / SWIPE_STEPS, y: y + (deltaY * step) / SWIPE_STEPS }],\n      });\n    }\n    await cdp.send(\"Input.dispatchTouchEvent\", { type: \"touchEnd\", touchPoints: [] });\n  } finally {\n    await cdp.detach().catch(() => {});\n  }\n}\n\nfunction resolveUrl(value: string, base: string): string {\n  try {\n    return new URL(value, base).href;\n  } catch {\n    return value;\n  }\n}\n\n/**\n * Reduce a Playwright error to one actionable line naming the step. Touch\n * failures get their own wording: the fix is a context option the caller\n * controls, not anything about the page.\n */\nfunction describeFailure(interaction: Interaction, error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n  const step = describeInteraction(interaction);\n\n  if (/hasTouch|does not support tap/i.test(message)) {\n    return `${step} failed: this page is not touch-enabled. Touch is turned on automatically for tap/swipe steps — if you see this, the page was opened without it.`;\n  }\n  return `${step} failed: ${firstLine}`;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * The shared zod fields every interaction step accepts. Both tools build their\n * own object around these (the action enums differ, and `framewatch_capture`\n * adds `delay_ms` where `framewatch_interact` adds `wait_ms`).\n */\nexport const interactionFieldShape = {\n  selector: z.string().optional().describe(\"CSS selector for click/tap/type/select/hover targets, or the scroll container\"),\n  value: z.string().optional().describe(\"Text to type, option value to select, or URL to navigate to\"),\n  x: z.number().optional().describe(\"X coordinate for click/tap/swipe (used when no selector is given)\"),\n  y: z.number().optional().describe(\"Y coordinate for click/tap/swipe (used when no selector is given)\"),\n  delta_x: z.number().optional().describe(\"Horizontal distance for scroll/swipe\"),\n  delta_y: z.number().optional().describe(\"Vertical distance for scroll/swipe\"),\n};\n\n/**\n * zod `superRefine` hook that rejects a step missing the fields its action\n * needs, so an unusable script is reported as invalid input instead of failing\n * half way through a recording.\n */\nexport function refineInteraction(value: Interaction, ctx: z.RefinementCtx): void {\n  const problem = validateInteraction(value);\n  if (problem !== null) {\n    ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem, path: [\"action\"] });\n  }\n}\n"]}

package/dist/engine/layers/console.d.ts

@@ -0,0 +1,63 @@
+import type { Page } from "playwright";
+import type { ConsoleEntry } from "../../types.js";
+/**
+ * Console layer.
+ *
+ * Collects everything the page says while a capture runs: `console.*` calls,
+ * uncaught exceptions, unhandled promise rejections, and the tab crashing.
+ * Entries are stamped with absolute time and rebased onto the recording clock
+ * by `entries(origin)`, because collection starts *before* the navigation —
+ * an error thrown during page load is usually the most valuable thing here,
+ * and it happens before frame 0 exists.
+ *
+ * Nothing in this layer touches the page. It is all Playwright events, so a
+ * page that has frozen, navigated away or died still yields whatever it said
+ * before it went.
+ */
+export type ConsoleLevel = ConsoleEntry["level"];
+/** One collected message, stamped with absolute (epoch) time and already normalised. */
+export interface ConsoleRecord {
+    at: number;
+    level: ConsoleLevel;
+    text: string;
+}
+/**
+ * Map Chromium's console message types onto the four levels FrameWatch
+ * reports. `assert` is an error because that is what a failed assertion is;
+ * `count`/`timeEnd` are instrumentation, so they sit with `info`; everything
+ * else that is not clearly a warning or an error is a plain log.
+ */
+export declare function toConsoleLevel(type: string): ConsoleLevel;
+/**
+ * Reduce a message to one printable line. Console output is rendered one entry
+ * per line, so an embedded newline (a stack trace, a pretty-printed object)
+ * would otherwise be indistinguishable from the next entry.
+ */
+export declare function normaliseText(text: string, maxLength?: number): string;
+/**
+ * Describe an uncaught error the way a developer reads a stack trace: the
+ * message, then where it came from. Playwright hands `pageerror` a real Error
+ * whose `stack` is "Name: message\n    at fn (url:line:col)"; the top frame is
+ * the actionable part and the rest is noise in a one-line entry.
+ */
+export declare function describePageError(error: Error): string;
+export declare class ConsoleCollector {
+    #private;
+    constructor(page: Page, limit?: number);
+    /** Start listening. Idempotent. */
+    attach(): this;
+    /** Stop listening. Collected entries are kept. */
+    detach(): void;
+    /** Entries refused or evicted by the cap. */
+    get dropped(): number;
+    /** Forget everything collected so far. See `BoundedLog.clear`. */
+    clear(): void;
+    /**
+     * Collected entries, oldest first, with timestamps rebased onto the
+     * recording clock (`origin` is the recording's start in epoch ms). Entries
+     * from before the recording started keep their negative timestamp: they
+     * happened during page load, and pretending otherwise would put them out of
+     * order with the rest.
+     */
+    entries(origin: number): ConsoleEntry[];
+}

package/dist/engine/layers/console.js

@@ -0,0 +1,118 @@
+import { MAX_CONSOLE_ENTRIES, MAX_CONSOLE_TEXT_LENGTH } from "../../constants.js";
+import { BoundedLog } from "../../utils/bounded-log.js";
+/**
+ * Map Chromium's console message types onto the four levels FrameWatch
+ * reports. `assert` is an error because that is what a failed assertion is;
+ * `count`/`timeEnd` are instrumentation, so they sit with `info`; everything
+ * else that is not clearly a warning or an error is a plain log.
+ */
+export function toConsoleLevel(type) {
+    switch (type) {
+        case "error":
+        case "assert":
+            return "error";
+        case "warning":
+            return "warn";
+        case "info":
+        case "count":
+        case "timeEnd":
+            return "info";
+        default:
+            return "log";
+    }
+}
+/**
+ * Reduce a message to one printable line. Console output is rendered one entry
+ * per line, so an embedded newline (a stack trace, a pretty-printed object)
+ * would otherwise be indistinguishable from the next entry.
+ */
+export function normaliseText(text, maxLength = MAX_CONSOLE_TEXT_LENGTH) {
+    const flat = text.replace(/\s*\n\s*/g, " ↵ ").trim();
+    return flat.length > maxLength ? `${flat.slice(0, maxLength)}… (${flat.length} chars)` : flat;
+}
+/**
+ * Describe an uncaught error the way a developer reads a stack trace: the
+ * message, then where it came from. Playwright hands `pageerror` a real Error
+ * whose `stack` is "Name: message\n    at fn (url:line:col)"; the top frame is
+ * the actionable part and the rest is noise in a one-line entry.
+ */
+export function describePageError(error) {
+    const head = error.message ? `${error.name}: ${error.message}` : error.name || "Error";
+    const frame = (error.stack ?? "")
+        .split("\n")
+        .slice(1)
+        .map((line) => line.trim())
+        .find((line) => line.startsWith("at "));
+    return frame ? `${head} (${frame})` : head;
+}
+export class ConsoleCollector {
+    #page;
+    #log;
+    #attached = false;
+    #onConsole = (message) => {
+        this.#record(toConsoleLevel(message.type()), message.text());
+    };
+    #onPageError = (error) => {
+        this.#record("error", describePageError(error));
+    };
+    #onCrash = () => {
+        // Not a console message, but it is the explanation for every frame after
+        // it, and there is nowhere better for the page to tell us it has died.
+        this.#record("error", "Page crashed (the browser tab stopped responding)");
+    };
+    constructor(page, limit = MAX_CONSOLE_ENTRIES) {
+        this.#page = page;
+        this.#log = new BoundedLog(limit, (entry) => entry.level === "error");
+    }
+    /** Start listening. Idempotent. */
+    attach() {
+        if (this.#attached)
+            return this;
+        this.#attached = true;
+        this.#page.on("console", this.#onConsole);
+        this.#page.on("pageerror", this.#onPageError);
+        this.#page.on("crash", this.#onCrash);
+        return this;
+    }
+    /** Stop listening. Collected entries are kept. */
+    detach() {
+        if (!this.#attached)
+            return;
+        this.#attached = false;
+        this.#page.off("console", this.#onConsole);
+        this.#page.off("pageerror", this.#onPageError);
+        this.#page.off("crash", this.#onCrash);
+    }
+    /** Entries refused or evicted by the cap. */
+    get dropped() {
+        return this.#log.dropped;
+    }
+    /** Forget everything collected so far. See `BoundedLog.clear`. */
+    clear() {
+        this.#log.clear();
+    }
+    /**
+     * Collected entries, oldest first, with timestamps rebased onto the
+     * recording clock (`origin` is the recording's start in epoch ms). Entries
+     * from before the recording started keep their negative timestamp: they
+     * happened during page load, and pretending otherwise would put them out of
+     * order with the rest.
+     */
+    entries(origin) {
+        return this.#log.items.map((record) => ({
+            level: record.level,
+            text: record.text,
+            timestamp_ms: Math.round(record.at - origin),
+        }));
+    }
+    /**
+     * Text is normalised here rather than on the way out: `console.log` of a
+     * megabyte-long string is one call, and holding a hundred of those until the
+     * recording ends is a real amount of memory to keep for text that will be
+     * elided anyway.
+     */
+    #record(level, text) {
+        this.#log.add({ at: Date.now(), level, text: normaliseText(text) });
+    }
+}
+//# sourceMappingURL=console.js.map

package/dist/engine/layers/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../../src/engine/layers/console.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ConsoleMessage, Page } from \"playwright\";\nimport { MAX_CONSOLE_ENTRIES, MAX_CONSOLE_TEXT_LENGTH } from \"../../constants.js\";\nimport type { ConsoleEntry } from \"../../types.js\";\nimport { BoundedLog } from \"../../utils/bounded-log.js\";\n\n/**\n * Console layer.\n *\n * Collects everything the page says while a capture runs: `console.*` calls,\n * uncaught exceptions, unhandled promise rejections, and the tab crashing.\n * Entries are stamped with absolute time and rebased onto the recording clock\n * by `entries(origin)`, because collection starts *before* the navigation —\n * an error thrown during page load is usually the most valuable thing here,\n * and it happens before frame 0 exists.\n *\n * Nothing in this layer touches the page. It is all Playwright events, so a\n * page that has frozen, navigated away or died still yields whatever it said\n * before it went.\n */\n\nexport type ConsoleLevel = ConsoleEntry[\"level\"];\n\n/** One collected message, stamped with absolute (epoch) time and already normalised. */\nexport interface ConsoleRecord {\n  at: number;\n  level: ConsoleLevel;\n  text: string;\n}\n\n/**\n * Map Chromium's console message types onto the four levels FrameWatch\n * reports. `assert` is an error because that is what a failed assertion is;\n * `count`/`timeEnd` are instrumentation, so they sit with `info`; everything\n * else that is not clearly a warning or an error is a plain log.\n */\nexport function toConsoleLevel(type: string): ConsoleLevel {\n  switch (type) {\n    case \"error\":\n    case \"assert\":\n      return \"error\";\n    case \"warning\":\n      return \"warn\";\n    case \"info\":\n    case \"count\":\n    case \"timeEnd\":\n      return \"info\";\n    default:\n      return \"log\";\n  }\n}\n\n/**\n * Reduce a message to one printable line. Console output is rendered one entry\n * per line, so an embedded newline (a stack trace, a pretty-printed object)\n * would otherwise be indistinguishable from the next entry.\n */\nexport function normaliseText(text: string, maxLength: number = MAX_CONSOLE_TEXT_LENGTH): string {\n  const flat = text.replace(/\\s*\\n\\s*/g, \" ↵ \").trim();\n  return flat.length > maxLength ? `${flat.slice(0, maxLength)}… (${flat.length} chars)` : flat;\n}\n\n/**\n * Describe an uncaught error the way a developer reads a stack trace: the\n * message, then where it came from. Playwright hands `pageerror` a real Error\n * whose `stack` is \"Name: message\\n    at fn (url:line:col)\"; the top frame is\n * the actionable part and the rest is noise in a one-line entry.\n */\nexport function describePageError(error: Error): string {\n  const head = error.message ? `${error.name}: ${error.message}` : error.name || \"Error\";\n  const frame = (error.stack ?? \"\")\n    .split(\"\\n\")\n    .slice(1)\n    .map((line) => line.trim())\n    .find((line) => line.startsWith(\"at \"));\n  return frame ? `${head} (${frame})` : head;\n}\n\nexport class ConsoleCollector {\n  readonly #page: Page;\n  readonly #log: BoundedLog<ConsoleRecord>;\n  #attached = false;\n\n  readonly #onConsole = (message: ConsoleMessage): void => {\n    this.#record(toConsoleLevel(message.type()), message.text());\n  };\n\n  readonly #onPageError = (error: Error): void => {\n    this.#record(\"error\", describePageError(error));\n  };\n\n  readonly #onCrash = (): void => {\n    // Not a console message, but it is the explanation for every frame after\n    // it, and there is nowhere better for the page to tell us it has died.\n    this.#record(\"error\", \"Page crashed (the browser tab stopped responding)\");\n  };\n\n  constructor(page: Page, limit: number = MAX_CONSOLE_ENTRIES) {\n    this.#page = page;\n    this.#log = new BoundedLog<ConsoleRecord>(limit, (entry) => entry.level === \"error\");\n  }\n\n  /** Start listening. Idempotent. */\n  attach(): this {\n    if (this.#attached) return this;\n    this.#attached = true;\n    this.#page.on(\"console\", this.#onConsole);\n    this.#page.on(\"pageerror\", this.#onPageError);\n    this.#page.on(\"crash\", this.#onCrash);\n    return this;\n  }\n\n  /** Stop listening. Collected entries are kept. */\n  detach(): void {\n    if (!this.#attached) return;\n    this.#attached = false;\n    this.#page.off(\"console\", this.#onConsole);\n    this.#page.off(\"pageerror\", this.#onPageError);\n    this.#page.off(\"crash\", this.#onCrash);\n  }\n\n  /** Entries refused or evicted by the cap. */\n  get dropped(): number {\n    return this.#log.dropped;\n  }\n\n  /** Forget everything collected so far. See `BoundedLog.clear`. */\n  clear(): void {\n    this.#log.clear();\n  }\n\n  /**\n   * Collected entries, oldest first, with timestamps rebased onto the\n   * recording clock (`origin` is the recording's start in epoch ms). Entries\n   * from before the recording started keep their negative timestamp: they\n   * happened during page load, and pretending otherwise would put them out of\n   * order with the rest.\n   */\n  entries(origin: number): ConsoleEntry[] {\n    return this.#log.items.map((record) => ({\n      level: record.level,\n      text: record.text,\n      timestamp_ms: Math.round(record.at - origin),\n    }));\n  }\n\n  /**\n   * Text is normalised here rather than on the way out: `console.log` of a\n   * megabyte-long string is one call, and holding a hundred of those until the\n   * recording ends is a real amount of memory to keep for text that will be\n   * elided anyway.\n   */\n  #record(level: ConsoleLevel, text: string): void {\n    this.#log.add({ at: Date.now(), level, text: normaliseText(text) });\n  }\n}\n"]}

package/dist/engine/layers/dom.d.ts

@@ -0,0 +1,53 @@
+import type { Page } from "playwright";
+import { type InstallOptions } from "./probe.js";
+/** What happened to a node. */
+export type DomOp = "+" | "-" | "~" | "t";
+/** One mutation, as pushed by the page. Timestamps are absolute (epoch ms). */
+export interface RawDomRecord {
+    /** Absolute time the mutation was observed. */
+    t: number;
+    op: DomOp;
+    /** Short descriptor of the node — `div#id`, `span.class`, `p`. */
+    target: string;
+    /** Descriptor of the parent, for adds and removes. */
+    parent?: string;
+    /** Attribute name, for `~`. */
+    detail?: string;
+}
+/** One mutation, rebased onto the recording clock. */
+export interface DomRecord {
+    timestamp_ms: number;
+    op: DomOp;
+    target: string;
+    parent?: string;
+    detail?: string;
+}
+export declare class DomCollector {
+    #private;
+    constructor(page: Page, limit?: number);
+    /**
+     * Install the probe. Call before the page navigates, or pass
+     * `{ runNow: true }` to also watch the document that is already loaded.
+     */
+    attach(options?: InstallOptions): Promise<this>;
+    /** Mutations the cap refused. */
+    get dropped(): number;
+    /** Forget everything collected so far. See `BoundedLog.clear`. */
+    clear(): void;
+    /**
+     * Collected mutations in time order, rebased onto the recording clock
+     * (`origin` is the recording's start in epoch ms). Mutations from before the
+     * recording started keep their negative timestamp — they are the page
+     * building itself, and belong on the first card.
+     */
+    records(origin: number): DomRecord[];
+}
+/**
+ * Turn one card's mutations into a few readable lines.
+ *
+ * Identical mutations are collapsed with a count, in first-seen order: an
+ * animation driven by an inline style produces one `~ #logo [style] ×24` line
+ * rather than 24 identical ones, and the order still tells the story of what
+ * happened first. Returns undefined when there is nothing to say.
+ */
+export declare function renderDomChanges(records: DomRecord[], maxLines?: number): string | undefined;