@inhuman.tools/quickdraw 0.0.0-stage → 0.2.0

package/dist/runtime/present_profile.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Present profiles — sexy under budget.
+ *
+ *   local → 120fps, truecolor, full flourish
+ *   ssh   → 30fps, ansi256 preferred, sparse flourish
+ *
+ * This is the depth SOURCE hosts read: `resolvePresentConfig().colorDepth`
+ * feeds straight into `attuneTheme({depth})` (quickdraw-layout). When no
+ * probe ran, the fallback is `guessColorDepth(env)` — an honest env read
+ * (NO_COLOR → mono included), never a blind "ansi256 is probably fine".
+ *
+ * Env:
+ *   QD_PROFILE=auto|local|ssh
+ *   QD_FPS=<number>            force present rate
+ *   QD_COLOR=auto|truecolor|ansi256|ansi16|mono
+ *   QD_FLOURISH=full|sparse|off
+ *   QD_SYNC=auto|0|1           (handled by host; config only prefers)
+ *   NO_COLOR=<any>             honored via guessColorDepth when unprobed
+ */
+import { type ColorDepth } from "../capabilities/index.js";
+export type Transport = "local" | "ssh";
+export type ProfileName = "auto" | "local" | "ssh";
+export type FlourishMode = "full" | "sparse" | "off";
+export type ColorMode = "auto" | "truecolor" | "ansi256" | "ansi16" | "mono";
+export type PresentConfig = {
+    /** Resolved transport class (never auto). */
+    profile: Transport;
+    targetFps: number;
+    colorDepth: ColorDepth;
+    flourish: FlourishMode;
+    /** Aesthetic clock Hz (braille / live tick). 0 = off. */
+    flourishHz: number;
+    /** Prefer DEC 2026 when terminal supports it. */
+    preferSync2026: boolean;
+    /** How colorDepth was chosen. */
+    colorSource: "forced" | "profile" | "probe" | "default";
+    /** Human summary for teardown log. */
+    label: string;
+};
+export type ResolvePresentOpts = {
+    env?: NodeJS.ProcessEnv;
+    /** Probed terminal depth (before demotion). */
+    probedDepth?: ColorDepth;
+    /** Probed sync 2026 support. */
+    probedSync2026?: boolean;
+};
+/** SSH-ish signals — default Profile S. */
+export declare function detectTransport(env?: NodeJS.ProcessEnv): Transport;
+/** Cap depth to a maximum (e.g. ssh caps truecolor → 256). */
+export declare function demoteDepth(have: ColorDepth, max: ColorDepth): ColorDepth;
+/** Aesthetic live-lane Hz (bgFx / birth / progress). Below this, stream chrome starves (glyphs freeze). */
+export declare const DEFAULT_FLOURISH_HZ = 30;
+/**
+ * Resolve present config from env + probe.
+ * Host applies preferSync2026 against actual probe flags separately.
+ */
+export declare function resolvePresentConfig(opts?: ResolvePresentOpts): PresentConfig;
+//# sourceMappingURL=present_profile.d.ts.map

package/dist/runtime/present_profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"present_profile.d.ts","sourceRoot":"","sources":["../../src/runtime/present_profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE5E,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AACxC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AACnD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE7E,MAAM,MAAM,aAAa,GAAG;IAC1B,6CAA6C;IAC7C,OAAO,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,cAAc,EAAE,OAAO,CAAC;IACxB,iCAAiC;IACjC,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxD,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,gCAAgC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,2CAA2C;AAC3C,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAQ/E;AA8BD,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,UAAU,CAEzE;AAED,2GAA2G;AAC3G,eAAO,MAAM,mBAAmB,KAAK,CAAC;AActC;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,aAAa,CA8CjF"}

package/dist/runtime/present_profile.js

