@tooee/choose 0.2.0 → 0.2.2

package/README.md

@@ -14,6 +14,29 @@ Terminal selection with fuzzy filtering. `Choose` and `ChooseOverlay` are compat
 
 Use `controllerRef` on an assembly, or the controller returned by `useChoose`, to set/clear the filter, move or set the active row, toggle selection, submit/cancel, change mode, or reload the current source.
 
+## Promise-based dialog
+
+`useChooseDialog<T>()` opens `ChooseOverlay` as a modal dialog on the host's
+overlay stack and resolves the typed selection:
+
+```tsx
+const choose = useChooseDialog<Model>()
+
+const model = await choose.open({
+  items: models, // readonly T[] or a sync/async loader
+  toItem: (m) => ({ text: m.label }), // optional when T is a ChooseItem
+  prompt: "Pick a model",
+})
+// T on select, T[] with { multi: true }, null on cancel/replacement/unmount
+```
+
+Generics are retained without casts: single-select resolves `T | null`,
+multi-select resolves `T[] | null` (Choose selection semantics: toggled items,
+falling back to the active item). Each `open()` owns one overlay record
+(unique id per call) and one owned modal command surface; the promise settles
+exactly once. The host must render overlay content (`AppLayout` does; custom
+hosts render `useCurrentOverlay()`).
+
 ## Command surfaces
 
 Built-in interaction uses `useCommand`, so a nested modal command surface suspends the chooser automatically. A filter also blurs while another modal surface owns input. Mouse events bypass command-surface arbitration; pass `suspended` to a custom `ChooseList` host when covered rows can remain visible.

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { ChooseHighlightedText } from "./ChooseHighlightedText.js";
 export type { ChooseHighlightedTextProps } from "./ChooseHighlightedText.js";
 export { useChoose } from "./use-choose.js";
 export type { ChooseCommandGroup, ChooseController, ChooseState, ChooseViewModel, UseChooseOptions, UseChooseResult, } from "./use-choose.js";
+export { useChooseDialog } from "./use-choose-dialog.js";
+export type { ChooseDialogHandle, ChooseDialogItems, ChooseDialogOptions, ChooseDialogOptionsBase, ChooseDialogToItem, } from "./use-choose-dialog.js";
 export { loadChooseSource } from "./source.js";
 export { launch } from "./launch.js";
 export type { ChooseLaunchOptions } from "./launch.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAChE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,YAAY,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,UAAU,EACV,qBAAqB,EACrB,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAChE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,YAAY,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAClE,YAAY,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,UAAU,EACV,qBAAqB,EACrB,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -5,6 +5,7 @@ export { ChooseFilter } from "./ChooseFilter.js";
 export { ChooseList } from "./ChooseList.js";
 export { ChooseHighlightedText } from "./ChooseHighlightedText.js";
 export { useChoose } from "./use-choose.js";
+export { useChooseDialog } from "./use-choose-dialog.js";
 export { loadChooseSource } from "./source.js";
 export { launch } from "./launch.js";
 export { createStdinChooseProvider, createStaticProvider } from "./default-provider.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEhD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAElE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAS3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEhD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAElE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAS3C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAQxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEpF,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,qBAAqB,CAAA;IACtC,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAkDpF"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEpF,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,qBAAqB,CAAA;IACtC,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAiBpF"}

package/dist/launch.js

@@ -1,46 +1,11 @@
 import { jsx as _jsx } from "@opentui/react/jsx-runtime";
