@askalf/dario 3.38.6 → 4.0.0

package/dist/config-file.js

@@ -0,0 +1,326 @@
+/**
+ * Config file foundation — v4.
+ *
+ * Persists user-tunable settings to `~/.dario/config.json` so the TUI
+ * can read + write them without having to manage shell scripts. Establishes
+ * the precedence chain that every effective value passes through:
+ *
+ *   defaults  <  config.json  <  env var  <  CLI flag
+ *
+ * Existing CLI flags + env vars continue to work unchanged. The config
+ * file is purely additive — a missing file resolves to defaults, exactly
+ * as v3 already behaved (since v3 had no config file).
+ *
+ * Atomic write: write to `config.json.tmp`, fsync, rename. Same primitive
+ * shape `atomicWriteJson` in src/live-fingerprint.ts uses for the
+ * captured CC template.
+ *
+ * Unknown keys in the loaded file are preserved (forward-compat for
+ * future schema versions); validation is best-effort, not strict — a
+ * corrupt or partial file falls back to defaults rather than aborting
+ * the process.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Bumped on any incompatible shape change. v4.0.0 ships schema v1. A
+ * future shape change would either add a new optional field (no bump)
+ * or rename / restructure (bump to v2 with a migration in `loadConfig`).
+ */
+export const CONFIG_SCHEMA_VERSION = 1;
+/**
+ * Default `~/.dario/config.json` location. Override in tests via
+ * `loadConfig(path)` / `saveConfig(path, …)`.
+ */
+export const DEFAULT_CONFIG_PATH = join(homedir(), '.dario', 'config.json');
+/**
+ * Defaults match the v3.x CLI flag defaults exactly. Any value not
+ * specified in config.json resolves to its corresponding default here.
+ * Updates to a flag default MUST land here too so they stay in sync.
+ */
+export function defaultConfig() {
+    return {
+        version: CONFIG_SCHEMA_VERSION,
+        port: 3456,
+        host: '127.0.0.1',
+        model: null,
+        passthrough: false,
+        preserveTools: false,
+        hybridTools: false,
+        mergeTools: false,
+        noAutoDetect: false,
+        strictTls: false,
+        strictTemplate: false,
+        noLiveCapture: false,
+        drainOnClose: false,
+        stealth: false,
+        pacing: { minMs: 500, jitterMs: 0 },
+        thinkTime: { baseMs: 0, perTokenMs: 0, jitterMs: 0, maxMs: 30_000 },
+        sessionStart: { minMs: 0, jitterMs: 0 },
+        session: {
+            idleRotateMs: 900_000,
+            rotateJitterMs: 0,
+            maxAgeMs: null,
+            perClient: false,
+        },
+        queue: { maxConcurrent: null, maxQueued: null, timeoutMs: null },
+        effort: null,
+        maxTokens: null,
+        passthroughBetas: [],
+        systemPrompt: null,
+        preserveOrchestrationTags: false,
+        logFile: null,
+    };
+}
+/**
+ * Load the config file at `path` (default ~/.dario/config.json).
+ *
+ * Returns `{ config, source }` where `source` describes the load outcome
+ * for the caller's UI:
+ *
+ *   - 'file'    — successfully loaded
+ *   - 'missing' — file doesn't exist; defaults returned (not an error)
+ *   - 'invalid' — file exists but parse / shape check failed; defaults
+ *                 returned. The TUI surfaces this so the user knows
+ *                 their saved settings were ignored.
+ *
+ * The loaded shape is type-checked field-by-field: unknown keys pass
+ * through (forward-compat), known keys with wrong types are dropped.
+ * Strict validation would force a config migration on every shape
+ * tweak; loose-but-typed lets the file evolve without breaking older
+ * dario installs that haven't been restarted.
+ */
+export function loadConfig(path = DEFAULT_CONFIG_PATH) {
+    if (!existsSync(path)) {
+        return { config: defaultConfig(), source: 'missing' };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        return {
+            config: defaultConfig(),
+            source: 'invalid',
+            error: `read failed: ${err.message}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            config: defaultConfig(),
+            source: 'invalid',
+            error: `JSON parse failed: ${err.message}`,
+        };
+    }
+    if (!isPlainObject(parsed)) {
+        return {
+            config: defaultConfig(),
+            source: 'invalid',
+            error: `top-level value is not an object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`,
+        };
+    }
+    // Future schema bumps: dispatch on parsed.version here and run the
+    // appropriate migration. For now we accept any version field but
+    // pass the rest through field-by-field validation.
+    const typed = sanitize(parsed);
+    // Merge over defaults so callers always get a fully-populated shape.
+    return {
+        config: mergeOver(defaultConfig(), typed),
+        source: 'file',
+    };
+}
+/**
+ * Atomically write `config` to `path`. Writes to `<path>.tmp`, then
+ * renames into place — guarantees a reader never observes a half-written
+ * file. Creates parent directories if missing.
+ *
+ * Throws on permission / disk failures (caller handles + surfaces to
+ * the TUI's status line). Does NOT throw on a no-op rewrite of the
+ * same content; that's a cheap idempotent path.
+ */
+export function saveConfig(path = DEFAULT_CONFIG_PATH, config) {
+    const parent = dirname(path);
+    if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true, mode: 0o700 });
+    }
+    const json = JSON.stringify({ ...config, version: CONFIG_SCHEMA_VERSION }, null, 2) + '\n';
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    try {
+        writeFileSync(tmp, json, { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        // Best-effort cleanup of the temp file so we don't leave debris.
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/**
+ * Deep-merge `over` into `base`, preferring `over` values where defined.
+ * Nested objects are merged recursively; arrays and primitives are
+ * replaced wholesale (no array-element merge — that'd be surprising).
+ *
+ * `undefined` in `over` is treated as "absent" and falls through to
+ * the `base` value. `null` is a real value and overrides.
+ */
+export function mergeOver(base, over) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over)) {
+        if (v === undefined)
+            continue;
+        if (isPlainObject(v) && isPlainObject(out[k])) {
+            // Recurse into nested object groups (pacing, thinkTime, …) so a
+            // partial override on one sub-field doesn't wipe siblings.
+            out[k] = mergeOver(out[k], v);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the effective config: load file, layer env vars on top, layer
+ * CLI flags on top.
+ *
+ *   defaults  <  config.json  <  env  <  cli
+ *
+ * `cliOverrides` and `envOverrides` are partial — only the keys the
+ * caller actually wants to override should be set. `undefined` keys
+ * are skipped, so the existing flag parsers in cli.ts can pass through
+ * their normalized output without filtering nulls.
+ */
+export function resolveConfig(opts) {
+    const fromFile = loadConfig(opts.path);
+    const withEnv = mergeOver(fromFile.config, opts.envOverrides ?? {});
+    const withCli = mergeOver(withEnv, opts.cliOverrides ?? {});
+    return { ...fromFile, config: withCli };
+}
+// ── internals ────────────────────────────────────────────────────────
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Field-by-field type-check. Drops keys whose values don't match the
+ * expected type — better to silently fall back to a default than to
+ * abort startup on a stray manually-edited typo. Unknown top-level
+ * keys pass through unchanged (forward-compat for future fields).
+ */
+function sanitize(parsed) {
+    const out = { version: CONFIG_SCHEMA_VERSION };
+    const pickNumber = (k) => typeof parsed[k] === 'number' && Number.isFinite(parsed[k]) ? parsed[k] : undefined;
+    const pickBool = (k) => typeof parsed[k] === 'boolean' ? parsed[k] : undefined;
+    const pickString = (k) => typeof parsed[k] === 'string' ? parsed[k] : undefined;
+    const pickStringOrNull = (k) => {
+        if (parsed[k] === null)
+            return null;
+        if (typeof parsed[k] === 'string')
+            return parsed[k];
+        return undefined;
+    };
+    const pickNumberOrNull = (k) => {
+        if (parsed[k] === null)
+            return null;
+        if (typeof parsed[k] === 'number' && Number.isFinite(parsed[k]))
+            return parsed[k];
+        return undefined;
+    };
+    if (typeof parsed.version === 'number')
+        out.version = parsed.version;
+    if (pickNumber('port') !== undefined)
+        out.port = pickNumber('port');
+    if (pickString('host') !== undefined)
+        out.host = pickString('host');
+    const model = pickStringOrNull('model');
+    if (model !== undefined)
+        out.model = model;
+    for (const k of ['passthrough', 'preserveTools', 'hybridTools', 'mergeTools',
+        'noAutoDetect', 'strictTls', 'strictTemplate', 'noLiveCapture',
+        'drainOnClose', 'stealth', 'preserveOrchestrationTags']) {
+        const v = pickBool(k);
+        // Each `k` is a literal boolean-typed field on DarioConfig (verified
+        // by the `as const` tuple type above), so the assignment is sound
+        // — we route through `unknown` because TS can't narrow the union
+        // of literal keys to a single typed assignment at compile time.
+        if (v !== undefined)
+            out[k] = v;
+    }
+    // Nested groups — sanitize each, drop if not an object
+    if (isPlainObject(parsed.pacing)) {
+        out.pacing = {};
+        if (typeof parsed.pacing.minMs === 'number')
+            out.pacing.minMs = parsed.pacing.minMs;
+        if (typeof parsed.pacing.jitterMs === 'number')
+            out.pacing.jitterMs = parsed.pacing.jitterMs;
+    }
+    if (isPlainObject(parsed.thinkTime)) {
+        out.thinkTime = {};
+        for (const k of ['baseMs', 'perTokenMs', 'jitterMs', 'maxMs']) {
+            if (typeof parsed.thinkTime[k] === 'number') {
+                out.thinkTime[k] = parsed.thinkTime[k];
+            }
+        }
+    }
+    if (isPlainObject(parsed.sessionStart)) {
+        out.sessionStart = {};
+        if (typeof parsed.sessionStart.minMs === 'number')
+            out.sessionStart.minMs = parsed.sessionStart.minMs;
+        if (typeof parsed.sessionStart.jitterMs === 'number')
+            out.sessionStart.jitterMs = parsed.sessionStart.jitterMs;
+    }
+    if (isPlainObject(parsed.session)) {
+        out.session = {};
+        if (typeof parsed.session.idleRotateMs === 'number')
+            out.session.idleRotateMs = parsed.session.idleRotateMs;
+        if (typeof parsed.session.rotateJitterMs === 'number')
+            out.session.rotateJitterMs = parsed.session.rotateJitterMs;
+        if (parsed.session.maxAgeMs === null || typeof parsed.session.maxAgeMs === 'number') {
+            out.session.maxAgeMs = parsed.session.maxAgeMs;
+        }
+        if (typeof parsed.session.perClient === 'boolean')
+            out.session.perClient = parsed.session.perClient;
+    }
+    if (isPlainObject(parsed.queue)) {
+        out.queue = {};
+        for (const k of ['maxConcurrent', 'maxQueued', 'timeoutMs']) {
+            const v = parsed.queue[k];
+            if (v === null || (typeof v === 'number' && Number.isFinite(v))) {
+                out.queue[k] = v;
+            }
+        }
+    }
+    const effort = pickStringOrNull('effort');
+    if (effort !== undefined)
+        out.effort = effort;
+    // maxTokens is special — it's a number, the string 'client', or null
+    if (parsed.maxTokens === null)
+        out.maxTokens = null;
+    else if (parsed.maxTokens === 'client')
+        out.maxTokens = 'client';
+    else {
+        const n = pickNumber('maxTokens');
+        if (n !== undefined)
+            out.maxTokens = n;
+    }
+    if (Array.isArray(parsed.passthroughBetas)) {
+        out.passthroughBetas = parsed.passthroughBetas
+            .filter((x) => typeof x === 'string');
+    }
+    const sysPrompt = pickStringOrNull('systemPrompt');
+    if (sysPrompt !== undefined)
+        out.systemPrompt = sysPrompt;
+    const logFile = pickStringOrNull('logFile');
+    if (logFile !== undefined)
+        out.logFile = logFile;
+    // Silence unused-warning helper.
+    void pickNumberOrNull;
+    return out;
+}

package/dist/proxy.js

@@ -567,7 +567,12 @@ export async function startProxy(opts = {}) {
     // eventual `7d_opus`) doesn't slip past unnoticed. Pure observability —
     // routing already handles unknown families generically.
     const seenPerModelBuckets = new Set();
-    const analytics = pool ? new Analytics() : null;
+    // v4 promotion: analytics is always-on so the TUI's Analytics + Hits
+    // tabs work in both pool and single-account mode. Pre-v4 this was
+    // `pool ? new Analytics() : null` — that gated the /analytics
+    // endpoint, but burn-rate / per-request visibility is useful for
+    // single-account users too.
+    const analytics = new Analytics();
     let status;
     if (pool) {
         for (const acc of accountsList) {
@@ -912,17 +917,70 @@ export async function startProxy(opts = {}) {
             }));
             return;
         }
-        // Analytics endpoint — request history + burn-rate summary (pool mode only).
+        // Analytics endpoint — rolling-window summary + burn-rate snapshot.
+        // Always-on as of v4 (pre-v4 this was gated to pool mode).
         if (urlPath === '/analytics' && req.method === 'GET') {
-            if (!analytics) {
-                res.writeHead(200, JSON_HEADERS);
-                res.end(JSON.stringify({ mode: 'single-account', note: 'Analytics are only collected in pool mode.' }));
-                return;
-            }
             res.writeHead(200, JSON_HEADERS);
             res.end(JSON.stringify(analytics.summary()));
             return;
         }
+        // Analytics live stream — SSE of new RequestRecord JSON, one event
+        // per record as it lands. Drives the v4 TUI's Hits tab. Sends a
+        // backlog of the most-recent 50 records on connect so a freshly-
+        // attached subscriber sees state immediately, then live-tails.
+        //
+        // Auth: same as /analytics — no auth in single-account default mode;
+        // the proxy listens on loopback by default. DARIO_API_KEY users
+        // get rejected by the earlier auth gate up the handler chain.
+        //
+        // Disconnect handling: the 'close' event on `req` removes our
+        // listener from the Analytics EventEmitter so we don't leak.
+        if (urlPath === '/analytics/stream' && req.method === 'GET') {
+            // SECURITY_HEADERS sets Cache-Control: no-store; SSE wants
+            // no-cache, no-transform. Spread SECURITY_HEADERS first then
+            // override the cache directive — order matters since spread
+            // overlap is last-wins in JS.
+            const sseHeaders = {
+                ...SECURITY_HEADERS,
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache, no-transform',
+                'Connection': 'keep-alive',
+                'X-Accel-Buffering': 'no', // disable any proxy buffering
+                'Access-Control-Allow-Origin': corsOrigin,
+            };
+            res.writeHead(200, sseHeaders);
+            // Backlog: replay recent records so a TUI attaching mid-session
+            // sees something. 50 is a soft default; lots of room to send more
+            // since this is one-time on connect.
+            for (const past of analytics.recent(50)) {
+                res.write(`data: ${JSON.stringify(past)}\n\n`);
+            }
+            // Live tail
+            const onRecord = (r) => {
+                // Use try/catch so a broken socket (peer hung up between events)
+                // doesn't crash the request hot-path — Analytics already wraps
+                // its emit in try/catch but the .write itself can also throw.
+                try {
+                    res.write(`data: ${JSON.stringify(r)}\n\n`);
+                }
+                catch { /* ignored */ }
+            };
+            analytics.on('record', onRecord);
+            // Heartbeat every 25s — SSE comments are ignored by clients but
+            // keep middle-boxes (CDNs, dev-proxies) from closing the pipe.
+            const heartbeat = setInterval(() => {
+                try {
+                    res.write(`: heartbeat ${Date.now()}\n\n`);
+                }
+                catch { /* ignored */ }
+            }, 25_000);
+            heartbeat.unref?.();
+            req.on('close', () => {
+                analytics.off('record', onRecord);
+                clearInterval(heartbeat);
+            });
+            return;
+        }
         if (urlPath === '/v1/models' && req.method === 'GET') {
             requestCount++;
             res.writeHead(200, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin });
@@ -1585,12 +1643,19 @@ export async function startProxy(opts = {}) {
                             }
                         }
                         requestCount++;
-                        if (analytics && poolAccount) {
+                        // v4: analytics is always-on. Pool mode supplies the rate-limit
+                        // snapshot from `poolAccount.rateLimit` (already authoritative);
+                        // single-account mode parses it from the upstream response
+                        // headers on the spot so the TUI's Hits feed shows the same
+                        // bucket / utilization fields in both modes.
+                        {
+                            const rl = poolAccount?.rateLimit ?? parseRateLimits(upstream.headers);
                             analytics.record({
-                                timestamp: Date.now(), account: poolAccount.alias, model: requestModel,
+                                timestamp: Date.now(),
+                                account: poolAccount?.alias ?? ACCOUNT_KEY_SINGLE,
+                                model: requestModel,
                                 inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0, thinkingTokens: 0,
-                                claim: poolAccount.rateLimit.claim, util5h: poolAccount.rateLimit.util5h,
-                                util7d: poolAccount.rateLimit.util7d, overageUtil: poolAccount.rateLimit.overageUtil,
+                                claim: rl.claim, util5h: rl.util5h, util7d: rl.util7d, overageUtil: rl.overageUtil,
                                 latencyMs: Date.now() - startTime, status: 429, isStream: false, isOpenAI,
                             });
                         }
@@ -1669,12 +1734,14 @@ export async function startProxy(opts = {}) {
                         }
                     }
                     requestCount++;
-                    if (analytics && poolAccount) {
+                    {
+                        const rl = poolAccount?.rateLimit ?? parseRateLimits(upstream.headers);
                         analytics.record({
-                            timestamp: Date.now(), account: poolAccount.alias, model: requestModel,
+                            timestamp: Date.now(),
+                            account: poolAccount?.alias ?? ACCOUNT_KEY_SINGLE,
+                            model: requestModel,
                             inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0, thinkingTokens: 0,
-                            claim: poolAccount.rateLimit.claim, util5h: poolAccount.rateLimit.util5h,
-                            util7d: poolAccount.rateLimit.util7d, overageUtil: poolAccount.rateLimit.overageUtil,
+                            claim: rl.claim, util5h: rl.util5h, util7d: rl.util7d, overageUtil: rl.overageUtil,
                             latencyMs: Date.now() - startTime, status: 429, isStream: false, isOpenAI,
                         });
                     }
@@ -1880,14 +1947,16 @@ export async function startProxy(opts = {}) {
                     lastResponseTime = Date.now();
                     lastResponseTokens = streamOutputTokens;
                 }
-                if (analytics && poolAccount) {
+                {
+                    const rl = poolAccount?.rateLimit ?? parseRateLimits(upstream.headers);
                     analytics.record({
-                        timestamp: Date.now(), account: poolAccount.alias, model: requestModel,
+                        timestamp: Date.now(),
+                        account: poolAccount?.alias ?? ACCOUNT_KEY_SINGLE,
+                        model: requestModel,
                         inputTokens: streamInputTokens, outputTokens: streamOutputTokens,
                         cacheReadTokens: streamCacheReadTokens, cacheCreateTokens: streamCacheCreateTokens,
                         thinkingTokens: 0,
-                        claim: poolAccount.rateLimit.claim, util5h: poolAccount.rateLimit.util5h,
-                        util7d: poolAccount.rateLimit.util7d, overageUtil: poolAccount.rateLimit.overageUtil,
+                        claim: rl.claim, util5h: rl.util5h, util7d: rl.util7d, overageUtil: rl.overageUtil,
                         latencyMs: Date.now() - startTime, status: upstream.status, isStream: true, isOpenAI,
                     });
                 }
@@ -1938,16 +2007,17 @@ export async function startProxy(opts = {}) {
                     lastResponseTime = Date.now();
                     lastResponseTokens = bufferedUsage?.outputTokens ?? 0;
                 }
-                if (analytics && poolAccount && bufferedUsage) {
+                if (bufferedUsage) {
                     try {
+                        const rl = poolAccount?.rateLimit ?? parseRateLimits(upstream.headers);
                         analytics.record({
-                            timestamp: Date.now(), account: poolAccount.alias,
+                            timestamp: Date.now(),
+                            account: poolAccount?.alias ?? ACCOUNT_KEY_SINGLE,
                             model: bufferedUsage.model || requestModel,
                             inputTokens: bufferedUsage.inputTokens, outputTokens: bufferedUsage.outputTokens,
                             cacheReadTokens: bufferedUsage.cacheReadTokens, cacheCreateTokens: bufferedUsage.cacheCreateTokens,
                             thinkingTokens: bufferedUsage.thinkingTokens,
-                            claim: poolAccount.rateLimit.claim, util5h: poolAccount.rateLimit.util5h,
-                            util7d: poolAccount.rateLimit.util7d, overageUtil: poolAccount.rateLimit.overageUtil,
+                            claim: rl.claim, util5h: rl.util5h, util7d: rl.util7d, overageUtil: rl.overageUtil,
                             latencyMs: Date.now() - startTime, status: upstream.status, isStream: false, isOpenAI,
                         });
                     }

package/dist/tui/app.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The TUI App — main render loop + lifecycle + key dispatch.
+ *
+ * The shape is deliberately simple: one render function (caller-
+ * supplied) that takes `state + dimensions` and returns the full frame
+ * as a string. The App drives the loop, manages stdin raw mode, handles
+ * resize events, and flushes one write per frame. Tabs (M4) are
+ * decoupled state machines that the caller's render() composes.
+ *
+ * Lifecycle invariants:
+ *
+ *   - Enters alt-screen on start, leaves on stop. The shell that
+ *     spawned dario sees its prior content restored when the TUI quits.
+ *   - Hides the cursor on start, restores it on stop. ALWAYS, even on
+ *     uncaught exceptions or SIGINT — we install signal + exit hooks.
+ *   - Sets stdin raw mode on start, restores it on stop.
+ *
+ * The hook chain is registered on process events; quit calls them all
+ * synchronously so no terminal state leaks out.
+ */
+import { type Key } from './input.js';
+export interface AppOptions<S> {
+    /**
+     * Initial state. The App holds a reference and re-renders when
+     * `setState` is called.
+     */
+    initialState: S;
+    /**
+     * Pure function: state + dimensions → full screen content.
+     * The App calls this on every redraw + flushes the returned string
+     * to stdout in a single write.
+     */
+    render: (state: S, dim: {
+        cols: number;
+        rows: number;
+    }) => string;
+    /**
+     * Key dispatch. Receives every parsed key from stdin (after the
+     * App has already handled global keys like Ctrl-C). Return a new
+     * state (or undefined for no change) — same shape as React's
+     * setState reducer.
+     */
+    onKey: (state: S, key: Key) => S | undefined;
+    /**
+     * Optional: called on every redraw after the new frame has been
+     * written. Used by tabs that have async data (e.g. SSE-fed Hits
+     * tab) to schedule periodic refreshes.
+     */
+    afterFrame?: (state: S) => void;
+    /**
+     * stdin / stdout — overridable for tests. Defaults to process.stdin
+     * and process.stdout.
+     */
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+}
+export declare class App<S> {
+    private state;
+    private renderFn;
+    private keyFn;
+    private afterFrameFn?;
+    private stdin;
+    private stdout;
+    private cleanupFns;
+    private running;
+    private redrawScheduled;
+    constructor(opts: AppOptions<S>);
+    /**
+     * Replace state. If the new state differs from the old (shallow
+     * equality), schedule a redraw. Tabs use this both for synchronous
+     * key-driven updates and for async data arrivals (SSE 'record').
+     *
+     * The "differs" check is intentionally shallow — deep equality on
+     * potentially-large analytics records would be expensive and the
+     * caller almost always passes new object identity when it mutates.
+     * If you mutate state in place and don't change identity, the
+     * redraw won't fire (this is documented; sometimes desired).
+     */
+    setState(updater: Partial<S> | ((s: S) => S)): void;
+    /** Read-only state accessor — for callers that need to compute next state from current. */
+    getState(): S;
+    /**
+     * Start the TUI: enter alt-screen, hide cursor, raw stdin, attach
+     * resize listener, render once, then idle until stop() or process
+     * exit.
+     *
+     * Returns a Promise that resolves when stop() is called. Wires
+     * process exit / signal hooks so a Ctrl-C / kill leaves the
+     * terminal sane.
+     */
+    start(): Promise<void>;
+    /** Stop the TUI — restore terminal state and resolve the start() promise. */
+    stop(): void;
+    private scheduleRedraw;
+    private redraw;
+}