@deepseek-harness-tui/dsh-tui 0.6.1 → 0.7.1

package/lib/types/sessionModes.js

@@ -0,0 +1,45 @@
+/**
+ * Configurable Shift+Tab session modes (the `modes` dsh-tui plugin config):
+ * each mode is a named bundle of optional DSH plane switches — plan mode
+ * (dsh-plan-mode `/plan`), sandbox mode (dsh-sandbox-policy `sandbox/mode`
+ * session events), approval policy (dsh-user-approval `approval/policy`
+ * events). An absent atom means "this mode does not touch that plane".
+ */
+import { t } from './i18n.js';
+/** The shipped cycle when cordis.yml pins no `modes` — array order IS the
+ *  Shift+Tab cycle order; index 0 is the unmarked base mode. */
+export const DEFAULT_SESSION_MODES = [
+    { id: 'default', plan: false, sandbox: 'workspace-write', approval: 'ask' },
+    { id: 'plan', plan: true, sandbox: 'read-only', approval: 'ask' },
+    { id: 'full', plan: false, sandbox: 'danger-full-access', approval: 'never' },
+];
+/** Config → cycle list: undefined/empty → DEFAULT_SESSION_MODES; entries
+ *  declaring no atom at all are dropped (their ids are returned for the
+ *  caller to warn about); if nothing survives, DEFAULT_SESSION_MODES. Atom
+ *  vocabularies are already enforced by the plugin Schema at load, so no
+ *  value validation happens here. */
+export function resolveSessionModes(raw) {
+    if (raw === undefined || raw.length === 0)
+        return { modes: DEFAULT_SESSION_MODES, dropped: [] };
+    const dropped = [];
+    const modes = raw.filter(spec => {
+        const usable = spec.plan !== undefined || spec.sandbox !== undefined || spec.approval !== undefined;
+        if (!usable)
+            dropped.push(spec.id);
+        return usable;
+    });
+    return modes.length === 0 ? { modes: DEFAULT_SESSION_MODES, dropped } : { modes, dropped };
+}
+/** Display name: explicit `label` > built-in i18n (`mode-default`/
+ *  `mode-plan`/`mode-full` for those ids) > the raw id. */
+export function modeDisplayName(spec) {
+    if (spec.label !== undefined)
+        return spec.label;
+    if (spec.id === 'default')
+        return t('mode-default');
+    if (spec.id === 'plan')
+        return t('mode-plan');
+    if (spec.id === 'full')
+        return t('mode-full');
+    return spec.id;
+}

package/lib/types/theme.d.ts

@@ -8,6 +8,12 @@
  * text, accent-soft blues). `dark-ansi` is the 16-color fallback for
  * terminals without truecolor. The active palette is chosen at startup by
  * querying the terminal background (OSC 11) — see ThemeProvider.
