@askdkc/dsh-cli 0.11.3

package/lib/types/components/whaleIdle.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Settled-header whale behaviors, ported from the dsh-ui-whale web plugin's
+ * animation driver (https://github.com/lhh010/dsh-ui-whale, src/client/
+ * animation.ts): independent tail / fin / heart / sleep-Z / blink layers —
+ * a click heart plays OVER a mid-wag tail or the sleep-Z loop instead of
+ * replacing it (the old whole-frame planner arbitrated one action at a time).
+ *
+ * Web-faithful layer semantics: continuous tail/fin cycling while the agent
+ * works, occasional passes while idle AND while asleep (the web pet never
+ * freezes mid-sleep), a sticky sleep entered after SLEEP_DELAY_MS of
+ * inactivity that work or a click clears (the web pet's sleep is
+ * click-sticky — TUI divergence), and a one-way 1-2-3 heart pass.
+ *
+ * Event-driven: while resting, the ONLY pending timer is the next due layer
+ * transition, and with the setting off the component holds no timer at all
+ * (the idle-wakeup contract keeps holding). Pure functions over (state,
+ * input, now) — unit-testable without timers.
+ */
+import type { WhaleLayerPose } from './whaleLayers.js';
+/** How long each heart size is held (web HEART_HOLD = 3 ticks). */
+export declare const HEART_HOLD_MS: number;
+/** Continuous inactivity before the whale falls asleep (10 seconds). */
+export declare const SLEEP_DELAY_MS = 10000;
+/**
+ * Planner state — one independent plane per layer. Steps index their pose
+ * sequence (-1 = resting); holds are deadlines; the *At fields schedule the
+ * occasional passes and the sleep entry. The heart is its own one-shot plane
+ * so it overlays whatever the body planes are doing.
+ */
+export interface WhaleIdleState {
+    readonly tailStep: number;
+    readonly tailHoldUntil: number;
+    readonly thumpAt: number;
+    readonly finStep: number;
+    readonly finHoldUntil: number;
+    readonly flutterAt: number;
+    readonly blinkAt: number;
+    readonly blinkUntil: number;
+    readonly heartStep: number;
+    readonly heartHoldUntil: number;
+    readonly asleep: boolean;
+    readonly sleepStep: number;
+    readonly sleepHoldUntil: number;
+    readonly sleepAt: number;
+}
+/** The per-step inputs: agent activity + a pending click-heart request. */
+export interface WhaleIdleInput {
+    readonly working: boolean;
+    readonly heart: boolean;
+}
+/** One planner decision: the state to keep, the pose to paint, the wait. */
+export interface WhaleIdleStep {
+    readonly state: WhaleIdleState;
+    readonly pose: WhaleLayerPose;
+    readonly delayMs: number;
+}
+/** The resting initial state; `now` seeds the idle event schedule. */
+export declare function initialWhaleIdleState(now: number): WhaleIdleState;
+/**
+ * Compute the next animation step.
+ * @param prev - the state carried from the previous step.
+ * @param input - working (agent turn active) and heart (click requested).
+ * @param now - current wall-clock ms (test seam: inject fixed clocks).
+ */
+export declare function nextWhaleIdleStep(prev: WhaleIdleState, input: WhaleIdleInput, now: number): WhaleIdleStep;
+//# sourceMappingURL=whaleIdle.d.ts.map

package/lib/types/components/whaleIdle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whaleIdle.d.ts","sourceRoot":"","sources":["../../../src/components/whaleIdle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAmBtD,mEAAmE;AACnE,eAAO,MAAM,aAAa,QAAc,CAAA;AACxC,wEAAwE;AACxE,eAAO,MAAM,cAAc,QAAS,CAAA;AAiBpC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAiBjE;AAoCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,MAAM,GACV,aAAa,CAoGf"}

package/lib/types/components/whaleIdle.js

