@askdkc/dsh-cli 0.11.3

package/lib/types/trajectory/effortIgnition.d.ts

@@ -0,0 +1,66 @@
+/** 三幕时间轴（ms）：扫光全长、字样启动（波至中段）、字样渐亮、渐隐起止。边框扫光与输入行字样徽标共用。 */
+export declare const IGNITION_TIMELINE: {
+    readonly sweepMs: 1000;
+    readonly labelStartMs: 600;
+    readonly labelBrightenMs: 160;
+    readonly fadeStartMs: 1500;
+    readonly fadeEndMs: 2000;
+};
+/**
+ * Effort ignition motion math — pure functions, zero dependencies.
+ *
+ * Waveform semantics ported from Codex CLI's effort_ignition(_styles).rs
+ * (openai/codex PR #34365) and revalidated in a dsh-TUI integration: a
+ * cosine-bell travelling wave produces per-column colours only — a renderer
+ * that keeps glyphs constant and changes colours per frame stays SGR-only
+ * by construction.
+ *
+ * Consumers ride the FOREGROUND channel (a constant block glyph under a
+ * varying fg colour): pure-background cells never reached the terminal in
+ * the fullscreen log-update pipeline, while foreground is the channel every
+ * live element already rides.
+ */
+import type { RGBColor } from '../components/Spinner/spinnerUtils.js';
+/** 扫光全长（ms），仅用于把墙钟时间折算成动画秒数，不创建任何定时器。 */
+export declare const SWEEP_TOTAL_MS = 1000;
+export declare function ignitionHues(onLight: boolean): readonly [RGBColor, RGBColor, RGBColor];
+/**
+ * 充能色对（前缀强调用）：从带底色调暗端到全值，与波共用 hues[0]。
+ */
+export declare function accentRamp(onLight: boolean): {
+    dim: RGBColor;
+    full: RGBColor;
+};
+/** 余弦钟形：`crest(0)=1`、`crest(±1)=0`、之外为 0（负距离同样静默——
+ * 现有调用方都传 `Math.abs`，这里兜底防未来调用方拿到全强度）。 */
+export declare function crest(distance: number): number;
+/** ease-out cubic：`1-(1-p)³`，两端 clamp。 */
+export declare function easeOutCubic(progress: number): number;
+/** ease-in-out cubic：前半 `4p³`、后半镜像，两端 clamp。 */
+export declare function easeInOutCubic(progress: number): number;
+/** 线性混色（t=0 → a，t=1 → b，不 clamp）。 */
+export declare function blend(a: RGBColor, b: RGBColor, t: number): RGBColor;
+/**
+ * 扫光某一时刻的整行颜色。
+ *
+ * @param options.elapsedMs - 距触发的时间；达到 {@link SWEEP_TOTAL_MS}
+ *   后整行返回空数组（无波，行恢复本底）。
+ * @param options.width - 行列数（终端宽）。
+ * @param options.onLight - 浅色主题时用浅底色板与浅带底色。
+ * @returns 逐列颜色（`rgb(r,g,b)` 字符串）；无波的列为 `undefined`，
+ *   渲染层应输出本底色，保持行宽恒定。
+ */
+export declare function ignitionLineColors(options: {
+    elapsedMs: number;
+    width: number;
+    onLight: boolean;
+}): ReadonlyArray<string | undefined>;
+/**
+ * 顶档切入判定：从「已有档位」变为「另一档位」且新档位是档位表末位
+ * 最高档。冷启动恢复偏好、单档表、档位表未知都不触发。
+ */
+export declare function entersTopTier(previous: string | undefined, current: string | undefined, levels: readonly string[] | undefined): boolean;
+/** 充能时长（ms）与充能进度（钳 [0,1]，负 elapsed 钳 0）。 */
+export declare const CHARGE_MS = 150;
+export declare function chargeProgress(elapsedMs: number): number;
+//# sourceMappingURL=effortIgnition.d.ts.map

