@deepseek-harness-tui/dsh-tui 0.7.3 → 0.8.1

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

@@ -0,0 +1,244 @@
+/**
+ * React-free form model behind the `/settings` screen (issue #165), mirroring
+ * the web front door's card-form.ts semantics: a section stages what the user
+ * types and writes it only on save — every settings write is a durable,
+ * revision-fenced `settings.mutate`, so a control that committed as it
+ * settled turned one edit into a write the user never asked for and could
+ * not preview; staged text makes what is on screen exactly what a save would
+ * store.
+ *
+ * A field shows its effective value — the user layer over the composition
+ * layer over the schema default — and whether the user layer carries it. That
+ * presence, not a value comparison, is what marks a field overridden: an
+ * override equal to the composition default is still an override.
+ *
+ * The kernel side (storage, schema validation, layering, revision fencing)
+ * stays with the dsh settings / credentials services; this module only
+ * translates between drafts and `mutate` path ops.
+ */
+/** Read a nested value by path (array indexes as strings). */
+export function getPath(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (Array.isArray(current)) {
+            current = current[Number(key)];
+            continue;
+        }
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Whether a value explicitly carries the path — its presence marks a user
+ * override, independent of the value stored there.
+ */
+export function hasPath(value, path) {
+    if (path.length === 0)
+        return value !== undefined;
+    const parent = getPath(value, path.slice(0, -1));
+    const key = path[path.length - 1];
+    if (Array.isArray(parent))
+        return Number(key) < parent.length;
+    if (typeof parent !== 'object' || parent === null)
+        return false;
+    return key in parent;
+}
+/** Default draft text for a kind; the empty string when the section carries none. */
+function defaultFormat(field, value) {
+    if (field.format)
+        return field.format(value);
+    if (value === undefined || value === null)
+        return '';
+    switch (field.kind) {
+        case 'number':
+            return typeof value === 'number' ? String(value) : '';
+        case 'boolean':
+            return value === true ? 'true' : 'false';
+        default:
+            return typeof value === 'string' ? value : String(value);
+    }
+}
+/** Default write for a kind: an empty text/number draft stages a clear. */
+function defaultParse(field, text) {
+    if (field.parse)
+        return field.parse(text);
+    const trimmed = text.trim();
+    switch (field.kind) {
+        case 'number': {
+            if (trimmed === '')
+                return { kind: 'clear' };
+            const value = Number(trimmed);
+            return Number.isFinite(value) ? { kind: 'set', value } : undefined;
+        }
+        case 'boolean':
+            return { kind: 'set', value: trimmed === 'true' };
+        case 'select':
+            return field.options?.some(option => option.value === trimmed)
+                ? { kind: 'set', value: trimmed }
+                : undefined;
+        default:
+            return trimmed === '' ? { kind: 'clear' } : { kind: 'set', value: text };
+    }
+}
+/** Key addressing one field inside a form: its path joined. */
+function fieldKey(field) {
+    return field.path.join('.');
+}
+/**
+ * The staged form over one settings namespace's declared fields. The screen
+ * re-seeds it from a fresh namespace view after every save and whenever the
+ * underlying document changes.
+ */
+export class SettingsForm {
+    host;
+    view;
+    fields;
+    edits = new Map();
+    saving = false;
+    failed = false;
+    constructor(host, view, fields) {
+        this.host = host;
+        this.view = view;
+        this.fields = fields;
+    }
+    get available() {
+        return this.view !== undefined;
+    }
+    /** The namespace view the form was seeded from (undefined = not served). */
+    get namespace() {
+        return this.view;
+    }
+    field(field) {
+        const key = fieldKey(field);
+        const staged = this.edits.get(key);
+        if (field.secret !== undefined) {
+            // A credential literal never seeds a draft: blank until typed, and a
+            // blank draft writes nothing.
+            return { text: staged?.text ?? '', overridden: false, invalid: false };
+        }
+        if (staged !== undefined) {
+            const write = defaultParse(field, staged.text);
+            return {
+                text: staged.text,
+                overridden: write?.kind === 'set',
+                invalid: write === undefined,
+            };
+        }
+        return {
+            text: defaultFormat(field, this.view ? getPath(this.view.value, field.path) : undefined),
+            overridden: this.view !== undefined && hasPath(this.view.user, field.path),
+            invalid: false,
+        };
+    }
+    shell() {
+        let invalid = false;
+        for (const field of this.fields) {
+            if (this.field(field).invalid)
+                invalid = true;
+        }
+        return {
+            available: this.available,
+            dirty: this.edits.size > 0,
+            invalid,
+            saving: this.saving,
+            failed: this.failed,
+        };
+    }
+    /** Whether the field holds a staged (unsaved) edit. */
+    isStaged(field) {
+        return this.edits.has(fieldKey(field));
+    }
+    /** Stage draft text for one field. */
+    edit(field, text) {
+        this.edits.set(fieldKey(field), { text, clear: false });
+        this.failed = false;
+    }
+    /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+    resetField(field) {
+        this.edits.set(fieldKey(field), { text: '', clear: true });
+        this.failed = false;
+    }
+    /** Drop every staged edit. */
+    discard() {
+        this.edits.clear();
+        this.failed = false;
+    }
+    /** Whether any staged draft is invalid, which blocks the save. */
+    get invalid() {
+        return this.shell().invalid;
+    }
+    /**
+     * Write every staged edit. Settings fields land as one revision-fenced
+     * `mutate` (one retry on a stale-revision conflict); credential fields
+     * write through the credentials seam. Resolves to whether every write
+     * landed — the caller re-seeds from a fresh namespace view afterwards.
+     *
+     * Only the edits THIS save snapshotted are cleared on success, and only
+     * when they are still the same edit: a draft typed while the write was in
+     * flight is a newer object and survives — it was never written, so it must
+     * not be silently dropped.
+     */
+    async save() {
+        if (this.view === undefined || this.invalid || this.saving)
+            return false;
+        const ns = this.view.ns;
+        const snapshot = new Map(this.edits);
+        const ops = [];
+        const secrets = [];
+        for (const field of this.fields) {
+            const staged = snapshot.get(fieldKey(field));
+            if (staged === undefined)
+                continue;
+            if (field.secret !== undefined) {
+                // Blank drafts write nothing; typed drafts replace the credential.
+                if (staged.text !== '')
+                    secrets.push({ ref: field.secret.ref, text: staged.text });
+                continue;
+            }
+            const write = staged.clear ? { kind: 'clear' } : defaultParse(field, staged.text);
+            if (write === undefined)
+                return false;
+            ops.push(write.kind === 'clear'
+                ? { op: 'unset', path: field.path }
+                : { op: 'set', path: field.path, value: write.value });
+        }
+        this.saving = true;
+        try {
+            if (ops.length > 0) {
+                try {
+                    await this.host.write(ns, ops, this.view.revision);
+                }
+                catch (error) {
+                    // One retry on a stale-revision conflict (a concurrent write landed
+                    // between seed and save); anything else propagates.
+                    if (error?.code !== 'SETTINGS_CONFLICT')
+                        throw error;
+                    const fresh = this.host.listNamespaces().find(entry => entry.ns === ns);
+                    await this.host.write(ns, ops, fresh?.revision);
+                }
+            }
+            for (const secret of secrets) {
+                await this.host.writeCredential(secret.ref, secret.text);
+            }
+            for (const [key, edit] of snapshot) {
+                if (this.edits.get(key) === edit)
+                    this.edits.delete(key);
+            }
+            this.failed = false;
+            return true;
+        }
+        catch {
+            this.failed = true;
+            return false;
+        }
+        finally {
+            this.saving = false;
+        }
+    }
+    /** Whether any layer supplies the credential a secret field addresses. */
+    credentialConfigured(field) {
+        return field.secret === undefined ? Promise.resolve(false) : this.host.credentialConfigured(field.secret.ref);
+    }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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 { Context, Service } from '@deepseek-ai/cordis';
+/** Minimal shape of the ink Key flags the matcher reads (kept structurally
+ *  compatible with `Key` from the ui kit without importing React-facing
+ *  modules into the adapter). */
+export interface TuiShortcutKey {
+    ctrl?: boolean;
+    meta?: boolean;
+    super?: boolean;
+    shift?: boolean;
+    return?: boolean;
+    escape?: boolean;
+    tab?: boolean;
+    backspace?: boolean;
+    delete?: boolean;
+    upArrow?: boolean;
+    downArrow?: boolean;
+    leftArrow?: boolean;
+    rightArrow?: boolean;
+    home?: boolean;
+    end?: boolean;
+    pageUp?: boolean;
+    pageDown?: boolean;
+}
+export interface TuiShortcutOptions {
+    /** One-line description (shown by future /help surfaces; required so
+     *  every binding is discoverable). */
+    description: string;
+    handler: () => void | Promise<void>;
+}
+interface ParsedCombo {
+    readonly raw: string;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+    readonly shift: boolean;
+    /** Named key flag on the Key object, or undefined for a character key. */
+    readonly named?: keyof TuiShortcutKey;
+    /** Character to match against the ink `input` string (lowercased). */
+    readonly char?: string;
+}
+/**
+ * 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 declare function parseShortcutCombo(raw: string): ParsedCombo | undefined;
+/** Match a keypress against a parsed combo. `input` is ink's input string
+ *  (already the resolved character; ctrl+space arrives as ' '). */
+export declare function matchShortcut(combo: ParsedCombo, input: string, key: TuiShortcutKey): boolean;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiShortcuts: TuiShortcutRuntime;
+    }
+}
+/** `ctx.tuiShortcuts` — plugin keyboard shortcut registry. */
+export declare class TuiShortcutRuntime extends Service {
+    private readonly shortcuts;
+    /** Handler invocation errors are surfaced through this hook — the chat
+     *  screen wires it to its notification toast. */
+    onError: ((combo: string, error: unknown) => void) | undefined;
+    constructor(ctx: Context);
+    /**
+     * 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: string, options: TuiShortcutOptions, identity?: Context): () => void;
+    /** Registered combos with descriptions (diagnostics / future /help). */
+    list(): readonly {
+        combo: string;
+        description: string;
+    }[];
+    /**
+     * Match a keypress; on a hit, run the handler and return true (the UI
+     * consumes the key). Handler rejections are caught and reported through
+     * {@link onError} — never propagated into the input path.
+     */
+    dispatch(input: string, key: TuiShortcutKey): boolean;
+}
+export default TuiShortcutRuntime;
+//# sourceMappingURL=shortcuts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/shortcuts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGtD;;iCAEiC;AACjC,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;0CACsC;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,cAAc,CAAA;IACrC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AA6DD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CA8CvE;AAkBD;mEACmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAiB7F;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,YAAY,EAAE,kBAAkB,CAAA;KACjC;CACF;AAED,8DAA8D;AAC9D,qBAAa,kBAAmB,SAAQ,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE;qDACiD;IACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;gBAElD,GAAG,EAAE,OAAO;IAIxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;IAoDpF,wEAAwE;IACxE,IAAI,IAAI,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE;IAIzD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO;CAatD;AAED,eAAe,kBAAkB,CAAA"}

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

@@ -0,0 +1,268 @@
+/**
+ * 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';
+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 {
+    shortcuts = new Map();
+    /** Handler invocation errors are surfaced through this hook — the chat
+     *  screen wires it to its notification toast. */
+    onError;
+    constructor(ctx) {
+        super(ctx, 'tuiShortcuts');
+    }
+    /**
+     * 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) {
+        const parsed = parseShortcutCombo(combo);
+        if (parsed === undefined) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected ${JSON.stringify(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 "${combo}" — reserved by a built-in binding`);
+            return () => { };
+        }
+        if (this.shortcuts.has(key)) {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${combo}" — already registered`);
+            this.ctx.get('tuiEffectLedger')?.record({
+                operation: 'bind',
+                resource: { kind: 'shortcut', id: key },
+                result: 'failed',
+                errorCode: 'DUPLICATE_CONTRIBUTION_ID',
+            }, identity);
+            return () => { };
+        }
+        const description = cleanScalarText(options?.description, 120);
+        if (typeof options?.handler !== 'function' || description === '') {
+            this.ctx.logger.warn(`dsh-tui: tuiShortcuts.register rejected "${combo}" — needs a description and a handler`);
+            return () => { };
+        }
+        const entry = { combo: parsed, description, handler: options.handler };
+        this.shortcuts.set(key, entry);
+        this.ctx.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'shortcut', id: key }, result: 'applied' }, identity);
+        return () => {
+            if (this.shortcuts.get(key) !== entry)
+                return;
+            this.shortcuts.delete(key);
+            this.ctx.get('tuiEffectLedger')?.record({ operation: 'release', resource: { kind: 'shortcut', id: key }, result: 'applied' }, identity);
+        };
+    }
+    /** Registered combos with descriptions (diagnostics / future /help). */
+    list() {
+        return [...this.shortcuts.values()].map(entry => ({ combo: entry.combo.raw, description: entry.description }));
+    }
+    /**
+     * Match a keypress; on a hit, run the handler and return true (the UI
+     * consumes the key). Handler rejections are caught and reported through
+     * {@link onError} — never propagated into the input path.
+     */
+    dispatch(input, key) {
+        for (const entry of this.shortcuts.values()) {
+            if (!matchShortcut(entry.combo, input, key))
+                continue;
+            Promise.resolve()
+                .then(() => entry.handler())
+                .catch((error) => {
+                this.onError?.(entry.combo.raw, error);
+                this.ctx.logger.warn(`dsh-tui: shortcut "${entry.combo.raw}" handler failed: %o`, error);
+            });
+            return true;
+        }
+        return false;
+    }
+}
+export default TuiShortcutRuntime;