@@ -0,0 +1,174 @@
+const TICK_MS = 120; // the web plugin's animation tick
+// Web-faithful cadences: animation.ts WAG_HOLD / FIN_HOLD / BLINK_GAP /
+// SLEEP_HOLD / HEART_HOLD, in ticks, converted to ms.
+// Idle gaps and idle holds are TIGHTENED from the web values (thump 90
+// ticks, flutter 60, holds 6/5): at web cadence the settled terminal whale
+// visibly stalls between moves, so it moves ~3x as often here.
+const WAG_HOLD_WORKING_MS = 2 * TICK_MS;
+const WAG_HOLD_IDLE_MS = 3 * TICK_MS;
+const FIN_HOLD_WORKING_MS = 2 * TICK_MS;
+const FIN_HOLD_IDLE_MS = 2 * TICK_MS;
+const BLINK_HOLD_MS = 1 * TICK_MS;
+const BLINK_GAP_WORKING_MS = 14 * TICK_MS;
+const BLINK_GAP_IDLE_MS = 42 * TICK_MS;
+const IDLE_THUMP_GAP_MS = 25 * TICK_MS;
+const IDLE_FLUTTER_GAP_MS = 16 * TICK_MS;
+const SLEEP_HOLD_MS = 3 * TICK_MS;
+/** How long each heart size is held (web HEART_HOLD = 3 ticks). */
+export const HEART_HOLD_MS = 3 * TICK_MS;
+/** Continuous inactivity before the whale falls asleep (10 seconds). */
+export const SLEEP_DELAY_MS = 10_000;
+// Pose sequences — layer indices, straight from the web plugin:
+// WAG_SEQUENCE 0-1-2-3-4-3-2-1-0 (forward-and-back), FIN_SEQUENCE 0-1-2-1-0,
+// HEART one-way 0-1-2-3-0 (grows, then the pass ends).
+const WAG_SEQUENCE = [1, 2, 3, 4, 3, 2, 1];
+const FIN_SEQUENCE = [1, 2, 1];
+const HEART_SEQUENCE = [1, 2, 3];
+const SLEEP_LAST = 5;
+/** The resting initial state; `now` seeds the idle event schedule. */
+export function initialWhaleIdleState(now) {
+    return {
+        tailStep: -1,
+        tailHoldUntil: 0,
+        thumpAt: now + IDLE_THUMP_GAP_MS,
+        finStep: -1,
+        finHoldUntil: 0,
+        flutterAt: now + IDLE_FLUTTER_GAP_MS,
+        blinkAt: now + BLINK_GAP_IDLE_MS,
+        blinkUntil: 0,
+        heartStep: -1,
+        heartHoldUntil: 0,
+        asleep: false,
+        sleepStep: -1,
+        sleepHoldUntil: 0,
+        sleepAt: now + SLEEP_DELAY_MS,
+    };
+}
+/**
+ * Advance one limb plane. Working cycles the pass continuously; idle and
+ * asleep play one occasional pass per gap and rest at the resting pose
+ * between passes (web advanceLimb: the sleeping whale never freezes —
+ * the tail keeps thumping and the fins keep fluttering on their cadence).
+ */
+function advanceLimb(step, holdUntil, passAt, sequence, holdWorkingMs, holdIdleMs, passGapMs, continuous, now) {
+    const holdMs = continuous ? holdWorkingMs : holdIdleMs;
+    if (continuous) {
+        if (step < 0)
+            return { step: 0, holdUntil: now + holdMs, passAt: now + passGapMs };
+        if (now >= holdUntil)
+            return { step: (step + 1) % sequence.length, holdUntil: now + holdMs, passAt: now + passGapMs };
+        return { step, holdUntil, passAt };
+    }
+    if (step >= 0) {
+        if (now >= holdUntil) {
+            if (step >= sequence.length - 1)
+                return { step: -1, holdUntil: 0, passAt: now + passGapMs };
+            return { step: step + 1, holdUntil: now + holdMs, passAt };
+        }
+        return { step, holdUntil, passAt };
+    }
+    if (now >= passAt)
+        return { step: 0, holdUntil: now + holdMs, passAt };
+    return { step: -1, holdUntil: 0, passAt };
+}
+/**
+ * Compute the next animation step.
+ * @param prev - the state carried from the previous step.
+ * @param input - working (agent turn active) and heart (click requested).
+ * @param now - current wall-clock ms (test seam: inject fixed clocks).
+ */
+export function nextWhaleIdleStep(prev, input, now) {
+    // Heart plane — a click (re)arms the one-way pass from the small heart,
+    // even mid-pass; it overlays everything. On the TUI a click also WAKES a
+    // sleeping whale (the web pet's sleep is click-sticky — deliberate
+    // divergence: the whale should respond to the one gesture it has).
+    let heartStep = prev.heartStep;
+    let heartHoldUntil = prev.heartHoldUntil;
+    if (input.heart) {
+        heartStep = 0;
+        heartHoldUntil = now + HEART_HOLD_MS;
+    }
+    else if (heartStep >= 0 && now >= heartHoldUntil) {
+        heartStep = heartStep >= HEART_SEQUENCE.length - 1 ? -1 : heartStep + 1;
+        if (heartStep >= 0)
+            heartHoldUntil = now + HEART_HOLD_MS;
+    }
+    // Sleep plane — sticky while idle: work or a click clears it (a click
+    // wakes the whale AND plays the heart pass), and both re-arm the sleep
+    // delay so it dozes off again only after a fresh idle stretch. A click
+    // counts as activity even when the whale is awake: it must not fall
+    // asleep mid-heart-pass (a click at sleepAt - 500ms would otherwise).
+    let asleep = prev.asleep;
+    let sleepStep = prev.sleepStep;
+    let sleepHoldUntil = prev.sleepHoldUntil;
+    let sleepAt = prev.sleepAt;
+    if (input.working || input.heart) {
+        if (asleep || sleepStep >= 0) {
+            asleep = false;
+            sleepStep = -1;
+        }
+        sleepAt = now + SLEEP_DELAY_MS;
+    }
+    else if (!asleep && now >= sleepAt) {
+        // Entry: the resting pose (layer 0) plays once as the whale settles.
+        asleep = true;
+        sleepStep = 0;
+        sleepHoldUntil = now + SLEEP_HOLD_MS;
+    }
+    else if (asleep && now >= sleepHoldUntil) {
+        // Z loop: 1..5, wrapping back to 1 (never to the resting pose).
+        sleepStep = sleepStep >= SLEEP_LAST ? 1 : sleepStep + 1;
+        sleepHoldUntil = now + SLEEP_HOLD_MS;
+    }
+    // Body planes — tail and fin run independently of each other and of the
+    // heart/sleep overlays.
+    const continuous = input.working;
+    const tail = advanceLimb(prev.tailStep, prev.tailHoldUntil, prev.thumpAt, WAG_SEQUENCE, WAG_HOLD_WORKING_MS, WAG_HOLD_IDLE_MS, IDLE_THUMP_GAP_MS, continuous, now);
+    const fin = advanceLimb(prev.finStep, prev.finHoldUntil, prev.flutterAt, FIN_SEQUENCE, FIN_HOLD_WORKING_MS, FIN_HOLD_IDLE_MS, IDLE_FLUTTER_GAP_MS, continuous, now);
+    // Blink plane — its own cadence, composing over any body pose.
+    let blinkAt = prev.blinkAt;
+    let blinkUntil = prev.blinkUntil;
+    if (now >= blinkAt) {
+        blinkUntil = now + BLINK_HOLD_MS;
+        blinkAt = now + (input.working ? BLINK_GAP_WORKING_MS : BLINK_GAP_IDLE_MS);
+    }
+    const blinking = now < blinkUntil;
+    const pose = {
+        tail: tail.step < 0 ? 0 : WAG_SEQUENCE[tail.step] ?? 0,
+        fin: fin.step < 0 ? 0 : FIN_SEQUENCE[fin.step] ?? 0,
+        spout: 0,
+        heart: heartStep < 0 ? 0 : HEART_SEQUENCE[heartStep] ?? 0,
+        sleep: asleep ? Math.max(0, sleepStep) : 0,
+        blink: blinking,
+    };
+    // Next due transition across every active plane; the sleep deadline is
+    // always pending while awake, so a resting whale waits for exactly one
+    // event (the idle-wakeup contract).
+    const dues = [];
+    dues.push(tail.step >= 0 ? tail.holdUntil : tail.passAt);
+    dues.push(fin.step >= 0 ? fin.holdUntil : fin.passAt);
+    if (heartStep >= 0)
+        dues.push(heartHoldUntil);
+    dues.push(asleep ? sleepHoldUntil : sleepAt);
+    dues.push(blinkAt);
+    if (blinking)
+        dues.push(blinkUntil);
+    const next = dues.reduce((a, b) => (b < a && b > now ? b : a), Number.POSITIVE_INFINITY);
+    const delayMs = Math.max(16, next - now);
+    return { state: {
+            tailStep: tail.step,
+            tailHoldUntil: tail.holdUntil,
+            thumpAt: tail.passAt,
+            finStep: fin.step,
+            finHoldUntil: fin.holdUntil,
+            flutterAt: fin.passAt,
+            blinkAt,
+            blinkUntil,
+            heartStep,
+            heartHoldUntil,
+            asleep,
+            sleepStep,
+            sleepHoldUntil,
+            sleepAt,
+        }, pose, delayMs };
+}

