waterplane 0.0.1 → 0.1.6

package/packages/host/dist/capture/capturepass.js

@@ -0,0 +1,262 @@
+/**
+ * One capture run's passes: verify → settle → diff → emit, the frame writer and
+ * the watch loop. Split out of `CaptureManager` (move only): the three private
+ * methods are functions now, and the manager's `canceled` set is handed in.
+ */
+import { writeFileSync, copyFileSync } from "node:fs";
+import { join } from "node:path";
+import { newOutboxPath } from "../files.js";
+import { blankVariance, changedPct, pixelToolReason, pngSize, probePixelTools, BLANK_SD } from "./pixels.js";
+import { DEFAULT_DIFF_PCT, DEFAULT_SETTLE_MS, MAX_SETTLE_MS, MAX_SIDECAR_LINES, WATCH_INTERVAL_MS, WATCH_MAX_FRAMES, WATCH_MAX_MS, sleep, } from "./capturekit.js";
+import { classifyOverlay } from "./captureconfig.js";
+import { diffRecord, shouldEmit, verdictLine, verificationLevel } from "./captureverdict.js";
+import { artifactOf, matchAnchors, oracleAnswered, safeId, weakest } from "./capturehelpers.js";
+import { settleFrames } from "./capturesettle.js";
+/** verify → settle → diff → emit, once per pass. */
+export async function runCapturePass(canceledSet, i, target, backend, cwd, tmpDir, watch, log) {
+    const runId = i.id;
+    const startedAt = Date.now();
+    const anchors = target.anchor ?? [];
+    const settleCap = Math.min(target.settleMs ?? DEFAULT_SETTLE_MS, MAX_SETTLE_MS);
+    const diffPct = target.diffPct ?? DEFAULT_DIFF_PCT;
+    const passes = backend.passes(target);
+    const files = [];
+    const artifacts = [];
+    let sampled = 0;
+    let stableAfterMs;
+    let level;
+    let overlay;
+    let diffRec;
+    let score;
+    let viewport;
+    let theme;
+    let blank = false;
+    // ── Aggregated across passes, never overwritten by the last one ──────────
+    //
+    // A `theme: "both"` target is two passes, and the sidecar is ONE record of
+    // the run. Keeping only the newest pass's console made a dark pass that
+    // logged three errors disappear behind a clean light one, and rewrote an
+    // anchor record whose own level said the anchor was missing. The rule below
+    // is the same one `weakest()` applies to the level: the run is only as
+    // trustworthy as its weakest frame, so counts SUM, missing anchors UNION,
+    // and a found anchor has to have been found by every pass that looked.
+    const consoleAcc = { errors: 0, warnings: 0, lines: [] };
+    const netAcc = { failed: 0, lines: [] };
+    let sawConsole = false;
+    let sawNetwork = false;
+    let sawAnchors = false;
+    let anchorFound = [];
+    const anchorMissing = new Set();
+    /** Distinct geometry+theme combinations, so the verdict can admit there
+     *  were others rather than quoting one pass's shape as the run's. */
+    const shapes = new Set();
+    for (let n = 0; n < passes.length; n++) {
+        const pass = passes[n];
+        if (canceledSet.has(runId))
+            break;
+        const ctx = {
+            cwd, tmpDir, pass, anchors, log,
+            cancelled: () => canceledSet.has(runId),
+        };
+        const session = await backend.open(target, ctx);
+        try {
+            const settle = await settleFrames(session, ctx, settleCap, `p${n}`);
+            sampled += settle.sampled;
+            if (settle.stableAfterMs !== undefined) {
+                stableAfterMs = Math.max(stableAfterMs ?? 0, settle.stableAfterMs);
+            }
+            // The weakest pass's score, not the newest — same rule as the level. A
+            // run is not worth its best-looking frame.
+            if (settle.score !== undefined)
+                score = score === undefined ? settle.score : Math.min(score, settle.score);
+            if (settle.note)
+                log(`[capture] ${settle.note}`);
+            const reading = await session.oracle();
+            const asked = oracleAnswered(reading);
+            const m = asked && anchors.length ? matchAnchors(anchors, reading) : null;
+            if (m) {
+                // Intersect the found, union the missing. An anchor one pass saw and
+                // another did not is a MISSING anchor for the run — the old code let
+                // a later pass rewrite `missing` to `[]` under a level that had
+                // already been capped by the earlier one, so the evidence and the
+                // claim contradicted each other inside one document.
+                anchorFound = sawAnchors ? anchorFound.filter((a) => m.found.includes(a)) : m.found.slice();
+                for (const a of m.missing)
+                    anchorMissing.add(a);
+                sawAnchors = true;
+            }
+            if (reading?.console) {
+                sawConsole = true;
+                consoleAcc.errors += reading.console.errors;
+                consoleAcc.warnings += reading.console.warnings;
+                for (const l of reading.console.lines)
+                    if (consoleAcc.lines.length < MAX_SIDECAR_LINES)
+                        consoleAcc.lines.push(l);
+            }
+            if (reading?.network) {
+                sawNetwork = true;
+                netAcc.failed += reading.network.failed;
+                for (const l of reading.network.lines)
+                    if (netAcc.lines.length < MAX_SIDECAR_LINES)
+                        netAcc.lines.push(l);
+            }
+            const ov = reading?.overlay ?? classifyOverlay(reading?.html);
+            if (ov && !overlay)
+                overlay = ov;
+            const passLevel = verificationLevel({
+                sampled: settle.sampled,
+                settled: settle.stableAfterMs !== undefined,
+                oracle: asked,
+                wanted: anchors.length,
+                // THIS pass's misses — the run-wide union is the record, not the rung.
+                missing: m ? m.missing.length : anchors.length,
+            });
+            // The run is only as trustworthy as its weakest frame.
+            level = level === undefined ? passLevel : weakest(level, passLevel);
+            const sd = await blankVariance(settle.last);
+            if (sd !== null && sd < BLANK_SD)
+                blank = true;
+            // `pass.viewport` is what was ASKED for in device-independent pixels;
+            // `size` is the PNG's own device pixels, which is the only geometry a
+            // backend that emulates nothing has. They are different numbers on a
+            // web pass (`deviceScaleFactor: 2`) and `wire/capture.ts` says which is
+            // which. The FIRST pass's is recorded — `shapes` is what says the rest
+            // existed, and `files[]` carries each frame's own.
+            const size = pngSize(settle.last);
+            const geom = pass.viewport ?? size ?? undefined;
+            shapes.add(`${geom ? `${geom.w}x${geom.h}` : "n/a"}|${pass.theme ?? ""}`);
+            if (viewport === undefined)
+                viewport = geom;
+            if (theme === undefined && pass.theme)
+                theme = pass.theme;
+            const emitted = emitFrame(i.cwd, target, settle.last, pass, size, files, artifacts);
+            log(`[capture] ${pass.label || "frame"} → ${emitted.relPath} (${settle.sampled} sampled`
+                + `${settle.stableAfterMs !== undefined ? `, settled after ${settle.stableAfterMs} ms` : ", never settled"})`);
+            if (watch && n === 0) {
+                const w = await watchLoop(i, target, session, ctx, emitted, diffPct, files, artifacts, log);
+                diffRec = w.diff;
+                sampled += w.sampled;
+            }
+        }
+        finally {
+            try {
+                await session.end();
+            }
+            catch { /* already gone */ }
+        }
+        if (watch)
+            break; // watch drives ONE pass; the rest would fight it for the lease
+    }
+    const canceled = canceledSet.has(runId);
+    const verification = level ?? "unverified";
+    // Absent stays absent: a run where no pass had a console to read carries no
+    // console record at all, which prints `n/a` and is a different statement
+    // from a measured `{errors: 0}`.
+    const consoleRec = sawConsole ? consoleAcc : undefined;
+    const netRec = sawNetwork ? netAcc : undefined;
+    const anchorRec = sawAnchors
+        ? { wanted: anchors, found: anchorFound.filter((a) => !anchorMissing.has(a)), missing: [...anchorMissing] }
+        : undefined;
+    const verdict = verdictLine({
+        verification, blank, errorOverlay: overlay, score, viewport, theme,
+        shapes: shapes.size, console: consoleRec, network: netRec,
+    });
+    const sidecar = {
+        v: 1,
+        runId,
+        target: { id: target.id, name: target.name, backend: target.backend },
+        startedAt,
+        finishedAt: Date.now(),
+        verification,
+        anchor: anchorRec,
+        score,
+        viewport,
+        theme,
+        frames: { sampled, stableAfterMs },
+        errorOverlay: overlay,
+        console: consoleRec,
+        network: netRec,
+        diff: diffRec,
+        files,
+        verdict,
+    };
+    const doc = newOutboxPath(i.cwd, `capture-${safeId(target.id)}`, ".json");
+    try {
+        writeFileSync(doc.full, JSON.stringify(sidecar, null, 2));
+        artifacts.push(artifactOf(i.cwd, doc));
+        log(`[capture] ${doc.relPath}`);
+    }
+    catch (e) {
+        log(`[capture] could not write the sidecar: ${String(e?.message ?? e)}`);
+    }
+    log(`[capture] ${verdict}`);
+    if (canceled)
+        return { ok: false, canceled: true, detail: "cancelled from the phone", artifacts, exitCode: null };
+    // An overlay or a blank frame is a FAILED run with a verdict — and the
+    // frame is in the outbox either way, because a failure whose evidence was
+    // deleted cannot be debugged from a phone.
+    const ok = !overlay && !blank && files.length > 0;
+    return {
+        ok,
+        detail: verdict,
+        exitCode: ok ? 0 : 1,
+        artifacts,
+    };
+}
+/** Copy one settled frame into `.claude/outbox/` and record it both ways. */
+function emitFrame(repoDir, target, from, pass, size, files, artifacts) {
+    const out = newOutboxPath(repoDir, `capture-${safeId(target.id)}`, ".png");
+    copyFileSync(from, out.full);
+    files.push({ relPath: out.relPath, w: size?.w, h: size?.h, theme: pass.theme });
+    artifacts.push(artifactOf(repoDir, out));
+    return { relPath: out.relPath, full: out.full };
+}
+/**
+ * Watch mode: keep sampling one pass, emitting only what the diff gate lets
+ * through, until cancel / 10 minutes / 60 frames.
+ *
+ * With no pixel tool `shouldEmit` degrades to emit-every-frame, and the
+ * REASON it gives is logged and stored on `diff.reason` — so the output says
+ * why sixty near-identical frames appeared, rather than the run looking
+ * broken or, worse, silently emitting nothing.
+ */
+async function watchLoop(i, target, session, ctx, firstEmitted, diffPct, files, artifacts, log) {
+    const tools = await probePixelTools();
+    const t0 = Date.now();
+    let emitted = 1;
+    let skipped = 0;
+    let sampled = 0;
+    let against = firstEmitted;
+    let diff;
+    log(`[capture] watching — a frame is kept past ${diffPct}% changed, up to ${WATCH_MAX_FRAMES} frames or 10 minutes.`);
+    while (!ctx.cancelled() && Date.now() - t0 < WATCH_MAX_MS && emitted < WATCH_MAX_FRAMES) {
+        await sleep(WATCH_INTERVAL_MS);
+        if (ctx.cancelled())
+            break;
+        const path = join(ctx.tmpDir, `watch-${sampled}.png`);
+        let taken;
+        try {
+            taken = (await session.frame(path)).path;
+        }
+        catch (e) {
+            log(`[capture] ${String(e?.message ?? e)}`);
+            break;
+        }
+        sampled++;
+        const pct = await changedPct(against.full, taken);
+        const d = shouldEmit({ first: false, changedPct: pct, diffPct, emitted, maxFrames: WATCH_MAX_FRAMES });
+        if (!d.emit) {
+            skipped++;
+            continue;
+        }
+        const size = pngSize(taken);
+        const out = emitFrame(i.cwd, target, taken, ctx.pass, size, files, artifacts);
+        emitted++;
+        diff = diffRecord(against.relPath, pct, pixelToolReason(tools));
+        log(`[capture] ${out.relPath} — ${d.reason}`);
+        against = out;
+    }
+    log(`[capture] watch ended: ${emitted} frames kept, ${skipped} skipped.`);
+    return { diff, sampled };
+}
+//# sourceMappingURL=capturepass.js.map

