@x1a0f3n9/dsh-client-ui-commands 0.1.5-rc.3

package/lib/index.js

@@ -0,0 +1,12 @@
+//#region lib/types/index.js
+/**
+* Command UI plugin, node half. Pure UI plugin: the empty apply exists so
+* the plugin appears in the host cordis.yml / Loader; the browser half ships
+* via exports["./client"], discovered through the package.json dsh.client
+* declaration. The host command registry itself mounts separately
+* (bootHost + CommandUiRuntime).
+*/
+/** Host plugin body — no host-side behavior for the command UI plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/PopupSelectView.d.ts

@@ -0,0 +1,16 @@
+import type { PropsLocale } from '@x1a0f3n9/dsh-client-ui-slots';
+import type { PopupSelectController } from './popup.ts';
+/** Injected business face of the popupSelect overlay entry. */
+export interface PopupSelectInjected {
+    /** The session's shell controller (state store + verbs; the view never touches the open-context type). */
+    popup: PopupSelectController;
+}
+/** Full shell props: injected face + the locale seat. */
+export type PopupSelectViewProps = PopupSelectInjected & PropsLocale<'command'>;
+/**
+ * Render the popupSelect shell overlay entry.
+ * @param props - injected face: the session's shell controller; `t` rides the standard locale seat.
+ * @returns the select card while open; null while closed.
+ */
+export declare function PopupSelectView({ popup, t }: PopupSelectViewProps): import("react").JSX.Element | null;
+//# sourceMappingURL=PopupSelectView.d.ts.map