package/lib/types/trajectory/effortIgnition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortIgnition.d.ts","sourceRoot":"","sources":["../../../src/trajectory/effortIgnition.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB;;;;;;CAMpB,CAAA;AAEV;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAA;AAGrE,yCAAyC;AACzC,eAAO,MAAM,cAAc,OAAO,CAAA;AA8BlC,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAEtF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,GAAG,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAG9E;AAED;0CAC0C;AAC1C,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKvD;AAaD,qCAAqC;AACrC,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,QAAQ,CAMnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,CA0BpC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACpC,OAAO,CAST;AAED,4CAA4C;AAC5C,eAAO,MAAM,SAAS,MAAM,CAAA;AAE5B,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/lib/types/trajectory/effortIgnition.js

@@ -0,0 +1,142 @@
+/** 三幕时间轴（ms）：扫光全长、字样启动（波至中段）、字样渐亮、渐隐起止。边框扫光与输入行字样徽标共用。 */
+export const IGNITION_TIMELINE = {
+    sweepMs: 1000,
+    labelStartMs: 600,
+    labelBrightenMs: 160,
+    fadeStartMs: 1500,
+    fadeEndMs: 2000,
+};
+import { rgbString } from './motion.js';
+/** 扫光全长（ms），仅用于把墙钟时间折算成动画秒数，不创建任何定时器。 */
+export const SWEEP_TOTAL_MS = 1000;
+/** 波形宽度参数（列）。 */
+const WAVE_HALF_WIDTH = 14;
+/** 波形参数：`[launch, travel]`（秒）——扫光在何时启动、多久行至右缘。 */
+const BAND = [0.1, 0.75];
+/**
+ * 高亮彩色色板：亮蓝/亮青/亮紫三 hue（浅色背景用加深变体——浅底上
+ * 亮色没有对比度）。波只点亮 hues[0]，前两个 hue 留给未来的多带风格。
+ */
+const HUES_DARK = [
+    { r: 130, g: 185, b: 255 },
+    { r: 140, g: 252, b: 248 },
+    { r: 195, g: 172, b: 255 },
+];
+const HUES_LIGHT = [
+    { r: 30, g: 95, b: 235 },
+    { r: 10, g: 160, b: 200 },
+    { r: 120, g: 80, b: 235 },
+];
+/**
+ * 带底色（波向终端本底淡入的目标色）。近似值：取主题深/浅背景的典
+ * 型值而非逐主题读取——波只存活一秒，色差在低 alpha 下不可辨。
+ */
+const BAND_DARK = { r: 27, g: 30, b: 40 };
+const BAND_LIGHT = { r: 240, g: 240, b: 242 };
+export function ignitionHues(onLight) {
+    return onLight ? HUES_LIGHT : HUES_DARK;
+}
+/**
+ * 充能色对（前缀强调用）：从带底色调暗端到全值，与波共用 hues[0]。
+ */
+export function accentRamp(onLight) {
+    const band = onLight ? BAND_LIGHT : BAND_DARK;
+    return { dim: blend(band, ignitionHues(onLight)[0], 0.45), full: ignitionHues(onLight)[0] };
+}
+/** 余弦钟形：`crest(0)=1`、`crest(±1)=0`、之外为 0（负距离同样静默——
+ * 现有调用方都传 `Math.abs`，这里兜底防未来调用方拿到全强度）。 */
+export function crest(distance) {
+    if (distance >= 1 || distance <= -1)
+        return 0;
+    return 0.5 * (1 + Math.cos(Math.PI * distance));
+}
+/** ease-out cubic：`1-(1-p)³`，两端 clamp。 */
+export function easeOutCubic(progress) {
+    const p = Math.min(1, Math.max(0, progress));
+    const inverse = 1 - p;
+    return 1 - inverse * inverse * inverse;
+}
+/** ease-in-out cubic：前半 `4p³`、后半镜像，两端 clamp。 */
+export function easeInOutCubic(progress) {
+    const p = Math.min(1, Math.max(0, progress));
+    if (p < 0.5)
+        return 4 * p * p * p;
+    const inverse = -2 * p + 2;
+    return 1 - (inverse * inverse * inverse) / 2;
+}
+/** 单列对波带的采样：三 hue 权重（未归一；单波形只点亮 hue[0]）。 */
+function sampleColumn(elapsed, column, width) {
+    const weights = [0, 0, 0];
+    const [launch, travel] = BAND;
+    const progress = (elapsed - launch) / travel;
+    if (progress < 0 || progress > 1)
+        return weights;
+    const center = easeInOutCubic(progress) * (width + 2 * WAVE_HALF_WIDTH) - WAVE_HALF_WIDTH;
+    weights[0] = crest(Math.abs(column - center) / WAVE_HALF_WIDTH);
+    return weights;
+}
+/** 线性混色（t=0 → a，t=1 → b，不 clamp）。 */
+export function blend(a, b, t) {
+    return {
+        r: Math.round(a.r + (b.r - a.r) * t),
+        g: Math.round(a.g + (b.g - a.g) * t),
+        b: Math.round(a.b + (b.b - a.b) * t),
+    };
+}
+/**
+ * 扫光某一时刻的整行颜色。
+ *
+ * @param options.elapsedMs - 距触发的时间；达到 {@link SWEEP_TOTAL_MS}
+ *   后整行返回空数组（无波，行恢复本底）。
+ * @param options.width - 行列数（终端宽）。
+ * @param options.onLight - 浅色主题时用浅底色板与浅带底色。
+ * @returns 逐列颜色（`rgb(r,g,b)` 字符串）；无波的列为 `undefined`，
+ *   渲染层应输出本底色，保持行宽恒定。
+ */
+export function ignitionLineColors(options) {
+    const { elapsedMs, width, onLight } = options;
+    const elapsed = elapsedMs / 1000;
+    const total = SWEEP_TOTAL_MS / 1000;
+    if (width <= 0 || !Number.isFinite(elapsed) || elapsed <= 0 || elapsed >= total)
+        return [];
+    const hue = ignitionHues(onLight)[0];
+    const band = onLight ? BAND_LIGHT : BAND_DARK;
+    const colors = new Array(width);
+    for (let column = 0; column < width; column++) {
+        const weight = sampleColumn(elapsed, column, width)[0];
+        if (weight <= 0.01) {
+            colors[column] = undefined;
+            continue;
+        }
+        // 波按强度淡入带底色：alpha=1 是纯 hue，alpha→0 收敛回本底；高亮
+        // 度档满强度纯 hue 直出。输出前通道量化到 8 步长——渐变列因此能
+        // 合并成长段（渲染层 RLE 段数降一个数量级），8/256 的色差在终端
+        // cell 分辨率下不可辨。
+        const tinted = blend(band, hue, Math.min(weight, 1));
+        colors[column] = rgbString({
+            r: Math.round(tinted.r / 8) * 8,
+            g: Math.round(tinted.g / 8) * 8,
+            b: Math.round(tinted.b / 8) * 8,
+        });
+    }
+    return colors;
+}
+/**
+ * 顶档切入判定：从「已有档位」变为「另一档位」且新档位是档位表末位
+ * 最高档。冷启动恢复偏好、单档表、档位表未知都不触发。
+ */
+export function entersTopTier(previous, current, levels) {
+    return (current !== undefined &&
+        previous !== undefined &&
+        current !== previous &&
+        levels !== undefined &&
+        levels.length > 1 &&
+        current === levels[levels.length - 1]);
+}
+/** 充能时长（ms）与充能进度（钳 [0,1]，负 elapsed 钳 0）。 */
+export const CHARGE_MS = 150;
+export function chargeProgress(elapsedMs) {
+    if (!Number.isFinite(elapsedMs))
+        return 0;
+    return Math.min(1, Math.max(0, Math.max(0, elapsedMs) / CHARGE_MS));
+}

