@north-light/api 0.3.580 → 0.3.588

package/dist/core/tui/markdown.js

@@ -0,0 +1,407 @@
+// markdown.ts — a tiny, pure markdown → styled-spans renderer for crtr's
+// raw-ANSI TUIs.
+//
+// WHY THIS EXISTS instead of the managed termrender subprocess: `renderFrame`
+// (canvas browse) is a pure function of state/size/caps called on EVERY
+// keystroke. termrender's `renderMarkdownBlockAwareLines` shells out to a python
+// venv per call, and pi-tui's Markdown component needs a component tree — both
+// are unusable inside a synchronous frame paint. So this module supports the
+// subset of markdown that actually shows up in a preview (headings, lists, code,
+// quotes, rules, tables, and inline emphasis) with no dependencies at all.
+//
+// It returns Span[][] — one span group per screen line, already wrapped to the
+// caller's width and already carrying its own prefixes (list markers, quote
+// bars). The caller assembles each line with draw.ts's `assemble`, so hue stays
+// gated on `caps.color` exactly like every other line in the frame.
+import { clip } from './draw.js';
+const FG_CYAN = '36';
+// ── Style composition ─────────────────────────────────────────────────────────
+/** Layer `add` over `base`. Structural flags OR together (a bold heading keeps
+ *  its bold inside an italic run); hue is last-one-wins. */
+function extend(base, add) {
+    const out = {};
+    const fg = add.fg ?? base.fg;
+    const bg = add.bg ?? base.bg;
+    if (fg !== undefined)
+        out.fg = fg;
+    if (bg !== undefined)
+        out.bg = bg;
+    if (add.bold || base.bold)
+        out.bold = true;
+    if (add.dim || base.dim)
+        out.dim = true;
+    if (add.italic || base.italic)
+        out.italic = true;
+    if (add.reverse || base.reverse)
+        out.reverse = true;
+    return out;
+}
+const RE_FENCE = /^\s{0,3}(```|~~~)/;
+const RE_HEAD = /^\s{0,3}(#{1,6})\s+(.*)$/;
+const RE_BULLET = /^(\s*)[-*+]\s+(.*)$/;
+const RE_ORDER = /^(\s*)(\d{1,9})[.)]\s+(.*)$/;
+const RE_QUOTE = /^\s{0,3}>\s?(.*)$/;
+const RE_RULE = /^\s{0,3}(?:(?:-\s*){3,}|(?:\*\s*){3,}|(?:_\s*){3,})$/;
+const RE_TABLE = /^\s*\|/;
+/** Does this line open a new block? Used to decide whether a following line is a
+ *  lazy continuation of the paragraph / list item / quote being accumulated. */
+function isBlockStart(line) {
+    return RE_FENCE.test(line) || RE_HEAD.test(line) || RE_RULE.test(line)
+        || RE_BULLET.test(line) || RE_ORDER.test(line) || RE_QUOTE.test(line) || RE_TABLE.test(line);
+}
+function parseBlocks(src) {
+    const lines = src.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === '') {
+            i++;
+            continue;
+        }
+        const fence = RE_FENCE.exec(line);
+        if (fence !== null) {
+            const tok = fence[1];
+            i++;
+            const body = [];
+            while (i < lines.length && !lines[i].trimStart().startsWith(tok)) {
+                body.push(lines[i]);
+                i++;
+            }
+            if (i < lines.length)
+                i++; // consume the closing fence
+            out.push({ k: 'code', lines: body });
+            continue;
+        }
+        // Rule before bullet: `---` and `***` would otherwise look like list markers.
+        if (RE_RULE.test(line)) {
+            out.push({ k: 'rule' });
+            i++;
+            continue;
+        }
+        const head = RE_HEAD.exec(line);
+        if (head !== null) {
+            out.push({ k: 'head', level: head[1].length, text: head[2].replace(/\s+#+\s*$/, '').trim() });
+            i++;
+            continue;
+        }
+        if (RE_TABLE.test(line)) {
+            const body = [];
+            while (i < lines.length && RE_TABLE.test(lines[i])) {
+                body.push(lines[i].trim());
+                i++;
+            }
+            out.push({ k: 'table', lines: body });
+            continue;
+        }
+        const bullet = RE_BULLET.exec(line);
+        const order = bullet === null ? RE_ORDER.exec(line) : null;
+        if (bullet !== null || order !== null) {
+            const indent = (bullet !== null ? bullet[1] : order[1]).length;
+            const marker = bullet !== null ? '• ' : `${order[2]}. `;
+            let text = bullet !== null ? bullet[2] : order[3];
+            i++;
+            while (i < lines.length && lines[i].trim() !== '' && !isBlockStart(lines[i])) {
+                text += ` ${lines[i].trim()}`;
+                i++;
+            }
+            out.push({ k: 'item', depth: Math.min(4, Math.floor(indent / 2)), marker, text: text.trim() });
+            continue;
+        }
+        const quote = RE_QUOTE.exec(line);
+        if (quote !== null) {
+            let text = quote[1];
+            i++;
+            for (;;) {
+                if (i >= lines.length)
+                    break;
+                const more = RE_QUOTE.exec(lines[i]);
+                if (more !== null) {
+                    text += ` ${more[1]}`;
+                    i++;
+                    continue;
+                }
+                if (lines[i].trim() !== '' && !isBlockStart(lines[i])) {
+                    text += ` ${lines[i].trim()}`;
+                    i++;
+                    continue;
+                }
+                break;
+            }
+            out.push({ k: 'quote', text: text.trim() });
+            continue;
+        }
+        let text = line.trim();
+        i++;
+        while (i < lines.length && lines[i].trim() !== '' && !isBlockStart(lines[i])) {
+            text += ` ${lines[i].trim()}`;
+            i++;
+        }
+        out.push({ k: 'para', text });
+    }
+    return out;
+}
+// ── Inline grammar ────────────────────────────────────────────────────────────
+const ESCAPABLE = /[\\`*_~[\]()#>-]/;
+/** Parse inline markup left to right, recursing on delimited content with the
+ *  base style extended. Unclosed or implausible delimiters stay literal, which is
+ *  the right failure mode for a preview: never eat the user's text. */
+export function inlineSpans(src, base = {}) {
+    const out = [];
+    let buf = '';
+    const flush = () => { if (buf !== '') {
+        out.push({ text: buf, style: base });
+        buf = '';
+    } };
+    const emit = (spans) => { flush(); for (const s of spans)
+        out.push(s); };
+    const n = src.length;
+    let i = 0;
+    while (i < n) {
+        const c = src[i];
+        if (c === '\\' && i + 1 < n && ESCAPABLE.test(src[i + 1])) {
+            buf += src[i + 1];
+            i += 2;
+            continue;
+        }
+        if (c === '`') {
+            const end = src.indexOf('`', i + 1);
+            if (end > i + 1) {
+                emit([{ text: src.slice(i + 1, end), style: extend(base, { fg: FG_CYAN }) }]);
+                i = end + 1;
+                continue;
+            }
+        }
+        // [label](url) — keep the label in cyan, drop the URL (a preview has no room
+        // for it and nothing here is clickable).
+        if (c === '[') {
+            const close = src.indexOf(']', i + 1);
+            if (close > i + 1 && src[close + 1] === '(') {
+                const paren = src.indexOf(')', close + 2);
+                if (paren > close) {
+                    emit(inlineSpans(src.slice(i + 1, close), extend(base, { fg: FG_CYAN })));
+                    i = paren + 1;
+                    continue;
+                }
+            }
+        }
+        if (c === '~' && src[i + 1] === '~') {
+            const end = src.indexOf('~~', i + 2);
+            if (end > i + 1) {
+                emit(inlineSpans(src.slice(i + 2, end), extend(base, { dim: true })));
+                i = end + 2;
+                continue;
+            }
+        }
+        if (c === '*' || c === '_') {
+            const run = src[i + 1] === c ? (src[i + 2] === c ? 3 : 2) : 1;
+            const delim = c.repeat(run);
+            // `_` must not open mid-word, or every snake_case identifier turns italic.
+            const wordBefore = c === '_' && i > 0 && /\w/.test(src[i - 1]);
+            const opens = !wordBefore && i + run < n && !/\s/.test(src[i + run]);
+            if (opens) {
+                let end = -1;
+                let from = i + run;
+                for (;;) {
+                    const at = src.indexOf(delim, from);
+                    if (at < 0)
+                        break;
+                    const tightRight = !/\s/.test(src[at - 1] ?? ' ');
+                    const wordAfter = c === '_' && /\w/.test(src[at + run] ?? '');
+                    if (tightRight && !wordAfter) {
+                        end = at;
+                        break;
+                    }
+                    from = at + 1;
+                }
+                if (end > i) {
+                    const add = run === 3 ? { bold: true, italic: true } : run === 2 ? { bold: true } : { italic: true };
+                    emit(inlineSpans(src.slice(i + run, end), extend(base, add)));
+                    i = end + run;
+                    continue;
+                }
+            }
+        }
+        buf += c;
+        i++;
+    }
+    flush();
+    return out;
+}
+// ── Wrapping ──────────────────────────────────────────────────────────────────
+function spanWidth(spans) {
+    let n = 0;
+    for (const s of spans)
+        n += [...s.text].length;
+    return n;
+}
+function sameStyle(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    return a.fg === b.fg && a.bg === b.bg && !!a.bold === !!b.bold
+        && !!a.dim === !!b.dim && !!a.italic === !!b.italic && !!a.reverse === !!b.reverse;
+}
+/** Merge neighbouring same-style spans. Word-wrapping emits one span per word, and
+ *  `assemble` wraps EVERY span in its own SGR pair — so without this a styled
+ *  sentence ships as a stutter of escape sequences. */
+function coalesce(spans) {
+    const out = [];
+    for (const s of spans) {
+        const last = out[out.length - 1];
+        if (last !== undefined && sameStyle(last.style, s.style))
+            last.text += s.text;
+        else
+            out.push({ text: s.text, ...(s.style === undefined ? {} : { style: s.style }) });
+    }
+    return out;
+}
+/** Greedy word-wrap over a span stream, with a first-line prefix and a separate
+ *  continuation prefix so list markers and quote bars hang correctly. A word
+ *  longer than the line is hard-sliced rather than dropped. */
+function wrapSpans(spans, width, first, cont) {
+    const lines = [];
+    const limitFor = (idx) => Math.max(1, width - spanWidth(idx === 0 ? first : cont));
+    let line = [];
+    let used = 0;
+    let limit = limitFor(0);
+    const flushLine = () => {
+        lines.push(coalesce([...(lines.length === 0 ? first : cont), ...line]));
+        line = [];
+        used = 0;
+        limit = limitFor(lines.length);
+    };
+    let pendingSpace = false;
+    for (const span of spans) {
+        for (const part of span.text.split(/(\s+)/)) {
+            if (part === '')
+                continue;
+            if (/^\s+$/.test(part)) {
+                if (used > 0)
+                    pendingSpace = true;
+                continue;
+            }
+            const w = [...part].length;
+            const extra = pendingSpace ? 1 : 0;
+            if (used + extra + w <= limit) {
+                // The break space carries the word's style so a styled run stays one span.
+                if (pendingSpace) {
+                    line.push({ text: ' ', style: span.style });
+                    used++;
+                }
+                line.push({ text: part, style: span.style });
+                used += w;
+                pendingSpace = false;
+                continue;
+            }
+            if (used > 0)
+                flushLine();
+            pendingSpace = false;
+            let rest = [...part];
+            while (rest.length > limit) {
+                line.push({ text: rest.slice(0, limit).join(''), style: span.style });
+                rest = rest.slice(limit);
+                flushLine();
+            }
+            if (rest.length > 0) {
+                line.push({ text: rest.join(''), style: span.style });
+                used = rest.length;
+            }
+        }
+    }
+    if (line.length > 0)
+        flushLine();
+    return lines;
+}
+// ── Blocks → lines ────────────────────────────────────────────────────────────
+function blockToLines(b, width, base) {
+    switch (b.k) {
+        case 'rule':
+            return [[{ text: '─'.repeat(Math.max(1, width)), style: { dim: true } }]];
+        case 'code':
+            return b.lines.map((l) => [{ text: clip(l.replace(/\t/g, '  '), width), style: extend(base, { fg: FG_CYAN }) }]);
+        case 'table':
+            return b.lines.map((l) => [{ text: clip(l, width), style: extend(base, { dim: true }) }]);
+        case 'head': {
+            // Level 3+ is a sub-sub-heading — bold alone would out-shout the body it
+            // introduces, so it goes dim-bold.
+            const st = extend(base, b.level >= 3 ? { bold: true, dim: true } : { bold: true });
+            return wrapSpans(inlineSpans(b.text, st), width, [], []);
+        }
+        case 'item': {
+            const pad = ' '.repeat(b.depth * 2);
+            const first = [{ text: pad }, { text: b.marker, style: extend(base, { dim: true }) }];
+            const cont = [{ text: pad + ' '.repeat([...b.marker].length) }];
+            return wrapSpans(inlineSpans(b.text, base), width, first, cont);
+        }
+        case 'quote': {
+            const bar = [{ text: '▏ ', style: { dim: true } }];
+            return wrapSpans(inlineSpans(b.text, extend(base, { dim: true })), width, bar, bar);
+        }
+        case 'para':
+            return wrapSpans(inlineSpans(b.text, base), width, [], []);
+    }
+}
+/** Trim the last line to make room, then mark the cut. Without this a truncated
+ *  reply reads as the end of the text — exactly the wrong impression for "where
+ *  did this node leave off?". */
+function appendEllipsis(lines, width) {
+    const last = lines[lines.length - 1];
+    if (last === undefined)
+        return;
+    let w = spanWidth(last);
+    while (w > width - 1 && last.length > 0) {
+        const tail = last[last.length - 1];
+        const chars = [...tail.text];
+        if (chars.length <= 1) {
+            last.pop();
+            w -= chars.length;
+        }
+        else {
+            tail.text = chars.slice(0, -1).join('');
+            w--;
+        }
+    }
+    last.push({ text: '…', style: { dim: true } });
+}
+/**
+ * Render `src` as markdown into at most `maxLines` span groups, each already
+ * wrapped to `width` visible columns.
+ *
+ * `spacing` inserts a blank line between blocks — true where the panel has room
+ * to breathe, false in a cramped one where every line counts. Consecutive list
+ * items never get one, so a tight list stays tight.
+ *
+ * `base` is the style every rendered run inherits (the caller's block style,
+ * e.g. the dim of a report body); markdown's own styles layer over it.
+ */
+export function renderMarkdownSpans(src, width, maxLines, spacing = false, base = {}) {
+    if (width <= 0 || maxLines <= 0)
+        return [];
+    const blocks = parseBlocks(src);
+    const out = [];
+    let truncated = false;
+    let prev;
+    for (const b of blocks) {
+        if (out.length >= maxLines) {
+            truncated = true;
+            break;
+        }
+        if (prev !== undefined && spacing && !(prev.k === 'item' && b.k === 'item'))
+            out.push([]);
+        for (const line of blockToLines(b, width, base)) {
+            if (out.length >= maxLines) {
+                truncated = true;
+                break;
+            }
+            out.push(line);
+        }
+        prev = b;
+    }
+    while (out.length > 0 && out[out.length - 1].length === 0)
+        out.pop();
+    if (truncated)
+        appendEllipsis(out, width);
+    return out;
+}

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

@@ -0,0 +1,31 @@
+import { ProcessTerminal, type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { readRawScopeConfig } from '../config.js';
+import { type BindingId, type BindingResolution } from '../keybindings/index.js';
+/** A full-screen page: a focusable TUI component that cleans up after itself. */
+export type TuiPageSurface = Component & Focusable & {
+    dispose(): void;
+};
+export interface TuiPageContext {
+    tui: TUI;
+    terminal: ProcessTerminal;
+    bindings: BindingResolution<BindingId>;
+    rawUserConfig: ReturnType<typeof readRawScopeConfig>;
+    /**
+     * Hand the terminal to a child process ($EDITOR) and return the closure that
+     * takes it back with a full repaint. Callers must invoke the closure in a
+     * `finally` block. Same contract as the attach viewer's `SurfaceHost`.
+     */
+    suspendForChild(): () => void;
+}
+export interface TuiPageControl<Result> {
+    /** Close the page with a result. */
+    submit(result: Result): void;
+    /** Close the page with no result. */
+    cancel(): void;
+}
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export declare function runTuiPage<Result>(createSurface: (context: TuiPageContext, control: TuiPageControl<Result>) => TuiPageSurface, interceptCancel?: (data: string, bindings: BindingResolution<BindingId>) => boolean): Promise<Result | undefined>;

package/dist/core/tui/page-host.js

@@ -0,0 +1,74 @@
+// The process-level terminal host for crouter's full-screen TUI pages —
+// `crtr sys settings`, the setup wizard, and `crtr pkg browse`.
+//
+// It owns exactly the concerns every page shares: theme, resolved keybindings,
+// the raw user config those pages edit, the ProcessTerminal/TUI pair, the
+// release and reclaim of that terminal for a child process, and a restore path
+// that survives an exception, a signal, and process exit. Anything
+// a single page needs beyond that — pi's model runtime, a canvas client — the
+// page's own runner builds and closes over before calling in here.
+import { ProcessTerminal, TuiMainScreen, } from '@earendil-works/pi-tui';
+import { applyTheme } from '../../clients/attach/config.js';
+import { readRawScopeConfig } from '../config.js';
+import { resolveKeybindings, } from '../keybindings/index.js';
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export async function runTuiPage(createSurface, interceptCancel) {
+    applyTheme({ cwd: process.cwd() });
+    const rawUserConfig = readRawScopeConfig("user");
+    const bindings = resolveKeybindings(rawUserConfig?.keybindings);
+    const terminal = new ProcessTerminal();
+    const tui = new TuiMainScreen(terminal, true);
+    return new Promise((resolve, reject) => {
+        let surface;
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            surface?.dispose();
+            try {
+                tui.stop();
+            }
+            catch {
+                /* terminal restore */
+            }
+        };
+        const finish = (result) => {
+            restore();
+            resolve(result);
+        };
+        const suspendForChild = () => {
+            tui.stop();
+            return () => {
+                tui.start();
+                tui.invalidate();
+                tui.requestRender(true);
+            };
+        };
+        try {
+            surface = createSurface({ tui, terminal, bindings, rawUserConfig, suspendForChild }, { submit: finish, cancel: () => finish(undefined) });
+            tui.addChild(surface);
+            tui.setFocus(surface);
+            process.once("exit", restore);
+            for (const signal of ["SIGTERM", "SIGHUP", "SIGINT"])
+                process.once(signal, () => finish(undefined));
+            if (interceptCancel !== undefined) {
+                tui.addInputListener((data) => {
+                    if (!interceptCancel(data, bindings))
+                        return undefined;
+                    finish(undefined);
+                    return { consume: true };
+                });
+            }
+            tui.start();
+        }
+        catch (error) {
+            restore();
+            reject(error);
+        }
+    });
+}

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

@@ -0,0 +1,45 @@
+export interface SetupPanel {
+    handleInput(data: string, matches?: (id: string, input: string) => boolean): boolean;
+    render(width: number, height: number): string[];
+    /** Short live state shown on this panel's settings-rail row. */
+    badge?(): string;
+}
+type ThemeFgRole = "border" | "accent" | "dim" | "success" | "warning" | "muted" | "mdLink" | "mdLinkUrl";
+export declare const theme: {
+    fg(role: ThemeFgRole, text: string): string;
+    /** A real filled selection band. An identity `selectedBg` would leave the
+     *  active tab and the active row with no background at all — reverse video is
+     *  the one background every terminal theme honours. */
+    bg(_role: "selectedBg", text: string): string;
+    bold(text: string): string;
+};
+export declare function wrapText(text: string, width: number): string[];
+export declare function renderRows(lines: string[], width: number): string[];
+export declare function padAnsi(text: string, width: number): string;
+export declare function rule(width: number): string;
+export declare function visibleRange(count: number, selected: number, capacity: number): {
+    start: number;
+    end: number;
+};
+/** A bordered box for an emphasised sub-region — an input field, a modal. Panel
+ *  bodies are not boxed: the page frame and rail divider already frame them. */
+export declare function framed(lines: string[], width: number): string[];
+export declare function fitTail(lines: string[], budget: number): string[];
+/** Rows the page frame spends on its own title, rules and footer. */
+export declare const PAGE_CHROME_ROWS = 4;
+/** Title row with right-aligned scope metadata, a rule under it, the body
+ *  padded to fill the viewport, a rule, and the footer pinned to the last row.
+ *  Every settings/setup screen goes through this so the footer never floats in
+ *  the middle of a half-empty terminal. */
+export declare function pageFrame(opts: {
+    width: number;
+    height: number;
+    title: string;
+    meta?: string;
+    body: string[];
+    footer: string;
+}): string[];
+/** Two columns joined by a vertical divider, each already wrapped to its own
+ *  width. Short columns pad; the taller one sets the height. */
+export declare function columns(left: string[], leftWidth: number, right: string[], rightWidth: number): string[];
+export {};