@vincemakes/kiso-tui-cells 0.16.4 → 0.16.6

package/dist/approval-panel.js

@@ -273,7 +273,7 @@ export function panelBlockLayout(view, phase, cursor, W, maxRows, note, safer) {
     // block, and none of them the composer's. A rule SEPARATES, a gutter
     // SCOPES — the args keep their gutter because they are a verbatim
     // block; everything that was drawing a boundary is one rule now.
-    rows.push(`${p.dim}${"\u254c".repeat(Math.max(0, W))}${p.reset}`);
+    rows.push(`${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`);
     rows.push(`  ${cutLine(panelRuleText(view), Math.max(1, W - 2))}`);
     rows.push(`  ${cutLine(`${p.bold}${escapeTerminal(view.title)}${p.reset}`, Math.max(1, W - 2))}`);
     // TUI2-R1.5 ⑤ (VD-11): the divider is a LABEL, not a design note. "the
@@ -388,7 +388,7 @@ export function panelBlockLayout(view, phase, cursor, W, maxRows, note, safer) {
     // else in the product, so a CAPPED panel emitted two elbow rows in a
     // row meaning entirely different things. The rule reads as an edge,
     // and the cut notice above it reads as a notice.
-    rows.push(`${p.dim}${"\u254c".repeat(Math.max(0, W))}${p.reset}`);
+    rows.push(`${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`);
     return { rows, ...layout };
 }
 /**
@@ -493,7 +493,7 @@ export function panelAffordance(view, phase, cursor, safer) {
 export function pickBlockRows(view, state, W, maxRows) {
     const p = palette();
     const spec = view.pick;
-    const rows = [`${p.dim}${"\u254c".repeat(Math.max(0, W))}${p.reset}`]; // R2: the same rule the composer and the other panels use
+    const rows = [`${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`]; // R2: the same rule the composer and the other panels use
     const room = Math.max(1, W - 2);
     rows.push(`  ${cutLine(`${p.bold}${escapeTerminal(spec.header.split(" \u2014 ")[0] ?? spec.header)}${p.reset}${p.dim}${escapeTerminal(spec.header.slice((spec.header.split(" \u2014 ")[0] ?? "").length))}${p.reset}`, room)}`);
     if (spec.options.length === 0) {
@@ -546,7 +546,7 @@ export function pickBlockRows(view, state, W, maxRows) {
     const tText = cutLine(`${typing ? p.bold : ""}${typing ? "\u2192" : " "} t ${p.reset}${p.dim}${escapeTerminal(spec.typeHint)}${p.reset}`, room);
     rows.push(typing ? selectionBar(tText, visibleWidth(tText), W) : ` ${tText}`);
     rows.push(`  ${p.dim}${cutLine(pickAffordance(state), room)}${p.reset}`);
-    rows.push(`${p.dim}${"\u254c".repeat(Math.max(0, W))}${p.reset}`);
+    rows.push(`${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`);
     return rows;
 }
 /** The digits are the keys, so the list the panel offers is bounded by

package/dist/components.d.ts

@@ -293,6 +293,18 @@ export declare function exploreRows(parts: readonly {
  *  metadata terms survive (the W14 metadata rule — they give way LAST),
  *  the words width-cut at the end with the honest "…" (never a silent
  *  truncate — invariant ① holds on the ONE row by construction). */
+/**
+ * R3b — what a run of work DID, in words. One definition, because two
+ * surfaces say it: the fold line (`turnFold`, above) and the expand
+ * header the compositor writes when that fold is opened. A second copy
+ * would be a second answer to the same question, and the first thing to
+ * drift would be the plurals — `search_text` is "matches", not
+ * "searchs", and only the ROLLUP_NOUN table knows that.
+ *
+ * Zero terms are dropped (owner ruling, R3b): a term earns its place by
+ * having a count.
+ */
+export declare function foldTerms(reads: number, edits: number, others: readonly [string, number][]): string[];
 export declare function turnFold(t: {
     words: string;
     thoughtSeconds: number;
@@ -378,14 +390,19 @@ export declare function selectionBar(styled: string, visible: number, W: number)
 /**
  * R2 — the composer's rails, and the ONE edge vocabulary.
  *
+ * R3 (owner, 2026-08-27): the rule is a SOLID hairline (`\u2500`), not
+ * the dashed `\u254c` R2 shipped, and it is solid EVERYWHERE — the
+ * composer, every panel's open and close, the band headers and the
+ * markdown rule. One line, one weight, no exceptions to remember.
+ *
  * W6 turned two \u254c dotted rows into a rounded box, reasoning that
  * "the box already says input lives here". That is reversed here, and
  * the reason is not taste: a rule is a DELIMITER and a box is a
  * CONTAINER, and the screen was carrying six edge vocabularies at once
  * (this box, the panel's \u2502 gutter and \u2514\u2500\u2500 tail, the
  * diff gutter, the quote's \u258f, the table's rails, the markdown
- * rule). One dashed rule replaces the ones that SEPARATE; the \u2502
- * gutter survives where it SCOPES.
+ * rule). ONE rule replaces the ones that SEPARATE; the \u2502 gutter
+ * survives where it SCOPES.
  *
  * Row-neutral by construction: CHROME_ROWS is still 4, so every gate
  * keyed on H \u2212 4 is untouched, and the input row gains the two

package/dist/components.js

@@ -22,7 +22,7 @@ import { displayWidth, visibleWidth } from "./width.js";
 // KEY_BINDINGS). strings.js imports only render/width here, so this edge
 // adds no cycle.
 import { displayVerb } from "./strings.js";
-import { bannerLines, escapeTerminal, foldThinking, foldResult, renderTerminalGap, renderToolSummary, toolTarget, kUnit, palette, } from "./render.js";
+import { bannerLines, breathFrame, escapeTerminal, foldThinking, foldResult, renderTerminalGap, renderToolSummary, toolTarget, kUnit, palette, } from "./render.js";
 // TUI2-MD: the markdown renderer's surface reaches the tui through this
 // module (the tui's components shim re-exports it) — one import edge,
 // and it points one way: md.ts measures with the width authority, never
@@ -657,7 +657,14 @@ class ToolExecution {
             // leaves; the duration then rides the row, always legible.
             const elapsed = c.startedAt !== null ? Math.max(1, Math.round((ctx.now - c.startedAt) / 1000)) : 1;
             const dur = ` · ${elapsed}s`;
-            const out = gutterCut(`${p.bold}${SPINNER[ctx.spinnerI % SPINNER.length]}${p.reset} `, `${verbCol} ${liveTarget(c)}`, Math.max(4, W - dur.length));
+            // R3 (design §5.2): a running command BREATHES — one glyph, seven
+            // greys, bottoming out on the ground's dim token (§2.2 applies
+            // mid-animation, not just at rest). The quadrant spinner it
+            // replaces ROTATED, which §5.3 forbids for a call whose duration
+            // cannot be predicted: a turning mark implies progress the
+            // product does not have. With no ground the breath freezes to a
+            // static `●` and says the same thing more quietly.
+            const out = gutterCut(`${breathFrame(ctx.spinnerI)} `, `${verbCol} ${liveTarget(c)}`, Math.max(4, W - dur.length));
             out[0] = `${out[0]}${p.dim}${dur}${p.reset}`;
             out.push(...toolBlockBody(c, W));
             return out;
@@ -953,23 +960,56 @@ function countTerm(n, singular, plural) {
  *  metadata terms survive (the W14 metadata rule — they give way LAST),
  *  the words width-cut at the end with the honest "…" (never a silent
  *  truncate — invariant ① holds on the ONE row by construction). */
-export function turnFold(t, W) {
-    const p = palette();
-    const parts = [`thought ${t.thoughtSeconds}s`, countTerm(t.reads, "read", "reads"), countTerm(t.edits, "edit", "edits")];
-    for (const [name, n] of t.others) {
+/**
+ * R3b — what a run of work DID, in words. One definition, because two
+ * surfaces say it: the fold line (`turnFold`, above) and the expand
+ * header the compositor writes when that fold is opened. A second copy
+ * would be a second answer to the same question, and the first thing to
+ * drift would be the plurals — `search_text` is "matches", not
+ * "searchs", and only the ROLLUP_NOUN table knows that.
+ *
+ * Zero terms are dropped (owner ruling, R3b): a term earns its place by
+ * having a count.
+ */
+export function foldTerms(reads, edits, others) {
+    const parts = [];
+    if (reads > 0)
+        parts.push(countTerm(reads, "read", "reads"));
+    if (edits > 0)
+        parts.push(countTerm(edits, "edit", "edits"));
+    for (const [name, n] of others) {
+        if (n === 0)
+            continue;
         const noun = ROLLUP_NOUN[name];
-        if (noun !== undefined) {
+        if (noun !== undefined)
             parts.push(countTerm(n, noun.endsWith("es") ? noun.slice(0, -2) : noun.slice(0, -1), noun));
-        }
         else {
             const verb = displayVerb(name);
             parts.push(countTerm(n, verb, `${verb}s`));
         }
     }
-    const meta = parts.join(" · ");
+    return parts;
+}
+export function turnFold(t, W) {
+    const p = palette();
+    // R3b (owner, 2026-08-27): ZERO TERMS ARE DROPPED. W14 always wrote
+    // `no reads · no edits`, which is a sentence about things that did not
+    // happen — on a segment fold, where a run is usually all reads or all
+    // edits, half the row was the half that said nothing. A term earns its
+    // place by having a count.
+    const meta = [`thought ${t.thoughtSeconds}s`, ...foldTerms(t.reads, t.edits, t.others)].join(" · ");
     const words = escapeTerminal(t.words);
     if (words === "") {
         const row = `${p.bold}✦${p.reset} ${meta}`;
+        // R3b: the fold NAMES ITS OWN KEY. Without it the segment's work is
+        // unreachable — no rollup row, no expand, nothing — and hiding a
+        // tool call behind a line with no way back is the one thing this
+        // product must not do. The suffix gives way first at a narrow
+        // width, on the same principle the settled card's does: an
+        // affordance that does not fit is dropped, never half-drawn.
+        const keyed = `${row}${p.dim} · ctrl+r${p.reset}`;
+        if (visibleWidth(keyed) <= W)
+            return [keyed];
         return visibleWidth(row) <= W ? [row] : [`${p.bold}✦${p.reset} ${widthCut(meta, Math.max(1, W - 3))}…`]; // a wordless turn folds to the W14 shape
     }
     // A9 (ruling R2, mock A): the user chip rides the fold — the human's
@@ -1547,26 +1587,36 @@ export function selectionBar(styled, visible, W) {
 /**
  * R2 — the composer's rails, and the ONE edge vocabulary.
  *
+ * R3 (owner, 2026-08-27): the rule is a SOLID hairline (`\u2500`), not
+ * the dashed `\u254c` R2 shipped, and it is solid EVERYWHERE — the
+ * composer, every panel's open and close, the band headers and the
+ * markdown rule. One line, one weight, no exceptions to remember.
+ *
  * W6 turned two \u254c dotted rows into a rounded box, reasoning that
  * "the box already says input lives here". That is reversed here, and
  * the reason is not taste: a rule is a DELIMITER and a box is a
  * CONTAINER, and the screen was carrying six edge vocabularies at once
  * (this box, the panel's \u2502 gutter and \u2514\u2500\u2500 tail, the
  * diff gutter, the quote's \u258f, the table's rails, the markdown
- * rule). One dashed rule replaces the ones that SEPARATE; the \u2502
- * gutter survives where it SCOPES.
+ * rule). ONE rule replaces the ones that SEPARATE; the \u2502 gutter
+ * survives where it SCOPES.
  *
  * Row-neutral by construction: CHROME_ROWS is still 4, so every gate
  * keyed on H \u2212 4 is untouched, and the input row gains the two
  * columns the walls were taking.
  */
 export function boxTop(W) {
-    return `\x1b[2m${"\u254c".repeat(Math.max(0, W))}\x1b[0m`;
+    // R3: the palette's dim, not a hardcoded SGR 2 — `dim` is an absolute
+    // grey once the ground is known, and a rail that hardcodes the
+    // attribute would be the one chrome row not obeying the table.
+    const p = palette();
+    return `${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`;
 }
 /** R2 — the same rule below. Named for its POSITION, not its shape, so
  *  the compositor's two call sites did not have to move. */
 export function boxBottom(W) {
-    return `\x1b[2m${"\u254c".repeat(Math.max(0, W))}\x1b[0m`;
+    const p = palette();
+    return `${p.dim}${"\u2500".repeat(Math.max(0, W))}${p.reset}`;
 }
 /** The terminal label + rhythm gap (the pipe path's v2c bytes — the
  *  exact render the passthrough needs). */

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * package); the cli never imports it directly. Experimental — no
  * API-stability promise yet.
  */
-export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, focusToken, ROLLUP_NOUN, turnFold, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, type FrameCtx, type RenderLine, type Component, type BodyCell, } from "./components.js";
+export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, focusToken, ROLLUP_NOUN, turnFold, foldTerms, CAP_TASK_LIVE, formatDuration, 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 { pendingQueueRows } from "./components.js";
 export { charWidth, displayWidth, leadWidth, widthOf } from "./width.js";
@@ -14,7 +14,7 @@ export { panelAffordance, panelBlockRows, panelLead, panelLeadPlain, panelLeadWi
 export { interactivePrompt, projectTrustRows, projectTrustView, projectUntrustedNote, uncertainView, type TrustArtifact, } from "./strings.js";
 export { extensionsBannerText, 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, 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, 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";
 /** 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";

package/dist/index.js

@@ -6,7 +6,7 @@
  * package); the cli never imports it directly. Experimental — no
  * API-stability promise yet.
  */
-export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, focusToken, ROLLUP_NOUN, turnFold, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, } from "./components.js";
+export { SPINNER, foldLine, foldWords, visibleWidth, bodySpacing, Container, cellComponent, focusToken, ROLLUP_NOUN, turnFold, foldTerms, CAP_TASK_LIVE, formatDuration, statusLine, boxTop, boxBottom, terminalPipe, } from "./components.js";
 export { editFileDiff, 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
@@ -28,7 +28,7 @@ export { extensionsBannerText, 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, renderTerminalGap, renderToolSummary, TAGLINE, toolTarget, truncateRow, } from "./render.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";
 /** 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";

package/dist/md.js

@@ -258,7 +258,7 @@ function blockBody(b, W) {
             // R2: the dashed rule, at the block's own width. The 28 was a
             // guess that read as a short line rather than a divider, and ─
             // belonged to the box vocabulary this round is collapsing.
-            return [`${p.dim}${"\u254c".repeat(Math.max(1, W))}${p.reset}`];
+            return [`${p.dim}${"\u2500".repeat(Math.max(1, W))}${p.reset}`];
         case "fence-open":
             // E2: the RAIL, not a gutter. A block drawn with ``` is still a
             // fenced block when a human selects it and pastes it somewhere

package/dist/render.d.ts

@@ -82,11 +82,22 @@ export interface Palette {
 /**
  * DC-3 — one table per ground.
  *
- * `dim` is the same in all three ON tables and that is the point: SGR 2
- * is an ATTRIBUTE, it dims whatever the terminal's own foreground is, so
- * it adapts to the ground instead of asserting one. Only the background
- * genuinely needs to know, which is why `wash` is the only member that
- * varies.
+ * 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).
+ *
+ * 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
+ * right about what SGR 2 IS and wrong about what it MEASURES: a
+ * terminal renders it as a fraction of its own foreground, and on Apple
+ * Terminal's light profile that lands well under the 4.5:1 floor — the
+ * labels, the keys row and the status row were all reported unreadable
+ * in real use. An attribute that adapts to an unknown ratio is not a
+ * contrast guarantee; the table's measured value is.
+ *
+ * The UNKNOWN ground keeps SGR 2, because §3.1 forbids an absolute
+ * foreground in a palette that has not established a background — the
+ * attribute is exactly the "correct on any ground" degradation there.
  */
 export declare const COLOR_NEUTRAL: Palette;
 export declare const COLOR_LIGHT: Palette;
@@ -141,6 +152,42 @@ export declare function kUnit(value: number | null): string;
  * this verbatim; the render tests pin the sequence.
  */
 export declare function renderTerminalGap(statusLine: string | null): string;
+/**
+ * v3 §01 (V6-2) — the banner, block-split. The logo is THREE BRICK rows
+ * (the logo.svg pixel form — K I S O), then a BLANK, then the info rows:
+ * "kiso vX — tagline" + extensions. The tagline rides the version line
+ * (the old logo MIDDLE row was the tagline — a text row masquerading as
+ * the logo's centre). Every row truncates at the terminal width with a
+ * " (+N)" marker (N = the hidden display width); a window narrower than
+ * 40 columns skips the logo + the blank entirely — only the info rows.
+ * Pure.
+ */
+/**
+ * design.md §5.2 — THE TWO CYCLES, built. Seven frames each, walked at
+ * the existing 200ms spinner cadence, so a waiting screen's byte volume
+ * and frame rate are exactly what they were.
+ *
+ * §5.3 is why neither rotates: "a breath says alive; a turn says
+ * counting". A call whose duration cannot be predicted must not wear a
+ * mark that implies progress it does not have.
+ */
+/** The THINKING twinkle — glyphs only, no colour at all, so it survives
+ *  NO_COLOR and any ground intact. §4.1: it settles onto `✦`, which is
+ *  the same mark the collapsed segment keeps, so nothing new appears at
+ *  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. */
+export declare function breathFrame(step: number): string;
+/** The twinkle's frame — pure glyph, no palette involved. */
+export declare function twinkleFrame(step: number): string;
+/** Both cycles are seven frames, so ONE counter walks them and the two
+ *  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. */

package/dist/render.js

@@ -28,19 +28,30 @@ const BASE = { bold: "\x1b[1m", dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32
  * 4's principle exactly: when the ground is unknown, use the thing that
  * is correct on any ground rather than guessing one.
  */
-const withWash = (wash, washEnd, red = BASE.red) => ({ ...BASE, red, wash, washEnd, code: wash });
+const withWash = (wash, washEnd, red = BASE.red, dim = BASE.dim) => ({ ...BASE, red, dim, wash, washEnd, code: wash });
 /**
  * DC-3 — one table per ground.
  *
- * `dim` is the same in all three ON tables and that is the point: SGR 2
- * is an ATTRIBUTE, it dims whatever the terminal's own foreground is, so
- * it adapts to the ground instead of asserting one. Only the background
- * genuinely needs to know, which is why `wash` is the only member that
- * varies.
+ * 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).
+ *
+ * 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
+ * right about what SGR 2 IS and wrong about what it MEASURES: a
+ * terminal renders it as a fraction of its own foreground, and on Apple
+ * Terminal's light profile that lands well under the 4.5:1 floor — the
+ * labels, the keys row and the status row were all reported unreadable
+ * in real use. An attribute that adapts to an unknown ratio is not a
+ * contrast guarantee; the table's measured value is.
+ *
+ * The UNKNOWN ground keeps SGR 2, because §3.1 forbids an absolute
+ * foreground in a palette that has not established a background — the
+ * attribute is exactly the "correct on any ground" degradation there.
  */
 export const COLOR_NEUTRAL = withWash("\x1b[7m", "\x1b[27m");
-export const COLOR_LIGHT = withWash("\x1b[48;5;255m", "\x1b[49m", "\x1b[38;5;124m");
-export const COLOR_DARK = withWash("\x1b[48;5;236m", "\x1b[49m", "\x1b[38;5;173m");
+export const COLOR_LIGHT = withWash("\x1b[48;5;255m", "\x1b[49m", "\x1b[38;5;124m", "\x1b[38;5;243m");
+export const COLOR_DARK = withWash("\x1b[48;5;236m", "\x1b[49m", "\x1b[38;5;173m", "\x1b[38;5;246m");
 /** The historical name — the palette for a colour TTY whose ground has
  *  not been established. Unchanged in every byte except `code`, which
  *  was the defect. */
@@ -211,6 +222,46 @@ export function renderTerminalGap(statusLine) {
  * 40 columns skips the logo + the blank entirely — only the info rows.
  * Pure.
  */
+/**
+ * design.md §5.2 — THE TWO CYCLES, built. Seven frames each, walked at
+ * the existing 200ms spinner cadence, so a waiting screen's byte volume
+ * and frame rate are exactly what they were.
+ *
+ * §5.3 is why neither rotates: "a breath says alive; a turn says
+ * counting". A call whose duration cannot be predicted must not wear a
+ * mark that implies progress it does not have.
+ */
+/** The THINKING twinkle — glyphs only, no colour at all, so it survives
+ *  NO_COLOR and any ground intact. §4.1: it settles onto `✦`, which is
+ *  the same mark the collapsed segment keeps, so nothing new appears at
+ *  the transition. Every glyph is in Menlo and absent from Apple Color
+ *  Emoji (§6.1's test, run). */
+export const TWINKLE = ["\u2727", "\u2726", "\u2736", "\u2738", "\u273a", "\u2738", "\u2726"];
+/** The COMMAND breath — brightness only, one glyph. The ramps bottom out
+ *  EXACTLY on the ground's dim token (§2.2: "the floor is a floor,
+ *  including mid-animation"): light ends at 243 (4.54:1 on white), dark
+ *  at 246 (5.50:1 on #1e1e1e). Measured, not assumed. */
+const BREATH_LIGHT = [232, 236, 240, 243, 240, 236, 232];
+const BREATH_DARK = [255, 251, 248, 246, 248, 251, 255];
+/** 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. */
+export function breathFrame(step) {
+    const p = palette();
+    const ramp = currentGround() === "light" ? BREATH_LIGHT : currentGround() === "dark" ? BREATH_DARK : null;
+    if (ramp === null || p.bold === "")
+        return "\u25cf";
+    return `\x1b[38;5;${ramp[step % ramp.length]}m\u25cf${p.reset}`;
+}
+/** The twinkle's frame — pure glyph, no palette involved. */
+export function twinkleFrame(step) {
+    return TWINKLE[step % TWINKLE.length];
+}
+/** Both cycles are seven frames, so ONE counter walks them and the two
+ *  marks stay in step on a screen showing both. */
+export const MOTION_FRAMES = 7;
 /** DC-18: the display-width prefix of PLAIN text. `widthCut` lives in
  *  components.ts, which imports this module — the dependency runs one
  *  way, so the four lines live here rather than inverting it. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui-cells",
-	"version": "0.16.4",
+	"version": "0.16.6",
 	"description": "kiso tui-cells — the components cell renderer (components, diff, width, the render slice). Zero runtime dependencies: input is data, output is bytes.",
 	"type": "module",
 	"license": "MIT",