package/lib/types/trajectory/format.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Trajectory formatting — durations, clocks, badges and heat.
+ *
+ * Presentation only, and deliberately in the UI layer rather than beside the
+ * projection: these decisions are about a terminal's width and palette, not
+ * about what the session log means.
+ */
+import type { Theme } from '../theme.js';
+import type { TrajKind } from '../dsh-adapter/types.js';
+/**
+ * Truncate to a terminal DISPLAY width, CJK-aware (a wide char costs two
+ * columns). Used where the caller must control the cut precisely: Ink's own
+ * `wrap="truncate"` appends its ellipsis as soon as the content is as wide as
+ * its box rather than wider, which silently eats the last character of a
+ * right-aligned group that was laid out at exactly its natural width.
+ *
+ * @param text - Plain text (no ANSI).
+ * @param maxWidth - Column budget, ellipsis included.
+ * @returns `text` unchanged when it fits, otherwise a cut ending in `…`.
+ */
+export declare function truncateWidth(text: string, maxWidth: number): string;
+/** `HH:MM:SS` local wall-clock of an epoch-ms timestamp. */
+export declare function formatClock(time: number): string;
+/**
+ * Compact duration: `82ms` / `1.4s` / `2m05s` / `1h04m`.
+ *
+ * Every form is at most six columns wide, so the ledger's duration column
+ * never reflows when a fast call is followed by a slow one.
+ */
+export declare function formatDuration(ms: number): string;
+/** Compact token count: `840` / `12.4k` / `1.1M`. */
+export declare function formatTokens(count: number): string;
+/**
+ * Heat colour for a duration cell.
+ *
+ * The point of the ledger is usually to find the slow thing, so the duration
+ * column encodes magnitude as colour: anything under a second recedes, tens
+ * of seconds warn, minutes shout. Reading a column of numbers is work; seeing
+ * one red cell is not.
+ */
+export declare function heatColor(ms: number | undefined): keyof Theme;
+/**
+ * Cost glyph for a row's own duration — an ABSOLUTE, learnable scale.
+ *
+ * A relative scale (tallest row in view = full block) would re-teach itself on
+ * every scroll; fixed thresholds mean `█` always says "over a minute" and `▁`
+ * always says "instant", so after one session the column is read without
+ * looking at the number beside it. Each step is roughly half an order of
+ * magnitude, which is the resolution a human actually acts on.
+ */
+export declare function costGlyph(ms: number | undefined): string;
+/**
+ * Fixed-width badge text per row kind — six columns, including one cell of
+ * padding on each side.
+ *
+ * The padding is what turns a coloured word into a pill. Background colour
+ * flush against the glyphs reads as a highlighter smudge; a cell of ground on
+ * either side reads as a chip, and chips are what let the eye group forty rows
+ * by kind without reading any of them.
+ */
+export declare const KIND_BADGE: Record<TrajKind, string>;
+/** One-character badge for the narrowest layout tier. */
+export declare const KIND_GLYPH: Record<TrajKind, string>;
+/**
+ * Badge foreground per kind. Backgrounds come from {@link KIND_BADGE_BG} — the
+ * pair reads as a pill, which carries far better in a dense ledger than
+ * coloured text alone.
+ */
+export declare const KIND_FG: Record<TrajKind, keyof Theme>;
+/**
+ * Badge background per kind, or `undefined` for kinds that read better
+ * unfilled (structural rows, which should recede behind the work rows).
+ */
+export declare const KIND_BADGE_BG: Partial<Record<TrajKind, keyof Theme>>;
+/**
+ * Ledger column budget at a given terminal width.
+ *
+ * Columns are dropped whole rather than letting a row wrap: a wrapped ledger
+ * row destroys the alignment that makes the whole view scannable, so at every
+ * tier the row is still exactly one line.
+ */
+export interface LedgerLayout {
+    /** Width of the badge column: 6 (padded pill), 1 (bare glyph). */
+    readonly badge: 6 | 1;
+    /** Show the `#N` index column. */
+    readonly index: boolean;
+    /** Show the `→ result` preview. */
+    readonly outcome: boolean;
+    /** Characters available to the label + detail preview. */
+    readonly detail: number;
+}
+/**
+ * Resolve the column budget for one terminal width.
+ *
+ * @param columns - Terminal width in cells.
+ * @returns The tier's budget; `detail` is never below 12 so the label itself
+ *   survives even on a pathologically narrow terminal.
+ */
+export declare function ledgerLayout(columns: number): LedgerLayout;
+//# sourceMappingURL=format.d.ts.map

