framewatch-mcp-server 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../src/engine/layers/probe.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAkCrG,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,OAAO;QACP,QAAQ,EAAE,cAAc;QACxB,SAAS,EAAE,eAAe;QAC1B,WAAW,EAAE,8BAA8B;KAC5C,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAU,EACV,MAAmB,EACnB,MAAqC,EACrC,OAA+B,EAC/B,UAA0B,EAAE;IAE5B,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,KAAc,EAAE,EAAE;QACnE,IAAI,CAAC;YACH,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,KAAY,CAAC,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACP,wDAAwD;QAC1D,CAAC;IACH,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEzC,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,0CAA0C;QAC1C,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACtD,CAAC;AACH,CAAC","sourcesContent":["import type { Page } from \"playwright\";\nimport { LAYER_FLUSH_MS, MAX_LAYER_BATCH, MAX_LAYER_RECORDS_PER_DOCUMENT } from \"../../constants.js\";\n\n/**\n * In-page probe plumbing, shared by the DOM and performance layers.\n *\n * Console and network are Playwright events, but \"what changed in the DOM\" and\n * \"when did the browser paint\" only exist inside the page, so those two layers\n * inject an observer and push what it sees back to Node.\n *\n * The push is an `exposeBinding` function rather than one `page.evaluate` at\n * the end of the recording, for one reason: a navigation destroys the document\n * and everything buffered in it. Bindings and init scripts are reinstalled on\n * every new document, so a capture that navigates keeps the records from both\n * pages — and a capture whose page freezes or dies keeps whatever it pushed\n * before it went.\n *\n * Each probe inlines its own batching queue (page scripts cannot import, and\n * `eval`ing a shared one would break on any page with a strict CSP). Records\n * are stamped when they are *made*, never when their batch is flushed, so\n * batching cannot move a record onto the wrong diff card.\n */\n\n/** Config handed to the page-side script. Must stay JSON-serialisable. */\nexport interface ProbeConfig {\n  /** Name of the `window` function the page pushes batches through. */\n  binding: string;\n  /** How long to coalesce records before pushing a batch. */\n  flush_ms: number;\n  /** Records one batch may carry. */\n  max_batch: number;\n  /** Records the probe may push over the lifetime of one document. */\n  max_records: number;\n}\n\nexport function probeConfig(binding: string): ProbeConfig {\n  return {\n    binding,\n    flush_ms: LAYER_FLUSH_MS,\n    max_batch: MAX_LAYER_BATCH,\n    max_records: MAX_LAYER_RECORDS_PER_DOCUMENT,\n  };\n}\n\n/**\n * Expose `config.binding` on the page and arrange for `script` to run at the\n * start of every document (including after a navigation).\n *\n * `onBatch` must never throw: it runs as the resolution of a promise the page\n * is holding, so a throw here surfaces inside the page under test as an\n * unhandled rejection — which the console layer would then dutifully report as\n * a bug in the user's app. It is wrapped here so callers cannot get that wrong.\n */\nexport async function installProbe<T>(\n  page: Page,\n  config: ProbeConfig,\n  script: (config: ProbeConfig) => void,\n  onBatch: (records: T[]) => void,\n  options: InstallOptions = {},\n): Promise<void> {\n  await page.exposeBinding(config.binding, (_source, batch: unknown) => {\n    try {\n      if (Array.isArray(batch)) onBatch(batch as T[]);\n    } catch {\n      // A collector must never break the page it is watching.\n    }\n  });\n  await page.addInitScript(script, config);\n\n  if (options.runNow === true) {\n    // Init scripts only reach *new* documents, so a probe installed on a page\n    // that is already loaded would watch nothing until the next navigation.\n    // Running it once by hand covers the document that is already there; the\n    // probes guard against being installed twice, so the init script running\n    // later on the same document is harmless.\n    await page.evaluate(script, config).catch(() => {});\n  }\n}\n\nexport interface InstallOptions {\n  /**\n   * Also run the probe against the document the page already has. Needed for\n   * `framewatch_interact`, which acts on a page that is open before the layer\n   * is asked for; captures attach before navigating and do not need it.\n   */\n  runNow?: boolean;\n}\n"]}

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

@@ -0,0 +1,46 @@
+import type { Page } from "playwright";
+import type { CapturedContext, LayerFlags } from "./index.js";
+/**
+ * Context layers for a page that outlives one tool call.
+ *
+ * `framewatch_capture` gets a fresh page every time, so it can attach layers,
+ * record, and throw the whole thing away. `framewatch_interact` cannot: its
+ * page stays open between calls — that is what makes click → look → type →
+ * look possible — and two of the four layers cannot be attached twice to the
+ * same page at all. `page.exposeBinding` refuses a name that is already taken,
+ * and an init script, once added, can never be removed.
+ *
+ * So the layers live as long as the page does, and each call *drains* them
+ * instead of attaching its own: `ensure` installs whatever this call asked for
+ * and is not there yet, `clear` empties the collectors so the call reports
+ * only what its own action caused, and `collect` reads them afterwards.
+ *
+ * A layer that was installed for an earlier call keeps collecting even when
+ * this call did not ask for it — nothing can uninstall it — but it is cleared
+ * with the rest and simply not reported. The cost is a MutationObserver that
+ * nobody reads; the alternative is a page that has to be thrown away and
+ * rebuilt whenever the flags change, which would defeat the tool.
+ */
+export declare class SessionLayers {
+    #private;
+    constructor(page: Page);
+    /**
+     * Install every requested layer that is not there yet.
+     *
+     * Failures become notes rather than exceptions, for the same reason as in
+     * `attachLayers`: the interaction is the point and the context is the bonus,
+     * so a layer that will not install must not take the tool call down with it.
+     */
+    ensure(flags: LayerFlags): Promise<void>;
+    /** Empty every installed collector, so the next window starts from nothing. */
+    clear(): void;
+    /**
+     * What the requested layers saw, rebased onto `origin` (epoch ms).
+     *
+     * Only the layers this call asked for are reported, whatever else happens to
+     * be installed. Purely synchronous and never touches the page, so it still
+     * works after the page has navigated, frozen or died.
+     */
+    collect(origin: number, flags: LayerFlags): CapturedContext;
+}
+export declare function layersFor(page: Page): SessionLayers;

