waterplane 0.0.1 → 0.1.6

package/packages/host/dist/termqueries.js

@@ -0,0 +1,207 @@
+/**
+ * The tmux client's terminal queries, answered HERE — so a session behaves the
+ * same whether or not a phone is attached.
+ *
+ * The PTY the host holds runs a tmux CLIENT, and a client starting up asks its
+ * outer terminal who it is (measured, tmux 3.6b, with the host's own
+ * generated tmux.conf): DA1 `ESC[c`, DA2 `ESC[>c`, XTVERSION `ESC[>q`, the
+ * OSC 10/11 foreground/background colours, the colour scheme `ESC[?996n` and
+ * the text area in pixels and in cells (`ESC[14t`, `ESC[18t`; asked again on
+ * every resize). Nothing answered ⇒ for ~5.15 s tmux holds a lone Esc typed
+ * into the window (it could be the start of a reply), then gives up and
+ * repaints the whole pane. A phone's xterm.js answered SOME of them as session
+ * input, which made the timing depend on whether anybody was watching —
+ * scheduled, backlog, fan-out and resumed sessions run with the phone off.
+ *
+ * So the host answers all eight, the moment it sees them, by writing the reply
+ * to the PTY — and STRIPS them from the stream before any consumer (scrollback,
+ * the screen recorder, echo/settle, the phones), so no xterm.js ever answers a
+ * second time: a reply nobody asked for would be typed into the pane. Every
+ * other byte goes through untouched.
+ *
+ * The values are what an xterm.js would say, from facts the host owns:
+ *  - DA1 `ESC[?1;2c` and DA2 `ESC[>0;276;0c` — xterm.js 6's own answers.
+ *  - XTVERSION `ESC P>|xterm.js(6.0.0) ESC\` — xterm.js does not answer this
+ *    one; the name is the phone's terminal, so tmux files no feature it lacks.
+ *  - OSC 10/11 — `shared/termpalette.ts`'s DARK theme, 16 bits per channel,
+ *    with the terminator the query used. The theme a phone picked is a
+ *    per-DEVICE preference that never reaches the host (`shared/settings.ts`),
+ *    and a session nobody watches has no device at all, so dark it is — the
+ *    app's default and the system default when the OS will not say.
+ *  - `?996n` → `ESC[?997;1n` (1 = dark), agreeing with the colours.
+ *  - 18t → `ESC[8;<rows>;<cols>t` off the PTY's REAL geometry, read at the
+ *    moment of asking; 14t → `ESC[4;<h>;<w>t` as cells × a nominal cell of
+ *    `CELL_PX` (a ~15px monospace face). Nothing here draws pixels; tmux only
+ *    uses it to scale images, and a fixed cell is honest about that.
+ *
+ * Answered in the ORDER asked: measured, a 14t reply written before the 18t
+ * reply tmux asked for first is not consumed and the 18t reply leaks into the
+ * pane as typed text.
+ *
+ * What is NOT intercepted: a program inside the pane asking (the claude CLI
+ * asks OSC 11 for its background) talks to tmux, and tmux answers it from what
+ * it learned here — measured, the pane now gets `rgb:0b0b/0d0d/1010` where it
+ * used to get nothing before tmux's timeout. Those queries never reach the
+ * client's output. A pane program that WRAPS a query in tmux passthrough does
+ * reach it, byte-identical to tmux's own; a colour, scheme or size query is
+ * answered like one, and the reply lands in tmux's input exactly where a
+ * phone's reply always landed. A wrapped DA1/DA2/XTVERSION falls under the
+ * start-up deadline below like tmux's own — and loses nothing by it: tmux sets
+ * its HAVEDA/DA2/XDA flags on the FIRST such reply or at its start timer and
+ * forwards any later one to the pane as keys, so a late passthrough reply was
+ * never consumable, and stripping it is strictly better than typing it.
+ *
+ * **A start-up reply has a deadline.** DA1, DA2 and XTVERSION are asked once, when the client
+ * starts, and tmux waits ~5 s for them; a reply arriving after that is no longer read as a reply
+ * but forwarded to the pane as KEYS — `1;2c0;276;0c:>|xterm.js(6.0.0)^[\\` typed in front of
+ * whatever comes next (measured on tmux 3.4 and 3.6b: answered at 4.8 s, consumed; at 5.6 s,
+ * typed). The host answers the moment it READS the query, so a late answer means the host read it
+ * late — a boot re-attaching every live session in one synchronous pass over a slow `/mnt/c`
+ * did that on a WSL desktop. Past `STARTUP_REPLY_MS` of the client's life these three are
+ * stripped and NOT answered: tmux then gives up at 5 s exactly as it did before this module
+ * existed, which costs a repaint, where a late answer costs words in the composer. The colour,
+ * scheme and size replies are read at any time (same measurement) and are always answered.
+ *
+ * A chunk may end part-way into a query: the possible prefix (≤ 9 bytes) is
+ * held for the next chunk and released by `flush()` if none comes (the caller's
+ * short timer), so a held tail is never stranded.
+ */
+import { logTag, TERM_COLORS } from "@waterplane/shared";
+/** Nominal pixel cell for the 14t answer. */
+export const CELL_PX = { w: 9, h: 18 };
+/** Past this age of the client, a start-up-only query goes unanswered (tmux stops waiting at ~5 s). */
+export const STARTUP_REPLY_MS = 4000;
+const STARTUP_ONLY = new Set(["da1", "da2", "xtversion"]);
+const ESC = "\x1b";
+const ST = `${ESC}\\`;
+/** Every byte-exact query this answers, with its kind. Parameterless forms and
+ *  the explicit `0` forms both appear in the wild; the OSCs come with either
+ *  terminator and the reply mirrors it. */
+const FORMS = [
+    [`${ESC}[c`, "da1"], [`${ESC}[0c`, "da1"],
+    [`${ESC}[>c`, "da2"], [`${ESC}[>0c`, "da2"],
+    [`${ESC}[>q`, "xtversion"], [`${ESC}[>0q`, "xtversion"],
+    [`${ESC}]10;?${ST}`, "fg"], [`${ESC}]10;?\x07`, "fg"],
+    [`${ESC}]11;?${ST}`, "bg"], [`${ESC}]11;?\x07`, "bg"],
+    [`${ESC}[?996n`, "scheme"],
+    [`${ESC}[14t`, "px"],
+    [`${ESC}[18t`, "cells"],
+];
+/** `#rrggbb` → `rgb:rrrr/gggg/bbbb`, the X11 form xterm.js answers with. */
+export function x11Rgb(hex) {
+    const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex);
+    const [r, g, b] = m ? [m[1], m[2], m[3]] : ["00", "00", "00"];
+    const ch = (h) => (h + h).toLowerCase();
+    return `rgb:${ch(r)}/${ch(g)}/${ch(b)}`;
+}
+function answer(kind, form, facts) {
+    const term = form.endsWith("\x07") ? "\x07" : ST;
+    const colors = facts.colors?.() ?? TERM_COLORS.dark;
+    switch (kind) {
+        case "da1": return `${ESC}[?1;2c`;
+        case "da2": return `${ESC}[>0;276;0c`;
+        case "xtversion": return `${ESC}P>|xterm.js(6.0.0)${ST}`;
+        case "fg": return `${ESC}]10;${x11Rgb(colors.foreground)}${term}`;
+        case "bg": return `${ESC}]11;${x11Rgb(colors.background)}${term}`;
+        case "scheme": return `${ESC}[?997;${colors === TERM_COLORS.light ? 2 : 1}n`;
+        case "px": return `${ESC}[4;${facts.rows() * CELL_PX.h};${facts.cols() * CELL_PX.w}t`;
+        case "cells": return `${ESC}[8;${facts.rows()};${facts.cols()}t`;
+    }
+}
+/** Is `s` (starting at an ESC) a strict prefix of some query — i.e. could the
+ *  next chunk complete it? */
+function couldBecomeQuery(s) {
+    return FORMS.some(([f]) => f.length > s.length && f.startsWith(s));
+}
+export class TermQueryResponder {
+    facts;
+    held = "";
+    constructor(facts) {
+        this.facts = facts;
+    }
+    /** True while a possible query prefix waits for the next chunk. */
+    holding() { return this.held.length > 0; }
+    /** Release a held tail that no chunk completed. */
+    flush() { const h = this.held; this.held = ""; return h; }
+    feed(chunk) {
+        const s = this.held + chunk;
+        this.held = "";
+        if (!s.includes(ESC))
+            return { out: s, replies: "", late: 0 };
+        let out = "";
+        let replies = "";
+        let late = 0;
+        let from = 0;
+        let i = s.indexOf(ESC);
+        while (i !== -1) {
+            const hit = FORMS.find(([f]) => s.startsWith(f, i));
+            if (hit) {
+                out += s.slice(from, i);
+                if (STARTUP_ONLY.has(hit[1]) && (this.facts.ageMs?.() ?? 0) > STARTUP_REPLY_MS)
+                    late++;
+                else
+                    replies += answer(hit[1], hit[0], this.facts);
+                from = i + hit[0].length;
+                i = s.indexOf(ESC, from);
+                continue;
+            }
+            // At the very end and possibly a query cut in half: hold it.
+            const rest = s.slice(i);
+            if (rest.length < 10 && couldBecomeQuery(rest)) {
+                out += s.slice(from, i);
+                this.held = rest;
+                return { out, replies, late };
+            }
+            i = s.indexOf(ESC, i + 1);
+        }
+        out += s.slice(from);
+        return { out, replies, late };
+    }
+}
+/** How long a possible query prefix may wait for the chunk that completes it. */
+export const HOLD_MS = 25;
+/**
+ * Put the responder IN FRONT of a PTY's data handler: `onChunk` sees the
+ * stream with every query removed, and the replies go straight back into the
+ * PTY. The ONE place a tmux client's output enters the host (`sessions.ts`'s
+ * `register`), so no consumer can see a query and none can be skipped.
+ */
+export function answerTermQueries(proc, onChunk, facts, onLate) {
+    // Called right after the spawn, in the same tick: the client's age is counted from here.
+    const startedAt = Date.now();
+    const responder = new TermQueryResponder({ cols: () => proc.cols, rows: () => proc.rows, ageMs: () => Date.now() - startedAt, ...facts });
+    let timer = null;
+    proc.onData((raw) => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        const { out, replies, late } = responder.feed(raw);
+        if (replies) {
+            try {
+                proc.write(replies);
+            }
+            catch { /* exited */ }
+        }
+        if (late)
+            onLate?.(late, Date.now() - startedAt);
+        if (out)
+            onChunk(out);
+        if (responder.holding()) {
+            timer = setTimeout(() => { timer = null; const t = responder.flush(); if (t)
+                onChunk(t); }, HOLD_MS);
+        }
+    });
+    // Disposed on exit: only the timer goes (a chunk node-pty hands over after
+    // the exit event is still delivered, as it always was).
+    return { dispose() { if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        } } };
+}
+/** `answerTermQueries`' `onLate` for a session: one line naming it, the count and the age. */
+export function lateQueryLog(id, title) {
+    return (n, ageMs) => console.log(`${logTag} ${title || id} (${id}): ${n} start-up terminal ${n === 1 ? "query" : "queries"} read `
+        + `${(ageMs / 1000).toFixed(1)} s after its tmux client started — left unanswered: tmux had stopped waiting, and the reply would have been typed into the pane`);
+}
+//# sourceMappingURL=termqueries.js.map

