harnery 0.33.0 → 0.34.0

package/dist/lib/browser/qa-snapshot.d.ts

@@ -0,0 +1,64 @@
+import { type QaContext, type QaSignature } from "./qa-plan.js";
+import type { PersistedCritique } from "./qa-reuse.js";
+declare const SNAPSHOT_DIR: string;
+export interface QaSnapshotStoreOptions {
+    /** Override the store root (tests, host-managed cache locations). */
+    root?: string;
+}
+export interface StoredQaSnapshot {
+    signature: QaSignature;
+    /** Directory holding this snapshot's files. */
+    path: string;
+    domHtmlPath?: string;
+    screenshotPath?: string;
+    /** Critique results persisted with the snapshot (full-coverage runs only) —
+     * what the band-diff reuse layer replays for provably-unchanged regions. */
+    critique?: PersistedCritique;
+}
+/** Filesystem-safe key for a target URL/file + render context. The digest
+ * disambiguates targets whose sanitized slugs collide. */
+export declare function qaSnapshotKey(target: string): string;
+/**
+ * Persist a QA snapshot atomically. The whole context directory is staged as
+ * `<dir>.tmp-<pid>` and renamed into place, replacing any prior snapshot for
+ * the same target + context — a reader never observes a partial write.
+ */
+export declare function saveQaSnapshot(target: string, context: QaContext, content: {
+    signature: QaSignature;
+    domHtml?: string;
+    screenshotPng?: Buffer;
+    critique?: PersistedCritique;
+}, opts?: QaSnapshotStoreOptions): StoredQaSnapshot;
+/** Load the persisted snapshot for a target + context, or null. A corrupt
+ * signature file returns null (and the caller re-acquires a baseline) rather
+ * than throwing — a bad cache entry must never block QA. */
+export declare function loadQaSnapshot(target: string, context: QaContext, opts?: QaSnapshotStoreOptions): StoredQaSnapshot | null;
+/** List targets with at least one persisted snapshot (store maintenance). */
+export declare function listQaSnapshotTargets(opts?: QaSnapshotStoreOptions): string[];
+export interface ResolvedQaBaseline {
+    /** `qa-snapshot:<capturedAt>` | `production-render:<capturedAt>` |
+     * `revision-render:<label>` | `none` — recorded in the manifest so a
+     * reviewer can judge staleness. */
+    source: string;
+    signature: QaSignature | null;
+}
+/**
+ * Walk the baseline resolution order with caller-supplied fallbacks. Pure
+ * orchestration: rendering lives in the caller (production URLs and git
+ * worktrees are its business), this just encodes the order and the source
+ * labeling. A fallback that throws or returns null falls through to the next
+ * rung; exhausting all rungs returns `{ source: "none", signature: null }`,
+ * which classifies as `unknown` — never silently text-only.
+ */
+export declare function resolveQaBaseline(opts: {
+    target: string;
+    context: QaContext;
+    store?: QaSnapshotStoreOptions;
+    renderProduction?: () => Promise<QaSignature | null>;
+    renderRevision?: {
+        label: string;
+        render: () => Promise<QaSignature | null>;
+    };
+}): Promise<ResolvedQaBaseline>;
+export { SNAPSHOT_DIR as QA_SNAPSHOT_DIR };
+//# sourceMappingURL=qa-snapshot.d.ts.map

package/dist/lib/browser/qa-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qa-snapshot.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/qa-snapshot.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAW,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,QAAA,MAAM,YAAY,QAA0D,CAAC;AAE7E,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,WAAW,CAAC;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;0DAC0D;AAC1D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBpD;AAWD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE;IACP,SAAS,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B,EACD,IAAI,GAAE,sBAA2B,GAChC,gBAAgB,CAyBlB;AAED;;4DAE4D;AAC5D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,EAClB,IAAI,GAAE,sBAA2B,GAChC,gBAAgB,GAAG,IAAI,CAiCzB;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,sBAA2B,GAAG,MAAM,EAAE,CAUjF;AAED,MAAM,WAAW,kBAAkB;IACjC;;uCAEmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACrD,cAAc,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;KAAE,CAAC;CAC/E,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwB9B;AAED,OAAO,EAAE,YAAY,IAAI,eAAe,EAAE,CAAC"}

