@pasko70/pibo 1.9.9 → 1.9.10

package/dist/debug/web-artifacts.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getPiboHome } from "../core/pibo-home.js";
+const STDOUT_BUDGET = 12_000;
+export async function writeLastSnapshot(snapshot) {
+    if (!snapshot)
+        return;
+    const file = lastSnapshotPath();
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(snapshot, null, 2), "utf-8");
+}
+export async function readBaselineSnapshot(file) {
+    const target = file ?? lastSnapshotPath();
+    let text;
+    try {
+        text = await readFile(target, "utf-8");
+    }
+    catch {
+        throw new Error(`Baseline snapshot not found at ${target}. Run pibo debug web snapshot first or pass --from <artifact>.`);
+    }
+    const parsed = JSON.parse(text);
+    if (isSnapshot(parsed))
+        return parsed;
+    if (isRecord(parsed) && isSnapshot(parsed.snapshot))
+        return parsed.snapshot;
+    if (isRecord(parsed) && isSnapshot(parsed.current))
+        return parsed.current;
+    throw new Error(`File is not a web render snapshot: ${target}`);
+}
+export async function writeArtifact(kind, payload) {
+    return writeTextArtifact(kind, "json", JSON.stringify(payload, null, 2));
+}
+export async function writeTextArtifact(kind, extension, content) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const dir = path.join(getPiboHome(), "debug", "web-render", stamp);
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${kind}.${extension}`);
+    await writeFile(file, content, "utf-8");
+    return file;
+}
+export async function writeReportOutput(outputPath, content) {
+    const file = path.resolve(outputPath);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, content, "utf-8");
+    return file;
+}
+export function compactTarget(target) {
+    return { id: target.id, url: target.url, title: target.title, webSocketDebuggerUrl: target.webSocketDebuggerUrl };
+}
+export function limitStdout(value) {
+    if (value.length <= STDOUT_BUDGET)
+        return value;
+    return `${value.slice(0, STDOUT_BUDGET)}\n... truncated ${value.length - STDOUT_BUDGET} chars by stdout budget ...`;
+}
+function lastSnapshotPath() {
+    return path.join(getPiboHome(), "debug", "web-render", "last-snapshot.json");
+}
+function isSnapshot(value) {
+    return isRecord(value) && value.kind === "snapshot" && typeof value.scope === "string" && Array.isArray(value.nodes);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/debug/web-options.js

@@ -0,0 +1,313 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export const DEFAULT_WATCH_DURATION_MS = 5_000;
+export const MAX_WATCH_DURATION_MS = 30_000;
+export const DEFAULT_NODE_LIMIT = 250;
+export const DEFAULT_DEPTH_LIMIT = 8;
+export const DEFAULT_EVENT_LIMIT = 500;
+export const DEFAULT_TEXT_LIMIT = 80;
+const BATCH_NEGATIVE_EXPECTED_REGRESSIONS = ["positive DOM updates", "DOM max jump", "SSE text events per chunk", "live pipeline flush/enqueue", "live pipeline overlay updates/flushed"];
+const OVERLAY_DROP_NEGATIVE_EXPECTED_REGRESSIONS = ["positive DOM updates", "live pipeline flushed events/overlay expected", "live pipeline overlay events/input expected", "live pipeline current text/expected", "live pipeline flush/enqueue", "live pipeline overlay updates/flushed"];
+export function parseOptions(args) {
+    const options = {
+        positionals: [],
+        json: false,
+        artifact: false,
+        fixture: false,
+        backendFixture: false,
+        simulateReconnect: false,
+        simulateTraceCatchup: false,
+        simulateOverlayDrop: false,
+        assertHealthy: false,
+        expectedRegressionPatterns: [],
+        providerSelectedSession: false,
+        compareHosted: false,
+        compareHostedIfConfigured: false,
+        act: false,
+        manual: false,
+        includeText: false,
+        includeLayout: false,
+        compact: false,
+    };
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--json")
+            options.json = true;
+        else if (arg === "--artifact")
+            options.artifact = true;
+        else if (arg === "--fixture")
+            options.fixture = true;
+        else if (arg === "--backend-fixture")
+            options.backendFixture = true;
+        else if (arg === "--simulate-reconnect")
+            options.simulateReconnect = true;
+        else if (arg === "--simulate-trace-catchup")
+            options.simulateTraceCatchup = true;
+        else if (arg === "--assert")
+            options.assertHealthy = true;
+        else if (arg === "--expect-regression")
+            options.expectedRegressionPatterns.push(requireValue(args, ++index, arg));
+        else if (arg.startsWith("--expect-regression="))
+            options.expectedRegressionPatterns.push(arg.slice("--expect-regression=".length));
+        else if (arg === "--act")
+            options.act = true;
+        else if (arg === "--manual")
+            options.manual = true;
+        else if (arg === "--include-text")
+            options.includeText = true;
+        else if (arg === "--include-layout")
+            options.includeLayout = true;
+        else if (arg === "--compact")
+            options.compact = true;
+        else if (arg === "--output")
+            options.output = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--output="))
+            options.output = arg.slice("--output=".length);
+        else if (arg === "--json-output")
+            options.jsonOutput = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--json-output="))
+            options.jsonOutput = arg.slice("--json-output=".length);
+        else if (arg === "--cdp-url")
+            options.cdpUrl = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--cdp-url="))
+            options.cdpUrl = arg.slice("--cdp-url=".length);
+        else if (arg === "--target")
+            options.target = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--target="))
+            options.target = arg.slice("--target=".length);
+        else if (arg === "--scope")
+            options.scope = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--scope="))
+            options.scope = arg.slice("--scope=".length);
+        else if (arg === "--preset")
+            options.preset = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--preset="))
+            options.preset = arg.slice("--preset=".length);
+        else if (arg === "--duration")
+            options.duration = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--duration="))
+            options.duration = arg.slice("--duration=".length);
+        else if (arg === "--runs")
+            options.runs = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--runs="))
+            options.runs = arg.slice("--runs=".length);
+        else if (arg === "--fixture-profile")
+            options.fixtureProfile = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--fixture-profile="))
+            options.fixtureProfile = arg.slice("--fixture-profile=".length);
+        else if (arg === "--fixture-mix")
+            options.fixtureMix = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--fixture-mix="))
+            options.fixtureMix = arg.slice("--fixture-mix=".length);
+        else if (arg === "--fixture-prelude-messages")
+            options.fixturePreludeMessages = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--fixture-prelude-messages="))
+            options.fixturePreludeMessages = arg.slice("--fixture-prelude-messages=".length);
+        else if (arg === "--negative-profile")
+            options.negativeProfile = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--negative-profile="))
+            options.negativeProfile = arg.slice("--negative-profile=".length);
+        else if (arg === "--compare-url")
+            options.compareUrl = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--compare-url="))
+            options.compareUrl = arg.slice("--compare-url=".length);
+        else if (arg === "--provider-request-id")
+            options.providerRequestId = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--provider-request-id="))
+            options.providerRequestId = arg.slice("--provider-request-id=".length);
+        else if (arg === "--provider-session-id")
+            options.providerSessionId = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--provider-session-id="))
+            options.providerSessionId = arg.slice("--provider-session-id=".length);
+        else if (arg === "--provider-turn-id")
+            options.providerTurnId = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--provider-turn-id="))
+            options.providerTurnId = arg.slice("--provider-turn-id=".length);
+        else if (arg === "--provider-selected-session")
+            options.providerSelectedSession = true;
+        else if (arg === "--compare-hosted")
+            options.compareHosted = true;
+        else if (arg === "--compare-hosted-if-configured")
+            options.compareHostedIfConfigured = true;
+        else if (arg === "--from")
+            options.from = requireValue(args, ++index, arg);
+        else if (arg.startsWith("--from="))
+            options.from = arg.slice("--from=".length);
+        else
+            options.positionals.push(arg);
+    }
+    return options;
+}
+function requireValue(args, index, flag) {
+    const value = args[index];
+    if (!value)
+        throw new Error(`${flag} requires a value`);
+    return value;
+}
+export function resolveScope(options) {
+    if (options.scope)
+        return options.scope;
+    if (options.preset)
+        return presetScope(options.preset);
+    throw new Error("Missing --scope or --preset. Try --preset session-list, chat-shell, composer, or app.");
+}
+export function presetScope(preset) {
+    switch (preset) {
+        case "app": return "[data-pibo-debug=\"chat-app\"]";
+        case "route-shell": return "[data-pibo-debug=\"route-shell\"]";
+        case "sidebar": return "[data-pibo-debug=\"sidebar-shell\"]";
+        case "session-list": return "[data-pibo-debug=\"session-list\"]";
+        case "chat-shell": return "[data-pibo-debug=\"chat-shell\"]";
+        case "composer": return "[data-pibo-debug=\"composer\"]";
+        default: throw new Error(`Unknown web render preset "${preset}". Use app, route-shell, sidebar, session-list, chat-shell, or composer.`);
+    }
+}
+export function parseDuration(value) {
+    if (!value)
+        return DEFAULT_WATCH_DURATION_MS;
+    const duration = Number(value);
+    if (!Number.isFinite(duration) || duration <= 0)
+        throw new Error("--duration must be a positive number of milliseconds");
+    if (duration > MAX_WATCH_DURATION_MS)
+        throw new Error(`--duration must be <= ${MAX_WATCH_DURATION_MS}ms`);
+    return Math.round(duration);
+}
+export function parseRuns(value) {
+    if (!value)
+        return 1;
+    const runs = Number(value);
+    if (!Number.isInteger(runs) || runs <= 0)
+        throw new Error("--runs must be a positive integer");
+    if (runs > 10)
+        throw new Error("--runs must be <= 10");
+    return runs;
+}
+export function parseFixtureProfile(value) {
+    if (!value)
+        return "steady";
+    if (value === "steady" || value === "jitter" || value === "burst" || value === "batch")
+        return value;
+    throw new Error("--fixture-profile must be steady, jitter, burst, or batch");
+}
+export function parseFixtureMix(value) {
+    if (!value)
+        return "text";
+    if (value === "text" || value === "reasoning-text" || value === "markdown" || value === "gfm-markdown" || value === "gfm-task-markdown" || value === "gfm-full-markdown")
+        return value;
+    throw new Error("--fixture-mix must be text, reasoning-text, markdown, gfm-markdown, gfm-task-markdown, or gfm-full-markdown");
+}
+export function parseFixturePreludeMessages(value) {
+    if (!value)
+        return 0;
+    const count = Number(value);
+    if (!Number.isInteger(count) || count < 0)
+        throw new Error("--fixture-prelude-messages must be a non-negative integer");
+    if (count > 2000)
+        throw new Error("--fixture-prelude-messages must be <= 2000");
+    return count;
+}
+export function parseNegativeProfile(value) {
+    if (!value)
+        return undefined;
+    if (value === "batch" || value === "overlay-drop")
+        return value;
+    throw new Error("--negative-profile must be batch or overlay-drop");
+}
+export function applyNegativeStreamingProfile(options, profile) {
+    const conflictingFlags = [];
+    if (options.fixture)
+        conflictingFlags.push("--fixture");
+    if (options.backendFixture)
+        conflictingFlags.push("--backend-fixture");
+    if (options.fixtureProfile)
+        conflictingFlags.push("--fixture-profile");
+    if (options.fixtureMix)
+        conflictingFlags.push("--fixture-mix");
+    if (options.fixturePreludeMessages)
+        conflictingFlags.push("--fixture-prelude-messages");
+    if (options.simulateReconnect)
+        conflictingFlags.push("--simulate-reconnect");
+    if (options.simulateTraceCatchup)
+        conflictingFlags.push("--simulate-trace-catchup");
+    if (options.simulateOverlayDrop)
+        conflictingFlags.push("--simulate-overlay-drop");
+    if (options.expectedRegressionPatterns.length > 0)
+        conflictingFlags.push("--expect-regression");
+    if (conflictingFlags.length > 0)
+        throw new Error(`--negative-profile ${profile} already selects fixture settings and expected regressions; remove ${conflictingFlags.join(", ")}`);
+    return {
+        ...options,
+        backendFixture: true,
+        fixtureProfile: profile === "batch" ? "batch" : "steady",
+        fixtureMix: "reasoning-text",
+        simulateOverlayDrop: profile === "overlay-drop",
+        assertHealthy: true,
+        expectedRegressionPatterns: profile === "batch" ? [...BATCH_NEGATIVE_EXPECTED_REGRESSIONS] : [...OVERLAY_DROP_NEGATIVE_EXPECTED_REGRESSIONS],
+    };
+}
+export function resolveStreamingBenchmarkCompareUrl(rawCompareUrl, primaryUrl) {
+    const primary = new URL(primaryUrl);
+    const compare = new URL(rawCompareUrl, primary);
+    const comparePath = compare.pathname.replace(/\/+$/, "");
+    const primaryPath = primary.pathname.replace(/\/+$/, "");
+    if ((comparePath === "" || comparePath === "/apps/chat") && primaryPath.startsWith("/apps/chat/")) {
+        compare.pathname = primary.pathname;
+        compare.search = primary.search;
+    }
+    compare.searchParams.set("debugStreaming", "1");
+    return compare.toString();
+}
+export async function resolveStreamingBenchmarkHostedCompareUrl(options = {}) {
+    const hostedUrl = resolveStreamingBenchmarkHostedCompareUrlFromValues(process.env, await readDeveloperHostEnvFile());
+    if (hostedUrl || options.optional)
+        return hostedUrl;
+    throw new Error("--compare-hosted requires PIBO_DEV_PUBLIC_URL or PIBO_DEV_BASE_URL in the environment or .env.developer-host");
+}
+export function resolveStreamingBenchmarkHostedCompareUrlFromValues(env, envFile) {
+    const directUrl = env.PIBO_DEV_PUBLIC_URL?.trim();
+    if (directUrl)
+        return directUrl;
+    const baseUrl = env.PIBO_DEV_BASE_URL?.trim();
+    if (baseUrl)
+        return `${baseUrl.replace(/\/+$/, "")}/apps/chat`;
+    const fileDirectUrl = envFile.PIBO_DEV_PUBLIC_URL?.trim();
+    if (fileDirectUrl)
+        return fileDirectUrl;
+    const fileBaseUrl = envFile.PIBO_DEV_BASE_URL?.trim();
+    if (fileBaseUrl)
+        return `${fileBaseUrl.replace(/\/+$/, "")}/apps/chat`;
+    return undefined;
+}
+async function readDeveloperHostEnvFile() {
+    try {
+        return parseSimpleEnvFile(await readFile(path.resolve(process.cwd(), ".env.developer-host"), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+function parseSimpleEnvFile(text) {
+    const values = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const assignment = line.startsWith("export ") ? line.slice("export ".length).trimStart() : line;
+        const equals = assignment.indexOf("=");
+        if (equals <= 0)
+            continue;
+        const key = assignment.slice(0, equals).trim();
+        if (key !== "PIBO_DEV_PUBLIC_URL" && key !== "PIBO_DEV_BASE_URL")
+            continue;
+        values[key] = stripEnvQuotes(assignment.slice(equals + 1).trim());
+    }
+    return values;
+}
+function stripEnvQuotes(value) {
+    if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}

package/dist/debug/web-render-analysis.js

@@ -0,0 +1,310 @@
+export function formatSnapshot(snapshot, target) {
+    const lines = [
+        `# Web Render Snapshot`,
+        `# target: ${target.id} ${target.url || snapshot.url}`,
+        `# scope: ${snapshot.scope}`,
+    ];
+    if (!snapshot.rootFound) {
+        lines.push("root: not found");
+        return lines.join("\n");
+    }
+    for (const node of snapshot.nodes)
+        lines.push(formatNodeLine(node));
+    lines.push(`Summary: ${snapshot.nodes.length} nodes, omitted=${snapshot.omitted.nodes}, depth_omitted=${snapshot.omitted.depth}`);
+    return lines.join("\n");
+}
+function formatNodeLine(node) {
+    const indent = "  ".repeat(Math.min(node.depth, 8));
+    const parts = [`${indent}${node.ref}`, node.identityKind === "path" ? `${node.identity} unstable` : node.identity, `<${node.tag}>`];
+    if (node.role)
+        parts.push(`role=${node.role}`);
+    if (node.name)
+        parts.push(`name=${JSON.stringify(node.name)}`);
+    if (node.attributes["data-pibo-session-id"])
+        parts.push(`session=${node.attributes["data-pibo-session-id"]}`);
+    if (node.attributes["data-pibo-selected"])
+        parts.push(`selected=${node.attributes["data-pibo-selected"]}`);
+    if (node.attributes["data-pibo-state"])
+        parts.push(`state=${node.attributes["data-pibo-state"]}`);
+    if (node.classSummary)
+        parts.push(`class=${JSON.stringify(node.classSummary)}`);
+    if (node.text && !node.name)
+        parts.push(`text=${JSON.stringify(node.text)}`);
+    if (node.focused)
+        parts.push("focused=true");
+    if (node.box)
+        parts.push(`box=${node.box.x},${node.box.y},${node.box.w},${node.box.h}`);
+    return parts.join(" ");
+}
+export function diffSnapshots(before, after) {
+    const beforeMap = new Map(before.nodes.map((node) => [node.identity, node]));
+    const afterMap = new Map(after.nodes.map((node) => [node.identity, node]));
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const node of after.nodes)
+        if (!beforeMap.has(node.identity))
+            added.push(node);
+    for (const node of before.nodes)
+        if (!afterMap.has(node.identity))
+            removed.push(node);
+    for (const [identity, beforeNode] of beforeMap) {
+        const afterNode = afterMap.get(identity);
+        if (!afterNode)
+            continue;
+        const changes = nodeChanges(beforeNode, afterNode);
+        if (changes.length)
+            changed.push({ before: beforeNode, after: afterNode, changes });
+    }
+    const suspectedFlickers = inferSnapshotFlickers(removed, added);
+    return { added, removed, changed, suspectedFlickers };
+}
+function nodeChanges(before, after) {
+    const changes = [];
+    if (before.name !== after.name)
+        changes.push(`name ${jsonShort(before.name)} -> ${jsonShort(after.name)}`);
+    if (before.text !== after.text)
+        changes.push(`text ${jsonShort(before.text)} -> ${jsonShort(after.text)}`);
+    if (before.classSummary !== after.classSummary)
+        changes.push(`class ${jsonShort(before.classSummary)} -> ${jsonShort(after.classSummary)}`);
+    for (const key of new Set([...Object.keys(before.attributes), ...Object.keys(after.attributes)])) {
+        if (before.attributes[key] !== after.attributes[key])
+            changes.push(`${key} ${jsonShort(before.attributes[key])} -> ${jsonShort(after.attributes[key])}`);
+    }
+    if (before.box && after.box) {
+        const moved = Math.abs(before.box.x - after.box.x) + Math.abs(before.box.y - after.box.y);
+        const resized = Math.abs(before.box.w - after.box.w) + Math.abs(before.box.h - after.box.h);
+        if (moved > 2 || resized > 2)
+            changes.push(`box ${before.box.x},${before.box.y},${before.box.w},${before.box.h} -> ${after.box.x},${after.box.y},${after.box.w},${after.box.h}`);
+    }
+    return changes;
+}
+function inferSnapshotFlickers(removed, added) {
+    const flickers = [];
+    for (const oldNode of removed) {
+        const match = bestLogicalMatch(oldNode, added);
+        if (match && match.score >= 55) {
+            flickers.push(`remount-like ${oldNode.identity} -> ${match.node.identity} reason=${match.reason}`);
+        }
+    }
+    return flickers.slice(0, 20);
+}
+export function formatSnapshotDiff(diff, before, after, target) {
+    const lines = [
+        `# Web Render Diff`,
+        `# target: ${target.id} ${target.url || after.url}`,
+        `# scope: ${after.scope}`,
+        `# baseline: ${before.createdAt}`,
+        `# current: ${after.createdAt}`,
+    ];
+    for (const node of diff.removed)
+        lines.push(`- ${node.identity} ${describeNode(node)}`);
+    for (const node of diff.added)
+        lines.push(`+ ${node.identity} ${describeNode(node)}`);
+    for (const item of diff.changed)
+        lines.push(`~ ${item.after.identity} ${item.changes.join("; ")}`);
+    if (diff.suspectedFlickers.length) {
+        lines.push("", "Suspected flicker:");
+        for (const flicker of diff.suspectedFlickers)
+            lines.push(`- ${flicker}`);
+    }
+    lines.push(``, `Summary: ${diff.added.length} adds, ${diff.removed.length} removals, ${diff.changed.length} updates, ${diff.suspectedFlickers.length} suspected flickers`);
+    return lines.join("\n");
+}
+export function formatWatch(watch, target, label = "watch") {
+    const lines = [
+        `# Web Render Watch: ${label}, ${(watch.durationMs / 1000).toFixed(1)}s`,
+        `# target: ${target.id} ${target.url || watch.url}`,
+        `# scope: ${watch.scope}`,
+    ];
+    if (!watch.rootFound) {
+        lines.push("root: not found");
+        return lines.join("\n");
+    }
+    if (watch.action) {
+        lines.push(`# action: ${watch.action.requested} performed=${watch.action.performed}${watch.action.error ? ` error=${watch.action.error}` : ""}`);
+    }
+    const snapshotDelta = watch.before && watch.after ? diffSnapshots(watch.before, watch.after) : undefined;
+    const hasSnapshotDelta = snapshotDelta ? hasSnapshotDiff(snapshotDelta) : false;
+    if (!watch.events.length && hasSnapshotDelta) {
+        lines.push("no mutation events captured; final snapshot differs:");
+        lines.push(...formatCompactSnapshotDelta(snapshotDelta));
+    }
+    else if (!watch.events.length) {
+        lines.push("no changes");
+    }
+    for (const event of watch.events) {
+        lines.push(formatWatchEvent(event));
+    }
+    const flickers = inferWatchFlickers(watch.events);
+    if (flickers.length) {
+        lines.push("", "Suspected flicker:");
+        for (const flicker of flickers)
+            lines.push(`- ${flicker}`);
+    }
+    const counts = countEvents(watch.events);
+    lines.push("", `Summary: ${counts.added} adds, ${counts.removed} removals, ${counts.attr} attr updates, ${counts.text} text updates, ${counts.focus} focus, ${counts.route} route, ${flickers.length} suspected flickers, omitted=${watch.omitted.events}`);
+    return lines.join("\n");
+}
+function formatWatchEvent(event) {
+    const t = String(event.t).padStart(4, "0");
+    if (event.source === "dom" && event.kind === "attr")
+        return `${t}ms dom ~ ${event.target ?? "?"} ${event.detail}: ${jsonShort(event.before)} -> ${jsonShort(event.after)}`;
+    if (event.source === "dom" && event.kind === "text")
+        return `${t}ms dom ~ ${event.target ?? "?"} text: ${jsonShort(event.before)} -> ${jsonShort(event.after)}`;
+    if (event.source === "dom" && event.kind === "added")
+        return `${t}ms dom + ${event.target ?? "?"} ${event.node ? describeNode(event.node) : ""}`;
+    if (event.source === "dom" && event.kind === "removed")
+        return `${t}ms dom - ${event.target ?? "?"} ${event.node ? describeNode(event.node) : ""}`;
+    if (event.source === "focus")
+        return `${t}ms focus ${event.kind} ${event.target ?? "?"}`;
+    if (event.source === "route")
+        return `${t}ms route ${event.kind} ${event.before ? `${event.before} -> ` : ""}${event.after ?? ""}`;
+    if (event.source === "action")
+        return `${t}ms action ${event.kind} ${event.detail ?? ""} ${event.target ?? ""}`;
+    return `${t}ms ${event.source} ${event.kind} ${event.target ?? ""}`;
+}
+function hasSnapshotDiff(diff) {
+    return Boolean(diff.added.length || diff.removed.length || diff.changed.length);
+}
+function formatCompactSnapshotDelta(diff, limit = 8) {
+    const lines = [];
+    for (const node of diff.removed)
+        lines.push(`  - ${node.identity} ${describeNode(node)}`);
+    for (const node of diff.added)
+        lines.push(`  + ${node.identity} ${describeNode(node)}`);
+    for (const item of diff.changed)
+        lines.push(`  ~ ${item.after.identity} ${item.changes.join("; ")}`);
+    if (lines.length > limit)
+        return [...lines.slice(0, limit), `  … ${lines.length - limit} more snapshot changes`];
+    return lines;
+}
+export function inferWatchFlickers(events) {
+    const flickers = [];
+    const removals = events.filter((event) => event.kind === "removed" && event.node);
+    const additions = events.filter((event) => event.kind === "added" && event.node);
+    for (const added of additions) {
+        const addedNode = added.node;
+        const removal = removals.find((removed) => removed.t >= added.t && removed.t - added.t <= 500 && removed.node && sameStableNode(addedNode, removed.node));
+        if (removal?.node)
+            flickers.push(`transient node within ${removal.t - added.t}ms: ${addedNode.identity} added then removed`);
+    }
+    for (const removed of removals) {
+        const removedNode = removed.node;
+        const candidates = additions.filter((added) => added.t >= removed.t && added.t - removed.t <= 500 && added.node);
+        const match = bestLogicalMatch(removedNode, candidates.map((candidate) => candidate.node));
+        if (match && match.score >= 55) {
+            const event = candidates.find((candidate) => candidate.node === match.node);
+            if (event)
+                flickers.push(`remove/add within ${event.t - removed.t}ms: ${removedNode.identity} -> ${match.node.identity} reason=${match.reason}`);
+        }
+    }
+    const attrRollbacks = new Map();
+    for (const event of events) {
+        if (event.kind !== "attr" || !event.target || !event.detail)
+            continue;
+        const key = `${event.target}:${event.detail}`;
+        attrRollbacks.set(key, [...(attrRollbacks.get(key) ?? []), event]);
+    }
+    for (const [key, entries] of attrRollbacks) {
+        for (let i = 1; i < entries.length; i++) {
+            if (entries[i - 1].before === entries[i].after && entries[i].t - entries[i - 1].t <= 500) {
+                flickers.push(`attribute rollback within ${entries[i].t - entries[i - 1].t}ms: ${key}`);
+                break;
+            }
+        }
+    }
+    return [...new Set(flickers)].slice(0, 20);
+}
+function sameStableNode(left, right) {
+    if (left.identity === right.identity)
+        return true;
+    const leftSession = attrText(left, "data-pibo-session-id");
+    const rightSession = attrText(right, "data-pibo-session-id");
+    return Boolean(leftSession && leftSession === rightSession);
+}
+function bestLogicalMatch(node, candidates) {
+    let best;
+    for (const candidate of candidates) {
+        const match = logicalMatchScore(node, candidate);
+        if (!best || match.score > best.score)
+            best = { node: candidate, ...match };
+    }
+    return best && best.score > 0 ? best : undefined;
+}
+function logicalMatchScore(left, right) {
+    if (left.identity === right.identity)
+        return { score: 100, reason: "same-identity" };
+    const leftSession = attrText(left, "data-pibo-session-id");
+    const rightSession = attrText(right, "data-pibo-session-id");
+    if (leftSession && rightSession && leftSession === rightSession)
+        return { score: 90, reason: "same-session-id" };
+    const reasons = [];
+    let score = 0;
+    const leftDebug = attrText(left, "data-pibo-debug");
+    const rightDebug = attrText(right, "data-pibo-debug");
+    if (leftDebug || rightDebug) {
+        if (leftDebug !== rightDebug)
+            return { score: 0, reason: "different-debug-anchor" };
+        score += 45;
+        reasons.push("same-debug-anchor");
+    }
+    if (left.tag === right.tag) {
+        score += 10;
+        reasons.push("same-tag");
+    }
+    if (left.path && left.path === right.path) {
+        score += 25;
+        reasons.push("same-path");
+    }
+    if (left.role && left.role === right.role) {
+        score += 10;
+        reasons.push("same-role");
+    }
+    const differentSessionIds = Boolean(leftSession && rightSession && leftSession !== rightSession);
+    if (!differentSessionIds) {
+        if (left.name && left.name === right.name) {
+            score += 15;
+            reasons.push("same-name");
+        }
+        if (left.text && left.text === right.text) {
+            score += 10;
+            reasons.push("same-text");
+        }
+    }
+    return { score, reason: reasons.join("+") || "weak-match" };
+}
+function attrText(node, key) {
+    const value = node.attributes[key];
+    return typeof value === "string" && value.length ? value : undefined;
+}
+function countEvents(events) {
+    return {
+        added: events.filter((event) => event.kind === "added").length,
+        removed: events.filter((event) => event.kind === "removed").length,
+        attr: events.filter((event) => event.kind === "attr").length,
+        text: events.filter((event) => event.kind === "text").length,
+        focus: events.filter((event) => event.source === "focus").length,
+        route: events.filter((event) => event.source === "route").length,
+    };
+}
+function describeNode(node) {
+    const parts = [`<${node.tag}>`];
+    if (node.role)
+        parts.push(`role=${node.role}`);
+    if (node.name)
+        parts.push(`name=${JSON.stringify(node.name)}`);
+    if (node.text && !node.name)
+        parts.push(`text=${JSON.stringify(node.text)}`);
+    if (node.attributes["data-pibo-session-id"])
+        parts.push(`session=${node.attributes["data-pibo-session-id"]}`);
+    if (node.attributes["data-pibo-selected"])
+        parts.push(`selected=${node.attributes["data-pibo-selected"]}`);
+    if (node.classSummary)
+        parts.push(`class=${JSON.stringify(node.classSummary)}`);
+    return parts.join(" ");
+}
+function jsonShort(value) {
+    const text = JSON.stringify(value);
+    return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}