-import * as fs from "node:fs";
-import * as tty from "node:tty";
-import { createCliRenderer } from "@opentui/core";
-import { createRoot } from "@opentui/react";
-import { TooeeProvider, guardTerminalHealth } from "@tooee/shell";
+import { runCliSession } from "@tooee/shell";
 import { Choose } from "./Choose.js";
 export async function launch(opts) {
-    // When stdin is piped (not a TTY), open /dev/tty for keyboard input
-    // so the renderer doesn't consume the piped data stream.
-    const stdinIsPiped = !process.stdin.isTTY;
-    let ttyStdin;
-    if (stdinIsPiped) {
-        const fd = fs.openSync("/dev/tty", "r");
-        ttyStdin = new tty.ReadStream(fd);
-    }
-    return new Promise((resolve) => {
-        let renderer = null;
-        const cleanup = (result) => {
-            if (renderer) {
-                renderer.destroy();
-            }
-            if (ttyStdin) {
-                ttyStdin.destroy();
-            }
-            resolve(result);
-        };
-        createCliRenderer({
-            exitOnCtrlC: false,
-            ...(ttyStdin ? { stdin: ttyStdin } : {}),
-        })
-            .then((r) => {
-            renderer = r;
-            guardTerminalHealth(r);
-            createRoot(r).render(_jsx(TooeeProvider, { initialMode: "insert", children: _jsx(Choose, { contentProvider: opts.contentProvider, options: opts.options, actions: opts.actions, onConfirm: (result) => cleanup(result), onCancel: () => cleanup(null) }) }));
-        })
-            .catch(() => {
-            // Renderer init failed — release /dev/tty and resolve so the caller never hangs.
-            if (ttyStdin) {
-                ttyStdin.destroy();
-            }
-            resolve(null);
-        });
+    return runCliSession(({ resolve, cancel }) => (_jsx(Choose, { contentProvider: opts.contentProvider, options: opts.options, actions: opts.actions, onConfirm: resolve, onCancel: cancel })), {
+        exitOnCtrlC: false,
+        provider: { initialMode: "insert" },
+        stdinPolicy: "tty-if-piped",
     });
 }
 //# sourceMappingURL=launch.js.map

package/dist/launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"launch.js","sourceRoot":"","sources":["../src/launch.tsx"],"names":[],"mappings":";AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEjE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AASpC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAyB;IACpD,oEAAoE;IACpE,yDAAyD;IACzD,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAA;IACzC,IAAI,QAAoC,CAAA;IACxC,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAA;QACvC,QAAQ,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACnC,CAAC;IAED,OAAO,IAAI,OAAO,CAAsB,CAAC,OAAO,EAAE,EAAE;QAClD,IAAI,QAAQ,GAAyD,IAAI,CAAA;QAEzE,MAAM,OAAO,GAAG,CAAC,MAA2B,EAAE,EAAE;YAC9C,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,OAAO,EAAE,CAAA;YACpB,CAAC;YACD,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,OAAO,EAAE,CAAA;YACpB,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,CAAA;QACjB,CAAC,CAAA;QAED,iBAAiB,CAAC;YAChB,WAAW,EAAE,KAAK;YAClB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAwC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,CAAC;aACC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YACV,QAAQ,GAAG,CAAC,CAAA;YACZ,mBAAmB,CAAC,CAAC,CAAC,CAAA;YACtB,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAClB,KAAC,aAAa,IAAC,WAAW,EAAC,QAAQ,YACjC,KAAC,MAAM,IACL,eAAe,EAAE,IAAI,CAAC,eAAe,EACrC,OAAO,EAAE,IAAI,CAAC,OAAO,EACrB,OAAO,EAAE,IAAI,CAAC,OAAO,EACrB,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EACtC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAC7B,GACY,CACjB,CAAA;QACH,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,iFAAiF;YACjF,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,OAAO,EAAE,CAAA;YACpB,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAA;QACf,CAAC,CAAC,CAAA;IACN,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../src/launch.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AASpC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAyB;IACpD,OAAO,aAAa,CAClB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CACvB,KAAC,MAAM,IACL,eAAe,EAAE,IAAI,CAAC,eAAe,EACrC,OAAO,EAAE,IAAI,CAAC,OAAO,EACrB,OAAO,EAAE,IAAI,CAAC,OAAO,EACrB,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAE,MAAM,GAChB,CACH,EACD;QACE,WAAW,EAAE,KAAK;QAClB,QAAQ,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE;QACnC,WAAW,EAAE,cAAc;KAC5B,CACF,CAAA;AACH,CAAC"}

package/dist/use-choose-dialog.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+import type { ActionDefinition } from "@tooee/commands";
+import type { ChooseListProps } from "./ChooseList.js";
+import type { ChoosePanelProps } from "./ChoosePanel.js";
+import type { ChooseItem } from "./types.js";
+/** Typed item source: a fixed list, or a loader invoked when the dialog opens. */
+export type ChooseDialogItems<T> = readonly T[] | (() => readonly T[] | Promise<readonly T[]>);
+export interface ChooseDialogOptionsBase<T> {
+    items: ChooseDialogItems<T>;
+    /** Multi-select: Tab toggles, Enter submits the selection (default false). */
+    multi?: boolean;
+    prompt?: string;
+    placeholder?: string;
+    emptyMessage?: string;
+    /**
+     * Extra commands registered on the dialog's own command surface. Handlers
+     * may open further dialogs; the nested dialog suspends this one until it
+     * settles.
+     */
+    commands?: ActionDefinition[];
+    /** Chrome pass-throughs (see ChooseOverlay). */
+    renderItem?: ChooseListProps["renderItem"];
+    hints?: ChoosePanelProps["hints"];
+    statusRight?: ReactNode;
+    footer?: ReactNode;
+    inset?: ChoosePanelProps["inset"];
+}
+/**
+ * Projection from a typed item to the displayed `ChooseItem`. Optional when
+ * `T` is itself a `ChooseItem`; required otherwise, which is what keeps the
+ * public generic cast-free for arbitrary item types.
+ */
+export type ChooseDialogToItem<T> = [T] extends [ChooseItem] ? {
+    toItem?: (item: T) => ChooseItem;
+} : {
+    toItem: (item: T) => ChooseItem;
+};
+export type ChooseDialogOptions<T> = ChooseDialogOptionsBase<T> & ChooseDialogToItem<T>;
+export interface ChooseDialogHandle<T> {
+    /**
+     * Open a modal chooser and resolve with the chosen item(s), or `null` when
+     * the dialog is cancelled, replaced, or unmounted. Settles exactly once per
+     * call. Result shape follows Choose selection semantics: single-select
+     * resolves the confirmed item; multi-select resolves the toggled items
+     * (falling back to the active item when nothing is toggled).
+     */
+    open(options: ChooseDialogOptions<T> & {
+        multi: true;
+    }): Promise<T[] | null>;
+    open(options: ChooseDialogOptions<T> & {
+        multi?: false;
+    }): Promise<T | null>;
+}
+/**
+ * Promise-based modal chooser dialog on the overlay stack.
+ *
+ * Each `open()` owns one modal overlay record and one owned command surface
+ * (via `ownCommands`), so the host app's commands are suspended and its global
+ * mode is never touched while the dialog is up. The returned promise settles
+ * exactly once: with the typed selection, or with `null` on cancel (Escape in
+ * cursor mode, `q`, or the close button), same-id replacement, or unmount of
+ * the owning component.
+ *
+ * The overlay renders wherever the host presents overlay content
+ * (`AppLayout` does this automatically; custom hosts render
+ * `useCurrentOverlay()`).
+ */
+export declare function useChooseDialog<T>(): ChooseDialogHandle<T>;
+//# sourceMappingURL=use-choose-dialog.d.ts.map

package/dist/use-choose-dialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-choose-dialog.d.ts","sourceRoot":"","sources":["../src/use-choose-dialog.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAA;AAU1D,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,SAAS,CAAC,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAA;AAE9F,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;IAC3B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAC7B,gDAAgD;IAChD,UAAU,CAAC,EAAE,eAAe,CAAC,YAAY,CAAC,CAAA;IAC1C,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACjC,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;CAClC;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,GACxD;IAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,UAAU,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,UAAU,CAAA;CAAE,CAAA;AAEvC,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAA;AAEvF,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG;QAAE,KAAK,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAA;IAC5E,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;CAC7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAoI1D"}

package/dist/use-choose-dialog.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx } from "@opentui/react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { useOverlay } from "@tooee/overlays";
+import { ChooseOverlay } from "./ChooseOverlay.js";
+/**
+ * Per-open unique overlay id. A module-level sequence guarantees that
+ * concurrent dialogs — including dialogs opened from separate providers in the
+ * same process — never share an overlay id, so one dialog can never displace
+ * another through same-id replacement.
+ */
+let chooseDialogSequence = 0;
+/**
+ * Promise-based modal chooser dialog on the overlay stack.
+ *
+ * Each `open()` owns one modal overlay record and one owned command surface
+ * (via `ownCommands`), so the host app's commands are suspended and its global
+ * mode is never touched while the dialog is up. The returned promise settles
+ * exactly once: with the typed selection, or with `null` on cancel (Escape in
+ * cursor mode, `q`, or the close button), same-id replacement, or unmount of
+ * the owning component.
+ *
+ * The overlay renders wherever the host presents overlay content
+ * (`AppLayout` does this automatically; custom hosts render
+ * `useCurrentOverlay()`).
+ */
+export function useChooseDialog() {
+    const overlay = useOverlay();
+    const overlayRef = useRef(overlay);
+    overlayRef.current = overlay;
+    // Open dialogs by overlay id, so unmounting the owner closes (and thereby
+    // settles) every dialog it opened.
+    const openHandlesRef = useRef(new Map());
+    const unmountedRef = useRef(false);
+    useEffect(() => {
+        unmountedRef.current = false;
+        const handles = openHandlesRef.current;
+        return () => {
+            unmountedRef.current = true;
+            // Map iteration tolerates deletion: settle() removes entries as each
+            // close lands.
+            for (const handle of handles.values())
+                handle.close("unmounted");
+            handles.clear();
+        };
+    }, []);
+    // Stable identity so command handlers and effects can capture the handle.
+    const handleRef = useRef(null);
+    if (handleRef.current === null) {
+        const open = (options) => {
+            return new Promise((resolvePromise) => {
+                if (unmountedRef.current) {
+                    resolvePromise(null);
+                    return;
+                }
+                const id = `choose-dialog-${++chooseDialogSequence}`;
+                let settled = false;
+                const settle = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    openHandlesRef.current.delete(id);
+                    resolvePromise(value);
+                };
+                // Displayed rows map back to typed items by identity: every mapped
+                // row is a fresh object (spread copy), so duplicates in `items` and
+                // `toItem` results that share references stay unambiguous.
+                // Safe default: `toItem` may only be omitted when T is a ChooseItem
+                // (enforced by ChooseDialogToItem).
+                const toItem = options.toItem ?? ((item) => item);
+                const rowToValue = new Map();
+                const mapValues = (values) => {
+                    rowToValue.clear();
+                    return values.map((value) => {
+                        const row = { ...toItem(value) };
+                        rowToValue.set(row, value);
+                        return row;
+                    });
+                };
+                // Created once per open() so the source identity is stable across
+                // overlay re-renders (a fresh source each render would reload forever).
+                const items = options.items;
+                const source = Array.isArray(items)
+                    ? mapValues(items)
+                    : () => {
+                        const loaded = items();
+                        return loaded instanceof Promise ? loaded.then(mapValues) : mapValues(loaded);
+                    };
+                const multi = options.multi === true;
+                const shared = {
+                    items: source,
+                    prompt: options.prompt,
+                    placeholder: options.placeholder,
+                    emptyMessage: options.emptyMessage,
+                    commands: options.commands,
+                    renderItem: options.renderItem,
+                    hints: options.hints,
+                    statusRight: options.statusRight,
+                    footer: options.footer,
+                    inset: options.inset,
+                };
+                const handle = overlayRef.current.open(id, () => multi ? (_jsx(ChooseOverlay, { ...shared, multi: true, onSubmit: (result) => {
+                        if (settled)
+                            return;
+                        const values = result.items.flatMap((row) => {
+                            const value = rowToValue.get(row);
+                            return value === undefined ? [] : [value];
+                        });
+                        settle(values);
+                        handle.close("close");
+                    }, onCancel: () => handle.close("escape") })) : (_jsx(ChooseOverlay, { ...shared, onSelect: (row) => {
+                        if (settled)
+                            return;
+                        const value = rowToValue.get(row);
+                        settle(value === undefined ? null : value);
+                        handle.close("close");
+                    }, onCancel: () => handle.close("escape") })), undefined, {
+                    ownCommands: true,
+                    role: "modal",
+                    surfaceMode: "insert",
+                    // Single settlement funnel: every close path (cancel, escape,
+                    // replacement, unmount, external closeTop) lands here. Select and
+                    // submit settle first, making this a no-op.
+                    onClose: () => settle(null),
+                });
+                openHandlesRef.current.set(id, handle);
+            });
+        };
+        handleRef.current = { open: open };
+    }
+    return handleRef.current;
+}
+//# sourceMappingURL=use-choose-dialog.js.map