package/lib/types/trajectory/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/trajectory/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYpE;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,KAAK,CAM7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAUxD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAc/C,CAAA;AAED,yDAAyD;AACzD,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAc/C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,KAAK,CAiBjD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,KAAK,CAAC,CAWhE,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAA;IACrB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAO1D"}

package/lib/types/trajectory/format.js

@@ -0,0 +1,213 @@
+/**
+ * Trajectory formatting — durations, clocks, badges and heat.
+ *
+ * Presentation only, and deliberately in the UI layer rather than beside the
+ * projection: these decisions are about a terminal's width and palette, not
+ * about what the session log means.
+ */
+import { stringWidth } from '../ink/stringWidth.js';
+/**
+ * Truncate to a terminal DISPLAY width, CJK-aware (a wide char costs two
+ * columns). Used where the caller must control the cut precisely: Ink's own
+ * `wrap="truncate"` appends its ellipsis as soon as the content is as wide as
+ * its box rather than wider, which silently eats the last character of a
+ * right-aligned group that was laid out at exactly its natural width.
+ *
+ * @param text - Plain text (no ANSI).
+ * @param maxWidth - Column budget, ellipsis included.
+ * @returns `text` unchanged when it fits, otherwise a cut ending in `…`.
+ */
+export function truncateWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return '';
+    if (stringWidth(text) <= maxWidth)
+        return text;
+    let width = 0;
+    let out = '';
+    for (const char of text) {
+        const charWidth = stringWidth(char);
+        if (width + charWidth > maxWidth - 1)
+            break;
+        width += charWidth;
+        out += char;
+    }
+    return `${out}…`;
+}
+/** `HH:MM:SS` local wall-clock of an epoch-ms timestamp. */
+export function formatClock(time) {
+    const date = new Date(time);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+/**
+ * Compact duration: `82ms` / `1.4s` / `2m05s` / `1h04m`.
+ *
+ * Every form is at most six columns wide, so the ledger's duration column
+ * never reflows when a fast call is followed by a slow one.
+ */
+export function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return '—';
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    if (ms < 3_600_000) {
+        const minutes = Math.floor(ms / 60_000);
+        return `${minutes}m${String(Math.round((ms % 60_000) / 1000)).padStart(2, '0')}s`;
+    }
+    const hours = Math.floor(ms / 3_600_000);
+    return `${hours}h${String(Math.floor((ms % 3_600_000) / 60_000)).padStart(2, '0')}m`;
+}
+/** Compact token count: `840` / `12.4k` / `1.1M`. */
+export function formatTokens(count) {
+    if (count < 1000)
+        return String(Math.round(count));
+    if (count < 1_000_000)
+        return `${(count / 1000).toFixed(1)}k`;
+    return `${(count / 1_000_000).toFixed(1)}M`;
+}
+/**
+ * Heat colour for a duration cell.
+ *
+ * The point of the ledger is usually to find the slow thing, so the duration
+ * column encodes magnitude as colour: anything under a second recedes, tens
+ * of seconds warn, minutes shout. Reading a column of numbers is work; seeing
+ * one red cell is not.
+ */
+export function heatColor(ms) {
+    if (ms === undefined)
+        return 'subtle';
+    if (ms >= 60_000)
+        return 'error';
+    if (ms >= 10_000)
+        return 'warning';
+    if (ms >= 1000)
+        return 'inactiveShimmer';
+    return 'subtle';
+}
+/**
+ * Cost glyph for a row's own duration — an ABSOLUTE, learnable scale.
+ *
+ * A relative scale (tallest row in view = full block) would re-teach itself on
+ * every scroll; fixed thresholds mean `█` always says "over a minute" and `▁`
+ * always says "instant", so after one session the column is read without
+ * looking at the number beside it. Each step is roughly half an order of
+ * magnitude, which is the resolution a human actually acts on.
+ */
+export function costGlyph(ms) {
+    if (ms === undefined)
+        return ' ';
+    if (ms >= 60_000)
+        return '█';
+    if (ms >= 30_000)
+        return '▇';
+    if (ms >= 10_000)
+        return '▆';
+    if (ms >= 3_000)
+        return '▅';
+    if (ms >= 1_000)
+        return '▄';
+    if (ms >= 300)
+        return '▃';
+    if (ms >= 100)
+        return '▂';
+    return '▁';
+}
+/**
+ * Fixed-width badge text per row kind — six columns, including one cell of
+ * padding on each side.
+ *
+ * The padding is what turns a coloured word into a pill. Background colour
+ * flush against the glyphs reads as a highlighter smudge; a cell of ground on
+ * either side reads as a chip, and chips are what let the eye group forty rows
+ * by kind without reading any of them.
+ */
+export const KIND_BADGE = {
+    turn: ' TURN ',
+    step: ' STEP ',
+    user: ' USR  ',
+    assistant: ' AST  ',
+    thinking: ' THK  ',
+    tool: ' TOOL ',
+    subtool: ' SUB  ',
+    retry: ' RTY  ',
+    approval: ' APR  ',
+    compaction: ' CMP  ',
+    system: ' SYS  ',
+    context: ' CTX  ',
+    todo: ' TODO ',
+};
+/** One-character badge for the narrowest layout tier. */
+export const KIND_GLYPH = {
+    turn: '▶',
+    step: '·',
+    user: '❯',
+    assistant: '✦',
+    thinking: '✻',
+    tool: '⏺',
+    subtool: '⏵',
+    retry: '↻',
+    approval: '⚑',
+    compaction: '⊟',
+    system: '⚙',
+    context: '⊕',
+    todo: '✓',
+};
+/**
+ * Badge foreground per kind. Backgrounds come from {@link KIND_BADGE_BG} — the
+ * pair reads as a pill, which carries far better in a dense ledger than
+ * coloured text alone.
+ */
+export const KIND_FG = {
+    turn: 'text',
+    step: 'subtle',
+    user: 'suggestion',
+    assistant: 'accent',
+    // Reasoning is ambient: it is the most numerous row kind and the least
+    // often the thing you came to find, so it recedes rather than competing
+    // with tool names for the eye.
+    thinking: 'inactive',
+    tool: 'chromeYellow',
+    subtool: 'autoAccept',
+    retry: 'error',
+    approval: 'warning',
+    compaction: 'planMode',
+    system: 'planMode',
+    context: 'success',
+    todo: 'planMode',
+};
+/**
+ * Badge background per kind, or `undefined` for kinds that read better
+ * unfilled (structural rows, which should recede behind the work rows).
+ */
+export const KIND_BADGE_BG = {
+    user: 'userMessageBackground',
+    assistant: 'userMessageBackground',
+    tool: 'bashMessageBackgroundColor',
+    subtool: 'bashMessageBackgroundColor',
+    retry: 'diffRemoved',
+    approval: 'diffRemovedDimmed',
+    compaction: 'diffAddedDimmed',
+    system: 'diffAddedDimmed',
+    context: 'diffAdded',
+    todo: 'diffAdded',
+};
+/**
+ * Resolve the column budget for one terminal width.
+ *
+ * @param columns - Terminal width in cells.
+ * @returns The tier's budget; `detail` is never below 12 so the label itself
+ *   survives even on a pathologically narrow terminal.
+ */
+export function ledgerLayout(columns) {
+    // Fixed costs: spine (2) + clock (8) + pill (6) + cost (1) + duration (7),
+    // plus one cell of gap between each.
+    if (columns >= 110)
+        return { badge: 6, index: true, outcome: true, detail: Math.max(12, columns - 72) };
+    if (columns >= 90)
+        return { badge: 6, index: true, outcome: true, detail: Math.max(12, columns - 64) };
+    if (columns >= 70)
+        return { badge: 6, index: false, outcome: false, detail: Math.max(12, columns - 26) };
+    return { badge: 1, index: false, outcome: false, detail: Math.max(12, columns - 16) };
+}

