@cruxy/cli 0.25.0 → 0.27.0

package/dist/render/capabilities.js

@@ -4,6 +4,24 @@ import { detectScreenReader, detectUnicode } from "../theme/index.js";
 function isSet(value) {
     return value !== undefined && value !== "";
 }
+/** Fallback width when the terminal reports none (non-TTY, pipe, unknown). */
+export const DEFAULT_COLUMNS = 80;
+/**
+ * Resolve the terminal width (U.12) — the single rule behind
+ * {@link RenderCapabilities.width} and every resize recompute. `COLUMNS` wins
+ * when set (honored so `COLUMNS=100 cruxy …` and CI overrides work), then the
+ * stream's own `columns`, then {@link DEFAULT_COLUMNS}. Never returns a
+ * non-positive width — an unknown terminal degrades to a sensible default, it
+ * does not crash a width calculation with 0.
+ */
+export function resolveColumns(stream = process.stdout, env = process.env) {
+    const fromEnv = env.COLUMNS === undefined ? NaN : Number.parseInt(env.COLUMNS, 10);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    if (typeof stream.columns === "number" && stream.columns > 0)
+        return stream.columns;
+    return DEFAULT_COLUMNS;
+}
 /**
  * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
  * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
@@ -44,8 +62,6 @@ export function detectCapabilities(stream = process.stdout, env = process.env) {
         // Unicode glyph safety (U.1) — independent of color. dumb / CRUXY_ASCII →
         // ASCII glyphs; everything else (incl. pipes) keeps unicode.
         unicode: detectUnicode(env),
-        width: typeof stream.columns === "number" && stream.columns > 0
-            ? stream.columns
-            : 80,
+        width: resolveColumns(stream, env),
     };
 }

package/dist/render/diff.d.ts

@@ -15,4 +15,4 @@ export declare const PREVIEW_MAX_LINES = 40;
  * patches, a create/overwrite listing for writes, the publish plan for PRs.
  * Long previews collapse past {@link PREVIEW_MAX_LINES}.
  */
-export declare function renderActionPreview(preview: ActionPreview | undefined, c: Theme): string;
+export declare function renderActionPreview(preview: ActionPreview | undefined, c: Theme, width?: number): string;

package/dist/render/diff.js

