@gaia-ai/addon-gaia-ui 0.7.0 → 0.9.0

package/dist/src/Widget/textarea.js

@@ -0,0 +1,115 @@
+// GAIA-340 (ticket decision 6) — the widget layer's own `Renderable`, and the
+// one control the cockpit does not hand-paint.
+//
+// It arrived in GAIA-326 as `ViewOnlyTextarea` inside `Kernel/caret-slot.ts`,
+// where it was placed ABSOLUTELY over rows the frame had already composed. Here
+// it is a node in the tree the form returns, laid out by Yoga like every other
+// node — same class, same reasons, one owner. Task 9 Step 5 deleted that module
+// with the last screen that composed a popup out of rows, so this is the only
+// place the cockpit's insertion point has ever to be looked for.
+//
+// WHY A SUBCLASS AT ALL, since `@opentui/core` already ships the control:
+// `Kernel/mount.ts` patches a standing tree by ASSIGNING the props the next
+// frame declares, and `TextareaRenderable` exposes no assignable text. `setText`
+// is a method, `plainText` is read-only, and `initialValue`'s setter is guarded
+// by `_initialValueSet` so it applies exactly once. A raw
+// `h(TextareaRenderable, { initialValue })` would therefore paint the value the
+// field held when it was mounted and never change again — and the first frame
+// would look right, which is the kind of defect the PTY drivers exist for.
+// `value` and `caretOffset` are the two assignable props that fix it.
+import { RGBA, TextareaRenderable, } from '@opentui/core';
+/**
+ * Every colour the field uses, explicitly the terminal's own.
+ *
+ * `TextareaRenderable` defaults `textColor` to `#FFFFFF` and `placeholderColor`
+ * to `#666666`, and `EditBufferRenderable` defaults `cursorColor` to
+ * `rgba(1,1,1,1)` — hardcoded hex, i.e. TRUECOLOR on the wire, which is the one
+ * thing `tests/pty/verify-colors.mjs` fails the cockpit for and the exact defect
+ * that froze an operator's theme once already.
+ */
+const COLORS = () => ({
+    textColor: RGBA.defaultForeground(),
+    backgroundColor: RGBA.defaultBackground(),
+    focusedTextColor: RGBA.defaultForeground(),
+    focusedBackgroundColor: RGBA.defaultBackground(),
+    placeholderColor: RGBA.defaultForeground(),
+    cursorColor: RGBA.defaultForeground(),
+});
+/**
+ * A text field's value block: a Textarea that paints and never listens.
+ *
+ * CONTROLLED, and that word carries the whole design. The form reducer stays the
+ * single source of truth: this renderable is handed the current value and the
+ * current offset on every draw and owns NOTHING. So it must not also process
+ * keys — a focused renderable's `handleKeyPress` runs after the kernel's global
+ * listener, which does not `preventDefault()` (and could not do so per-widget),
+ * so both would apply the same keystroke. Measured against the stock class:
+ * typing `X` into a focused Textarea holding `ab` left `abX` in the widget AND
+ * `abX` in the reducer.
+ */
+export class FieldTextarea extends TextareaRenderable {
+    constructor(ctx, options) {
+        super(ctx, {
+            ...COLORS(),
+            // The widget layer's own wrap already decided where the lines break and
+            // the caller reserved exactly that many rows, so the renderable must not
+            // wrap again: it is handed the finished rows and lays them out verbatim.
+            // Measured, and the reason this is not `'word'`: the native word wrap
+            // breaks a line that exactly fills the width, so it disagreed with
+            // `wrapToWidthRows` on 3 of 10 sampled values — and a disagreement is a
+            // row the caller did not reserve.
+            wrapMode: 'none',
+            // No context margin: the viewport is sized to hold the whole row plus the
+            // cursor's cell, so there is nothing to scroll towards and a margin would
+            // only invent a reason to scroll.
+            scrollMargin: 0,
+            ...options,
+        });
+        // A picture of a value, not a document: a drag over it would paint a
+        // selection the cockpit never asked for, exactly as on the composed rows.
+        this.selectable = false;
+        // `instantiate` passes props to the CONSTRUCTOR and assigns nothing, while
+        // `patchTree` assigns and constructs nothing — so both entry points have to
+        // be served, and the first frame goes through here.
+        if (options.value !== undefined)
+            this.value = options.value;
+        if (options.caretOffset !== undefined)
+            this.caretOffset = options.caretOffset;
+    }
+    /** The reducer owns every key. This one sees them and declines all of them. */
+    handleKeyPress() {
+        return false;
+    }
+    /** …and a bracketed paste is just a very fast sequence of them. */
+    handlePaste() { }
+    get value() {
+        return this.plainText;
+    }
+    /**
+     * Guarded because `setText` resets the whole buffer through FFI, and a draw
+     * happens on every keystroke, wheel notch and resize — most of which leave the
+     * value alone and move only the offset.
+     */
+    set value(text) {
+        if (this.plainText !== text)
+            this.setText(text);
+    }
+    get caretOffset() {
+        return this.cursorOffset;
+    }
+    /**
+     * Focus before the offset: `renderCursor` draws nothing unless the renderable
+     * is focused, and the offset is what it resolves into a cell. Re-asserted on
+     * every draw rather than once, so a focus the renderer moved elsewhere (a
+     * click's `autoFocus`) is taken back on the next repaint instead of leaving
+     * the operator without a cursor.
+     *
+     * A node declaring both props must state `value` BEFORE `caretOffset`:
+     * `patchTree` assigns in declaration order and `setText` resets the offset.
+     */
+    set caretOffset(offset) {
+        if (!this.focused)
+            this.focus();
+        this.cursorOffset = offset;
+    }
+}