package/dist/use-choose-dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-choose-dialog.js","sourceRoot":"","sources":["../src/use-choose-dialog.tsx"],"names":[],"mappings":"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"}

package/dist/use-choose-dialog.typecheck.d.ts

@@ -0,0 +1,2 @@
+export declare function chooseDialogTypeChecks(): Promise<void>;
+//# sourceMappingURL=use-choose-dialog.typecheck.d.ts.map

package/dist/use-choose-dialog.typecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-choose-dialog.typecheck.d.ts","sourceRoot":"","sources":["../src/use-choose-dialog.typecheck.ts"],"names":[],"mappings":"AAwBA,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkC5D"}

package/dist/use-choose-dialog.typecheck.js

@@ -0,0 +1,32 @@
+// Never called; exists only to be typechecked.
+export async function chooseDialogTypeChecks() {
+    // --- Single select resolves T | null, cast-free ---------------------------
+    const single = await modelDialog.open({
+        items: [{ id: "a", label: "A" }],
+        toItem: (model) => ({ text: model.label }),
+    });
+    if (single !== null) {
+        expectType(single.id);
+    }
+    // --- Multi select resolves T[] | null, cast-free ---------------------------
+    const multi = await modelDialog.open({
+        items: [{ id: "a", label: "A" }],
+        multi: true,
+        toItem: (model) => ({ text: model.label }),
+    });
+    if (multi !== null) {
+        expectType(multi.map((model) => model.id));
+    }
+    // --- toItem may be omitted only when T is a ChooseItem ---------------------
+    const row = await rowDialog.open({ items: [{ text: "one" }] });
+    if (row !== null) {
+        expectType(row.text);
+    }
+    // @ts-expect-error toItem is required when T is not a ChooseItem
+    await modelDialog.open({ items: [{ id: "a", label: "A" }] });
+    // @ts-expect-error toItem must return a ChooseItem
+    await modelDialog.open({ items: [{ id: "a", label: "A" }], toItem: (model) => model });
+    // @ts-expect-error items must be T, not ChooseItem
+    await modelDialog.open({ items: [{ text: "raw" }], toItem: (model) => ({ text: model.label }) });
+}
+//# sourceMappingURL=use-choose-dialog.typecheck.js.map