@@ -0,0 +1,130 @@
+/**
+ * Present profiles — sexy under budget.
+ *
+ *   local → 120fps, truecolor, full flourish
+ *   ssh   → 30fps, ansi256 preferred, sparse flourish
+ *
+ * This is the depth SOURCE hosts read: `resolvePresentConfig().colorDepth`
+ * feeds straight into `attuneTheme({depth})` (quickdraw-layout). When no
+ * probe ran, the fallback is `guessColorDepth(env)` — an honest env read
+ * (NO_COLOR → mono included), never a blind "ansi256 is probably fine".
+ *
+ * Env:
+ *   QD_PROFILE=auto|local|ssh
+ *   QD_FPS=<number>            force present rate
+ *   QD_COLOR=auto|truecolor|ansi256|ansi16|mono
+ *   QD_FLOURISH=full|sparse|off
+ *   QD_SYNC=auto|0|1           (handled by host; config only prefers)
+ *   NO_COLOR=<any>             honored via guessColorDepth when unprobed
+ */
+import { guessColorDepth } from "../capabilities/index.js";
+/** SSH-ish signals — default Profile S. */
+export function detectTransport(env = process.env) {
+    if (env.QD_PROFILE === "local")
+        return "local";
+    if (env.QD_PROFILE === "ssh")
+        return "ssh";
+    // explicit auto / unset
+    if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY)
+        return "ssh";
+    // mosh / remote terminal hints
+    if (env.LC_SSH || env.REMOTEHOST)
+        return "ssh";
+    return "local";
+}
+function parseProfile(env) {
+    const v = (env.QD_PROFILE ?? "auto").toLowerCase();
+    if (v === "local" || v === "ssh" || v === "auto")
+        return v;
+    return "auto";
+}
+function parseFlourish(env, profile) {
+    const v = (env.QD_FLOURISH ?? "").toLowerCase();
+    if (v === "full" || v === "sparse" || v === "off")
+        return v;
+    return profile === "local" ? "full" : "sparse";
+}
+function parseColorMode(env) {
+    const v = (env.QD_COLOR ?? "auto").toLowerCase();
+    if (v === "auto" || v === "truecolor" || v === "ansi256" || v === "ansi16" || v === "mono") {
+        return v;
+    }
+    return "auto";
+}
+/** mono is the floor: never promoted by a max cap, never itself a cap that promotes color. */
+function depthRank(d) {
+    if (d === "truecolor")
+        return 3;
+    if (d === "ansi256")
+        return 2;
+    if (d === "ansi16")
+        return 1;
+    return 0;
+}
+/** Cap depth to a maximum (e.g. ssh caps truecolor → 256). */
+export function demoteDepth(have, max) {
+    return depthRank(have) <= depthRank(max) ? have : max;
+}
+/** Aesthetic live-lane Hz (bgFx / birth / progress). Below this, stream chrome starves (glyphs freeze). */
+export const DEFAULT_FLOURISH_HZ = 30;
+/**
+ * Live present host Hz (stream chrome + aesthetic clock injection).
+ * Default **30fps** for general live behaviors (DEFAULT_LIVE_HZ).
+ * Spinner glyphs still derive from wall clock at DEFAULT_SPIN_HZ inside paint
+ * when callers use spinTick — this rate is "how often live lane fires".
+ */
+function flourishHz(mode, profile) {
+    if (mode === "off")
+        return 0;
+    if (mode === "sparse")
+        return profile === "ssh" ? 15 : 20;
+    return profile === "local" ? DEFAULT_FLOURISH_HZ : 20;
+}
+/**
+ * Resolve present config from env + probe.
+ * Host applies preferSync2026 against actual probe flags separately.
+ */
+export function resolvePresentConfig(opts = {}) {
+    const env = opts.env ?? process.env;
+    const profileName = parseProfile(env);
+    const profile = profileName === "auto" ? detectTransport(env) : profileName;
+    const fpsEnv = env.QD_FPS?.trim();
+    const targetFps = fpsEnv
+        ? Math.max(1, Math.min(240, Number(fpsEnv) || (profile === "local" ? 120 : 30)))
+        : profile === "local"
+            ? 120
+            : 30;
+    const colorMode = parseColorMode(env);
+    const flourish = parseFlourish(env, profile);
+    // No probe run (host skipped detectCapabilities) → fall back to the same
+    // honest env guess capabilities uses, not a blind "ansi256 is probably
+    // fine": this is what lets NO_COLOR reach mono even without a TTY probe.
+    const probed = opts.probedDepth ?? guessColorDepth(env);
+    let colorDepth;
+    let colorSource;
+    if (colorMode !== "auto") {
+        colorDepth = colorMode;
+        colorSource = "forced";
+    }
+    else if (profile === "ssh") {
+        // SSH: cap at ansi256 even if terminal claims truecolor (wire budget)
+        colorDepth = demoteDepth(probed, "ansi256");
+        colorSource = opts.probedDepth ? "probe" : "profile";
+    }
+    else {
+        colorDepth = probed;
+        colorSource = opts.probedDepth ? "probe" : "default";
+    }
+    const preferSync2026 = env.QD_SYNC === "0" ? false : env.QD_SYNC === "1" ? true : opts.probedSync2026 !== false;
+    return {
+        profile,
+        targetFps,
+        colorDepth,
+        flourish,
+        flourishHz: flourishHz(flourish, profile),
+        preferSync2026,
+        colorSource,
+        label: `${profile}@${targetFps}fps ${colorDepth} flourish=${flourish}`,
+    };
+}
+//# sourceMappingURL=present_profile.js.map