package/lib/types/client/contract.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Frozen contract of the client command surface. Types only. The
+ * CommandUiRuntime (`ctx.commandUi`) implements this face; business packages
+ * consume `register` alone.
+ */
+import type { ComponentType } from 'react';
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { ClientSessionContext } from '@x1a0f3n9/dsh-client-ui-input-trigger/client';
+import type { IconProps } from '@x1a0f3n9/dsh-client-ui-primitives';
+/** Copy for an option that must be acknowledged before onSelect can run. */
+export interface SelectConfirmation {
+    readonly title: string;
+    readonly description: string;
+    readonly acknowledgeLabel: string;
+    readonly cancelLabel: string;
+    readonly confirmLabel: string;
+}
+/** One option row of a popupSelect shell. */
+export interface SelectOption {
+    readonly id: string;
+    readonly label: string;
+    readonly detail?: string;
+    readonly active?: boolean;
+    /** Optional in-page risk gate owned by the shared popup shell. */
+    readonly confirmation?: SelectConfirmation;
+}
+/**
+ * Business registration for the popupSelect command kind. Data is
+ * self-served: options/onSelect use the business package's own protocol.
+ * The shell component is owned by ui-commands; business never sees it. Both
+ * callbacks receive the ClientSessionContext captured at popup open.
+ */
+export interface PopupSelectSpec {
+    readonly kind: 'popupSelect';
+    options(session: ClientSessionContext, signal: AbortSignal): Promise<readonly SelectOption[]>;
+    onSelect(option: SelectOption, session: ClientSessionContext): void | Promise<void>;
+}
+/**
+ * Business registration for the action command kind: a bare invocation
+ * consumes the trigger token and runs one client-side callback. It submits nothing, so an
+ * attachment-carrying draft never refuses it.
+ */
+export interface ActionSpec {
+    readonly kind: 'action';
+    /**
+     * Run the action for one session.
+     * @param session - the ClientSessionContext captured at invocation.
+     */
+    run(session: ClientSessionContext): void;
+}
+/** The UI behavior of a contribution or decoration. */
+export type CommandUiSpec = PopupSelectSpec | ActionSpec;
+/**
+ * One client-owned command contribution: a slash-menu entry whose behavior
+ * lives entirely on the client (no host descriptor). Merged with the host
+ * catalog by name — a collision with a host command fails loud at candidate
+ * synthesis, never shadows. Row copy is read on every candidate pass, so a
+ * locale change reaches the next menu open without re-registration.
+ */
+export interface CommandContribution {
+    /** Command name without the leading slash (unique across contributions). */
+    readonly name: string;
+    /** Localized menu row title; the name itself when absent. */
+    label?(): string;
+    /** Localized menu row description; the row shows none when absent. */
+    description?(): string;
+    /** Menu row glyph from the shared icon set. */
+    readonly icon?: ComponentType<IconProps>;
+    /** Capability filter, called with a fresh projection per candidate pass. */
+    available(session: ClientSessionContext): boolean;
+    /** The command's UI behavior. */
+    readonly ui: CommandUiSpec;
+}
+/**
+ * A UI decoration hung on one HOST command: what its BARE invocation does on
+ * this client. Not a second command — the host command keeps its catalog
+ * row, its argument claim (space / argued enter), and its lifecycle logging;
+ * the decoration replaces only the bare menu-pick/enter with a popup whose
+ * onSelect typically submits a completed line back through command.execute.
+ * A decoration never manufactures a row: a name with no host catalog entry
+ * in the session's directory simply never reaches the decoration.
+ */
+export interface CommandDecoration {
+    /** The HOST command name this decorates (without the leading slash). */
+    readonly name: string;
+    /** Capability filter, called with a fresh projection per bare invocation. */
+    available(session: ClientSessionContext): boolean;
+    /** The bare-invocation UI. */
+    readonly ui: CommandUiSpec;
+}
+/** The `ctx.commandUi` service face visible to business packages. */
+export interface CommandUiContract {
+    /**
+     * Register one client command contribution; effect disposer. Duplicate
+     * names throw at registration.
+     */
+    register(contribution: CommandContribution): () => void;
+    /**
+     * Hang a bare-invocation decoration on one host command; effect disposer.
+     * Duplicate names throw at registration.
+     */
+    decorate(decoration: CommandDecoration): () => void;
+    /** Resolve the per-session popup controller for one session scope (wiring/overlay layer). */
+    popupFor(actx: ClientContext): unknown;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/directory.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Command-directory cache keyed by session: one entry per served catalog —
+ * every session is agent-backed, so `command.list({sessionId})` is the only
+ * request fields. Each entry keeps the single-flight / soft-hard invalidation
+ * / epoch-guard behavior of the original global cache; the session-key axis
+ * is the only extra dimension.
+ */
+import type { CommandDescriptor } from '@x1a0f3n9/dsh-commands/types';
+import type { SessionId } from '@x1a0f3n9/dsh-session/types';
+export type { CommandDescriptor } from '@x1a0f3n9/dsh-commands/types';
+/**
+ * cold = never pulled; pending = pull in flight with nothing servable;
+ * ready = snapshot serving (a soft-invalidate repull keeps this status);
+ * failed = last winning pull rejected, snapshot dropped.
+ */
+export type DirectoryStatus = 'cold' | 'pending' | 'ready' | 'failed';
+/** Injected pull (the service binds command.list off the root connection). */
+export type FetchCommands = (sessionId: SessionId) => Promise<readonly CommandDescriptor[]>;
+/** The session-keyed directory cache. Plain class — the owning service wires events and RPC. */
+export declare class CommandDirectory {
+    private readonly fetchCommands;
+    private readonly entries;
+    constructor(fetchCommands: FetchCommands);
+    /**
+     * Current cache status for one session.
+     * @param sessionId - session key.
+     * @returns the entry status (cold when never touched).
+     */
+    status(sessionId: SessionId): DirectoryStatus;
+    /**
+     * Synchronous command lookup over one Session's ready catalog; exact names precede localized aliases.
+     * @param sessionId - session key.
+     * @param name - typed command spelling without the leading slash.
+     * @returns the descriptor, or undefined when absent or the entry is not ready.
+     */
+    resolve(sessionId: SessionId, name: string): CommandDescriptor | undefined;
+    /** Soft invalidation (commands-changed): background repull on every touched key; ready snapshots keep serving. */
+    invalidateAll(): void;
+    /**
+     * Drop one Session's obsolete composition-specific snapshot and prewarm its replacement.
+     * @param sessionId - Session whose effective command composition changed.
+     */
+    resetSession(sessionId: SessionId): void;
+    /**
+     * Hard reset on reconnect: every entry drops its snapshot (the agent world
+     * may have changed shape across the generation) and prewarms.
+     */
+    resetConnected(): void;
+    /**
+     * Fire-and-forget prewarm of one session (the command source's scope-birth
+     * warm hook lands here).
+     * @param sessionId - session key.
+     */
+    warm(sessionId: SessionId): void;
+    /**
+     * Start one pull for one session. Publishes ready/failed only while it is
+     * still the key's latest pull (epoch guard); a ready snapshot is not
+     * demoted while the pull flies.
+     * @param sessionId - session key.
+     * @returns settled when this pull's outcome is published or discarded.
+     */
+    refresh(sessionId: SessionId): Promise<void>;
+    /**
+     * Strong-wait until one session's catalog is servable (the enter-
+     * adjudication "directory must be reached" rule): ready returns at once;
+     * cold/failed launch a fresh pull; pending joins the flying one. Rejects
+     * when the awaited pull fails or the signal aborts.
+     * @param sessionId - session key.
+     * @param signal - attempt-scoped abort (the SubmitAttempt signal).
+     * @returns the hot command snapshot.
+     */
+    ensureReady(sessionId: SessionId, signal: AbortSignal): Promise<readonly CommandDescriptor[]>;
+    private entry;
+}
+//# sourceMappingURL=directory.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Command UI plugin, browser half: CommandUiRuntime (`ctx.commandUi`) owning the
+ * capability-keyed directory cache, the '/' command source, the client
+ * contribution registry, and the per-session popupSelect controllers; the
+ * popupSelect shell self-registers into conversation.input.overlay with
+ * per-session resolution.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { CommandUiRuntime } from './service.ts';
+import { type CommandKey } from './locales.ts';
+export { CommandUiRuntime } from './service.ts';
+export { CommandDirectory } from './directory.ts';
+export type { CommandDescriptor, DirectoryStatus } from './directory.ts';
+export { filterOptions, PopupSelectController } from './popup.ts';
+export type { PopupSelectDeps, PopupSpec, PopupState, TokenSegment } from './popup.ts';
+export type { PopupSelectInjected, PopupSelectViewProps } from './PopupSelectView.tsx';
+export type { ActionSpec, CommandContribution, CommandDecoration, CommandUiContract, CommandUiSpec, PopupSelectSpec, SelectConfirmation, SelectOption, } from './contract.ts';
+export type { CommandKey } from './locales.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        commandUi: CommandUiRuntime;
+    }
+}
+declare module '@x1a0f3n9/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The menu rows' and the popupSelect shell's copy. */
+        command: CommandKey;
+    }
+}
+/** Required services: the '/' source registry, session scopes, commands Remote, and locale registry. */
+export declare const inject: string[];
+/**
+ * Mount the command service and its per-session popupSelect overlay.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `command` namespace dictionaries: the composer menu's section headings,
+ * the client face (title, description, claim token) of the built-in Host
+ * commands whose catalog descriptors carry English text only, and the
+ * popupSelect shell's copy.
+ */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'section.add': string;
+    'section.commands': string;
+    'label.goal': string;
+    'label.plan': string;
+    'label.feedback': string;
+    'label.compact': string;
+    'label.permission': string;
+    'label.export': string;
+    'description.goal': string;
+    'description.plan': string;
+    'description.feedback': string;
+    'description.compact': string;
+    'description.permission': string;
+    'description.export': string;
+    'token.goal': string;
+    'token.plan': string;
+    'token.feedback': string;
+    'token.compact': string;
+    'token.permission': string;
+    'token.export': string;
+    'search.placeholder': string;
+    'search.aria': string;
+    'status.loading': string;
+    'status.applying': string;
+    'status.empty': string;
+    'overlay.aria': string;
+    'listbox.aria': string;
+    'notice.attachmentsUnsupported': string;
+};
+/** The command namespace key union. */
+export type CommandKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'section.add': string;
+    'section.commands': string;
+    'label.goal': string;
+    'label.plan': string;
+    'label.feedback': string;
+    'label.compact': string;
+    'label.permission': string;
+    'label.export': string;
+    'description.goal': string;
+    'description.plan': string;
+    'description.feedback': string;
+    'description.compact': string;
+    'description.permission': string;
+    'description.export': string;
+    'token.goal': string;
+    'token.plan': string;
+    'token.feedback': string;
+    'token.compact': string;
+    'token.permission': string;
+    'token.export': string;
+    'search.placeholder': string;
+    'search.aria': string;
+    'status.loading': string;
+    'status.applying': string;
+    'status.empty': string;
+    'overlay.aria': string;
+    'listbox.aria': string;
+    'notice.attachmentsUnsupported': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/popup.d.ts

