@xmoon76/dsh-pi-tui 0.4.3-alpha.2 → 0.4.5

package/dist/{public-types-_pe9ZH00.d.mts → public-types-YbB5Rhku.d.mts}

@@ -67,8 +67,16 @@ interface TuiAutocompleteQuery {
 interface TuiAutocompleteProvider {
   getSuggestions(query: TuiAutocompleteQuery): Promise<TuiAutocompleteSuggestions | null>;
 }
-/** API version of the extension surface (bumped only on breaking changes). */
-declare const API_VERSION: 1;
+/**
+ * API version of the extension surface (bumped only on breaking changes).
+ * `2` is the client-command contribution contract: `execution` and the
+ * never-wired `argumentProvider` are REMOVED, `handler` is required, and a
+ * stale plugin still declaring the removed ownership shape is rejected at
+ * registration. `1` was the M0–M3 foundation. A plugin branching on
+ * `api().apiVersion` can tell the two schemas apart — the host never reports
+ * a version it does not implement.
+ */
+declare const API_VERSION: 2;
 /** Capability identifiers, feature-detected via {@link PiTuiApiInfo}. */
 type PiTuiCapability = 'slot.chrome.header.badge' | 'slot.input.dock.item' | 'slot.chrome.footer.status' | 'slot.chrome.footer.item' | 'slot.input.widget' | 'surface.snapshot' | 'advanced.input.capture' | 'advanced.ui.interactive' | 'advanced.editor.control' | 'unstable.input.raw' | 'unstable.surface.handle';
 /** Slot identities this bundle knows; unknown names are rejected at registration. */
@@ -79,7 +87,8 @@ type PiTuiSlotSemantic = 'list' | 'single';
 type ExtensionTier = 'stable' | 'advanced' | 'unstable';
 /** What a plugin may know about the host (M1: version + capabilities only). */
 interface PiTuiApiInfo {
-  /** The extension API version; 1 for the M0–M3 foundation. */
+  /** The extension API version: 2 for the client-command contribution
+   * contract, 1 for the M0–M3 foundation (see {@link API_VERSION}). */
   readonly apiVersion: typeof API_VERSION;
   /** The `@xmoon76/dsh-pi-tui` bundle version (semver string). */
   readonly hostVersion: string;
@@ -335,29 +344,40 @@ interface InputWidget {
   /** Preferred max rows (budget); the host may grant fewer. */
   readonly maxHeight?: number;
 }
-/** One command contribution (plan §10): ownership metadata over an
- * existing command. The bridge does NOT execute — the commands service
- * does. `/name args...` ALWAYS keeps `invocation.rawInput` verbatim. */
+/** One CLIENT-OWNED command contribution (plan §10) — the DSH client
+ * command contribution shape: a slash name whose behavior lives entirely on
+ * the client (no host descriptor). It appears in the `/` menu merged with
+ * the host catalog and executes through its own `handler`, never steered.
+ * A contribution whose name is a host command FAILS LOUD at candidate
+ * synthesis and never shadows it (the host command keeps its claim).
+ * A contribution is a slash-MENU entry, so it claims the BARE `/name` token
+ * only (DSH `matchEnter`): `/name args...` is NOT an invocation — it is an
+ * ordinary submission that reaches the model, and `handler` never runs for
+ * it. */
 interface TuiCommandContribution {
   readonly id: string;
   /** The slash-command name WITHOUT the leading slash. */
   readonly name: string;
   readonly description: string;
-  /** Execution ownership: local (never steered) vs submission (session
-   * policy). Busy Enter classifies by the EFFECTIVE ownership. */
-  readonly execution: 'local' | 'submission';
-  /** Whether the command may run without a live session. */
+  /** Whether the command may run BEFORE a live session exists (default
+   * false). A sessionless contribution executes immediately; every other
+   * contribution resolves/creates the session first, then executes — the
+   * host command surface is session-keyed upstream, so this is an explicit
+   * TUI extension for pure client commands (an overlay toggle, a picker). */
   readonly sessionless?: boolean;
-  /** Optional autocomplete provider for this command's arguments
-   * (the structural {@link TuiAutocompleteProvider}). */
-  readonly argumentProvider?: TuiAutocompleteProvider;
-  /** Optional local handler; absent = metadata-only ownership (the
-   * commands service handler runs). */
-  readonly handler?: TuiLocalCommandHandler;
+  /** The command's client behavior (required): the TUI runs it locally for the
+   * BARE `/name` line, passing `invocation.rawInput` verbatim (it carries no
+   * non-whitespace input, since an argued line is never an invocation, though
+   * trailing whitespace may be preserved), with or without a live session
+   * according to {@link sessionless}. */
+  readonly handler: TuiLocalCommandHandler;
 }
 /** The local command handler signature (invocation carries the VERBATIM
- * raw input — never re-parsed or rewritten). Returns the commands
- * service's result shape (`{ kind: 'success' }` / `{ kind: 'error',
+ * raw input — never re-parsed or rewritten). A client command CONTRIBUTION is
+ * invoked by its bare token alone, so its `rawInput` never carries
+ * non-whitespace input (trailing whitespace is preserved verbatim); TUI-owned
+ * local commands (`/export json`) still receive their arguments here. Returns the
+ * commands service's result shape (`{ kind: 'success' }` / `{ kind: 'error',
  * text }`) so the runner's notify path is shared. */
 interface TuiLocalCommandHandler {
   (invocation: {
@@ -380,9 +400,13 @@ interface TuiLocalCommandHandler {
     readonly text: string;
   }>;
 }
-/** A live handle on one command contribution. */
+/** A live handle on ONE command contribution REGISTRATION. */
 interface TuiCommandHandle {
   readonly id: string;
+  /** Dispose THIS registration (idempotent). A repeated or late call — e.g.
+   * a fiber disposer running after an HMR reload re-registered the same id —
+   * never removes a NEWER registration: the handle names one generation, not
+   * the id. */
   dispose(): void;
 }
 /** The command bridge's observable snapshot. */
@@ -391,9 +415,12 @@ interface TuiCommandBridgeSnapshot {
     readonly id: string;
     readonly name: string;
     readonly description: string;
-    readonly execution: 'local' | 'submission';
     readonly sessionless: boolean;
     readonly owner: string;
+    /** Monotonic per-registration generation (diagnostics + the notice
+     * identity): a dispose + re-register under the same id/owner is a NEW
+     * generation, even when both happen inside one coalesced flush. */
+    readonly generation: number;
   }[];
   readonly revision: number;
 }