package/dist/runtime/present_profile.js.map

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

package/dist/runtime/raster.d.ts

@@ -0,0 +1,24 @@
+import { type Buffer as CellBuffer } from "../buffer/index.js";
+import { type LayoutNode } from "../layout/index.js";
+/** Frozen clock for screenshots. Same epoch as storybook paint. */
+export declare const SCREENSHOT_NOW_MS = 1700000000000;
+export type RasterFrame = {
+    buffer: CellBuffer;
+    chars: string[];
+    groundHex: string;
+};
+export declare function rasterFrame(node: LayoutNode, cols: number, rows: number, opts?: {
+    nowMs?: number;
+    birth?: ReadonlyMap<string, number>;
+}): RasterFrame;
+export declare function rasterLayout(node: LayoutNode, cols: number, rows: number, opts?: {
+    nowMs?: number;
+    birth?: ReadonlyMap<string, number>;
+}): string[];
+/** Truecolor PNG of the product column. No TTY. */
+export declare function rasterPng(node: LayoutNode, cols: number, rows: number, opts?: {
+    nowMs?: number;
+    birth?: ReadonlyMap<string, number>;
+}): Buffer;
+export declare function bufferRows(buf: CellBuffer): string[];
+//# sourceMappingURL=raster.d.ts.map

package/dist/runtime/raster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raster.d.ts","sourceRoot":"","sources":["../../src/runtime/raster.ts"],"names":[],"mappings":"AAKA,OAAO,EAAuB,KAAK,MAAM,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGtF,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,gBAAoB,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GACjE,WAAW,CAWb;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GACjE,MAAM,EAAE,CAEV;AAED,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GACjE,MAAM,CAGR;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,EAAE,CAWpD"}

package/dist/runtime/raster.js

@@ -0,0 +1,43 @@
+/**
+ * Headless present: LayoutNode → cells. Screenshots force truecolor so
+ * CI NO_COLOR cannot demote the palette. Clock is frozen.
+ */
+import { bufferToPng } from "./screenshot.js";
+import { clear, createBuffer } from "../buffer/index.js";
+import { attuneTheme, layout, paintFrame } from "../layout/index.js";
+import { expandWidgetPriors } from "../widgets/expand.js";
+/** Frozen clock for screenshots. Same epoch as storybook paint. */
+export const SCREENSHOT_NOW_MS = 1_700_000_000_000;
+export function rasterFrame(node, cols, rows, opts = {}) {
+    const { paint, theme } = attuneTheme({ depth: "truecolor" });
+    const expanded = expandWidgetPriors(node, { width: cols });
+    const frame = layout(expanded, { w: cols, h: rows });
+    const buf = createBuffer(cols, rows);
+    clear(buf);
+    paintFrame(frame, buf, paint, {
+        nowMs: opts.nowMs ?? SCREENSHOT_NOW_MS,
+        birth: opts.birth,
+    });
+    return { buffer: buf, chars: bufferRows(buf), groundHex: theme.groundHex };
+}
+export function rasterLayout(node, cols, rows, opts = {}) {
+    return rasterFrame(node, cols, rows, opts).chars;
+}
+/** Truecolor PNG of the product column. No TTY. */
+export function rasterPng(node, cols, rows, opts = {}) {
+    const frame = rasterFrame(node, cols, rows, opts);
+    return bufferToPng(frame.buffer, frame.groundHex);
+}
+export function bufferRows(buf) {
+    const rows = [];
+    for (let y = 0; y < buf.height; y += 1) {
+        let row = "";
+        for (let x = 0; x < buf.width; x += 1) {
+            const cell = buf.cells[y * buf.width + x];
+            row += cell?.placeholder ? "" : (cell?.ch ?? " ");
+        }
+        rows.push(row.replace(/\s+$/u, ""));
+    }
+    return rows;
+}
+//# sourceMappingURL=raster.js.map