@@ -0,0 +1,154 @@
+import type { SnapshotStore } from '@x1a0f3n9/dsh-client-store';
+import type { TokenSpan } from '@x1a0f3n9/dsh-client-ui-input-trigger/client';
+import type { SelectOption } from './contract.ts';
+/**
+ * The command token segment snapshotted at shell-open time, replayed to the
+ * injected {@link PopupSelectDeps.consume} callback after a successful
+ * selection. The Input side guards it: a menu-path span consumes iff draftRev
+ * is unchanged, an enter-path line iff the trimmed draft still equals the
+ * bare token.
+ */
+export type TokenSegment = {
+    readonly via: 'menu';
+    readonly span: TokenSpan;
+} | {
+    readonly via: 'enter';
+    readonly token: string;
+};
+/**
+ * Structural business spec the shell settles against — the popupSelect half
+ * of CommandUiSpec, generic in the context value the opener captures (the
+ * session wiring passes its session projection; the controller only carries
+ * it from open() to the callbacks).
+ */
+export interface PopupSpec<TCtx> {
+    /** Load the option rows once per open (retry after failure reuses the same signal). */
+    options(context: TCtx, signal: AbortSignal): Promise<readonly SelectOption[]>;
+    /** Settle the picked option against the open-time context. */
+    onSelect(option: SelectOption, context: TCtx): void | Promise<void>;
+}
+/** Injected session-wiring callbacks of one controller (tests pass fakes). */
+export interface PopupSelectDeps {
+    /**
+     * Consume the open-time token segment after a successful onSelect (the
+     * wiring dispatches the consume-token event to the opening session).
+     * @param segment - the open-time token segment snapshot.
+     * @returns whether the token was consumed; false (CAS miss) is benign and
+     * never retried.
+     */
+    consume(segment: TokenSegment): boolean;
+    /** Return focus to the session composer (successful settle and Escape close paths). */
+    focusComposer(): void;
+}
+/** Popup shell state (the shell component renders from here; closed = render null). */
+export interface PopupState {
+    readonly open: boolean;
+    /** Command name the shell is open for (null while closed). */
+    readonly command: string | null;
+    /** Options-load lifecycle; 'failed' keeps the shell open for retry(). */
+    readonly status: 'pending' | 'ready' | 'failed';
+    /** Options as loaded — never re-fetched per keystroke; views render {@link filterOptions} over them. */
+    readonly options: readonly SelectOption[];
+    /** Local filter text over the loaded options. */
+    readonly search: string;
+    /** Highlight index into the filtered row list (0 when empty/pending). */
+    readonly active: number;
+    /** A select() settlement is in flight: further select/search/highlight no-op until it settles. */
+    readonly submitting: boolean;
+    /** Option waiting for explicit risk acknowledgement; null during normal selection. */
+    readonly confirming: SelectOption | null;
+    /** Caller-controlled checkbox state for the pending confirmation. */
+    readonly acknowledged: boolean;
+    /** Surfaced settlement failure (options load or onSelect); null when none. */
+    readonly error: string | null;
+}
+/**
+ * Filter option rows against the shell's local search text (case-insensitive
+ * substring over label and detail; blank search keeps every row).
+ * @param options - the loaded rows.
+ * @param search - the shell's search text.
+ * @returns the rows the shell shows and highlights over.
+ */
+export declare function filterOptions(options: readonly SelectOption[], search: string): readonly SelectOption[];
+/**
+ * Headless controller of one session's popupSelect shell. Late settlements
+ * lose their write rights through binding identity: dismiss/dispose/reopen
+ * swap the binding, so a settling options fetch or onSelect that no longer
+ * matches writes nothing and consumes nothing.
+ */
+export declare class PopupSelectController<TCtx = unknown> {
+    private readonly deps;
+    /** Shell state store (the overlay component subscribes here). */
+    readonly state: SnapshotStore<PopupState>;
+    private binding;
+    /**
+     * @param deps - session-wiring callbacks (token consumption + composer focus).
+     */
+    constructor(deps: PopupSelectDeps);
+    /**
+     * Open the shell for one command: publish pending state and fetch options
+     * once through the business spec. A reopen supersedes the previous shell
+     * (its options fetch is aborted, its late settlements are dropped).
+     * @param command - command name the shell serves.
+     * @param spec - the registered popupSelect spec.
+     * @param context - open-time context snapshot, handed verbatim to options/onSelect.
+     * @param segment - open-time token segment snapshot for post-select consumption.
+     */
+    open(command: string, spec: PopupSpec<TCtx>, context: TCtx, segment: TokenSegment): void;
+    /** Run the one options fetch of a binding; settlement rights die with the binding. */
+    private load;
+    /** Re-run a failed options fetch (search survives; no-op unless status is 'failed'). */
+    retry(): void;
+    /**
+     * Replace the local search text (pure local filter — the provider is never
+     * re-queried) and rebase the highlight onto the new filtered list.
+     * @param search - the shell search input's text.
+     */
+    setSearch(search: string): void;
+    /**
+     * Move the highlight across the filtered rows (wraps around; no-op unless
+     * options are ready and no selection is in flight).
+     * @param dir - +1 down, -1 up.
+     */
+    move(dir: 1 | -1): void;
+    /**
+     * Set the highlight directly (pointer hover; no-op unless ready, idle, and
+     * in filtered range).
+     * @param index - filtered-row index.
+     */
+    highlight(index: number): void;
+    /**
+     * Select one filtered row: single-flight — the first call enters
+     * `submitting` and later calls no-op until it settles. Success consumes the
+     * open-time token segment (a false CAS answer is benign), closes, and
+     * returns focus to the composer. Failure keeps the shell open with search,
+     * highlight, and token intact, surfaces the error, and re-arms select as
+     * the retry.
+     * @param index - filtered-row index (callers pass the highlight or the clicked row).
+     * @returns settled when the attempt has closed the shell or surfaced its failure.
+     */
+    select(index: number): Promise<void>;
+    /**
+     * Update the explicit checkbox for the currently pending risk gate.
+     * @param acknowledged - whether the user has acknowledged the displayed risk.
+     */
+    acknowledge(acknowledged: boolean): void;
+    /** Cancel only the risk gate and return to the still-open option picker. */
+    cancelConfirmation(): void;
+    /** Settle the gated option only after the checkbox is acknowledged. */
+    confirm(): Promise<void>;
+    /** Run the business settlement for an already admitted option. */
+    private settle;
+    /**
+     * Close the shell; aborts a flying options fetch and revokes settlement
+     * rights. An outside pointer interaction dismisses plainly (the click's own
+     * target takes focus); Escape passes focusComposer to return focus explicitly.
+     * @param opts - focusComposer: also restore composer focus (Escape path).
+     */
+    dismiss(opts?: {
+        readonly focusComposer?: boolean;
+    }): void;
+    /** Scope-teardown disposer: abort in-flight work and clear state (no focus side effect). */
+    dispose(): void;
+}
+//# sourceMappingURL=popup.d.ts.map