package/dist/src/Widget/types.d.ts

@@ -5,7 +5,8 @@ export interface WidgetContext {
     readonly field: FieldDecl;
     /** Whether the form's cursor is on this field. */
     readonly active: boolean;
-    /** The kernel's within-field cursor (a multiselect row, a suggestion row). */
+    /** The kernel's within-field cursor — per kind: a character offset in a
+     *  text value (GAIA-283), a multiselect row, a suggestion row. */
     readonly cursor: number;
     /** Display columns the popup body may use, border excluded. */
     readonly width: number;
@@ -36,6 +37,58 @@ export interface WidgetContext {
     /** The text typed into this field's search box (an `autocomplete` field). */
     query(): string;
 }
+/**
+ * GAIA-326 — where a kind's insertion point goes, for the kinds that have one.
+ *
+ * NOT A DRAWING. The `text` field used to splice an inverse-video cell into its
+ * own row; on an operator decision — they drive the cockpit over mosh from a
+ * phone, where mosh's local predictive echo needs a real cursor to predict at —
+ * the insertion point became a terminal cursor instead. A terminal cursor is not
+ * a character, so it cannot be expressed in the rows a widget returns: it is
+ * published as a POSITION and `renderWidget` turns it into a `FieldTextarea`
+ * node, which owns the cell and the cursor.
+ *
+ * IT LIVES HERE NOW, and that is the whole shape of GAIA-340 Task 9. It used to
+ * be `types.ts`'s `TextCaret`, in the shared types, because three layers that may
+ * not import each other all spoke it — `Widget/` published it, `Screen/` carried
+ * it on the presentation and `Kernel/` consumed it, each restating the one
+ * coordinate space it owned (a widget row, a `lines` index, a box row). The
+ * screens hand over trees, so nothing rebases it: `renderWidget` spends `row` and
+ * `column` as the block's position in the layout and Yoga places it. One layer
+ * speaks it, and it is this one.
+ *
+ * `row` indexes the rows `render` returned and `column` counts display columns
+ * from the popup body's left edge.
+ */
+export interface FieldCaret {
+    /** The row the value block starts on, among the rows `render` returned. */
+    readonly row: number;
+    /** Display columns from the body's left edge to the value block. */
+    readonly column: number;
+    /** The value block's display width in columns... */
+    readonly width: number;
+    /** ...and its height in rows. */
+    readonly height: number;
+    /**
+     * The value block's rows joined by `\n`.
+     *
+     * ONE WRAP: the widget wraps once and hands the rows here, so the height the
+     * layout reserves and the text the renderable paints cannot disagree about
+     * where a line breaks.
+     */
+    readonly text: string;
+    /** The insertion point's offset into {@link text} (UTF-16 code units). */
+    readonly offset: number;
+    /**
+     * What to paint when {@link text} is empty.
+     *
+     * An empty `text` field still occupies a row so the popup's rows keep lining
+     * up with its fields, and the block is what stands on that row — so it has to
+     * be told the same word the composed row said, or an empty active field would
+     * go blank the moment it got the cursor.
+     */
+    readonly placeholder: string | undefined;
+}
 export interface FieldWidget {
     /**
      * The rows this field occupies, WITHOUT the active marker: the caller prefixes
@@ -43,6 +96,16 @@ export interface FieldWidget {
      * absolute indent rather than a relative one.
      */
     render(ctx: WidgetContext): string[];
+    /**
+     * Where this kind's insertion point goes, when it is ACTIVE and has one.
+     *
+     * Optional because most kinds have none at all: a `select` is a ring, a
+     * `multiselect` a checklist, an `action` a button. Two kinds implement it —
+     * `text` (the value block) and, since GAIA-326's widget-fit F2 conversion,
+     * `autocomplete` (the query row, whose `▌` character it replaced with a real
+     * terminal cursor).
+     */
+    caret?(ctx: WidgetContext): FieldCaret | undefined;
     /**
      * Whether this kind draws its bag's failure itself.
      *

package/dist/src/launcher.d.ts

@@ -50,8 +50,15 @@ export interface GaiaUiLauncherOptions {
     connection: HomeConnection;
     /** Repo/home root the launched agents run in. */
     cwd: string;
-    /** Default project (opaque group), from the conductor registry. */
+    /** Default project (opaque group) — `gaia ui --project`, when given. */
     project?: string | undefined;
+    /**
+     * GAIA-232 (D9): the `.gaia` dir the entry is standing in. The renderer's
+     * `run()` resolves it against the control plane into the default `project`
+     * and `ownConductorMachineId`; the entry cannot, holding no JSON:API client.
+     * An explicit `project` above still wins.
+     */
+    gaiaDir?: string | undefined;
     /** Herdr-backed agent host, already adapted prompt→command (injected). */
     agents?: TuiAgentService | undefined;
     /** Preselected new-ticket assignee (this machine's user id). */
@@ -83,6 +90,6 @@ export type { UiInitialRoute, UiViewMode };
  * Build + run the dropsh `--format tui` program with the TUI renderer and the
  * injected agent host. A trivial `search gaia_project` seeds the renderer's
  * `run()`; the renderer discards the seed document and boots its own projects
- * screen from the conductor registry (`~/.gaia/conductors.json`).
+ * screen from the `gaia_conductor` records it reads through this connection.
  */
 export declare function runGaiaUi(opts: GaiaUiLauncherOptions): Promise<void>;

package/dist/src/launcher.js

@@ -3,7 +3,7 @@ import gaiaUiPlugin from './plugin.js';
  * Build + run the dropsh `--format tui` program with the TUI renderer and the
  * injected agent host. A trivial `search gaia_project` seeds the renderer's
  * `run()`; the renderer discards the seed document and boots its own projects
- * screen from the conductor registry (`~/.gaia/conductors.json`).
+ * screen from the `gaia_conductor` records it reads through this connection.
  */
 export async function runGaiaUi(opts) {
     // Point dropsh's own in-process context factory at the home dropsh config so
@@ -22,6 +22,7 @@ export async function runGaiaUi(opts) {
     const renderer = makeRenderer({
         cwd: opts.cwd,
         ...(opts.project !== undefined ? { project: opts.project } : {}),
+        ...(opts.gaiaDir !== undefined ? { gaiaDir: opts.gaiaDir } : {}),
         ...(opts.agents ? { agents: opts.agents } : {}),
         ...(opts.currentUser !== undefined
             ? { currentUser: opts.currentUser }

package/dist/src/lib/ansi.js

@@ -12,10 +12,16 @@ export function sanitizeDisplay(value) {
     // map every C0 whitespace control (TAB, LF, VT, FF, CR) to a space — keeping
     // words separated — then strip the remaining C0/C1 controls. A single field can
     // therefore never carry an embedded newline/tab into a "single row".
-    return (String(value)
+    //
+    // The ONE exception is SGR (`\x1b[…m`): it occupies no column and can neither
+    // move the cursor nor clear the screen, and the text field's inverse-video
+    // caret (GAIA-283) rides through this pipe on its way to the frame. Every
+    // OTHER escape sequence keeps losing its ESC and collapsing to inert text.
+    return String(value)
         .replace(/[\t\n\v\f\r]/g, ' ')
-        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping the C0/C1 control range is the whole point of this sanitizer.
-        .replace(/[\x00-\x1f\x7f-\x9f]/g, ''));
+        .replace(
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping the C0/C1 control range (SGR excepted) is the whole point of this sanitizer.
+    /(\x1b\[[0-9;]*m)|[\x00-\x1f\x7f-\x9f]/g, (_m, sgr) => sgr ?? '');
 }
 // Fit a value to exactly `width` DISPLAY COLUMNS. Measuring code units instead
 // (`String.length`/`padEnd`) is one column short per wide character — `⚡` alone
@@ -60,8 +66,10 @@ export function fitLineKeptWidth(value, width) {
     return displayWidth(truncateToWidth(text, Math.max(0, width - 1)));
 }
 // Fit + style the visible window: selected row inverse, heading rows bold —
-// both applied AFTER fitLine() so the ANSI wraps the sanitized text, never the
-// reverse (fitting an ANSI-wrapped string strips the ESC and leaks CSI text).
+// both applied AFTER fitLine() so the ANSI wraps whole fitted rows. (SGR also
+// survives INSIDE a value now — sanitizeDisplay keeps it for the GAIA-283
+// caret — but a style that must cover the row's PADDING still has to wrap the
+// fitted row, which is what happens here.)
 //
 // INVARIANT (AC-4): every returned entry is exactly ONE physical row. Two things
 // make that true, and BOTH are needed:

package/dist/src/lib/clipboard.d.ts

@@ -0,0 +1,41 @@
+import type { ClipboardOutcome, ClipboardWriter } from '../types.js';
+/**
+ * GAIA-326 — what the operator READS after asking for a copy, and the one rule
+ * the wording follows: never claim more than the outcome does.
+ *
+ * WHY THERE IS FEEDBACK AT ALL. An OSC 52 write paints nothing. The escape
+ * leaves for the operator's terminal emulator and either lands in their system
+ * clipboard or does not, and the cockpit is never told which. A copy that
+ * silently succeeds is therefore indistinguishable from one that silently
+ * failed — so the footer states the outcome, every time, and states the four
+ * outcomes differently.
+ *
+ * WHY FOUR OUTCOMES AND NOT TWO. `@opentui/core@0.5.1` probes the terminal and
+ * reports `supported | unknown | unsupported`
+ * (`TerminalCapabilities.osc52_support`), and `Clipboard.copyToClipboardOSC52`
+ * refuses ONLY on `unsupported`. So an `unknown` terminal — one that never
+ * answered the probe, which is what a plain `TERM=xterm-256color` pty is —
+ * really does get the escape, and the copy really may have worked. Reporting
+ * that as `copied` would be a claim the cockpit cannot back; reporting it as a
+ * failure would be a lie in the other direction. It gets its own word.
+ *
+ * The wording stays SHORT because the kernel's `fitLine` truncates the footer
+ * from the right (`Kernel/frame.ts`), and the notice shares that row with the
+ * screen's own key hints.
+ */
+export declare function clipboardStatus(outcome: ClipboardOutcome, what: string): string;
+/**
+ * Put `text` in the operator's clipboard and return the line that says so.
+ *
+ * SECURITY, and the reason this takes the text as an argument rather than
+ * reaching for it: OSC 52 writes into the operator's REAL system clipboard,
+ * clobbering whatever was there. So it is only ever reached from a keystroke
+ * that explicitly asked for a copy — never from navigation, a reload, a resize
+ * or a draw — and it copies exactly the one thing that keystroke named.
+ *
+ * `absent` is what to say when the caller has nothing to copy (a ticket with no
+ * link because the session has no base URL). Nothing is written in that case:
+ * an empty OSC 52 write would silently WIPE the operator's clipboard, which is
+ * a worse outcome than the copy not happening.
+ */
+export declare function copyThrough(writer: ClipboardWriter | undefined, text: string | undefined, what: string, absent: string): string;

package/dist/src/lib/clipboard.js

@@ -0,0 +1,65 @@
+/**
+ * GAIA-326 — what the operator READS after asking for a copy, and the one rule
+ * the wording follows: never claim more than the outcome does.
+ *
+ * WHY THERE IS FEEDBACK AT ALL. An OSC 52 write paints nothing. The escape
+ * leaves for the operator's terminal emulator and either lands in their system
+ * clipboard or does not, and the cockpit is never told which. A copy that
+ * silently succeeds is therefore indistinguishable from one that silently
+ * failed — so the footer states the outcome, every time, and states the four
+ * outcomes differently.
+ *
+ * WHY FOUR OUTCOMES AND NOT TWO. `@opentui/core@0.5.1` probes the terminal and
+ * reports `supported | unknown | unsupported`
+ * (`TerminalCapabilities.osc52_support`), and `Clipboard.copyToClipboardOSC52`
+ * refuses ONLY on `unsupported`. So an `unknown` terminal — one that never
+ * answered the probe, which is what a plain `TERM=xterm-256color` pty is —
+ * really does get the escape, and the copy really may have worked. Reporting
+ * that as `copied` would be a claim the cockpit cannot back; reporting it as a
+ * failure would be a lie in the other direction. It gets its own word.
+ *
+ * The wording stays SHORT because the kernel's `fitLine` truncates the footer
+ * from the right (`Kernel/frame.ts`), and the notice shares that row with the
+ * screen's own key hints.
+ */
+export function clipboardStatus(outcome, what) {
+    switch (outcome) {
+        case 'copied':
+            return `copied ${what}`;
+        case 'unconfirmed':
+            // Deliberately still opens with `copied`: the escape WAS sent, and on
+            // Ghostty — where the operator actually is — it works. The qualifier is
+            // what stops it being a promise. Kept to four words because it shares the
+            // footer with the screen's key ladder; the long version pushed `q quit`
+            // off a 120-column terminal, measured.
+            return `copied ${what} · OSC 52 unconfirmed`;
+        case 'unsupported':
+            return 'not copied · this terminal refuses OSC 52 clipboard writes';
+        default:
+            return 'not copied · the OSC 52 write failed';
+    }
+}
+/**
+ * Put `text` in the operator's clipboard and return the line that says so.
+ *
+ * SECURITY, and the reason this takes the text as an argument rather than
+ * reaching for it: OSC 52 writes into the operator's REAL system clipboard,
+ * clobbering whatever was there. So it is only ever reached from a keystroke
+ * that explicitly asked for a copy — never from navigation, a reload, a resize
+ * or a draw — and it copies exactly the one thing that keystroke named.
+ *
+ * `absent` is what to say when the caller has nothing to copy (a ticket with no
+ * link because the session has no base URL). Nothing is written in that case:
+ * an empty OSC 52 write would silently WIPE the operator's clipboard, which is
+ * a worse outcome than the copy not happening.
+ */
+export function copyThrough(writer, text, what, absent) {
+    if (text === undefined || text === '')
+        return absent;
+    // No writer means no terminal — the non-interactive `gaia ui` path, which
+    // writes plain lines to a pipe and never sees a keystroke. Stated rather than
+    // silently treated as a failure of the terminal's.
+    if (writer === undefined)
+        return 'not copied · no terminal to copy through';
+    return clipboardStatus(writer(text), what);
+}

package/dist/src/lib/cursor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The list selection cursor: an index plus the four move keys (GAIA-294).
+ *
+ * Extracted from FOUR verbatim copies — `ticket/Screen/tickets.ts`,
+ * `run/Screen/runs.ts`, `project/Screen/projects-screen.ts` and
+ * `ticket/Screen/ticket-agents.ts`. It is a plain composed object, not a base
+ * class or a mixin, because two of those four are `AsyncScreen<Row[]>` while the
+ * other two are `AsyncScreen<Page<Row>>`: no single base class spans them, and
+ * putting the index on `AsyncScreen` itself would hand a `selectedIndex` to every
+ * form, detail and dashboard screen that has no rows.
+ *
+ * It claims the move keys and NOTHING else — not `Enter`, which resolves to a
+ * per-screen `activate()`, and not the LEFT/RIGHT arrows, which page. So a caller
+ * keeps its own dispatch order simply by calling `handle` where its move keys used
+ * to be.
+ */
+export declare class ListCursor {
+    /** The selected row, or -1 on an empty list (see `handle`). */
+    index: number;
+    /**
+     * Apply `input` as a cursor move over `length` rows; false when it is not a
+     * cursor key, so the caller's `else if` chain continues unchanged.
+     *
+     * The clamping arithmetic is copied EXACTLY from the four call sites, including
+     * `Math.min(index + 1, length - 1)` yielding -1 when `length` is 0. That is
+     * today's behaviour, `present()` maps it back to -1, and GAIA-294 is
+     * behaviour-neutral — fixing it here would be a change smuggled into a refactor.
+     */
+    handle(input: string, length: number): boolean;
+    reset(): void;
+}

package/dist/src/lib/cursor.js

@@ -0,0 +1,45 @@
+/**
+ * The list selection cursor: an index plus the four move keys (GAIA-294).
+ *
+ * Extracted from FOUR verbatim copies — `ticket/Screen/tickets.ts`,
+ * `run/Screen/runs.ts`, `project/Screen/projects-screen.ts` and
+ * `ticket/Screen/ticket-agents.ts`. It is a plain composed object, not a base
+ * class or a mixin, because two of those four are `AsyncScreen<Row[]>` while the
+ * other two are `AsyncScreen<Page<Row>>`: no single base class spans them, and
+ * putting the index on `AsyncScreen` itself would hand a `selectedIndex` to every
+ * form, detail and dashboard screen that has no rows.
+ *
+ * It claims the move keys and NOTHING else — not `Enter`, which resolves to a
+ * per-screen `activate()`, and not the LEFT/RIGHT arrows, which page. So a caller
+ * keeps its own dispatch order simply by calling `handle` where its move keys used
+ * to be.
+ */
+export class ListCursor {
+    /** The selected row, or -1 on an empty list (see `handle`). */
+    index = 0;
+    /**
+     * Apply `input` as a cursor move over `length` rows; false when it is not a
+     * cursor key, so the caller's `else if` chain continues unchanged.
+     *
+     * The clamping arithmetic is copied EXACTLY from the four call sites, including
+     * `Math.min(index + 1, length - 1)` yielding -1 when `length` is 0. That is
+     * today's behaviour, `present()` maps it back to -1, and GAIA-294 is
+     * behaviour-neutral — fixing it here would be a change smuggled into a refactor.
+     */
+    handle(input, length) {
+        if (input === 'j' || input === 'down')
+            this.index = Math.min(this.index + 1, length - 1);
+        else if (input === 'k' || input === 'up')
+            this.index = Math.max(this.index - 1, 0);
+        else if (input === 'g')
+            this.index = 0;
+        else if (input === 'G')
+            this.index = Math.max(0, length - 1);
+        else
+            return false;
+        return true;
+    }
+    reset() {
+        this.index = 0;
+    }
+}

package/dist/src/lib/format.d.ts

@@ -1,16 +1,3 @@
-/**
- * A value fitted to exactly `width` DISPLAY COLUMNS — the unit a terminal lays
- * out in, not UTF-16 code units. Padding by `String.length` drifts one column
- * per wide character, which both misaligns table columns and (once the row is
- * assembled with borders) overflows the line into a second physical row.
- *
- * The value is SANITIZED before it is measured, and that ordering is the point:
- * every row `pad` builds passes through `fitLine`, which sanitizes too — mapping
- * TAB/LF/CR to a space and stripping the rest of the C0/C1 range. Measuring the
- * raw value counted a TAB as zero columns here and one column there, so the field
- * came out a column off and every later column of the table drifted with it.
- */
-export declare function pad(value: unknown, width: number): string;
 /** Read a value as a string, or `undefined` when it is not one. */
 export declare function asString(value: unknown): string | undefined;
 /**
@@ -22,3 +9,24 @@ export declare function asString(value: unknown): string | undefined;
  * removes those two cross-entity edges instead of grandfathering them.
  */
 export declare function humanizeAge(lastSeenSeconds: number | null, nowSeconds: number): string;
+/**
+ * Parse a human duration into SECONDS, or `null` when it is not one.
+ *
+ * Accepts `1d 2h 30m`, `1h30m`, `3h`, `90m` and a BARE INTEGER read as minutes
+ * — the last because the common case in a popup is typing a number, and every
+ * other tracker reads it the same way. Storage is seconds everywhere else
+ * (GAIA-308 D5); this grammar exists only at the terminal edge.
+ *
+ * An EMPTY input is 0, not null: clearing the field is a real edit, and the
+ * caller needs to tell "the operator cleared it" from "the operator typed
+ * nonsense". A negative or unknown-unit input is nonsense and yields null.
+ */
+export declare function parseDuration(input: string): number | null;
+/**
+ * Render SECONDS as a compact `1d 2h 30m`, largest unit first.
+ *
+ * Zero-valued leading units are dropped; a zero total reads `0m` rather than an
+ * empty string, so a deliberate zero is never mistaken for an absent value —
+ * which is `—`, the same em dash `humanizeAge` uses for an unknown timestamp.
+ */
+export declare function formatDuration(seconds: number | null | undefined): string;

package/dist/src/lib/format.js

@@ -1,31 +1,20 @@
-import { sanitizeDisplay } from './ansi.js';
-import { displayWidth, truncateToWidth } from './width.js';
-/**
- * A value fitted to exactly `width` DISPLAY COLUMNS — the unit a terminal lays
- * out in, not UTF-16 code units. Padding by `String.length` drifts one column
- * per wide character, which both misaligns table columns and (once the row is
- * assembled with borders) overflows the line into a second physical row.
- *
- * The value is SANITIZED before it is measured, and that ordering is the point:
- * every row `pad` builds passes through `fitLine`, which sanitizes too — mapping
- * TAB/LF/CR to a space and stripping the rest of the C0/C1 range. Measuring the
- * raw value counted a TAB as zero columns here and one column there, so the field
- * came out a column off and every later column of the table drifted with it.
- */
-export function pad(value, width) {
-    // As in `fitLine`: a zero budget renders nothing, not a lone ellipsis.
-    if (width <= 0)
-        return '';
-    const s = value == null ? '' : sanitizeDisplay(value);
-    const columns = displayWidth(s);
-    if (columns <= width)
-        return s + ' '.repeat(Math.max(0, width - columns));
-    // Truncation may stop a column short rather than split a wide character, so
-    // pad whatever the ellipsis does not fill.
-    const head = truncateToWidth(s, Math.max(0, width - 1));
-    const out = `${head}…`;
-    return out + ' '.repeat(Math.max(0, width - displayWidth(out)));
-}
+// GAIA-340 Task 13 — `pad` AND `sanitizeDisplay` USED TO LIVE HERE, and are
+// deliberately gone.
+//
+// `pad` fitted a value to a field of exactly N DISPLAY COLUMNS, which is why it
+// reached `lib/width.ts` — and `sanitizeDisplay` existed only to make that
+// measurement honest (a TAB counted as zero columns where it rendered as one, so
+// the field came out a column short and every later column of the table drifted).
+// Its two callers were the dashboard's bars and the ticket detail's Runs table,
+// both of which composed their columns into ONE STRING because the surface they
+// fed was a pipe as well as a screen.
+//
+// Neither composes now: each states its cells and their Yoga budgets
+// (`lib/vnode.ts`'s `Cell`), the renderer places the values, and the pipe prints
+// them one space apart and unaligned. That last part is a real change to what
+// `gaia ui … | cat` emits, made with the operator's approval and re-pinned in
+// `docs/evidence/GAIA-340/`; it is what takes the last display-column
+// measurement off the non-TTY path (R5/D8).
 /** Read a value as a string, or `undefined` when it is not one. */
 export function asString(value) {
     return typeof value === 'string' ? value : undefined;
@@ -50,3 +39,62 @@ export function humanizeAge(lastSeenSeconds, nowSeconds) {
         return `${Math.round(delta / 3600)}h ago`;
     return `${Math.round(delta / 86_400)}d ago`;
 }
+/** Seconds per accepted unit suffix, largest first — the order both functions read. */
+const DURATION_UNITS = [
+    ['d', 86_400],
+    ['h', 3600],
+    ['m', 60],
+];
+/**
+ * Parse a human duration into SECONDS, or `null` when it is not one.
+ *
+ * Accepts `1d 2h 30m`, `1h30m`, `3h`, `90m` and a BARE INTEGER read as minutes
+ * — the last because the common case in a popup is typing a number, and every
+ * other tracker reads it the same way. Storage is seconds everywhere else
+ * (GAIA-308 D5); this grammar exists only at the terminal edge.
+ *
+ * An EMPTY input is 0, not null: clearing the field is a real edit, and the
+ * caller needs to tell "the operator cleared it" from "the operator typed
+ * nonsense". A negative or unknown-unit input is nonsense and yields null.
+ */
+export function parseDuration(input) {
+    const text = input.trim().toLowerCase();
+    if (text === '')
+        return 0;
+    if (/^\d+$/.test(text))
+        return Number(text) * 60;
+    // One or more `<digits><unit>` groups, whitespace optional between them, and
+    // nothing else — anchored, so `1x` and `-5m` fall through to null.
+    if (!/^(\d+[dhm]\s*)+$/.test(text))
+        return null;
+    let seconds = 0;
+    for (const [, amount, unit] of text.matchAll(/(\d+)([dhm])/g)) {
+        const factor = DURATION_UNITS.find(([suffix]) => suffix === unit)?.[1];
+        if (factor === undefined)
+            return null;
+        seconds += Number(amount) * factor;
+    }
+    return seconds;
+}
+/**
+ * Render SECONDS as a compact `1d 2h 30m`, largest unit first.
+ *
+ * Zero-valued leading units are dropped; a zero total reads `0m` rather than an
+ * empty string, so a deliberate zero is never mistaken for an absent value —
+ * which is `—`, the same em dash `humanizeAge` uses for an unknown timestamp.
+ */
+export function formatDuration(seconds) {
+    if (seconds == null)
+        return '—';
+    if (seconds <= 0)
+        return '0m';
+    let rest = Math.floor(seconds);
+    const parts = [];
+    for (const [suffix, factor] of DURATION_UNITS) {
+        const value = Math.floor(rest / factor);
+        if (value > 0)
+            parts.push(`${value}${suffix}`);
+        rest -= value * factor;
+    }
+    return parts.length > 0 ? parts.join(' ') : '0m';
+}