package/packages/host/dist/capture/capturepass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capturepass.js","sourceRoot":"","sources":["../../src/capture/capturepass.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/capture/capturesettle.d.ts

@@ -0,0 +1,35 @@
+import type { CaptureCtx, CaptureSession } from "./types.js";
+/**
+ * SETTLE — sample until two consecutive frames are byte-identical, or until the
+ * cap.
+ *
+ * Byte-equality and not a pixel comparison, deliberately: it needs no tool at
+ * all, which is what lets a machine with no ImageMagick still reach
+ * `settled:stable`. `settleMs` is a CAP — the loop stops the moment the screen
+ * agrees with itself, and a screen that never does gets its frame anyway with
+ * `stableAfterMs` ABSENT and a level that says `unverified`.
+ *
+ * ── The clock starts when the FIRST FRAME COMPLETES ────────────────────────
+ *
+ * `settleMs` is "how long to wait for the screen to stop moving", NOT "how long
+ * one frame may take". Those are different quantities and conflating them broke
+ * the whole loop on any slow backend: a cold garmin frame costs ~80–87 s (the
+ * simulator is pushed and restarted), the default cap is 15 s, so a clock
+ * started before frame 1 was already past the cap when frame 1 came back. The
+ * loop broke at `sampled: 1`, which is `unverified` on every backend — and
+ * `verificationLevel()` then THREW AWAY an OCR-confirmed anchor, because
+ * `anchor` requires `settled` and one frame can never be settled. Every real
+ * ciqkit run was `unverified`, with an anchor record beside it saying the text
+ * was there.
+ *
+ * So: the first frame is paid for unconditionally, whatever it costs, and the
+ * cap governs the WAITING after it. This is the kind of thing that gets
+ * re-broken by somebody making the run "respect its timeout".
+ */
+export declare function settleFrames(session: CaptureSession, ctx: CaptureCtx, capMs: number, tag: string): Promise<{
+    last: string;
+    sampled: number;
+    stableAfterMs?: number;
+    score?: number;
+    note?: string;
+}>;