package/lib/types/client/presentation.d.ts

@@ -0,0 +1,23 @@
+import type { InputTriggerCandidate } from '@x1a0f3n9/dsh-client-ui-input-trigger/client';
+import type { TranslateNS } from '@x1a0f3n9/dsh-client-locale/client';
+import type { CommandDescriptor } from '@x1a0f3n9/dsh-commands/types';
+/** The menu's two sections. */
+export type MenuSection = 'add' | 'commands';
+/**
+ * The localized menu face of a catalog row.
+ * @param descriptor - effective Host command descriptor.
+ * @param t - the `command` namespace translator.
+ * @returns title, description, and glyph for a built-in command; undefined
+ * for any other row, which keeps its catalog description.
+ */
+export declare function builtinRowFace(descriptor: CommandDescriptor, t: TranslateNS<'command'>): Pick<InputTriggerCandidate, 'label' | 'description' | 'icon'> | undefined;
+/**
+ * Arrange the empty-query menu: the Add section, then the Commands section,
+ * each in usage order, with unlisted rows closing Commands in their input
+ * order; each row carries its section heading.
+ * @param rows - the visible candidates in catalog-then-contribution order.
+ * @param t - the `command` namespace translator.
+ * @returns the sectioned rows.
+ */
+export declare function sectionRows(rows: readonly InputTriggerCandidate[], t: TranslateNS<'command'>): readonly InputTriggerCandidate[];
+//# sourceMappingURL=presentation.d.ts.map