package/dist/engine/layers/session.js

@@ -0,0 +1,131 @@
+import { ConsoleCollector } from "./console.js";
+import { DomCollector } from "./dom.js";
+import { NetworkCollector } from "./network.js";
+import { PerformanceCollector } from "./performance.js";
+/**
+ * Context layers for a page that outlives one tool call.
+ *
+ * `framewatch_capture` gets a fresh page every time, so it can attach layers,
+ * record, and throw the whole thing away. `framewatch_interact` cannot: its
+ * page stays open between calls — that is what makes click → look → type →
+ * look possible — and two of the four layers cannot be attached twice to the
+ * same page at all. `page.exposeBinding` refuses a name that is already taken,
+ * and an init script, once added, can never be removed.
+ *
+ * So the layers live as long as the page does, and each call *drains* them
+ * instead of attaching its own: `ensure` installs whatever this call asked for
+ * and is not there yet, `clear` empties the collectors so the call reports
+ * only what its own action caused, and `collect` reads them afterwards.
+ *
+ * A layer that was installed for an earlier call keeps collecting even when
+ * this call did not ask for it — nothing can uninstall it — but it is cleared
+ * with the rest and simply not reported. The cost is a MutationObserver that
+ * nobody reads; the alternative is a page that has to be thrown away and
+ * rebuilt whenever the flags change, which would defeat the tool.
+ */
+export class SessionLayers {
+    #page;
+    #console = null;
+    #network = null;
+    #dom = null;
+    #performance = null;
+    /** Layers that could not be installed on this page, one note each. */
+    #notes = [];
+    constructor(page) {
+        this.#page = page;
+    }
+    /**
+     * Install every requested layer that is not there yet.
+     *
+     * Failures become notes rather than exceptions, for the same reason as in
+     * `attachLayers`: the interaction is the point and the context is the bonus,
+     * so a layer that will not install must not take the tool call down with it.
+     */
+    async ensure(flags) {
+        this.#notes = [];
+        if (flags.console && !this.#console) {
+            this.#console = new ConsoleCollector(this.#page).attach();
+        }
+        if (flags.network && !this.#network) {
+            this.#network = new NetworkCollector(this.#page).attach();
+        }
+        // The injected probes go in with `runNow`: the page is already loaded by
+        // the time this runs, and an init script alone would not reach it until
+        // the next navigation.
+        if (flags.dom && !this.#dom) {
+            this.#dom = await this.#install(new DomCollector(this.#page), "DOM");
+        }
+        if (flags.performance && !this.#performance) {
+            this.#performance = await this.#install(new PerformanceCollector(this.#page), "performance");
+        }
+    }
+    /** Empty every installed collector, so the next window starts from nothing. */
+    clear() {
+        this.#console?.clear();
+        this.#network?.clear();
+        this.#dom?.clear();
+        this.#performance?.clear();
+    }
+    /**
+     * What the requested layers saw, rebased onto `origin` (epoch ms).
+     *
+     * Only the layers this call asked for are reported, whatever else happens to
+     * be installed. Purely synchronous and never touches the page, so it still
+     * works after the page has navigated, frozen or died.
+     */
+    collect(origin, flags) {
+        const context = { notes: [...this.#notes] };
+        if (flags.console && this.#console) {
+            context.console = this.#console.entries(origin);
+            if (this.#console.dropped > 0) {
+                context.notes.push(`Console output was capped — ${this.#console.dropped} entries dropped (errors kept first).`);
+            }
+        }
+        if (flags.network && this.#network) {
+            context.network = this.#network.events(origin);
+            if (this.#network.dropped > 0) {
+                context.notes.push(`Network log was capped — ${this.#network.dropped} events dropped (failures kept first).`);
+            }
+        }
+        if (flags.dom && this.#dom) {
+            context.dom = this.#dom.records(origin);
+            if (this.#dom.dropped > 0) {
+                context.notes.push(`DOM log was capped — ${this.#dom.dropped} mutations dropped.`);
+            }
+        }
+        if (flags.performance && this.#performance) {
+            context.performance = this.#performance.samples(origin);
+            if (this.#performance.dropped > 0) {
+                context.notes.push(`Performance log was capped — ${this.#performance.dropped} entries dropped.`);
+            }
+        }
+        return context;
+    }
+    async #install(collector, name) {
+        try {
+            return await collector.attach({ runNow: true });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
+            this.#notes.push(`The ${name} layer could not be installed: ${reason}`);
+            return null;
+        }
+    }
+}
+/**
+ * The layers belonging to `page`, created on first use.
+ *
+ * Keyed weakly by page, so a session that is reopened (a viewport change that
+ * needed touch, a crashed tab) starts with fresh collectors and the old ones
+ * are collected along with the page they watched.
+ */
+const byPage = new WeakMap();
+export function layersFor(page) {
+    const existing = byPage.get(page);
+    if (existing)
+        return existing;
+    const created = new SessionLayers(page);
+    byPage.set(page, created);
+    return created;
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/engine/layers/session.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from \"playwright\";\nimport { ConsoleCollector } from \"./console.js\";\nimport { DomCollector } from \"./dom.js\";\nimport { NetworkCollector } from \"./network.js\";\nimport { PerformanceCollector } from \"./performance.js\";\nimport type { CapturedContext, LayerFlags } from \"./index.js\";\n\n/**\n * Context layers for a page that outlives one tool call.\n *\n * `framewatch_capture` gets a fresh page every time, so it can attach layers,\n * record, and throw the whole thing away. `framewatch_interact` cannot: its\n * page stays open between calls — that is what makes click → look → type →\n * look possible — and two of the four layers cannot be attached twice to the\n * same page at all. `page.exposeBinding` refuses a name that is already taken,\n * and an init script, once added, can never be removed.\n *\n * So the layers live as long as the page does, and each call *drains* them\n * instead of attaching its own: `ensure` installs whatever this call asked for\n * and is not there yet, `clear` empties the collectors so the call reports\n * only what its own action caused, and `collect` reads them afterwards.\n *\n * A layer that was installed for an earlier call keeps collecting even when\n * this call did not ask for it — nothing can uninstall it — but it is cleared\n * with the rest and simply not reported. The cost is a MutationObserver that\n * nobody reads; the alternative is a page that has to be thrown away and\n * rebuilt whenever the flags change, which would defeat the tool.\n */\nexport class SessionLayers {\n  readonly #page: Page;\n  #console: ConsoleCollector | null = null;\n  #network: NetworkCollector | null = null;\n  #dom: DomCollector | null = null;\n  #performance: PerformanceCollector | null = null;\n  /** Layers that could not be installed on this page, one note each. */\n  #notes: string[] = [];\n\n  constructor(page: Page) {\n    this.#page = page;\n  }\n\n  /**\n   * Install every requested layer that is not there yet.\n   *\n   * Failures become notes rather than exceptions, for the same reason as in\n   * `attachLayers`: the interaction is the point and the context is the bonus,\n   * so a layer that will not install must not take the tool call down with it.\n   */\n  async ensure(flags: LayerFlags): Promise<void> {\n    this.#notes = [];\n\n    if (flags.console && !this.#console) {\n      this.#console = new ConsoleCollector(this.#page).attach();\n    }\n    if (flags.network && !this.#network) {\n      this.#network = new NetworkCollector(this.#page).attach();\n    }\n    // The injected probes go in with `runNow`: the page is already loaded by\n    // the time this runs, and an init script alone would not reach it until\n    // the next navigation.\n    if (flags.dom && !this.#dom) {\n      this.#dom = await this.#install(new DomCollector(this.#page), \"DOM\");\n    }\n    if (flags.performance && !this.#performance) {\n      this.#performance = await this.#install(new PerformanceCollector(this.#page), \"performance\");\n    }\n  }\n\n  /** Empty every installed collector, so the next window starts from nothing. */\n  clear(): void {\n    this.#console?.clear();\n    this.#network?.clear();\n    this.#dom?.clear();\n    this.#performance?.clear();\n  }\n\n  /**\n   * What the requested layers saw, rebased onto `origin` (epoch ms).\n   *\n   * Only the layers this call asked for are reported, whatever else happens to\n   * be installed. Purely synchronous and never touches the page, so it still\n   * works after the page has navigated, frozen or died.\n   */\n  collect(origin: number, flags: LayerFlags): CapturedContext {\n    const context: CapturedContext = { notes: [...this.#notes] };\n\n    if (flags.console && this.#console) {\n      context.console = this.#console.entries(origin);\n      if (this.#console.dropped > 0) {\n        context.notes.push(`Console output was capped — ${this.#console.dropped} entries dropped (errors kept first).`);\n      }\n    }\n    if (flags.network && this.#network) {\n      context.network = this.#network.events(origin);\n      if (this.#network.dropped > 0) {\n        context.notes.push(`Network log was capped — ${this.#network.dropped} events dropped (failures kept first).`);\n      }\n    }\n    if (flags.dom && this.#dom) {\n      context.dom = this.#dom.records(origin);\n      if (this.#dom.dropped > 0) {\n        context.notes.push(`DOM log was capped — ${this.#dom.dropped} mutations dropped.`);\n      }\n    }\n    if (flags.performance && this.#performance) {\n      context.performance = this.#performance.samples(origin);\n      if (this.#performance.dropped > 0) {\n        context.notes.push(`Performance log was capped — ${this.#performance.dropped} entries dropped.`);\n      }\n    }\n\n    return context;\n  }\n\n  async #install<T extends { attach(options: { runNow: boolean }): Promise<T> }>(\n    collector: T,\n    name: string,\n  ): Promise<T | null> {\n    try {\n      return await collector.attach({ runNow: true });\n    } catch (error) {\n      const reason = error instanceof Error ? error.message.split(\"\\n\")[0] : String(error);\n      this.#notes.push(`The ${name} layer could not be installed: ${reason}`);\n      return null;\n    }\n  }\n}\n\n/**\n * The layers belonging to `page`, created on first use.\n *\n * Keyed weakly by page, so a session that is reopened (a viewport change that\n * needed touch, a crashed tab) starts with fresh collectors and the old ones\n * are collected along with the page they watched.\n */\nconst byPage = new WeakMap<Page, SessionLayers>();\n\nexport function layersFor(page: Page): SessionLayers {\n  const existing = byPage.get(page);\n  if (existing) return existing;\n  const created = new SessionLayers(page);\n  byPage.set(page, created);\n  return created;\n}\n"]}

