@zenera/cli 1.1.18 → 1.1.20

package/dist/tui/theme.d.ts

@@ -1,10 +1,17 @@
-export type Appearance = 'dark' | 'light';
-/** The roles a line can play in the transcript. */
-export type Kind = 'you' | 'agent' | 'tool' | 'note' | 'error';
+import { type Appearance } from '../term.ts';
+export type { Appearance };
+/**
+ * The roles a line can play in the transcript.
+ *
+ * `text` is what the agent said on its way somewhere — prose between one batch
+ * of calls and the next — and `agent` is the answer it finished on, which is
+ * the only one that gets a box. Reasoning is not among them: it is progress,
+ * and progress that has finished is worth no rows at all.
+ */
+export type Kind = 'you' | 'text' | 'agent' | 'tool' | 'note' | 'error';
 export interface LineStyle {
     /** `undefined` means the terminal's own foreground. */
     readonly color?: string;
-    readonly dim?: boolean;
 }
 export interface Theme {
     readonly appearance: Appearance;
@@ -13,13 +20,35 @@ export interface Theme {
     readonly accent: string;
     /** Read-only badge, busy label. */
     readonly warn: string;
+    /**
+     * Box rules, clocks, the footer's numbers, the call rows. One step quieter
+     * than the prose and never two — stated as a grey because `dim` is a
+     * request the terminal is free to over-honour, and some do.
+     */
+    readonly chrome: LineStyle;
     /**
      * Reasoning. It is not a tool call and it is not the answer, and drawn in
-     * the same dim foreground as the rows around it there was nothing to say
-     * which — a wall of one weight reads as one thing. Its own hue is what
-     * separates the model's thinking from the work it went on to do.
+     * the same grey as the rows around it there was nothing to say which — a
+     * wall of one weight reads as one thing. Its own hue is what separates the
+     * model's thinking from the work it went on to do.
      */
     readonly thinking: LineStyle;
+    /**
+     * Inline code inside prose — `zen check`, `--theme`, a path.
+     *
+     * The one role added for markdown, and it is added because the alternative
+     * is worse: bold is already what `**strong**` means, and grey would say a
+     * command name matters less than the sentence around it when it is usually
+     * the only part worth copying. A hue says *this is literal* without
+     * ranking it.
+     */
+    readonly code: LineStyle;
+    /**
+     * The three things a turn spends time on. One word in the footer says which,
+     * and it is read at a glance from across a desk — so the word changing is
+     * backed by the colour changing, not left to be spelled out.
+     */
+    readonly phase: Record<'reasoning' | 'waiting' | 'working', string>;
     /**
      * Branch colours, cycled in order of first sight. A fan-out is the one
      * place where colour carries information rather than decoration: eight

package/dist/tui/theme.js

@@ -13,47 +13,75 @@
 // unreadable on dark and invisible on paper. What is left is the handful of
 // accents that ANSI *does* let a light theme get wrong, so those swap.
 //
-// Dim is spent on *chrome* — box rules, clocks, the footer's numbers — and no
-// longer on content. Tool rows are most of what is on screen, and dimming them
-// put the bulk of the transcript one step from unreadable: the whole thing read
-// as too dark. They are content, so they get the foreground like content does.
+// A second weight is spent on *chrome* and on the machinery: box rules,
+// clocks, the footer's numbers, and the call rows that say how an answer was
+// arrived at. What the agent actually said is drawn at full weight in the
+// terminal's own foreground, so a transcript read top to bottom reads as prose
+// with the work annotated beside it — not as one undifferentiated wall.
 //
-// Note what is *not* here: no hex, no 256-colour ramps, no attempt at a brand.
-// A palette that ignores the user's scheme is worse on both schemes than one
-// that mostly defers to it.
+// That weight used to be SGR 2 (`dim`), and it was the third version of the
+// same bug. `dim` is not a colour, it is an instruction, and how far it is
+// obeyed is the terminal's business: iTerm2 takes a step, Apple Terminal
+// blends most of the way to the background. On Terminal.app the entire margin
+// — every rule, every call row, every number — went out with it.
+//
+// So there is exactly one ramp here, `chrome`, and it is a stated grey rather
+// than an attribute. It is the only number in the file, and it buys the one
+// thing deference cannot: a floor under the quiet half of the screen.
+// Everything else is still named by role and still defers to the user's own
+// scheme — no brand, no second hue, no 256-colour palette.
 // ---------------------------------------------------------------------------
+import { appearance, CHROME } from "../term.js";
+// The two greys, shared with every one-shot command so a `zen check` table and
+// a TUI call row are the same weight. Chalk steps them down for a 16-colour
+// terminal, which is the only place the old `gray` problem is still reachable.
+const DARK_CHROME = { color: `ansi256(${CHROME.dark})` };
+const LIGHT_CHROME = { color: `ansi256(${CHROME.light})` };
 const DARK = {
     appearance: 'dark',
     line: {
         you: { color: 'cyan' },
+        text: {},
         agent: {},
-        // Never dim, and never `gray`: bright black is already the faintest
-        // colour a terminal has, and either one puts the bulk of the
-        // transcript a step from unreadable.
-        tool: {},
+        // A call is the machinery, not the work: the transcript is read for
+        // what the agent said, and the rows saying how it found out are a
+        // margin note beside that.
+        tool: DARK_CHROME,
         note: { color: 'cyan' },
         error: { color: 'red' },
     },
     accent: 'cyan',
     warn: 'yellow',
-    thinking: { color: 'magenta' },
+    chrome: DARK_CHROME,
+    // Bright: the gist is one line among many and plain `magenta` on black is
+    // the darkest of the six.
+    thinking: { color: 'magentaBright' },
+    // Green is the one hue with no other job here: it is not the accent, not
+    // the warning, and not the thinking.
+    code: { color: 'green' },
+    phase: { reasoning: 'magenta', waiting: 'yellow', working: 'cyan' },
     lanes: ['cyan', 'green', 'yellow', 'blue', 'red', 'magenta'],
 };
 // On a light background `cyan` and `yellow` are barely darker than the paper.
-// Dimmed default foreground and `blue`/`magenta` are the same information,
-// still legible.
+// Grey and `blue`/`magenta` are the same information, still legible.
 const LIGHT = {
     appearance: 'light',
     line: {
         you: { color: 'blue' },
+        text: {},
         agent: {},
-        tool: {},
+        tool: LIGHT_CHROME,
         note: { color: 'blue' },
         error: { color: 'red' },
     },
     accent: 'blue',
     warn: 'magenta',
+    chrome: LIGHT_CHROME,
     thinking: { color: 'magenta' },
+    code: { color: 'green' },
+    // No yellow: `waiting` takes blue and `working` green, which are the two
+    // that survive paper.
+    phase: { reasoning: 'magenta', waiting: 'blue', working: 'green' },
     // No cyan or yellow: on paper they are barely darker than the paper.
     lanes: ['blue', 'green', 'red', 'magenta'],
 };
@@ -67,23 +95,17 @@ export async function resolveTheme(choice) {
     if (asked !== 'auto') {
         return THEMES[asked];
     }
-    return THEMES[(await queryBackground()) ?? fromColorFgBg() ?? 'dark'];
-}
-/**
- * `COLORFGBG` is `fg;bg` or `fg;<something>;bg`; the background is the last
- * field. Anything non-numeric (notably `default`) tells us nothing.
- */
-function fromColorFgBg() {
-    const parts = process.env['COLORFGBG']?.split(';');
-    const bg = parts?.[parts.length - 1];
-    if (bg === undefined || !/^\d+$/.test(bg)) {
-        return undefined;
-    }
-    const n = Number(bg);
-    return n === 7 || n >= 9 ? 'light' : 'dark';
+    return THEMES[(await queryBackground()) ?? appearance()];
 }
-const QUERY = '\u001b]11;?\u0007';
+// The DA1 behind the colour query is what makes the answer conclusive. Every
+// terminal replies to DA1, and none replies to it ahead of an OSC 11 it
+// supports — so a DA1 arriving alone means "I do not do that", known in one
+// round trip instead of guessed at the end of a timeout. What is left for the
+// timeout is the terminal that answers neither, which is the only case worth
+// waiting on and now the only one that does.
+const QUERY = '\u001b]11;?\u0007\u001b[c';
 const REPLY = /\u001b\]11;rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})/i;