package/lib/types/client/resolution.d.ts

@@ -0,0 +1,35 @@
+/** Command identity and localized input spelling over the effective Host catalog. */
+import type { CommandDescriptor } from '@x1a0f3n9/dsh-commands/types';
+import type { TranslateNS } from '@x1a0f3n9/dsh-client-locale/client';
+declare const BUILTINS: {
+    readonly goal: "@x1a0f3n9/dsh-command-goal";
+    readonly plan: "@x1a0f3n9/dsh-plan-mode";
+    readonly feedback: "@x1a0f3n9/dsh-command-feedback";
+    readonly compact: "@x1a0f3n9/dsh-command-compact";
+    readonly permission: "@x1a0f3n9/dsh-permission-presets";
+    readonly export: "@x1a0f3n9/dsh-session-log-export";
+};
+/** Names whose first-party definitions have localized client presentation. */
+export type BuiltinCommandName = keyof typeof BUILTINS;
+/**
+ * Identify a first-party definition without interpreting its display copy.
+ * @param descriptor - effective Host descriptor after scoped shadowing.
+ * @returns its first-party name, or undefined for another definition.
+ */
+export declare function builtinCommandName(descriptor: CommandDescriptor): BuiltinCommandName | undefined;
+/**
+ * Select the input spelling for a menu-picked command.
+ * @param descriptor - effective Host descriptor.
+ * @param t - command-namespace translator.
+ * @returns localized spelling for a known definition, otherwise its registered name.
+ */
+export declare function claimToken(descriptor: CommandDescriptor, t: TranslateNS<'command'>): string;
+/**
+ * Resolve typed spelling against the current Session's effective definitions.
+ * @param token - typed name without its leading slash.
+ * @param descriptors - effective descriptors in the Session's ready catalog.
+ * @returns the matching descriptor; aliases never select an unrelated scoped override.
+ */
+export declare function resolveCommand(token: string, descriptors: readonly CommandDescriptor[]): CommandDescriptor | undefined;
+export {};
+//# sourceMappingURL=resolution.d.ts.map