@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/tui/contract.d.ts

@@ -0,0 +1,83 @@
+import type { Key } from './terminal.js';
+import type { Draw, Rect } from './draw.js';
+export interface ViewManifest {
+    id: string;
+    title: string;
+    subtitle?: string;
+    description: string;
+    refreshMs?: number;
+    keymap?: KeyHint[];
+}
+export interface KeyHint {
+    keys: string;
+    label: string;
+}
+/** Severity of a {@link ViewHost.setBanner} banner — drives glyph + hue + the
+ *  derived state chip (error→blocked/red, action→attention/yellow, info→neutral). */
+export type BannerLevel = 'info' | 'action' | 'error';
+/** The current host banner, threaded into {@link ViewModule.dump} so the static
+ *  (non-TTY) path can surface guidance without the view mirroring it into state. */
+export interface Banner {
+    msg: string;
+    level: BannerLevel;
+}
+/** Optional host context passed to {@link ViewModule.dump} on the piped path. */
+export interface DumpContext {
+    banner: Banner | null;
+}
+export interface ViewHost {
+    /** CLI flags forwarded verbatim, e.g. { port: '9222', target: '...' }. */
+    readonly options: Readonly<Record<string, string>>;
+    /** Transient status line (left of the footer): "Loading…", "Sent". */
+    setStatus(msg: string | null): void;
+    /** Severity-coded guidance banner above the footer (info/action/error). The
+     *  level drives the banner glyph + hue AND the derived title state chip. */
+    setBanner(msg: string, level: BannerLevel): void;
+    /** Sticky error banner above the footer; null clears. Back-compat shorthand
+     *  for setBanner(msg, 'error'). */
+    setError(msg: string | null): void;
+    /** Dynamic title subtitle: a dim ` · <s>` after the bold title (e.g. the live
+     *  unread count "3 unread"). A non-null value OVERRIDES the static
+     *  {@link ViewManifest.subtitle}; `null` clears back to the manifest default
+     *  (or nothing). The title still leads — the subtitle is muted. */
+    setSubtitle(s: string | null): void;
+    /** Explicit interaction-mode chip override (compose/react). When set it WINS
+     *  the title state chip over the derived state, rendering the mode word in the
+     *  compose accent (yellow `33` bold) with the `✎` glyph (`react` → `☺`), so
+     *  entering an input mode is unmistakable. `null` returns to derived behavior. */
+    setMode(mode: string | null): void;
+}
+export type ViewAction = {
+    type: 'render';
+} | {
+    type: 'refresh';
+} | {
+    type: 'quit';
+} | {
+    type: 'none';
+};
+export interface ViewKey {
+    input: string;
+    key: Key;
+}
+export interface ViewModule<S = unknown> {
+    manifest: ViewManifest;
+    /** Build initial state. CHEAP + synchronous-ish — no screen, no slow fetch.
+     *  Slow data loads on the first refresh() so the host can paint a loading state. */
+    init(host: ViewHost): S | Promise<S>;
+    /** Fetch/poll. Mutates state in place. Host calls it on launch, on `refreshMs`,
+     *  and whenever a hook returns { type:'refresh' }. The host runs it in the
+     *  single-flight lane (busy indicator; never re-entrant). */
+    refresh?(state: S, host: ViewHost): Promise<void>;
+    /** Paint the view into `content` (the body rect, host chrome excluded).
+     *  Pure: reads state, calls draw.*; returns nothing. NEVER writes ANSI. */
+    render(state: S, draw: Draw, content: Rect): void;
+    /** Handle one keystroke. Mutates state; returns the next action. May be async
+     *  (open thread / send) — the host serializes async hooks in the single lane. */
+    onKey?(k: ViewKey, state: S, host: ViewHost): ViewAction | Promise<ViewAction>;
+    /** Static text for the non-TTY / piped path (exit 0). Snapshot of current
+     *  state. The host threads its current banner via the optional `ctx` so a view
+     *  can surface guidance without mirroring it into state (older views ignore the
+     *  arg and read their own state). */
+    dump(state: S, ctx?: DumpContext): string;
+}