+const DA1 = /\u001b\[\?[\d;]*c/;
 /**
  * Ask the terminal for its background colour and read the answer off stdin.
  *
@@ -93,7 +115,7 @@ const REPLY = /\u001b\]11;rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})/i;
  * and nothing else. Anything the user typed in that window is put back, so
  * the first keystroke of a fast start is not eaten by the handshake.
  */
-async function queryBackground(timeoutMs = 120) {
+async function queryBackground(timeoutMs = 300) {
     const { stdin, stdout } = process;
     if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== 'function') {
         return undefined;
@@ -102,6 +124,7 @@ async function queryBackground(timeoutMs = 120) {
     let timer;
     let settled = false;
     let seen = '';
+    let found;
     return await new Promise((resolve) => {
         const finish = (result) => {
             if (settled) {
@@ -114,26 +137,33 @@ async function queryBackground(timeoutMs = 120) {
             if (!wasRaw) {
                 stdin.pause();
             }
-            const typed = seen.replace(REPLY, '').replace(/\u001b\\|\u0007/g, '');
+            const typed = seen
+                .replace(REPLY, '')
+                .replace(DA1, '')
+                .replace(/\u001b\\|\u0007/g, '');
             if (typed) {
                 stdin.unshift(Buffer.from(typed, 'latin1'));
             }
             resolve(result);
         };
+        // The DA1 is sent second and answered second, so it is the end of the
+        // conversation whether or not the colour came back. Settling on the
+        // colour alone leaves the DA1 in the pipe, and it surfaces a moment
+        // later as `[?64;1;2;...c` typed into the prompt.
         const onData = (chunk) => {
             seen += chunk.toString('latin1');
             const m = REPLY.exec(seen);
             if (m) {
-                finish(appearanceOf(m[1], m[2], m[3]));
+                found = appearanceOf(m[1], m[2], m[3]);
             }
-            else if (seen.length > 256) {
-                finish(undefined);
+            if (DA1.test(seen) || seen.length > 256) {
+                finish(found);
             }
         };
         stdin.setRawMode(true);
         stdin.resume();
         stdin.on('data', onData);
-        timer = setTimeout(() => finish(undefined), timeoutMs);
+        timer = setTimeout(() => finish(found), timeoutMs);
         timer.unref?.();
         stdout.write(QUERY);
     });

package/dist/tui/wrap.d.ts

@@ -17,26 +17,33 @@ export declare function clip(text: string, width: number): string;
 export declare function wrap(text: string, width: number): string[];
 /** The three footer rows, its margin, the prompt, and a row in hand. */
 export declare const CHROME_ROWS = 7;
-/** How much of the reasoning stream is worth showing. It is a progress bar. */
-export declare const THINKING_ROWS = 6;
+/**
+ * How much of the reasoning stream is worth showing.
+ *
+ * One row. A reasoning summary is not a document to be read while it arrives —
+ * it is the model saying what it is about to do, and the sentence that says so
+ * is the heading it writes for itself. Six rows of it pushed the answer and the
+ * work down the screen to make room for a paragraph nobody finishes reading,
+ * and the whole chain is in the trajectory either way.
+ */
+export declare const THINKING_ROWS = 1;
 /** How much of the frame the work in flight may take. A branch is a box now,
- *  not a row, so a fan-out of two costs fourteen of these. */
-export declare const ACTIVITY_ROWS = 16;
-/** The rule that opens a reasoning block and the one that closes it. */
-export declare const THINKING_CHROME = 2;
+ *  not a row, so a fan-out of two costs twenty-two of these. */
+export declare const ACTIVITY_ROWS = 24;
+/** The width of the elapsed-time column every call row is drawn behind. */
+export declare const TIME_COL = 5;
 export interface Budget {
     /** rows for the list of what is in flight */
     activity: number;
-    /** rows for the tail of the reasoning stream */
+    /** rows for the gist of what the model is reasoning about */
     thinking: number;
     /** rows for the answer as it arrives */
     live: number;
     /**
-     * What the three of them occupy together, rules included — a constant for
-     * a given terminal, whatever is happening inside it. The region grows to
-     * this and stops, and never shrinks back while the turn runs, which is what
-     * keeps the footer on one row instead of riding up and down on the
-     * reasoning block.
+     * What the three of them occupy together — a constant for a given terminal,
+     * whatever is happening inside it. The region grows to this and stops, and
+     * never shrinks back while the turn runs, which is what keeps the footer on
+     * one row instead of riding up and down on the work.
      */
     total: number;
 }
@@ -47,15 +54,22 @@ export interface Budget {
  * arrives matters more than the machinery producing it. Reasoning yields to it
  * in turn, because it is a progress indicator and the answer is the point.
  *
- * `thinking` is how many rows of reasoning are wanted, counting text only: none
- * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
- * settled and its tail is history rather than progress. The two rules are
- * charged on top, so a block too cramped to be worth boxing is not drawn at all
- * rather than drawn as a border with a line in it.
+ * `thinking` is how many rows of reasoning are wanted — one while the model is
+ * reasoning, none otherwise — and it never takes the answer's last row.
  */
 export declare function budgetOf(rows: number, activity: number, thinking: number): Budget;
-/** The rows a branch box may spend on its own calls and its reasoning. */
-export declare const BRANCH_ROWS = 5;
+/** The rows a branch box may spend on its own calls, prose and reasoning. */
+export declare const BRANCH_ROWS = 9;
+/**
+ * The fewest a box is worth drawing at.
+ *
+ * One row per branch fit more of them on screen and said nothing about any of
+ * them: a box holding a single call is a label, and the reason it is a box at
+ * all is that what a branch just did and said is why it is doing this. Below
+ * six rows there is no *what it just did* — so a fork too wide to give every
+ * branch six is cut to the ones that fit and counted, which is `fitActivity`.
+ */
+export declare const BRANCH_MIN = 6;
 /** Rows a branch box spends on chrome: the title rule and the closing one. */
 export declare const BOX_CHROME = 2;
 /**
@@ -63,18 +77,27 @@ export declare const BOX_CHROME = 2;
  * activity region has to divide between them.
  *
  * Every branch gets the same number, because they are the same kind of thing
- * and a fan-out is read across, not down. A wide fork spends its rows on being
- * complete rather than on being detailed: eight branches showing one call each
- * is a picture of the fork, eight rows of one branch is not.
+ * and a fan-out is read across, not down.
  */
 export declare function branchRows(count: number, allowance: number): number;
 /**
- * How wide the answer is drawn. A line of prose spanning a 200-column terminal
- * is measurably harder to read than one that stops, which is why every demo in
+ * How wide *prose* is drawn. A line spanning a 200-column terminal is
+ * measurably harder to read than one that stops, which is why every demo in
  * `examples/sdk/` puts its answer in a box of bounded width — the terminal is the
  * page, not the paragraph.
+ *
+ * `boxWidth` is what a whole answer is drawn at; this is the floor it starts from.
  */
 export declare function answerWidth(columns: number): number;
+/**
+ * How wide the box holding `text` has to be.
+ *
+ * Prose stops at the comfort width, but a fence and a table cannot be
+ * reflowed — fold a table row and the columns stop lining up, which is the one
+ * thing the table was for — so the box grows to hold the widest of them, as far
+ * as the terminal allows and no further.
+ */
+export declare function boxWidth(text: string, columns: number): number;
 /**
  * A tool payload as a person would read it, rather than as it was serialised.
  *
@@ -87,18 +110,102 @@ export declare function answerWidth(columns: number): number;
  * that got cut.
  */
 export declare function readable(preview: string): string;
-/** A run of lines from an answer, and whether it was fenced as code. */
-export interface Segment {
-    code: boolean;
+/** Every field of a preview, first mention winning. */
+export declare function fieldsOf(preview: string): Map<string, string>;
+/** What a call is doing, and what it is doing it to. */
+export interface CallView {
+    /** The verb, drawn first: what kind of thing this is. */
+    verb: string;
+    /** What identifies this call: a path, a command, a query. May be empty. */
+    subject: string;
+}
+export declare function describeCall(name: string, preview: string): CallView;
+export declare function summarise(name: string, preview: string): string;
+/**
+ * One line saying where the model has got to.
+ *
+ * Reasoning summaries arrive as markdown and are structured by their own bold
+ * headings — Gemini emits one every few sentences, and they are the shortest
+ * true account of the step. The last one is where the model is now. Failing
+ * that the raw text is clipped, which is a fragment, but a moving fragment is
+ * still proof that something is happening.
+ */
+export declare function gistOf(text: string, width: number): string;
+/** A run of inline text and what it is. Style rides beside the text, never in it. */
+export interface Span {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    /** an inline code span, taken verbatim and never scanned again */
+    code?: boolean;
+    /** where a link points, when its own text does not say */
+    href?: string;
+}
+export type BlockKind = 'paragraph' | 'heading' | 'item' | 'quote' | 'code' | 'table' | 'rule';
+/** How a table column is set, when its rule row said. */
+export type Align = 'left' | 'right' | 'center';
+/**
+ * One block of an answer.
+ *
+ * `lines`, `cells` and `spans` are exclusive and say how the block may be
+ * drawn: `lines` is verbatim and must be cut rather than wrapped, `cells` is a
+ * grid to be laid out by `gridOf`, `spans` is prose and the renderer may do as
+ * it likes with it.
+ */
+export interface Block {
+    kind: BlockKind;
+    /** `heading`: its depth, 1–6. `item`: how deep it is nested. */
+    level?: number;
     /** the fence's info string, when it had one */
     title?: string;
-    lines: string[];
+    /** what a list item is drawn behind — a bullet, or the number that was written */
+    marker?: string;
+    /** `code` only, whose indentation is its meaning */
+    lines?: string[];
+    /** `table` only: every row but the rule, as cells, with their markup resolved */
+    cells?: Span[][][];
+    /** `table` only: how each column is set, and that the first row is a header */
+    align?: Align[];
+    /** every other kind, with its inline markup resolved */
+    spans?: Span[];
 }
 /**
- * Splits an answer on ``` fences. Prose is left exactly as it was — the common
- * answer has no fence in it and comes back in one piece — but a fenced block is
- * the one thing a terminal must not reflow: its indentation is its meaning, and
- * wrapping it as prose destroys it.
+ * The inline markup of one block, resolved.
+ *
+ * Order is the correctness argument. Code is settled first and never entered
+ * again, which is why this is a scanner and not a chain of replaces: in
+ * "use `[a](b)` syntax" the brackets are prose, and no regex over the whole
+ * string can know that. Everything else recurses on the text between its own
+ * markers, so `**bold with `code` in it**` keeps both.
+ */
+export declare function inlineOf(text: string, style?: Omit<Span, 'text'>, depth?: number): Span[];
+/**
+ * An answer, as the blocks it is made of.
+ *
+ * Read top down, one line at a time, because that is the order the text
+ * arrives in and a stream must be readable before it is finished. The two
+ * verbatim kinds win over everything: a pipe inside a fence is whatever the
+ * code says it is, and a `#` inside one is a comment, not a heading.
+ */
+export declare function blocksOf(text: string): Block[];
+/**
+ * A table as its rows, each one a single run of spans.
+ *
+ * Columns are laid out here and nowhere else, so the drawn table and the plain
+ * one are the same table: a cell's width is the length of its text, which is
+ * what a `Span` measures whatever styling rides beside it. Nothing a model
+ * writes in a cell can move the cell after it.
+ */
+export declare function gridOf(block: Block): Span[][];
+/**
+ * A block as the row or rows it reads as, with its markers resolved rather
+ * than shown, and nothing styled.
+ *
+ * This is what a sink that cannot style gets — the pre-answer stream, and the
+ * plain box `zen meta` draws — so that the text does not visibly change shape
+ * at the moment it settles.
  */
-export declare function segmentsOf(text: string): Segment[];
+export declare function textOf(block: Block, width?: number): string;
+/** A whole answer with its markup resolved instead of shown. Still plain text. */
+export declare function unmarked(text: string, width?: number): string;
 //# sourceMappingURL=wrap.d.ts.map