package/dist/runtime/raster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raster.js","sourceRoot":"","sources":["../../src/runtime/raster.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,YAAY,EAA6B,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAmB,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAQnD,MAAM,UAAU,WAAW,CACzB,IAAgB,EAChB,IAAY,EACZ,IAAY,EACZ,OAAgE,EAAE;IAElE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,WAAW,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,KAAK,CAAC,GAAG,CAAC,CAAC;IACX,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE;QAC5B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,iBAAiB;QACtC,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,IAAgB,EAChB,IAAY,EACZ,IAAY,EACZ,OAAgE,EAAE;IAElE,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,SAAS,CACvB,IAAgB,EAChB,IAAY,EACZ,IAAY,EACZ,OAAgE,EAAE;IAElE,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,OAAO,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAe;IACxC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAC1C,GAAG,IAAI,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runtime/renderer.d.ts

@@ -0,0 +1,151 @@
+import { type BoxBusDownMessage, type BoxBusUpMessage, type BoxMailbox } from "./box_bus.js";
+import { type PaintLocal, type RetainedPaintSource } from "./paint_source.js";
+import { type DraftState } from "../input/index.js";
+import { type ThemeAttuneOpts, type ThemeBinding } from "../layout/index.js";
+/** Lone-ESC hold before it counts as Escape (cannot tell Escape from a split CSI). */
+export declare const ESC_QUIET_MS = 30;
+/** Ceiling for live-demand presents (spinners, birth). Not an idle loop rate. */
+export declare const TARGET_FPS = 60;
+/**
+ * Drag-select present rate. Gesture state tracks every SGR cell; paint does not.
+ * Press/release still tick immediately (clear, copy, click). Knob if 30 is wrong.
+ */
+export declare const SELECTION_PAINT_HZ = 30;
+export interface TtyInput {
+    onData(handler: (chunk: string) => void): void;
+    setRawMode(enabled: boolean): void;
+}
+export interface TtyOutput {
+    write(text: string): void;
+    readonly cols: number;
+    readonly rows: number;
+    onResize(handler: () => void): void;
+}
+export interface PresentLoop {
+    stop(): void;
+}
+/**
+ * Paint mailbox port — product hosts adapt their lane envelope to this.
+ * Host-lane (failed/boot/quit) stays outside; only paint batch + up messages.
+ */
+/** Mailbox messages, plus paint_init as the ready signal (payload already applied). */
+export type CadenceDownItem = BoxBusDownMessage | {
+    readonly kind: "paint_init";
+};
+export interface BoxCadencePort {
+    post(message: BoxBusUpMessage): void;
+    /** Deliver paint batches (structure / box_set / box_free) and paint_init ready. */
+    onBatch(handler: (batch: readonly CadenceDownItem[]) => void): void;
+}
+export interface BoxCadenceHostOptions {
+    readonly port: BoxCadencePort;
+    readonly input: TtyInput;
+    readonly output: TtyOutput;
+    /** Ceiling for live-demand presents. Idle never ticks regardless. */
+    readonly targetFps?: number;
+    /**
+     * Aesthetic live-lane Hz (bgFx / birth / progress). Spinner `liveDemand.maxHz`
+     * is unchanged. Default {@link DEFAULT_FLOURISH_HZ}. `QD_FPS` stays the cap.
+     */
+    readonly flourishHz?: number;
+    /**
+     * Per-frame DEC 2026 bracket on emit. `fx` does this; a session-level
+     * `?2026h` without `?2026l` lets the terminal time out mid-paint and drop rows.
+     */
+    readonly sync2026?: boolean;
+    readonly onPresent?: (info: {
+        dirtyRows: number;
+        bytes: number;
+        reusedFrame: boolean;
+    }) => void;
+    /** Structure key for the composer content box (worker mints this id). */
+    readonly composerBoxKey?: string;
+    /** Layout key for the chrome_frame draft surface (caret park / click). */
+    readonly composerFrameKey?: string;
+    /**
+     * Clipboard body for Ctrl-V. Tests inject; production defaults to the OS
+     * clipboard, then last copy-on-select.
+     */
+    readonly readClipboard?: () => string;
+    /**
+     * Second Ctrl-C (first arms #quitArmed; other keys disarm). Lifecycle on UI
+     * thread — never a worker keymap chord.
+     */
+    readonly onQuit?: () => void;
+    /** Armed Ctrl-C hint. Default `"exit"`. Daemon sessions keep interpreting. */
+    readonly quitAction?: () => string;
+    /** First structure or paint_init — ready signal. Fired once. */
+    readonly onReady?: () => void;
+    readonly onFirstPaint?: () => void;
+    /**
+     * Retained paint source. tick calls prepare() first. A non-null root is
+     * the frame; a null root keeps the mailbox path.
+     */
+    readonly paintSource?: RetainedPaintSource;
+    /** One bag per TUI process. Cadence writes cols/rows; harness writes echo. */
+    readonly paintLocal?: PaintLocal;
+    /**
+     * Bound once by the caller (OSC 11 probe before alt screen). Explicit rather
+     * than ambient paintTheme() — default is "nothing measured", not silent ambient.
+     */
+    readonly theme?: ThemeBinding;
+}
+type BoxCadenceHostInit = BoxCadenceHostOptions & {
+    readonly now?: () => number;
+    readonly schedule?: (fn: () => void) => void;
+    readonly startLoop?: (opts: {
+        targetFps: number;
+        onFrame: (dtMs: number) => void;
+    }) => PresentLoop;
+};
+export declare class Renderer {
+    #private;
+    constructor(options: BoxCadenceHostInit);
+    get mailbox(): BoxMailbox;
+    start(): void;
+    /**
+     * Push a new canvas ground/depth. Theme is computed; the reaction drops
+     * cached RGB and (on polarity flip) the Frame so diffs re-highlight.
+     */
+    attune(opts: ThemeAttuneOpts): void;
+    /**
+     * Coalesced on-demand paint: any number of wakes inside one macrotask batch
+     * into a single tick on the next one. The wake sources are enumerated in
+     * the class preamble — nothing else may paint.
+     */
+    requestPaint(): void;
+    /** Stop paint/read. Does NOT restore the terminal — teardown owns that order. */
+    stop(): void;
+    /**
+     * Decode → translate → queue → deliver, even during boot.
+     * Bytes become events when carry state is correct; only delivery waits (F1).
+     */
+    onBytes(chunk: string): void;
+    onResize(cols: number, rows: number): void;
+    /**
+     * 1-based terminal cell → hit-test against painted frame.
+     * Fold is host-local; `intent: "activate"` posts `activate{key}` (innermost).
+     */
+    onClick(col: number, row: number): void;
+    /** Apply a paint-lane batch from the worker. */
+    onPaintBatch(batch: readonly CadenceDownItem[]): void;
+    /**
+     * Paint one frame now. Reached only through a wake source (requestPaint,
+     * live timer, a mouse press/release, or a throttled drag-select present).
+     * Held ESC gets a belt-and-braces flush here; its primary path is the
+     * one-shot quiet timer.
+     */
+    tick(): void;
+}
+/**
+ * Walk box value (stack or chrome_frame) for draft/cursor/mark.
+ *
+ * Slash mode stacks `slash-complete` (list panel with bodySegRows, empty draft)
+ * above `composer:frame`. Returning the first chrome_frame always hit the empty
+ * list panel — caret stayed at cell 0 while typing. Only the omnibox chrome_frame
+ * is the draft surface.
+ */
+export declare function readComposerInteractive(value: unknown, composerFrameKey?: string): boolean;
+export declare function readDraftState(value: unknown, composerFrameKey?: string): DraftState;
+export {};
+//# sourceMappingURL=renderer.d.ts.map

package/dist/runtime/renderer.d.ts.map

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