package/dist/core/tui/contract.js

@@ -0,0 +1,8 @@
+// contract.ts — the view contract every `crtr view` module implements.
+//
+// A view is a self-contained ESM module whose DEFAULT export is a `ViewModule`.
+// State is a single mutable object the view owns (mirrors browse/app.ts's
+// BrowseState); hooks mutate it in place and return a `ViewAction` telling the
+// host what to do next. The host injects `Draw` (from ./draw) + `ViewHost`; a
+// view imports NOTHING from crtr internals.
+export {};

package/dist/core/tui/draw.d.ts

@@ -0,0 +1,96 @@
+export interface Size {
+    cols: number;
+    rows: number;
+}
+export interface Rect {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+}
+export interface Style {
+    fg?: string;
+    bg?: string;
+    bold?: boolean;
+    dim?: boolean;
+    reverse?: boolean;
+}
+export interface Span {
+    text: string;
+    style?: Style;
+}
+/** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
+ *  Guards styleSpan against a non-numeric value (a color name) producing a broken
+ *  escape sequence. */
+export declare function isSgrParams(v: string): boolean;
+/** Style one chunk of text. Hue (fg/bg) is gated on `color`; bold/dim/reverse
+ *  are not. After the styled text we return to `lineBase` (not a bare reset) so a
+ *  row-level background/dim persists across spans instead of bleeding or being
+ *  cleared. */
+export declare function styleSpan(text: string, style: Style | undefined, color: boolean, lineBase: string): string;
+/** Assemble styled spans into one line clipped to `width` visible cols. When
+ *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
+ *  background spans the full width. Always RESET-terminated so no color bleeds
+ *  into the next line. */
+export declare function assemble(spans: Span[], width: number, color: boolean, lineBase: string, fill: boolean): string;
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+export declare function clip(text: string, max: number): string;
+export interface ColorCaps {
+    /** Any hue (fg/bg color) allowed. */
+    color: boolean;
+    /** 256-color bg allowed — drives the subtle cursor-row background. */
+    color256: boolean;
+}
+/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
+ *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
+ *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
+export declare function detectColorCaps(stream?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): ColorCaps;
+/** One pre-styled list row (the view styles its own spans; `list` windows + the
+ *  cursor highlight are the host's job). An optional `right` group is flush-right
+ *  on the row (e.g. a timestamp) via spansRight; the left `spans` are clipped to
+ *  leave room for it, and the cursor-row highlight merges over both. */
+export interface ListItemRow {
+    spans: Span[];
+    right?: Span[];
+}
+/** Adjusted scroll the view stores back so the cursor stays visible. */
+export interface ListResult {
+    scroll: number;
+}
+export interface Draw {
+    readonly size: Size;
+    readonly caps: ColorCaps;
+    /** Styled spans at an absolute cell, clipped to maxWidth (default → edge). */
+    spans(row: number, col: number, spans: Span[], maxWidth?: number): void;
+    /** Flush-right span placement (mirror of `spans`): the group's last visible
+     *  cell lands just before `rightCol` (i.e. start col = rightCol − visibleWidth,
+     *  rightCol exclusive). If the group exceeds `maxWidth` (default → the room left
+     *  of rightCol) the LEFT end is clipped with a leading `…`. */
+    spansRight(row: number, rightCol: number, spans: Span[], maxWidth?: number): void;
+    /** Convenience single span. */
+    text(row: number, col: number, text: string, style?: Style): void;
+    /** Dim horizontal rule across [fromCol,toCol) (default full width). */
+    hline(row: number, fromCol?: number, toCol?: number, ch?: string): void;
+    /** Dim vertical rule down column `col` across [fromRow,toRow) (default full
+     *  height). `ch` defaults to `│`; pass `|` as the ASCII fallback. */
+    vline(col: number, fromRow?: number, toRow?: number, ch?: string): void;
+    /** Single-line box border around rect (optional title in the top edge). */
+    box(rect: Rect, title?: string): void;
+    /** Split a rect into N columns by weights. */
+    columns(rect: Rect, weights: number[]): Rect[];
+    /** Scrollable list within rect: windows `items` to fit height, highlights the
+     *  cursor row (256-bg or reverse fallback, like browse). Returns adjusted
+     *  scroll so the cursor stays visible — the view stores it in state. */
+    list(rect: Rect, items: ListItemRow[], cursor: number, scroll: number): ListResult;
+}
+/** A live Draw plus the host-side serializer. */
+export interface DrawHandle {
+    draw: Draw;
+    /** Serialize the buffer to a full repaint frame (home + per-line clear + clear
+     *  below) — identical framing to browse's renderFrame. */
+    frame(): string;
+}
+/** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
+export declare function createDraw(size: Size, caps: ColorCaps): DrawHandle;

package/dist/core/tui/draw.js

@@ -0,0 +1,339 @@
+// draw.ts — the generic immediate-mode drawing surface shared by every crtr
+// raw-ANSI TUI (the `crtr view` host and `canvas browse`).
+//
+// The span/color primitives (Span, styleSpan, assemble, clip, ColorCaps,
+// detectColorCaps) are extracted verbatim-in-behavior from
+// canvas/browse/render.ts so there is ONE copy; browse imports them back.
+//
+// On top of those primitives this module adds the `Draw` factory: a line/cell
+// buffer covering the screen that a view fills via absolute-cell helpers
+// (spans/text/hline/box/columns/list). The host allocates one Draw per frame,
+// draws its chrome into it, hands the view a content Rect, then serializes the
+// buffer to a single repaint frame (`\x1b[H` + per-line `\x1b[K` + `\x1b[J`) —
+// exactly like browse's renderFrame does today.
+//
+// COLOR: hue (fg/bg) is gated on `caps.color`; structural SGR (bold/dim/reverse)
+// is always allowed. 256-color bg (the cursor-row highlight) additionally needs
+// `caps.color256`, falling back to reverse.
+// ── ANSI ────────────────────────────────────────────────────────────────────
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+const REVERSE = `${ESC}7m`;
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+/** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
+ *  Guards styleSpan against a non-numeric value (a color name) producing a broken
+ *  escape sequence. */
+export function isSgrParams(v) {
+    return v.length > 0 && /^[0-9;]+$/.test(v);
+}
+/** Style one chunk of text. Hue (fg/bg) is gated on `color`; bold/dim/reverse
+ *  are not. After the styled text we return to `lineBase` (not a bare reset) so a
+ *  row-level background/dim persists across spans instead of bleeding or being
+ *  cleared. */
+export function styleSpan(text, style, color, lineBase) {
+    if (text === '')
+        return '';
+    let pre = '';
+    if (style?.dim)
+        pre += DIM;
+    if (style?.bold)
+        pre += BOLD;
+    if (style?.reverse)
+        pre += REVERSE;
+    // fg is an SGR parameter string (e.g. '32' or '1;36'); bg is a 256-color index.
+    // Reject anything else so a bad value (e.g. a color NAME like 'green') degrades
+    // to no-color instead of emitting an invalid CSI that prints as literal garbage.
+    if (color && style?.fg && isSgrParams(style.fg))
+        pre += `${ESC}${style.fg}m`;
+    if (color && style?.bg && isSgrParams(style.bg))
+        pre += `${ESC}48;5;${style.bg}m`;
+    if (pre === '')
+        return text; // inherits lineBase / default
+    return `${pre}${text}${RESET}${lineBase}`;
+}
+/** Assemble styled spans into one line clipped to `width` visible cols. When
+ *  `fill`, pad the remainder with spaces (under `lineBase`) so a cursor-row
+ *  background spans the full width. Always RESET-terminated so no color bleeds
+ *  into the next line. */
+export function assemble(spans, width, color, lineBase, fill) {
+    let used = 0;
+    let body = '';
+    for (const span of spans) {
+        if (used >= width)
+            break;
+        if (span.text === '')
+            continue;
+        let t = span.text;
+        const remaining = width - used;
+        let cut = false;
+        if (t.length > remaining) {
+            t = t.slice(0, Math.max(0, remaining - 1)) + '…';
+            cut = true;
+        }
+        body += styleSpan(t, span.style, color, lineBase);
+        used += t.length;
+        if (cut)
+            break;
+    }
+    if (fill && used < width)
+        body += ' '.repeat(width - used);
+    return lineBase === '' ? body : `${lineBase}${body}${RESET}`;
+}
+/** Truncate to `max` visible cols (plain text, no ANSI). */
+export function clip(text, max) {
+    if (max <= 0)
+        return '';
+    return text.length <= max ? text : text.slice(0, Math.max(0, max - 1)) + '…';
+}
+/** Detect color capability. Honors `NO_COLOR` and `TERM=dumb`, and only emits
+ *  hue when stdout is a TTY. `color256` additionally requires a 256/truecolor
+ *  terminal (for the cursor-row background; otherwise we fall back to reverse). */
+export function detectColorCaps(stream = process.stdout, env = process.env) {
+    const term = env['TERM'] ?? '';
+    const color = stream.isTTY === true && !env['NO_COLOR'] && term !== 'dumb';
+    const colorTerm = env['COLORTERM'] ?? '';
+    const color256 = color && (/256|direct/i.test(term) || /truecolor|24bit/i.test(colorTerm));
+    return { color, color256 };
+}
+function mergeStyle(base, top) {
+    if (!top)
+        return base;
+    return {
+        fg: top.fg ?? base.fg,
+        bg: top.bg ?? base.bg,
+        bold: top.bold || base.bold,
+        dim: top.dim || base.dim,
+        reverse: top.reverse || base.reverse,
+    };
+}
+function sameStyle(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.fg === b.fg && a.bg === b.bg
+        && !!a.bold === !!b.bold && !!a.dim === !!b.dim && !!a.reverse === !!b.reverse;
+}
+/** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
+export function createDraw(size, caps) {
+    const cols = Math.max(1, size.cols);
+    const rows = Math.max(1, size.rows);
+    const grid = [];
+    for (let r = 0; r < rows; r++) {
+        const line = new Array(cols);
+        for (let c = 0; c < cols; c++)
+            line[c] = { ch: ' ', style: undefined };
+        grid.push(line);
+    }
+    /** Place spans starting at (row, col), clipped to `limit` visible cells; each
+     *  span's style optionally merged under `base` (the cursor-row highlight). */
+    const place = (row, col, spans, maxWidth, base) => {
+        if (row < 0 || row >= rows)
+            return;
+        const edge = cols - col;
+        const limit = Math.min(maxWidth ?? edge, edge);
+        if (limit <= 0)
+            return;
+        let x = col;
+        let drawn = 0;
+        for (const span of spans) {
+            if (drawn >= limit)
+                break;
+            const style = base ? mergeStyle(base, span.style) : span.style;
+            for (const ch of Array.from(span.text)) {
+                if (drawn >= limit)
+                    break;
+                if (x >= 0 && x < cols)
+                    grid[row][x] = { ch, style };
+                x++;
+                drawn++;
+            }
+        }
+    };
+    const fillStyle = (row, col, width, style) => {
+        if (row < 0 || row >= rows)
+            return;
+        const end = Math.min(cols, col + width);
+        for (let x = Math.max(0, col); x < end; x++)
+            grid[row][x] = { ch: ' ', style };
+    };
+    /** Visible (column) width of a span group — ANSI-free cell count. */
+    const spanWidth = (spans) => {
+        let n = 0;
+        for (const s of spans)
+            n += Array.from(s.text).length;
+        return n;
+    };
+    /** Flatten spans to per-cell {ch,style}, then re-group consecutive same-style
+     *  cells back into spans — used to left-clip a flush-right group. */
+    const regroup = (cells) => {
+        const out = [];
+        for (const c of cells) {
+            const last = out[out.length - 1];
+            if (last && sameStyle(last.style, c.style))
+                last.text += c.ch;
+            else
+                out.push({ text: c.ch, style: c.style });
+        }
+        return out;
+    };
+    /** Flush-right placement shared by draw.spansRight and the list right-group.
+     *  Lays `spans` so the group ends just before `rightCol` (exclusive); clips the
+     *  LEFT end with a leading `…` when the group exceeds the effective width.
+     *  `base` (the cursor-row highlight) merges under each cell, like `place`. */
+    const placeRight = (row, rightCol, spans, maxWidth, base) => {
+        if (row < 0 || row >= rows)
+            return;
+        const cap = Math.max(0, rightCol); // room available left of rightCol
+        const max = Math.min(maxWidth ?? cap, cap);
+        if (max <= 0)
+            return;
+        let cells = [];
+        for (const s of spans)
+            for (const ch of Array.from(s.text))
+                cells.push({ ch, style: s.style });
+        if (cells.length === 0)
+            return;
+        if (cells.length > max) {
+            const drop = cells.length - max + 1; // make room for the leading …
+            cells = cells.slice(drop);
+            cells.unshift({ ch: '…', style: cells[0]?.style });
+        }
+        const startCol = rightCol - cells.length;
+        place(row, startCol, regroup(cells), undefined, base);
+    };
+    const draw = {
+        size: { cols, rows },
+        caps,
+        spans(row, col, spans, maxWidth) {
+            place(row, col, spans, maxWidth);
+        },
+        spansRight(row, rightCol, spans, maxWidth) {
+            placeRight(row, rightCol, spans, maxWidth);
+        },
+        text(row, col, text, style) {
+            place(row, col, [{ text, style }], undefined);
+        },
+        hline(row, fromCol = 0, toCol = cols, ch = '─') {
+            if (row < 0 || row >= rows)
+                return;
+            const a = Math.max(0, Math.min(cols, fromCol));
+            const b = Math.max(0, Math.min(cols, toCol));
+            for (let x = a; x < b; x++)
+                grid[row][x] = { ch, style: { dim: true } };
+        },
+        vline(col, fromRow = 0, toRow = rows, ch = '│') {
+            if (col < 0 || col >= cols)
+                return;
+            const a = Math.max(0, Math.min(rows, fromRow));
+            const b = Math.max(0, Math.min(rows, toRow));
+            for (let r = a; r < b; r++)
+                grid[r][col] = { ch, style: { dim: true } };
+        },
+        box(rect, title) {
+            const { row, col, width, height } = rect;
+            if (width < 2 || height < 2)
+                return;
+            const bs = { dim: true };
+            const right = col + width - 1;
+            const bottom = row + height - 1;
+            const horiz = '─'.repeat(Math.max(0, width - 2));
+            place(row, col, [{ text: `┌${horiz}┐`, style: bs }], width);
+            place(bottom, col, [{ text: `└${horiz}┘`, style: bs }], width);
+            for (let r = row + 1; r < bottom; r++) {
+                place(r, col, [{ text: '│', style: bs }], 1);
+                place(r, right, [{ text: '│', style: bs }], 1);
+            }
+            if (title !== undefined && title !== '' && width > 4) {
+                place(row, col + 2, [{ text: ` ${title} ` }], width - 4);
+            }
+        },
+        columns(rect, weights) {
+            const n = weights.length;
+            if (n === 0)
+                return [];
+            const total = weights.reduce((a, b) => a + (b > 0 ? b : 0), 0) || 1;
+            const out = [];
+            let x = rect.col;
+            let used = 0;
+            for (let i = 0; i < n; i++) {
+                const isLast = i === n - 1;
+                const w = isLast
+                    ? Math.max(0, rect.width - used)
+                    : Math.max(0, Math.floor((rect.width * Math.max(0, weights[i])) / total));
+                out.push({ row: rect.row, col: x, width: w, height: rect.height });
+                x += w;
+                used += w;
+            }
+            return out;
+        },
+        list(rect, items, cursor, scroll) {
+            const height = Math.max(0, rect.height);
+            let sc = scroll;
+            if (height > 0) {
+                if (cursor < sc)
+                    sc = cursor;
+                if (cursor >= sc + height)
+                    sc = cursor - height + 1;
+            }
+            if (sc < 0)
+                sc = 0;
+            if (sc > Math.max(0, items.length - 1))
+                sc = Math.max(0, items.length - 1);
+            const end = Math.min(items.length, sc + height);
+            for (let i = sc; i < end; i++) {
+                const rowIdx = rect.row + (i - sc);
+                const item = items[i];
+                const base = i === cursor
+                    ? (caps.color256 ? { bg: '236' } : { reverse: true })
+                    : undefined;
+                if (base)
+                    fillStyle(rowIdx, rect.col, rect.width, base);
+                if (item.right && item.right.length) {
+                    // Right-flush group (e.g. a timestamp); clip the left spans so they
+                    // never collide, and merge the cursor highlight over both.
+                    const rightWidth = spanWidth(item.right);
+                    const leftLimit = Math.max(0, rect.width - rightWidth - 1);
+                    place(rowIdx, rect.col, item.spans, leftLimit, base);
+                    placeRight(rowIdx, rect.col + rect.width, item.right, rightWidth, base);
+                }
+                else {
+                    place(rowIdx, rect.col, item.spans, rect.width, base);
+                }
+            }
+            return { scroll: sc };
+        },
+    };
+    const serializeRow = (cells) => {
+        // Trim trailing plain blanks (clear-to-EOL covers them); keep styled tails
+        // (e.g. a cursor-row background fill) intact.
+        let last = -1;
+        for (let i = cells.length - 1; i >= 0; i--) {
+            const c = cells[i];
+            if (c.ch !== ' ' || c.style !== undefined) {
+                last = i;
+                break;
+            }
+        }
+        if (last < 0)
+            return '';
+        let out = '';
+        let i = 0;
+        while (i <= last) {
+            const style = cells[i].style;
+            let text = '';
+            while (i <= last && sameStyle(cells[i].style, style)) {
+                text += cells[i].ch;
+                i++;
+            }
+            out += styleSpan(text, style, caps.color, '');
+        }
+        return out;
+    };
+    const frame = () => {
+        const body = grid.map((cells) => `${serializeRow(cells)}${ESC}K`).join('\r\n');
+        return `${ESC}H${body}${ESC}J`;
+    };
+    return { draw, frame };
+}

