@deepseek-harness-tui/dsh-tui 0.8.0 → 0.8.2

package/lib/types/dsh-adapter/shortcuts.js

@@ -0,0 +1,340 @@
+/**
+ * Plugin keyboard shortcuts — pi's `pi.registerShortcut`. A plugin binds a
+ * combo (`ctrl+shift+p`, `alt+k`, …) to a handler; the chat screen matches
+ * combos against keypresses that survived every built-in binding and runs
+ * the handler, consuming the key.
+ *
+ * Precedence rule (same philosophy as the command list: a plugin shadows
+ * nothing built in):
+ *
+ * - Combos must carry ctrl or alt (meta) — bare letters are typing, and
+ *   bare Esc/arrows are navigation. Rejected at registration.
+ * - A RESERVED list (every combo the TUI itself binds globally or in the
+ *   prompt editor) is refused at registration with a warning. The list is
+ *   the enforcement of "locals win": collisions can never reach the matcher.
+ * - Overlays (pickers, dialogs, scenes, the session browser) own the
+ *   keyboard while open; shortcuts match only in the plain chat state.
+ *
+ * Handlers are fire-and-forget from the UI's point of view: async handlers
+ * are awaited but their rejection is caught and toasted — a throwing
+ * handler must never break the keyboard for everyone else.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+import { activationFiber, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+const NAMED_KEYS = {
+    enter: 'return',
+    return: 'return',
+    esc: 'escape',
+    escape: 'escape',
+    tab: 'tab',
+    backspace: 'backspace',
+    delete: 'delete',
+    up: 'upArrow',
+    down: 'downArrow',
+    left: 'leftArrow',
+    right: 'rightArrow',
+    home: 'home',
+    end: 'end',
+    pageup: 'pageUp',
+    pagedown: 'pageDown',
+};
+/**
+ * Combos the TUI owns, globally or inside the prompt editor (the editor's
+ * bindings are checked AFTER plugin shortcuts, so refusing them here is
+ * what keeps "locals win" true). Built-in handlers match a MODIFIER SUBSET
+ * (`isMod(key) && input === 'x'` — they never exclude an extra Shift), so
+ * the reserved check below refuses a plugin combo whose SHIFTLESS form is
+ * reserved: ctrl+shift+x would shadow Ctrl+X on terminals that report both
+ * as the same keypress (ConPTY does), and would be dead weight on terminals
+ * that don't.
+ */
+const RESERVED_COMBOS = new Set([
+    'ctrl+c', // interrupt / clear
+    'ctrl+d', // exit on empty input
+    'ctrl+t', // startup context panel
+    'ctrl+r', // history search
+    'ctrl+x', // external editor
+    'ctrl+o', // transcript mode toggle
+    'ctrl+l', // terminal redraw
+    'ctrl+e', // show all messages / line end
+    'ctrl+v', // paste
+    'ctrl+a', // line start
+    'ctrl+u', // kill line
+    'ctrl+k', // kill to end
+    'ctrl+w', // kill word
+    'ctrl+left', // word jump
+    'ctrl+right', // word jump
+    'ctrl+return', // newline (multi-line input)
+    'ctrl+shift+return', // shift+Enter newline (CSI 13;6u) — same editor binding
+    'alt+return', // newline fallback on terminals without shift reporting
+    'alt+up', // pull the last pending message back for editing
+    'escape', // pickers / interrupt / rewind double-tap
+    'tab', // command completion
+    'shift+tab', // session-mode cycle
+]);
+/**
+ * Parse `ctrl+shift+p` style combos. Returns undefined on anything
+ * malformed or disallowed (no modifier, unknown key name); `allowReserved`
+ * is exposed for tests only.
+ */
+export function parseShortcutCombo(raw) {
+    const parts = String(raw ?? '')
+        .toLowerCase()
+        .split('+')
+        .map(part => part.trim())
+        .filter(part => part !== '');
+    if (parts.length === 0)
+        return undefined;
+    let ctrl = false;
+    let meta = false;
+    let shift = false;
+    let named;
+    let char;
+    for (const part of parts) {
+        if (part === 'ctrl' || part === 'control') {
+            if (ctrl)
+                return undefined;
+            ctrl = true;
+        }
+        else if (part === 'alt' || part === 'meta' || part === 'option') {
+            if (meta)
+                return undefined;
+            meta = true;
+        }
+        else if (part === 'shift') {
+            if (shift)
+                return undefined;
+            shift = true;
+        }
+        else if (part === 'space') {
+            if (char !== undefined || named !== undefined)
+                return undefined;
+            char = ' ';
+        }
+        else if (part in NAMED_KEYS) {
+            if (char !== undefined || named !== undefined)
+                return undefined;
+            named = NAMED_KEYS[part];
+        }
+        else if ([...part].length === 1) {
+            if (char !== undefined || named !== undefined)
+                return undefined;
+            char = part;
+        }
+        else {
+            return undefined;
+        }
+    }
+    if (char === undefined && named === undefined)
+        return undefined;
+    // Bare keys are typing/navigation; a modifier is what makes a shortcut.
+    if (!ctrl && !meta)
+        return undefined;
+    // Escape combos are refused outright: the input layer sets key.meta = true
+    // for EVERY Escape (ink/events/input-event.ts — `keypress.meta ||
+    // keypress.name === 'escape' || keypress.option`), so an alt+escape combo
+    // would match every bare Esc press and shadow clear-input / the double-Esc
+    // rewind. Esc is fully owned by the TUI; there is no unambiguous way to
+    // bind it.
+    if (named === 'escape')
+        return undefined;
+    return { raw: parts.join('+'), ctrl, meta, shift, ...(named === undefined ? {} : { named }), ...(char === undefined ? {} : { char }) };
+}
+/** Canonical form for dedupe/reserved checks: modifiers sorted, key last. */
+function comboKey(combo) {
+    const mods = [combo.ctrl ? 'ctrl' : '', combo.meta ? 'alt' : '', combo.shift ? 'shift' : '']
+        .filter(part => part !== '')
+        .sort();
+    return [...mods, combo.named === undefined ? (combo.char ?? '') : String(combo.named)].join('+');
+}
+/** Reserved lookup accepts user-spelled combos too (`ctrl+c`). */
+function reservedKey(raw) {
+    const combo = parseShortcutCombo(raw);
+    return combo === undefined ? raw.toLowerCase() : comboKey(combo);
+}
+const RESERVED_CANONICAL = new Set([...RESERVED_COMBOS].map(reservedKey));
+/** Match a keypress against a parsed combo. `input` is ink's input string
+ *  (already the resolved character; ctrl+space arrives as ' '). */
+export function matchShortcut(combo, input, key) {
+    if (Boolean(key.ctrl) !== combo.ctrl)
+        return false;
+    // ink reports Alt as meta; Esc itself also sets meta, which is why the
+    // modifier check runs against the combo, not a bare flag read.
+    if (Boolean(key.meta) !== combo.meta)
+        return false;
+    if (key.super)
+        return false;
+    // Shift must match for NAMED keys exactly as for characters — otherwise a
+    // registered ctrl+shift+enter would also match a plain ctrl+enter press,
+    // letting a plugin shadow the editor's built-in Ctrl+Enter delivery.
+    if (Boolean(key.shift) !== combo.shift)
+        return false;
+    if (combo.named !== undefined) {
+        return key[combo.named] === true;
+    }
+    if (combo.char === undefined)
+        return false;
+    // Shift+letter arrives as the uppercase character; compare case-folded
+    // (the shift FLAG equality above already pinned the modifier state).
+    return input.toLowerCase() === combo.char;
+}
+/** `ctx.tuiShortcuts` — plugin keyboard shortcut registry. */
+export class TuiShortcutRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiShortcuts');
+        compositionRoot(ctx);
+        const runtime = this;
+        const state = {
+            shortcuts: new Map(),
+            owners: new Map(),
+            onError: undefined,
+            host: undefined,
+            logger: ctx.logger,
+        };
+        const host = Object.freeze({
+            dispatch: (input, key) => dispatchShortcut(runtime, input, key),
+            setErrorHandler: (handler) => {
+                state.onError = handler;
+                return () => {
+                    if (state.onError === handler)
+                        state.onError = undefined;
+                };
+            },
+        });
+        state.host = host;
+        hostShortcuts.set(runtime, state);
+    }
+    /**
+     * Bind `combo` to `handler`. Invalid, modifier-less, reserved, or
+     * duplicate combos are refused with a logger warning rather than a throw
+     * — a bad binding must not fail the plugin's whole boot.
+     *
+     * Returns the dispose function; the CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as `tuiScenes`
+     * registration. (A service method only sees the service's own ctx, so
+     * caller-fiber cleanup cannot happen here.)
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared` (C-060).
+     */
+    register(combo, options, identity) {
+        let caller;
+        try {
+            caller = requirePluginCaller(this.ctx, 'tuiShortcuts.register', this);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiShortcuts.register requires a live non-root plugin activation');
+            return () => { };
+        }
+        const state = shortcutStateFor(this);
+        const owner = activationFiber(caller);
+        if (owner === undefined) {
+            this.ctx.logger.warn('dsh-tui: tuiShortcuts.register requires a live activation');
+            return () => { };
+        }
+        let parsed;
+        try {
+            parsed = parseShortcutCombo(combo);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiShortcuts.register rejected an uncoercible combo');
+            return () => { };
+        }
+        if (parsed === undefined) {
+            this.ctx.logger.warn('dsh-tui: tuiShortcuts.register rejected an invalid combo — need ctrl/alt plus one key (e.g. "ctrl+shift+p")');
+            return () => { };
+        }
+        const key = comboKey(parsed);
+        // Built-ins match a modifier subset (see RESERVED_COMBOS): a combo whose
+        // SHIFTLESS form is reserved collides with the built-in on terminals that
+        // don't report Shift distinctly, so it is refused too. The exact form is
+        // still checked for combos reserved WITH shift (ctrl+shift+return).
+        const shiftlessKey = comboKey({ ...parsed, shift: false });
+        if (RESERVED_CANONICAL.has(key) || RESERVED_CANONICAL.has(shiftlessKey)) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${parsed.raw}" — reserved by a built-in binding`);
+            return () => { };
+        }
+        if (state.shortcuts.has(key)) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${parsed.raw}" — already registered`);
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'bind',
+                resource: { kind: 'shortcut', id: key },
+                result: 'failed',
+                errorCode: 'DUPLICATE_CONTRIBUTION_ID',
+            }, identity);
+            return () => { };
+        }
+        let description;
+        let handler;
+        try {
+            description = cleanScalarText(options?.description, 120);
+            handler = options?.handler;
+        }
+        catch {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${parsed.raw}" — malformed options`);
+            return () => { };
+        }
+        if (typeof handler !== 'function' || description === '') {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${parsed.raw}" — needs a description and a handler`);
+            return () => { };
+        }
+        const entry = { combo: parsed, description, handler };
+        state.shortcuts.set(key, entry);
+        state.owners.set(key, owner);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'shortcut', id: key }, result: 'applied' }, identity);
+        const dispose = () => {
+            if (state.shortcuts.get(key) !== entry)
+                return;
+            state.shortcuts.delete(key);
+            state.owners.delete(key);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'shortcut', id: key }, result: 'applied' }, identity);
+        };
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+    /** Registered combos with descriptions (diagnostics / future /help). */
+    list() {
+        const caller = requirePluginCaller(this.ctx, 'tuiShortcuts.list', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return [];
+        const state = shortcutStateFor(this);
+        return [...state.shortcuts.entries()]
+            .filter(([key]) => state.owners.get(key) === owner)
+            .map(([, entry]) => ({ combo: entry.combo.raw, description: entry.description }));
+    }
+}
+const hostShortcuts = new WeakMap();
+function shortcutStateFor(runtime) {
+    const state = hostShortcuts.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiShortcuts host state is unavailable');
+    return state;
+}
+function dispatchShortcut(runtime, input, key) {
+    const state = shortcutStateFor(runtime);
+    for (const entry of state.shortcuts.values()) {
+        if (!matchShortcut(entry.combo, input, key))
+            continue;
+        Promise.resolve()
+            .then(() => entry.handler())
+            .catch((error) => {
+            state.onError?.(entry.combo.raw, error);
+            state.logger.warn(`dsh-tui: shortcut "${entry.combo.raw}" handler failed: %o`, error);
+        });
+        return true;
+    }
+    return false;
+}
+export function getHostShortcuts(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return hostShortcuts.get(concreteService(runtime))?.host;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiShortcutRuntime;

package/lib/types/dsh-adapter/status.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Keyed status-line contributions — pi's `ctx.ui.setStatus(key, text)`.
+ * Each plugin owns a key; setting text shows it, setting undefined clears
+ * it. The TUI renders all contributions as one joined line above the prompt
+ * (host-owned rendering: plugins supply text, never layout).
+ *
+ * Same split as the dialogs seam: a cordis-free store the chat screen
+ * subscribes to, and a thin cordis service validating untrusted text.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** One rendered contribution. */
+export interface TuiStatusEntry {
+    readonly key: string;
+    readonly text: string;
+}
+/** Cordis-free keyed-text store. Render order is first-set order (Map
+ *  insertion order), so a plugin's line never jumps around on updates. */
+export declare class TuiStatusStore {
+    private readonly listeners;
+    private readonly entries;
+    private snapshot;
+    /** Set or clear (undefined/empty) one key. */
+    set(key: string, text: string | undefined, token?: number, owner?: object): void;
+    /** Current contributions, first-set first (stable between changes). */
+    getSnapshot(): readonly TuiStatusEntry[];
+    /** Host runtime uses this to enforce that one activation cannot rewrite or
+     * clear another activation's keyed contribution. */
+    ownerOf(key: string): object | undefined;
+    /** Clear `key` only while it still holds the write tagged `token` — a
+     *  stale disposer must not wipe a newer contribution (even one with
+     *  identical text). Returns true when this call actually cleared. */
+    clearIf(key: string, token: number, owner?: object): boolean;
+    /** Drop everything (teardown). */
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    private emit;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiStatus: TuiStatusRuntime;
+    }
+}
+/**
+ * `ctx.tuiStatus` — plugin-facing status contributions. Invalid keys and
+ * oversized text are rejected with a logger warning instead of throwing:
+ * a status line must never take the TUI down.
+ */
+export declare class TuiStatusRuntime extends Service {
+    constructor(ctx: Context);
+    /**
+     * Set (or clear with `undefined`) the contribution for `key`. Keys are
+     * plugin-namespaced by convention (`my-plugin`, `my-plugin:detail`);
+     * control chars are stripped and text is capped at 200 cells. Text is
+     * scalar-only: string/number/boolean are coerced to string, anything else
+     * is refused with a warning (never rendered as "[object Object]", never
+     * silently treated as a clear).
+     *
+     * Returns a disposer that clears the contribution IF the key still holds
+     * exactly this write (a later set — even of identical text — wins over a
+     * stale disposer). The CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as
+     * `tuiShortcuts`/`tuiScenes`: a service method only sees the service's own
+     * ctx, so per-plugin cleanup cannot happen here. Without that, an unloaded
+     * or hot-reloaded plugin would leave its line behind forever.
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared`, never a
+     * guess (C-060 honest identity).
+     */
+    set(key: string, text: string | number | boolean | undefined, identity?: Context): () => void;
+}
+export declare function getHostStatusStore(runtime: TuiStatusRuntime | undefined): TuiStatusStore | undefined;
+export default TuiStatusRuntime;
+//# sourceMappingURL=status.d.ts.map

