@vincemakes/kiso-tui-cells 0.46.2 → 0.47.0

package/dist/render.d.ts

@@ -5,7 +5,8 @@
  * produce the bytes a human sees. Colors are raw ANSI — zero
  * dependencies (the tui-cells package has none).
  */
-import type { Ground } from "./ground.js";
+import type { Ground, Rgb } from "./ground.js";
+import { type Tier } from "./graphite.js";
 /**
  * v2a — the palette, centralized (no hard-coded codes elsewhere); v5
  * (TUI v5 #16e, the v4.1 design): the decorative blue (38;5;75) is
@@ -114,13 +115,72 @@ export interface Palette {
     readonly washDim: string;
     readonly washDimEnd: string;
     readonly reset: string;
+    /** Graphite (design.md §2) — the tokens the redesign reads. Each is an
+     *  SGR open for its colour in the resolved tier (§2: 24-bit or the
+     *  nearest xterm-256 index), and EMPTY where the ground is unknown or
+     *  colour is off: §3.1 forbids an absolute colour on a ground nobody
+     *  established, so every one of them degrades to the terminal's own.
+     *  Foregrounds close with `fgEnd` (39), backgrounds with `washEnd`
+     *  (49), for the reason `rv` closes with 27. */
+    readonly ink2: string;
+    readonly rail: string;
+    readonly line: string;
+    readonly gold: string;
+    readonly goldMark: string;
+    readonly blue: string;
+    readonly ok: string;
+    readonly fail: string;
+    readonly humanInk: string;
+    readonly track: string;
+    readonly washRun: string;
+    readonly washDone: string;
+    readonly washFail: string;
+    readonly washAsk: string;
+    readonly human: string;
+    readonly codeBg: string;
+    readonly add: string;
+    readonly del: string;
+    /** Graphite §6 (R2a) — the changed words inside a `+` / `-` row: the
+     *  row's ground deepened toward its colour, as a BACKGROUND. */
+    readonly addWord: string;
+    readonly delWord: string;
+    /** Graphite §5 (R2b) — the bar down a quote's rows, and an alert's
+     *  (NOTE / TIP / IMPORTANT in blue, WARNING in gold, CAUTION in the
+     *  failure colour): one cell of the ground deepened toward the colour,
+     *  as a BACKGROUND (§1.5 — a glyph bar seams between rows). */
+    /** Graphite §5 (R2b) — a table's rails: between `line` and `rail`, so
+     *  the grid reads without outweighing the words in it. */
+    readonly edge: string;
+    readonly quoteBar: string;
+    readonly noteBar: string;
+    readonly warnBar: string;
+    readonly cautionBar: string;
+    /** Graphite §7.4 — a card's EDGE: one cell of its ground deepened
+     *  toward the state's colour, as a BACKGROUND (§1.5: a glyph bar down
+     *  several rows shows a break at every row in Apple Terminal; a cell's
+     *  background does not). One per card state. */
+    readonly runEdge: string;
+    readonly failEdge: string;
+    readonly askEdge: string;
+    /** Graphite §7.9 — the person's block's edge: one cell of gold toward
+     *  the warm ground, as a BACKGROUND, the same width as a card's edge.
+     *  A half-cell `▌` is thinner but shows a break at every row in Apple
+     *  Terminal (the owner's seam tests, 2026-09-29). */
+    readonly humanEdge: string;
+    readonly fgEnd: string;
+    /** §5.2 — the command breath's seven foreground opens; empty where
+     *  the mark freezes (no ground, or no colour). */
+    readonly breath: readonly string[];
+    /** The tier the colours were written in, or null when none were. */
+    readonly tier: Tier | null;
 }