+ *
+ * `auto` is a pseudo-theme, not a palette: it resolves to `light` or `dark`
+ * from the terminal background detected via OSC 11 (which tracks the system
+ * theme in terminals that follow it). ThemeProvider re-runs detection every
+ * time `auto` is selected and pushes the result through setAutoThemeBase(),
+ * so getTheme('auto') always serves the currently detected palette.
  */
 export type Theme = {
     autoAccept: string;
@@ -82,16 +88,34 @@ export type Theme = {
 };
 /** The built-in theme names, in display order. */
 export declare const THEME_NAMES: readonly ["dark", "dark-ansi", "light"];
+/**
+ * The `auto` pseudo-theme: not a palette, but a standing request to follow
+ * the terminal background (OSC 11, which tracks the system theme in
+ * terminals that follow it). Selectable everywhere a theme name is
+ * (/theme, DSH_TUI_THEME, ~/.dsh-tui/theme.json); getTheme() resolves it to
+ * the last detected `light`/`dark` palette via the auto base below.
+ */
+export declare const AUTO_THEME_NAME = "auto";
+/**
+ * Record the palette `auto` should resolve to. Called by ThemeProvider
+ * after each terminal-background detection while `auto` is active.
+ * @param name - The detected base palette.
+ */
+export declare function setAutoThemeBase(name: 'light' | 'dark'): void;
+/** The palette `auto` currently resolves to (`light` or `dark`). */
+export declare function getAutoThemeBase(): 'light' | 'dark';
 /**
  * Any theme name: a built-in palette (`light`/`dark`/`dark-ansi`) or a user
- * theme from ~/.dsh-cc/themes/<name>.json. Always resolvable to a concrete
+ * theme from ~/.dsh-tui/themes/<name>.json. Always resolvable to a concrete
  * color palette via getTheme() (unknown names fall back to `dark`).
  */
 export type ThemeName = string;
 /**
  * Resolve a theme name to its concrete color palette.
- * @param themeName - The theme to resolve (built-in or user theme name).
- * @returns The matching palette; unknown names fall back to `dark`.
+ * @param themeName - The theme to resolve (built-in, `auto`, or user theme
+ *   name).
+ * @returns The matching palette; `auto` resolves to the detected base
+ *   (light/dark), unknown names fall back to `dark`.
  */
 export declare function getTheme(themeName: ThemeName): Theme;
 /**

package/lib/types/theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/theme.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/theme.ts"],"names":[],"mappings":"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"}

package/lib/types/theme.js

@@ -8,9 +8,43 @@
  * text, accent-soft blues). `dark-ansi` is the 16-color fallback for
  * terminals without truecolor. The active palette is chosen at startup by
  * querying the terminal background (OSC 11) — see ThemeProvider.
+ *
+ * `auto` is a pseudo-theme, not a palette: it resolves to `light` or `dark`
+ * from the terminal background detected via OSC 11 (which tracks the system
+ * theme in terminals that follow it). ThemeProvider re-runs detection every
+ * time `auto` is selected and pushes the result through setAutoThemeBase(),
+ * so getTheme('auto') always serves the currently detected palette.
  */
 /** The built-in theme names, in display order. */
 export const THEME_NAMES = ['dark', 'dark-ansi', 'light'];
+/**
+ * The `auto` pseudo-theme: not a palette, but a standing request to follow
+ * the terminal background (OSC 11, which tracks the system theme in
+ * terminals that follow it). Selectable everywhere a theme name is
+ * (/theme, DSH_TUI_THEME, ~/.dsh-tui/theme.json); getTheme() resolves it to
+ * the last detected `light`/`dark` palette via the auto base below.
+ */
+export const AUTO_THEME_NAME = 'auto';
+/**
+ * The palette `auto` currently resolves to, mirrored module-level so
+ * getTheme('auto') works for non-React rendering without a context.
+ * ThemeProvider sets this on every detection (startup and runtime switch);
+ * defaults to `dark` until the first detection settles (the pre-detection
+ * status quo, biased dark for readability).
+ */
+let autoBase = 'dark';
+/**
+ * Record the palette `auto` should resolve to. Called by ThemeProvider
+ * after each terminal-background detection while `auto` is active.
+ * @param name - The detected base palette.
+ */
+export function setAutoThemeBase(name) {
+    autoBase = name;
+}
+/** The palette `auto` currently resolves to (`light` or `dark`). */
+export function getAutoThemeBase() {
+    return autoBase;
+}
 const rgb = (hex) => {
     const n = parseInt(hex.slice(1), 16);
     return `rgb(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255})`;
@@ -170,9 +204,9 @@ const lightTheme = {
 };
 /**
  * Dark ANSI theme using only the 16 standard ANSI colors, for terminals
- * without true color support (verbatim from the leak).
+ * without true color support (verbatim from Claude Code).
  *
- * User themes (JSON files in ~/.dsh-cc/themes/) overlay one of these three
+ * User themes (JSON files in ~/.dsh-tui/themes/) overlay one of these three
  * bases — see customTheme.ts. `getTheme` resolves them through a resolver
  * registered by ThemeProvider.
  */
@@ -249,15 +283,25 @@ const darkAnsiTheme = {
 };
 /**
  * Resolve a theme name to its concrete color palette.
- * @param themeName - The theme to resolve (built-in or user theme name).
- * @returns The matching palette; unknown names fall back to `dark`.
+ * @param themeName - The theme to resolve (built-in, `auto`, or user theme
+ *   name).
+ * @returns The matching palette; `auto` resolves to the detected base
+ *   (light/dark), unknown names fall back to `dark`.
  */
 export function getTheme(themeName) {
     switch (themeName) {
         case 'light':
             return lightTheme;
+        // `dark` is an explicit case (not the default): built-in bases must
+        // resolve without touching the custom-theme resolver — parseCustomTheme
+        // calls getTheme(base) while the resolver may still be indexing, and a
+        // resolver round-trip there re-enters theme-file parsing recursively.
+        case 'dark':
+            return darkTheme;
         case 'dark-ansi':
             return darkAnsiTheme;
+        case AUTO_THEME_NAME:
+            return autoBase === 'light' ? lightTheme : darkTheme;
         default:
             return customThemeResolver?.(themeName) ?? darkTheme;
     }

package/lib/types/themePrefs.d.ts

@@ -1,10 +1,10 @@
 /**
  * Persisted color-theme preference. The `/theme` choice (built-in palette
- * or user theme name) survives restarts in `~/.dsh-cc/theme.json`, mirroring
- * the working-activity preference (`~/.dsh-cc/working-activity.json`). The
+ * or user theme name) survives restarts in `~/.dsh-tui/theme.json`, mirroring
+ * the working-activity preference (`~/.dsh-tui/working-activity.json`). The
  * file is best-effort: a missing or corrupt file just falls back to the
  * default (terminal-background auto-detection). The preference only wins
- * when CC_TUI_THEME is unset — see ThemeProvider.
+ * when DSH_TUI_THEME is unset — see ThemeProvider.
  */
 /**
  * Parse a persisted `{ theme }` value; anything else yields undefined.

package/lib/types/themePrefs.js

@@ -1,16 +1,16 @@
 /**
  * Persisted color-theme preference. The `/theme` choice (built-in palette
- * or user theme name) survives restarts in `~/.dsh-cc/theme.json`, mirroring
- * the working-activity preference (`~/.dsh-cc/working-activity.json`). The
+ * or user theme name) survives restarts in `~/.dsh-tui/theme.json`, mirroring
+ * the working-activity preference (`~/.dsh-tui/working-activity.json`). The
  * file is best-effort: a missing or corrupt file just falls back to the
  * default (terminal-background auto-detection). The preference only wins
- * when CC_TUI_THEME is unset — see ThemeProvider.
+ * when DSH_TUI_THEME is unset — see ThemeProvider.
  */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { isSafeThemeName } from './customTheme.js';
-const PREFS_DIR = join(homedir(), '.dsh-cc');
+import { DATA_DIR } from './utils/paths.js';
+const PREFS_DIR = DATA_DIR;
 /**
  * Parse a persisted `{ theme }` value; anything else yields undefined.
  * @param text - Raw file contents.

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: 'claude',
+    // 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"}