package/packages/host/dist/capture/capturesettle.js

@@ -0,0 +1,77 @@
+/**
+ * SETTLE — sample until two consecutive frames agree. Split out of `capture.ts`
+ * (move only); the clock rule below is the one that was re-broken once.
+ */
+import { join } from "node:path";
+import { SETTLE_SAMPLE_MS, sleep } from "./capturekit.js";
+import { framesIdentical } from "./pixels.js";
+/**
+ * SETTLE — sample until two consecutive frames are byte-identical, or until the
+ * cap.
+ *
+ * Byte-equality and not a pixel comparison, deliberately: it needs no tool at
+ * all, which is what lets a machine with no ImageMagick still reach
+ * `settled:stable`. `settleMs` is a CAP — the loop stops the moment the screen
+ * agrees with itself, and a screen that never does gets its frame anyway with
+ * `stableAfterMs` ABSENT and a level that says `unverified`.
+ *
+ * ── The clock starts when the FIRST FRAME COMPLETES ────────────────────────
+ *
+ * `settleMs` is "how long to wait for the screen to stop moving", NOT "how long
+ * one frame may take". Those are different quantities and conflating them broke
+ * the whole loop on any slow backend: a cold garmin frame costs ~80–87 s (the
+ * simulator is pushed and restarted), the default cap is 15 s, so a clock
+ * started before frame 1 was already past the cap when frame 1 came back. The
+ * loop broke at `sampled: 1`, which is `unverified` on every backend — and
+ * `verificationLevel()` then THREW AWAY an OCR-confirmed anchor, because
+ * `anchor` requires `settled` and one frame can never be settled. Every real
+ * ciqkit run was `unverified`, with an anchor record beside it saying the text
+ * was there.
+ *
+ * So: the first frame is paid for unconditionally, whatever it costs, and the
+ * cap governs the WAITING after it. This is the kind of thing that gets
+ * re-broken by somebody making the run "respect its timeout".
+ */
+export async function settleFrames(session, ctx, capMs, tag) {
+    let t0 = 0;
+    let prev = null;
+    let last = "";
+    let sampled = 0;
+    let stableAfterMs;
+    let score;
+    let note;
+    for (;;) {
+        const r = await session.frame(join(ctx.tmpDir, `${tag}-${sampled}.png`));
+        sampled++;
+        if (sampled === 1)
+            t0 = Date.now();
+        last = r.path;
+        if (r.score !== undefined)
+            score = r.score;
+        if (r.note)
+            note = r.note;
+        if (prev && framesIdentical(prev, last)) {
+            stableAfterMs = Date.now() - t0;
+            break;
+        }
+        prev = last;
+        if (ctx.cancelled())
+            break;
+        if (Date.now() - t0 >= capMs)
+            break;
+        await sleep(SETTLE_SAMPLE_MS);
+    }
+    // Score the frame that is actually kept, once. A backend whose scorer is a
+    // subprocess (ciqkit shells out to python and numpy) must not pay for one per
+    // sample: the samples before the last one are thrown away, so their scores
+    // are a number nobody reads bought at a process start each. A backend that
+    // knows the score first-hand still returns it on `FrameResult` and that
+    // answer stands.
+    if (session.score && last) {
+        const s = await session.score(last);
+        if (s !== null)
+            score = s;
+    }
+    return { last, sampled, stableAfterMs, score, note };
+}
+//# sourceMappingURL=capturesettle.js.map