package/dist/lib/browser/qa-snapshot.js

@@ -0,0 +1,171 @@
+// Persisted QA snapshots: the baseline source that makes repeat QA cheap.
+//
+// Every passing QA run persists its final page signature (and optionally the
+// serialized DOM + full-page screenshot) per render context. The next run
+// inherits its baseline for free instead of re-rendering production or a git
+// revision. Resolution order (the plan's 2.6):
+//   1. persisted QA snapshot   (this store)
+//   2. production render       (caller-supplied fallback)
+//   3. baseline-revision render (caller-supplied fallback, from a worktree)
+//   4. none                    → classification is `unknown`, never text-only
+//
+// Storage is content-under-a-key, like visual-diff baselines: a directory per
+// target, a subdirectory per context, atomic writes (tmp + rename) so a
+// crashed writer never leaves a half-baseline the next run would trust.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { fnv1a32 } from "./qa-plan.js";
+const SNAPSHOT_DIR = resolve(homedir(), ".cache", "harnery", "qa-snapshots");
+/** Filesystem-safe key for a target URL/file + render context. The digest
+ * disambiguates targets whose sanitized slugs collide. */
+export function qaSnapshotKey(target) {
+    const source = target.replace(/^[a-z]+:\/\//i, "");
+    let slug = "";
+    let separatorPending = false;
+    for (let index = 0; index < source.length && slug.length < 80; index++) {
+        const code = source.charCodeAt(index);
+        const alpha = (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+        const digit = code >= 48 && code <= 57;
+        if (alpha || digit) {
+            if (separatorPending && slug.length > 0 && slug.length < 80)
+                slug += "-";
+            if (slug.length < 80)
+                slug += source[index];
+            separatorPending = false;
+        }
+        else if (slug.length > 0) {
+            separatorPending = true;
+        }
+    }
+    return `${slug || "target"}-${fnv1a32(target).slice(0, 8)}`;
+}
+function contextDirName(context) {
+    const clean = (part) => part.replace(/[^a-zA-Z0-9_.]+/g, "-");
+    return `${clean(context.viewport)}-${clean(context.theme)}-${clean(context.state)}`;
+}
+function snapshotDir(target, context, opts) {
+    return resolve(opts.root ?? SNAPSHOT_DIR, qaSnapshotKey(target), contextDirName(context));
+}
+/**
+ * Persist a QA snapshot atomically. The whole context directory is staged as
+ * `<dir>.tmp-<pid>` and renamed into place, replacing any prior snapshot for
+ * the same target + context — a reader never observes a partial write.
+ */
+export function saveQaSnapshot(target, context, content, opts = {}) {
+    const dir = snapshotDir(target, context, opts);
+    const staging = `${dir}.tmp-${process.pid}`;
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    writeFileSync(resolve(staging, "signature.json"), `${JSON.stringify(content.signature)}\n`);
+    if (content.domHtml !== undefined) {
+        writeFileSync(resolve(staging, "dom.html"), content.domHtml);
+    }
+    if (content.screenshotPng !== undefined) {
+        writeFileSync(resolve(staging, "screenshot.png"), content.screenshotPng);
+    }
+    if (content.critique !== undefined) {
+        writeFileSync(resolve(staging, "critique.json"), `${JSON.stringify(content.critique)}\n`);
+    }
+    rmSync(dir, { recursive: true, force: true });
+    renameSync(staging, dir);
+    return {
+        signature: content.signature,
+        path: dir,
+        ...(content.domHtml !== undefined ? { domHtmlPath: resolve(dir, "dom.html") } : {}),
+        ...(content.screenshotPng !== undefined
+            ? { screenshotPath: resolve(dir, "screenshot.png") }
+            : {}),
+    };
+}
+/** Load the persisted snapshot for a target + context, or null. A corrupt
+ * signature file returns null (and the caller re-acquires a baseline) rather
+ * than throwing — a bad cache entry must never block QA. */
+export function loadQaSnapshot(target, context, opts = {}) {
+    const dir = snapshotDir(target, context, opts);
+    const sigPath = resolve(dir, "signature.json");
+    if (!existsSync(sigPath))
+        return null;
+    try {
+        const signature = JSON.parse(readFileSync(sigPath, "utf8"));
+        if (!signature || !Array.isArray(signature.nodes) || !Array.isArray(signature.stylesheets)) {
+            return null;
+        }
+        const domHtmlPath = resolve(dir, "dom.html");
+        const screenshotPath = resolve(dir, "screenshot.png");
+        const critiquePath = resolve(dir, "critique.json");
+        let critique;
+        if (existsSync(critiquePath)) {
+            try {
+                const parsed = JSON.parse(readFileSync(critiquePath, "utf8"));
+                if (parsed && typeof parsed.contract_version === "number" && Array.isArray(parsed.tiles)) {
+                    critique = parsed;
+                }
+            }
+            catch {
+                // corrupt critique.json degrades to a reuse miss, never an error
+            }
+        }
+        return {
+            signature,
+            path: dir,
+            ...(existsSync(domHtmlPath) ? { domHtmlPath } : {}),
+            ...(existsSync(screenshotPath) ? { screenshotPath } : {}),
+            ...(critique ? { critique } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** List targets with at least one persisted snapshot (store maintenance). */
+export function listQaSnapshotTargets(opts = {}) {
+    const root = opts.root ?? SNAPSHOT_DIR;
+    if (!existsSync(root))
+        return [];
+    try {
+        return readdirSync(root)
+            .filter((name) => !name.includes(".tmp-"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Walk the baseline resolution order with caller-supplied fallbacks. Pure
+ * orchestration: rendering lives in the caller (production URLs and git
+ * worktrees are its business), this just encodes the order and the source
+ * labeling. A fallback that throws or returns null falls through to the next
+ * rung; exhausting all rungs returns `{ source: "none", signature: null }`,
+ * which classifies as `unknown` — never silently text-only.
+ */
+export async function resolveQaBaseline(opts) {
+    const stored = loadQaSnapshot(opts.target, opts.context, opts.store ?? {});
+    if (stored) {
+        return { source: `qa-snapshot:${stored.signature.capturedAt}`, signature: stored.signature };
+    }
+    if (opts.renderProduction) {
+        try {
+            const signature = await opts.renderProduction();
+            if (signature)
+                return { source: `production-render:${signature.capturedAt}`, signature };
+        }
+        catch {
+            // fall through — an unreachable production URL is not a verdict
+        }
+    }
+    if (opts.renderRevision) {
+        try {
+            const signature = await opts.renderRevision.render();
+            if (signature) {
+                return { source: `revision-render:${opts.renderRevision.label}`, signature };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return { source: "none", signature: null };
+}
+export { SNAPSHOT_DIR as QA_SNAPSHOT_DIR };

package/dist/lib/browser/runts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runts.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/runts.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,CAAC,IAAI,EAAE;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAK,WAAW,CAoIhB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,KAAK,IAAI,CAyC/E;AAED,wBAAgB,gCAAgC,IAAI,MAAM,IAAI,CAI7D"}
+{"version":3,"file":"runts.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/runts.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,CAAC,IAAI,EAAE;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAK,WAAW,CA6JhB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,KAAK,IAAI,CAyC/E;AAED,wBAAgB,gCAAgC,IAAI,MAAM,IAAI,CAI7D"}

package/dist/lib/browser/runts.js

@@ -113,9 +113,10 @@ export function buildRuntsCheck() {
                     if (entry) {
                         entry.words.push(m[0]);
                         entry.last = rect;
+                        entry.node = n;
                     }
                     else {
-                        lines.set(top, { words: [m[0]], last: rect });
+                        lines.set(top, { words: [m[0]], last: rect, node: n });
                     }
                 }
             }
@@ -129,6 +130,26 @@ export function buildRuntsCheck() {
             const word = last.words[0] ?? "";
             if (ATOMIC.test(word))
                 continue;
+            // A chip is not prose. A lone token whose glyphs live inside a padded,
+            // boxed inline element (a <code> chip, pill, or badge) is a UI control:
+            // it cannot be rebalanced by rewording, tag rows legitimately wrap to a
+            // single chip, and its shifted glyph box also buckets as a phantom
+            // "line" when it sits mid-line beside normal text. Walk the word's
+            // inline ancestry (tag-based, since flex/grid parents blockify computed
+            // display) and skip the finding when a chip hosts it.
+            const chipHosted = (() => {
+                for (let e = last.node.parentElement; e && e !== el && INLINE.has(e.tagName); e = e.parentElement) {
+                    const cs = getComputedStyle(e);
+                    const padX = (Number.parseFloat(cs.paddingLeft) || 0) + (Number.parseFloat(cs.paddingRight) || 0);
+                    const boxed = (cs.backgroundColor !== "rgba(0, 0, 0, 0)" && cs.backgroundColor !== "transparent") ||
+                        (Number.parseFloat(cs.borderTopWidth) || 0) > 0;
+                    if (padX > 0 && boxed)
+                        return true;
+                }
+                return false;
+            })();
+            if (chipHosted)
+                continue;
             runts.push({
                 block: label(el),
                 word,

package/dist/lib/browser/tiling.d.ts

@@ -0,0 +1,71 @@
+export interface VisualAtom {
+    /** hard: cutting through it visibly breaks content. soft: looks untidy. */
+    kind: "text-line" | "replaced" | "box";
+    /** Document-space vertical span (CSS px scaled to image px by the caller). */
+    top: number;
+    bottom: number;
+}
+export interface SnapSeam {
+    /** Document-space y of the cut. */
+    y: number;
+    /** Weighted atoms the cut passes through; 0 = clean. */
+    cost: number;
+    /** Hard atoms (text lines, replaced elements) the cut passes through. */
+    hard: number;
+    clean: boolean;
+}
+export interface SnapOptions {
+    bandHeight: number;
+    /** Overlap applied below a dirty seam (the legacy constant, e.g. 120). */
+    overlap: number;
+    /** Overlap applied below a clean seam. Default 16. */
+    cleanOverlap?: number;
+    /** Fraction of bandHeight the seam may move up from its target. Default 0.3. */
+    slackRatio?: number;
+    /** Minimum band height as a fraction of bandHeight. Default 0.5. */
+    minBandRatio?: number;
+}
+/** Weighted cost of a horizontal cut at document-space y. */
+export declare function cutCost(atoms: VisualAtom[], y: number): {
+    cost: number;
+    hard: number;
+};
+/**
+ * Cut the vertical span [top, bottom) into bands whose seams snap into
+ * content gaps. Seams only move UP from their fixed target (never down), so
+ * band height is bounded by `bandHeight` above and `minBandRatio` below.
+ * Returns full-width rects in the caller's coordinate space plus the seam
+ * record for logging/telemetry.
+ */
+export declare function snappedBandRects(top: number, bottom: number, x: number, width: number, atoms: VisualAtom[], opts: SnapOptions): {
+    rects: Array<{
+        index: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    seams: SnapSeam[];
+};
+/**
+ * Split one element rect into internally-banded sub-rects when it is taller
+ * than the band budget. Selector-mode tiles previously shipped over-tall
+ * elements as one giant tile that the vision provider downscales; banding
+ * inside the element keeps every sub-tile at full resolution. Elements within
+ * 1.25x of the budget stay whole — a slightly-over tile beats a degenerate
+ * split.
+ */
+export declare function bandOversizedRect(rect: {
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, atoms: VisualAtom[], opts: SnapOptions): Array<{
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+//# sourceMappingURL=tiling.d.ts.map

package/dist/lib/browser/tiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiling.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/tiling.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;IACvC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,mCAAmC;IACnC,CAAC,EAAE,MAAM,CAAC;IACV,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CActF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,EAAE,EACnB,IAAI,EAAE,WAAW,GAChB;IACD,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB,CA+CA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5E,KAAK,EAAE,UAAU,EAAE,EACnB,IAAI,EAAE,WAAW,GAChB,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAU/E"}

package/dist/lib/browser/tiling.js

@@ -0,0 +1,118 @@
+// Content-aware band placement for the vision critique tiler.
+//
+// Fixed-height bands cut whatever sits at the boundary — half a heading, a
+// sliced table row, the middle of an image — and the critique rubric then has
+// to tell the model to ignore slice-edge clipping, which costs sensitivity on
+// every tile. This module snaps each cut into nearby content gaps instead:
+// the caller extracts "visual atoms" (text line boxes, replaced elements,
+// small bordered boxes) from the live page, and `snappedBandRects` places
+// each seam at the cheapest cut inside a bounded search window above the
+// fixed target. A clean seam (nothing straddles it) needs only a token
+// overlap; a dirty seam (unavoidable content, e.g. an element taller than
+// the band) keeps the caller's full overlap so the rubric mitigation still
+// applies there.
+//
+// Measured on a mixed fixture (prose, cards, 60-row table, an 1800px chart):
+// hard-atom slices per page dropped 9 → 1 on desktop and 4 → 2 on mobile at
+// an unchanged tile count, with every band height within [50%, 100%] of the
+// budget. The remaining slice was inside the over-tall chart, where no clean
+// cut exists — exactly the case the dirty-seam fallback covers.
+//
+// Pure math, no DOM access: atoms come in as plain rect spans so the module
+// stays testable and portable. Atom extraction lives on the browser client.
+const HARD_WEIGHT = 10;
+const SOFT_WEIGHT = 1;
+const EDGE_MARGIN = 4; // grazing an atom edge this closely counts as crossing
+const CANDIDATE_STEP = 2; // px between scored cut candidates
+/** Weighted cost of a horizontal cut at document-space y. */
+export function cutCost(atoms, y) {
+    let cost = 0;
+    let hard = 0;
+    for (const a of atoms) {
+        if (y > a.top - EDGE_MARGIN && y < a.bottom + EDGE_MARGIN) {
+            if (a.kind === "box") {
+                cost += SOFT_WEIGHT;
+            }
+            else {
+                cost += HARD_WEIGHT;
+                hard++;
+            }
+        }
+    }
+    return { cost, hard };
+}
+/**
+ * Cut the vertical span [top, bottom) into bands whose seams snap into
+ * content gaps. Seams only move UP from their fixed target (never down), so
+ * band height is bounded by `bandHeight` above and `minBandRatio` below.
+ * Returns full-width rects in the caller's coordinate space plus the seam
+ * record for logging/telemetry.
+ */
+export function snappedBandRects(top, bottom, x, width, atoms, opts) {
+    const rects = [];
+    const seams = [];
+    const span = bottom - top;
+    if (span <= 0 || width <= 0)
+        return { rects, seams };
+    const cleanOverlap = opts.cleanOverlap ?? 16;
+    const slack = Math.round(opts.bandHeight * (opts.slackRatio ?? 0.3));
+    const minBand = Math.round(opts.bandHeight * (opts.minBandRatio ?? 0.5));
+    let bandTop = top;
+    let index = 0;
+    while (bandTop + opts.bandHeight < bottom) {
+        const target = bandTop + opts.bandHeight;
+        const lo = Math.max(bandTop + minBand, target - slack);
+        // Score candidates, find the minimal cost in the window.
+        const costs = [];
+        let minCost = Number.POSITIVE_INFINITY;
+        for (let y = lo; y <= target; y += CANDIDATE_STEP) {
+            const c = cutCost(atoms, y);
+            costs.push({ y, ...c });
+            if (c.cost < minCost)
+                minCost = c.cost;
+        }
+        // Snap to the center of the widest minimal-cost run; ties resolve toward
+        // the target (later run wins on >=) so bands stay as tall as possible.
+        let runStart = -1;
+        let best = { start: 0, end: costs.length - 1, len: 0 };
+        for (let i = 0; i <= costs.length; i++) {
+            const inRun = i < costs.length && costs[i].cost === minCost;
+            if (inRun && runStart === -1)
+                runStart = i;
+            if (!inRun && runStart !== -1) {
+                const len = i - runStart;
+                if (len >= best.len)
+                    best = { start: runStart, end: i - 1, len };
+                runStart = -1;
+            }
+        }
+        const pick = costs[Math.floor((best.start + best.end) / 2)];
+        const clean = pick.cost === 0;
+        seams.push({ y: pick.y, cost: pick.cost, hard: pick.hard, clean });
+        rects.push({ index, x, y: bandTop, width, height: pick.y - bandTop });
+        index++;
+        bandTop = pick.y - (clean ? cleanOverlap : opts.overlap);
+    }
+    rects.push({ index, x, y: bandTop, width, height: bottom - bandTop });
+    return { rects, seams };
+}
+/**
+ * Split one element rect into internally-banded sub-rects when it is taller
+ * than the band budget. Selector-mode tiles previously shipped over-tall
+ * elements as one giant tile that the vision provider downscales; banding
+ * inside the element keeps every sub-tile at full resolution. Elements within
+ * 1.25x of the budget stay whole — a slightly-over tile beats a degenerate
+ * split.
+ */
+export function bandOversizedRect(rect, atoms, opts) {
+    if (rect.height <= opts.bandHeight * 1.25)
+        return [rect];
+    const { rects } = snappedBandRects(rect.y, rect.y + rect.height, rect.x, rect.width, atoms, opts);
+    return rects.map((r, i) => ({
+        label: `${rect.label} (${i + 1}/${rects.length})`,
+        x: r.x,
+        y: r.y,
+        width: r.width,
+        height: r.height,
+    }));
+}

package/dist/lib/claude-desktop.d.ts

@@ -58,36 +58,6 @@ export interface MirrorPlan {
     /** Entries skipped because they are archived (opt in via includeArchived). */
     skippedArchived: number;
 }
-export type DesktopLifecycleState = "active" | "blocked" | "done";
-export interface DesktopLifecycleRecord {
-    state: DesktopLifecycleState;
-    updatedAt: string;
-    instanceId: string | null;
-    sessionId: string | null;
-    reason: string | null;
-}
-export type DesktopTidySource = "lifecycle" | "legacy-prefix";
-export interface DesktopTidyAction {
-    entry: DesktopSessionEntry;
-    source: DesktopTidySource;
-    lifecycle: DesktopLifecycleRecord | null;
-}
-export type DesktopTidySkipReason = "already_archived" | "blocked_title" | "lifecycle_active" | "lifecycle_blocked" | "unmatched";
-export interface DesktopTidySkip {
-    entry: DesktopSessionEntry;
-    reason: DesktopTidySkipReason;
-    lifecycle: DesktopLifecycleRecord | null;
-}
-export interface DesktopTidyPlan {
-    actions: DesktopTidyAction[];
-    skipped: DesktopTidySkip[];
-}
-export interface DesktopTidyOptions {
-    /** Restrict entries to accounts whose UUID starts with one of these prefixes. */
-    accounts?: string[];
-    /** Accept an unmatched historical `[DONE]` title as a compatibility fallback. */
-    includeLegacyPrefix?: boolean;
-}
 /**
  * Candidate desktop-app data directories for this machine, most specific
  * first. Only directories that exist AND contain a claude-code-sessions/
@@ -132,21 +102,4 @@ export declare function planMirror(accounts: DesktopAccount[], opts?: MirrorOpti
 export declare function applyMirror(plan: MirrorPlan): {
     copied: number;
 };
-/**
- * Read the latest durable lifecycle declaration for every Harnery session.
- *
- * The canonical ledger rotates into `events-*.ndjson` archives. Stream each
- * file rather than loading the whole history into one string, then compare
- * event timestamps because adapter replay may append an older event later.
- * Records are indexed by both session_id and instance_id so a desktop
- * cliSessionId can match either identity shape used by older adapters.
- */
-export declare function readDesktopLifecycleIndex(coordRoot: string): Promise<Map<string, DesktopLifecycleRecord>>;
-/** Select desktop entries whose durable lifecycle is done. */
-export declare function planTidy(accounts: DesktopAccount[], lifecycleBySession: ReadonlyMap<string, DesktopLifecycleRecord>, opts?: DesktopTidyOptions): DesktopTidyPlan;
-/** Apply a tidy plan with same-directory temp files and atomic renames. */
-export declare function applyTidy(plan: DesktopTidyPlan): {
-    archived: number;
-    alreadyArchived: number;
-};
 //# sourceMappingURL=claude-desktop.d.ts.map

package/dist/lib/claude-desktop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/lib/claude-desktop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/lib/claude-desktop.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,mBAAmB,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;CACzB;AAaD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAgC/D;AA4CD,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAyB9D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAerF;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM1F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,UAAU,CA2C3F;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAQhE"}