+export declare function paletteFor(kind: "light" | "dark", ground: Rgb | null, tier: Tier): Palette;
 /**
  * DC-3 — one table per ground.
  *
- * R3 (owner, 2026-08-27) — `dim` is ABSOLUTE once the ground is known,
- * and design.md §2's table always said so: light `243` `#767676` at
- * 4.54:1, dark `246` `#949494` at 5.50:1 (both re-measured here).
+ * R3 (owner, 2026-08-27) — `dim` is ABSOLUTE once the ground is known:
+ * Graphite's `dim`, measured against the floor on every surface it can
+ * reach (design.md §2.1).
  *
  * DC-3 shipped SGR 2 instead, on the argument that an attribute adapts
  * to the ground while an absolute grey asserts one. That argument is
@@ -136,6 +196,8 @@ export interface Palette {
  * attribute is exactly the "correct on any ground" degradation there.
  */
 export declare const COLOR_NEUTRAL: Palette;
+/** The two reference palettes: Graphite on its reference grounds, in the
+ *  24-bit tier. `paletteFor` is the general form. */
 export declare const COLOR_LIGHT: Palette;
 export declare const COLOR_DARK: Palette;
 /** The historical name — the palette for a colour TTY whose ground has
@@ -143,8 +205,9 @@ export declare const COLOR_DARK: Palette;
  *  was the defect. */
 export declare const COLOR_ON: Palette;
 export declare const COLOR_OFF: Palette;
-export declare function setGround(g: Ground): void;
+export declare function setGround(g: Ground, rgb?: Rgb | null): void;
 export declare function currentGround(): Ground;
+export declare function currentGroundRgb(): Rgb | null;
 export declare function palette(): Palette;
 export declare function stripAnsi(text: string): string;
 export declare function escapeTerminal(text: string): string;