package/packages/host/dist/termqueries.js.map

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

package/packages/host/dist/themeoverlay.d.ts

@@ -0,0 +1,74 @@
+import { type TermColors, type ThemeIconSlot, type ThemeOverlay } from "@waterplane/shared";
+export interface ThemeOverlayState {
+    file: string;
+    /** The file exists. */
+    present: boolean;
+    /** The cleaned overlay — `{}` when absent or ignored whole. */
+    overlay: ThemeOverlay;
+    /** Entries dropped, one sentence each. */
+    notes: string[];
+    /** Why the whole file was ignored, when it was. */
+    error?: string;
+}
+export declare const themeFile: () => string;
+/** The overlay as the file says right now. Never throws. */
+export declare function themeOverlayState(file?: string): ThemeOverlayState;
+/** What the tmux client is told its colours are (OSC 10/11). Dark, as before
+ *  this overlay existed — the host has no phone theme to follow. */
+export declare function hostTermColors(): TermColors;
+/** What `/api/theme` sends: the cleaned overlay minus `icons` (desktop paths; the shell carries the links). */
+export declare function wireThemeOverlay(o: ThemeOverlay): ThemeOverlay;
+export declare const ICON_MAX_BYTES: number;
+export declare const THEME_ICON_PREFIX = "/theme-icon/";
+export interface ThemeIconFile {
+    slot: ThemeIconSlot;
+    file: string;
+    mime: "image/png" | "image/svg+xml";
+    body: Buffer;
+    tag: string;
+}
+/**
+ * A slot's icon, resolved, contained and sniffed — or why not, in words.
+ * `dir` is the config dir (a parameter for the tests). Never throws.
+ */
+export declare function themeIconFile(slot: string, overlay?: ThemeOverlay, dir?: string): ThemeIconFile | {
+    error: string;
+};
+/** Every slot that resolves right now → its served URL (cache-busted by size+mtime). */
+export declare function themeIconUrls(overlay?: ThemeOverlay, dir?: string): Partial<Record<ThemeIconSlot, {
+    url: string;
+    mime: string;
+}>>;
+/** A short validator suffix for a served shell file that embeds these URLs ("" with none). */
+export declare const iconUrlsTag: (icons: Partial<Record<ThemeIconSlot, {
+    url: string;
+}>>) => string;
+type IconUrls = Partial<Record<ThemeIconSlot, {
+    url: string;
+    mime: string;
+}>>;
+/**
+ * The PWA manifest with the overlay's display name and icons, or `body`
+ * unchanged. An icon entry is replaced only by the slot of its own size —
+ * `192`, `512`, `maskable` by purpose, `favicon` the `any`-sized SVG when it is
+ * an SVG — so a slot not given keeps the built-in one.
+ */
+export declare function brandManifest(body: Buffer, displayName: string | undefined, icons?: IconUrls): Buffer;
+/**
+ * The served `index.html` with a fork's icons: `favicon` replaces every
+ * `<link rel="icon">` with one link, `apple-touch` the `apple-touch-icon`'s
+ * href. No icons ⇒ the same bytes.
+ */
+export declare function brandIndexHtml(body: Buffer, icons: IconUrls): Buffer;
+export interface OverlayCheck {
+    id: "overlays";
+    status: "ok" | "warn";
+    detail: string;
+    fix?: string;
+}
+/**
+ * The doctor's `overlays` row: which fork overlays are active in the config
+ * dir, and whether any entry was refused. `ok` with none is the normal case.
+ */
+export declare function overlaysCheck(): OverlayCheck;
+export {};