package/packages/host/dist/capture/capturesettle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capturesettle.js","sourceRoot":"","sources":["../../src/capture/capturesettle.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAuB,EACvB,GAAe,EACf,KAAa,EACb,GAAW;IAEX,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,aAAiC,CAAC;IACtC,IAAI,KAAyB,CAAC;IAC9B,IAAI,IAAwB,CAAC;IAE7B,SAAS,CAAC;QACR,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,OAAO,MAAM,CAAC,CAAC,CAAC;QACzE,OAAO,EAAE,CAAC;QACV,IAAI,OAAO,KAAK,CAAC;YAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QACd,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;YAAE,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAC3C,IAAI,CAAC,CAAC,IAAI;YAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QAC1B,IAAI,IAAI,IAAI,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;YAAC,MAAM;QAAC,CAAC;QACpF,IAAI,GAAG,IAAI,CAAC;QACZ,IAAI,GAAG,CAAC,SAAS,EAAE;YAAE,MAAM;QAC3B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,KAAK;YAAE,MAAM;QACpC,MAAM,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAChC,CAAC;IAED,2EAA2E;IAC3E,8EAA8E;IAC9E,2EAA2E;IAC3E,2EAA2E;IAC3E,wEAAwE;IACxE,iBAAiB;IACjB,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,IAAI;YAAE,KAAK,GAAG,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACvD,CAAC"}