package/lib/types/components/whaleLayers.d.ts

@@ -0,0 +1,28 @@
+/** One composed whale pose, in the web plugin's WhaleFrame shape. */
+export interface WhaleLayerPose {
+    /** 0 = resting tail; 1..4 = TAIL_1..4. */
+    readonly tail: number;
+    /** 0 = resting fins; 1..2 = FIN_1..2. */
+    readonly fin: number;
+    /** 0 = none; 1..6 = SPOUT_1..6. */
+    readonly spout: number;
+    /** 0 = none; 1..3 = HEART_1..3. */
+    readonly heart: number;
+    /** 0 = awake; 1..5 = SLEEP_1..5 (the Z loop). */
+    readonly sleep: number;
+    /** Eyes closed. */
+    readonly blink: boolean;
+}
+/** The resting pose every animation returns to. */
+export declare const RESTING_POSE: WhaleLayerPose;
+type Grid = string[][];
+/**
+ * Compose one pose into the full 25x40 character grid: body + eyes + tail +
+ * fins + spout + heart + sleep-Z, painted in the web plugin's layer order.
+ * Single-family poses compose to exactly that family's whole frame.
+ */
+export declare function composeWhaleGrid(pose: WhaleLayerPose): Grid;
+/** Stable cache key for one pose (layer indices are small integers). */
+export declare function poseKey(pose: WhaleLayerPose): string;
+export {};
+//# sourceMappingURL=whaleLayers.d.ts.map

