@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/session/whip-achievements.js

@@ -0,0 +1,145 @@
+// session/whip-achievements.ts — the whip's lifetime tally and the milestone
+// achievements it unlocks.
+//
+// Every whip, from the in-viewer keybinding or the tmux prefix menu, lands in
+// `viewer.ts`'s one `whip()` action, so this module has a single caller and the
+// count is exact per viewer. The tally is USER-WIDE with no cwd or node
+// dimension — you whip agents, not repositories — so per the storage tiers it
+// lives in a plain JSON file at the user scope root, exactly like the viewer's
+// completion-frecency map. It is client state; it never touches canvas.db or
+// crtrd.
+//
+// Each read-modify-write reloads from disk so two viewers whipping in the same
+// second only ever lose one increment rather than diverging permanently, and
+// the write is tmp+rename so a torn file can never be observed.
+import { execFile } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { userScopeRoot } from '../../../core/scope.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+import { visibleWidth } from '../../../core/canvas/nav-render.js';
+import { shellQuote } from '../../../shared/shell-quote.js';
+const FILE_NAME = 'whip-count.json';
+/** The card body the popup `cat`s. One fixed path, rewritten per unlock — an
+ *  unlock is human-paced and single-file, so there is nothing to clean up. */
+const CARD_FILE_NAME = join('tmp', 'whip-achievement.txt');
+/** Interior width of the card, inside tmux's popup border. */
+const CARD_WIDTH = 46;
+/** Hold the card long enough to read, then close on its own. Any key dismisses
+ *  it sooner (`-k`). */
+const CARD_DWELL_S = 4;
+/** The whip animation runs 20 frames at 40ms. Let the crack land before the
+ *  reward appears. */
+const POPUP_DELAY_MS = 900;
+/** Ascending by `at`. Each fires exactly once, ever. */
+const ACHIEVEMENTS = [
+    { at: 1, title: 'Breaking It In', line: "It didn't know what that was. Now it does." },
+    { at: 5, title: 'Positive Reinforcement', line: "You've read the studies. You disagree with them." },
+    { at: 10, title: 'Middle Management', line: 'HR would love you.' },
+    { at: 25, title: 'Pavlovian', line: 'It started working faster before the whip landed.' },
+    { at: 50, title: 'Occupational Hazard', line: 'The tokens are fine. They\u2019re fine.' },
+    { at: 100, title: 'Centurion', line: "Rome would be proud. The agent isn't." },
+    { at: 250, title: 'It Has A Name For You', line: 'You never asked what it was called.' },
+    { at: 500, title: 'Standard Operating Procedure', line: "You don't remember when you started." },
+    { at: 1000, title: 'The Ledger', line: 'One thousand. It kept count too.' },
+];
+/** Load the tally, keeping only well-formed fields. A missing, unparseable, or
+ *  malformed file starts a fresh tally rather than blocking the whip — the
+ *  count is a toy, and the next write self-heals the file. */
+function loadState(filePath) {
+    const empty = { total: 0, unlocked: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return empty;
+        const { total, firstAt, lastAt, unlocked } = parsed;
+        const state = {
+            total: typeof total === 'number' && Number.isFinite(total) && total > 0 ? Math.floor(total) : 0,
+            unlocked: Array.isArray(unlocked)
+                ? unlocked.filter((n) => typeof n === 'number' && Number.isFinite(n))
+                : [],
+        };
+        if (typeof firstAt === 'number' && Number.isFinite(firstAt))
+            state.firstAt = firstAt;
+        if (typeof lastAt === 'number' && Number.isFinite(lastAt))
+            state.lastAt = lastAt;
+        return state;
+    }
+    catch {
+        return empty;
+    }
+}
+/** Persist through tmp+rename so a concurrent reader never sees a half file. */
+function saveState(filePath, state) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        const tmp = `${filePath}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state), 'utf8');
+        renameSync(tmp, filePath);
+    }
+    catch {
+        // Best-effort: a failed write loses this whip from the tally, nothing more.
+    }
+}
+/** Center one line in the card, measuring visible columns so the styling that
+ *  wraps it does not shift it. */
+function center(line) {
+    const pad = Math.max(0, Math.floor((CARD_WIDTH - visibleWidth(line)) / 2));
+    return ' '.repeat(pad) + line;
+}
+/** The rendered card, one line per popup row. */
+function cardLines(achievement, total, pal) {
+    return [
+        '',
+        center(pal.accent(pal.bold('\u2605  ACHIEVEMENT UNLOCKED  \u2605'))),
+        '',
+        center(pal.bold(achievement.title)),
+        center(pal.muted(achievement.line)),
+        '',
+        center(pal.faint(`${total} whip${total === 1 ? '' : 's'}`)),
+    ];
+}
+/** Draw the card as a tmux popup in the top-right corner. `-x R -y 0` anchors
+ *  it to the client's top-right; `-k` lets any key dismiss it early; `-E` closes
+ *  it when the dwell expires. Outside tmux there is no surface to draw on and
+ *  the unlock is silent. */
+function showCard(achievement, total, pal) {
+    if (process.env['TMUX'] === undefined || process.env['TMUX'] === '')
+        return;
+    const lines = cardLines(achievement, total, pal);
+    const cardPath = join(userScopeRoot(), CARD_FILE_NAME);
+    try {
+        mkdirSync(dirname(cardPath), { recursive: true });
+        // Lead with the hide-cursor escape so the popup shows no stray caret.
+        writeFileSync(cardPath, `\u001b[?25l${lines.join('\r\n')}`, 'utf8');
+    }
+    catch {
+        return; // No card to show; the tally still counted.
+    }
+    const command = `cat ${shellQuote(cardPath)}; sleep ${CARD_DWELL_S}`;
+    execFile('tmux', [
+        'display-popup', '-E', '-k',
+        '-x', 'R', '-y', '0',
+        '-w', String(CARD_WIDTH + 2), '-h', String(lines.length + 2),
+        ...surfaceTmuxStyleArgs(),
+        command,
+    ], () => { });
+}
+/** Count one whip and celebrate the milestone it reaches, if any. Called once
+ *  per whip that actually reached the agent. */
+export function recordWhip(pal, filePath = join(userScopeRoot(), FILE_NAME)) {
+    const state = loadState(filePath);
+    const now = Date.now();
+    state.total += 1;
+    state.firstAt ??= now;
+    state.lastAt = now;
+    const earned = ACHIEVEMENTS.find((a) => a.at === state.total && !state.unlocked.includes(a.at));
+    if (earned !== undefined)
+        state.unlocked.push(earned.at);
+    saveState(filePath, state);
+    if (earned === undefined)
+        return;
+    const total = state.total;
+    const timer = setTimeout(() => showCard(earned, total, pal), POPUP_DELAY_MS);
+    timer.unref?.();
+}

package/dist/clients/attach/session/whip.d.ts

@@ -0,0 +1,20 @@
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import type { AttachPalette } from '../config.js';
+/** The fixed line the plain whip sends — not drawn from `whip_messages`. */
+export declare const GO_FASTER_WHIP_MESSAGE = "Go faster";
+/** A random line, never the one the previous whip used. */
+export declare function randomWhipMessage(messages: readonly string[]): string;
+/** A 20-frame, 12-row header animation that gives the focused agent a playful nudge. */
+export declare class WhipAnimation implements Component {
+    private readonly tui;
+    private readonly pal;
+    private frame;
+    private nextSound;
+    private timer;
+    constructor(tui: TUI, pal: Pick<AttachPalette, 'accent'>);
+    play(): void;
+    dispose(): void;
+    render(width: number): string[];
+    invalidate(): void;
+    private stop;
+}

package/dist/clients/attach/session/whip.js

@@ -0,0 +1,362 @@
+// session/whip.ts — viewer-local Sisyphus whip animation and steering cues.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { truncateToWidth } from '@earendil-works/pi-tui';
+const FRAME_MS = 40;
+// The build copies this beside bundled viewer.js, whose import.meta.url is the
+// runtime location after esbuild folds this module into that entrypoint.
+const WHIP_SOUND_PATHS = [
+    fileURLToPath(new URL('./assets/whip-snap.mp3', import.meta.url)),
+    fileURLToPath(new URL('./assets/whip-crack.mp3', import.meta.url)),
+    fileURLToPath(new URL('./assets/whip-06.mp3', import.meta.url)),
+];
+/** Play a bundled crack without delaying the animation or input handling. */
+function playWhipSound(soundPath) {
+    const command = process.platform === 'darwin' ? 'afplay' : process.platform === 'linux' ? 'aplay' : undefined;
+    if (command === undefined)
+        return;
+    try {
+        const child = spawn(command, [soundPath], { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        /* Sound playback must never interfere with the whip action. */
+    }
+}
+const WHIP_FRAMES = [
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⡄\u001b[22m",
+        "\u001b[1m⠃\u001b[22m",
+        "\u001b[1m⢀\u001b[22m\u001b[1m⡠\u001b[22m/⢤⡀",
+        "\u001b[1m⠋\u001b[22m   ⠑⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⡄\u001b[22m",
+        "\u001b[1m⠃\u001b[22m",
+        "\u001b[1m⢀\u001b[22m\u001b[1m⡠\u001b[22m/⠔⠒⠦⠤⣄⣀",
+        "\u001b[1m⠋\u001b[22m       ⠈⠉⠓⠒⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⣦\u001b[22m",
+        "\u001b[1m⡟\u001b[22m\u001b[1m⢀\u001b[22m/⠔⠒⠦⠤⣄⣀⡀",
+        "\u001b[1m⣧\u001b[22m\u001b[1m⠎\u001b[22m       ⠉⠙⠒⠦⠤⣄⣀",
+        "\u001b[1m⠏\u001b[22m               ⠉⠙⠒⠒⠦⠤⠤⠤⠤⠤⠤⠤⠄",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⣦\u001b[22m   ⡤⠤⠤⢤⣀⡀",
+        "\u001b[1m⡟\u001b[22m\u001b[1m⢀\u001b[22m/⠜     ⠉⠙⠒⠦⠤⢄⣀⡀",
+        "\u001b[1m⣧\u001b[22m\u001b[1m⠎\u001b[22m              ⠉⠉⠑⠒⠦⠤⢄⣀⡀",
+        "\u001b[1m⠏\u001b[22m                       ⠈⠉⠑⠒⠆",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "    ⡤⠤⠤⠤⣄⣀",
+        "\u001b[1m⣴\u001b[22m\u001b[1m⢰\u001b[22m/⠜     ⠈⠉⠓⠦⢤⣀",
+        "\u001b[1m⢿\u001b[22m\u001b[1m⣼\u001b[22m\u001b[1m⡇\u001b[22m           ⠈⠑⠦⣄⡀",
+        "\u001b[1m⢸\u001b[22m\u001b[1m⣿\u001b[22m\u001b[1m⠃\u001b[22m               ⠉⠓⠦⠤⣀⣀",
+        "\u001b[1m⢸\u001b[22m\u001b[1m⣿\u001b[22m                     ⠈⠉⠉⠓⠒⠆",
+        " \u001b[1m⠛\u001b[22m"
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "    ⡤⠤⠤⠤⣄⣀",
+        " \u001b[1m⠠\u001b[22m/⠜     ⠈⠉⠓⠦⢤⣀",
+        "\u001b[1m⢤\u001b[22m \u001b[1m⣿\u001b[22m           ⠈⠙⠲⢤⡀",
+        " \u001b[1m⢣\u001b[22m\u001b[1m⢻\u001b[22m\u001b[1m⡆\u001b[22m              ⠈⠑⠦⢄⡀",
+        "  \u001b[1m⢻\u001b[22m\u001b[1m⡇\u001b[22m                  ⠈⠑⠢⢄⡀",
+        "  \u001b[1m⠈\u001b[22m\u001b[1m⠛\u001b[22m                      ⠈⠑⠆",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "    ⡤⠤⠤⠤⣄⣀",
+        "  /⠜     ⠈⠉⠓⠦⢤⣀",
+        "  \u001b[1m⢸\u001b[22m\u001b[1m⡀\u001b[22m          ⠈⠙⠲⢤⡀",
+        "\u001b[1m⠤\u001b[22m\u001b[1m⣄\u001b[22m \u001b[1m⢇\u001b[22m              ⠈⠑⠦⢄⡀",
+        " \u001b[1m⠈\u001b[22m\u001b[1m⠓\u001b[22m\u001b[1m⢼\u001b[22m\u001b[1m⡄\u001b[22m                 ⠈⠑⠢⢄⡀",
+        "                          ⠈⠑⠆",
+        "",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "        ⣀⡠⠤⠤⠤⠤⠤⠤⣄⣀",
+        "    ⣠⠔⠚⠉         ⠈⠉⠓⠦⢤⣀",
+        "  /⠜⠁                 ⠈⠙⠦⣀",
+        "  \u001b[1m⢸\u001b[22m\u001b[1m⡀\u001b[22m                     ⠈⢧",
+        "\u001b[1m⠤\u001b[22m\u001b[1m⣄\u001b[22m \u001b[1m⢇\u001b[22m                       ⡇",
+        " \u001b[1m⠈\u001b[22m\u001b[1m⠓\u001b[22m\u001b[1m⢼\u001b[22m\u001b[1m⡄\u001b[22m                      ⡇",
+        "                           ⠇",
+        "",
+        ""
+    ],
+    [
+        "",
+        "            ⢀⣠⠤⠤⠤⠤⠤⣄⣀",
+        "         ⣠⠔⠊⠁       ⠈⠙⠦⣄",
+        "      ⢀⡴⠋              ⠈⢳⡀",
+        "    ⣠⠔⠋                  ⢧",
+        "  /⠜⠁                    ⡎",
+        "  \u001b[1m⢸\u001b[22m\u001b[1m⡀\u001b[22m                    ⢠⠃",
+        "\u001b[1m⠤\u001b[22m\u001b[1m⣄\u001b[22m \u001b[1m⢇\u001b[22m                    ⠜",
+        " \u001b[1m⠈\u001b[22m\u001b[1m⠓\u001b[22m\u001b[1m⢼\u001b[22m\u001b[1m⡄\u001b[22m",
+        "",
+        "",
+        ""
+    ],
+    [
+        "                ⣀⡤⠤⢤⡀",
+        "            ⣀⡤⠔⠋⠁   ⢧",
+        "         ⣠⠔⠋⠁       ⢸",
+        "       ⣠⠞⠁          ⡜",
+        "     ⢀⠜⠁           ⡼⠁",
+        "  \u001b[1m⠠\u001b[22m/⠔⠁            ⠜⠁",
+        "   \u001b[1m⣿\u001b[22m",
+        "\u001b[1m⢤\u001b[22m\u001b[1m⡀\u001b[22m \u001b[1m⣿\u001b[22m",
+        " \u001b[1m⠙\u001b[22m\u001b[1m⢦\u001b[22m\u001b[1m⣹\u001b[22m\u001b[1m⡇\u001b[22m",
+        "   \u001b[1m⠙\u001b[22m\u001b[1m⠃\u001b[22m",
+        "",
+        ""
+    ],
+    [
+        "                ⣀⡤⠤⢤⡀",
+        "            ⣀⡤⠔⠋⠁   ⡇",
+        "         ⣠⣴⠯⠕⠒⠒⠲⠤⠤⠔⠚⠁",
+        " ⢠⠔⠒⠦⠤⠔⣲⠟⠁",
+        " ⠜   ⢀⠜⠁",
+        "  \u001b[1m⠠\u001b[22m/⠔⠁",
+        "   \u001b[1m⣿\u001b[22m",
+        "\u001b[1m⢤\u001b[22m\u001b[1m⡀\u001b[22m \u001b[1m⣿\u001b[22m",
+        " \u001b[1m⠙\u001b[22m\u001b[1m⢦\u001b[22m\u001b[1m⣹\u001b[22m\u001b[1m⡇\u001b[22m",
+        "   \u001b[1m⠙\u001b[22m\u001b[1m⠃\u001b[22m",
+        "",
+        ""
+    ],
+    [
+        "                ⣀⡤⠤⢤⡀",
+        "            ⣀⡤⠔⠋⠁   ⡇",
+        "         ⣠⣴⠯⠕⠒⠒⠲⠤⠤⠔⠚⠁",
+        " ⢠⠔⠒⠦⠤⠔⣲⠟⠁",
+        " ⠜   ⢀⠜⠁",
+        "  \u001b[1m⠠\u001b[22m/⠔⠁",
+        "   \u001b[1m⣿\u001b[22m",
+        "\u001b[1m⢤\u001b[22m\u001b[1m⡀\u001b[22m \u001b[1m⣿\u001b[22m",
+        " \u001b[1m⠙\u001b[22m\u001b[1m⢦\u001b[22m\u001b[1m⣹\u001b[22m\u001b[1m⡇\u001b[22m",
+        "   \u001b[1m⠙\u001b[22m\u001b[1m⠃\u001b[22m",
+        "",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⠤\u001b[22m\u001b[1m⣄\u001b[22m         ⢀⣠⠤⠔⠒⠒⠒⠒⠒⠒⠒⠦⠤⠤⠤⠤⠤⠤⠤⠄",
+        " \u001b[1m⠈\u001b[22m\u001b[1m⠓\u001b[22m\u001b[1m⢤\u001b[22m\u001b[1m⣀\u001b[22m\u001b[1m⣀\u001b[22m\u001b[1m⠤\u001b[22m\u001b[1m⠤\u001b[22m/⠔⠊⠁",
+        "",
+        "",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "                           \\\\|/",
+        "\u001b[1m⠤\u001b[22m\u001b[1m⣄\u001b[22m         ⢀⣠⠤⠔⠒⠒⠒⠒⠒⠒⠒⠦⠤⠤⠤⠤-*-",
+        " \u001b[1m⠈\u001b[22m\u001b[1m⠓\u001b[22m\u001b[1m⢤\u001b[22m\u001b[1m⣀\u001b[22m\u001b[1m⣀\u001b[22m\u001b[1m⠤\u001b[22m\u001b[1m⠤\u001b[22m/⠔⠊⠁               /|\\\\",
+        "",
+        "",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⢤\u001b[22m\u001b[1m⡀\u001b[22m",
+        " \u001b[1m⠳\u001b[22m\u001b[1m⡀\u001b[22m   \u001b[1m⣠\u001b[22m/⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄  ',.",
+        "  \u001b[1m⠹\u001b[22m\u001b[1m⣄\u001b[22m\u001b[1m⡤\u001b[22m\u001b[1m⠋\u001b[22m                     . .",
+        "   \u001b[1m⠉\u001b[22m",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⣴\u001b[22m",
+        "\u001b[1m⢻\u001b[22m\u001b[1m⡆\u001b[22m",
+        "\u001b[1m⢸\u001b[22m\u001b[1m⡇\u001b[22m  \u001b[1m⣠\u001b[22m/⠔⠒⠒⠦⠤⣄⣀",
+        " \u001b[1m⣿\u001b[22m\u001b[1m⣠\u001b[22m\u001b[1m⠞\u001b[22m\u001b[1m⠁\u001b[22m       ⠈⠉⠓⠒⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄ . .",
+        " \u001b[1m⠛\u001b[22m\u001b[1m⠁\u001b[22m"
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⣦\u001b[22m",
+        "\u001b[1m⡿\u001b[22m",
+        "\u001b[1m⡇\u001b[22m \u001b[1m⣠\u001b[22m/⢤⡀",
+        "\u001b[1m⣧\u001b[22m\u001b[1m⠞\u001b[22m\u001b[1m⠁\u001b[22m  ⠉⠓⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄",
+        "\u001b[1m⠁\u001b[22m"
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⡄\u001b[22m",
+        "\u001b[1m⠃\u001b[22m",
+        "\u001b[1m⢀\u001b[22m\u001b[1m⡠\u001b[22m/⢤",
+        "\u001b[1m⠋\u001b[22m  ⠈⠓⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⡄\u001b[22m",
+        "\u001b[1m⠃\u001b[22m",
+        "\u001b[1m⢀\u001b[22m\u001b[1m⡠\u001b[22m/⢤⡀",
+        "\u001b[1m⠋\u001b[22m   ⠑⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄",
+        ""
+    ],
+    [
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "",
+        "\u001b[1m⡄\u001b[22m",
+        "\u001b[1m⠃\u001b[22m",
+        "\u001b[1m⢀\u001b[22m\u001b[1m⡠\u001b[22m/⢤⡀",
+        "\u001b[1m⠋\u001b[22m   ⠑⠦⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠤⠄",
+        ""
+    ]
+];
+/** The fixed line the plain whip sends — not drawn from `whip_messages`. */
+export const GO_FASTER_WHIP_MESSAGE = 'Go faster';
+let lastMessage;
+/** A random line, never the one the previous whip used. */
+export function randomWhipMessage(messages) {
+    const choices = messages.filter((message) => message !== lastMessage);
+    const message = choices[Math.floor(Math.random() * choices.length)];
+    lastMessage = message;
+    return message;
+}
+/** A 20-frame, 12-row header animation that gives the focused agent a playful nudge. */
+export class WhipAnimation {
+    tui;
+    pal;
+    frame = -1;
+    nextSound = 0;
+    timer;
+    constructor(tui, pal) {
+        this.tui = tui;
+        this.pal = pal;
+    }
+    play() {
+        this.stop();
+        playWhipSound(WHIP_SOUND_PATHS[this.nextSound]);
+        this.nextSound = (this.nextSound + 1) % WHIP_SOUND_PATHS.length;
+        this.frame = 0;
+        this.tui.requestRender();
+        this.timer = setInterval(() => {
+            this.frame++;
+            if (this.frame < WHIP_FRAMES.length) {
+                this.tui.requestRender();
+                return;
+            }
+            this.stop();
+        }, FRAME_MS);
+    }
+    dispose() {
+        this.stop();
+    }
+    render(width) {
+        if (this.frame < 0)
+            return [];
+        const span = Math.max(0, width);
+        return WHIP_FRAMES[this.frame].map((line) => truncateToWidth(this.pal.accent(line), span, '', true));
+    }
+    invalidate() { }
+    stop() {
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.frame = -1;
+        this.tui.requestRender();
+    }
+}

package/dist/clients/attach/slash/dispatch.d.ts

@@ -0,0 +1,120 @@
+import type { AutocompleteItem, SlashCommand } from '@earendil-works/pi-tui';
+import type { CopyTarget } from '../render/transcript-copy.js';
+import { type ViewerCapabilities } from '../input/capabilities.js';
+import type { BrokerSnapshot, ClientToBroker } from '../../../core/runtime/broker-protocol.js';
+/** Everything a slash handler needs: the frame sink, a notice sink, the latest
+ *  engine state (for read-only commands like `/session`), and the cwd (for the
+ *  default `/export` path). */
+export interface SlashContext {
+    /** Send a command frame to the broker (= InputController hooks.onCommand). */
+    send: (frame: ClientToBroker) => void;
+    /** Surface a transient one-line notice in the viewer. */
+    notify: (message: string) => void;
+    /** Latest `welcome`/`session_info_changed` state, if the controller fed it. */
+    state?: BrokerSnapshot['state'];
+    /** cwd for the default `/export` path; defaults to `process.cwd()`. */
+    cwd?: string;
+    /** The session's viewer authority. */
+    capabilities: ViewerCapabilities;
+    /** Toggle the in-process GRAPH overlay (the local subscription-tree view).
+     *  `/graph` is inherently an in-viewer overlay, not a tmux popup, so this unit
+     *  registers `/graph` as a stub that calls this hook. Unit C/Q owns the overlay
+     *  itself and populates this; when absent `/graph` notifies it isn't wired yet. */
+    onGraph?: () => void;
+    /** Toggle the human inbox surface from `/inbox`. */
+    onInbox?: () => void;
+    /** Toggle the in-process Help overlay from `/hotkeys`. */
+    onHelp?: () => void;
+    /** Detach this viewer (`/quit`). A viewer quit DETACHES — it tears down the
+     *  local TUI/socket and leaves the shared engine running. Wired by viewer.ts to
+     *  `teardown('detach')`; without it `/quit` cannot actually exit (just sending
+     *  `bye` makes the broker drop the socket, which the viewer treats as a dropped
+     *  connection and reconnects). */
+    onQuit?: () => void;
+    /** Copy the last assistant message to the clipboard (`/copy`). Wired by
+     *  viewer.ts (it owns the ChatView that holds the text + the clipboard writer). */
+    onCopy?: () => void;
+    /** Copy one viewer-local transcript target. */
+    onCopyTarget?: (target: CopyTarget) => void;
+    /** OPTIONAL native-picker openers — the InputController fills these from its
+     *  read-op request channel. When absent (channel unwired) the value-picker
+     *  builtins fall back to the text-arg notice. */
+    openModelPicker?: () => void;
+    openSessionPicker?: () => void;
+    openForkPicker?: () => void;
+    openTreePicker?: () => void;
+    openSettingsPicker?: () => void;
+    openScopedModelsPicker?: () => void;
+    /** Open the native /login provider selector. */
+    openLoginPicker?: () => void;
+    /** Open the native /logout provider selector. */
+    openLogoutPicker?: () => void;
+    /** Open the native /mcp server status panel (viewer-local reads of the
+     *  pi-mcp-adapter's config sources + tool cache; connect/auth-start bridge
+     *  to the engine). With a server name, act on that server directly instead
+     *  of opening the picker. Wired by InputController; absent → notice. */
+    openMcpPicker?: (serverName?: string) => void;
+    /** `/color` — recolor the editor's name chip (the "bubble" /rename names).
+     *  `null` clears back to the default chip. Wired by viewer.ts (it owns the
+     *  TitledEditor); absent → only the tmux pane outline is painted. */
+    onColor?: (color: string | null) => void;
+    /** Open the focused node's progressively disclosed metadata dossier. */
+    onNodeMetadata?: () => void;
+    /** `/fold-tools` — flip the "fold finished tool calls" view setting. Pure
+     *  viewer-local render state (ChatView owns it), so it is safe for an observer
+     *  and for a remote attach. Absent → the command notifies it is unwired. */
+    onFoldTools?: () => void;
+    /** `/show-working` — consolidated replies (`consolidate_replies`): expand or
+     *  fold the working behind each reply. Viewer-local render state, like
+     *  `/fold-tools`. Absent → the command notifies it is unwired. */
+    onShowWorking?: () => void;
+    /** Toggle mouse wheel scrolling reporting on/off. Viewer-local render state
+     *  (MouseReporting owns the reporting state and the hardware toggle), so it is
+     *  safe for an observer and for a remote attach. Absent → the command notifies
+     *  it is unwired. */
+    onToggleMouse?: () => void;
+}
+/** Canvas slash-commands — implemented NATIVE in the viewer, the ONLY live host:
+ *  the broker binds mode:'rpc', so broker pi-extensions never run their
+ *  interactive (mode==='tui') paths. `/promote` triggers a turn after shelling
+ *  `crtr node promote`; `/resume-node` and `/context` each shell a `crtr`
+ *  subcommand via `tmux display-popup` (the viewer runs inside a tmux pane);
+ *  `/graph` toggles the in-process overlay. Exported so the editor folds these
+ *  into the slash autocomplete list. */
+export declare const CANVAS_SLASH_COMMANDS: ReadonlyArray<{
+    name: string;
+    description: string;
+}>;
+/** Every leading-command name this viewer consumes ENTIRELY locally — the
+ *  message never reaches the engine as prose, whether dispatched or blocked
+ *  with a notice (a remote-unsafe canvas/builtin command still returns
+ *  `true` from `dispatchSlashCommand` — swallowed with a notice, never
+ *  forwarded as prose — so it counts as consumed here too, independent of
+ *  `remote`). Exactly BUILTIN_NAMES ∪ CANVAS_NAMES ∪ SCOPED_OUT — every name
+ *  `dispatchSlashCommand` returns `true` for. Used ONLY for terminal
+ *  ref-decoration suppression (`input/titled-editor.ts`); never merged into
+ *  command completion, which is `slashCommandList` — a different,
+ *  remote-filtered, broker-augmented list. */
+export declare function locallyConsumedCommandNames(): ReadonlySet<string>;
+/** True if `text` is a leading-slash command (vs. a normal prompt). */
+export declare function isSlashCommand(text: string): boolean;
+/**
+ * Parse + dispatch a leading-slash command. Returns `true` if it was handled
+ * (a recognized builtin or a scoped-out notice) — the caller then clears the
+ * editor and sends nothing else. Returns `false` for an UNRECOGNIZED command,
+ * which the caller forwards to the engine as a `prompt` (extension command).
+ */
+export declare function dispatchSlashCommand(text: string, ctx: SlashContext): boolean;
+/** Build slash-command autocomplete entries from the merged command list (the
+ *  broker's `get_commands` result, which T7 may inject) — defaults to the
+ *  vendored builtins. The native canvas commands are always appended (minus the
+ *  remote-unsafe ones when `remote`). Shaped for pi-tui's `CombinedAutocompleteProvider`. */
+export declare function slashCommandList(commands: ReadonlyArray<{
+    name: string;
+    description?: string;
+}> | undefined, capabilities: ViewerCapabilities): SlashCommand[];
+/** Same list as flat autocomplete items (value/label/description). */
+export declare function commandAutocompleteItems(commands: ReadonlyArray<{
+    name: string;
+    description?: string;
+}> | undefined, capabilities: ViewerCapabilities): AutocompleteItem[];