npm - framewatch-mcp-server - Versions diffs - 0.1.0 - Mend

framewatch-mcp-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/LICENSE +21 -0
package/README.md +537 -0
package/dist/constants.d.ts +172 -0
package/dist/constants.js +168 -0
package/dist/constants.js.map +1 -0
package/dist/engine/browser.d.ts +56 -0
package/dist/engine/browser.js +142 -0
package/dist/engine/browser.js.map +1 -0
package/dist/engine/differ.d.ts +88 -0
package/dist/engine/differ.js +373 -0
package/dist/engine/differ.js.map +1 -0
package/dist/engine/interaction.d.ts +76 -0
package/dist/engine/interaction.js +254 -0
package/dist/engine/interaction.js.map +1 -0
package/dist/engine/layers/console.d.ts +63 -0
package/dist/engine/layers/console.js +118 -0
package/dist/engine/layers/console.js.map +1 -0
package/dist/engine/layers/dom.d.ts +53 -0
package/dist/engine/layers/dom.js +282 -0
package/dist/engine/layers/dom.js.map +1 -0
package/dist/engine/layers/index.d.ts +95 -0
package/dist/engine/layers/index.js +184 -0
package/dist/engine/layers/index.js.map +1 -0
package/dist/engine/layers/network.d.ts +62 -0
package/dist/engine/layers/network.js +169 -0
package/dist/engine/layers/network.js.map +1 -0
package/dist/engine/layers/performance.d.ts +55 -0
package/dist/engine/layers/performance.js +215 -0
package/dist/engine/layers/performance.js.map +1 -0
package/dist/engine/layers/probe.d.ts +50 -0
package/dist/engine/layers/probe.js +39 -0
package/dist/engine/layers/probe.js.map +1 -0
package/dist/engine/layers/session.d.ts +46 -0
package/dist/engine/layers/session.js +131 -0
package/dist/engine/layers/session.js.map +1 -0
package/dist/engine/recorder.d.ts +61 -0
package/dist/engine/recorder.js +256 -0
package/dist/engine/recorder.js.map +1 -0
package/dist/index.d.ts +13 -0
package/dist/index.js +125 -0
package/dist/index.js.map +1 -0
package/dist/tools/accessibility.d.ts +140 -0
package/dist/tools/accessibility.js +357 -0
package/dist/tools/accessibility.js.map +1 -0
package/dist/tools/capture.d.ts +279 -0
package/dist/tools/capture.js +275 -0
package/dist/tools/capture.js.map +1 -0
package/dist/tools/compare.d.ts +86 -0
package/dist/tools/compare.js +247 -0
package/dist/tools/compare.js.map +1 -0
package/dist/tools/index.d.ts +10 -0
package/dist/tools/index.js +25 -0
package/dist/tools/index.js.map +1 -0
package/dist/tools/interact.d.ts +160 -0
package/dist/tools/interact.js +203 -0
package/dist/tools/interact.js.map +1 -0
package/dist/tools/responsive.d.ts +89 -0
package/dist/tools/responsive.js +197 -0
package/dist/tools/responsive.js.map +1 -0
package/dist/tools/screenshot.d.ts +76 -0
package/dist/tools/screenshot.js +117 -0
package/dist/tools/screenshot.js.map +1 -0
package/dist/tools/server.d.ts +89 -0
package/dist/tools/server.js +201 -0
package/dist/tools/server.js.map +1 -0
package/dist/types.d.ts +123 -0
package/dist/types.js +9 -0
package/dist/types.js.map +1 -0
package/dist/utils/bounded-log.d.ts +41 -0
package/dist/utils/bounded-log.js +78 -0
package/dist/utils/bounded-log.js.map +1 -0
package/dist/utils/format.d.ts +56 -0
package/dist/utils/format.js +130 -0
package/dist/utils/format.js.map +1 -0
package/dist/utils/image.d.ts +44 -0
package/dist/utils/image.js +81 -0
package/dist/utils/image.js.map +1 -0
package/dist/utils/server-process.d.ts +84 -0
package/dist/utils/server-process.js +251 -0
package/dist/utils/server-process.js.map +1 -0
package/package.json +74 -0

package/dist/engine/layers/dom.js ADDED Viewed