package/dist/engine/recorder.d.ts

@@ -0,0 +1,61 @@
+import type { Page } from "playwright";
+import type { FrameTrigger, RawFrame } from "../types.js";
+/**
+ * Frame recorder.
+ *
+ * Captures raw PNG screenshots of a page at a fixed interval using a
+ * self-scheduling `setTimeout` chain aligned to `start + n * interval`, so two
+ * screenshots are never in flight at the same time. If one screenshot takes
+ * longer than the interval, the missed ticks are skipped rather than bunched.
+ *
+ * Every screenshot is bounded by an explicit timeout: Chromium blocks
+ * screenshots while a cross-document navigation is pending or the main thread
+ * is busy, and Playwright's 30s default would otherwise stall the recording
+ * (and stop(), which waits for the in-flight shot) for minutes.
+ */
+export interface RecorderOptions {
+    /** Interval between interval frames. Default CAPTURE_INTERVAL_MS. */
+    interval_ms?: number;
+}
+export interface RecordingResult {
+    /** All captured frames in ascending timestamp_ms order (forced frames interleaved in time order). */
+    frames: RawFrame[];
+    /** Actual wall-clock recording length in ms. */
+    duration_ms: number;
+    /** Interval ticks whose screenshot failed (e.g. mid-navigation) and were skipped. */
+    dropped: number;
+    /**
+     * Epoch ms of timestamp 0. The context layers start collecting before the
+     * navigation, so they stamp absolute time and need this to rebase onto the
+     * same clock the frames use.
+     */
+    started_at: number;
+}
+export declare class FrameRecorder {
+    #private;
+    constructor(page: Page, options?: RecorderOptions);
+    /** Frames captured so far (live view, in capture order). */
+    get frames(): readonly RawFrame[];
+    /**
+     * Start the interval loop; timestamp 0 is now. The first frame is captured
+     * immediately. Idempotent, and a no-op once the recorder has been stopped.
+     */
+    start(): void;
+    /**
+     * Capture one frame right now (outside the interval), tagged with `trigger`
+     * (is_interaction = trigger === "interaction"). Waits for any in-flight
+     * screenshot first. Resolves to the frame, or null if the screenshot
+     * failed. Never throws.
+     */
+    captureNow(trigger: FrameTrigger): Promise<RawFrame | null>;
+    /** Stop the loop, wait for any in-flight screenshot, capture one final frame, and return the result. */
+    stop(): Promise<RecordingResult>;
+}
+/**
+ * Convenience: start → (run `during(recorder)` concurrently if given) → wait
+ * `duration_ms` from start → stop. If `during` rejects, the recorder is
+ * stopped first and the error is rethrown.
+ */
+export declare function recordFrames(page: Page, options: RecorderOptions & {
+    duration_ms: number;
+}, during?: (recorder: FrameRecorder) => Promise<void>): Promise<RecordingResult>;