package/dist/core/tui/host.d.ts

@@ -0,0 +1,29 @@
+import { type Draw, type Rect, type Size } from './draw.js';
+import type { ViewModule, ViewManifest, BannerLevel } from './contract.js';
+export interface RunViewOptions {
+    /** CLI flags forwarded verbatim to the view via host.options. */
+    options?: Record<string, string>;
+}
+/** The host-tracked chrome state. `banner` + `busy` + `loaded` derive the title
+ *  state chip; `tick` advances the spinner under the busy-tick repaint. */
+export interface Chrome {
+    status: string | null;
+    banner: {
+        msg: string;
+        level: BannerLevel;
+    } | null;
+    busy: boolean;
+    loaded: boolean;
+    lastRefresh: number;
+    tick: number;
+    subtitle: string | null;
+    mode: string | null;
+}
+/** Draw the host chrome into `draw` and return the content Rect for the view.
+ *  Three zones: title row (state rail + title/subtitle + state chip + liveness),
+ *  a hairline, and a footer (status left, keymap right) with a severity banner
+ *  on the row above it when set. */
+declare function drawChrome(draw: Draw, size: Size, manifest: ViewManifest, c: Chrome, now?: number): Rect;
+export { drawChrome };
+/** Host a view in the alt screen until it quits (or Ctrl-C). */
+export declare function runView<S>(view: ViewModule<S>, opts?: RunViewOptions): Promise<void>;