package/lib/types/components/whaleLayers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whaleLayers.d.ts","sourceRoot":"","sources":["../../../src/components/whaleLayers.ts"],"names":[],"mappings":"AAkBA,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,mDAAmD;AACnD,eAAO,MAAM,YAAY,EAAE,cAE1B,CAAA;AAED,KAAK,IAAI,GAAG,MAAM,EAAE,EAAE,CAAA;AAyDtB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAS3D;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAEpD"}

package/lib/types/components/whaleLayers.js

@@ -0,0 +1,90 @@
+/**
+ * Layered whale sprite composition, ported from the dsh-ui-whale web plugin
+ * (https://github.com/lhh010/dsh-ui-whale, src/client/sprite.ts): the frame
+ * set splits into the still STANDARD body plus per-action diff regions — the
+ * cells any frame of an action changes relative to STANDARD. A pose composes
+ * by overlaying each action's diff cells onto the cleared body, so tail wags,
+ * fin flutters, hearts, sleep-Z and blinks render INDEPENDENTLY and can run
+ * in parallel (a click heart plays over a mid-wag tail; a blink composes over
+ * any pose) — exactly the web pet's semantics, where the old whole-frame
+ * planner could only arbitrate one action at a time.
+ *
+ * All pixel data comes from the same source art as the web plugin
+ * (whale_frames, 25x40 grids, palette D outline · B body · L belly · W mouth ·
+ * H heart · Z sleep-Z · `.` transparent), so composed poses are
+ * pixel-identical to it; `scripts/verify-whale-idle.mjs` pins frame parity.
+ */
+import { WHALE_FRAMES, WHALE_FRAME_INDEX } from './whaleFrames.js';
+/** The resting pose every animation returns to. */
+export const RESTING_POSE = {
+    tail: 0, fin: 0, spout: 0, heart: 0, sleep: 0, blink: false,
+};
+function gridOf(frameIndex) {
+    return WHALE_FRAMES[frameIndex].rows.map(row => row.split(''));
+}
+/** Cells where any frame of the family differs from STANDARD. */
+function diffRegion(frameIndexes) {
+    const region = new Set();
+    const standard = WHALE_FRAMES[WHALE_FRAME_INDEX.standard].rows;
+    for (const index of frameIndexes) {
+        WHALE_FRAMES[index].rows.forEach((row, y) => {
+            for (let x = 0; x < row.length; x += 1) {
+                if ((row[x] ?? '.') !== (standard[y]?.[x] ?? '.'))
+                    region.add(`${x},${y}`);
+            }
+        });
+    }
+    return region;
+}
+const F = WHALE_FRAME_INDEX;
+const EYES_REGION = diffRegion([F.blink]);
+const TAIL_REGION = diffRegion([F.tail1, F.tail2, F.tail3, F.tail4]);
+const FIN_REGION = diffRegion([F.fin1, F.fin2]);
+const SPOUT_REGION = diffRegion([F.spout1, F.spout2, F.spout3, F.spout4, F.spout5, F.spout6]);
+const HEART_REGION = diffRegion([F.heart1, F.heart2, F.heart3]);
+const SLEEP_REGION = diffRegion([F.sleep1, F.sleep2, F.sleep3, F.sleep4, F.sleep5]);
+/**
+ * The still body: STANDARD with every motion region cleared (transparent).
+ * Layers paint their own pixels back — an idle region cell stays transparent,
+ * exactly like the web plugin's filtered BODY layer.
+ */
+const BASE = (() => {
+    const grid = gridOf(F.standard);
+    for (const region of [EYES_REGION, TAIL_REGION, FIN_REGION, SPOUT_REGION, HEART_REGION, SLEEP_REGION]) {
+        for (const key of region) {
+            const [x, y] = key.split(',').map(Number);
+            grid[y][x] = '.';
+        }
+    }
+    return grid;
+})();
+/** Paint the family frame's cells inside the family's motion region. */
+function applyLayer(grid, frameIndex, region) {
+    const rows = WHALE_FRAMES[frameIndex].rows;
+    for (const key of region) {
+        const [x, y] = key.split(',').map(Number);
+        grid[y][x] = rows[y]?.[x] ?? '.';
+    }
+}
+function familyFrameIndex(poseValue, rest, frames) {
+    return poseValue <= 0 ? rest : frames[poseValue - 1] ?? rest;
+}
+/**
+ * Compose one pose into the full 25x40 character grid: body + eyes + tail +
+ * fins + spout + heart + sleep-Z, painted in the web plugin's layer order.
+ * Single-family poses compose to exactly that family's whole frame.
+ */
+export function composeWhaleGrid(pose) {
+    const grid = BASE.map(row => [...row]);
+    applyLayer(grid, pose.blink ? F.blink : F.standard, EYES_REGION);
+    applyLayer(grid, familyFrameIndex(pose.tail, F.standard, [F.tail1, F.tail2, F.tail3, F.tail4]), TAIL_REGION);
+    applyLayer(grid, familyFrameIndex(pose.fin, F.standard, [F.fin1, F.fin2]), FIN_REGION);
+    applyLayer(grid, familyFrameIndex(pose.spout, F.standard, [F.spout1, F.spout2, F.spout3, F.spout4, F.spout5, F.spout6]), SPOUT_REGION);
+    applyLayer(grid, familyFrameIndex(pose.heart, F.standard, [F.heart1, F.heart2, F.heart3]), HEART_REGION);
+    applyLayer(grid, familyFrameIndex(pose.sleep, F.standard, [F.sleep1, F.sleep2, F.sleep3, F.sleep4, F.sleep5]), SLEEP_REGION);
+    return grid;
+}
+/** Stable cache key for one pose (layer indices are small integers). */
+export function poseKey(pose) {
+    return `${pose.tail}.${pose.fin}.${pose.spout}.${pose.heart}.${pose.sleep}.${pose.blink ? 1 : 0}`;
+}