@@ -0,0 +1,282 @@
+import { MAX_DOM_LINES_PER_CARD, MAX_DOM_RECORDS } from "../../constants.js";
+import { installProbe, probeConfig } from "./probe.js";
+/**
+ * DOM layer.
+ *
+ * A frame tells you *that* something changed; this tells you *what*. A
+ * MutationObserver installed at document start records every structural
+ * change, and the records that fall between two diff cards are grouped into a
+ * few lines — "a div.modal appeared inside #app", "#app's style attribute
+ * changed 24 times" — which is usually enough to name the element behind a
+ * visual change without reading the app's source.
+ *
+ * Deliberately not recorded:
+ *  - anything inside `<head>`. Stylesheet and meta churn is constant in modern
+ *    apps (every CSS-in-JS library injects rules continuously) and its effect
+ *    is already visible in the frames.
+ *  - script/link/meta/title/template elements, comments and doctypes: not
+ *    visual.
+ *  - whitespace-only text nodes: markup indentation, not content.
+ * Subframes are skipped too — the probe only runs in the main frame, so an ad
+ * iframe cannot drown out the page under test.
+ */
+const BINDING = "__framewatch_dom";
+/**
+ * The page-side probe.
+ *
+ * Written against `globalThis` rather than the DOM globals because this file
+ * is compiled with the Node lib only — and because everything it touches has
+ * to be defensive anyway: it runs at document start in someone else's app,
+ * where any of it may be missing, patched or about to be torn down.
+ */
+const DOM_PROBE = (config) => {
+    const g = globalThis;
+    // Main frame only.
+    if (g.top && g.top !== g)
+        return;
+    // The probe can be asked for twice on one document (installed on a page that
+    // is already open, then re-run by the init script); a second MutationObserver
+    // would report every mutation twice.
+    const installed = config.binding + "_observing";
+    if (g[installed])
+        return;
+    g[installed] = true;
+    const send = g[config.binding];
+    const doc = g.document;
+    if (typeof send !== "function" || !doc || typeof g.MutationObserver !== "function")
+        return;
+    const SKIP_TAGS = ["script", "link", "meta", "title", "base", "noscript", "template", "head"];
+    const MAX_DESC = 48;
+    let queue = [];
+    let scheduled = false;
+    let budget = config.max_records;
+    const flush = () => {
+        scheduled = false;
+        if (queue.length === 0)
+            return;
+        const batch = queue;
+        queue = [];
+        try {
+            const result = send(batch);
+            if (result && typeof result.catch === "function")
+                result.catch(() => { });
+        }
+        catch {
+            // The page is being torn down; there is nowhere left to push to.
+        }
+    };
+    const push = (record) => {
+        if (budget <= 0)
+            return;
+        budget--;
+        if (queue.length >= config.max_batch)
+            flush();
+        queue.push(record);
+        if (!scheduled) {
+            scheduled = true;
+            g.setTimeout(flush, config.flush_ms);
+        }
+    };
+    try {
+        g.addEventListener("pagehide", flush, true);
+    }
+    catch {
+        // Not fatal: records wait for the timer instead.
+    }
+    const desc = (node) => {
+        if (!node)
+            return "?";
+        const type = node.nodeType;
+        if (type === 9)
+            return "#document";
+        if (type === 11)
+            return "#fragment";
+        if (type === 3)
+            return "#text";
+        if (type !== 1)
+            return "#node";
+        let out = String(node.tagName || "?").toLowerCase();
+        if (node.id)
+            out += "#" + String(node.id);
+        else if (node.classList && node.classList.length)
+            out += "." + String(node.classList[0]);
+        return out.length > MAX_DESC ? out.slice(0, MAX_DESC) + "…" : out;
+    };
+    /** Head content is noise (see the file comment); so is anything inside it. */
+    const inHead = (node) => {
+        const head = doc.head;
+        if (!head || !node)
+            return false;
+        if (node === head)
+            return true;
+        try {
+            return head.contains(node) === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    /** Nodes whose appearance or removal says nothing about what the page looks like. */
+    const ignored = (node) => {
+        if (!node)
+            return true;
+        const type = node.nodeType;
+        if (type === 3)
+            return String(node.nodeValue || "").trim() === "";
+        if (type !== 1)
+            return true;
+        return SKIP_TAGS.indexOf(String(node.tagName || "").toLowerCase()) !== -1;
+    };
+    /**
+     * Containers whose *contents* are not worth reporting either. Without this,
+     * parsing an inline <script> reports the arrival of its source text as a
+     * change to the page.
+     */
+    const ignoredContainer = (node) => {
+        if (!node || node.nodeType !== 1)
+            return false;
+        return SKIP_TAGS.indexOf(String(node.tagName || "").toLowerCase()) !== -1;
+    };
+    const record = (op, target, extra) => {
+        push({ t: Date.now(), op, target, ...extra });
+    };
+    /** A text node changing is really its parent element's text changing. */
+    const noteChildren = (nodes, op, parent) => {
+        const count = nodes ? nodes.length : 0;
+        for (let i = 0; i < count; i++) {
+            const node = nodes[i];
+            if (ignored(node))
+                continue;
+            if (node.nodeType === 3)
+                record("t", desc(parent));
+            else
+                record(op, desc(node), { parent: desc(parent) });
+        }
+    };
+    try {
+        new g.MutationObserver((records) => {
+            for (const mutation of records) {
+                const target = mutation.target;
+                if (inHead(target) || ignoredContainer(target))
+                    continue;
+                if (mutation.type === "childList") {
+                    noteChildren(mutation.addedNodes, "+", target);
+                    noteChildren(mutation.removedNodes, "-", target);
+                }
+                else if (mutation.type === "attributes") {
+                    record("~", desc(target), { detail: String(mutation.attributeName || "") });
+                }
+                else {
+                    // characterData: the text of the node's parent element changed.
+                    // Whitespace edits are the parser reflowing indentation, not content.
+                    const parent = target ? target.parentNode : null;
+                    if (String(target && target.nodeValue ? target.nodeValue : "").trim() === "")
+                        continue;
+                    if (ignoredContainer(parent) || inHead(parent))
+                        continue;
+                    record("t", desc(parent));
+                }
+            }
+        }).observe(doc, { subtree: true, childList: true, attributes: true, characterData: true });
+    }
+    catch {
+        // No observer, no DOM layer. The capture is still worth having.
+    }
+};
+export class DomCollector {
+    #page;
+    #limit;
+    #records = [];
+    #dropped = 0;
+    constructor(page, limit = MAX_DOM_RECORDS) {
+        this.#page = page;
+        this.#limit = Math.max(1, limit);
+    }
+    /**
+     * Install the probe. Call before the page navigates, or pass
+     * `{ runNow: true }` to also watch the document that is already loaded.
+     */
+    async attach(options = {}) {
+        const config = probeConfig(BINDING);
+        await installProbe(this.#page, config, DOM_PROBE, (batch) => this.#ingest(batch), options);
+        return this;
+    }
+    /** Mutations the cap refused. */
+    get dropped() {
+        return this.#dropped;
+    }
+    /** Forget everything collected so far. See `BoundedLog.clear`. */
+    clear() {
+        this.#records.length = 0;
+        this.#dropped = 0;
+    }
+    /**
+     * 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) {
+        return this.#records.map((record) => ({
+            timestamp_ms: Math.round(record.t - origin),
+            op: record.op,
+            target: record.target,
+            ...(record.parent !== undefined ? { parent: record.parent } : {}),
+            ...(record.detail !== undefined ? { detail: record.detail } : {}),
+        }));
+    }
+    #ingest(batch) {
+        for (const record of batch) {
+            // The page pushes this, so nothing about it is trusted.
+            if (!record || typeof record.t !== "number" || typeof record.target !== "string")
+                continue;
+            if (this.#records.length >= this.#limit) {
+                this.#dropped++;
+                continue;
+            }
+            this.#records.push(record);
+        }
+    }
+}
+/**
+ * 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 function renderDomChanges(records, maxLines = MAX_DOM_LINES_PER_CARD) {
+    if (records.length === 0)
+        return undefined;
+    const groups = new Map();
+    for (const record of records) {
+        const line = describeRecord(record);
+        const existing = groups.get(line);
+        if (existing)
+            existing.count++;
+        else
+            groups.set(line, { line, count: 1 });
+    }
+    const all = [...groups.values()];
+    const shown = all.slice(0, Math.max(1, maxLines));
+    const lines = shown.map((group) => (group.count > 1 ? `  ${group.line} ×${group.count}` : `  ${group.line}`));
+    if (all.length > shown.length) {
+        const hidden = all.slice(shown.length).reduce((sum, group) => sum + group.count, 0);
+        lines.push(`  … and ${hidden} more change${hidden === 1 ? "" : "s"} across ${all.length - shown.length} elements`);
+    }
+    return lines.join("\n");
+}
+function describeRecord(record) {
+    switch (record.op) {
+        case "+":
+            return record.parent ? `+ ${record.target} in ${record.parent}` : `+ ${record.target}`;
+        case "-":
+            return record.parent ? `- ${record.target} from ${record.parent}` : `- ${record.target}`;
+        case "~":
+            return `~ ${record.target} [${record.detail ?? "?"}]`;
+        default:
+            return `~ text in ${record.target}`;
+    }
+}
+//# sourceMappingURL=dom.js.map

package/dist/engine/layers/dom.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../src/engine/layers/dom.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from \"playwright\";\nimport { MAX_DOM_LINES_PER_CARD, MAX_DOM_RECORDS } from \"../../constants.js\";\nimport { installProbe, probeConfig, type InstallOptions, type ProbeConfig } from \"./probe.js\";\n\n/**\n * DOM layer.\n *\n * A frame tells you *that* something changed; this tells you *what*. A\n * MutationObserver installed at document start records every structural\n * change, and the records that fall between two diff cards are grouped into a\n * few lines — \"a div.modal appeared inside #app\", \"#app's style attribute\n * changed 24 times\" — which is usually enough to name the element behind a\n * visual change without reading the app's source.\n *\n * Deliberately not recorded:\n * - anything inside `<head>`. Stylesheet and meta churn is constant in modern\n * apps (every CSS-in-JS library injects rules continuously) and its effect\n * is already visible in the frames.\n * - script/link/meta/title/template elements, comments and doctypes: not\n * visual.\n * - whitespace-only text nodes: markup indentation, not content.\n * Subframes are skipped too — the probe only runs in the main frame, so an ad\n * iframe cannot drown out the page under test.\n */\n\nconst BINDING = \"__framewatch_dom\";\n\n/** What happened to a node. */\nexport type DomOp = \"+\" | \"-\" | \"~\" | \"t\";\n\n/** One mutation, as pushed by the page. Timestamps are absolute (epoch ms). */\nexport interface RawDomRecord {\n /** Absolute time the mutation was observed. */\n t: number;\n op: DomOp;\n /** Short descriptor of the node — `div#id`, `span.class`, `p`. */\n target: string;\n /** Descriptor of the parent, for adds and removes. */\n parent?: string;\n /** Attribute name, for `~`. */\n detail?: string;\n}\n\n/** One mutation, rebased onto the recording clock. */\nexport interface DomRecord {\n timestamp_ms: number;\n op: DomOp;\n target: string;\n parent?: string;\n detail?: string;\n}\n\n/**\n * The page-side probe.\n *\n * Written against `globalThis` rather than the DOM globals because this file\n * is compiled with the Node lib only — and because everything it touches has\n * to be defensive anyway: it runs at document start in someone else's app,\n * where any of it may be missing, patched or about to be torn down.\n */\nconst DOM_PROBE = (config: ProbeConfig): void => {\n const g = globalThis as any;\n // Main frame only.\n if (g.top && g.top !== g) return;\n // The probe can be asked for twice on one document (installed on a page that\n // is already open, then re-run by the init script); a second MutationObserver\n // would report every mutation twice.\n const installed = config.binding + \"_observing\";\n if (g[installed]) return;\n g[installed] = true;\n const send = g[config.binding];\n const doc = g.document;\n if (typeof send !== \"function\" || !doc || typeof g.MutationObserver !== \"function\") return;\n\n const SKIP_TAGS = [\"script\", \"link\", \"meta\", \"title\", \"base\", \"noscript\", \"template\", \"head\"];\n const MAX_DESC = 48;\n\n let queue: unknown[] = [];\n let scheduled = false;\n let budget = config.max_records;\n\n const flush = (): void => {\n scheduled = false;\n if (queue.length === 0) return;\n const batch = queue;\n queue = [];\n try {\n const result = send(batch);\n if (result && typeof result.catch === \"function\") result.catch(() => {});\n } catch {\n // The page is being torn down; there is nowhere left to push to.\n }\n };\n\n const push = (record: unknown): void => {\n if (budget <= 0) return;\n budget--;\n if (queue.length >= config.max_batch) flush();\n queue.push(record);\n if (!scheduled) {\n scheduled = true;\n g.setTimeout(flush, config.flush_ms);\n }\n };\n\n try {\n g.addEventListener(\"pagehide\", flush, true);\n } catch {\n // Not fatal: records wait for the timer instead.\n }\n\n const desc = (node: any): string => {\n if (!node) return \"?\";\n const type = node.nodeType;\n if (type === 9) return \"#document\";\n if (type === 11) return \"#fragment\";\n if (type === 3) return \"#text\";\n if (type !== 1) return \"#node\";\n let out = String(node.tagName || \"?\").toLowerCase();\n if (node.id) out += \"#\" + String(node.id);\n else if (node.classList && node.classList.length) out += \".\" + String(node.classList[0]);\n return out.length > MAX_DESC ? out.slice(0, MAX_DESC) + \"…\" : out;\n };\n\n /** Head content is noise (see the file comment); so is anything inside it. */\n const inHead = (node: any): boolean => {\n const head = doc.head;\n if (!head || !node) return false;\n if (node === head) return true;\n try {\n return head.contains(node) === true;\n } catch {\n return false;\n }\n };\n\n /** Nodes whose appearance or removal says nothing about what the page looks like. */\n const ignored = (node: any): boolean => {\n if (!node) return true;\n const type = node.nodeType;\n if (type === 3) return String(node.nodeValue || \"\").trim() === \"\";\n if (type !== 1) return true;\n return SKIP_TAGS.indexOf(String(node.tagName || \"\").toLowerCase()) !== -1;\n };\n\n /**\n * Containers whose *contents* are not worth reporting either. Without this,\n * parsing an inline <script> reports the arrival of its source text as a\n * change to the page.\n */\n const ignoredContainer = (node: any): boolean => {\n if (!node || node.nodeType !== 1) return false;\n return SKIP_TAGS.indexOf(String(node.tagName || \"\").toLowerCase()) !== -1;\n };\n\n const record = (op: string, target: string, extra?: Record<string, unknown>): void => {\n push({ t: Date.now(), op, target, ...extra });\n };\n\n /** A text node changing is really its parent element's text changing. */\n const noteChildren = (nodes: any, op: string, parent: any): void => {\n const count = nodes ? nodes.length : 0;\n for (let i = 0; i < count; i++) {\n const node = nodes[i];\n if (ignored(node)) continue;\n if (node.nodeType === 3) record(\"t\", desc(parent));\n else record(op, desc(node), { parent: desc(parent) });\n }\n };\n\n try {\n new g.MutationObserver((records: any[]) => {\n for (const mutation of records) {\n const target = mutation.target;\n if (inHead(target) || ignoredContainer(target)) continue;\n if (mutation.type === \"childList\") {\n noteChildren(mutation.addedNodes, \"+\", target);\n noteChildren(mutation.removedNodes, \"-\", target);\n } else if (mutation.type === \"attributes\") {\n record(\"~\", desc(target), { detail: String(mutation.attributeName || \"\") });\n } else {\n // characterData: the text of the node's parent element changed.\n // Whitespace edits are the parser reflowing indentation, not content.\n const parent = target ? target.parentNode : null;\n if (String(target && target.nodeValue ? target.nodeValue : \"\").trim() === \"\") continue;\n if (ignoredContainer(parent) || inHead(parent)) continue;\n record(\"t\", desc(parent));\n }\n }\n }).observe(doc, { subtree: true, childList: true, attributes: true, characterData: true });\n } catch {\n // No observer, no DOM layer. The capture is still worth having.\n }\n};\n\nexport class DomCollector {\n readonly #page: Page;\n readonly #limit: number;\n readonly #records: RawDomRecord[] = [];\n #dropped = 0;\n\n constructor(page: Page, limit: number = MAX_DOM_RECORDS) {\n this.#page = page;\n this.#limit = Math.max(1, limit);\n }\n\n /**\n * Install the probe. Call before the page navigates, or pass\n * `{ runNow: true }` to also watch the document that is already loaded.\n */\n async attach(options: InstallOptions = {}): Promise<this> {\n const config = probeConfig(BINDING);\n await installProbe<RawDomRecord>(this.#page, config, DOM_PROBE, (batch) => this.#ingest(batch), options);\n return this;\n }\n\n /** Mutations the cap refused. */\n get dropped(): number {\n return this.#dropped;\n }\n\n /** Forget everything collected so far. See `BoundedLog.clear`. */\n clear(): void {\n this.#records.length = 0;\n this.#dropped = 0;\n }\n\n /**\n * Collected mutations in time order, rebased onto the recording clock\n * (`origin` is the recording's start in epoch ms). Mutations from before the\n * recording started keep their negative timestamp — they are the page\n * building itself, and belong on the first card.\n */\n records(origin: number): DomRecord[] {\n return this.#records.map((record) => ({\n timestamp_ms: Math.round(record.t - origin),\n op: record.op,\n target: record.target,\n ...(record.parent !== undefined ? { parent: record.parent } : {}),\n ...(record.detail !== undefined ? { detail: record.detail } : {}),\n }));\n }\n\n #ingest(batch: RawDomRecord[]): void {\n for (const record of batch) {\n // The page pushes this, so nothing about it is trusted.\n if (!record || typeof record.t !== \"number\" || typeof record.target !== \"string\") continue;\n if (this.#records.length >= this.#limit) {\n this.#dropped++;\n continue;\n }\n this.#records.push(record);\n }\n }\n}\n\n/**\n * Turn one card's mutations into a few readable lines.\n *\n * Identical mutations are collapsed with a count, in first-seen order: an\n * animation driven by an inline style produces one `~ #logo [style] ×24` line\n * rather than 24 identical ones, and the order still tells the story of what\n * happened first. Returns undefined when there is nothing to say.\n */\nexport function renderDomChanges(records: DomRecord[], maxLines: number = MAX_DOM_LINES_PER_CARD): string | undefined {\n if (records.length === 0) return undefined;\n\n const groups = new Map<string, { line: string; count: number }>();\n for (const record of records) {\n const line = describeRecord(record);\n const existing = groups.get(line);\n if (existing) existing.count++;\n else groups.set(line, { line, count: 1 });\n }\n\n const all = [...groups.values()];\n const shown = all.slice(0, Math.max(1, maxLines));\n const lines = shown.map((group) => (group.count > 1 ? ` ${group.line} ×${group.count}` : ` ${group.line}`));\n if (all.length > shown.length) {\n const hidden = all.slice(shown.length).reduce((sum, group) => sum + group.count, 0);\n lines.push(` … and ${hidden} more change${hidden === 1 ? \"\" : \"s\"} across ${all.length - shown.length} elements`);\n }\n return lines.join(\"\\n\");\n}\n\nfunction describeRecord(record: DomRecord): string {\n switch (record.op) {\n case \"+\":\n return record.parent ? `+ ${record.target} in ${record.parent}` : `+ ${record.target}`;\n case \"-\":\n return record.parent ? `- ${record.target} from ${record.parent}` : `- ${record.target}`;\n case \"~\":\n return `~ ${record.target} [${record.detail ?? \"?\"}]`;\n default:\n return `~ text in ${record.target}`;\n }\n}\n"]}

package/dist/engine/layers/index.d.ts ADDED Viewed

@@ -0,0 +1,95 @@
+import type { Page } from "playwright";
+import type { ConsoleEntry, DiffCard, NetworkEvent } from "../../types.js";
+import { type DomRecord } from "./dom.js";
+import { type PerfSample } from "./performance.js";
+export { ConsoleCollector, describePageError, normaliseText, toConsoleLevel } from "./console.js";
+export { SessionLayers, layersFor } from "./session.js";
+export { NetworkCollector, shortenUrl } from "./network.js";
+export { DomCollector, renderDomChanges } from "./dom.js";
+export { PerformanceCollector, summarisePerformance } from "./performance.js";
+export type { ConsoleRecord } from "./console.js";
+export type { NetworkRecord } from "./network.js";
+export type { DomOp, DomRecord, RawDomRecord } from "./dom.js";
+export type { PerfKind, PerfSample, RawPerfRecord } from "./performance.js";
+/**
+ * Context layers.
+ *
+ * Four collectors watch a page while it is recorded — what it logged, what it
+ * fetched, what it changed in the DOM, and when it painted — and their output
+ * is then split across the diff cards by time, so each card carries the
+ * context for the interval that produced it.
+ *
+ * All four are attached before the page navigates, because the most valuable
+ * things they see (a script that throws on load, the request that never comes
+ * back, first paint) happen before frame 0 exists. Records from that window
+ * carry negative timestamps and land on the first card.
+ *
+ * Nothing here can fail a capture. A layer that cannot be installed is
+ * reported as a note and the recording goes ahead without it: frames are the
+ * point, and context is the bonus.
+ */
+/** Which layers to collect. Mirrors the `include_*` inputs of framewatch_capture. */
+export interface LayerFlags {
+    console: boolean;
+    network: boolean;
+    dom: boolean;
+    performance: boolean;
+}
+/** Everything the layers gathered, rebased onto the recording clock. */
+export interface CapturedContext {
+    console?: ConsoleEntry[];
+    network?: NetworkEvent[];
+    dom?: DomRecord[];
+    performance?: PerfSample[];
+    /** Anything the user should know about the collection itself (caps hit, layers unavailable). */
+    notes: string[];
+}
+/** Layers attached to a live page, waiting to be drained. */
+export interface AttachedLayers {
+    /**
+     * Take everything collected so far and rebase it onto the recording clock.
+     * `origin` is the recording's start in epoch ms. Purely synchronous and
+     * never touches the page, so it still works after the page has frozen,
+     * navigated away, crashed or been closed.
+     */
+    collect(origin: number): CapturedContext;
+    /** Stop listening. Safe to call more than once. */
+    detach(): void;
+}
+/**
+ * Attach the requested layers to `page`. Call before navigating.
+ *
+ * The two injected layers (DOM, performance) can genuinely fail to install —
+ * a page can be closed underneath us, and `exposeBinding` refuses a name that
+ * is already taken — so each is attached independently and a failure becomes a
+ * note rather than an exception.
+ */
+export declare function attachLayers(page: Page, flags: LayerFlags): Promise<AttachedLayers>;
+/**
+ * Hang the collected context off the cards it belongs to.
+ *
+ * Each card owns the half-open interval ending at its own timestamp: card N
+ * gets everything after card N-1 and up to and including card N — "since the
+ * last frame", which is what the context is for. The first card also absorbs
+ * everything from before the recording started (page load), and the last card
+ * absorbs anything that arrived after the final frame, so nothing collected is
+ * silently thrown away.
+ *
+ * Mutates `cards` in place.
+ */
+export declare function applyContext(cards: DiffCard[], context: CapturedContext): void;
+/**
+ * Lines about the collection itself, for a tool's summary.
+ *
+ * The first is a tally of every layer that ran, including the ones that saw
+ * nothing: silence after `include_network: true` is otherwise ambiguous — it
+ * could mean the page made no requests or that the layer never installed — and
+ * that difference is exactly what someone reading the result needs to know.
+ * Anything a layer had to drop follows on its own line.
+ *
+ * `cardCount` is how many cards the context could be hung off. Zero means the
+ * page produced no frames at all, and that is precisely when the console is
+ * worth reading: a page that died before its first screenshot usually said
+ * why, so its errors are carried up into the summary.
+ */
+export declare function summariseContext(context: CapturedContext, cardCount: number): string[] | undefined;

package/dist/engine/layers/index.js ADDED Viewed

@@ -0,0 +1,184 @@
+import { MAX_DOM_LINES_PER_CARD } from "../../constants.js";
+import { ConsoleCollector } from "./console.js";
+import { DomCollector, renderDomChanges } from "./dom.js";
+import { NetworkCollector } from "./network.js";
+import { PerformanceCollector, summarisePerformance } from "./performance.js";
+export { ConsoleCollector, describePageError, normaliseText, toConsoleLevel } from "./console.js";
+export { SessionLayers, layersFor } from "./session.js";
+export { NetworkCollector, shortenUrl } from "./network.js";
+export { DomCollector, renderDomChanges } from "./dom.js";
+export { PerformanceCollector, summarisePerformance } from "./performance.js";
+const EMPTY = { collect: () => ({ notes: [] }), detach: () => { } };
+/**
+ * Attach the requested layers to `page`. Call before navigating.
+ *
+ * The two injected layers (DOM, performance) can genuinely fail to install —
+ * a page can be closed underneath us, and `exposeBinding` refuses a name that
+ * is already taken — so each is attached independently and a failure becomes a
+ * note rather than an exception.
+ */
+export async function attachLayers(page, flags) {
+    if (!flags.console && !flags.network && !flags.dom && !flags.performance)
+        return EMPTY;
+    const notes = [];
+    const consoleCollector = flags.console ? new ConsoleCollector(page).attach() : null;
+    const networkCollector = flags.network ? new NetworkCollector(page).attach() : null;
+    const domCollector = flags.dom ? await attachOrNote(new DomCollector(page), "DOM", notes) : null;
+    const perfCollector = flags.performance ? await attachOrNote(new PerformanceCollector(page), "performance", notes) : null;
+    return {
+        collect(origin) {
+            const context = { notes: [...notes] };
+            if (consoleCollector) {
+                context.console = consoleCollector.entries(origin);
+                if (consoleCollector.dropped > 0) {
+                    context.notes.push(`Console output was capped — ${consoleCollector.dropped} entries dropped (errors kept first).`);
+                }
+            }
+            if (networkCollector) {
+                // Requests still in flight are events in their own right (see
+                // `NetworkCollector.events`), so the caller can count them from the
+                // list; there is no separate note for them.
+                context.network = networkCollector.events(origin);
+                if (networkCollector.dropped > 0) {
+                    context.notes.push(`Network log was capped — ${networkCollector.dropped} events dropped (failures kept first).`);
+                }
+            }
+            if (domCollector) {
+                context.dom = domCollector.records(origin);
+                if (domCollector.dropped > 0) {
+                    context.notes.push(`DOM log was capped — ${domCollector.dropped} mutations dropped.`);
+                }
+            }
+            if (perfCollector) {
+                context.performance = perfCollector.samples(origin);
+                if (perfCollector.dropped > 0) {
+                    context.notes.push(`Performance log was capped — ${perfCollector.dropped} entries dropped.`);
+                }
+            }
+            return context;
+        },
+        detach() {
+            consoleCollector?.detach();
+            networkCollector?.detach();
+        },
+    };
+}
+async function attachOrNote(collector, name, notes) {
+    try {
+        return await collector.attach();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
+        notes.push(`The ${name} layer could not be installed: ${reason}`);
+        return null;
+    }
+}
+/**
+ * Hang the collected context off the cards it belongs to.
+ *
+ * Each card owns the half-open interval ending at its own timestamp: card N
+ * gets everything after card N-1 and up to and including card N — "since the
+ * last frame", which is what the context is for. The first card also absorbs
+ * everything from before the recording started (page load), and the last card
+ * absorbs anything that arrived after the final frame, so nothing collected is
+ * silently thrown away.
+ *
+ * Mutates `cards` in place.
+ */
+export function applyContext(cards, context) {
+    if (cards.length === 0)
+        return;
+    if (context.console) {
+        assign(cards, context.console, (card, entries) => {
+            if (entries.length > 0)
+                card.console_entries = entries;
+        });
+    }
+    if (context.network) {
+        assign(cards, context.network, (card, events) => {
+            if (events.length > 0)
+                card.network_events = events;
+        });
+    }
+    if (context.dom) {
+        assign(cards, context.dom, (card, records) => {
+            const snapshot = renderDomChanges(records, MAX_DOM_LINES_PER_CARD);
+            if (snapshot !== undefined)
+                card.dom_snapshot = snapshot;
+        });
+    }
+    if (context.performance) {
+        assign(cards, context.performance, (card, samples) => {
+            const info = summarisePerformance(samples);
+            if (info !== undefined)
+                card.performance = info;
+        });
+    }
+}
+/** Bucket `items` by card (see `applyContext`) and hand each card its own. */
+function assign(cards, items, attach) {
+    const buckets = cards.map(() => []);
+    const last = cards.length - 1;
+    for (const item of items) {
+        // Items are already in time order, but a card boundary search is cheap and
+        // does not depend on that holding for every layer.
+        let index = cards.findIndex((card) => item.timestamp_ms <= card.timestamp_ms);
+        if (index === -1)
+            index = last;
+        buckets[index].push(item);
+    }
+    for (let i = 0; i < cards.length; i++) {
+        attach(cards[i], buckets[i]);
+    }
+}
+/**
+ * Lines about the collection itself, for a tool's summary.
+ *
+ * The first is a tally of every layer that ran, including the ones that saw
+ * nothing: silence after `include_network: true` is otherwise ambiguous — it
+ * could mean the page made no requests or that the layer never installed — and
+ * that difference is exactly what someone reading the result needs to know.
+ * Anything a layer had to drop follows on its own line.
+ *
+ * `cardCount` is how many cards the context could be hung off. Zero means the
+ * page produced no frames at all, and that is precisely when the console is
+ * worth reading: a page that died before its first screenshot usually said
+ * why, so its errors are carried up into the summary.
+ */
+export function summariseContext(context, cardCount) {
+    const parts = [];
+    if (context.console) {
+        parts.push(context.console.length > 0 ? `console: ${count(context.console.length, "entry", "entries")}` : "console: silent");
+    }
+    if (context.network) {
+        const pending = context.network.filter((event) => event.error === "pending").length;
+        const settled = context.network.length - pending;
+        const text = settled > 0 ? `network: ${count(settled, "request", "requests")}` : "network: no requests";
+        parts.push(pending > 0 ? `${text} (${pending} still pending)` : text);
+    }
+    if (context.dom) {
+        parts.push(context.dom.length > 0 ? `DOM: ${count(context.dom.length, "mutation", "mutations")}` : "DOM: no mutations");
+    }
+    if (context.performance) {
+        parts.push(context.performance.length > 0
+            ? `performance: ${count(context.performance.length, "entry", "entries")}`
+            : "performance: nothing measured");
+    }
+    const notes = parts.length > 0 ? [`Context — ${parts.join("; ")}`, ...context.notes] : [...context.notes];
+    if (cardCount === 0) {
+        const errors = (context.console ?? []).filter((entry) => entry.level === "error");
+        for (const entry of errors.slice(0, MAX_ORPHANED_ERRORS)) {
+            notes.push(`  [error] ${entry.text}`);
+        }
+        if (errors.length > MAX_ORPHANED_ERRORS) {
+            notes.push(`  … and ${errors.length - MAX_ORPHANED_ERRORS} more errors`);
+        }
+    }
+    return notes.length > 0 ? notes : undefined;
+}
+/** Console errors reported in the summary when a capture produced no frames at all. */
+const MAX_ORPHANED_ERRORS = 5;
+function count(n, singular, plural) {
+    return `${n} ${n === 1 ? singular : plural}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/engine/layers/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/layers/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from \"playwright\";\nimport { MAX_DOM_LINES_PER_CARD } from \"../../constants.js\";\nimport type { ConsoleEntry, DiffCard, NetworkEvent } from \"../../types.js\";\nimport { ConsoleCollector } from \"./console.js\";\nimport { DomCollector, renderDomChanges, type DomRecord } from \"./dom.js\";\nimport { NetworkCollector } from \"./network.js\";\nimport { PerformanceCollector, summarisePerformance, type PerfSample } from \"./performance.js\";\n\nexport { ConsoleCollector, describePageError, normaliseText, toConsoleLevel } from \"./console.js\";\nexport { SessionLayers, layersFor } from \"./session.js\";\nexport { NetworkCollector, shortenUrl } from \"./network.js\";\nexport { DomCollector, renderDomChanges } from \"./dom.js\";\nexport { PerformanceCollector, summarisePerformance } from \"./performance.js\";\nexport type { ConsoleRecord } from \"./console.js\";\nexport type { NetworkRecord } from \"./network.js\";\nexport type { DomOp, DomRecord, RawDomRecord } from \"./dom.js\";\nexport type { PerfKind, PerfSample, RawPerfRecord } from \"./performance.js\";\n\n/**\n * Context layers.\n *\n * Four collectors watch a page while it is recorded — what it logged, what it\n * fetched, what it changed in the DOM, and when it painted — and their output\n * is then split across the diff cards by time, so each card carries the\n * context for the interval that produced it.\n *\n * All four are attached before the page navigates, because the most valuable\n * things they see (a script that throws on load, the request that never comes\n * back, first paint) happen before frame 0 exists. Records from that window\n * carry negative timestamps and land on the first card.\n *\n * Nothing here can fail a capture. A layer that cannot be installed is\n * reported as a note and the recording goes ahead without it: frames are the\n * point, and context is the bonus.\n */\n\n/** Which layers to collect. Mirrors the `include_*` inputs of framewatch_capture. */\nexport interface LayerFlags {\n console: boolean;\n network: boolean;\n dom: boolean;\n performance: boolean;\n}\n\n/** Everything the layers gathered, rebased onto the recording clock. */\nexport interface CapturedContext {\n console?: ConsoleEntry[];\n network?: NetworkEvent[];\n dom?: DomRecord[];\n performance?: PerfSample[];\n /** Anything the user should know about the collection itself (caps hit, layers unavailable). */\n notes: string[];\n}\n\n/** Layers attached to a live page, waiting to be drained. */\nexport interface AttachedLayers {\n /**\n * Take everything collected so far and rebase it onto the recording clock.\n * `origin` is the recording's start in epoch ms. Purely synchronous and\n * never touches the page, so it still works after the page has frozen,\n * navigated away, crashed or been closed.\n */\n collect(origin: number): CapturedContext;\n /** Stop listening. Safe to call more than once. */\n detach(): void;\n}\n\nconst EMPTY: AttachedLayers = { collect: () => ({ notes: [] }), detach: () => {} };\n\n/**\n * Attach the requested layers to `page`. Call before navigating.\n *\n * The two injected layers (DOM, performance) can genuinely fail to install —\n * a page can be closed underneath us, and `exposeBinding` refuses a name that\n * is already taken — so each is attached independently and a failure becomes a\n * note rather than an exception.\n */\nexport async function attachLayers(page: Page, flags: LayerFlags): Promise<AttachedLayers> {\n if (!flags.console && !flags.network && !flags.dom && !flags.performance) return EMPTY;\n\n const notes: string[] = [];\n const consoleCollector = flags.console ? new ConsoleCollector(page).attach() : null;\n const networkCollector = flags.network ? new NetworkCollector(page).attach() : null;\n\n const domCollector = flags.dom ? await attachOrNote(new DomCollector(page), \"DOM\", notes) : null;\n const perfCollector = flags.performance ? await attachOrNote(new PerformanceCollector(page), \"performance\", notes) : null;\n\n return {\n collect(origin: number): CapturedContext {\n const context: CapturedContext = { notes: [...notes] };\n\n if (consoleCollector) {\n context.console = consoleCollector.entries(origin);\n if (consoleCollector.dropped > 0) {\n context.notes.push(`Console output was capped — ${consoleCollector.dropped} entries dropped (errors kept first).`);\n }\n }\n if (networkCollector) {\n // Requests still in flight are events in their own right (see\n // `NetworkCollector.events`), so the caller can count them from the\n // list; there is no separate note for them.\n context.network = networkCollector.events(origin);\n if (networkCollector.dropped > 0) {\n context.notes.push(`Network log was capped — ${networkCollector.dropped} events dropped (failures kept first).`);\n }\n }\n if (domCollector) {\n context.dom = domCollector.records(origin);\n if (domCollector.dropped > 0) {\n context.notes.push(`DOM log was capped — ${domCollector.dropped} mutations dropped.`);\n }\n }\n if (perfCollector) {\n context.performance = perfCollector.samples(origin);\n if (perfCollector.dropped > 0) {\n context.notes.push(`Performance log was capped — ${perfCollector.dropped} entries dropped.`);\n }\n }\n return context;\n },\n detach(): void {\n consoleCollector?.detach();\n networkCollector?.detach();\n },\n };\n}\n\nasync function attachOrNote<T extends { attach(): Promise<T> }>(collector: T, name: string, notes: string[]): Promise<T | null> {\n try {\n return await collector.attach();\n } catch (error) {\n const reason = error instanceof Error ? error.message.split(\"\\n\")[0] : String(error);\n notes.push(`The ${name} layer could not be installed: ${reason}`);\n return null;\n }\n}\n\n/**\n * Hang the collected context off the cards it belongs to.\n *\n * Each card owns the half-open interval ending at its own timestamp: card N\n * gets everything after card N-1 and up to and including card N — \"since the\n * last frame\", which is what the context is for. The first card also absorbs\n * everything from before the recording started (page load), and the last card\n * absorbs anything that arrived after the final frame, so nothing collected is\n * silently thrown away.\n *\n * Mutates `cards` in place.\n */\nexport function applyContext(cards: DiffCard[], context: CapturedContext): void {\n if (cards.length === 0) return;\n\n if (context.console) {\n assign(cards, context.console, (card, entries) => {\n if (entries.length > 0) card.console_entries = entries;\n });\n }\n if (context.network) {\n assign(cards, context.network, (card, events) => {\n if (events.length > 0) card.network_events = events;\n });\n }\n if (context.dom) {\n assign(cards, context.dom, (card, records) => {\n const snapshot = renderDomChanges(records, MAX_DOM_LINES_PER_CARD);\n if (snapshot !== undefined) card.dom_snapshot = snapshot;\n });\n }\n if (context.performance) {\n assign(cards, context.performance, (card, samples) => {\n const info = summarisePerformance(samples);\n if (info !== undefined) card.performance = info;\n });\n }\n}\n\n/** Bucket `items` by card (see `applyContext`) and hand each card its own. */\nfunction assign<T extends { timestamp_ms: number }>(\n cards: DiffCard[],\n items: T[],\n attach: (card: DiffCard, items: T[]) => void,\n): void {\n const buckets: T[][] = cards.map(() => []);\n const last = cards.length - 1;\n\n for (const item of items) {\n // Items are already in time order, but a card boundary search is cheap and\n // does not depend on that holding for every layer.\n let index = cards.findIndex((card) => item.timestamp_ms <= card.timestamp_ms);\n if (index === -1) index = last;\n buckets[index].push(item);\n }\n\n for (let i = 0; i < cards.length; i++) {\n attach(cards[i], buckets[i]);\n }\n}\n\n/**\n * Lines about the collection itself, for a tool's summary.\n *\n * The first is a tally of every layer that ran, including the ones that saw\n * nothing: silence after `include_network: true` is otherwise ambiguous — it\n * could mean the page made no requests or that the layer never installed — and\n * that difference is exactly what someone reading the result needs to know.\n * Anything a layer had to drop follows on its own line.\n *\n * `cardCount` is how many cards the context could be hung off. Zero means the\n * page produced no frames at all, and that is precisely when the console is\n * worth reading: a page that died before its first screenshot usually said\n * why, so its errors are carried up into the summary.\n */\nexport function summariseContext(context: CapturedContext, cardCount: number): string[] | undefined {\n const parts: string[] = [];\n if (context.console) {\n parts.push(context.console.length > 0 ? `console: ${count(context.console.length, \"entry\", \"entries\")}` : \"console: silent\");\n }\n if (context.network) {\n const pending = context.network.filter((event) => event.error === \"pending\").length;\n const settled = context.network.length - pending;\n const text = settled > 0 ? `network: ${count(settled, \"request\", \"requests\")}` : \"network: no requests\";\n parts.push(pending > 0 ? `${text} (${pending} still pending)` : text);\n }\n if (context.dom) {\n parts.push(context.dom.length > 0 ? `DOM: ${count(context.dom.length, \"mutation\", \"mutations\")}` : \"DOM: no mutations\");\n }\n if (context.performance) {\n parts.push(\n context.performance.length > 0\n ? `performance: ${count(context.performance.length, \"entry\", \"entries\")}`\n : \"performance: nothing measured\",\n );\n }\n\n const notes = parts.length > 0 ? [`Context — ${parts.join(\"; \")}`, ...context.notes] : [...context.notes];\n\n if (cardCount === 0) {\n const errors = (context.console ?? []).filter((entry) => entry.level === \"error\");\n for (const entry of errors.slice(0, MAX_ORPHANED_ERRORS)) {\n notes.push(` [error] ${entry.text}`);\n }\n if (errors.length > MAX_ORPHANED_ERRORS) {\n notes.push(` … and ${errors.length - MAX_ORPHANED_ERRORS} more errors`);\n }\n }\n\n return notes.length > 0 ? notes : undefined;\n}\n\n/** Console errors reported in the summary when a capture produced no frames at all. */\nconst MAX_ORPHANED_ERRORS = 5;\n\nfunction count(n: number, singular: string, plural: string): string {\n return `${n} ${n === 1 ? singular : plural}`;\n}\n"]}