@@ -1,3 +1,4 @@
+import { fit, fitMiddle } from "./layout.js";
 /**
  * The one diff/action-preview renderer (U.2). The approval prompt, PR preview,
  * and the streaming render path all draw diffs through here — there is no
@@ -13,20 +14,28 @@ function diffLines(oldStr, newStr, c) {
     const added = newStr.split("\n").map((l) => c.success(`+ ${l}`));
     return [...removed, ...added];
 }
-function renderPatchFiles(files, c) {
+/**
+ * Middle-truncate a file path so its basename (the strongest identifier)
+ * survives narrow width (U.12). `width` defaults to `Infinity`, so callers that
+ * don't thread width get the exact pre-U.12 bytes.
+ */
+function fitPath(path, c, width) {
+    return fitMiddle(path, Math.max(1, width - 10), c.glyph.ellipsis);
+}
+function renderPatchFiles(files, c, width = Infinity) {
     const out = [];
     for (const file of files) {
         if (file.op === "delete") {
-            out.push(c.danger(`delete ${file.path}`));
+            out.push(c.danger(`delete ${fitPath(file.path, c, width)}`));
         }
         else if (file.op === "create") {
-            out.push(c.success(`create ${file.path}`));
+            out.push(c.success(`create ${fitPath(file.path, c, width)}`));
             out.push(...file.lines.map((l) => c.success(`+ ${l}`)));
             if (file.omittedLines > 0)
                 out.push(c.muted(`  ...${file.omittedLines} more lines`));
         }
         else {
-            out.push(c.warning(`update ${file.path}`));
+            out.push(c.warning(`update ${fitPath(file.path, c, width)}`));
             for (const hunk of file.hunks)
                 out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
         }
@@ -116,7 +125,7 @@ function bodyLines(body) {
  * patches, a create/overwrite listing for writes, the publish plan for PRs.
  * Long previews collapse past {@link PREVIEW_MAX_LINES}.
  */
-export function renderActionPreview(preview, c) {
+export function renderActionPreview(preview, c, width = Infinity) {
     if (!preview)
         return "";
     let lines;
@@ -124,7 +133,7 @@ export function renderActionPreview(preview, c) {
         lines = diffLines(preview.oldStr, preview.newStr, c);
     }
     else if (preview.type === "patch") {
-        lines = renderPatchFiles(preview.files, c);
+        lines = renderPatchFiles(preview.files, c, width);
     }
     else if (preview.type === "pr") {
         lines = renderPrPreview(preview, c);
@@ -151,5 +160,12 @@ export function renderActionPreview(preview, c) {
             c.muted(`...${hidden} more`),
         ];
     }
-    return lines.map((l) => `  ${l}`).join("\n");
+    // Horizontal fit at the single choke point (U.12): every content line is
+    // truncated to the width available inside the 2-space indent, so no line ever
+    // soft-wraps. `fit` truncates from the RIGHT, so a diff line keeps its leading
+    // `+`/`-` sign and a labeled line keeps its `create`/`update`/`delete` verb —
+    // the meaning at line-start is never the part that's dropped. Default width
+    // Infinity → no-op, so non-threaded callers get the pre-U.12 bytes.
+    const room = Math.max(1, width - 2);
+    return lines.map((l) => `  ${fit(l, room, c.glyph.ellipsis)}`).join("\n");
 }

package/dist/render/index.d.ts

@@ -1,7 +1,10 @@
 import type { RenderStream, StreamRenderer } from "./types.js";
 export type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, TokenUsage, ToolLifecycleEvent, } from "./types.js";
-export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
-export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
+export { detectCapabilities, detectReducedMotion, resolveColumns, DEFAULT_COLUMNS, } from "./capabilities.js";
+export { attachResize, processResizeSignal, type ResizeSignal, } from "./resize.js";
+export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, type KvRow, } from "./layout.js";
+export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
+export { createFrameClock, inTransition, intervalFrameTimer, spinnerGlyph, FRAME_INTERVAL_MS, TRANSITION_TICKS, type FrameClock, type FrameTimer, } from "./motion.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";

package/dist/render/index.js

@@ -1,9 +1,13 @@
 import { detectCapabilities } from "./capabilities.js";
 import { PlainRenderer } from "./plain-renderer.js";
+import { attachResize } from "./resize.js";
 import { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 import { TtyRenderer } from "./tty-renderer.js";
-export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
-export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
+export { detectCapabilities, detectReducedMotion, resolveColumns, DEFAULT_COLUMNS, } from "./capabilities.js";
+export { attachResize, processResizeSignal, } from "./resize.js";
+export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, } from "./layout.js";
+export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
+export { createFrameClock, inTransition, intervalFrameTimer, spinnerGlyph, FRAME_INTERVAL_MS, TRANSITION_TICKS, } from "./motion.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
@@ -20,6 +24,9 @@ export { TtyRenderer } from "./tty-renderer.js";
  */
 export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
     const caps = detectCapabilities(out, env);
+    // Wire resize reactivity onto the one caps object before any surface reads
+    // its width (U.12). A no-op for non-TTY streams; the live region subscribes.
+    attachResize(caps, out, env);
     if (caps.screenReader)
         return new ScreenReaderRenderer(caps, out, err);
     return caps.cursor

package/dist/render/layout.d.ts

@@ -0,0 +1,59 @@
+import type { Theme } from "../theme/index.js";
+/** The visible text of a possibly-styled string (SGR removed). */
+export declare function stripAnsi(text: string): string;
+/**
+ * Visible width in code points — the number a terminal cell count approximates.
+ * Counts by code point (via spread) so a surrogate-pair glyph is 1, not 2, and
+ * is never split. Wide (CJK/emoji) cells are counted as 1; full display-width
+ * accounting is deliberately out of scope (U.12), but code-point counting is
+ * already strictly more correct than the pre-U.12 `.length`.
+ */
+export declare function visibleWidth(text: string): number;
+/**
+ * Truncate `text` to at most `width` visible columns, appending an honest
+ * ellipsis when anything was dropped. Text that already fits is returned
+ * UNCHANGED (style preserved). A truncated string is returned as plain text:
+ * dropping the style on the cut tail is the safe choice — re-styling a slice
+ * risks emitting a half of an escape pair.
+ *
+ * `width < 1` yields "". When `width` is smaller than the ellipsis itself
+ * (very-narrow), we show that many content characters rather than only dots —
+ * a single legible char beats a clipped "…".
+ */
+export declare function fit(text: string, width: number, ellipsis?: string): string;
+/**
+ * Truncate the MIDDLE, preserving the head and tail. For a path or a search
+ * hit, the tail (basename, `:line`) carries as much identity as the head
+ * (root) — a right-truncation would hide the very thing that names it. Yields
+ * `src/very/deep/…/Component.tsx`. Falls back to {@link fit} when there is no
+ * room for both sides plus the ellipsis. Returns plain text when it truncates.
+ */
+export declare function fitMiddle(text: string, width: number, ellipsis?: string): string;
+/**
+ * Word-wrap `text` to `width` visible columns, returning the wrapped lines.
+ * Wraps at spaces; a single token longer than `width` is hard-broken (its style
+ * is dropped on the break). Existing newlines are preserved as paragraph
+ * breaks. Use this — not {@link fit} — when meaning must survive in full (an
+ * approval command you must see whole), trading vertical space for completeness.
+ */
+export declare function reflow(text: string, width: number): string[];
+/** A key/value pair for {@link kvStack}. */
+export interface KvRow {
+    key: string;
+    value: string;
+}
+/**
+ * Minimum value columns an aligned two-column table needs before it collapses
+ * to a stack. Below this, the value column is too cramped to read, so stacking
+ * (key on its own line, value reflowed beneath) is the honest presentation.
+ */
+export declare const MIN_VALUE_COLS = 16;
+/**
+ * The table→stack collapser (U.12). At a width that affords the widest key plus
+ * {@link MIN_VALUE_COLS}, render aligned `key  value` rows (values truncated to
+ * the remaining columns). Too narrow for that, STACK each pair — a bold key
+ * line, then the value reflowed and indented — so a table never soft-wraps into
+ * a misaligned mess and never hides a value. One column budgeter for every kv
+ * caller.
+ */
+export declare function kvStack(rows: KvRow[], width: number, theme: Theme): string[];

package/dist/render/layout.js

@@ -0,0 +1,158 @@
+/**
+ * Width-aware layout (U.12): the ANSI-aware truncate/reflow/collapse helpers
+ * every rendered surface uses to fit content to `RenderCapabilities.width`.
+ * Pure string → string, like diff.ts / state.ts — no terminal, no width source
+ * of its own (callers pass the one `caps.width`), so each helper is directly
+ * testable.
+ *
+ * The one rule these enforce: width is measured on VISIBLE characters, not
+ * bytes. A colored 10-visible-char string is 10 wide even though its byte
+ * length is larger (SGR escapes) — truncating on `.length` would cut early and
+ * could sever an escape sequence mid-way, leaving torn ANSI on screen. So we
+ * strip SGR for the measurement and slice on CODE POINTS (never UTF-16 units),
+ * which also prevents splitting an astral glyph into two broken halves.
+ */
+/** SGR escape sequences (the only ANSI our surfaces emit — via picocolors). */
+// eslint-disable-next-line no-control-regex
+const SGR = /\x1b\[[0-9;]*m/g;
+/** The visible text of a possibly-styled string (SGR removed). */
+export function stripAnsi(text) {
+    return text.replace(SGR, "");
+}
+/**
+ * Visible width in code points — the number a terminal cell count approximates.
+ * Counts by code point (via spread) so a surrogate-pair glyph is 1, not 2, and
+ * is never split. Wide (CJK/emoji) cells are counted as 1; full display-width
+ * accounting is deliberately out of scope (U.12), but code-point counting is
+ * already strictly more correct than the pre-U.12 `.length`.
+ */
+export function visibleWidth(text) {
+    return [...stripAnsi(text)].length;
+}
+/**
+ * Truncate `text` to at most `width` visible columns, appending an honest
+ * ellipsis when anything was dropped. Text that already fits is returned
+ * UNCHANGED (style preserved). A truncated string is returned as plain text:
+ * dropping the style on the cut tail is the safe choice — re-styling a slice
+ * risks emitting a half of an escape pair.
+ *
+ * `width < 1` yields "". When `width` is smaller than the ellipsis itself
+ * (very-narrow), we show that many content characters rather than only dots —
+ * a single legible char beats a clipped "…".
+ */
+export function fit(text, width, ellipsis = "…") {
+    if (width < 1)
+        return "";
+    const chars = [...stripAnsi(text)];
+    if (chars.length <= width)
+        return text;
+    const ell = [...ellipsis].length;
+    if (width <= ell)
+        return chars.slice(0, width).join("");
+    return chars.slice(0, width - ell).join("") + ellipsis;
+}
+/**
+ * Truncate the MIDDLE, preserving the head and tail. For a path or a search
+ * hit, the tail (basename, `:line`) carries as much identity as the head
+ * (root) — a right-truncation would hide the very thing that names it. Yields
+ * `src/very/deep/…/Component.tsx`. Falls back to {@link fit} when there is no
+ * room for both sides plus the ellipsis. Returns plain text when it truncates.
+ */
+export function fitMiddle(text, width, ellipsis = "…") {
+    if (width < 1)
+        return "";
+    const chars = [...stripAnsi(text)];
+    if (chars.length <= width)
+        return text;
+    const ell = [...ellipsis].length;
+    if (width <= ell + 1)
+        return fit(text, width, ellipsis);
+    const budget = width - ell;
+    const head = Math.ceil(budget / 2);
+    const tail = budget - head;
+    const start = chars.slice(0, head).join("");
+    const end = tail > 0 ? chars.slice(chars.length - tail).join("") : "";
+    return start + ellipsis + end;
+}
+/** Break one over-long token into `width`-wide code-point chunks (plain text). */
+function hardBreak(word, width) {
+    const chars = [...stripAnsi(word)];
+    const chunks = [];
+    for (let i = 0; i < chars.length; i += width) {
+        chunks.push(chars.slice(i, i + width).join(""));
+    }
+    return chunks;
+}
+/**
+ * Word-wrap `text` to `width` visible columns, returning the wrapped lines.
+ * Wraps at spaces; a single token longer than `width` is hard-broken (its style
+ * is dropped on the break). Existing newlines are preserved as paragraph
+ * breaks. Use this — not {@link fit} — when meaning must survive in full (an
+ * approval command you must see whole), trading vertical space for completeness.
+ */
+export function reflow(text, width) {
+    if (width < 1)
+        return [text];
+    const out = [];
+    for (const para of text.split("\n")) {
+        if (para === "") {
+            out.push("");
+            continue;
+        }
+        let line = "";
+        for (const word of para.split(" ")) {
+            const candidate = line === "" ? word : `${line} ${word}`;
+            if (visibleWidth(candidate) <= width) {
+                line = candidate;
+                continue;
+            }
+            if (line !== "") {
+                out.push(line);
+                line = "";
+            }
+            if (visibleWidth(word) <= width) {
+                line = word;
+            }
+            else {
+                const chunks = hardBreak(word, width);
+                for (let i = 0; i < chunks.length - 1; i++)
+                    out.push(chunks[i]);
+                line = chunks[chunks.length - 1] ?? "";
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * Minimum value columns an aligned two-column table needs before it collapses
+ * to a stack. Below this, the value column is too cramped to read, so stacking
+ * (key on its own line, value reflowed beneath) is the honest presentation.
+ */
+export const MIN_VALUE_COLS = 16;
+/**
+ * The table→stack collapser (U.12). At a width that affords the widest key plus
+ * {@link MIN_VALUE_COLS}, render aligned `key  value` rows (values truncated to
+ * the remaining columns). Too narrow for that, STACK each pair — a bold key
+ * line, then the value reflowed and indented — so a table never soft-wraps into
+ * a misaligned mess and never hides a value. One column budgeter for every kv
+ * caller.
+ */
+export function kvStack(rows, width, theme) {
+    if (rows.length === 0)
+        return [];
+    const glyph = theme.glyph.ellipsis;
+    const keyWidth = Math.max(...rows.map((r) => visibleWidth(r.key)));
+    const valueRoom = width - keyWidth - 2;
+    if (valueRoom >= MIN_VALUE_COLS) {
+        return rows.map((r) => theme.kv(r.key, fit(r.value, valueRoom, glyph), keyWidth));
+    }
+    const out = [];
+    for (const r of rows) {
+        out.push(theme.strong(r.key));
+        for (const line of reflow(r.value, Math.max(1, width - 2))) {
+            out.push(`  ${line}`);
+        }
+    }
+    return out;
+}

package/dist/render/motion.d.ts

@@ -0,0 +1,76 @@
+import type { ThemeGlyphs } from "../theme/index.js";
+/**
+ * Motion (U.10) — one frame clock drives every live animation on the render
+ * seam, and a tiny set of pure frame→glyph/style primitives express it. The
+ * design is the same honest-signal discipline as U.4 state: motion encodes real
+ * state (work is progressing, the activity changed, a result landed) and never
+ * decorates. It is a cosmetic overlay on the transient live region (U.2) — never
+ * in the content path, never touching committed bytes.
+ *
+ * The single gate is `caps.spinner` (`cursor && !reducedMotion`, from U.11):
+ * when motion is reduced the clock is *disabled* — it schedules nothing and
+ * never ticks, so every motion collapses to its static end-state, drawn once.
+ * There is exactly one clock per renderer (refcounted like the U.12 resize
+ * signal), not a timer per surface.
+ */
+/** The one frame cadence: 10 fps, the pre-U.10 spinner interval. Bounded by construction. */
+export declare const FRAME_INTERVAL_MS = 100;
+/**
+ * How many frames a phase-transition emphasis lasts before it settles — ~300ms
+ * at {@link FRAME_INTERVAL_MS}. Long enough for the eye to catch "the activity
+ * changed", short enough to never read as decoration.
+ */
+export declare const TRANSITION_TICKS = 3;
+/** Schedule/cancel a repeating tick; injectable so tests drive frames deterministically. */
+export interface FrameTimer {
+    schedule(callback: () => void, intervalMs: number): {
+        unref?: () => void;
+    };
+    cancel(handle: {
+        unref?: () => void;
+    }): void;
+}
+/** The real timer: a single unref'd interval that never holds the process open. */
+export declare const intervalFrameTimer: FrameTimer;
+/**
+ * The one clock that drives all live animation. Subscribers get a monotonic
+ * frame number on each tick; the underlying timer runs ONLY while at least one
+ * subscriber is attached (refcounted), and is torn down on the last unsubscribe
+ * — the same discipline that keeps the U.12 resize listener from leaking.
+ */
+export interface FrameClock {
+    /**
+     * Attach a per-frame callback. The first subscriber starts the single timer;
+     * the returned function detaches and, when it was the last subscriber, stops
+     * the timer. A no-op subscription (returns a no-op unsubscribe) when the clock
+     * is disabled — reduced motion never schedules anything.
+     */
+    subscribe(onFrame: (frame: number) => void): () => void;
+    /** The current monotonic frame counter. Stays 0 while disabled (no ticks). */
+    readonly frame: number;
+    /** Whether motion runs at all — false under reduced motion (`caps.spinner`). */
+    readonly enabled: boolean;
+}
+/**
+ * Build the frame clock. `enabled` is `caps.spinner`: when false the clock is
+ * inert — {@link FrameClock.subscribe} schedules nothing, never ticks, and
+ * `frame` never advances, so callers draw their static end-state once and stop.
+ */
+export declare function createFrameClock(enabled: boolean, timer?: FrameTimer, intervalMs?: number): FrameClock;
+/**
+ * The spinner glyph for a frame (U.10 progress motion): the animated braille
+ * (or single-column ASCII) cycle when the clock runs, the static marker
+ * otherwise. `animated=false` (reduced motion / no cursor) yields the static
+ * glyph with no reference to `frame` — the honest still form of "working".
+ */
+export declare function spinnerGlyph(frame: number, glyph: ThemeGlyphs, animated: boolean): string;
+/**
+ * Whether a phase-transition emphasis is still playing (U.10): true for the
+ * first {@link TRANSITION_TICKS} frames after the phase *identity* changed. The
+ * caller records the frame the identity began on and passes it here; when the
+ * clock is not advancing (reduced motion), `startFrame === frame` forever, so
+ * this is briefly true only if drawn on the very first frame — the renderer
+ * gates the whole emphasis behind `clock.enabled`, so a static draw always uses
+ * the settled end-state.
+ */
+export declare function inTransition(frame: number, startFrame: number): boolean;

package/dist/render/motion.js

@@ -0,0 +1,94 @@
+/**
+ * Motion (U.10) — one frame clock drives every live animation on the render
+ * seam, and a tiny set of pure frame→glyph/style primitives express it. The
+ * design is the same honest-signal discipline as U.4 state: motion encodes real
+ * state (work is progressing, the activity changed, a result landed) and never
+ * decorates. It is a cosmetic overlay on the transient live region (U.2) — never
+ * in the content path, never touching committed bytes.
+ *
+ * The single gate is `caps.spinner` (`cursor && !reducedMotion`, from U.11):
+ * when motion is reduced the clock is *disabled* — it schedules nothing and
+ * never ticks, so every motion collapses to its static end-state, drawn once.
+ * There is exactly one clock per renderer (refcounted like the U.12 resize
+ * signal), not a timer per surface.
+ */
+/** The one frame cadence: 10 fps, the pre-U.10 spinner interval. Bounded by construction. */
+export const FRAME_INTERVAL_MS = 100;
+/**
+ * How many frames a phase-transition emphasis lasts before it settles — ~300ms
+ * at {@link FRAME_INTERVAL_MS}. Long enough for the eye to catch "the activity
+ * changed", short enough to never read as decoration.
+ */
+export const TRANSITION_TICKS = 3;
+/** The real timer: a single unref'd interval that never holds the process open. */
+export const intervalFrameTimer = {
+    schedule(callback, intervalMs) {
+        const handle = setInterval(callback, intervalMs);
+        handle.unref?.();
+        return handle;
+    },
+    cancel(handle) {
+        clearInterval(handle);
+    },
+};
+/**
+ * Build the frame clock. `enabled` is `caps.spinner`: when false the clock is
+ * inert — {@link FrameClock.subscribe} schedules nothing, never ticks, and
+ * `frame` never advances, so callers draw their static end-state once and stop.
+ */
+export function createFrameClock(enabled, timer = intervalFrameTimer, intervalMs = FRAME_INTERVAL_MS) {
+    const subscribers = new Set();
+    let handle = null;
+    let frame = 0;
+    const tick = () => {
+        frame++;
+        for (const fn of [...subscribers])
+            fn(frame);
+    };
+    return {
+        get frame() {
+            return frame;
+        },
+        enabled,
+        subscribe(onFrame) {
+            // Reduced motion: register nothing, schedule nothing. The single absolute
+            // gate — no timer can ever start, so no frame can ever be emitted.
+            if (!enabled)
+                return () => { };
+            subscribers.add(onFrame);
+            if (handle === null)
+                handle = timer.schedule(tick, intervalMs);
+            return () => {
+                subscribers.delete(onFrame);
+                if (subscribers.size === 0 && handle !== null) {
+                    timer.cancel(handle);
+                    handle = null;
+                }
+            };
+        },
+    };
+}
+/**
+ * The spinner glyph for a frame (U.10 progress motion): the animated braille
+ * (or single-column ASCII) cycle when the clock runs, the static marker
+ * otherwise. `animated=false` (reduced motion / no cursor) yields the static
+ * glyph with no reference to `frame` — the honest still form of "working".
+ */
+export function spinnerGlyph(frame, glyph, animated) {
+    if (!animated)
+        return glyph.spinnerStatic;
+    const frames = glyph.spinnerFrames;
+    return frames[frame % frames.length];
+}
+/**
+ * Whether a phase-transition emphasis is still playing (U.10): true for the
+ * first {@link TRANSITION_TICKS} frames after the phase *identity* changed. The
+ * caller records the frame the identity began on and passes it here; when the
+ * clock is not advancing (reduced motion), `startFrame === frame` forever, so
+ * this is briefly true only if drawn on the very first frame — the renderer
+ * gates the whole emphasis behind `clock.enabled`, so a static draw always uses
+ * the settled end-state.
+ */
+export function inTransition(frame, startFrame) {
+    return frame - startFrame < TRANSITION_TICKS;
+}

package/dist/render/resize.d.ts

@@ -0,0 +1,36 @@
+import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Resize reactivity (U.12). Terminal width lives in exactly one place —
+ * {@link RenderCapabilities.width} — and this module is what keeps it current:
+ * it listens for the OS resize signal, recomputes the width through the same
+ * {@link resolveColumns} rule that seeded it, updates `caps.width` IN PLACE, and
+ * pushes the new width to subscribers (the live region / transient frames).
+ *
+ * Committed output is never re-rendered from here — only surfaces that own a
+ * redrawable region subscribe. Everything else simply reads the now-current
+ * `caps.width` the next time it emits.
+ *
+ * The OS signal is injectable ({@link ResizeSignal}) so tests drive resize
+ * deterministically without a real terminal or a real SIGWINCH.
+ */
+/**
+ * The OS resize signal, abstracted for testability. `on` registers a callback
+ * fired on each terminal resize and returns an unsubscribe function.
+ */
+export interface ResizeSignal {
+    on(listener: () => void): () => void;
+}
+/** The real signal: Node emits `SIGWINCH` on the process when a TTY resizes. */
+export declare const processResizeSignal: ResizeSignal;
+/**
+ * Wire resize reactivity onto `caps`: install {@link RenderCapabilities.onResize}
+ * and start listening for terminal resizes. One OS listener is shared across all
+ * subscribers and is removed once the last one unsubscribes (and re-added if a
+ * new subscriber arrives), so nothing is leaked and the process is never held
+ * open by a stray handler.
+ *
+ * A no-op for streams that cannot resize (non-TTY / no `columns`): `onResize`
+ * stays undefined and surfaces fall back to the static width. Idempotent —
+ * calling twice on the same caps keeps the first wiring.
+ */
+export declare function attachResize(caps: RenderCapabilities, stream?: RenderStream, env?: NodeJS.ProcessEnv, signal?: ResizeSignal): void;

package/dist/render/resize.js

@@ -0,0 +1,45 @@
+import { resolveColumns } from "./capabilities.js";
+/** The real signal: Node emits `SIGWINCH` on the process when a TTY resizes. */
+export const processResizeSignal = {
+    on(listener) {
+        process.on("SIGWINCH", listener);
+        return () => void process.off("SIGWINCH", listener);
+    },
+};
+/**
+ * Wire resize reactivity onto `caps`: install {@link RenderCapabilities.onResize}
+ * and start listening for terminal resizes. One OS listener is shared across all
+ * subscribers and is removed once the last one unsubscribes (and re-added if a
+ * new subscriber arrives), so nothing is leaked and the process is never held
+ * open by a stray handler.
+ *
+ * A no-op for streams that cannot resize (non-TTY / no `columns`): `onResize`
+ * stays undefined and surfaces fall back to the static width. Idempotent —
+ * calling twice on the same caps keeps the first wiring.
+ */
+export function attachResize(caps, stream = process.stdout, env = process.env, signal = processResizeSignal) {
+    if (!stream.isTTY || caps.onResize)
+        return;
+    const listeners = new Set();
+    let off = null;
+    const onSignal = () => {
+        const next = resolveColumns(stream, env);
+        if (next === caps.width)
+            return;
+        caps.width = next; // the single source stays current — no second copy.
+        for (const l of [...listeners])
+            l(next);
+    };
+    caps.onResize = (listener) => {
+        listeners.add(listener);
+        if (off === null)
+            off = signal.on(onSignal);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0 && off !== null) {
+                off();
+                off = null;
+            }
+        };
+    };
+}

package/dist/render/state.d.ts

@@ -34,3 +34,16 @@ export declare function phaseIdentity(phase: RenderPhase | null): string;
  * when they can keep it ticking honestly (no timer → no frozen number).
  */
 export declare function composeStatusLine(progress: ProgressState | null, phase: RenderPhase | null, elapsedMs?: number, glyph?: ThemeGlyphs): string;
+/**
+ * The width-aware live line (U.12): {@link composeStatusLine} with honest
+ * degradation tiers so the status line never soft-wraps and never loses its
+ * essential meaning — *what is happening*. Priority is phase (the action) >
+ * the `[i/n] title` progress prefix (context) > the elapsed clock (decor), so
+ * as width shrinks we shed decor first and identity last:
+ *
+ * - wide: `[2/5] title · read_file src/x.ts… (12s)`
+ * - medium: drop the elapsed clock
+ * - narrow: drop the `[i/n] title` prefix, keep the phase
+ * - very-narrow: {@link fit} the phase text with an honest ellipsis
+ */
+export declare function fitStatusLine(progress: ProgressState | null, phase: RenderPhase | null, elapsedMs: number | undefined, glyph: ThemeGlyphs, width: number): string;