package/lib/types/components/workspaces/HomeWorkspaceRow.d.ts

@@ -0,0 +1,49 @@
+import React from 'react';
+import type { ClickEvent } from '../../ink/events/click-event.js';
+import type { ContextMenuEvent } from '../../ink/events/context-menu-event.js';
+/**
+ * One workspace in the home screen's left rail.
+ *
+ * Two lines, like every other navigable row in this app: the name line is what
+ * the user named it, the detail line is where it actually is and how much is in
+ * it. The path is not decoration — two workspaces can carry the same basename
+ * (`.../a/work` and `.../b/work`), and the ledger allows duplicate titles, so
+ * the path is the only thing that tells them apart.
+ *
+ * Widths are resolved here rather than left to flexbox for the same reason the
+ * session rows resolve them: a row must be exactly two lines at every terminal
+ * width, and a wrapped row destroys the alignment a list is scanned by.
+ */
+export declare function HomeWorkspaceRow({ title, path, home, sessionCount, present, selected, focused, width, onSelect, onMenu, }: {
+    title: string;
+    /** Canonical directory path recorded in the ledger. */
+    path: string;
+    /** Home directory, for collapsing the path to `~`. */
+    home: string;
+    sessionCount: number;
+    /** False when the recorded directory no longer exists. */
+    present: boolean;
+    /** Whether this workspace's sessions are the ones on the right. */
+    selected: boolean;
+    /** Keyboard cursor. */
+    focused: boolean;
+    /** Columns available to the row. */
+    width: number;
+    /** Left click: show this workspace's sessions (same path as Enter). */
+    onSelect?(event: ClickEvent): void;
+    /** Right click: open the workspace action menu. */
+    onMenu?(event: ContextMenuEvent): void;
+}): React.ReactNode;
+/**
+ * The `+` row that opens the directory picker.
+ *
+ * Deliberately the FIRST row of the rail and always clickable: adding a
+ * workspace is the rail's only creation action, and a control that is only
+ * reachable by keyboard is a control most users never find in a terminal.
+ */
+export declare function HomeAddWorkspaceRow({ focused, width, onOpen, }: {
+    focused: boolean;
+    width: number;
+    onOpen?(event: ClickEvent): void;
+}): React.ReactNode;
+//# sourceMappingURL=HomeWorkspaceRow.d.ts.map