package/lib/types/trajectory/motion.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Trajectory motion — five verbs, one shared clock, one hard rule.
+ *
+ * ## The rule: SGR-only
+ *
+ * The renderer diffs frames cell by cell and emits the smallest patch that
+ * reconciles them. A cell whose *style* changed costs a few bytes of SGR; a
+ * row whose *layout* changed costs a full row rewrite, and in inline mode a
+ * frame that got shorter takes the full-reset path that once deposited a copy
+ * of the whole UI into scrollback on every repaint (issues #38/#39/#19/#10).
+ *
+ * So every verb below animates colour and colour only. Nothing here changes a
+ * glyph count, a row count, or a box dimension. `verify-trace-motion` asserts
+ * this mechanically by capturing the write stream across a hundred ticks and
+ * failing on any row-level escape — the rule is machine-enforced, not a
+ * convention someone has to remember.
+ *
+ * ## The verbs
+ *
+ * | verb        | shape                      | used for                        |
+ * |-------------|----------------------------|---------------------------------|
+ * | `arrive`    | one bright frame, settle   | a row or wave column just landed |
+ * | `reproject` | dim → bright, two frames   | the same data, re-sorted/filtered |
+ * | `alert`     | two flashes, then steady   | an error, a retry, a pending ask |
+ * | `alive`     | slow breath, loops         | the running edge (1–2 cells max) |
+ * | `navigate`  | *nothing*                  | cursor, viewport, inspector      |
+ *
+ * `navigate` having no animation is a decision, not an omission: easing on a
+ * cursor is latency you can feel, and key auto-repeat already supplies the
+ * sense of continuity.
+ *
+ * ## Cost
+ *
+ * No timer is created here. The scene subscribes once to the Ink core's
+ * shared animation clock, which already pauses when the terminal loses focus
+ * or the view scrolls offscreen — so an idle session animates nothing.
+ */
+import { type RGBColor } from '../components/Spinner/spinnerUtils.js';
+import type { Color } from '../ink/styles.js';
+/** Scene clock period. One tick drives every verb below. */
+export declare const MOTION_TICK_MS = 100;
+/** Ticks a one-shot verb runs for before settling. */
+export declare const MOTION_SPANS: {
+    readonly arrive: 2;
+    readonly reproject: 3;
+    /** Two flashes: bright, dim, bright, dim, then steady. */
+    readonly alert: 8;
+};
+/** Format an RGB triple the way the theme and `<Text color>` expect. */
+export declare function rgbString(color: RGBColor): Color;
+/**
+ * Blend two colours, accepting either theme values (`rgb(r,g,b)`) or hex.
+ *
+ * @param base - Colour at `t = 0`.
+ * @param highlight - Colour at `t = 1`.
+ * @param t - Blend position, clamped into [0, 1].
+ * @returns A colour string `<Text color>` accepts, or `base` when either
+ *   input could not be parsed (a custom theme may carry an ANSI name).
+ */
+export declare function mix(base: string, highlight: string, t: number): Color;
+/**
+ * The `alive` verb: a triangular breath in [0, 1], synchronized across every
+ * caller because they all read the same clock.
+ *
+ * @param tick - Current scene tick.
+ * @returns Blend position for {@link mix}.
+ */
+export declare function alive(tick: number): number;
+/**
+ * The `arrive` verb: one bright frame, then settle.
+ *
+ * @returns Blend position, or 0 once settled.
+ */
+export declare function arrive(tick: number, startTick: number): number;
+/**
+ * The `reproject` verb: the view dims, then comes back up. Used when the same
+ * rows are re-ordered or re-filtered, so the eye is told "this is the same
+ * data, rearranged" rather than "this is a new screen".
+ *
+ * @returns Dim factor in [0, 1] where 1 is fully dimmed, 0 fully settled.
+ */
+export declare function reproject(tick: number, startTick: number): number;
+/**
+ * The `alert` verb: two flashes, then steady. Deliberately one-shot — a
+ * looping alarm is noise, and an error that keeps blinking after you have
+ * seen it trains you to ignore it.
+ *
+ * @returns Blend position toward the highlight, or 0 once steady.
+ */
+export declare function alert(tick: number, startTick: number): number;
+/**
+ * Colour for a running cell (the `alive` verb applied to a theme pair).
+ *
+ * @param tick - Current scene tick.
+ * @param base - Settled colour.
+ * @param highlight - Peak-of-breath colour.
+ */
+export declare function aliveColor(tick: number, base: string, highlight: string): Color;
+//# sourceMappingURL=motion.d.ts.map

package/lib/types/trajectory/motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../../src/trajectory/motion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,uCAAuC,CAAA;AACjG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,4DAA4D;AAC5D,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC,sDAAsD;AACtD,eAAO,MAAM,YAAY;;;IAGvB,0DAA0D;;CAElD,CAAA;AAKV,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,CAEhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,CAOrE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG1C;AAgBD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAE/E"}