package/packages/host/dist/themeoverlay.js

@@ -0,0 +1,262 @@
+/**
+ * **A fork's look, read off `<config dir>/theme.json`** — the third config
+ * overlay beside `prompts/<name>.md` (`prompts.ts`) and `models.json`
+ * (`backends/claudemodels.ts`), same posture: optional, never throws, a bad
+ * file is one log line and today's behaviour. The shape and every rule about
+ * what is kept live in `@waterplane/shared`'s `themeoverlay.ts`, which the phone
+ * runs again over what this serves.
+ *
+ * Read on demand with an mtime+size check, so an edit takes effect on the next
+ * read (the phone's next boot, the next tmux colour query) with no restart and
+ * no file read per query.
+ *
+ * Who reads it: `GET /api/theme` (`api.ts`), the tmux OSC 10/11 answers
+ * (`hostTermColors`, `sessions.ts` → `termqueries.ts`), the served
+ * `manifest.webmanifest` and `index.html` (`brandManifest`, `brandIndexHtml`,
+ * `server/http.ts`), the icon files at `/theme-icon/<slot>` (`themeIconFile`)
+ * and the doctor's `overlays` row (`overlaysCheck`).
+ *
+ * **Icons are files from the config dir, so they get the containment rule.** A
+ * slot's path is shape-checked in `shared` (relative, no `..`, `.png`/`.svg`),
+ * then resolved HERE with symlinks followed on BOTH sides (`realResolve`, the
+ * same comparison `inRoot` makes — `/var` → `/private/var`) and refused unless
+ * it lands inside the config dir; then it must be a regular file under
+ * `ICON_MAX_BYTES` whose bytes ARE what its extension says (PNG signature, an
+ * `<svg` root). Only a slot `theme.json` names is ever served — the URL carries
+ * the slot, never a path — and an SVG goes out under a `default-src 'none'`
+ * CSP with `nosniff`, so a fork's logo opened as a page runs nothing on the
+ * app's origin.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, sep } from "node:path";
+import { describeThemeOverlay, parseThemeOverlay, termColorsFor, themeIconPathOk, themeOverlayEmpty, THEME_ICON_SLOTS, } from "@waterplane/shared";
+import { configDir } from "./branddirs.js";
+import { realResolve } from "./paths.js";
+import { overriddenPrompts } from "./prompts.js";
+import { parseModelsOverride } from "./backends/claudemodels.js";
+export const themeFile = () => join(configDir(), "theme.json");
+let cache = null;
+const said = new Set();
+/** The overlay as the file says right now. Never throws. */
+export function themeOverlayState(file = themeFile()) {
+    let tag = "absent";
+    try {
+        const st = statSync(file);
+        tag = `${st.size}:${st.mtimeMs}`;
+    }
+    catch { /* absent */ }
+    if (cache && cache.file === file && cache.tag === tag)
+        return cache.state;
+    let state;
+    if (tag === "absent")
+        state = { file, present: false, overlay: {}, notes: [] };
+    else {
+        try {
+            const r = parseThemeOverlay(readFileSync(file, "utf8"));
+            state = "error" in r
+                ? { file, present: true, overlay: {}, notes: [], error: r.error }
+                : { file, present: true, overlay: r.overlay, notes: r.notes };
+        }
+        catch (e) {
+            state = { file, present: true, overlay: {}, notes: [], error: `unreadable (${e.message})` };
+        }
+        const key = `${file}\0${tag}`;
+        if (!said.has(key)) {
+            said.add(key);
+            if (state.error)
+                console.warn(`[theme] ${file} ignored: ${state.error}; using the built-in look`);
+            for (const n of state.notes)
+                console.warn(`[theme] ${file}: ${n}`);
+        }
+    }
+    cache = { file, tag, state };
+    return state;
+}
+/** What the tmux client is told its colours are (OSC 10/11). Dark, as before
+ *  this overlay existed — the host has no phone theme to follow. */
+export function hostTermColors() {
+    return termColorsFor("dark", themeOverlayState().overlay);
+}
+/** What `/api/theme` sends: the cleaned overlay minus `icons` (desktop paths; the shell carries the links). */
+export function wireThemeOverlay(o) {
+    if (!o.icons)
+        return o;
+    const { icons: _icons, ...rest } = o;
+    return rest;
+}
+export const ICON_MAX_BYTES = 1024 * 1024;
+export const THEME_ICON_PREFIX = "/theme-icon/";
+const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * A slot's icon, resolved, contained and sniffed — or why not, in words.
+ * `dir` is the config dir (a parameter for the tests). Never throws.
+ */
+export function themeIconFile(slot, overlay = themeOverlayState().overlay, dir = configDir()) {
+    if (!THEME_ICON_SLOTS.includes(slot))
+        return { error: `unknown icon slot "${slot}"` };
+    const rel = overlay.icons?.[slot];
+    if (rel === undefined)
+        return { error: `no "${slot}" icon set` };
+    // Shape again: this module must not trust that the overlay came through the cleaner.
+    if (!themeIconPathOk(rel) || isAbsolute(rel))
+        return { error: `"${slot}": not a .png/.svg path relative to the config dir` };
+    const root = realResolve(dir);
+    const file = realResolve(join(dir, rel));
+    if (!file.startsWith(root + sep))
+        return { error: `"${slot}": ${rel} resolves outside the config dir; refused` };
+    let size = 0;
+    let mtimeMs = 0;
+    try {
+        const st = statSync(file);
+        if (!st.isFile())
+            return { error: `"${slot}": ${rel} is not a file` };
+        size = st.size;
+        mtimeMs = st.mtimeMs;
+    }
+    catch {
+        return { error: `"${slot}": ${rel} not found` };
+    }
+    if (size > ICON_MAX_BYTES)
+        return { error: `"${slot}": ${rel} is over ${ICON_MAX_BYTES / 1024} KB` };
+    let body;
+    try {
+        body = readFileSync(file);
+    }
+    catch (e) {
+        return { error: `"${slot}": ${rel} unreadable (${e.message})` };
+    }
+    const svg = rel.endsWith(".svg");
+    const ok = svg ? /<svg[\s>]/i.test(body.subarray(0, 4096).toString("utf8")) : body.subarray(0, 8).equals(PNG_SIG);
+    if (!ok)
+        return { error: `"${slot}": ${rel} is not ${svg ? "an SVG" : "a PNG"}` };
+    const tag = `${size.toString(36)}${Math.floor(mtimeMs).toString(36)}`;
+    return { slot: slot, file, mime: svg ? "image/svg+xml" : "image/png", body, tag };
+}
+/** Every slot that resolves right now → its served URL (cache-busted by size+mtime). */
+export function themeIconUrls(overlay = themeOverlayState().overlay, dir = configDir()) {
+    const out = {};
+    for (const slot of THEME_ICON_SLOTS) {
+        if (!overlay.icons?.[slot])
+            continue;
+        const r = themeIconFile(slot, overlay, dir);
+        if ("error" in r)
+            continue;
+        out[slot] = { url: `${THEME_ICON_PREFIX}${slot}?v=${r.tag}`, mime: r.mime };
+    }
+    return out;
+}
+/** A short validator suffix for a served shell file that embeds these URLs ("" with none). */
+export const iconUrlsTag = (icons) => THEME_ICON_SLOTS.filter((s) => icons[s]).map((s) => icons[s].url.split("?v=")[1] ?? "").join(".");
+/**
+ * The PWA manifest with the overlay's display name and icons, or `body`
+ * unchanged. An icon entry is replaced only by the slot of its own size —
+ * `192`, `512`, `maskable` by purpose, `favicon` the `any`-sized SVG when it is
+ * an SVG — so a slot not given keeps the built-in one.
+ */
+export function brandManifest(body, displayName, icons = {}) {
+    const anyIcon = Object.keys(icons).length > 0;
+    if (!displayName && !anyIcon)
+        return body;
+    try {
+        const j = JSON.parse(body.toString("utf8"));
+        if (displayName) {
+            j.name = displayName;
+            j.short_name = displayName;
+        }
+        if (anyIcon && Array.isArray(j.icons)) {
+            j.icons = j.icons.map((e) => {
+                const slot = e.purpose === "maskable" ? "maskable"
+                    : e.sizes === "192x192" ? "192"
+                        : e.sizes === "512x512" ? "512"
+                            : e.sizes === "any" && icons.favicon?.mime === "image/svg+xml" ? "favicon"
+                                : null;
+                const r = slot ? icons[slot] : undefined;
+                if (!r)
+                    return e;
+                // The entry keeps its declared size: the fork supplies the size the slot names.
+                return { ...e, src: r.url, type: r.mime };
+            });
+        }
+        return Buffer.from(JSON.stringify(j, null, 2) + "\n");
+    }
+    catch {
+        return body;
+    }
+}
+/**
+ * The served `index.html` with a fork's icons: `favicon` replaces every
+ * `<link rel="icon">` with one link, `apple-touch` the `apple-touch-icon`'s
+ * href. No icons ⇒ the same bytes.
+ */
+export function brandIndexHtml(body, icons) {
+    if (!icons.favicon && !icons["apple-touch"])
+        return body;
+    let html = body.toString("utf8");
+    if (icons.favicon) {
+        let first = true;
+        html = html.replace(/[ \t]*<link rel="icon"[^>]*>\n?/g, (m) => {
+            if (!first)
+                return "";
+            first = false;
+            const indent = /^[ \t]*/.exec(m)?.[0] ?? "";
+            return `${indent}<link rel="icon" type="${icons.favicon.mime}" href="${icons.favicon.url}" />\n`;
+        });
+    }
+    const at = icons["apple-touch"];
+    if (at)
+        html = html.replace(/(<link rel="apple-touch-icon"[^>]*href=")[^"]*(")/, `$1${at.url}$2`);
+    return Buffer.from(html);
+}
+/**
+ * The doctor's `overlays` row: which fork overlays are active in the config
+ * dir, and whether any entry was refused. `ok` with none is the normal case.
+ */
+export function overlaysCheck() {
+    const dir = configDir();
+    const active = [];
+    const bad = [];
+    const prompts = overriddenPrompts();
+    if (prompts.length)
+        active.push(`prompts/ (${prompts.join(", ")})`);
+    const modelsFile = join(dir, "models.json");
+    let modelsText = null;
+    try {
+        modelsText = readFileSync(modelsFile, "utf8");
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            bad.push(`models.json unreadable`);
+    }
+    if (modelsText !== null) {
+        const r = parseModelsOverride(modelsText);
+        if ("error" in r)
+            bad.push(`models.json ignored: ${r.error}`);
+        else
+            active.push(`models.json (+${r.add.aliases.length + r.add.ids.length} / −${r.hide.length})`);
+    }
+    const t = themeOverlayState(join(dir, "theme.json"));
+    if (t.error)
+        bad.push(`theme.json ignored: ${t.error}`);
+    else if (t.present) {
+        if (!themeOverlayEmpty(t.overlay))
+            active.push(`theme.json (${describeThemeOverlay(t.overlay)})`);
+        for (const slot of THEME_ICON_SLOTS) {
+            if (!t.overlay.icons?.[slot])
+                continue;
+            const r = themeIconFile(slot, t.overlay, dir);
+            if ("error" in r)
+                bad.push(`theme.json icon ${r.error}`);
+        }
+        if (t.notes.length)
+            bad.push(`theme.json: ${t.notes.length} entr${t.notes.length === 1 ? "y" : "ies"} ignored — ${t.notes[0]}${t.notes.length > 1 ? " …" : ""}`);
+    }
+    const detail = active.length ? `active in ${dir}: ${active.join(" · ")}` : `none in ${dir} — upstream defaults`;
+    if (!bad.length)
+        return { id: "overlays", status: "ok", detail };
+    return {
+        id: "overlays", status: "warn",
+        detail: `${detail}; ${bad.join("; ")}`,
+        fix: "Fix or remove the named entries — an ignored entry keeps the built-in value (CONTRIBUTING.md, Forks).",
+    };
+}
+//# sourceMappingURL=themeoverlay.js.map

package/packages/host/dist/themeoverlay.js.map

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

package/packages/host/dist/thumbs.d.ts

@@ -0,0 +1,69 @@
+/** Set once at boot; until then thumbnails are off (no root = nowhere to cache). */
+export declare function initThumbs(root: string): void;
+/** The env that polices ImageMagick, or null before initThumbs wrote a policy. */
+export declare function magickEnv(): Record<string, string> | null;
+/** Snap a requested width to the allow-list, or null if it isn't one. */
+export declare function thumbWidth(raw: string | null): number | null;
+export declare function canThumb(path: string): boolean;
+export interface ConvertTools {
+    sips: boolean;
+    magick: string | null;
+    ffmpeg: boolean;
+    policyDir?: string;
+}
+export interface ConvertPlan {
+    cmd: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/**
+ * The command that encodes `src` down to `width` px wide as JPEG at `out`, or
+ * null when no tool here can do it safely. Pure: the decoder is always named
+ * from the EXTENSION, never left to content sniffing; an extension we have no
+ * decoder for gets no plan (the caller serves the original).
+ */
+export declare function convertPlan(src: string, out: string, width: number, tools: ConvertTools): ConvertPlan | null;
+export interface Thumb {
+    buf: Buffer;
+    mime: string;
+    key: string;
+}
+/**
+ * A JPEG thumbnail of `absPath` at `width`, or null when we can't/shouldn't make
+ * one (disabled, no converter, unsupported type, source already small enough,
+ * conversion failed). Null always means "serve the original".
+ */
+export declare function thumbnail(absPath: string, width: number): Promise<Thumb | null>;
+/** What this cache holds right now: files and bytes. Its own function because
+ *  the storage report must not readdir a directory whose layout is this
+ *  module's business — `.jpg` keyed by a hash is an implementation detail, and
+ *  a foreign walk of it would break the day it stops being one. */
+export declare function thumbCacheUsage(): {
+    count: number;
+    bytes: number;
+} | null;
+/**
+ * Throw away cached thumbnails written at or before `before` — the storage
+ * screen's clear.
+ *
+ * **The owner clears its own cache.** A foreign `rmSync` over this directory
+ * would race `thumbnail()`'s rename-in at a path an `inflight` promise is
+ * about to resolve from, and would have to know the naming scheme to avoid
+ * deleting a partial file it does not own.
+ *
+ * **`before` is the contract, not a name list.** A person was shown "1541
+ * files · 21 MB" measured at an instant, and the promise a clear makes is that
+ * nothing outside that reading goes. Sending 1541 filenames would keep the same
+ * promise with a 90 KB request body; an instant keeps it in one number — and
+ * unlike the transport sweep, the individual rows here were never the decision,
+ * because nobody chooses which thumbnails to keep.
+ *
+ * Files only, no recursion, symlinks skipped: the cache is flat by
+ * construction, so anything else in there is not this module's and is left
+ * alone.
+ */
+export declare function clearThumbCache(before: number): {
+    deleted: number;
+    bytes: number;
+    failed: number;
+};