package/dist/engine/recorder.js

@@ -0,0 +1,256 @@
+import { CAPTURE_INTERVAL_MS, SCREENSHOT_FINAL_TIMEOUT_MS, SCREENSHOT_RETRY_ATTEMPTS, SCREENSHOT_RETRY_DELAY_MS, SCREENSHOT_TIMEOUT_MS, } from "../constants.js";
+export class FrameRecorder {
+    #page;
+    #interval;
+    #frames = [];
+    #startedAt = 0;
+    #running = false;
+    #timer = null;
+    /** The currently running interval tick (screenshot), if any. */
+    #inFlight = null;
+    /** Serialises every screenshot (interval + out-of-band) so no two are ever in flight together. */
+    #chain = Promise.resolve();
+    #dropped = 0;
+    /** Per-screenshot timeout — see the class doc. */
+    #screenshotTimeout;
+    /** True while the last screenshot attempt timed out; stop() then skips the final frame. */
+    #unresponsive = false;
+    /** Main-frame URL (without fragment) of the last navigation we reacted to. */
+    #lastNavUrl = null;
+    /** Set by a navigation; the next frame that lands is tagged "navigation". */
+    #pendingNavTag = false;
+    /** Set by the first stop(); later calls return the same result instead of capturing again. */
+    #result = null;
+    /**
+     * Main-frame navigation → the next frame that lands is tagged "navigation"
+     * (and so is always kept by the differ). Attached in start(), removed in
+     * stop().
+     *
+     * Tagging rather than taking a dedicated screenshot matters twice over.
+     * Playwright emits this event for same-document navigations too, so the
+     * common scroll-spy / router pattern (a `history.replaceState` on every
+     * animation frame) fires it ~60 times a second — a screenshot per event
+     * would starve the recorder. And a screenshot requested at commit time is
+     * the one most likely to block: Chromium has not painted the new document
+     * yet, so the request hangs until it does, holds up every capture queued
+     * behind it, and can be lost entirely if the recording ends first. The next
+     * frame the loop takes shows the same navigation and always arrives.
+     *
+     * Fragment-only changes are ignored outright: `#a` → `#b` navigates nothing.
+     */
+    #onFrameNavigated = (frame) => {
+        if (frame !== this.#page.mainFrame())
+            return;
+        const url = stripFragment(frame.url());
+        if (url === this.#lastNavUrl)
+            return;
+        this.#lastNavUrl = url;
+        this.#pendingNavTag = true;
+    };
+    constructor(page, options = {}) {
+        this.#page = page;
+        const interval = options.interval_ms;
+        // A zero/negative/NaN interval would turn the tick chain into a tight
+        // screenshot loop (setTimeout coerces NaN and Infinity to ~1ms).
+        this.#interval = typeof interval === "number" && Number.isFinite(interval) && interval > 0 ? interval : CAPTURE_INTERVAL_MS;
+        this.#screenshotTimeout = Math.max(SCREENSHOT_TIMEOUT_MS, this.#interval * 2);
+    }
+    /** Frames captured so far (live view, in capture order). */
+    get frames() {
+        return this.#frames;
+    }
+    /**
+     * Start the interval loop; timestamp 0 is now. The first frame is captured
+     * immediately. Idempotent, and a no-op once the recorder has been stopped.
+     */
+    start() {
+        if (this.#running || this.#result)
+            return;
+        this.#running = true;
+        this.#startedAt = Date.now();
+        this.#lastNavUrl = stripFragment(this.#page.url());
+        this.#page.on("framenavigated", this.#onFrameNavigated);
+        this.#tick(0);
+    }
+    /**
+     * Capture one frame right now (outside the interval), tagged with `trigger`
+     * (is_interaction = trigger === "interaction"). Waits for any in-flight
+     * screenshot first. Resolves to the frame, or null if the screenshot
+     * failed. Never throws.
+     */
+    captureNow(trigger) {
+        return this.#capture(trigger);
+    }
+    /** Stop the loop, wait for any in-flight screenshot, capture one final frame, and return the result. */
+    async stop() {
+        if (!this.#result) {
+            this.#result = this.#doStop();
+        }
+        return this.#result;
+    }
+    async #doStop() {
+        this.#running = false;
+        this.#page.off("framenavigated", this.#onFrameNavigated);
+        if (this.#timer) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+        await this.#inFlight;
+        // Always try for a final frame — it is the settled end state, and it may
+        // still be carrying a pending navigation tag. If the last attempt timed
+        // out, bound this one tightly so a wedged page cannot stall shutdown while
+        // a page that has since recovered still gets captured.
+        if (!this.#page.isClosed()) {
+            await this.#capture(undefined, this.#unresponsive ? SCREENSHOT_FINAL_TIMEOUT_MS : undefined);
+        }
+        const duration_ms = this.#elapsed();
+        const frames = [...this.#frames].sort((a, b) => a.timestamp_ms - b.timestamp_ms);
+        return { frames, duration_ms, dropped: this.#dropped, started_at: this.#startedAt };
+    }
+    #elapsed() {
+        return Date.now() - this.#startedAt;
+    }
+    /** Run interval tick `n`, then schedule the next tick that is still in the future. */
+    #tick(n) {
+        if (!this.#running)
+            return;
+        this.#timer = null;
+        if (this.#page.isClosed()) {
+            // Nothing left to record — stop silently rather than counting every remaining tick as dropped.
+            this.#running = false;
+            return;
+        }
+        this.#inFlight = this.#capture(undefined)
+            .then((frame) => {
+            if (frame === null && !this.#page.isClosed())
+                this.#dropped++;
+        })
+            .finally(() => {
+            this.#inFlight = null;
+            if (!this.#running || this.#page.isClosed())
+                return;
+            // Next tick strictly in the future: skip any ticks already missed so screenshots never bunch up.
+            const elapsed = this.#elapsed();
+            const next = Math.max(n + 1, Math.floor(elapsed / this.#interval) + 1);
+            this.#timer = setTimeout(() => this.#tick(next), next * this.#interval - elapsed);
+        });
+    }
+    /**
+     * Take one screenshot (after any in-flight one has finished) and append it.
+     *
+     * The frame is stamped when the screenshot *resolves*, not when it was
+     * requested: a screenshot that waits on a pending navigation returns the new
+     * document, and stamping it with the request time would report the change as
+     * having happened far earlier than it did.
+     *
+     * Resolves to the frame, or null if the screenshot failed. Never throws.
+     */
+    #capture(trigger, timeoutMs) {
+        const run = async () => {
+            const buffer = await this.#screenshot(timeoutMs ?? this.#screenshotTimeout);
+            if (buffer === null)
+                return null;
+            // A navigation since the last frame? This one shows it.
+            let effective = trigger;
+            if (this.#pendingNavTag) {
+                this.#pendingNavTag = false;
+                effective ??= "navigation";
+            }
+            const frame = {
+                buffer,
+                timestamp_ms: this.#elapsed(),
+                is_interaction: effective === "interaction",
+                ...(effective !== undefined ? { trigger: effective } : {}),
+            };
+            this.#frames.push(frame);
+            return frame;
+        };
+        const result = this.#chain.then(run, run);
+        this.#chain = result;
+        return result;
+    }
+    /**
+     * One bounded screenshot. Returns null on failure (never throws) and records
+     * whether the page stopped responding. Chromium refuses a screenshot until
+     * it has produced its first frame — right after a navigation commits that
+     * happens about half the time — so that specific error is retried briefly.
+     */
+    async #screenshot(timeoutMs) {
+        for (let attempt = 0; attempt < SCREENSHOT_RETRY_ATTEMPTS; attempt++) {
+            try {
+                const buffer = await this.#page.screenshot({ type: "png", timeout: timeoutMs });
+                this.#unresponsive = false;
+                return buffer;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/Timeout .*exceeded/i.test(message)) {
+                    // The page is blocked; retrying only stalls the recording further.
+                    this.#unresponsive = true;
+                    return null;
+                }
+                if (!/Unable to capture screenshot/i.test(message) || this.#page.isClosed()) {
+                    return null;
+                }
+                await delay(SCREENSHOT_RETRY_DELAY_MS);
+            }
+        }
+        return null;
+    }
+}
+/** Compare navigation URLs without their fragment — `#a` → `#b` navigates nothing. */
+function stripFragment(url) {
+    const hash = url.indexOf("#");
+    return hash === -1 ? url : url.slice(0, hash);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Convenience: start → (run `during(recorder)` concurrently if given) → wait
+ * `duration_ms` from start → stop. If `during` rejects, the recorder is
+ * stopped first and the error is rethrown.
+ */
+export async function recordFrames(page, options, during) {
+    const recorder = new FrameRecorder(page, options);
+    recorder.start();
+    let timer;
+    const duration = Number.isFinite(options.duration_ms) ? Math.max(0, options.duration_ms) : 0;
+    const wait = new Promise((resolve) => {
+        timer = setTimeout(resolve, duration);
+    });
+    // There is nothing left to record once the page is gone: end the recording
+    // immediately instead of idling out the rest of the duration.
+    let onGone;
+    const pageGone = new Promise((resolve) => {
+        onGone = () => resolve();
+        page.once("close", onGone);
+        page.once("crash", onGone);
+    });
+    try {
+        const elapse = Promise.race([wait, pageGone]);
+        if (during) {
+            // Let a failing `during` short-circuit the wait; a successful one still waits out the duration.
+            await Promise.all([elapse, during(recorder)]);
+        }
+        else {
+            await elapse;
+        }
+    }
+    catch (error) {
+        clearTimeout(timer);
+        if (onGone) {
+            page.off("close", onGone);
+            page.off("crash", onGone);
+        }
+        await recorder.stop();
+        throw error;
+    }
+    clearTimeout(timer);
+    if (onGone) {
+        page.off("close", onGone);
+        page.off("crash", onGone);
+    }
+    return recorder.stop();
+}
+//# sourceMappingURL=recorder.js.map

package/dist/engine/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/engine/recorder.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Frame, Page } from \"playwright\";\nimport {\n  CAPTURE_INTERVAL_MS,\n  SCREENSHOT_FINAL_TIMEOUT_MS,\n  SCREENSHOT_RETRY_ATTEMPTS,\n  SCREENSHOT_RETRY_DELAY_MS,\n  SCREENSHOT_TIMEOUT_MS,\n} from \"../constants.js\";\nimport type { FrameTrigger, RawFrame } from \"../types.js\";\n\n/**\n * Frame recorder.\n *\n * Captures raw PNG screenshots of a page at a fixed interval using a\n * self-scheduling `setTimeout` chain aligned to `start + n * interval`, so two\n * screenshots are never in flight at the same time. If one screenshot takes\n * longer than the interval, the missed ticks are skipped rather than bunched.\n *\n * Every screenshot is bounded by an explicit timeout: Chromium blocks\n * screenshots while a cross-document navigation is pending or the main thread\n * is busy, and Playwright's 30s default would otherwise stall the recording\n * (and stop(), which waits for the in-flight shot) for minutes.\n */\n\nexport interface RecorderOptions {\n  /** Interval between interval frames. Default CAPTURE_INTERVAL_MS. */\n  interval_ms?: number;\n}\n\nexport interface RecordingResult {\n  /** All captured frames in ascending timestamp_ms order (forced frames interleaved in time order). */\n  frames: RawFrame[];\n  /** Actual wall-clock recording length in ms. */\n  duration_ms: number;\n  /** Interval ticks whose screenshot failed (e.g. mid-navigation) and were skipped. */\n  dropped: number;\n  /**\n   * Epoch ms of timestamp 0. The context layers start collecting before the\n   * navigation, so they stamp absolute time and need this to rebase onto the\n   * same clock the frames use.\n   */\n  started_at: number;\n}\n\nexport class FrameRecorder {\n  readonly #page: Page;\n  readonly #interval: number;\n  readonly #frames: RawFrame[] = [];\n  #startedAt = 0;\n  #running = false;\n  #timer: NodeJS.Timeout | null = null;\n  /** The currently running interval tick (screenshot), if any. */\n  #inFlight: Promise<void> | null = null;\n  /** Serialises every screenshot (interval + out-of-band) so no two are ever in flight together. */\n  #chain: Promise<unknown> = Promise.resolve();\n  #dropped = 0;\n  /** Per-screenshot timeout — see the class doc. */\n  readonly #screenshotTimeout: number;\n  /** True while the last screenshot attempt timed out; stop() then skips the final frame. */\n  #unresponsive = false;\n  /** Main-frame URL (without fragment) of the last navigation we reacted to. */\n  #lastNavUrl: string | null = null;\n  /** Set by a navigation; the next frame that lands is tagged \"navigation\". */\n  #pendingNavTag = false;\n  /** Set by the first stop(); later calls return the same result instead of capturing again. */\n  #result: Promise<RecordingResult> | null = null;\n  /**\n   * Main-frame navigation → the next frame that lands is tagged \"navigation\"\n   * (and so is always kept by the differ). Attached in start(), removed in\n   * stop().\n   *\n   * Tagging rather than taking a dedicated screenshot matters twice over.\n   * Playwright emits this event for same-document navigations too, so the\n   * common scroll-spy / router pattern (a `history.replaceState` on every\n   * animation frame) fires it ~60 times a second — a screenshot per event\n   * would starve the recorder. And a screenshot requested at commit time is\n   * the one most likely to block: Chromium has not painted the new document\n   * yet, so the request hangs until it does, holds up every capture queued\n   * behind it, and can be lost entirely if the recording ends first. The next\n   * frame the loop takes shows the same navigation and always arrives.\n   *\n   * Fragment-only changes are ignored outright: `#a` → `#b` navigates nothing.\n   */\n  readonly #onFrameNavigated = (frame: Frame): void => {\n    if (frame !== this.#page.mainFrame()) return;\n\n    const url = stripFragment(frame.url());\n    if (url === this.#lastNavUrl) return;\n    this.#lastNavUrl = url;\n    this.#pendingNavTag = true;\n  };\n\n  constructor(page: Page, options: RecorderOptions = {}) {\n    this.#page = page;\n    const interval = options.interval_ms;\n    // A zero/negative/NaN interval would turn the tick chain into a tight\n    // screenshot loop (setTimeout coerces NaN and Infinity to ~1ms).\n    this.#interval = typeof interval === \"number\" && Number.isFinite(interval) && interval > 0 ? interval : CAPTURE_INTERVAL_MS;\n    this.#screenshotTimeout = Math.max(SCREENSHOT_TIMEOUT_MS, this.#interval * 2);\n  }\n\n  /** Frames captured so far (live view, in capture order). */\n  get frames(): readonly RawFrame[] {\n    return this.#frames;\n  }\n\n  /**\n   * Start the interval loop; timestamp 0 is now. The first frame is captured\n   * immediately. Idempotent, and a no-op once the recorder has been stopped.\n   */\n  start(): void {\n    if (this.#running || this.#result) return;\n    this.#running = true;\n    this.#startedAt = Date.now();\n    this.#lastNavUrl = stripFragment(this.#page.url());\n    this.#page.on(\"framenavigated\", this.#onFrameNavigated);\n    this.#tick(0);\n  }\n\n  /**\n   * Capture one frame right now (outside the interval), tagged with `trigger`\n   * (is_interaction = trigger === \"interaction\"). Waits for any in-flight\n   * screenshot first. Resolves to the frame, or null if the screenshot\n   * failed. Never throws.\n   */\n  captureNow(trigger: FrameTrigger): Promise<RawFrame | null> {\n    return this.#capture(trigger);\n  }\n\n  /** Stop the loop, wait for any in-flight screenshot, capture one final frame, and return the result. */\n  async stop(): Promise<RecordingResult> {\n    if (!this.#result) {\n      this.#result = this.#doStop();\n    }\n    return this.#result;\n  }\n\n  async #doStop(): Promise<RecordingResult> {\n    this.#running = false;\n    this.#page.off(\"framenavigated\", this.#onFrameNavigated);\n    if (this.#timer) {\n      clearTimeout(this.#timer);\n      this.#timer = null;\n    }\n    await this.#inFlight;\n    // Always try for a final frame — it is the settled end state, and it may\n    // still be carrying a pending navigation tag. If the last attempt timed\n    // out, bound this one tightly so a wedged page cannot stall shutdown while\n    // a page that has since recovered still gets captured.\n    if (!this.#page.isClosed()) {\n      await this.#capture(undefined, this.#unresponsive ? SCREENSHOT_FINAL_TIMEOUT_MS : undefined);\n    }\n    const duration_ms = this.#elapsed();\n    const frames = [...this.#frames].sort((a, b) => a.timestamp_ms - b.timestamp_ms);\n    return { frames, duration_ms, dropped: this.#dropped, started_at: this.#startedAt };\n  }\n\n  #elapsed(): number {\n    return Date.now() - this.#startedAt;\n  }\n\n  /** Run interval tick `n`, then schedule the next tick that is still in the future. */\n  #tick(n: number): void {\n    if (!this.#running) return;\n    this.#timer = null;\n    if (this.#page.isClosed()) {\n      // Nothing left to record — stop silently rather than counting every remaining tick as dropped.\n      this.#running = false;\n      return;\n    }\n    this.#inFlight = this.#capture(undefined)\n      .then((frame) => {\n        if (frame === null && !this.#page.isClosed()) this.#dropped++;\n      })\n      .finally(() => {\n        this.#inFlight = null;\n        if (!this.#running || this.#page.isClosed()) return;\n        // Next tick strictly in the future: skip any ticks already missed so screenshots never bunch up.\n        const elapsed = this.#elapsed();\n        const next = Math.max(n + 1, Math.floor(elapsed / this.#interval) + 1);\n        this.#timer = setTimeout(() => this.#tick(next), next * this.#interval - elapsed);\n      });\n  }\n\n  /**\n   * Take one screenshot (after any in-flight one has finished) and append it.\n   *\n   * The frame is stamped when the screenshot *resolves*, not when it was\n   * requested: a screenshot that waits on a pending navigation returns the new\n   * document, and stamping it with the request time would report the change as\n   * having happened far earlier than it did.\n   *\n   * Resolves to the frame, or null if the screenshot failed. Never throws.\n   */\n  #capture(trigger: FrameTrigger | undefined, timeoutMs?: number): Promise<RawFrame | null> {\n    const run = async (): Promise<RawFrame | null> => {\n      const buffer = await this.#screenshot(timeoutMs ?? this.#screenshotTimeout);\n      if (buffer === null) return null;\n      // A navigation since the last frame? This one shows it.\n      let effective = trigger;\n      if (this.#pendingNavTag) {\n        this.#pendingNavTag = false;\n        effective ??= \"navigation\";\n      }\n      const frame: RawFrame = {\n        buffer,\n        timestamp_ms: this.#elapsed(),\n        is_interaction: effective === \"interaction\",\n        ...(effective !== undefined ? { trigger: effective } : {}),\n      };\n      this.#frames.push(frame);\n      return frame;\n    };\n    const result = this.#chain.then(run, run);\n    this.#chain = result;\n    return result;\n  }\n\n  /**\n   * One bounded screenshot. Returns null on failure (never throws) and records\n   * whether the page stopped responding. Chromium refuses a screenshot until\n   * it has produced its first frame — right after a navigation commits that\n   * happens about half the time — so that specific error is retried briefly.\n   */\n  async #screenshot(timeoutMs: number): Promise<Buffer | null> {\n    for (let attempt = 0; attempt < SCREENSHOT_RETRY_ATTEMPTS; attempt++) {\n      try {\n        const buffer = await this.#page.screenshot({ type: \"png\", timeout: timeoutMs });\n        this.#unresponsive = false;\n        return buffer;\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        if (/Timeout .*exceeded/i.test(message)) {\n          // The page is blocked; retrying only stalls the recording further.\n          this.#unresponsive = true;\n          return null;\n        }\n        if (!/Unable to capture screenshot/i.test(message) || this.#page.isClosed()) {\n          return null;\n        }\n        await delay(SCREENSHOT_RETRY_DELAY_MS);\n      }\n    }\n    return null;\n  }\n}\n\n/** Compare navigation URLs without their fragment — `#a` → `#b` navigates nothing. */\nfunction stripFragment(url: string): string {\n  const hash = url.indexOf(\"#\");\n  return hash === -1 ? url : url.slice(0, hash);\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Convenience: start → (run `during(recorder)` concurrently if given) → wait\n * `duration_ms` from start → stop. If `during` rejects, the recorder is\n * stopped first and the error is rethrown.\n */\nexport async function recordFrames(\n  page: Page,\n  options: RecorderOptions & { duration_ms: number },\n  during?: (recorder: FrameRecorder) => Promise<void>,\n): Promise<RecordingResult> {\n  const recorder = new FrameRecorder(page, options);\n  recorder.start();\n\n  let timer: NodeJS.Timeout | undefined;\n  const duration = Number.isFinite(options.duration_ms) ? Math.max(0, options.duration_ms) : 0;\n  const wait = new Promise<void>((resolve) => {\n    timer = setTimeout(resolve, duration);\n  });\n\n  // There is nothing left to record once the page is gone: end the recording\n  // immediately instead of idling out the rest of the duration.\n  let onGone: (() => void) | undefined;\n  const pageGone = new Promise<void>((resolve) => {\n    onGone = (): void => resolve();\n    page.once(\"close\", onGone);\n    page.once(\"crash\", onGone);\n  });\n\n  try {\n    const elapse = Promise.race([wait, pageGone]);\n    if (during) {\n      // Let a failing `during` short-circuit the wait; a successful one still waits out the duration.\n      await Promise.all([elapse, during(recorder)]);\n    } else {\n      await elapse;\n    }\n  } catch (error) {\n    clearTimeout(timer);\n    if (onGone) {\n      page.off(\"close\", onGone);\n      page.off(\"crash\", onGone);\n    }\n    await recorder.stop();\n    throw error;\n  }\n  clearTimeout(timer);\n  if (onGone) {\n    page.off(\"close\", onGone);\n    page.off(\"crash\", onGone);\n  }\n  return recorder.stop();\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const SERVER_NAME = "framewatch";
+export declare const SERVER_VERSION: string;
+/**
+ * Build a fully configured FrameWatch McpServer (not yet connected to a
+ * transport). Exported so tests and embedders can wire their own transport;
+ * importing this module has no side effects — the stdio server only starts
+ * when this file is executed directly (`node dist/index.js` / the npm bin).
+ */
+export declare function createServer(): McpServer;
+/** Run the server on stdio until the client disconnects or the process is signalled. */
+export declare function main(): Promise<void>;