package/lib/types/components/workspaces/HomeWorkspaceRow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HomeWorkspaceRow.d.ts","sourceRoot":"","sources":["../../../../src/components/workspaces/HomeWorkspaceRow.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmB,MAAM,OAAO,CAAA;AAGvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AAG9E;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,OAAO,EACP,KAAK,EACL,QAAQ,EACR,MAAM,GACP,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAA;IAChB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAA;IACjB,uBAAuB;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,QAAQ,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IAClC,mDAAmD;IACnD,MAAM,CAAC,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACvC,GAAG,KAAK,CAAC,SAAS,CAuClB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,KAAK,EACL,MAAM,GACP,EAAE;IACD,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;CACjC,GAAG,KAAK,CAAC,SAAS,CAoBlB"}

package/lib/types/components/workspaces/HomeWorkspaceRow.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text } from '../../ui.js';
+import { t } from '../../i18n.js';
+import { formatProject, spreadRow, truncateWidth } from '../../sessions/format.js';
+/**
+ * One workspace in the home screen's left rail.
+ *
+ * Two lines, like every other navigable row in this app: the name line is what
+ * the user named it, the detail line is where it actually is and how much is in
+ * it. The path is not decoration — two workspaces can carry the same basename
+ * (`.../a/work` and `.../b/work`), and the ledger allows duplicate titles, so
+ * the path is the only thing that tells them apart.
+ *
+ * Widths are resolved here rather than left to flexbox for the same reason the
+ * session rows resolve them: a row must be exactly two lines at every terminal
+ * width, and a wrapped row destroys the alignment a list is scanned by.
+ */
+export function HomeWorkspaceRow({ title, path, home, sessionCount, present, selected, focused, width, onSelect, onMenu, }) {
+    const [hovered, setHovered] = useState(false);
+    const body = Math.max(8, width - 4);
+    // The presence marker leads the badge on purpose: `spreadRow` may truncate
+    // the right-hand segment, and "this directory is gone" is the one fact that
+    // must never be the part that gets cut (the session count is also visible in
+    // the pane, the missing directory is not).
+    const count = t('home-sessions-count', { n: sessionCount });
+    const badge = present ? count : `${t('home-workspace-missing')} · ${count}`;
+    const heading = spreadRow(`${selected ? '▣' : '▢'} ${title}`, `${selected ? '✓ ' : ''}${badge}`, body);
+    const detail = formatProject(path, home);
+    // The cursor (green) outranks the selection ring (green); both outrank the
+    // idle colour. Blue is not part of this ladder at all — see the background.
+    const headingColor = (focused || selected) ? 'success' : present ? 'text' : 'inactive';
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, paddingX: 1, onClick: onSelect, onContextMenu: onMenu, onMouseEnter: onSelect === undefined && onMenu === undefined ? undefined : () => setHovered(true), onMouseLeave: onSelect === undefined && onMenu === undefined ? undefined : () => setHovered(false), 
+        // Hover is the BLUE prompt — pointer feedback and nothing else, so it
+        // never marks the focused or the selected row. Selection itself is green
+        // in the text, which is why this row draws no box while selected.
+        backgroundColor: hovered && !focused ? 'userMessageBackgroundHover' : undefined, children: [_jsxs(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: [_jsx(Text, { color: focused ? 'success' : 'subtle', children: focused ? '❯ ' : '  ' }), _jsx(Text, { color: headingColor, bold: focused || selected, children: heading.left }), _jsx(Text, { dimColor: !focused, children: `${' '.repeat(heading.gap)}${heading.right}` })] }), _jsx(Text, { color: (focused || selected) ? 'success' : undefined, dimColor: !(focused || selected), wrap: "truncate-end", children: `  ${truncateWidth(detail, body - 2)}` })] }));
+}
+/**
+ * The `+` row that opens the directory picker.
+ *
+ * Deliberately the FIRST row of the rail and always clickable: adding a
+ * workspace is the rail's only creation action, and a control that is only
+ * reachable by keyboard is a control most users never find in a terminal.
+ */
+export function HomeAddWorkspaceRow({ focused, width, onOpen, }) {
+    const [hovered, setHovered] = useState(false);
+    const body = Math.max(8, width - 4);
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, paddingX: 1, onClick: onOpen, onMouseEnter: onOpen === undefined ? undefined : () => setHovered(true), onMouseLeave: onOpen === undefined ? undefined : () => setHovered(false), backgroundColor: focused || hovered ? 'userMessageBackgroundHover' : undefined, children: [_jsxs(Box, { height: 1, flexShrink: 0, overflow: "hidden", children: [_jsx(Text, { color: focused ? 'suggestion' : 'subtle', children: focused ? '❯ ' : '  ' }), _jsx(Text, { color: "remember", bold: true, children: `＋ ${t('home-add-workspace')}` })] }), _jsx(Text, { dimColor: true, wrap: "truncate-end", children: `  ${truncateWidth(t('home-add-hint'), body - 2)}` })] }));
+}

