@vincemakes/kiso-tui-cells 0.46.2 → 0.47.1

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,143 @@
+/**
+ * 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: "#c2c2c2";
+        readonly dim: "#a4a4a4";
+        readonly rail: "#6b6b6b";
+        readonly line: "#656565";
+        readonly washRun: "#2b3854";
+        readonly washDone: "#333333";
+        readonly washFail: "#4d2b28";
+        readonly washAsk: "#483818";
+        readonly human: "#e8dfc6";
+        readonly humanInk: "#141620";
+        readonly gold: "#e3b04b";
+        readonly goldMark: "#e3b04b";
+        readonly blue: "#82a8f5";
+        readonly code: "#283658";
+        readonly ok: "#8fd19e";
+        readonly fail: "#f2877a";
+        readonly add: "#2a5034";
+        readonly del: "#5e302d";
+        readonly track: "#474747";
+    };
+};
+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. A DARK 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 — a terminal
+ * whose black is `#1e1e1e` gets a card that sits the same distance off
+ * ITS ground, and the distance narrows as a dark ground lightens, which
+ * keeps the text above the floor on the lighter dark themes. A LIGHT
+ * ground: the light table, moved by how far the ground sits from white.
+ * The two reference grounds reproduce the table exactly.
+ *
+ * 0.47.1 (the dark table's re-adaptation): DECLARED REVERSAL for the
+ * light grounds only. The one map through both tables tied them to the
+ * dark table — lifting the dark cards pulled a card on `#eeeeee` to within
+ * 1.09:1 of its ground. A light ground now answers to the light table
+ * alone; on the light grounds measured the cards move by a channel step
+ * or two at most.
+ */
+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;
+/** 0.47.1 (owner, 2026-10-07) — 24-bit where the terminal is KNOWN to
+ *  render it, though it does not say so in COLORTERM. Windows Terminal is
+ *  the case that found it: drawn in the 256 tier, the person's cream block
+ *  became pink (index 224) and its gold edge olive (186). Each terminal is
+ *  recognised by what it sets; the list is the reference implementation's.
+ *  Inside tmux or screen only COLORTERM counts — the outer terminal's
+ *  variables are inherited, its rendering is not. Apple Terminal says it
+ *  in COLORTERM where it renders 24-bit (§2), and keeps the 256 tier
+ *  otherwise. PURE: the environment and the platform are passed in. */
+export declare function terminalTier(env: Readonly<Record<string, string | undefined>>, platform: string): Tier;
+export declare function fg(c: Rgb, tier: Tier): string;
+export declare function bg(c: Rgb, tier: Tier): string;
+export {};