package/packages/host/dist/capture/captureverdict.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The capture loop's pure cores: the verification ladder, the verdict line, the
+ * emit gate and the diff record. Split out of `capture.ts` (move only).
+ */
+import type { CaptureOverlayKind, CaptureVerification, CaptureTheme, CaptureViewport } from "@waterplane/shared";
+/** What `verificationLevel()` is allowed to look at. */
+export interface VerificationInput {
+    /** Frames sampled in the settle loop. One frame can never be `stable`. */
+    sampled: number;
+    /** Two consecutive frames were byte-identical. */
+    settled: boolean;
+    /** An ORACLE reading actually happened. False for every backend whose
+     *  `oracle()` returned null, and for a run where the oracle was there but
+     *  could not be read. */
+    oracle: boolean;
+    /** How many anchors the target named, and how many were not on screen. */
+    wanted: number;
+    missing: number;
+}
+/**
+ * How much this frame can be trusted — the one derivation, for every backend.
+ *
+ * The ladder is MONOTONE: `anchor` sits on top of `stable`, which sits on top
+ * of `unverified`, and each rung requires the one below it. That is why a
+ * confirmed anchor on a single frame still answers `unverified` — an anchor
+ * found in a screen that is still moving was found in a screen that is still
+ * moving, and "verified" is the strongest word this app has. Under-claiming is
+ * the bias everywhere in this repo; the frame is written either way and the
+ * anchor record still says what was found.
+ *
+ * The ceiling that matters most: `oracle: false` can NEVER answer `anchor`.
+ * `capture/window.ts` is permanently in that state.
+ */
+export declare function verificationLevel(v: VerificationInput): CaptureVerification;
+/** Everything the verdict line is allowed to look at. A `CaptureSidecar` is
+ *  structurally one of these, so the sidecar's own `verdict` and a run row's
+ *  cannot be worded two ways. */
+export interface VerdictInput {
+    verification: CaptureVerification;
+    /** The frame is one flat colour — nothing painted. Measured only where a
+     *  pixel tool exists; absent means the check did not run, not "not blank". */
+    blank?: boolean;
+    errorOverlay?: {
+        kind: CaptureOverlayKind;
+        text?: string;
+    };
+    score?: number;
+    viewport?: CaptureViewport;
+    theme?: CaptureTheme;
+    /**
+     * How many DISTINCT geometry+theme combinations the run's passes covered.
+     *
+     * Absent or 1 ⇒ `viewport`/`theme` describe every frame. More than that and
+     * they describe the FIRST pass only, so the line SAYS there were others
+     * rather than quoting one pass's shape as if it were the run's — a
+     * `theme: "both"` run printing `390x844 light` is a sentence that is true of
+     * half the frames and silent about the other half.
+     */
+    shapes?: number;
+    console?: {
+        errors: number;
+        warnings: number;
+        lines: string[];
+    };
+    network?: {
+        failed: number;
+        lines: string[];
+    };
+}
+/**
+ * The ~50-token line a person — or an agent that cannot see the picture — reads
+ * instead of the frame.
+ *
+ * Grammar, pinned by the test:
+ *   `{level} · score {n|n/a} · {w}x{h}[ {theme}][ +N more]|n/a · console: {clean|N err}|n/a · net: {clean|N failed}|n/a`
+ *
+ * The separator is U+00B7 with spaces. The phone treats the whole line as an
+ * OPAQUE string and never splits it, which is why there is no shared separator
+ * constant: nothing at the other end is entitled to parse this back apart.
+ *
+ * Every `n/a` is a measurement that did not happen. `console: clean` means the
+ * console was READ and held no errors; `console: n/a` means there was no
+ * console to read — a different fact, and the reason the sidecar's fields are
+ * optional rather than zeroed.
+ */
+export declare function verdictLine(v: VerdictInput): string;
+/** What `shouldEmit()` weighs. */
+export interface EmitInput {
+    /** No previous frame to compare against. */
+    first: boolean;
+    /** Percent of pixels changed, or `null` when NOTHING on this machine could
+     *  measure it. Never conflate the two: `0` is a measurement. */
+    changedPct: number | null;
+    /** The target's threshold, in percent. */
+    diffPct: number;
+    /** Frames already written this run. */
+    emitted: number;
+    maxFrames: number;
+}
+/**
+ * The watch-mode diff gate: is this frame worth a file?
+ *
+ * Two degradations matter and they go opposite ways. Past the cap the answer is
+ * always no, because an unbounded watch run fills an outbox somebody then has
+ * to look at. With no pixel tool the answer is always YES — capped, and SAYING
+ * so — because a gate that cannot measure and therefore emits nothing is a
+ * feature that silently does not work, which is worse than a few redundant
+ * frames a sentence in the output accounts for.
+ *
+ * The reason is returned rather than logged, so the output line, the sidecar's
+ * `diff.reason` and the test all read the same string.
+ */
+export declare function shouldEmit(e: EmitInput): {
+    emit: boolean;
+    reason: string;
+};
+/**
+ * One frame's difference from the one before it — the record, built once.
+ *
+ * The whole point of this function is that a MEASURED zero and an
+ * UNMEASURABLE difference must stay telling apart. `changedPct: 0` means
+ * ImageMagick compared two files and found no differing pixels. `reason` with
+ * no `changedPct` means nothing on this machine could look. Writing `0` for
+ * the second would say "the screen did not change" about a screen nobody
+ * examined, which is the exact failure CLAUDE.md's "never to a wrong number"
+ * names.
+ */
+export declare function diffRecord(againstRelPath: string, pct: number | null, reasonWhenUnmeasured: string): {
+    againstRelPath: string;
+    changedPct?: number;
+    reason?: string;
+};

