wotann 0.5.0 → 0.5.39

package/dist/ui/markdown-stream.js

@@ -0,0 +1,314 @@
+/**
+ * markdown-stream — fence-aware streaming markdown boundary detector
+ * + nested-fence normalizer.
+ *
+ * Ported from claw-code rusty-claude-cli render.rs lines 600-814.
+ *
+ * Why it exists
+ * -------------
+ * When LLM tokens stream in incrementally, partial code fences (an
+ * opening ``` without a closer yet) cause a markdown renderer to
+ * mis-render half-finished fences as inline content, then redraw them
+ * once the closer arrives. This module buffers tokens until a
+ * "fence-safe boundary" — a fully closed fence run, or a blank line
+ * outside any open fence — and only then releases a chunk ready to be
+ * rendered.
+ *
+ * `normalizeNestedFences` is a pre-pass that upgrades an outer ```
+ * fence to ```` (or longer) when the body contains triple-backtick
+ * runs of equal or greater length. CommonMark would otherwise treat
+ * the inner marker as the closer; this is the LLM-quoting-markdown
+ * case where the model writes a code block that itself contains a
+ * code block.
+ *
+ * Contract
+ * --------
+ * - Pure module — no side effects, no I/O. The caller owns rendering.
+ * - Methods on MarkdownStreamState are minimal and immutable in
+ *   spirit: each call returns the slice that became ready, plus the
+ *   updated pending buffer.
+ * - Tilde fences (`~~~`) and backtick fences (` ``` `) are tracked
+ *   independently — a backtick run cannot close a tilde-opened fence
+ *   and vice versa.
+ *
+ * API
+ * ---
+ *   class MarkdownStreamState
+ *     push(delta: string): { readyToFlush: string; pending: string }
+ *     flush(): string
+ *   findStreamSafeBoundary(buf: string): number  // 0 = not safe yet
+ *   normalizeNestedFences(markdown: string): string
+ */
+/**
+ * Streaming buffer that releases chunks only at fence-safe boundaries.
+ *
+ * Although the buffer itself is mutable (a single internal string),
+ * `push` and `flush` always return fresh primitives — there is no
+ * shared object the caller can accidentally mutate.
+ */
+export class MarkdownStreamState {
+    #pending = "";
+    /**
+     * Append a streamed delta and return whatever is now safe to render.
+     *
+     * - `readyToFlush` is empty when no safe boundary has been crossed
+     *   yet (e.g. while inside an open fence). The caller should hold
+     *   the chunk back until the next push that crosses a boundary.
+     * - `pending` is what is still being buffered. It is returned for
+     *   visibility / debugging; the caller does not need to feed it
+     *   back.
+     */
+    push(delta) {
+        this.#pending = this.#pending + delta;
+        const split = findStreamSafeBoundary(this.#pending);
+        if (split === 0) {
+            return { readyToFlush: "", pending: this.#pending };
+        }
+        const ready = this.#pending.slice(0, split);
+        this.#pending = this.#pending.slice(split);
+        return { readyToFlush: ready, pending: this.#pending };
+    }
+    /**
+     * Release any buffered content at the end of the stream. Returns
+     * "" when only whitespace was held (we don't want to emit pure
+     * whitespace as a final chunk).
+     */
+    flush() {
+        const remaining = this.#pending;
+        if (remaining.trim().length === 0) {
+            this.#pending = "";
+            return "";
+        }
+        this.#pending = "";
+        return remaining;
+    }
+    /** Visible for tests — current internal buffer. */
+    get pending() {
+        return this.#pending;
+    }
+}
+/**
+ * Find the byte index up to which the buffer can safely be sliced and
+ * emitted. Returns `0` when no safe boundary exists yet (the whole
+ * buffer must stay pending).
+ *
+ * A boundary is:
+ *   - the end of a line that closes a previously opened fence, OR
+ *   - the end of a blank line, when no fence is open.
+ *
+ * The buffer must be split by `\n`-inclusive lines so that the
+ * returned index points just past a newline — slicing there never
+ * cuts a line in half.
+ *
+ * Note: a value > 0 is always at a line boundary. A value of 0 means
+ * either the buffer is empty or no safe boundary has been observed.
+ */
+export function findStreamSafeBoundary(buf) {
+    if (buf.length === 0) {
+        return 0;
+    }
+    let openFence = null;
+    let lastBoundary = 0;
+    let cursor = 0;
+    while (cursor < buf.length) {
+        const nl = buf.indexOf("\n", cursor);
+        const lineEnd = nl === -1 ? buf.length : nl + 1;
+        const line = buf.slice(cursor, lineEnd);
+        const lineWithoutNewline = stripTrailingNewline(line);
+        if (openFence !== null) {
+            if (lineClosesFence(lineWithoutNewline, openFence)) {
+                openFence = null;
+                lastBoundary = lineEnd;
+            }
+            cursor = lineEnd;
+            continue;
+        }
+        const opener = parseFenceOpener(lineWithoutNewline);
+        if (opener !== null) {
+            openFence = opener;
+            cursor = lineEnd;
+            continue;
+        }
+        if (lineWithoutNewline.trim().length === 0) {
+            lastBoundary = lineEnd;
+        }
+        cursor = lineEnd;
+    }
+    return lastBoundary;
+}
+/**
+ * Upgrade outer fences whose bodies contain fences of equal or
+ * greater length. The rewrite makes the inner markers ordinary
+ * content so a CommonMark parser won't see them as the closer.
+ *
+ * Returns the original string when no rewrite is needed.
+ */
+export function normalizeNestedFences(markdown) {
+    if (markdown.length === 0) {
+        return markdown;
+    }
+    const lines = splitInclusive(markdown, "\n");
+    const fenceInfo = lines.map((l) => parseFenceLine(l));
+    const stack = [];
+    const pairs = [];
+    for (let i = 0; i < fenceInfo.length; i++) {
+        const fl = fenceInfo[i];
+        if (fl === null || fl === undefined) {
+            continue;
+        }
+        if (fl.hasInfo) {
+            stack.push({ lineIdx: i, fence: fl });
+            continue;
+        }
+        const top = stack[stack.length - 1];
+        const closesTop = top !== undefined && top.fence.char === fl.char && fl.len >= top.fence.len;
+        if (closesTop) {
+            const opener = stack.pop();
+            let innerMax = 0;
+            for (let j = opener.lineIdx + 1; j < i; j++) {
+                const inner = fenceInfo[j];
+                if (inner !== null && inner !== undefined && inner.len > innerMax) {
+                    innerMax = inner.len;
+                }
+            }
+            pairs.push({ opener: opener.lineIdx, closer: i, innerMax });
+        }
+        else {
+            stack.push({ lineIdx: i, fence: fl });
+        }
+    }
+    const rewrites = new Map();
+    for (const { opener, closer, innerMax } of pairs) {
+        const openerFl = fenceInfo[opener];
+        const closerFl = fenceInfo[closer];
+        if (openerFl === null || openerFl === undefined)
+            continue;
+        if (closerFl === null || closerFl === undefined)
+            continue;
+        if (openerFl.len > innerMax)
+            continue;
+        const newLen = innerMax + 1;
+        rewrites.set(opener, { char: openerFl.char, newLen, indent: openerFl.indent });
+        rewrites.set(closer, { char: closerFl.char, newLen, indent: closerFl.indent });
+    }
+    if (rewrites.size === 0) {
+        return markdown;
+    }
+    let out = "";
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const rw = rewrites.get(i);
+        if (rw === undefined) {
+            out += line;
+            continue;
+        }
+        const fi = fenceInfo[i];
+        const trimmed = stripTrailingNewline(line);
+        const info = trimmed.slice(fi.indent + fi.len);
+        const trailing = line.slice(trimmed.length);
+        const indentStr = " ".repeat(rw.indent);
+        const fenceStr = rw.char.repeat(rw.newLen);
+        out += indentStr + fenceStr + info + trailing;
+    }
+    return out;
+}
+// ---------- internals ----------
+function parseFenceOpener(line) {
+    const indent = countLeading(line, " ");
+    if (indent > 3) {
+        return null;
+    }
+    const rest = line.slice(indent);
+    const ch = rest.charAt(0);
+    if (ch !== "`" && ch !== "~") {
+        return null;
+    }
+    const length = countLeading(rest, ch);
+    if (length < 3) {
+        return null;
+    }
+    const infoString = rest.slice(length);
+    // Per CommonMark, a backtick fence's info string may not itself
+    // contain a backtick. Tilde fences are unrestricted.
+    if (ch === "`" && infoString.includes("`")) {
+        return null;
+    }
+    return { character: ch, length };
+}
+function lineClosesFence(line, opener) {
+    const indent = countLeading(line, " ");
+    if (indent > 3) {
+        return false;
+    }
+    const rest = line.slice(indent);
+    const length = countLeading(rest, opener.character);
+    if (length < opener.length) {
+        return false;
+    }
+    const tail = rest.slice(length);
+    for (let i = 0; i < tail.length; i++) {
+        const c = tail.charAt(i);
+        if (c !== " " && c !== "\t") {
+            return false;
+        }
+    }
+    return true;
+}
+function parseFenceLine(line) {
+    const trimmed = stripTrailingNewline(line).replace(/\r$/, "");
+    const indent = countLeading(trimmed, " ");
+    if (indent > 3) {
+        return null;
+    }
+    const rest = trimmed.slice(indent);
+    const ch = rest.charAt(0);
+    if (ch !== "`" && ch !== "~") {
+        return null;
+    }
+    const len = countLeading(rest, ch);
+    if (len < 3) {
+        return null;
+    }
+    const after = rest.slice(len);
+    if (ch === "`" && after.includes("`")) {
+        return null;
+    }
+    const hasInfo = after.trim().length > 0;
+    return { char: ch, len, hasInfo, indent };
+}
+function countLeading(s, ch) {
+    let n = 0;
+    while (n < s.length && s.charAt(n) === ch) {
+        n++;
+    }
+    return n;
+}
+function stripTrailingNewline(line) {
+    if (line.endsWith("\n")) {
+        return line.slice(0, -1);
+    }
+    return line;
+}
+/**
+ * Equivalent to Rust's `str::split_inclusive('\n')` — returns lines
+ * with their trailing newline preserved, and a final entry without a
+ * newline if the input does not end in one.
+ */
+function splitInclusive(s, sep) {
+    if (s.length === 0) {
+        return [];
+    }
+    const out = [];
+    let cursor = 0;
+    while (cursor < s.length) {
+        const idx = s.indexOf(sep, cursor);
+        if (idx === -1) {
+            out.push(s.slice(cursor));
+            break;
+        }
+        out.push(s.slice(cursor, idx + sep.length));
+        cursor = idx + sep.length;
+    }
+    return out;
+}
+//# sourceMappingURL=markdown-stream.js.map

package/dist/ui/markdown-stream.js.map

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

package/dist/ui/terminal-keyboard-protocol.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Kitty / CSI-u progressive enhancement keyboard protocol.
+ *
+ * On supported terminals (kitty, alacritty, wezterm, foot, recent
+ * iTerm2 with the setting enabled), enabling this protocol makes
+ * Ctrl+M, Ctrl+I, Ctrl+H, Ctrl+J distinguishable from Enter/Tab/etc.
+ * On unsupported terminals (Apple Terminal.app, classic xterm, most
+ * SSH-from-Windows setups), we leave the protocol disabled — sending
+ * the enable sequence is harmless (terminals ignore unknown CSI
+ * sequences) but adds zero value, and querying for support without
+ * a fallback risks corrupting input on hostile environments.
+ *
+ * Reference: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ */
+export type KeyboardProtocolMode = "kitty" | "default";
+export declare function detectKeyboardProtocolSupport(env?: NodeJS.ProcessEnv): KeyboardProtocolMode;
+/**
+ * Send the kitty enable sequence and return a cleanup function. No-op
+ * when mode is "default". Safe to call multiple times — the cleanup
+ * handle is idempotent.
+ */
+export declare function enableKeyboardProtocol(mode: KeyboardProtocolMode, out?: NodeJS.WriteStream): () => void;
+//# sourceMappingURL=terminal-keyboard-protocol.d.ts.map

package/dist/ui/terminal-keyboard-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-keyboard-protocol.d.ts","sourceRoot":"","sources":["../../src/ui/terminal-keyboard-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,wBAAgB,6BAA6B,CAC3C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,oBAAoB,CA6BtB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,oBAAoB,EAC1B,GAAG,GAAE,MAAM,CAAC,WAA4B,GACvC,MAAM,IAAI,CAiBZ"}

package/dist/ui/terminal-keyboard-protocol.js

@@ -0,0 +1,72 @@
+/**
+ * Kitty / CSI-u progressive enhancement keyboard protocol.
+ *
+ * On supported terminals (kitty, alacritty, wezterm, foot, recent
+ * iTerm2 with the setting enabled), enabling this protocol makes
+ * Ctrl+M, Ctrl+I, Ctrl+H, Ctrl+J distinguishable from Enter/Tab/etc.
+ * On unsupported terminals (Apple Terminal.app, classic xterm, most
+ * SSH-from-Windows setups), we leave the protocol disabled — sending
+ * the enable sequence is harmless (terminals ignore unknown CSI
+ * sequences) but adds zero value, and querying for support without
+ * a fallback risks corrupting input on hostile environments.
+ *
+ * Reference: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ */
+export function detectKeyboardProtocolSupport(env = process.env) {
+    // Explicit env overrides win over auto-detection. Opt-out comes
+    // first, so a user whose tmux multiplexer doesn't pass through the
+    // protocol can disable it even when running under kitty/wezterm/etc.
+    if (env["WOTANN_KITTY_KEYBOARD"] === "0")
+        return "default";
+    // Explicit opt-in, for users who know their terminal supports it
+    // and want to override the conservative default.
+    if (env["WOTANN_KITTY_KEYBOARD"] === "1")
+        return "kitty";
+    // Conservative: only enable on terminals KNOWN to support it AND
+    // implement the protocol cleanly. Unknown terminals get default.
+    const term = env["TERM"] ?? "";
+    const termProgram = env["TERM_PROGRAM"] ?? "";
+    const lcTerm = env["LC_TERMINAL"] ?? "";
+    // Confirmed-good terminals
+    if (termProgram === "kitty" || term.includes("kitty"))
+        return "kitty";
+    if (termProgram === "WezTerm" || term.includes("wezterm"))
+        return "kitty";
+    if (term.startsWith("alacritty"))
+        return "kitty";
+    if (term === "foot" || term.includes("foot-"))
+        return "kitty";
+    if (lcTerm === "ghostty" || termProgram === "ghostty")
+        return "kitty";
+    // iTerm2 supports it from build 3.5+ but only when the user enables
+    // "Report modifiers using CSI u" in Profile > Keys. We can't probe
+    // that without a roundtrip, so default to "default" — Ctrl+O / Ctrl+X
+    // already work on iTerm2 and the cost of NOT enabling here is just
+    // muscle-memory loss for power users (they can override via env).
+    return "default";
+}
+/**
+ * Send the kitty enable sequence and return a cleanup function. No-op
+ * when mode is "default". Safe to call multiple times — the cleanup
+ * handle is idempotent.
+ */
+export function enableKeyboardProtocol(mode, out = process.stdout) {
+    if (mode !== "kitty")
+        return () => { };
+    if (!out.isTTY)
+        return () => { };
+    // Push a new keyboard mode (flag 1 = disambiguate escape codes).
+    // The push/pop semantics mean we don't clobber a parent process's
+    // mode if WOTANN is invoked from a terminal multiplexer that already
+    // uses the protocol.
+    out.write("\x1b[>1u");
+    let cleaned = false;
+    return () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        // Pop our mode off the stack.
+        out.write("\x1b[<u");
+    };
+}
+//# sourceMappingURL=terminal-keyboard-protocol.js.map

package/dist/ui/terminal-keyboard-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-keyboard-protocol.js","sourceRoot":"","sources":["../../src/ui/terminal-keyboard-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,UAAU,6BAA6B,CAC3C,MAAyB,OAAO,CAAC,GAAG;IAEpC,gEAAgE;IAChE,mEAAmE;IACnE,qEAAqE;IACrE,IAAI,GAAG,CAAC,uBAAuB,CAAC,KAAK,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3D,iEAAiE;IACjE,iDAAiD;IACjD,IAAI,GAAG,CAAC,uBAAuB,CAAC,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC;IAEzD,iEAAiE;IACjE,iEAAiE;IACjE,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IAExC,2BAA2B;IAC3B,IAAI,WAAW,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACtE,IAAI,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1E,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC9D,IAAI,MAAM,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAEtE,oEAAoE;IACpE,mEAAmE;IACnE,sEAAsE;IACtE,mEAAmE;IACnE,kEAAkE;IAElE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAA0B,EAC1B,MAA0B,OAAO,CAAC,MAAM;IAExC,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IACtC,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAEhC,iEAAiE;IACjE,kEAAkE;IAClE,qEAAqE;IACrE,qBAAqB;IACrB,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAEtB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,OAAO,GAAG,EAAE;QACV,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,8BAA8B;QAC9B,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/ui/theme/context.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Theme React context — single source of truth for the active palette.
+ *
+ * Pre-2026-05-03, every component hardcoded `buildTone(PALETTES.dark)`.
+ * Switching themes via Ctrl+Y / `/theme` updated `App.tsx` state but
+ * leaf components ignored it because they re-read the dark palette
+ * unconditionally. User report: "themes don't apply everywhere in the
+ * TUI" — this fixes that by threading the active palette through
+ * context so every `useThemeTone()` call resolves to the live palette.
+ *
+ * Why context not props: ~20 leaf components ranging from StatusBar
+ * to MemoryInspector to OptionPicker need the active tone. Prop-
+ * drilling through Box / Static / wrapper layers creates churn on
+ * every refactor. Context is the standard React pattern for cross-
+ * cutting design tokens, and Ink supports it natively.
+ *
+ * Performance: the provider memoises tone+palette together; consumer
+ * components only re-render when the palette identity changes (which
+ * happens on `/theme switch`, not on every state update).
+ */
+import React from "react";
+import { type Palette } from "../themes.js";
+import { type Tone } from "./tokens.js";
+interface ThemeContextValue {
+    readonly palette: Palette;
+    readonly tone: Tone;
+}
+export declare function ThemeProvider({ palette, children, }: {
+    readonly palette: Palette;
+    readonly children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * Read the active palette + tone from context. Use this in any leaf
+ * UI component instead of `buildTone(PALETTES.dark)` so theme cycling
+ * propagates to the whole tree.
+ */
+export declare function useThemeTone(): ThemeContextValue;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/ui/theme/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/ui/theme/context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAA6C,MAAM,OAAO,CAAC;AAClE,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnD,UAAU,iBAAiB;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AASD,wBAAgB,aAAa,CAAC,EAC5B,OAAO,EACP,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CACpC,GAAG,KAAK,CAAC,YAAY,CAMrB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,iBAAiB,CAEhD"}

package/dist/ui/theme/context.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Theme React context — single source of truth for the active palette.
+ *
+ * Pre-2026-05-03, every component hardcoded `buildTone(PALETTES.dark)`.
+ * Switching themes via Ctrl+Y / `/theme` updated `App.tsx` state but
+ * leaf components ignored it because they re-read the dark palette
+ * unconditionally. User report: "themes don't apply everywhere in the
+ * TUI" — this fixes that by threading the active palette through
+ * context so every `useThemeTone()` call resolves to the live palette.
+ *
+ * Why context not props: ~20 leaf components ranging from StatusBar
+ * to MemoryInspector to OptionPicker need the active tone. Prop-
+ * drilling through Box / Static / wrapper layers creates churn on
+ * every refactor. Context is the standard React pattern for cross-
+ * cutting design tokens, and Ink supports it natively.
+ *
+ * Performance: the provider memoises tone+palette together; consumer
+ * components only re-render when the palette identity changes (which
+ * happens on `/theme switch`, not on every state update).
+ */
+import { createContext, useContext, useMemo } from "react";
+import { PALETTES } from "../themes.js";
+import { buildTone } from "./tokens.js";
+const DEFAULT_VALUE = {
+    palette: PALETTES.dark,
+    tone: buildTone(PALETTES.dark),
+};
+const ThemeContext = createContext(DEFAULT_VALUE);
+export function ThemeProvider({ palette, children, }) {
+    const value = useMemo(() => ({ palette, tone: buildTone(palette) }), [palette]);
+    return _jsx(ThemeContext.Provider, { value: value, children: children });
+}
+/**
+ * Read the active palette + tone from context. Use this in any leaf
+ * UI component instead of `buildTone(PALETTES.dark)` so theme cycling
+ * propagates to the whole tree.
+ */
+export function useThemeTone() {
+    return useContext(ThemeContext);
+}
+//# sourceMappingURL=context.js.map

package/dist/ui/theme/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/ui/theme/context.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAc,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAgB,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,SAAS,EAAa,MAAM,aAAa,CAAC;AAOnD,MAAM,aAAa,GAAsB;IACvC,OAAO,EAAE,QAAQ,CAAC,IAAI;IACtB,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;CAC/B,CAAC;AAEF,MAAM,YAAY,GAAG,aAAa,CAAoB,aAAa,CAAC,CAAC;AAErE,MAAM,UAAU,aAAa,CAAC,EAC5B,OAAO,EACP,QAAQ,GAIT;IACC,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,EAC7C,CAAC,OAAO,CAAC,CACV,CAAC;IACF,OAAO,KAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAyB,CAAC;AACjF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC;AAClC,CAAC"}

package/dist/utils/platform.d.ts

@@ -0,0 +1,115 @@
+/**
+ * platform — single source of truth for OS-aware system calls.
+ *
+ * WOTANN runs on macOS, Linux, AND Windows. POSIX assumptions
+ * scattered across the codebase (hardcoded `bash`, `/bin/sh`,
+ * `which`, literal `/tmp`, `process.env.HOME`, `:` PATH separator)
+ * silently break on Windows. This module centralizes the
+ * platform branches so callers route everything through one
+ * helper instead of duplicating `process.platform === "win32"`
+ * checks at every call site.
+ *
+ * Quality bars:
+ *   - Pure functions (no module-level state, no env mutation)
+ *   - Frozen return objects for shape stability
+ *   - Tests live in tests/utils/platform.test.ts and exercise
+ *     win32/darwin/linux branches via explicit overrides
+ */
+export type SupportedPlatform = NodeJS.Platform;
+export interface PlatformShell {
+    /** The shell binary to invoke (e.g. "cmd.exe" or "/bin/sh"). */
+    readonly cmd: string;
+    /**
+     * Argument prefix for `execFile`/`spawn`. Combine with the actual
+     * command via a single trailing string argument so shell injection
+     * surface stays minimal. e.g. `[...args, "echo hello"]`.
+     */
+    readonly args: readonly string[];
+}
+/**
+ * Resolve the appropriate shell for the current platform.
+ *
+ * On Windows, returns cmd.exe with /c so callers can pass a single
+ * command string. POSIX systems use /bin/sh -c by default; bash is
+ * preferred when explicitly available but /bin/sh is the POSIX
+ * lowest-common-denominator (avoids "bash not on PATH" failures on
+ * minimal containers).
+ *
+ * Callers that need bash specifically (e.g. for arrays, [[ ]],
+ * process substitution) should branch on `process.platform` AND
+ * verify `bash` is on PATH via `whichBinary("bash")` first.
+ */
+export declare function getPlatformShell(platformOverride?: SupportedPlatform): PlatformShell;
+/**
+ * Build the argv for executing a single shell command portably.
+ * Returns the full argv ready to pass to `execFile` / `spawn`.
+ */
+export declare function buildShellCommand(command: string, platformOverride?: SupportedPlatform): {
+    readonly file: string;
+    readonly argv: readonly string[];
+};
+/**
+ * Return the OS-appropriate "which" binary name. Windows ships
+ * `where.exe`; POSIX has `which` on PATH by default.
+ *
+ * Callers should invoke this and check exit code rather than parsing
+ * stdout — the `where`/`which` output formats differ (where emits
+ * absolute paths separated by CRLF; which emits one path per line).
+ */
+export declare function whichBinary(platformOverride?: SupportedPlatform): "where" | "which";
+/**
+ * PATH list separator. POSIX uses `:`, Windows uses `;`. Centralized
+ * here so callers never inline the literal — that's a class of bug
+ * the prior audit caught at src/sandbox/extended-backends.ts:176.
+ */
+export declare function getPathDelimiter(platformOverride?: SupportedPlatform): ":" | ";";
+/**
+ * Re-export from `node:path` for callers that want the canonical
+ * separator without re-importing node:path. Identical to
+ * `getPathDelimiter()` on every modern Node.
+ */
+export declare const PATH_DELIMITER: string;
+/**
+ * Resolve the user's home directory, OS-aware. `process.env.HOME`
+ * is empty on Windows by default — Node's `os.homedir()` reads from
+ * USERPROFILE on Windows and HOME elsewhere.
+ */
+export declare function getHomeDir(): string;
+/**
+ * Resolve the OS-appropriate temp directory. Hardcoded `/tmp`
+ * literals fail on Windows; `process.env.TMPDIR` is POSIX-only.
+ * Node's `os.tmpdir()` is the canonical source.
+ */
+export declare function getTempDir(): string;
+/**
+ * Best-effort chmod wrapper. POSIX file modes are meaningless on
+ * Windows FAT/exFAT; the SDK throws EINVAL/ENOSYS on those layers.
+ * Wraps the sync chmod in a try/catch so callers don't have to.
+ *
+ * Returns true when chmod succeeded, false when it threw — callers
+ * that need to confirm POSIX-mode semantics should branch on the
+ * return value. For pure "let me try to make this executable"
+ * use-cases, the return value can be ignored.
+ */
+export declare function chmodBestEffort(fs: {
+    chmodSync: (path: string, mode: number) => void;
+}, filePath: string, mode: number): boolean;
+/**
+ * Resolve the platform-specific name of a Node tooling binary. On
+ * Windows, npm/npx/yarn/pnpm install as `.cmd` shims (e.g. npx.cmd)
+ * which spawnSync/execFile MUST receive literally — bare "npx" ENOENTs.
+ * On POSIX the bare name resolves via PATH.
+ */
+export declare function nodeToolBinary(name: "npx" | "npm" | "yarn" | "pnpm" | "tsc", platformOverride?: SupportedPlatform): string;
+/**
+ * Convenience predicate for branches that need to know "are we on
+ * Windows right now". Equivalent to `process.platform === "win32"`
+ * but accepts an override for tests.
+ */
+export declare function isWindows(platformOverride?: SupportedPlatform): boolean;
+/**
+ * Convenience predicate for macOS. Used by macOS-only paths like
+ * the seatbelt sandbox executor.
+ */
+export declare function isMacOS(platformOverride?: SupportedPlatform): boolean;
+//# sourceMappingURL=platform.d.ts.map

package/dist/utils/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/utils/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAYpF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,iBAAiB,GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAM7D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAGnF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,GAAG,GAAG,GAAG,CAGhF;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,MAAsB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE;IAAE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACvD,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,EAC7C,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAGvE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAGrE"}