package/dist/use-choose-dialog.typecheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-choose-dialog.typecheck.js","sourceRoot":"","sources":["../src/use-choose-dialog.typecheck.ts"],"names":[],"mappings":"AAuBA,+CAA+C;AAC/C,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,6EAA6E;IAC7E,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC;QACpC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAChC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;KAC3C,CAAC,CAAA;IACF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,UAAU,CAAS,MAAM,CAAC,EAAE,CAAC,CAAA;IAC/B,CAAC;IAED,8EAA8E;IAC9E,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC;QACnC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAChC,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;KAC3C,CAAC,CAAA;IACF,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,UAAU,CAAW,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,CAAC;IAED,8EAA8E;IAC9E,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;IAC9D,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,UAAU,CAAS,GAAG,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,iEAAiE;IACjE,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAE5D,mDAAmD;IACnD,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAA;IAEtF,mDAAmD;IACnD,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;AAClG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tooee/choose",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Terminal selection with fuzzy filtering",
   "keywords": [
     "cli",
@@ -37,12 +37,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tooee/commands": "0.2.0",
-    "@tooee/fuzzy": "0.2.0",
-    "@tooee/layout": "0.2.0",
-    "@tooee/overlays": "0.2.0",
-    "@tooee/shell": "0.2.0",
-    "@tooee/themes": "0.2.0"
+    "@tooee/commands": "0.2.2",
+    "@tooee/fuzzy": "0.2.2",
+    "@tooee/layout": "0.2.2",
+    "@tooee/overlays": "0.2.2",
+    "@tooee/shell": "0.2.2",
+    "@tooee/themes": "0.2.2"
   },
   "devDependencies": {
     "@opentui/core": "^0.4.3",

package/src/index.ts

@@ -19,6 +19,14 @@ export type {
   UseChooseOptions,
   UseChooseResult,
 } from "./use-choose.js"
+export { useChooseDialog } from "./use-choose-dialog.js"
+export type {
+  ChooseDialogHandle,
+  ChooseDialogItems,
+  ChooseDialogOptions,
+  ChooseDialogOptionsBase,
+  ChooseDialogToItem,
+} from "./use-choose-dialog.js"
 export { loadChooseSource } from "./source.js"
 export { launch } from "./launch.js"
 export type { ChooseLaunchOptions } from "./launch.js"

package/src/launch.tsx

@@ -1,8 +1,4 @@
-import * as fs from "node:fs"
-import * as tty from "node:tty"
-import { createCliRenderer } from "@opentui/core"
-import { createRoot } from "@opentui/react"
-import { TooeeProvider, guardTerminalHealth } from "@tooee/shell"
+import { runCliSession } from "@tooee/shell"
 import type { ActionDefinition } from "@tooee/commands"
 import { Choose } from "./Choose.js"
 import type { ChooseContentProvider, ChooseOptions, ChooseResult } from "./types.js"
@@ -14,53 +10,20 @@ export interface ChooseLaunchOptions {
 }
 
 export async function launch(opts: ChooseLaunchOptions): Promise<ChooseResult | null> {
-  // When stdin is piped (not a TTY), open /dev/tty for keyboard input
-  // so the renderer doesn't consume the piped data stream.
-  const stdinIsPiped = !process.stdin.isTTY
-  let ttyStdin: tty.ReadStream | undefined
-  if (stdinIsPiped) {
-    const fd = fs.openSync("/dev/tty", "r")
-    ttyStdin = new tty.ReadStream(fd)
-  }
-
-  return new Promise<ChooseResult | null>((resolve) => {
-    let renderer: Awaited<ReturnType<typeof createCliRenderer>> | null = null
-
-    const cleanup = (result: ChooseResult | null) => {
-      if (renderer) {
-        renderer.destroy()
-      }
-      if (ttyStdin) {
-        ttyStdin.destroy()
-      }
-      resolve(result)
-    }
-
-    createCliRenderer({
+  return runCliSession<ChooseResult>(
+    ({ resolve, cancel }) => (
+      <Choose
+        contentProvider={opts.contentProvider}
+        options={opts.options}
+        actions={opts.actions}
+        onConfirm={resolve}
+        onCancel={cancel}
+      />
+    ),
+    {
       exitOnCtrlC: false,
-      ...(ttyStdin ? { stdin: ttyStdin as unknown as NodeJS.ReadStream } : {}),
-    })
-      .then((r) => {
-        renderer = r
-        guardTerminalHealth(r)
-        createRoot(r).render(
-          <TooeeProvider initialMode="insert">
-            <Choose
-              contentProvider={opts.contentProvider}
-              options={opts.options}
-              actions={opts.actions}
-              onConfirm={(result) => cleanup(result)}
-              onCancel={() => cleanup(null)}
-            />
-          </TooeeProvider>,
-        )
-      })
-      .catch(() => {
-        // Renderer init failed — release /dev/tty and resolve so the caller never hangs.
-        if (ttyStdin) {
-          ttyStdin.destroy()
-        }
-        resolve(null)
-      })
-  })
+      provider: { initialMode: "insert" },
+      stdinPolicy: "tty-if-piped",
+    },
+  )
 }

package/src/use-choose-dialog.tsx

@@ -0,0 +1,210 @@
+import { useEffect, useRef, type ReactNode } from "react"
+import type { ActionDefinition } from "@tooee/commands"
+import { useOverlay, type OverlayHandle } from "@tooee/overlays"
+import { ChooseOverlay } from "./ChooseOverlay.js"
+import type { ChooseListProps } from "./ChooseList.js"
+import type { ChoosePanelProps } from "./ChoosePanel.js"
+import type { ChooseItem, ChooseSource } from "./types.js"
+
+/**
+ * Per-open unique overlay id. A module-level sequence guarantees that
+ * concurrent dialogs — including dialogs opened from separate providers in the
+ * same process — never share an overlay id, so one dialog can never displace
+ * another through same-id replacement.
+ */
+let chooseDialogSequence = 0
+
+/** Typed item source: a fixed list, or a loader invoked when the dialog opens. */
+export type ChooseDialogItems<T> = readonly T[] | (() => readonly T[] | Promise<readonly T[]>)
+
+export interface ChooseDialogOptionsBase<T> {
+  items: ChooseDialogItems<T>
+  /** Multi-select: Tab toggles, Enter submits the selection (default false). */
+  multi?: boolean
+  prompt?: string
+  placeholder?: string
+  emptyMessage?: string
+  /**
+   * Extra commands registered on the dialog's own command surface. Handlers
+   * may open further dialogs; the nested dialog suspends this one until it
+   * settles.
+   */
+  commands?: ActionDefinition[]
+  /** Chrome pass-throughs (see ChooseOverlay). */
+  renderItem?: ChooseListProps["renderItem"]
+  hints?: ChoosePanelProps["hints"]
+  statusRight?: ReactNode
+  footer?: ReactNode
+  inset?: ChoosePanelProps["inset"]
+}
+
+/**
+ * Projection from a typed item to the displayed `ChooseItem`. Optional when
+ * `T` is itself a `ChooseItem`; required otherwise, which is what keeps the
+ * public generic cast-free for arbitrary item types.
+ */
+export type ChooseDialogToItem<T> = [T] extends [ChooseItem]
+  ? { toItem?: (item: T) => ChooseItem }
+  : { toItem: (item: T) => ChooseItem }
+
+export type ChooseDialogOptions<T> = ChooseDialogOptionsBase<T> & ChooseDialogToItem<T>
+
+export interface ChooseDialogHandle<T> {
+  /**
+   * Open a modal chooser and resolve with the chosen item(s), or `null` when
+   * the dialog is cancelled, replaced, or unmounted. Settles exactly once per
+   * call. Result shape follows Choose selection semantics: single-select
+   * resolves the confirmed item; multi-select resolves the toggled items
+   * (falling back to the active item when nothing is toggled).
+   */
+  open(options: ChooseDialogOptions<T> & { multi: true }): Promise<T[] | null>
+  open(options: ChooseDialogOptions<T> & { multi?: false }): Promise<T | null>
+}
+
+/**
+ * Promise-based modal chooser dialog on the overlay stack.
+ *
+ * Each `open()` owns one modal overlay record and one owned command surface
+ * (via `ownCommands`), so the host app's commands are suspended and its global
+ * mode is never touched while the dialog is up. The returned promise settles
+ * exactly once: with the typed selection, or with `null` on cancel (Escape in
+ * cursor mode, `q`, or the close button), same-id replacement, or unmount of
+ * the owning component.
+ *
+ * The overlay renders wherever the host presents overlay content
+ * (`AppLayout` does this automatically; custom hosts render
+ * `useCurrentOverlay()`).
+ */
+export function useChooseDialog<T>(): ChooseDialogHandle<T> {
+  const overlay = useOverlay()
+  const overlayRef = useRef(overlay)
+  overlayRef.current = overlay
+
+  // Open dialogs by overlay id, so unmounting the owner closes (and thereby
+  // settles) every dialog it opened.
+  const openHandlesRef = useRef(new Map<string, OverlayHandle<undefined>>())
+  const unmountedRef = useRef(false)
+
+  useEffect(() => {
+    unmountedRef.current = false
+    const handles = openHandlesRef.current
+    return () => {
+      unmountedRef.current = true
+      // Map iteration tolerates deletion: settle() removes entries as each
+      // close lands.
+      for (const handle of handles.values()) handle.close("unmounted")
+      handles.clear()
+    }
+  }, [])
+
+  // Stable identity so command handlers and effects can capture the handle.
+  const handleRef = useRef<ChooseDialogHandle<T> | null>(null)
+  if (handleRef.current === null) {
+    const open = (
+      options: ChooseDialogOptionsBase<T> & { toItem?: (item: T) => ChooseItem },
+    ): Promise<T | T[] | null> => {
+      return new Promise<T | T[] | null>((resolvePromise) => {
+        if (unmountedRef.current) {
+          resolvePromise(null)
+          return
+        }
+
+        const id = `choose-dialog-${++chooseDialogSequence}`
+        let settled = false
+        const settle = (value: T | T[] | null) => {
+          if (settled) return
+          settled = true
+          openHandlesRef.current.delete(id)
+          resolvePromise(value)
+        }
+
+        // Displayed rows map back to typed items by identity: every mapped
+        // row is a fresh object (spread copy), so duplicates in `items` and
+        // `toItem` results that share references stay unambiguous.
+        // Safe default: `toItem` may only be omitted when T is a ChooseItem
+        // (enforced by ChooseDialogToItem).
+        const toItem = options.toItem ?? ((item: T) => item as unknown as ChooseItem)
+        const rowToValue = new Map<ChooseItem, T>()
+        const mapValues = (values: readonly T[]): ChooseItem[] => {
+          rowToValue.clear()
+          return values.map((value) => {
+            const row = { ...toItem(value) }
+            rowToValue.set(row, value)
+            return row
+          })
+        }
+
+        // Created once per open() so the source identity is stable across
+        // overlay re-renders (a fresh source each render would reload forever).
+        const items = options.items
+        const source: ChooseSource = Array.isArray(items)
+          ? mapValues(items as readonly T[])
+          : () => {
+              const loaded = (items as () => readonly T[] | Promise<readonly T[]>)()
+              return loaded instanceof Promise ? loaded.then(mapValues) : mapValues(loaded)
+            }
+
+        const multi = options.multi === true
+        const shared = {
+          items: source,
+          prompt: options.prompt,
+          placeholder: options.placeholder,
+          emptyMessage: options.emptyMessage,
+          commands: options.commands,
+          renderItem: options.renderItem,
+          hints: options.hints,
+          statusRight: options.statusRight,
+          footer: options.footer,
+          inset: options.inset,
+        }
+
+        const handle = overlayRef.current.open(
+          id,
+          () =>
+            multi ? (
+              <ChooseOverlay
+                {...shared}
+                multi
+                onSubmit={(result) => {
+                  if (settled) return
+                  const values = result.items.flatMap((row) => {
+                    const value = rowToValue.get(row)
+                    return value === undefined ? [] : [value]
+                  })
+                  settle(values)
+                  handle.close("close")
+                }}
+                onCancel={() => handle.close("escape")}
+              />
+            ) : (
+              <ChooseOverlay
+                {...shared}
+                onSelect={(row) => {
+                  if (settled) return
+                  const value = rowToValue.get(row)
+                  settle(value === undefined ? null : value)
+                  handle.close("close")
+                }}
+                onCancel={() => handle.close("escape")}
+              />
+            ),
+          undefined,
+          {
+            ownCommands: true,
+            role: "modal",
+            surfaceMode: "insert",
+            // Single settlement funnel: every close path (cancel, escape,
+            // replacement, unmount, external closeTop) lands here. Select and
+            // submit settle first, making this a no-op.
+            onClose: () => settle(null),
+          },
+        )
+        openHandlesRef.current.set(id, handle)
+      })
+    }
+
+    handleRef.current = { open: open as ChooseDialogHandle<T>["open"] }
+  }
+
+  return handleRef.current
+}

package/src/use-choose-dialog.typecheck.ts

@@ -0,0 +1,59 @@
+/**
+ * Compile-time regression tests for the typed dialog generics. This module has
+ * no runtime behaviour and is never imported; it exists so that `tsc -b`
+ * (which only checks `src/`) fails if the public generic contract is ever
+ * loosened.
+ *
+ * The contract (roadmap item 4): `useChooseDialog<T>().open(...)` retains the
+ * consumer's item type without casts — single-select resolves `T | null`,
+ * multi-select resolves `T[] | null` — and `toItem` may only be omitted when
+ * `T` is itself a `ChooseItem`.
+ */
+import type { ChooseItem } from "./types.js"
+import type { ChooseDialogHandle } from "./use-choose-dialog.js"
+
+interface Model {
+  id: string
+  label: string
+}
+
+declare const modelDialog: ChooseDialogHandle<Model>
+declare const rowDialog: ChooseDialogHandle<ChooseItem>
+declare function expectType<T>(value: T): void
+
+// Never called; exists only to be typechecked.
+export async function chooseDialogTypeChecks(): Promise<void> {
+  // --- Single select resolves T | null, cast-free ---------------------------
+  const single = await modelDialog.open({
+    items: [{ id: "a", label: "A" }],
+    toItem: (model) => ({ text: model.label }),
+  })
+  if (single !== null) {
+    expectType<string>(single.id)
+  }
+
+  // --- Multi select resolves T[] | null, cast-free ---------------------------
+  const multi = await modelDialog.open({
+    items: [{ id: "a", label: "A" }],
+    multi: true,
+    toItem: (model) => ({ text: model.label }),
+  })
+  if (multi !== null) {
+    expectType<string[]>(multi.map((model) => model.id))
+  }
+
+  // --- toItem may be omitted only when T is a ChooseItem ---------------------
+  const row = await rowDialog.open({ items: [{ text: "one" }] })
+  if (row !== null) {
+    expectType<string>(row.text)
+  }
+
+  // @ts-expect-error toItem is required when T is not a ChooseItem
+  await modelDialog.open({ items: [{ id: "a", label: "A" }] })
+
+  // @ts-expect-error toItem must return a ChooseItem
+  await modelDialog.open({ items: [{ id: "a", label: "A" }], toItem: (model) => model })
+
+  // @ts-expect-error items must be T, not ChooseItem
+  await modelDialog.open({ items: [{ text: "raw" }], toItem: (model) => ({ text: model.label }) })
+}