package/lib/types/dsh-adapter/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKtD,iCAAiC;AACjC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AASD;0EAC0E;AAC1E,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAKlD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoE;IAG5F,OAAO,CAAC,QAAQ,CAAgC;IAEhD,8CAA8C;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,SAAI,EAAE,KAAK,GAAE,MAA0B,GAAG,IAAI;IAmB9F,uEAAuE;IACvE,WAAW,IAAI,SAAS,cAAc,EAAE;IAIxC;wDACoD;IACpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC;;yEAEqE;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO;IAS5D,kCAAkC;IAClC,KAAK,IAAI,IAAI;IAOb,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C,OAAO,CAAC,IAAI;CAGb;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,SAAS,EAAE,gBAAgB,CAAA;KAC5B;CACF;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,OAAO;gBAC/B,GAAG,EAAE,OAAO;IAUxB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;CAwF9F;AAgBD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAOpG;AAED,eAAe,gBAAgB,CAAA"}

package/lib/types/dsh-adapter/status.js

@@ -0,0 +1,234 @@
+/**
+ * Keyed status-line contributions — pi's `ctx.ui.setStatus(key, text)`.
+ * Each plugin owns a key; setting text shows it, setting undefined clears
+ * it. The TUI renders all contributions as one joined line above the prompt
+ * (host-owned rendering: plugins supply text, never layout).
+ *
+ * Same split as the dialogs seam: a cordis-free store the chat screen
+ * subscribes to, and a thin cordis service validating untrusted text.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { cleanScalarText } from './sanitize.js';
+import { activationFiber, assertCallerContext, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { componentIdentityOf } from './component-identity.js';
+// Colon-separated segments are the documented namespacing convention
+// (`plugin:sub-item`); each segment stays a lowercase slug.
+const KEY_PATTERN = /^[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)*$/u;
+const TEXT_CELLS = 200;
+const MAX_ENTRIES = 20;
+const HOST_STATUS_OWNER = Object.freeze({ kind: 'host-status-owner' });
+/** Cordis-free keyed-text store. Render order is first-set order (Map
+ *  insertion order), so a plugin's line never jumps around on updates. */
+export class TuiStatusStore {
+    listeners = new Set();
+    // Each write carries a token: a disposer compares TOKENS, not text —
+    // value comparison has an ABA hole (set 'x', set 'x' again, the first
+    // disposer would wipe the second write, e.g. a hot reload restoring the
+    // same status text).
+    entries = new Map();
+    // useSyncExternalStore requires a referentially stable snapshot between
+    // emits — a fresh array per call would re-render in an infinite loop.
+    snapshot = [];
+    /** Set or clear (undefined/empty) one key. */
+    set(key, text, token = 0, owner = HOST_STATUS_OWNER) {
+        const had = this.entries.has(key);
+        if (text === undefined || text === '') {
+            if (!had)
+                return;
+            this.entries.delete(key);
+        }
+        else {
+            const existing = this.entries.get(key);
+            if (existing?.text === text) {
+                // Same text, new write: adopt the new token so the newest disposer
+                // is the one that owns the line (no re-emit — nothing visible changed).
+                existing.token = token;
+                return;
+            }
+            this.entries.set(key, { text, token, owner });
+        }
+        this.snapshot = [...this.entries].map(([entryKey, entry]) => ({ key: entryKey, text: entry.text }));
+        this.emit();
+    }
+    /** Current contributions, first-set first (stable between changes). */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    /** Host runtime uses this to enforce that one activation cannot rewrite or
+     * clear another activation's keyed contribution. */
+    ownerOf(key) {
+        return this.entries.get(key)?.owner;
+    }
+    /** Clear `key` only while it still holds the write tagged `token` — a
+     *  stale disposer must not wipe a newer contribution (even one with
+     *  identical text). Returns true when this call actually cleared. */
+    clearIf(key, token, owner) {
+        if (owner !== undefined && this.entries.get(key)?.owner !== owner)
+            return false;
+        if (this.entries.get(key)?.token !== token)
+            return false;
+        this.entries.delete(key);
+        this.snapshot = [...this.entries].map(([entryKey, entry]) => ({ key: entryKey, text: entry.text }));
+        this.emit();
+        return true;
+    }
+    /** Drop everything (teardown). */
+    clear() {
+        if (this.entries.size === 0)
+            return;
+        this.entries.clear();
+        this.snapshot = [];
+        this.emit();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/**
+ * `ctx.tuiStatus` — plugin-facing status contributions. Invalid keys and
+ * oversized text are rejected with a logger warning instead of throwing:
+ * a status line must never take the TUI down.
+ */
+export class TuiStatusRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiStatus');
+        compositionRoot(ctx);
+        // Keep host state out of the traceable service object. A WeakMap also
+        // works with Cordis's caller-bound method proxy (unlike `#private`).
+        const state = { store: new TuiStatusStore(), nextToken: 1 };
+        hostStatusStores.set(this, state);
+        ctx.effect(() => () => state.store.clear());
+    }
+    /**
+     * Set (or clear with `undefined`) the contribution for `key`. Keys are
+     * plugin-namespaced by convention (`my-plugin`, `my-plugin:detail`);
+     * control chars are stripped and text is capped at 200 cells. Text is
+     * scalar-only: string/number/boolean are coerced to string, anything else
+     * is refused with a warning (never rendered as "[object Object]", never
+     * silently treated as a clear).
+     *
+     * Returns a disposer that clears the contribution IF the key still holds
+     * exactly this write (a later set — even of identical text — wins over a
+     * stale disposer). The CALLER scopes it to its own fiber
+     * (`ctx.effect(() => dispose)`) — the same contract as
+     * `tuiShortcuts`/`tuiScenes`: a service method only sees the service's own
+     * ctx, so per-plugin cleanup cannot happen here. Without that, an unloaded
+     * or hot-reloaded plugin would leave its line behind forever.
+     *
+     * The optional trailing `identity` (the plugin's own ctx) only feeds the
+     * effect ledger's pluginId — omitting it records `undeclared`, never a
+     * guess (C-060 honest identity).
+     */
+    set(key, text, identity) {
+        const noop = () => { };
+        let caller;
+        try {
+            caller = requirePluginCaller(this.ctx, 'tuiStatus.set', this);
+        }
+        catch {
+            this.ctx.logger.warn('dsh-tui: tuiStatus.set requires a live non-root plugin activation');
+            return noop;
+        }
+        const state = statusStateFor(this);
+        const store = state.store;
+        const callerIdentity = componentIdentityOf(caller);
+        const suppliedIdentity = identity === undefined ? callerIdentity : componentIdentityOf(identity);
+        if (identity !== undefined) {
+            try {
+                assertCallerContext(caller, identity, 'tuiStatus.set');
+            }
+            catch {
+                caller.logger.warn('dsh-tui: tuiStatus.set rejected an identity belonging to another activation');
+                return noop;
+            }
+        }
+        const owner = activationFiber(caller);
+        if (owner === undefined) {
+            caller.logger.warn('dsh-tui: tuiStatus.set requires a live activation owner');
+            return noop;
+        }
+        let normalized;
+        try {
+            normalized = String(key ?? '').trim().toLowerCase();
+        }
+        catch {
+            caller.logger.warn('dsh-tui: tuiStatus.set rejected an uncoercible key');
+            return noop;
+        }
+        if (!KEY_PATTERN.test(normalized)) {
+            caller.logger.warn('dsh-tui: tuiStatus.set rejected an invalid key');
+            return noop;
+        }
+        if (text !== undefined && !store.getSnapshot().some(e => e.key === normalized)) {
+            // New key beyond the cap: the line is one row of terminal — an
+            // unbounded count would push the prompt off screen.
+            if (store.getSnapshot().length >= MAX_ENTRIES) {
+                caller.logger.warn(`dsh-tui: tuiStatus.set rejected "${normalized}": ${MAX_ENTRIES} contributions already shown`);
+                return noop;
+            }
+        }
+        let cleaned;
+        if (text !== undefined) {
+            // Scalar-only coercion (Track A contract): a non-scalar text (an
+            // object would otherwise render as "[object Object]") is REFUSED with
+            // a warning — it must not silently become a clear, either.
+            if (typeof text !== 'string' && typeof text !== 'number' && typeof text !== 'boolean') {
+                caller.logger.warn(`dsh-tui: tuiStatus.set rejected non-scalar text for "${normalized}"`);
+                return noop;
+            }
+            cleaned = cleanScalarText(text, TEXT_CELLS);
+        }
+        const token = state.nextToken++;
+        const had = store.getSnapshot().some(entry => entry.key === normalized);
+        if (store.ownerOf(normalized) !== undefined && store.ownerOf(normalized) !== owner) {
+            caller.logger.warn(`dsh-tui: tuiStatus.set rejected "${normalized}" — the contribution belongs to another activation`);
+            return noop;
+        }
+        store.set(normalized, cleaned, token, owner);
+        const ledger = caller.get('tuiEffectLedger');
+        if (cleaned === undefined) {
+            if (had)
+                ledger?.record({ operation: 'release', resource: { kind: 'status', id: normalized }, result: 'applied' }, identity);
+        }
+        else {
+            ledger?.record({
+                operation: had ? 'replace' : 'bind',
+                resource: { kind: 'status', id: normalized },
+                result: 'applied',
+                ...(had ? { replaces: { resourceId: normalized } } : {}),
+            }, identity);
+        }
+        const dispose = () => {
+            if (store.clearIf(normalized, token, owner)) {
+                caller.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'status', id: normalized }, result: 'applied' }, identity);
+            }
+        };
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+}
+const hostStatusStores = new WeakMap();
+function statusStateFor(runtime) {
+    const store = hostStatusStores.get(concreteService(runtime));
+    if (store === undefined)
+        throw new Error('tuiStatus host store is unavailable');
+    return store;
+}
+export function getHostStatusStore(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return hostStatusStores.get(concreteService(runtime))?.store;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiStatusRuntime;