@askdkc/dsh-cli 0.11.3

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

@@ -0,0 +1,238 @@
+/** 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;
+    failureMessage = undefined;
+    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,
+            failureMessage: this.failed ? this.failureMessage : undefined,
+        };
+    }
+    /** 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.clearFailure();
+    }
+    /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+    resetField(field) {
+        this.edits.set(fieldKey(field), { text: '', clear: true });
+        this.clearFailure();
+    }
+    /** Drop every staged edit. */
+    discard() {
+        this.edits.clear();
+        this.clearFailure();
+    }
+    /** A new edit or save cycle retires the last failure's explanation. */
+    clearFailure() {
+        this.failed = false;
+        this.failureMessage = undefined;
+    }
+    /** 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;
+        this.clearFailure();
+        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 (error) {
+            this.failed = true;
+            // Guarded rejections (reserved credential refs, …) carry their own
+            // localized explanation — keep it for the screen to show verbatim
+            // instead of a generic "save failed".
+            this.failureMessage = error instanceof Error && error.message !== '' ? error.message : undefined;
+            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/sharp.d.ts

@@ -0,0 +1,10 @@
+export type SharpModule = Awaited<typeof import('sharp')>['default'];
+/** Load `sharp` once per process, preferring the host's copy. */
+export declare function loadSharp(): Promise<SharpModule | undefined>;
+/**
+ * Candidate `sharp` entry files, host first. The host anchor is a blessed
+ * upstream package: profile installs alias `@deepseek-ai/*` to the running
+ * dsh, so resolving `sharp` from that location walks the host's tree.
+ */
+export declare function sharpCandidatePaths(): string[];
+//# sourceMappingURL=sharp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharp.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/sharp.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAIpE,iEAAiE;AACjE,wBAAgB,SAAS,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAe9C"}

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

@@ -0,0 +1,59 @@
+/**
+ * Host-first `sharp` loader.
+ *
+ * dsh-tui runs inside the dsh process, and the host attachment service
+ * (`@deepseek-ai/dsh-attachment-local`) already loads its own `sharp`. Loading
+ * a second copy from this package's optional dependency puts two libvips
+ * dylibs into one process; on macOS the Objective-C runtime reports the
+ * duplicate classes on stderr, and that text lands on the alternate screen
+ * (0.1.2-rc.1 ships sharp 0.35.4 while this package pins 0.35.3).
+ *
+ * Resolve `sharp` from the host tree first, fall back to our own optional
+ * copy, and cache the outcome so the process holds one instance. A missing
+ * module resolves to `undefined`; callers keep their text fallback.
+ */
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+let loader;
+/** Load `sharp` once per process, preferring the host's copy. */
+export function loadSharp() {
+    loader ??= resolveSharp();
+    return loader;
+}
+/**
+ * Candidate `sharp` entry files, host first. The host anchor is a blessed
+ * upstream package: profile installs alias `@deepseek-ai/*` to the running
+ * dsh, so resolving `sharp` from that location walks the host's tree.
+ */
+export function sharpCandidatePaths() {
+    const local = createRequire(import.meta.url);
+    const paths = [];
+    try {
+        const anchor = local.resolve('@deepseek-ai/dsh-session/package.json');
+        paths.push(createRequire(anchor).resolve('sharp'));
+    }
+    catch {
+        // The host tree has no sharp (or no dsh-session); use our own copy.
+    }
+    try {
+        paths.push(local.resolve('sharp'));
+    }
+    catch {
+        // Optional dependency not installed.
+    }
+    return [...new Set(paths)];
+}
+async function resolveSharp() {
+    for (const path of sharpCandidatePaths()) {
+        try {
+            const mod = await import(pathToFileURL(path).href);
+            const candidate = mod.default ?? mod;
+            if (typeof candidate === 'function')
+                return candidate;
+        }
+        catch {
+            // A broken native build in one tree must not hide a working one.
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,82 @@
+/**
+ * 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 (fixed combos the TUI itself binds globally or in the
+ *   prompt editor, PLUS the effective combos of every customizable built-in
+ *   action from src/utils/keymap.ts) is refused at registration with a
+ *   warning. The list is the enforcement of "locals win": collisions can
+ *   never reach the matcher — and it follows user remaps made in /settings.
+ * - 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';
+import { comboMatchesStrict, parseCombo, type ComboKeyFlags, type ParsedCombo } from '../utils/keymap.js';
+/**
+ * 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 type TuiShortcutKey = ComboKeyFlags;
+export declare const parseShortcutCombo: typeof parseCombo;
+export declare const matchShortcut: typeof comboMatchesStrict;
+export type { ParsedCombo };
+/** Controls that only the Chat input path may use. They are kept out of the
+ * Cordis service object, so one plugin cannot synthesize an input event to
+ * invoke another plugin's shortcut handler. */
+export interface TuiShortcutHost {
+    register(combo: string, options: TuiShortcutOptions): () => void;
+    list(): readonly {
+        combo: string;
+        description: string;
+    }[];
+    dispatch(input: string, key: TuiShortcutKey): boolean;
+    setErrorHandler(handler: (combo: string, error: unknown) => void): () => void;
+}
+export interface TuiShortcutOptions {
+    /** Required one-line label returned by list() for diagnostics. */
+    description: string;
+    handler: () => void | Promise<void>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiShortcuts: TuiShortcutRuntime;
+    }
+}
+/** `ctx.tuiShortcuts` — plugin keyboard shortcut registry. */
+export declare class TuiShortcutRuntime extends Service {
+    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;
+    /** Combos and descriptions owned by the calling plugin activation. */
+    list(): readonly {
+        combo: string;
+        description: string;
+    }[];
+}
+export declare function getHostShortcuts(runtime: TuiShortcutRuntime | undefined): TuiShortcutHost | undefined;
+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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQtD,OAAO,EAEL,kBAAkB,EAElB,UAAU,EAEV,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAA;AAE3B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,CAAA;AAI1C,eAAO,MAAM,kBAAkB,mBAAa,CAAA;AAC5C,eAAO,MAAM,aAAa,2BAAqB,CAAA;AAC/C,YAAY,EAAE,WAAW,EAAE,CAAA;AAE3B;;+CAE+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;IAChE,IAAI,IAAI,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAA;IACrD,eAAe,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CAC9E;AAED,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC;AAiBD,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,YAAY,EAAE,kBAAkB,CAAA;KACjC;CACF;AAED,8DAA8D;AAC9D,qBAAa,kBAAmB,SAAQ,OAAO;gBACjC,GAAG,EAAE,OAAO;IA+DxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,IAAI;IA2FpF,sEAAsE;IACtE,IAAI,IAAI,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE;CAU1D;AAqCD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAOrG;AAED,eAAe,kBAAkB,CAAA"}

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

@@ -0,0 +1,252 @@
+/**
+ * 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 (fixed combos the TUI itself binds globally or in the
+ *   prompt editor, PLUS the effective combos of every customizable built-in
+ *   action from src/utils/keymap.ts) is refused at registration with a
+ *   warning. The list is the enforcement of "locals win": collisions can
+ *   never reach the matcher — and it follows user remaps made in /settings.
+ * - 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';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { canonicalCombo, comboMatchesStrict, fixedReservedCombos, parseCombo, reservedActionCombos, } from '../utils/keymap.js';
+// Shared combo grammar + built-in keymap live in src/utils/keymap.ts; the
+// parse/match entry points stay re-exported here for API stability.
+export const parseShortcutCombo = parseCombo;
+export const matchShortcut = comboMatchesStrict;
+/**
+ * The fixed half of the reserved set lives in src/utils/keymap.ts
+ * (FIXED_RESERVED_COMBOS) so the /settings draft validator and this
+ * registry agree on one list; the customizable action combos join here
+ * dynamically via `reservedActionCombos()` so a user remap (say
+ * paste → alt+v) moves the reservation with the binding.
+ */
+const FIXED_RESERVED_CANONICAL = fixedReservedCombos();
+/** `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,
+            runtime: adapterRuntimeFor(ctx),
+        };
+        const host = Object.freeze({
+            register: (combo, options) => {
+                const shortcutState = shortcutStateFor(runtime);
+                let parsed;
+                try {
+                    parsed = parseShortcutCombo(combo);
+                }
+                catch {
+                    return () => { };
+                }
+                if (parsed === undefined)
+                    return () => { };
+                const key = canonicalCombo(parsed);
+                const shiftlessKey = canonicalCombo({ ...parsed, shift: false });
+                const actionReserved = reservedActionCombos();
+                if (FIXED_RESERVED_CANONICAL.has(key) || FIXED_RESERVED_CANONICAL.has(shiftlessKey)
+                    || actionReserved.has(key) || actionReserved.has(shiftlessKey)
+                    || shortcutState.shortcuts.has(key)) {
+                    return () => { };
+                }
+                let description;
+                let handler;
+                try {
+                    description = cleanScalarText(options?.description, 120);
+                    handler = options?.handler;
+                }
+                catch {
+                    return () => { };
+                }
+                if (typeof handler !== 'function' || description === '')
+                    return () => { };
+                const entry = { combo: parsed, description, handler };
+                shortcutState.shortcuts.set(key, entry);
+                return () => {
+                    if (shortcutState.shortcuts.get(key) !== entry)
+                        return;
+                    shortcutState.shortcuts.delete(key);
+                    shortcutState.owners.delete(key);
+                };
+            },
+            list: () => [...shortcutStateFor(runtime).shortcuts.entries()].map(([, entry]) => ({
+                combo: entry.combo.raw,
+                description: entry.description,
+            })),
+            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) {
+        assertCapabilityShadowPolicy('host.shortcuts.register', shortcutStateFor(this).runtime.mode, shortcutStateFor(this).runtime.slices);
+        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 = canonicalCombo(parsed);
+        // Built-ins match a modifier subset (see FIXED_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). The customizable action combos join the check
+        // dynamically, so a user remap (paste → alt+v) reserves the new combo
+        // from the moment the settings layer applies it.
+        const shiftlessKey = canonicalCombo({ ...parsed, shift: false });
+        const actionReserved = reservedActionCombos();
+        if (FIXED_RESERVED_CANONICAL.has(key) || FIXED_RESERVED_CANONICAL.has(shiftlessKey) ||
+            actionReserved.has(key) || actionReserved.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;
+    }
+    /** Combos and descriptions owned by the calling plugin activation. */
+    list() {
+        assertCapabilityShadowPolicy('host.shortcuts.list', shortcutStateFor(this).runtime.mode, shortcutStateFor(this).runtime.slices);
+        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) {
+    assertCapabilityShadowPolicy('host.shortcuts.dispatch', shortcutStateFor(runtime).runtime.mode, shortcutStateFor(runtime).runtime.slices);
+    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;