@vincemakes/kiso-tui-cells 0.46.2 → 0.47.0

package/dist/diff.d.ts

@@ -1,8 +1,9 @@
 /**
  * v2e — the diff renderer: edit/write changes as inline ± lines, zero
- * dependencies, no syntax highlighting (the spec's scope line). Shown at
- * the approval moment ONLY — the frozen summary stays one line (v2d's
- * anti-leak principle), /last has the full data.
+ * dependencies, no syntax highlighting (the spec's scope line). v2e drew
+ * it at the approval moment only; Graphite §6 (R2a) draws it on every
+ * edit's card too, from the call's own hunks (`hunksDiff`) — DECLARED
+ * REVERSAL of "the frozen summary stays one line".
  *
  * edit_file diffs IN PLACE (the search→replace windows are known — no
  * general engine needed); write_file does a row-level LCS over the old
@@ -17,7 +18,17 @@
 export type DiffLine = {
     kind: "-" | "+" | " " | "note";
     text: string;
+    /** Graphite §6 (R2a): the changed WORDS of a line that replaced one
+     *  other line — `[start, end)` offsets into `text`, sorted, disjoint.
+     *  Absent everywhere else. */
+    marks?: readonly (readonly [number, number])[];
 };
+/** One change an edit_file call asks for: the text it looks for, and what
+ *  replaces it. */
+export interface Hunk {
+    readonly search: string;
+    readonly replace: string;
+}
 export interface DiffResult {
     /** The FULL diff (with context, not truncated) — the display truncates. */
     lines: DiffLine[];
@@ -44,6 +55,8 @@ export interface DiffResult {
      *  changes meaning. */
     notFound?: true;
 }
+/** A line-level LCS diff — the classic two-row DP, ~small inputs. */
+export declare function lcsDiff(oldLines: string[], newLines: string[]): DiffLine[];
 /** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
 export declare function truncateDiff(diff: DiffLine[]): DiffLine[];
 /** edit_file: the preview of a CHARACTER splice.
@@ -72,3 +85,27 @@ export declare function editFileDiff(oldContent: string, search: string, replace
 /** write_file: a new file is all +; an existing file diffs row-level
  *  against its old content. */
 export declare function writeFileDiff(oldContent: string | null, newContent: string): DiffResult;
+/** The hunks an edit_file call carries: its `edits`, or its one
+ *  `search`/`replace` pair. Null when the input has neither (the tool
+ *  refuses such a call, so there is nothing to draw). */
+export declare function hunksOf(input: Record<string, unknown>): Hunk[] | null;
+/** Graphite §6 (R2a) — what an edit CHANGED, drawn from the call's own
+ *  hunks: per hunk a line LCS of `search` against `replace`, the lines
+ *  both keep as context (two around each change), a `···` note between
+ *  hunks, and word marks where one line replaced one line. The file is
+ *  never read, so the diff is a pure function of the durable log — the
+ *  same live, after a reprint, after resume. */
+export declare function hunksDiff(hunks: readonly Hunk[]): DiffResult;
+/** The approval preview of a batch: the hunks applied IN ORDER, each to
+ *  the text the ones before it left — the tool's own rule (ACI-3) — and
+ *  the result diffed against the file. A hunk the tool would refuse (not
+ *  there, or there more than once) is named, and nothing is drawn: the
+ *  tool writes all of the batch or none of it. */
+export declare function editFileHunksDiff(oldContent: string, hunks: readonly Hunk[], path?: string): DiffResult;
+/** A line's tokens: runs of word characters, runs of spaces, and every
+ *  other character on its own. Joined, they are the line. */
+export declare function wordTokens(line: string): string[];
+/** The token LCS of two lines: for each side, the `[start, end)` offsets
+ *  of the tokens the other side does not keep, adjacent ones merged.
+ *  Null when too little survives for marks to mean anything. */
+export declare function tokenMarks(a: string, b: string): [Array<[number, number]> | null, Array<[number, number]> | null];

package/dist/diff.js

@@ -1,8 +1,9 @@
 /**
  * v2e — the diff renderer: edit/write changes as inline ± lines, zero
- * dependencies, no syntax highlighting (the spec's scope line). Shown at
- * the approval moment ONLY — the frozen summary stays one line (v2d's
- * anti-leak principle), /last has the full data.
+ * dependencies, no syntax highlighting (the spec's scope line). v2e drew
+ * it at the approval moment only; Graphite §6 (R2a) draws it on every
+ * edit's card too, from the call's own hunks (`hunksDiff`) — DECLARED
+ * REVERSAL of "the frozen summary stays one line".
  *
  * edit_file diffs IN PLACE (the search→replace windows are known — no
  * general engine needed); write_file does a row-level LCS over the old
@@ -11,7 +12,7 @@
  * from the full diff.
  */
 /** A line-level LCS diff — the classic two-row DP, ~small inputs. */
-function lcsDiff(oldLines, newLines) {
+export function lcsDiff(oldLines, newLines) {
     const n = oldLines.length;
     const m = newLines.length;
     const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
@@ -138,7 +139,7 @@ export function editFileDiff(oldContent, search, replace, path) {
         };
     }
     const result = oldContent.slice(0, at) + replace + oldContent.slice(at + search.length);
-    const lines = withContext(lcsDiff(oldContent.split("\n"), result.split("\n")));
+    const lines = withMarks(withContext(lcsDiff(oldContent.split("\n"), result.split("\n"))));
     return { lines, ...stats(lines), outcome: "diff" };
 }
 /** write_file: a new file is all +; an existing file diffs row-level
@@ -151,3 +152,139 @@ export function writeFileDiff(oldContent, newContent) {
     const lines = withContext(lcsDiff(oldContent.split("\n"), newContent.split("\n")));
     return { lines, ...stats(lines), outcome: "diff" };
 }
+/** The hunks an edit_file call carries: its `edits`, or its one
+ *  `search`/`replace` pair. Null when the input has neither (the tool
+ *  refuses such a call, so there is nothing to draw). */
+export function hunksOf(input) {
+    const pair = (x) => {
+        if (typeof x !== "object" || x === null)
+            return null;
+        const { search, replace } = x;
+        return typeof search === "string" && typeof replace === "string" ? { search, replace } : null;
+    };
+    if (Array.isArray(input.edits)) {
+        const hunks = input.edits.map(pair);
+        return hunks.length > 0 && hunks.every((h) => h !== null) ? hunks : null;
+    }
+    const one = pair(input);
+    return one === null ? null : [one];
+}
+/** Graphite §6 (R2a) — what an edit CHANGED, drawn from the call's own
+ *  hunks: per hunk a line LCS of `search` against `replace`, the lines
+ *  both keep as context (two around each change), a `···` note between
+ *  hunks, and word marks where one line replaced one line. The file is
+ *  never read, so the diff is a pure function of the durable log — the
+ *  same live, after a reprint, after resume. */
+export function hunksDiff(hunks) {
+    const lines = [];
+    for (const [i, h] of hunks.entries()) {
+        const one = withMarks(withContext(lcsDiff(h.search.split("\n"), h.replace.split("\n"))));
+        if (one.length === 0)
+            continue;
+        if (i > 0 && lines.length > 0)
+            lines.push({ kind: "note", text: "\u00b7\u00b7\u00b7" });
+        lines.push(...one);
+    }
+    return { lines, ...stats(lines), outcome: "diff" };
+}
+/** The approval preview of a batch: the hunks applied IN ORDER, each to
+ *  the text the ones before it left — the tool's own rule (ACI-3) — and
+ *  the result diffed against the file. A hunk the tool would refuse (not
+ *  there, or there more than once) is named, and nothing is drawn: the
+ *  tool writes all of the batch or none of it. */
+export function editFileHunksDiff(oldContent, hunks, path) {
+    if (hunks.length === 1)
+        return editFileDiff(oldContent, hunks[0].search, hunks[0].replace, path);
+    const where = path ?? "the file";
+    let edited = oldContent;
+    for (const [i, h] of hunks.entries()) {
+        const at = edited.indexOf(h.search);
+        const which = i === 0 ? "hunk 1" : `hunk ${i + 1}, after ${i === 1 ? "hunk 1" : `hunks 1\u2013${i}`} applied`;
+        if (at < 0)
+            return { lines: [{ kind: "note", text: `pattern not found in ${where} (${which})` }], added: 0, removed: 0, outcome: "not-found", notFound: true };
+        if (h.search.length > 0 && edited.indexOf(h.search, at + 1) > at) {
+            return { lines: [{ kind: "note", text: `pattern matches more than one place in ${where} (${which})` }], added: 0, removed: 0, outcome: "ambiguous" };
+        }
+        edited = edited.slice(0, at) + h.replace + edited.slice(at + h.search.length);
+    }
+    const lines = withMarks(withContext(lcsDiff(oldContent.split("\n"), edited.split("\n"))));
+    return { lines, ...stats(lines), outcome: "diff" };
+}
+/** A line's tokens: runs of word characters, runs of spaces, and every
+ *  other character on its own. Joined, they are the line. */
+export function wordTokens(line) {
+    return line.match(/[\p{L}\p{N}_]+|\s+|[\s\S]/gu) ?? [];
+}
+/** The share of a replaced line's tokens (spaces aside) that must survive
+ *  for word marks to help: below it the whole line changed, and marking
+ *  nearly every word says less than the line's own colour does. */
+const MARK_MIN_KEPT = 0.34;
+/** Word marks on a diff: every `-` line directly followed by one `+` line,
+ *  with no other change beside the pair, gets the offsets of the tokens
+ *  the other side does not keep (a token LCS). */
+function withMarks(diff) {
+    const changed = (k) => k >= 0 && k < diff.length && (diff[k].kind === "-" || diff[k].kind === "+");
+    return diff.map((d, k) => {
+        const pairAt = d.kind === "-" ? k : d.kind === "+" ? k - 1 : -1;
+        if (pairAt < 0 || diff[pairAt]?.kind !== "-" || diff[pairAt + 1]?.kind !== "+" || changed(pairAt - 1) || changed(pairAt + 2))
+            return d;
+        const [oldMarks, newMarks] = tokenMarks(diff[pairAt].text, diff[pairAt + 1].text);
+        if (oldMarks === null || newMarks === null)
+            return d;
+        const marks = d.kind === "-" ? oldMarks : newMarks;
+        return marks.length === 0 ? d : { ...d, marks };
+    });
+}
+/** The token LCS of two lines: for each side, the `[start, end)` offsets
+ *  of the tokens the other side does not keep, adjacent ones merged.
+ *  Null when too little survives for marks to mean anything. */
+export function tokenMarks(a, b) {
+    const ta = wordTokens(a);
+    const tb = wordTokens(b);
+    const n = ta.length;
+    const m = tb.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1)
+            dp[i][j] = ta[i] === tb[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+    const keptA = new Array(n).fill(false);
+    const keptB = new Array(m).fill(false);
+    for (let i = 0, j = 0; i < n && j < m;) {
+        if (ta[i] === tb[j]) {
+            keptA[i] = true;
+            keptB[j] = true;
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            i += 1;
+        else
+            j += 1;
+    }
+    const solid = (t) => /\S/.test(t);
+    const words = ta.filter(solid).length + tb.filter(solid).length;
+    const kept = ta.filter((t, i) => keptA[i] && solid(t)).length + tb.filter((t, j) => keptB[j] && solid(t)).length;
+    if (words === 0 || kept / words < MARK_MIN_KEPT)
+        return [null, null];
+    return [spans(ta, keptA), spans(tb, keptB)];
+}
+/** The offsets of the tokens not kept, adjacent spans merged; a run of
+ *  spaces between two changed tokens joins them. */
+function spans(tokens, kept) {
+    const line = tokens.join("");
+    const out = [];
+    let at = 0;
+    for (const [i, t] of tokens.entries()) {
+        const end = at + t.length;
+        if (!kept[i] && /\S/.test(t)) {
+            const last = out[out.length - 1];
+            if (last !== undefined && /^\s*$/.test(line.slice(last[1], at)))
+                last[1] = end;
+            else
+                out.push([at, end]);
+        }
+        at = end;
+    }
+    return out;
+}

package/dist/graphite.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Graphite (design.md §2, §3.4) — the colour tokens, the output tier, and
+ * the surfaces derived from the ground the terminal actually reported.
+ *
+ * PURE: no process state is read except where a caller passes it in, so
+ * every decision here is testable without a terminal. `render.ts` turns
+ * these colours into SGR bytes; this module only decides the colours.
+ */
+import { type Rgb } from "./ground.js";
+export type Kind = "light" | "dark";
+/** How colour reaches the terminal: 24-bit (`38;2;r;g;b`) where the
+ *  terminal says it renders it, the nearest xterm-256 index otherwise. */
+export type Tier = "24bit" | "256";
+/** The Graphite table (design.md §2), on the two reference grounds. */
+export declare const GRAPHITE: {
+    readonly light: {
+        readonly ground: "#ffffff";
+        readonly ink: "#111111";
+        readonly ink2: "#444444";
+        readonly dim: "#646464";
+        readonly rail: "#8c8c8c";
+        readonly line: "#e6e6e6";
+        readonly washRun: "#edf2fb";
+        readonly washDone: "#f1f1f1";
+        readonly washFail: "#fbecea";
+        readonly washAsk: "#f7f1e3";
+        readonly human: "#f7efdc";
+        readonly humanInk: "#171923";
+        readonly gold: "#8a5a00";
+        readonly goldMark: "#c9921f";
+        readonly blue: "#2456b5";
+        readonly code: "#e4ebf8";
+        readonly ok: "#2f7a3a";
+        readonly fail: "#b3261e";
+        readonly add: "#dff0e2";
+        readonly del: "#fadfdc";
+        readonly track: "#e2e2e2";
+    };
+    readonly dark: {
+        readonly ground: "#0b0b0b";
+        readonly ink: "#ededed";
+        readonly ink2: "#b5b5b5";
+        readonly dim: "#8e8e8e";
+        readonly rail: "#6b6b6b";
+        readonly line: "#212121";
+        readonly washRun: "#141b28";
+        readonly washDone: "#1b1b1b";
+        readonly washFail: "#2a1716";
+        readonly washAsk: "#211d13";
+        readonly human: "#efe6cf";
+        readonly humanInk: "#141620";
+        readonly gold: "#e3b04b";
+        readonly goldMark: "#e3b04b";
+        readonly blue: "#82a8f5";
+        readonly code: "#1a2438";
+        readonly ok: "#8fd19e";
+        readonly fail: "#f2877a";
+        readonly add: "#16301f";
+        readonly del: "#3a1b1a";
+        readonly track: "#2a2a2a";
+    };
+};
+export type Token = Exclude<keyof (typeof GRAPHITE)["light"], "ground">;
+export type Colours = {
+    readonly [K in Token | "ground"]: Rgb;
+};
+/** The tokens that are GROUNDS near the terminal's own (§3.4): each is
+ *  derived from the reported ground. Every other token is fixed per kind. */
+export declare const SURFACES: readonly ["line", "washRun", "washDone", "washFail", "washAsk", "human", "code", "add", "del", "track"];
+/** The text tokens that read on the ground and on the card surfaces (§2.1). */
+export declare const CARD_TEXT: readonly ["ink", "ink2", "dim", "gold", "blue", "ok", "fail"];
+export declare const CARDS: readonly ["washRun", "washDone", "washFail", "washAsk"];
+type Surface = Token | "ground";
+/** Every text-on-surface pair a human reads (§2.1's floor applies to each). */
+export declare const TEXT_PAIRS: readonly (readonly [Token, Surface])[];
+export declare const FLOOR = 4.5;
+/** The floor for a GRAPHIC — a mark, not text (WCAG 1.4.11). The breath
+ *  never drops below it (§2.2). */
+export declare const GRAPHIC_FLOOR = 3;
+export declare function hexRgb(hex: string): Rgb;
+export declare function rgbHex({ r, g, b }: Rgb): string;
+/** The WCAG contrast ratio, the measure of §2's floor. */
+export declare function contrast(a: Rgb, b: Rgb): number;
+/** `t` of the way from `a` to `b`, per channel. */
+export declare function mix(a: Rgb, b: Rgb, t: number): Rgb;
+/**
+ * §3.4 — one surface for any ground. Per channel an affine map
+ * `s = a + k·g`, fitted so that the white reference ground gives the
+ * table's white value and the black one its black value: the two
+ * grounds reproduce the table exactly, and a terminal whose black is
+ * `#1e1e1e` gets a card that sits the same distance off ITS ground.
+ */
+export declare function deriveSurface(token: Token, ground: Rgb): Rgb;
+/** A colour as the terminal will show it: itself in the 24-bit tier, the
+ *  nearest xterm-256 entry in the 256 tier. The floor is checked on what
+ *  is SHOWN — rounding to the nearest index can cost a pair its contrast. */
+export declare function shown(c: Rgb, tier: Tier): Rgb;
+/** The weakest text-on-surface pair of a colour set, as shown in `tier`. */
+export declare function weakestPair(c: Colours, tier?: Tier): {
+    pair: readonly [Token, Surface];
+    ratio: number;
+};
+export declare function graphiteColours(kind: Kind, ground: Rgb | null, tier?: Tier): Colours;
+/**
+ * The command breath (§5.2): seven steps from `gold` toward the running
+ * card's ground, peak → floor → peak. The floor is the deepest step that
+ * still meets the graphic floor on that ground (§2.2): the mark dims and
+ * never disappears.
+ */
+export declare function breathRamp(c: Colours): readonly Rgb[];
+/** The xterm-256 palette's colour for an index 16–255 (the cube and the
+ *  grey ramp; the first sixteen are the terminal's own and never chosen). */
+export declare function xterm256(index: number): Rgb;
+/** The nearest xterm-256 index (16–255) to a colour, by squared distance
+ *  in RGB — the 256 tier's whole translation. */
+export declare function nearest256(c: Rgb): number;
+/** §2 — 24-bit where the terminal says it renders it. `COLORTERM` is the
+ *  standard statement; anything else gets the 256 tier, which every
+ *  terminal kiso docks in renders. */
+export declare function colourTier(colorterm: string | undefined): Tier;
+export declare function fg(c: Rgb, tier: Tier): string;
+export declare function bg(c: Rgb, tier: Tier): string;
+export {};

package/dist/graphite.js

@@ -0,0 +1,257 @@
+/**
+ * Graphite (design.md §2, §3.4) — the colour tokens, the output tier, and
+ * the surfaces derived from the ground the terminal actually reported.
+ *
+ * PURE: no process state is read except where a caller passes it in, so
+ * every decision here is testable without a terminal. `render.ts` turns
+ * these colours into SGR bytes; this module only decides the colours.
+ */
+import { groundFrom, relativeLuminance } from "./ground.js";
+/** The Graphite table (design.md §2), on the two reference grounds. */
+export const GRAPHITE = {
+    light: {
+        ground: "#ffffff",
+        ink: "#111111",
+        ink2: "#444444",
+        dim: "#646464",
+        rail: "#8c8c8c",
+        line: "#e6e6e6",
+        washRun: "#edf2fb",
+        washDone: "#f1f1f1",
+        washFail: "#fbecea",
+        washAsk: "#f7f1e3",
+        human: "#f7efdc",
+        humanInk: "#171923",
+        gold: "#8a5a00",
+        goldMark: "#c9921f",
+        blue: "#2456b5",
+        code: "#e4ebf8",
+        ok: "#2f7a3a",
+        fail: "#b3261e",
+        add: "#dff0e2",
+        del: "#fadfdc",
+        track: "#e2e2e2",
+    },
+    dark: {
+        ground: "#0b0b0b",
+        ink: "#ededed",
+        ink2: "#b5b5b5",
+        dim: "#8e8e8e",
+        rail: "#6b6b6b",
+        line: "#212121",
+        washRun: "#141b28",
+        washDone: "#1b1b1b",
+        washFail: "#2a1716",
+        washAsk: "#211d13",
+        human: "#efe6cf",
+        humanInk: "#141620",
+        gold: "#e3b04b",
+        goldMark: "#e3b04b",
+        blue: "#82a8f5",
+        code: "#1a2438",
+        ok: "#8fd19e",
+        fail: "#f2877a",
+        add: "#16301f",
+        del: "#3a1b1a",
+        track: "#2a2a2a",
+    },
+};
+/** The tokens that are GROUNDS near the terminal's own (§3.4): each is
+ *  derived from the reported ground. Every other token is fixed per kind. */
+export const SURFACES = ["line", "washRun", "washDone", "washFail", "washAsk", "human", "code", "add", "del", "track"];
+/** The text tokens that read on the ground and on the card surfaces (§2.1). */
+export const CARD_TEXT = ["ink", "ink2", "dim", "gold", "blue", "ok", "fail"];
+export const CARDS = ["washRun", "washDone", "washFail", "washAsk"];
+/** Every text-on-surface pair a human reads (§2.1's floor applies to each). */
+export const TEXT_PAIRS = [
+    ...["ground", ...CARDS].flatMap((surface) => CARD_TEXT.map((text) => [text, surface])),
+    ["humanInk", "human"],
+    ["blue", "code"],
+    ["ink", "add"],
+    ["ink", "del"],
+];
+export const FLOOR = 4.5;
+/** The floor for a GRAPHIC — a mark, not text (WCAG 1.4.11). The breath
+ *  never drops below it (§2.2). */
+export const GRAPHIC_FLOOR = 3;
+export function hexRgb(hex) {
+    const n = Number.parseInt(hex.slice(1), 16);
+    return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+export function rgbHex({ r, g, b }) {
+    return `#${[r, g, b].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+/** The WCAG contrast ratio, the measure of §2's floor. */
+export function contrast(a, b) {
+    const [x, y] = [relativeLuminance(a), relativeLuminance(b)].sort((p, q) => q - p);
+    return (x + 0.05) / (y + 0.05);
+}
+/** `t` of the way from `a` to `b`, per channel. */
+export function mix(a, b, t) {
+    const c = (x, y) => Math.round(x + (y - x) * t);
+    return { r: c(a.r, b.r), g: c(a.g, b.g), b: c(a.b, b.b) };
+}
+const REF_LIGHT = hexRgb(GRAPHITE.light.ground);
+const REF_DARK = hexRgb(GRAPHITE.dark.ground);
+/**
+ * §3.4 — one surface for any ground. Per channel an affine map
+ * `s = a + k·g`, fitted so that the white reference ground gives the
+ * table's white value and the black one its black value: the two
+ * grounds reproduce the table exactly, and a terminal whose black is
+ * `#1e1e1e` gets a card that sits the same distance off ITS ground.
+ */
+export function deriveSurface(token, ground) {
+    const w = hexRgb(GRAPHITE.light[token]);
+    const d = hexRgb(GRAPHITE.dark[token]);
+    const chan = (wc, dc, lw, ld, g) => {
+        const k = (wc - dc) / (lw - ld);
+        return Math.max(0, Math.min(255, Math.round(dc + k * (g - ld))));
+    };
+    return {
+        r: chan(w.r, d.r, REF_LIGHT.r, REF_DARK.r, ground.r),
+        g: chan(w.g, d.g, REF_LIGHT.g, REF_DARK.g, ground.g),
+        b: chan(w.b, d.b, REF_LIGHT.b, REF_DARK.b, ground.b),
+    };
+}
+function table(kind) {
+    const t = GRAPHITE[kind];
+    return Object.fromEntries(Object.entries(t).map(([k, v]) => [k, hexRgb(v)]));
+}
+/** A colour as the terminal will show it: itself in the 24-bit tier, the
+ *  nearest xterm-256 entry in the 256 tier. The floor is checked on what
+ *  is SHOWN — rounding to the nearest index can cost a pair its contrast. */
+export function shown(c, tier) {
+    return tier === "24bit" ? c : xterm256(nearest256(c));
+}
+/** One pair's ratio as shown. The ground is the terminal's own colour and
+ *  is never rounded; every token kiso writes is. */
+function pairRatio(c, text, surface, tier) {
+    const s = surface === "ground" ? c.ground : shown(c[surface], tier);
+    return contrast(shown(c[text], tier), s);
+}
+/** The weakest text-on-surface pair of a colour set, as shown in `tier`. */
+export function weakestPair(c, tier = "24bit") {
+    let worst = { pair: TEXT_PAIRS[0], ratio: Number.POSITIVE_INFINITY };
+    for (const pair of TEXT_PAIRS) {
+        const ratio = pairRatio(c, pair[0], pair[1], tier);
+        if (ratio < worst.ratio)
+            worst = { pair, ratio };
+    }
+    return worst;
+}
+/** A text token moved toward the kind's extreme (white on a dark ground,
+ *  black on a light one) just far enough that it clears the floor, as
+ *  shown, on every surface it reads on. Unmoved when it already does. */
+function lifted(c, token, kind, tier) {
+    const on = TEXT_PAIRS.filter(([t]) => t === token).map(([, s]) => s);
+    const extreme = kind === "dark" ? { r: 255, g: 255, b: 255 } : { r: 0, g: 0, b: 0 };
+    for (let t = 0; t <= 1.0001; t += 0.02) {
+        const cand = { ...c, [token]: mix(c[token], extreme, t) };
+        if (on.every((s) => pairRatio(cand, token, s, tier) >= FLOOR))
+            return cand[token];
+    }
+    return extreme;
+}
+/**
+ * The colours for one screen. `ground` is the RGB the terminal reported
+ * (OSC 11), or null when the ground was resolved without a colour — an
+ * explicit theme, the terminal's scheme report, COLORFGBG — in which case
+ * the table is used as it stands.
+ *
+ * A reported ground of the OTHER kind (a human who set `theme: light` on
+ * a black terminal) derives nothing: the answer the human gave wins, and
+ * surfaces fitted to a ground the text tokens were not chosen for would
+ * be wrong in both directions.
+ *
+ * On a reported ground the surfaces are derived (§3.4), and a text token
+ * that would fall under the floor — as shown in `tier` — on the ground or
+ * on a surface is moved toward the kind's extreme just far enough to clear
+ * it: a lighter dark theme lifts `dim`, never the other way. The table's
+ * own values pass on their reference grounds in both tiers, so there
+ * nothing moves. If a pair is still under the floor, the table is used.
+ */
+/** The last derivation, kept: the opening's rules and wordmark ask for
+ *  the colours on every frame (the banner is a live cell), and the answer
+ *  only moves with its three inputs (the render-perf pass, 2026-10-07).
+ *  Callers read the table; none writes to it. */
+let lastColours = null;
+export function graphiteColours(kind, ground, tier = "24bit") {
+    const r = ground === null ? -1 : ground.r;
+    const g = ground === null ? -1 : ground.g;
+    const b = ground === null ? -1 : ground.b;
+    const k = lastColours;
+    if (k !== null && k.kind === kind && k.tier === tier && k.r === r && k.g === g && k.b === b)
+        return k.out;
+    const out = deriveColours(kind, ground, tier);
+    lastColours = { kind, r, g, b, tier, out };
+    return out;
+}
+function deriveColours(kind, ground, tier) {
+    const base = table(kind);
+    if (ground === null || groundFrom(ground) !== kind)
+        return base;
+    const derived = { ...base, ground };
+    for (const s of SURFACES)
+        derived[s] = deriveSurface(s, ground);
+    for (const t of new Set(TEXT_PAIRS.map(([text]) => text)))
+        derived[t] = lifted(derived, t, kind, tier);
+    const out = derived;
+    return weakestPair(out, tier).ratio >= FLOOR ? out : base;
+}
+/**
+ * The command breath (§5.2): seven steps from `gold` toward the running
+ * card's ground, peak → floor → peak. The floor is the deepest step that
+ * still meets the graphic floor on that ground (§2.2): the mark dims and
+ * never disappears.
+ */
+export function breathRamp(c) {
+    const card = c.washRun;
+    let deepest = 0;
+    for (let t = 0; t <= 1.0001; t += 0.01) {
+        if (contrast(mix(c.gold, card, t), card) >= GRAPHIC_FLOOR)
+            deepest = t;
+        else
+            break;
+    }
+    const at = (f) => mix(c.gold, card, deepest * f);
+    return [at(0), at(1 / 3), at(2 / 3), at(1), at(2 / 3), at(1 / 3), at(0)];
+}
+/** The xterm-256 palette's colour for an index 16–255 (the cube and the
+ *  grey ramp; the first sixteen are the terminal's own and never chosen). */
+export function xterm256(index) {
+    if (index >= 232) {
+        const v = 8 + (index - 232) * 10;
+        return { r: v, g: v, b: v };
+    }
+    const i = index - 16;
+    const step = (n) => (n === 0 ? 0 : 55 + n * 40);
+    return { r: step(Math.floor(i / 36)), g: step(Math.floor(i / 6) % 6), b: step(i % 6) };
+}
+/** The nearest xterm-256 index (16–255) to a colour, by squared distance
+ *  in RGB — the 256 tier's whole translation. */
+export function nearest256(c) {
+    let best = 16;
+    let bestD = Number.POSITIVE_INFINITY;
+    for (let i = 16; i <= 255; i += 1) {
+        const x = xterm256(i);
+        const d = (x.r - c.r) ** 2 + (x.g - c.g) ** 2 + (x.b - c.b) ** 2;
+        if (d < bestD) {
+            bestD = d;
+            best = i;
+        }
+    }
+    return best;
+}
+/** §2 — 24-bit where the terminal says it renders it. `COLORTERM` is the
+ *  standard statement; anything else gets the 256 tier, which every
+ *  terminal kiso docks in renders. */
+export function colourTier(colorterm) {
+    const v = colorterm?.trim().toLowerCase();
+    return v === "truecolor" || v === "24bit" ? "24bit" : "256";
+}
+export function fg(c, tier) {
+    return tier === "24bit" ? `\x1b[38;2;${c.r};${c.g};${c.b}m` : `\x1b[38;5;${nearest256(c)}m`;
+}
+export function bg(c, tier) {
+    return tier === "24bit" ? `\x1b[48;2;${c.r};${c.g};${c.b}m` : `\x1b[48;5;${nearest256(c)}m`;
+}

package/dist/index.d.ts

@@ -7,14 +7,17 @@
  * API-stability promise yet.
  */
 export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, foldTerms, elapsedLabel, settledLabel, statusLine, boxTop, boxBottom, terminalPipe, type FrameCtx, type RenderLine, type Component, type BodyCell, } from "./components.js";
-export { editFileDiff, truncateDiff, writeFileDiff, type DiffLine, type DiffResult } from "./diff.js";
+export { editFileDiff, editFileHunksDiff, hunksDiff, hunksOf, truncateDiff, writeFileDiff, type DiffLine, type DiffResult, type Hunk } from "./diff.js";
 export { pendingQueueRows } from "./components.js";
 export { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
 export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWidth, panelStatus, type PanelArgs, type PanelFlavor, type PanelPhase, deletionRiskHint, SAFER_BACK, SAFER_DEGRADED, type SaferOption, type SaferRuntime, panelOptions, type PanelOption, type PanelOptionKind, type PanelState, type PanelVerdict, type PanelView, type AskAnswer, type AskOption, type AskQuestion, type AskResult, type AskRuntime, type AskSpec, } from "./approval-panel.js";
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact, } from "./strings.js";
-export { coldResumeLine, coldResumeView, extensionsBannerText, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";
+export { coldResumeLine, coldResumeView, extensionsBannerText, extensionsFact, helpRows, unansweredAskView, type BannerExtension } from "./strings.js";
 export { displayVerb } from "./strings.js";
-export { bannerLines, COLOR_OFF, COLOR_DARK, COLOR_LIGHT, COLOR_NEUTRAL, COLOR_ON, currentGround, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, MOTION_FRAMES, TWINKLE, breathFrame, twinkleFrame, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, type Palette, type ResumeMeta, } from "./render.js";
+export { bannerLines, COLOR_OFF, COLOR_DARK, COLOR_LIGHT, COLOR_NEUTRAL, COLOR_ON, currentGround, currentGroundRgb, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, paletteFor, relativeTime, renderResumeList, MOTION_FRAMES, TWINKLE, breathFrame, twinkleFrame, renderTerminalGap, renderToolSummary, TAGLINE, MOTTO, WORDMARK_W, type BannerFact, type BannerMeta, toolTarget, truncateRow, type Palette, type ResumeMeta, } from "./render.js";
 /** DC-3 — the ground: is the terminal light or dark. Pure; see the
  *  module comment for why `unknown` is a result and not a failure. */
 export { groundFrom, parseOscColor, relativeLuminance, resolveGround, type Ground, type GroundInputs, type Rgb } from "./ground.js";
+/** Graphite (design.md §2, §3.4) — the tokens, the tier and the derived
+ *  surfaces, as colours. Pure; `render.ts` writes them as SGR. */
+export { GRAPHITE, breathRamp, colourTier, contrast, deriveSurface, graphiteColours, hexRgb, nearest256, rgbHex, weakestPair, type Colours, type Kind, type Tier, type Token } from "./graphite.js";

package/dist/index.js

@@ -7,7 +7,7 @@
  * API-stability promise yet.
  */
 export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, foldTerms, elapsedLabel, settledLabel, statusLine, boxTop, boxBottom, terminalPipe, } from "./components.js";
-export { editFileDiff, truncateDiff, writeFileDiff } from "./diff.js";
+export { editFileDiff, editFileHunksDiff, hunksDiff, hunksOf, truncateDiff, writeFileDiff } from "./diff.js";
 // W22 (the v8 input round): the pending-queue chips — the SAME
 // UserMessage chip with the □ gutter, pre-rendered above the input
 // row while turns wait in the queue.
@@ -24,11 +24,14 @@ export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWi
 // the cli; what the human reads is presentation.
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, } from "./strings.js";
 // KC3.5: the interrupted-ask copy and the extracted /help table.
-export { coldResumeLine, coldResumeView, extensionsBannerText, helpRows, unansweredAskView } from "./strings.js";
+export { coldResumeLine, coldResumeView, extensionsBannerText, extensionsFact, helpRows, unansweredAskView } from "./strings.js";
 // TUI2-R2pre ④: the ONE display-verb table — the screen names the act,
 // the tool table names the call.
 export { displayVerb } from "./strings.js";
-export { bannerLines, COLOR_OFF, COLOR_DARK, COLOR_LIGHT, COLOR_NEUTRAL, COLOR_ON, currentGround, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, relativeTime, renderResumeList, MOTION_FRAMES, TWINKLE, breathFrame, twinkleFrame, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.js";
+export { bannerLines, COLOR_OFF, COLOR_DARK, COLOR_LIGHT, COLOR_NEUTRAL, COLOR_ON, currentGround, currentGroundRgb, setGround, escapeTerminal, foldResult, foldThinking, kUnit, palette, paletteFor, relativeTime, renderResumeList, MOTION_FRAMES, TWINKLE, breathFrame, twinkleFrame, renderTerminalGap, renderToolSummary, TAGLINE, MOTTO, WORDMARK_W, toolTarget, truncateRow, } from "./render.js";
 /** DC-3 — the ground: is the terminal light or dark. Pure; see the
  *  module comment for why `unknown` is a result and not a failure. */
 export { groundFrom, parseOscColor, relativeLuminance, resolveGround } from "./ground.js";
+/** Graphite (design.md §2, §3.4) — the tokens, the tier and the derived
+ *  surfaces, as colours. Pure; `render.ts` writes them as SGR. */
+export { GRAPHITE, breathRamp, colourTier, contrast, deriveSurface, graphiteColours, hexRgb, nearest256, rgbHex, weakestPair } from "./graphite.js";