package/lib/types/customTheme.d.ts

@@ -0,0 +1,108 @@
+/**
+ * User-defined color themes for dsh-tui.
+ *
+ * A theme is a JSON file in `~/.dsh-tui/themes/<name>.json`:
+ *
+ * ```json
+ * { "name": "sakura", "displayName": "Sakura Pink", "base": "dark",
+ *   "colors": { "accent": "#FF9EC7", "text": "#E8E6E0" } }
+ * ```
+ *
+ * `base` is required (`light`/`dark`/`dark-ansi`) and selects the built-in
+ * palette the file overlays; `colors` holds a subset of Theme keys. `name`
+ * defaults to the file name; `displayName` defaults to `name`.
+ *
+ * Validation is best-effort per key: unknown keys and invalid color values
+ * are skipped with a warning on stderr, never fatal; a file whose JSON is
+ * malformed or whose `base` is invalid is skipped entirely (also warned).
+ * Accepted color value forms (the same forms the built-in palettes and the
+ * Ink color engine use): `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb(r,g,b)`,
+ * `ansi256(n)` and the 16 `ansi:` names.
+ */
+import { type Theme, type ThemeColorKey } from './theme.js';
+/** The base palettes a user theme may overlay. */
+export declare const THEME_BASE_NAMES: readonly ["light", "dark", "dark-ansi"];
+export type ThemeBase = (typeof THEME_BASE_NAMES)[number];
+/** The directory user theme files live in (~/.dsh-tui/themes). */
+export declare const CUSTOM_THEME_DIR: string;
+/** A validated user theme file. `colors` only carries accepted overrides. */
+export type CustomThemeSpec = {
+    /** Stable id: the file's `name` field, or the file name (minus .json) when omitted. */
+    name: string;
+    /** Human-readable label for pickers; defaults to `name`. */
+    displayName: string;
+    /** The built-in palette this theme overlays. */
+    base: ThemeBase;
+    /** Validated Theme-key overrides (a subset of the base palette). */
+    colors: Partial<Theme>;
+    /** The underlying file name without .json — the on-disk load key. */
+    file: string;
+};
+/** Whether a value names one of the three built-in overlay palettes. */
+export declare function isThemeBase(value: unknown): value is ThemeBase;
+/** Whether a value is a canonical or deprecated Theme input key. */
+export declare function isThemeKey(value: unknown): value is ThemeColorKey;
+/**
+ * Whether a name is safe to use as a file name (no path separators or dot
+ * traversal). Theme names are user input from DSH_TUI_THEME and /theme, so
+ * they must never escape the themes directory.
+ */
+export declare function isSafeThemeName(name: string): boolean;
+/**
+ * Whether a value is an accepted color string: #rgb/#rrggbb/#rrggbbaa,
+ * rgb(r,g,b), ansi256(n) or one of the 16 ansi: names — the same forms the
+ * built-in palettes and the Ink color engine accept.
+ * @param value - Candidate color value.
+ * @returns True when the value is a well-formed color string.
+ */
+export declare function isValidThemeColor(value: unknown): value is string;
+/**
+ * Parse and validate a theme file's contents. Unknown keys and invalid
+ * color values are skipped (each warned); a file that is not an object,
+ * has an invalid `base`, or has a non-object `colors` is rejected entirely.
+ * @param text - Raw file contents.
+ * @param fileName - File name (with or without the .json extension); the
+ *   load key and the default theme name when the file omits `name`.
+ * @returns The validated spec, or undefined when the file is unusable.
+ */
+export declare function parseCustomTheme(text: string, fileName: string): CustomThemeSpec | undefined;
+/**
+ * Load and validate one user theme by name.
+ * @param name - Theme name (file name without .json).
+ * @param dir - Themes directory (injectable for tests).
+ * @returns The validated spec, or undefined when missing/invalid.
+ */
+export declare function loadCustomTheme(name: string, dir?: string): CustomThemeSpec | undefined;
+/**
+ * Discover every usable user theme in the themes directory, sorted by name.
+ * Invalid files are skipped (each warned by parseCustomTheme).
+ * @param dir - Themes directory (injectable for tests).
+ * @returns The validated specs found.
+ */
+export declare function listCustomThemes(dir?: string): CustomThemeSpec[];
+/**
+ * Overlay a spec's overrides onto its base palette.
+ * @param spec - Validated theme spec.
+ * @returns The full concrete palette.
+ */
+export declare function buildTheme(spec: CustomThemeSpec): Theme;
+/**
+ * Resolve a user theme name to its full palette, cached after first load.
+ * A `name` field that differs from the file name is indexed on the first
+ * miss, so display names resolve everywhere. Failures are not cached, so a
+ * file fixed while the TUI runs can be picked up on the next attempt.
+ * @param name - User theme name.
+ * @returns The built palette, or undefined when unknown/invalid.
+ */
+export declare function resolveCustomTheme(name: string): Theme | undefined;
+/**
+ * Whether a name selects a usable theme: a built-in palette, the `auto`
+ * pseudo-theme, or a valid user theme file. Used for DSH_TUI_THEME /
+ * persisted-preference validation and the runtime /theme switch.
+ * @param name - Candidate theme name.
+ * @returns True when the theme resolves.
+ */
+export declare function isThemeAvailable(name: string): boolean;
+/** Drop the resolved-theme cache and name index (tests, or after themes change on disk). */
+export declare function clearCustomThemeCache(): void;
+//# sourceMappingURL=customTheme.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"customTheme.d.ts","sourceRoot":"","sources":["../../src/customTheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAML,KAAK,KAAK,EACV,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AAGnB,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,yCAA0C,CAAA;AACvE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzD,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,QAA2B,CAAA;AAExD,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,IAAI,EAAE,SAAS,CAAA;IACf,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IACtB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAuCD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAUjE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,eAAe,GAAG,SAAS,CAwE7B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAyB,GAC7B,eAAe,GAAG,SAAS,CAQ7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAyB,GAAG,eAAe,EAAE,CAclF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,KAAK,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAWlE;AAcD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGtD;AAED,4FAA4F;AAC5F,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C"}