package/packages/host/dist/capture/captureverdict.js

@@ -0,0 +1,107 @@
+/**
+ * How much this frame can be trusted — the one derivation, for every backend.
+ *
+ * The ladder is MONOTONE: `anchor` sits on top of `stable`, which sits on top
+ * of `unverified`, and each rung requires the one below it. That is why a
+ * confirmed anchor on a single frame still answers `unverified` — an anchor
+ * found in a screen that is still moving was found in a screen that is still
+ * moving, and "verified" is the strongest word this app has. Under-claiming is
+ * the bias everywhere in this repo; the frame is written either way and the
+ * anchor record still says what was found.
+ *
+ * The ceiling that matters most: `oracle: false` can NEVER answer `anchor`.
+ * `capture/window.ts` is permanently in that state.
+ */
+export function verificationLevel(v) {
+    const settled = v.settled && v.sampled >= 2;
+    if (settled && v.oracle && v.wanted > 0 && v.missing === 0)
+        return "anchor";
+    if (settled)
+        return "stable";
+    return "unverified";
+}
+/**
+ * The ~50-token line a person — or an agent that cannot see the picture — reads
+ * instead of the frame.
+ *
+ * Grammar, pinned by the test:
+ *   `{level} · score {n|n/a} · {w}x{h}[ {theme}][ +N more]|n/a · console: {clean|N err}|n/a · net: {clean|N failed}|n/a`
+ *
+ * The separator is U+00B7 with spaces. The phone treats the whole line as an
+ * OPAQUE string and never splits it, which is why there is no shared separator
+ * constant: nothing at the other end is entitled to parse this back apart.
+ *
+ * Every `n/a` is a measurement that did not happen. `console: clean` means the
+ * console was READ and held no errors; `console: n/a` means there was no
+ * console to read — a different fact, and the reason the sidecar's fields are
+ * optional rather than zeroed.
+ */
+export function verdictLine(v) {
+    const level = v.errorOverlay
+        ? `error-overlay:${v.errorOverlay.kind}`
+        : v.blank
+            ? "blank"
+            : v.verification === "anchor"
+                ? "verified:anchor"
+                : v.verification === "stable"
+                    ? "settled:stable"
+                    : "unverified";
+    const score = typeof v.score === "number" ? `score ${v.score}` : "score n/a";
+    // The `n/a` arm exists because a whole-desktop grab whose PNG header will not
+    // parse has no honest geometry — and `0x0` would read as a real answer.
+    const geom = v.viewport ? `${v.viewport.w}x${v.viewport.h}` : "n/a";
+    const one = v.theme ? `${geom} ${v.theme}` : geom;
+    // `+N more` rather than a second pair of numbers: the slot names the pass the
+    // geometry belongs to and admits the rest exist. The per-frame truth is in
+    // the sidecar's `files[]`, which is where a reader who needs all of them goes.
+    const shape = v.shapes && v.shapes > 1 ? `${one} +${v.shapes - 1} more` : one;
+    const con = v.console
+        ? (v.console.errors === 0 ? "console: clean" : `console: ${v.console.errors} err`)
+        : "console: n/a";
+    const net = v.network
+        ? (v.network.failed === 0 ? "net: clean" : `net: ${v.network.failed} failed`)
+        : "net: n/a";
+    return [level, score, shape, con, net].join(" · ");
+}
+/**
+ * The watch-mode diff gate: is this frame worth a file?
+ *
+ * Two degradations matter and they go opposite ways. Past the cap the answer is
+ * always no, because an unbounded watch run fills an outbox somebody then has
+ * to look at. With no pixel tool the answer is always YES — capped, and SAYING
+ * so — because a gate that cannot measure and therefore emits nothing is a
+ * feature that silently does not work, which is worse than a few redundant
+ * frames a sentence in the output accounts for.
+ *
+ * The reason is returned rather than logged, so the output line, the sidecar's
+ * `diff.reason` and the test all read the same string.
+ */
+export function shouldEmit(e) {
+    if (e.emitted >= e.maxFrames)
+        return { emit: false, reason: `frame cap reached (${e.maxFrames})` };
+    if (e.first)
+        return { emit: true, reason: "first frame" };
+    if (e.changedPct === null) {
+        return { emit: true, reason: "no pixel tool here, so every frame is emitted (capped)" };
+    }
+    return e.changedPct >= e.diffPct
+        ? { emit: true, reason: `changed ${e.changedPct}% (threshold ${e.diffPct}%)` }
+        : { emit: false, reason: `changed ${e.changedPct}%, under the ${e.diffPct}% threshold` };
+}
+/**
+ * One frame's difference from the one before it — the record, built once.
+ *
+ * The whole point of this function is that a MEASURED zero and an
+ * UNMEASURABLE difference must stay telling apart. `changedPct: 0` means
+ * ImageMagick compared two files and found no differing pixels. `reason` with
+ * no `changedPct` means nothing on this machine could look. Writing `0` for
+ * the second would say "the screen did not change" about a screen nobody
+ * examined, which is the exact failure CLAUDE.md's "never to a wrong number"
+ * names.
+ */
+export function diffRecord(againstRelPath, pct, reasonWhenUnmeasured) {
+    return pct === null
+        ? { againstRelPath, reason: reasonWhenUnmeasured }
+        : { againstRelPath, changedPct: pct };
+}
+//# sourceMappingURL=captureverdict.js.map

package/packages/host/dist/capture/captureverdict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureverdict.js","sourceRoot":"","sources":["../../src/capture/captureverdict.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/capture/garmin.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureBackend } from "./types.js";
+export declare const garminBackend: CaptureBackend;