framewatch-mcp-server 0.1.0

package/dist/utils/bounded-log.js

@@ -0,0 +1,78 @@
+/**
+ * A fixed-size log that gives priority to interesting entries.
+ *
+ * The context layers watch things a page can produce without limit — console
+ * output, network requests — so every collector needs a cap. A plain cap has
+ * the wrong failure mode: a page that logs in a render loop fills the budget
+ * with noise in the first second, and the console error thrown at second four
+ * (the one thing worth capturing) is dropped.
+ *
+ * So the log keeps `limit` entries, and once it is full an *important* entry
+ * still gets in by evicting the oldest unimportant one. Important entries are
+ * only ever dropped when the log holds nothing but important entries — at
+ * which point the page is genuinely producing more signal than the cap allows.
+ * `dropped` counts everything that did not make it, so the caller can say so.
+ */
+export class BoundedLog {
+    #limit;
+    #isImportant;
+    #items = [];
+    #dropped = 0;
+    /**
+     * @param limit Maximum entries kept. Values below 1 are treated as 1.
+     * @param isImportant Entries worth evicting an ordinary entry for. Defaults to "nothing is".
+     */
+    constructor(limit, isImportant = () => false) {
+        this.#limit = Math.max(1, Math.floor(limit));
+        this.#isImportant = isImportant;
+    }
+    /** Entries kept, oldest first. */
+    get items() {
+        return this.#items;
+    }
+    get size() {
+        return this.#items.length;
+    }
+    /** How many entries were refused or evicted. */
+    get dropped() {
+        return this.#dropped;
+    }
+    add(item) {
+        if (this.#items.length < this.#limit) {
+            this.#items.push(item);
+            return;
+        }
+        if (!this.#isImportant(item)) {
+            this.#dropped++;
+            return;
+        }
+        const victim = this.#items.findIndex((existing) => !this.#isImportant(existing));
+        if (victim === -1) {
+            // Nothing but important entries left; the newest is the one we lose, so
+            // the record of how the trouble *started* survives.
+            this.#dropped++;
+            return;
+        }
+        this.#items.splice(victim, 1);
+        this.#items.push(item);
+        this.#dropped++;
+    }
+    /**
+     * Forget everything, including the dropped count.
+     *
+     * A capture builds a log and throws it away, but `framewatch_interact` keeps
+     * one page — and so one set of collectors — alive across many calls, and
+     * each call reports only what its own action caused. Without this, call
+     * twenty would repeat the console output of calls one to nineteen and then
+     * start dropping the entries that actually mattered.
+     */
+    clear() {
+        this.#items = [];
+        this.#dropped = 0;
+    }
+    /** A plain copy of the entries (safe to hand out and mutate). */
+    toArray() {
+        return [...this.#items];
+    }
+}
+//# sourceMappingURL=bounded-log.js.map

package/dist/utils/bounded-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-log.js","sourceRoot":"","sources":["../../src/utils/bounded-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,UAAU;IACZ,MAAM,CAAS;IACf,YAAY,CAAuB;IAC5C,MAAM,GAAQ,EAAE,CAAC;IACjB,QAAQ,GAAG,CAAC,CAAC;IAEb;;;OAGG;IACH,YAAY,KAAa,EAAE,cAAoC,GAAG,EAAE,CAAC,KAAK;QACxE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;IAClC,CAAC;IAED,kCAAkC;IAClC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,gDAAgD;IAChD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,GAAG,CAAC,IAAO;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACrC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;QACjF,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,wEAAwE;YACxE,oDAAoD;YACpD,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,iEAAiE;IACjE,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;CACF","sourcesContent":["/**\n * A fixed-size log that gives priority to interesting entries.\n *\n * The context layers watch things a page can produce without limit — console\n * output, network requests — so every collector needs a cap. A plain cap has\n * the wrong failure mode: a page that logs in a render loop fills the budget\n * with noise in the first second, and the console error thrown at second four\n * (the one thing worth capturing) is dropped.\n *\n * So the log keeps `limit` entries, and once it is full an *important* entry\n * still gets in by evicting the oldest unimportant one. Important entries are\n * only ever dropped when the log holds nothing but important entries — at\n * which point the page is genuinely producing more signal than the cap allows.\n * `dropped` counts everything that did not make it, so the caller can say so.\n */\nexport class BoundedLog<T> {\n  readonly #limit: number;\n  readonly #isImportant: (item: T) => boolean;\n  #items: T[] = [];\n  #dropped = 0;\n\n  /**\n   * @param limit Maximum entries kept. Values below 1 are treated as 1.\n   * @param isImportant Entries worth evicting an ordinary entry for. Defaults to \"nothing is\".\n   */\n  constructor(limit: number, isImportant: (item: T) => boolean = () => false) {\n    this.#limit = Math.max(1, Math.floor(limit));\n    this.#isImportant = isImportant;\n  }\n\n  /** Entries kept, oldest first. */\n  get items(): readonly T[] {\n    return this.#items;\n  }\n\n  get size(): number {\n    return this.#items.length;\n  }\n\n  /** How many entries were refused or evicted. */\n  get dropped(): number {\n    return this.#dropped;\n  }\n\n  add(item: T): void {\n    if (this.#items.length < this.#limit) {\n      this.#items.push(item);\n      return;\n    }\n    if (!this.#isImportant(item)) {\n      this.#dropped++;\n      return;\n    }\n    const victim = this.#items.findIndex((existing) => !this.#isImportant(existing));\n    if (victim === -1) {\n      // Nothing but important entries left; the newest is the one we lose, so\n      // the record of how the trouble *started* survives.\n      this.#dropped++;\n      return;\n    }\n    this.#items.splice(victim, 1);\n    this.#items.push(item);\n    this.#dropped++;\n  }\n\n  /**\n   * Forget everything, including the dropped count.\n   *\n   * A capture builds a log and throws it away, but `framewatch_interact` keeps\n   * one page — and so one set of collectors — alive across many calls, and\n   * each call reports only what its own action caused. Without this, call\n   * twenty would repeat the console output of calls one to nineteen and then\n   * start dropping the entries that actually mattered.\n   */\n  clear(): void {\n    this.#items = [];\n    this.#dropped = 0;\n  }\n\n  /** A plain copy of the entries (safe to hand out and mutate). */\n  toArray(): T[] {\n    return [...this.#items];\n  }\n}\n"]}

package/dist/utils/format.d.ts

@@ -0,0 +1,56 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { DiffCard } from "../types.js";
+/** What became of a replayed interaction script. */
+export interface InteractionReport {
+    /** Steps in the script. */
+    total: number;
+    /** Steps that ran successfully. */
+    completed: number;
+    /** One-line description of each completed step, in order. */
+    steps: string[];
+    /** Message from the step that failed, if any (already a single line). */
+    error?: string;
+    /** 1-based position of the failing step. */
+    failed_index?: number;
+}
+/** Everything the formatter needs to describe one capture session. */
+export interface CaptureSummary {
+    cards: DiffCard[];
+    total_frames: number;
+    duration_ms: number;
+    /** URL that was requested. */
+    url: string;
+    /** URL the page ended on (after redirects / in-page navigation). */
+    final_url?: string;
+    title?: string;
+    /** Frames dropped by the recorder (screenshot failures). */
+    dropped?: number;
+    /** Present only when an interaction script was replayed. */
+    interactions?: InteractionReport;
+    /**
+     * Remarks about the capture itself rather than about any one frame — a
+     * context layer that hit its cap, requests still in flight when the
+     * recording ended. One line each, after the summary.
+     */
+    notes?: string[];
+}
+/**
+ * Build the MCP CallToolResult for a capture, following the "MCP Response
+ * Format" in CLAUDE.md: one summary text block, then per card an image block,
+ * a metadata text block and (when present) the change-region crop image.
+ */
+export declare function formatDiffCards(summary: CaptureSummary): CallToolResult;
+/**
+ * How the interaction script went: how many steps ran, what they were, and —
+ * when one failed — which one and why. A failed step is a finding about the
+ * page, not a tool failure, so it is reported here alongside the frames rather
+ * than replacing them with an error.
+ */
+export declare function formatInteractionLine(report: InteractionReport): string;
+/**
+ * The metadata text block for one card (exported for tests and for reuse by
+ * the interact tool). Line 1 is always `Frame N @ Tms [trigger]`; the
+ * optional sections follow in a fixed order — Changed, Console, Network,
+ * Performance, DOM — and are omitted entirely when their data is absent.
+ */
+export declare function formatCardMeta(card: DiffCard): string;

package/dist/utils/format.js

@@ -0,0 +1,130 @@
+/**
+ * Build the MCP CallToolResult for a capture, following the "MCP Response
+ * Format" in CLAUDE.md: one summary text block, then per card an image block,
+ * a metadata text block and (when present) the change-region crop image.
+ */
+export function formatDiffCards(summary) {
+    const lines = [formatSummaryLine(summary)];
+    if (summary.interactions) {
+        lines.push(formatInteractionLine(summary.interactions));
+    }
+    for (const note of summary.notes ?? []) {
+        lines.push(note);
+    }
+    const content = [{ type: "text", text: lines.join("\n") }];
+    for (const card of summary.cards) {
+        content.push({ type: "image", data: card.full_frame, mimeType: "image/png" });
+        content.push({ type: "text", text: formatCardMeta(card) });
+        if (card.change_region?.crop) {
+            content.push({ type: "image", data: card.change_region.crop, mimeType: "image/png" });
+        }
+    }
+    return { content };
+}
+/**
+ * One-line description of the whole capture. Always names the requested url;
+ * appends the final url only when the page ended somewhere else, the page
+ * title when known, and the dropped-frame count only when frames were lost.
+ */
+function formatSummaryLine(summary) {
+    const { cards, total_frames, duration_ms, url, final_url, title, dropped } = summary;
+    const recording = `from ${total_frames} raw frames (${duration_ms}ms recording) of ${url}`;
+    let text = cards.length === 0 ? `No frames captured ${recording}` : `Captured ${cards.length} meaningful frames ${recording}`;
+    if (final_url !== undefined && !isSameUrl(url, final_url)) {
+        text += ` → ${final_url}`;
+    }
+    if (title) {
+        text += ` — "${title}"`;
+    }
+    if (dropped !== undefined && dropped > 0) {
+        text += ` (${dropped} frames dropped)`;
+    }
+    return text;
+}
+/**
+ * How the interaction script went: how many steps ran, what they were, and —
+ * when one failed — which one and why. A failed step is a finding about the
+ * page, not a tool failure, so it is reported here alongside the frames rather
+ * than replacing them with an error.
+ */
+export function formatInteractionLine(report) {
+    let text = `Interactions: ${report.completed}/${report.total} replayed`;
+    if (report.steps.length > 0) {
+        text += ` — ${report.steps.join(", ")}`;
+    }
+    if (report.error !== undefined) {
+        text += `. Step ${report.failed_index ?? report.completed + 1}: ${report.error}`;
+    }
+    return text;
+}
+/**
+ * Compare two URLs as URLs, not as strings: `page.url()` returns the
+ * WHATWG-normalised form, so a request for `http://localhost:3000` comes back
+ * as `http://localhost:3000/` without anything having navigated.
+ */
+function isSameUrl(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return new URL(a).href === new URL(b).href;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The metadata text block for one card (exported for tests and for reuse by
+ * the interact tool). Line 1 is always `Frame N @ Tms [trigger]`; the
+ * optional sections follow in a fixed order — Changed, Console, Network,
+ * Performance, DOM — and are omitted entirely when their data is absent.
+ */
+export function formatCardMeta(card) {
+    const lines = [`Frame ${card.index} @ ${card.timestamp_ms}ms [${card.trigger}]`];
+    const region = card.change_region;
+    if (region) {
+        if (region.change_percent === 0) {
+            lines.push("Changed: 0.0% — no visual change since previous frame");
+        }
+        else {
+            const { bbox } = region;
+            let changed = `Changed: ${region.change_percent.toFixed(1)}% — region: ${bbox.x},${bbox.y} ${bbox.width}x${bbox.height}`;
+            if (!region.crop) {
+                changed += " (full-frame change, see frame image)";
+            }
+            lines.push(changed);
+        }
+    }
+    if (card.console_entries?.length) {
+        lines.push("Console:");
+        for (const entry of card.console_entries) {
+            lines.push(`  [${entry.level}] ${entry.text}`);
+        }
+    }
+    if (card.network_events?.length) {
+        lines.push("Network:");
+        for (const event of card.network_events) {
+            // A request that never got a response has no status to print; what
+            // stopped it (or that it is still running) is the useful part.
+            const outcome = event.status > 0 ? String(event.status) : (event.error ?? "no response");
+            const why = event.status > 0 && event.error !== undefined ? ` ${event.error}` : "";
+            lines.push(`  ${event.method} ${event.url} → ${outcome}${why} (${event.duration_ms}ms)`);
+        }
+    }
+    const perf = card.performance;
+    if (perf) {
+        lines.push("Performance:");
+        if (perf.paint_time_ms !== undefined)
+            lines.push(`  paint ${perf.paint_time_ms}ms`);
+        if (perf.layout_shifts !== undefined) {
+            const score = perf.layout_shift_score !== undefined ? ` (score ${perf.layout_shift_score})` : "";
+            lines.push(`  layout shifts ${perf.layout_shifts}${score}`);
+        }
+        if (perf.lcp_ms !== undefined)
+            lines.push(`  lcp ${perf.lcp_ms}ms`);
+    }
+    if (card.dom_snapshot) {
+        lines.push(`DOM:\n${card.dom_snapshot}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport type { DiffCard } from \"../types.js\";\n\n/** What became of a replayed interaction script. */\nexport interface InteractionReport {\n  /** Steps in the script. */\n  total: number;\n  /** Steps that ran successfully. */\n  completed: number;\n  /** One-line description of each completed step, in order. */\n  steps: string[];\n  /** Message from the step that failed, if any (already a single line). */\n  error?: string;\n  /** 1-based position of the failing step. */\n  failed_index?: number;\n}\n\n/** Everything the formatter needs to describe one capture session. */\nexport interface CaptureSummary {\n  cards: DiffCard[];\n  total_frames: number;\n  duration_ms: number;\n  /** URL that was requested. */\n  url: string;\n  /** URL the page ended on (after redirects / in-page navigation). */\n  final_url?: string;\n  title?: string;\n  /** Frames dropped by the recorder (screenshot failures). */\n  dropped?: number;\n  /** Present only when an interaction script was replayed. */\n  interactions?: InteractionReport;\n  /**\n   * Remarks about the capture itself rather than about any one frame — a\n   * context layer that hit its cap, requests still in flight when the\n   * recording ended. One line each, after the summary.\n   */\n  notes?: string[];\n}\n\n/**\n * Build the MCP CallToolResult for a capture, following the \"MCP Response\n * Format\" in CLAUDE.md: one summary text block, then per card an image block,\n * a metadata text block and (when present) the change-region crop image.\n */\nexport function formatDiffCards(summary: CaptureSummary): CallToolResult {\n  const lines = [formatSummaryLine(summary)];\n  if (summary.interactions) {\n    lines.push(formatInteractionLine(summary.interactions));\n  }\n  for (const note of summary.notes ?? []) {\n    lines.push(note);\n  }\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n  for (const card of summary.cards) {\n    content.push({ type: \"image\", data: card.full_frame, mimeType: \"image/png\" });\n    content.push({ type: \"text\", text: formatCardMeta(card) });\n    if (card.change_region?.crop) {\n      content.push({ type: \"image\", data: card.change_region.crop, mimeType: \"image/png\" });\n    }\n  }\n  return { content };\n}\n\n/**\n * One-line description of the whole capture. Always names the requested url;\n * appends the final url only when the page ended somewhere else, the page\n * title when known, and the dropped-frame count only when frames were lost.\n */\nfunction formatSummaryLine(summary: CaptureSummary): string {\n  const { cards, total_frames, duration_ms, url, final_url, title, dropped } = summary;\n  const recording = `from ${total_frames} raw frames (${duration_ms}ms recording) of ${url}`;\n  let text = cards.length === 0 ? `No frames captured ${recording}` : `Captured ${cards.length} meaningful frames ${recording}`;\n  if (final_url !== undefined && !isSameUrl(url, final_url)) {\n    text += ` → ${final_url}`;\n  }\n  if (title) {\n    text += ` — \"${title}\"`;\n  }\n  if (dropped !== undefined && dropped > 0) {\n    text += ` (${dropped} frames dropped)`;\n  }\n  return text;\n}\n\n/**\n * How the interaction script went: how many steps ran, what they were, and —\n * when one failed — which one and why. A failed step is a finding about the\n * page, not a tool failure, so it is reported here alongside the frames rather\n * than replacing them with an error.\n */\nexport function formatInteractionLine(report: InteractionReport): string {\n  let text = `Interactions: ${report.completed}/${report.total} replayed`;\n  if (report.steps.length > 0) {\n    text += ` — ${report.steps.join(\", \")}`;\n  }\n  if (report.error !== undefined) {\n    text += `. Step ${report.failed_index ?? report.completed + 1}: ${report.error}`;\n  }\n  return text;\n}\n\n/**\n * Compare two URLs as URLs, not as strings: `page.url()` returns the\n * WHATWG-normalised form, so a request for `http://localhost:3000` comes back\n * as `http://localhost:3000/` without anything having navigated.\n */\nfunction isSameUrl(a: string, b: string): boolean {\n  if (a === b) return true;\n  try {\n    return new URL(a).href === new URL(b).href;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The metadata text block for one card (exported for tests and for reuse by\n * the interact tool). Line 1 is always `Frame N @ Tms [trigger]`; the\n * optional sections follow in a fixed order — Changed, Console, Network,\n * Performance, DOM — and are omitted entirely when their data is absent.\n */\nexport function formatCardMeta(card: DiffCard): string {\n  const lines: string[] = [`Frame ${card.index} @ ${card.timestamp_ms}ms [${card.trigger}]`];\n\n  const region = card.change_region;\n  if (region) {\n    if (region.change_percent === 0) {\n      lines.push(\"Changed: 0.0% — no visual change since previous frame\");\n    } else {\n      const { bbox } = region;\n      let changed = `Changed: ${region.change_percent.toFixed(1)}% — region: ${bbox.x},${bbox.y} ${bbox.width}x${bbox.height}`;\n      if (!region.crop) {\n        changed += \" (full-frame change, see frame image)\";\n      }\n      lines.push(changed);\n    }\n  }\n\n  if (card.console_entries?.length) {\n    lines.push(\"Console:\");\n    for (const entry of card.console_entries) {\n      lines.push(`  [${entry.level}] ${entry.text}`);\n    }\n  }\n\n  if (card.network_events?.length) {\n    lines.push(\"Network:\");\n    for (const event of card.network_events) {\n      // A request that never got a response has no status to print; what\n      // stopped it (or that it is still running) is the useful part.\n      const outcome = event.status > 0 ? String(event.status) : (event.error ?? \"no response\");\n      const why = event.status > 0 && event.error !== undefined ? ` ${event.error}` : \"\";\n      lines.push(`  ${event.method} ${event.url} → ${outcome}${why} (${event.duration_ms}ms)`);\n    }\n  }\n\n  const perf = card.performance;\n  if (perf) {\n    lines.push(\"Performance:\");\n    if (perf.paint_time_ms !== undefined) lines.push(`  paint ${perf.paint_time_ms}ms`);\n    if (perf.layout_shifts !== undefined) {\n      const score = perf.layout_shift_score !== undefined ? ` (score ${perf.layout_shift_score})` : \"\";\n      lines.push(`  layout shifts ${perf.layout_shifts}${score}`);\n    }\n    if (perf.lcp_ms !== undefined) lines.push(`  lcp ${perf.lcp_ms}ms`);\n  }\n\n  if (card.dom_snapshot) {\n    lines.push(`DOM:\\n${card.dom_snapshot}`);\n  }\n\n  return lines.join(\"\\n\");\n}\n"]}

package/dist/utils/image.d.ts

@@ -0,0 +1,44 @@
+import type { BoundingBox } from "../types.js";
+/**
+ * Resize a PNG for delivery to the MCP client: fit within `maxWidth`,
+ * never enlarge, keep aspect ratio, re-encode as PNG.
+ *
+ * `quality` puts sharp into palette mode (libimagequant), which is what keeps
+ * screenshots small — dropping it quadruples the payload on noisy frames. Its
+ * default effort (7) is far too slow for a capture, though: a single noisy
+ * 1280x720 frame costs ~600ms and one capture encodes up to 60 images.
+ * `effort: 1` is ~6x faster for ~15% more bytes.
+ */
+export declare function resizeForOutput(png: Buffer, maxWidth?: number): Promise<Buffer>;
+/** Read the pixel dimensions of an encoded image buffer. */
+export declare function getDimensions(image: Buffer): Promise<{
+    width: number;
+    height: number;
+}>;
+/** Base64-encode a binary buffer (MCP image content blocks expect base64 data). */
+export declare function toBase64(buffer: Buffer): string;
+/**
+ * Resize + grayscale a PNG to DIFF_WIDTH x DIFF_HEIGHT (fit: "fill") and
+ * return raw 1-channel pixels (length DIFF_WIDTH * DIFF_HEIGHT). This is the
+ * low-res representation the smart diff engine compares frames with.
+ */
+export declare function toDiffBuffer(png: Buffer): Promise<Buffer>;
+/** Full-resolution grayscale raw pixels (1 channel) plus dimensions. */
+export declare function toGrayscale(png: Buffer): Promise<{
+    data: Buffer;
+    width: number;
+    height: number;
+}>;
+/** Crop a PNG to `bbox` (must already be clamped to the image) and re-encode as PNG. */
+export declare function cropRegion(png: Buffer, bbox: BoundingBox): Promise<Buffer>;
+/**
+ * Paint `mask` over `png` in OVERLAY_COLOUR and return the result as a PNG.
+ *
+ * This is the compare tool's diff overlay: the second page as it really looks,
+ * with every pixel that differs from the first tinted, so a reviewer can see
+ * *where* the two differ instead of hunting for it. The tint is translucent
+ * (OVERLAY_ALPHA) so what changed stays readable underneath it.
+ *
+ * `mask` must be one byte per pixel, row-major, matching `width` x `height`.
+ */
+export declare function overlayMask(png: Buffer, mask: Uint8Array, width: number, height: number): Promise<Buffer>;

package/dist/utils/image.js

@@ -0,0 +1,81 @@
+import sharp from "sharp";
+import { DIFF_HEIGHT, DIFF_WIDTH, OUTPUT_MAX_WIDTH, OVERLAY_ALPHA, OVERLAY_COLOUR } from "../constants.js";
+/**
+ * Resize a PNG for delivery to the MCP client: fit within `maxWidth`,
+ * never enlarge, keep aspect ratio, re-encode as PNG.
+ *
+ * `quality` puts sharp into palette mode (libimagequant), which is what keeps
+ * screenshots small — dropping it quadruples the payload on noisy frames. Its
+ * default effort (7) is far too slow for a capture, though: a single noisy
+ * 1280x720 frame costs ~600ms and one capture encodes up to 60 images.
+ * `effort: 1` is ~6x faster for ~15% more bytes.
+ */
+export async function resizeForOutput(png, maxWidth = OUTPUT_MAX_WIDTH) {
+    return sharp(png)
+        .resize(maxWidth, null, { fit: "inside", withoutEnlargement: true })
+        .png({ quality: 80, effort: 1, compressionLevel: 6 })
+        .toBuffer();
+}
+/** Read the pixel dimensions of an encoded image buffer. */
+export async function getDimensions(image) {
+    const { width, height } = await sharp(image).metadata();
+    if (width === undefined || height === undefined) {
+        throw new Error("Could not read image dimensions");
+    }
+    return { width, height };
+}
+/** Base64-encode a binary buffer (MCP image content blocks expect base64 data). */
+export function toBase64(buffer) {
+    return buffer.toString("base64");
+}
+/**
+ * Resize + grayscale a PNG to DIFF_WIDTH x DIFF_HEIGHT (fit: "fill") and
+ * return raw 1-channel pixels (length DIFF_WIDTH * DIFF_HEIGHT). This is the
+ * low-res representation the smart diff engine compares frames with.
+ */
+export async function toDiffBuffer(png) {
+    return sharp(png).resize(DIFF_WIDTH, DIFF_HEIGHT, { fit: "fill" }).grayscale().raw().toBuffer();
+}
+/** Full-resolution grayscale raw pixels (1 channel) plus dimensions. */
+export async function toGrayscale(png) {
+    const { data, info } = await sharp(png).grayscale().raw().toBuffer({ resolveWithObject: true });
+    return { data, width: info.width, height: info.height };
+}
+/** Crop a PNG to `bbox` (must already be clamped to the image) and re-encode as PNG. */
+export async function cropRegion(png, bbox) {
+    return sharp(png)
+        .extract({ left: bbox.x, top: bbox.y, width: bbox.width, height: bbox.height })
+        .png()
+        .toBuffer();
+}
+/**
+ * Paint `mask` over `png` in OVERLAY_COLOUR and return the result as a PNG.
+ *
+ * This is the compare tool's diff overlay: the second page as it really looks,
+ * with every pixel that differs from the first tinted, so a reviewer can see
+ * *where* the two differ instead of hunting for it. The tint is translucent
+ * (OVERLAY_ALPHA) so what changed stays readable underneath it.
+ *
+ * `mask` must be one byte per pixel, row-major, matching `width` x `height`.
+ */
+export async function overlayMask(png, mask, width, height) {
+    const pixels = width * height;
+    if (mask.length !== pixels) {
+        throw new Error(`overlayMask: mask length mismatch — expected ${pixels} (${width}x${height}), got ${mask.length}`);
+    }
+    const rgba = Buffer.alloc(pixels * 4);
+    for (let i = 0; i < pixels; i++) {
+        if (mask[i] === 0)
+            continue;
+        const at = i * 4;
+        rgba[at] = OVERLAY_COLOUR.r;
+        rgba[at + 1] = OVERLAY_COLOUR.g;
+        rgba[at + 2] = OVERLAY_COLOUR.b;
+        rgba[at + 3] = OVERLAY_ALPHA;
+    }
+    return sharp(png)
+        .composite([{ input: rgba, raw: { width, height, channels: 4 }, blend: "over" }])
+        .png()
+        .toBuffer();
+}
+//# sourceMappingURL=image.js.map

package/dist/utils/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/utils/image.ts"],"names":[],"mappings":"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","sourcesContent":["import sharp from \"sharp\";\nimport { DIFF_HEIGHT, DIFF_WIDTH, OUTPUT_MAX_WIDTH, OVERLAY_ALPHA, OVERLAY_COLOUR } from \"../constants.js\";\nimport type { BoundingBox } from \"../types.js\";\n\n/**\n * Resize a PNG for delivery to the MCP client: fit within `maxWidth`,\n * never enlarge, keep aspect ratio, re-encode as PNG.\n *\n * `quality` puts sharp into palette mode (libimagequant), which is what keeps\n * screenshots small — dropping it quadruples the payload on noisy frames. Its\n * default effort (7) is far too slow for a capture, though: a single noisy\n * 1280x720 frame costs ~600ms and one capture encodes up to 60 images.\n * `effort: 1` is ~6x faster for ~15% more bytes.\n */\nexport async function resizeForOutput(png: Buffer, maxWidth: number = OUTPUT_MAX_WIDTH): Promise<Buffer> {\n  return sharp(png)\n    .resize(maxWidth, null, { fit: \"inside\", withoutEnlargement: true })\n    .png({ quality: 80, effort: 1, compressionLevel: 6 })\n    .toBuffer();\n}\n\n/** Read the pixel dimensions of an encoded image buffer. */\nexport async function getDimensions(image: Buffer): Promise<{ width: number; height: number }> {\n  const { width, height } = await sharp(image).metadata();\n  if (width === undefined || height === undefined) {\n    throw new Error(\"Could not read image dimensions\");\n  }\n  return { width, height };\n}\n\n/** Base64-encode a binary buffer (MCP image content blocks expect base64 data). */\nexport function toBase64(buffer: Buffer): string {\n  return buffer.toString(\"base64\");\n}\n\n/**\n * Resize + grayscale a PNG to DIFF_WIDTH x DIFF_HEIGHT (fit: \"fill\") and\n * return raw 1-channel pixels (length DIFF_WIDTH * DIFF_HEIGHT). This is the\n * low-res representation the smart diff engine compares frames with.\n */\nexport async function toDiffBuffer(png: Buffer): Promise<Buffer> {\n  return sharp(png).resize(DIFF_WIDTH, DIFF_HEIGHT, { fit: \"fill\" }).grayscale().raw().toBuffer();\n}\n\n/** Full-resolution grayscale raw pixels (1 channel) plus dimensions. */\nexport async function toGrayscale(png: Buffer): Promise<{ data: Buffer; width: number; height: number }> {\n  const { data, info } = await sharp(png).grayscale().raw().toBuffer({ resolveWithObject: true });\n  return { data, width: info.width, height: info.height };\n}\n\n/** Crop a PNG to `bbox` (must already be clamped to the image) and re-encode as PNG. */\nexport async function cropRegion(png: Buffer, bbox: BoundingBox): Promise<Buffer> {\n  return sharp(png)\n    .extract({ left: bbox.x, top: bbox.y, width: bbox.width, height: bbox.height })\n    .png()\n    .toBuffer();\n}\n\n/**\n * Paint `mask` over `png` in OVERLAY_COLOUR and return the result as a PNG.\n *\n * This is the compare tool's diff overlay: the second page as it really looks,\n * with every pixel that differs from the first tinted, so a reviewer can see\n * *where* the two differ instead of hunting for it. The tint is translucent\n * (OVERLAY_ALPHA) so what changed stays readable underneath it.\n *\n * `mask` must be one byte per pixel, row-major, matching `width` x `height`.\n */\nexport async function overlayMask(png: Buffer, mask: Uint8Array, width: number, height: number): Promise<Buffer> {\n  const pixels = width * height;\n  if (mask.length !== pixels) {\n    throw new Error(`overlayMask: mask length mismatch — expected ${pixels} (${width}x${height}), got ${mask.length}`);\n  }\n\n  const rgba = Buffer.alloc(pixels * 4);\n  for (let i = 0; i < pixels; i++) {\n    if (mask[i] === 0) continue;\n    const at = i * 4;\n    rgba[at] = OVERLAY_COLOUR.r;\n    rgba[at + 1] = OVERLAY_COLOUR.g;\n    rgba[at + 2] = OVERLAY_COLOUR.b;\n    rgba[at + 3] = OVERLAY_ALPHA;\n  }\n\n  return sharp(png)\n    .composite([{ input: rgba, raw: { width, height, channels: 4 }, blend: \"over\" }])\n    .png()\n    .toBuffer();\n}\n"]}

package/dist/utils/server-process.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Dev server process manager.
+ *
+ * FrameWatch can start the app it is about to look at. One server runs at a
+ * time — the tools that use it take no server argument, so a second would have
+ * no way of being addressed — and it is owned for as long as the MCP server
+ * lives, then stopped on shutdown. Nothing here is allowed to outlive the
+ * process that spawned it.
+ *
+ * **Readiness is the port, not the log line.** `ready_pattern` is matched and
+ * reported (dev servers print the URL they actually bound to, which is worth
+ * repeating back), but what makes a server "running" is that something answers
+ * on its port: that is the condition the next tool call depends on, and a
+ * pattern that fires early — or a regex that never matches a server that is
+ * working perfectly — would report the wrong thing in both directions.
+ */
+/** A server that is up, with everything worth telling the caller about it. */
+export interface RunningServer {
+    command: string;
+    port: number;
+    pid: number;
+    cwd: string;
+    url: string;
+    /** How long the port took to answer. */
+    ready_ms: number;
+    /** The output line that matched `ready_pattern`, if one did. */
+    ready_line?: string;
+}
+/** What a stopped server left behind. */
+export interface StoppedServer {
+    command: string;
+    port: number;
+    pid: number;
+    uptime_ms: number;
+    /** How it went: exit code, or the signal that ended it. */
+    exit_code: number | null;
+    exit_signal: string | null;
+    /** True when SIGTERM was ignored and the process had to be killed outright. */
+    forced: boolean;
+}
+export interface StartDevServerOptions {
+    command: string;
+    port: number;
+    ready_pattern: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout_ms: number;
+}
+/** A start that failed, carrying the output that explains why. */
+export declare class DevServerError extends Error {
+    readonly output: string[];
+    constructor(message: string, output?: string[]);
+}
+/** The running server, or null. A process that has since died counts as null. */
+export declare function getDevServer(): RunningServer | null;
+/** The last `count` output lines of the running server, oldest first. */
+export declare function devServerOutput(count: number): string[];
+/**
+ * Spawn a dev server and wait until its port answers.
+ *
+ * @throws DevServerError when a server is already running, when the port is
+ * already taken by something else, when the process exits before the port
+ * opens, or when it never opens at all. Each of those carries the output the
+ * server produced, because that is where the reason actually is.
+ */
+export declare function startDevServer(options: StartDevServerOptions): Promise<RunningServer>;
+/**
+ * Stop the running server, or return null if there is none.
+ *
+ * SIGTERM to the whole process group first — dev servers use it to clean up
+ * their own children and their sockets — then SIGKILL if it is still there
+ * after SERVER_STOP_GRACE_MS.
+ */
+export declare function stopDevServer(): Promise<StoppedServer | null>;
+/** Stop the server on the way out. Never throws — shutdown must not be blocked by it. */
+export declare function shutdownDevServer(): Promise<void>;
+/**
+ * True when something accepts a TCP connection on `port`.
+ *
+ * Both loopback addresses are tried: a server bound only to `::1` (Node's
+ * default when the host resolves to IPv6 first) does not answer on 127.0.0.1,
+ * and reporting that as "never started" would be wrong.
+ */
+export declare function isPortOpen(port: number, timeoutMs?: number): Promise<boolean>;