@@ -254,11 +317,20 @@ export declare function renderTerminalGap(statusLine: string | null): string;
  *  the transition. Every glyph is in Menlo and absent from Apple Color
  *  Emoji (§6.1's test, run). */
 export declare const TWINKLE: readonly ["✧", "✦", "✶", "✸", "✺", "✸", "✦"];
-/** The breath's frame: `●` at the step's grey, for the CURRENT ground.
- *  With no ground — or under NO_COLOR — it freezes to a static `●`,
- *  because a brightness ramp needs a background to be a ramp against and
- *  §3.1 forbids guessing one. The glyph never changes, so the freeze
- *  degrades the motion and never the meaning. */
+/**
+ * Graphite §7.8 — the composer's top rule: `gold-mark` for its first eighth,
+ * fading to `line` by a third of the width, `line` after. Drawn in a
+ * handful of runs, not a colour per cell, so the row costs a few escapes
+ * rather than one per column. Off a known ground it is the plain dim rule.
+ */
+export declare function fadeRule(W: number): string;
+/** The breath's frame: `●` at the step's brightness (§5.2 — seven steps
+ *  of gold toward the running card's ground, never under the graphic
+ *  floor, `graphite.ts` `breathRamp`). With no ground — or under
+ *  NO_COLOR — it freezes to a static `●`, because a brightness ramp needs
+ *  a background to be a ramp against and §3.1 forbids guessing one. The
+ *  glyph never changes, so the freeze degrades the motion and never the
+ *  meaning. */
 export declare function breathFrame(step: number): string;
 /** The twinkle's frame — pure glyph, no palette involved. */
 export declare function twinkleFrame(step: number): string;
@@ -266,15 +338,38 @@ export declare function twinkleFrame(step: number): string;
  *  marks stay in step on a screen showing both. */
 export declare const MOTION_FRAMES = 7;
 export declare const TAGLINE = "the coding agent that survives kill -9";
-/** R2 — what the opening knows about the session. Optional because the
- *  off-TTY caller prints a banner before a model is bound. */
+/**
+ * Graphite §7.10 — the opening: the wordmark, then what loaded.
+ *
+ * DECLARED REVERSAL (Graphite, owner-ruled 2026-09-28) of R2's "no logo,
+ * the name is the mark". R2 retired the wordmark because it cost the rows
+ * a first screen needed for three questions — what model, where am I, what
+ * is loaded. The model and the folder moved to the status bar (§8.9), what
+ * is loaded moved beside the wordmark, and the wordmark came back: ten
+ * rows, once, at the top of a session — including in the 80×24 window a
+ * Mac opens by default (owner, 2026-09-29: a wordmark the default window
+ * never shows is not worth drawing). Under 20 rows, on a terminal too
+ * narrow for it, and on a resume (the history is above the opening there,
+ * and ten rows of wordmark would bury its tail) the opening is one line.
+ *
+ * The R2 keys row retires with it: `?` lists the keys (§8.5).
+ */
+export declare const MOTTO = "intent \u2192 effect \u2192 durable fact";
+/** The wordmark's width in cells (its widest row). */
+export declare const WORDMARK_W: number;
+/** One fact the opening states: its label, the fact, and a quieter note
+ *  after it. An empty label continues the fact above it. */
+export interface BannerFact {
+    readonly label: string;
+    readonly value: string;
+    readonly note?: string;
+}
+/** §7.10 — what the opening knows: what loaded (the CLI composes the
+ *  facts; this module only lays them out), and whether the session was
+ *  resumed (a resumed session opens on the one-line form). */
 export interface BannerMeta {
-    readonly model: string;
-    readonly mode: string;
-    readonly cwd: string;
-    /** DC-49 — the workspace IS the user's home directory. Computed by the
-     *  CLI (realpath on both sides); the banner only renders it. */
-    readonly homeWorkspace?: boolean;
+    readonly facts: readonly BannerFact[];
+    readonly resumed?: boolean;
 }
 /** W20 — the ONE-ROW cut with the honest mark, SGR-aware. A line that
  *  fits (≤ W) passes through whole; an overflow cuts the content at
@@ -293,16 +388,30 @@ export declare function cutLine(line: string, W: number): string;
  *  for it, so a truncated row never exceeds W (a cut row carries the
  *  marker INSIDE the width; a row that fits is returned untouched). */
 export declare function truncateRow(row: string, width: number): string;
-/** v3 §01 (V6-2) + W1: the banner lines for a width W and height H —
- *  the tier table (extends the existing "under 40 columns, skip the
- *  logo" rule with a HEIGHT input; VD-14 merged the two art tiers):
- *    W ≥ 40 and H ≥ 14 → the 2-row wordmark, 2-column indent
- *    anything smaller → text rows only
- *  then the blank, then "vX — tagline" — the art IS the wordmark, so the
- *  text row does not repeat the name — then extensions — then the W5
- *  resume list (BIG only, W5). Every row truncates at the terminal width
- *  with a " (+N)" marker. Pure. */
+/**
+ * Graphite §7.10 — the opening's rows for a width W and height H. Pure;
+ * invariant ① holds at every width (each row is cut to W).
+ *
+ *  - The tall form (H ≥ 30, W ≥ the wordmark at the content edge, not a
+ *    resume): the wordmark, its rule, the tagline with the version, the
+ *    motto. The facts sit beside it behind one hairline when W ≥ 96, and
+ *    below it otherwise.
+ *  - The one-line form otherwise: `✦ kiso <version> · <tagline>`, the
+ *    facts below it.
+ *
+ * On a known ground the block cells take `mix(ink, dim, row / 4)` top to
+ * bottom, the box-drawing shadow `mix(rail, ground, 0.35)`, and the rule
+ * fades from `dim` to the ground; there is no gold (§1.2 — gold is the
+ * edge, and the opening has none). Off one the wordmark is the terminal's
+ * own foreground. `<version>` is the caller's, never a literal.
+ */
 export declare function bannerLines(W: number, H: number, version: string, extensionsText: string, resume?: readonly ResumeMeta[], now?: number, meta?: BannerMeta | undefined): string[];
+/** The rule under the wordmark: `dim` fading to the ground, in a few runs.
+ *  Off a known ground, the plain dim rule. */
+/** Graphite §5 (R2b) — the rule under an answer's `#` heading: `gold-mark`
+ *  fading to the ground over `n` cells (the prototype's forty). Off a known
+ *  ground, the plain dim rule. */
+export declare function headingRule(n: number): string;
 /** W5 — the opening-screen resume list. Every field already exists
  *  behind renderSessionLine / `kiso sessions`: the relative time, the
  *  title, then the right-aligned "N events · M runs". The columns are