@ai-matrx/kit 0.9.2 → 0.10.0

package/dist/confirm-opener.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/confirm/opener.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/confirm-opener — the imperative opener, and since 0.9.0 the\n * ONLY half of the confirm system this package ships.\n *\n * Pure-TS imperative API for the global confirm dialog. Zero React, zero\n * dialog markup — this module is statically importable from anywhere\n * (hooks, utils, Redux thunks, async handlers, sync code, anything).\n *\n * The host (`ConfirmDialogHost`, in `@ai-matrx/design-system`) registers a\n * controller on mount and\n * unregisters on unmount. Calls made before the host has hydrated queue\n * up and resolve as soon as the host is alive — so a destructive action\n * triggered in the first ~50ms after page load still gets a real\n * confirmation, never a silent default-yes/no. With no host ever mounted,\n * a `confirm()` promise stays pending forever (the original's behavior —\n * it never resolves to a silent default).\n *\n * One dialog at a time: concurrent calls queue and present sequentially.\n *\n * Ported verbatim from matrx-frontend\n * `components/dialogs/confirm/confirmDialogOpener.ts`, with ONE structural\n * inversion: the host/queue state lives on `globalThis` under a\n * `Symbol.for` slot instead of module-level variables. With the package\n * built `splitting: false` in dual ESM/CJS format, and the host now living in\n * a DIFFERENT PACKAGE, CJS/ESM each instantiate their own module graph — a module-level variable would\n * silently split the host registration from the callers (the same hazard\n * `@ai-matrx/tap-target` documents for its link registry). Behavior is\n * unchanged; never \"clean this up\" into a module local.\n */\n\nimport type { ReactNode } from \"react\";\n\nexport interface ConfirmOptions {\n  title: ReactNode;\n  description?: ReactNode | undefined;\n  confirmLabel?: string | undefined;\n  /** `null` hides the cancel button (acknowledge-only dialogs). */\n  cancelLabel?: string | null | undefined;\n  variant?: \"default\" | \"destructive\" | undefined;\n}\n\ntype Resolver = (confirmed: boolean) => void;\n\ninterface PendingRequest {\n  opts: ConfirmOptions;\n  resolve: Resolver;\n}\n\ninterface HostController {\n  show: (opts: ConfirmOptions, resolve: Resolver) => void;\n}\n\ninterface OpenerState {\n  host: HostController | null;\n  queue: PendingRequest[];\n}\n\nconst STATE_SLOT = Symbol.for(\"ai-matrx.kit.confirm-opener-state\");\n\nfunction getState(): OpenerState {\n  const holder = globalThis as Record<symbol, OpenerState | undefined>;\n  let state = holder[STATE_SLOT];\n  if (!state) {\n    state = { host: null, queue: [] };\n    holder[STATE_SLOT] = state;\n  }\n  return state;\n}\n\n/** @internal Called by `ConfirmDialogHost` on mount. */\nexport function _registerHost(controller: HostController): void {\n  const state = getState();\n  state.host = controller;\n  while (state.queue.length > 0) {\n    const next = state.queue.shift()!;\n    controller.show(next.opts, next.resolve);\n  }\n}\n\n/** @internal Called by `ConfirmDialogHost` on unmount. */\nexport function _unregisterHost(controller: HostController): void {\n  const state = getState();\n  if (state.host === controller) state.host = null;\n}\n\n/** @internal Test-only: drop any registered host and pending queue. */\nexport function _resetConfirmOpenerState(): void {\n  const state = getState();\n  state.host = null;\n  state.queue.length = 0;\n}\n\n/**\n * Imperative confirm. Returns a Promise that resolves `true` if the user\n * confirms, `false` if they cancel/dismiss. Replaces `window.confirm`.\n *\n * @example\n *   const ok = await confirm({\n *     title: \"Delete sandbox\",\n *     description: \"This cannot be undone.\",\n *     variant: \"destructive\",\n *     confirmLabel: \"Delete\",\n *   });\n *   if (!ok) return;\n */\nexport function confirm(opts: ConfirmOptions): Promise<boolean> {\n  return new Promise<boolean>((resolve) => {\n    const state = getState();\n    if (state.host) {\n      state.host.show(opts, resolve);\n    } else {\n      state.queue.push({ opts, resolve });\n    }\n  });\n}\n"],"mappings":";AAyDA,IAAM,aAAa,uBAAO,IAAI,mCAAmC;AAEjE,SAAS,WAAwB;AAC/B,QAAM,SAAS;AACf,MAAI,QAAQ,OAAO,UAAU;AAC7B,MAAI,CAAC,OAAO;AACV,YAAQ,EAAE,MAAM,MAAM,OAAO,CAAC,EAAE;AAChC,WAAO,UAAU,IAAI;AAAA,EACvB;AACA,SAAO;AACT;AAGO,SAAS,cAAc,YAAkC;AAC9D,QAAM,QAAQ,SAAS;AACvB,QAAM,OAAO;AACb,SAAO,MAAM,MAAM,SAAS,GAAG;AAC7B,UAAM,OAAO,MAAM,MAAM,MAAM;AAC/B,eAAW,KAAK,KAAK,MAAM,KAAK,OAAO;AAAA,EACzC;AACF;AAGO,SAAS,gBAAgB,YAAkC;AAChE,QAAM,QAAQ,SAAS;AACvB,MAAI,MAAM,SAAS,WAAY,OAAM,OAAO;AAC9C;AAGO,SAAS,2BAAiC;AAC/C,QAAM,QAAQ,SAAS;AACvB,QAAM,OAAO;AACb,QAAM,MAAM,SAAS;AACvB;AAeO,SAAS,QAAQ,MAAwC;AAC9D,SAAO,IAAI,QAAiB,CAAC,YAAY;AACvC,UAAM,QAAQ,SAAS;AACvB,QAAI,MAAM,MAAM;AACd,YAAM,KAAK,KAAK,MAAM,OAAO;AAAA,IAC/B,OAAO;AACL,YAAM,MAAM,KAAK,EAAE,MAAM,QAAQ,CAAC;AAAA,IACpC;AAAA,EACF,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/opener.ts","../src/confirm/opener.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/opener — THE opener pattern, once.\n *\n * An \"opener\" is the imperative half of a global dialog: a pure-TS function\n * you can `await` from anywhere (a Redux thunk, a util, a sync handler, an\n * async pipeline) that resolves with what the user chose, plus a registry a\n * React host attaches itself to on mount. The whole point is that the CALL\n * SITE never imports the dialog: the opener is zero-React, zero-markup,\n * zero-CSS, so hundreds of static call sites cost nothing and the heavy body\n * stays behind a lazy host.\n *\n * This module is the generic engine. `./confirm-opener` is a three-line\n * specialisation of it, and so is every app-side opener — the sandbox gate,\n * the scope-mismatch gate, the value prompts. Before this existed each one\n * hand-rolled the same `let host`, the same `queue`, the same\n * `_registerHost` drain loop, the same never-resolve-silently promise; four\n * copies of one contract, three of them with module-level state that would\n * have split across loader graphs the moment they left the app.\n *\n * THE CONTRACT — every opener made here behaves identically:\n *\n *  • ONE host at a time. It registers on mount and unregisters on unmount;\n *    a late unmount of a SUPERSEDED host never tears down the live one\n *    (the React double-mount / provider-swap case).\n *  • NEVER a silent default. With no host mounted, `open()` does NOT resolve\n *    to some assumed yes/no — the promise stays pending and the request\n *    queues, so a destructive action fired in the first ~50ms after page load\n *    still gets a real dialog once the host hydrates. Requests are served in\n *    call order.\n *  • NOTHING FAILS SILENTLY (platform law 4). \"Stays pending\" would be an\n *    invisible hang if the host is never mounted at all, so an opener that\n *    has waited `warnWithoutHostAfterMs` with a queued request SCREAMS on the\n *    console, naming the remedy (`hostHint`) — once per opener, cleared the\n *    moment a host registers.\n *  • DEDUPE is opt-in. With a `dedupeKey`, a second `open()` for the same key\n *    while the first is unsettled returns THE SAME promise instead of\n *    stacking a second dialog (double-clicked send buttons).\n *  • CANCELLATION is opt-in per call. Pass an `AbortSignal` and the pending\n *    request is dropped from the queue and settled — resolved with\n *    `onAbortResolveWith` when the caller supplies a neutral answer\n *    (\"cancel\"), rejected with an `AbortError` otherwise. A host that answers\n *    an already-settled request is ignored, never a double-resolve.\n *\n * 🚨 STATE LIVES ON A `globalThis` SLOT, NEVER A MODULE LOCAL. With the\n * package built `splitting: false` in dual ESM/CJS format — and the host\n * routinely living in a DIFFERENT PACKAGE from the caller — each loader graph\n * instantiates its own copy of this module. A module-level `let host` would\n * silently split host registration from the callers: the dialog mounts, the\n * caller queues into a different registry, and the promise hangs forever with\n * no error anywhere. Same hazard `@ai-matrx/tap-target` documents for its link\n * registry. Never \"clean this up\" into a module local; the tarball canary\n * proves the slot spans both graphs.\n */\n\n/** What a mounted host must provide. */\nexport interface OpenerHostController<TRequest, TResponse> {\n  show: (request: TRequest, resolve: (response: TResponse) => void) => void;\n}\n\ninterface PendingEntry<TRequest, TResponse> {\n  request: TRequest;\n  /** Wrapped resolver: settles once, then every later call is a no-op. */\n  settle: (response: TResponse) => void;\n  /** Present only while the entry is still queued (no host yet). */\n  dedupeKey: string | undefined;\n  settled: boolean;\n}\n\ninterface OpenerState<TRequest, TResponse> {\n  host: OpenerHostController<TRequest, TResponse> | null;\n  queue: PendingEntry<TRequest, TResponse>[];\n  /** Unsettled entries by dedupe key — queued AND in-flight at the host. */\n  inFlight: Map<string, { entry: PendingEntry<TRequest, TResponse>; promise: Promise<TResponse> }>;\n  warnTimer: ReturnType<typeof setTimeout> | null;\n  warned: boolean;\n}\n\nexport interface OpenerOptions<TRequest> {\n  /**\n   * Collapse concurrent duplicates. Return a stable string for requests that\n   * must not stack (the same conversation's send gate, say), or `undefined`\n   * to opt this request out of deduping.\n   */\n  dedupeKey?: ((request: TRequest) => string | undefined) | undefined;\n  /**\n   * How long a request may sit queued with no host before the opener screams\n   * on the console. `0` disables the scream (tests, deliberately host-less\n   * environments). Default 5000ms.\n   */\n  warnWithoutHostAfterMs?: number | undefined;\n  /**\n   * The remedy named in that scream — say EXACTLY what to mount and from\n   * where, e.g. `\"<ConfirmDialogHost /> from @ai-matrx/design-system\"`.\n   */\n  hostHint?: string | undefined;\n}\n\nexport interface OpenRequestOptions<TResponse> {\n  /** Abort the request: drops it from the queue and settles the promise. */\n  signal?: AbortSignal | undefined;\n  /**\n   * On abort, resolve with this value instead of rejecting. Use it when the\n   * response type already HAS a neutral answer (`\"cancel\"`, `null`) — an\n   * abort is then indistinguishable from the user dismissing the dialog, and\n   * no call site needs a try/catch.\n   */\n  onAbortResolveWith?: TResponse | undefined;\n}\n\nexport interface Opener<TRequest, TResponse> {\n  /** The `globalThis` slot name this opener's state lives under. */\n  readonly slot: string;\n  /**\n   * Open the dialog. Resolves with the host's answer. With no host mounted\n   * the request queues and the promise stays pending — never a silent\n   * default.\n   */\n  open: (request: TRequest, options?: OpenRequestOptions<TResponse>) => Promise<TResponse>;\n  /** @internal Called by the host component on mount. */\n  _registerHost: (controller: OpenerHostController<TRequest, TResponse>) => void;\n  /** @internal Called by the host component on unmount. */\n  _unregisterHost: (controller: OpenerHostController<TRequest, TResponse>) => void;\n  /** @internal Test-only: drop the registered host, the queue and the timers. */\n  _reset: () => void;\n  /** @internal Diagnostics: is a host currently registered? */\n  _hasHost: () => boolean;\n}\n\n/** Thrown to an aborted `open()` that supplied no `onAbortResolveWith`. */\nexport class OpenerAbortError extends Error {\n  override readonly name = \"AbortError\";\n  constructor(slot: string) {\n    super(`The ${slot} request was aborted before the user answered it.`);\n  }\n}\n\nfunction getState<TRequest, TResponse>(slot: string): OpenerState<TRequest, TResponse> {\n  const holder = globalThis as Record<symbol, unknown>;\n  const symbol = Symbol.for(slot);\n  let state = holder[symbol] as OpenerState<TRequest, TResponse> | undefined;\n  if (!state) {\n    state = { host: null, queue: [], inFlight: new Map(), warnTimer: null, warned: false };\n    holder[symbol] = state;\n  }\n  return state;\n}\n\n/**\n * Build an opener.\n *\n * @param slot The `globalThis` slot name — the opener's identity across every\n *   module graph in the process, so it must be globally unique and stable.\n *   Convention: `\"<owner>.<name>-opener-state\"`, e.g.\n *   `\"ai-matrx.kit.confirm-opener-state\"` or\n *   `\"matrx-frontend.sandbox-gate-opener-state\"`. Changing it after release\n *   splits live hosts from live callers — treat it as a public name.\n *\n * @example\n *   // sandboxGateOpener.ts — the whole module.\n *   const opener = createOpener<SandboxGateOptions, SandboxGateChoice>(\n *     \"matrx-frontend.sandbox-gate-opener-state\",\n *     { hostHint: \"<SandboxGateHost /> (mounted once per provider tree)\" },\n *   );\n *   export const openSandboxGate = opener.open;\n */\nexport function createOpener<TRequest, TResponse>(\n  slot: string,\n  options: OpenerOptions<TRequest> = {},\n): Opener<TRequest, TResponse> {\n  const warnAfterMs = options.warnWithoutHostAfterMs ?? 5000;\n  const hostHint = options.hostHint;\n  const dedupeKeyOf = options.dedupeKey;\n\n  function clearWarnTimer(state: OpenerState<TRequest, TResponse>): void {\n    if (state.warnTimer !== null) {\n      clearTimeout(state.warnTimer);\n      state.warnTimer = null;\n    }\n  }\n\n  function armWarnTimer(state: OpenerState<TRequest, TResponse>): void {\n    if (warnAfterMs <= 0 || state.warned || state.warnTimer !== null) return;\n    state.warnTimer = setTimeout(() => {\n      state.warnTimer = null;\n      if (state.host || state.queue.length === 0) return;\n      state.warned = true;\n      // THE SCREAM. A queued request with no host is a promise that will hang\n      // forever — invisible to the user, invisible in the network tab. Say\n      // what is stuck and exactly what to mount.\n      console.error(\n        `[@ai-matrx/kit/opener] ${state.queue.length} request(s) on \"${slot}\" have been waiting ` +\n          `${warnAfterMs}ms with no host registered, so the awaiting code is stuck and the user ` +\n          `sees nothing. REMEDY: mount ${hostHint ?? `the host for \"${slot}\"`} once, near the root ` +\n          `of this provider tree.`,\n      );\n    }, warnAfterMs);\n    // Never hold a Node process open for a diagnostic timer.\n    (state.warnTimer as unknown as { unref?: () => void }).unref?.();\n  }\n\n  function drainTo(\n    state: OpenerState<TRequest, TResponse>,\n    controller: OpenerHostController<TRequest, TResponse>,\n  ): void {\n    while (state.queue.length > 0) {\n      const next = state.queue.shift()!;\n      if (next.settled) continue;\n      controller.show(next.request, next.settle);\n    }\n  }\n\n  const opener: Opener<TRequest, TResponse> = {\n    slot,\n\n    open(request, requestOptions = {}) {\n      const state = getState<TRequest, TResponse>(slot);\n      const signal = requestOptions.signal;\n      const dedupeKey = dedupeKeyOf?.(request);\n\n      if (dedupeKey !== undefined) {\n        const existing = state.inFlight.get(dedupeKey);\n        // A duplicate NEVER stacks a second dialog: the second caller awaits\n        // the answer the first one is already asking for.\n        if (existing && !existing.entry.settled) return existing.promise;\n      }\n\n      let entry!: PendingEntry<TRequest, TResponse>;\n      const promise = new Promise<TResponse>((resolve, reject) => {\n        const finish = (run: () => void): void => {\n          if (entry.settled) return;\n          entry.settled = true;\n          if (entry.dedupeKey !== undefined) state.inFlight.delete(entry.dedupeKey);\n          const queuedAt = state.queue.indexOf(entry);\n          if (queuedAt >= 0) state.queue.splice(queuedAt, 1);\n          if (state.queue.length === 0) clearWarnTimer(state);\n          run();\n        };\n\n        entry = {\n          request,\n          dedupeKey,\n          settled: false,\n          settle: (response) => finish(() => resolve(response)),\n        };\n\n        const abort = (): void =>\n          finish(() => {\n            if (\"onAbortResolveWith\" in requestOptions && requestOptions.onAbortResolveWith !== undefined) {\n              resolve(requestOptions.onAbortResolveWith);\n            } else {\n              reject(new OpenerAbortError(slot));\n            }\n          });\n\n        if (signal?.aborted) {\n          abort();\n          return;\n        }\n        signal?.addEventListener(\"abort\", abort, { once: true });\n      });\n\n      if (entry.settled) return promise; // aborted before it ever queued\n\n      if (dedupeKey !== undefined) state.inFlight.set(dedupeKey, { entry, promise });\n\n      if (state.host) {\n        state.host.show(entry.request, entry.settle);\n      } else {\n        state.queue.push(entry);\n        armWarnTimer(state);\n      }\n      return promise;\n    },\n\n    _registerHost(controller) {\n      const state = getState<TRequest, TResponse>(slot);\n      state.host = controller;\n      state.warned = false;\n      clearWarnTimer(state);\n      drainTo(state, controller);\n    },\n\n    _unregisterHost(controller) {\n      const state = getState<TRequest, TResponse>(slot);\n      // Only the CURRENT host may unregister: a superseded host's late unmount\n      // must not tear down the live one.\n      if (state.host === controller) state.host = null;\n    },\n\n    _reset() {\n      const state = getState<TRequest, TResponse>(slot);\n      clearWarnTimer(state);\n      state.host = null;\n      state.queue.length = 0;\n      state.inFlight.clear();\n      state.warned = false;\n    },\n\n    _hasHost() {\n      return getState<TRequest, TResponse>(slot).host !== null;\n    },\n  };\n\n  return opener;\n}\n","/**\n * @ai-matrx/kit/confirm-opener — the imperative confirm opener, and since\n * 0.9.0 the ONLY half of the confirm system this package ships.\n *\n * Since 0.10.0 this file is a THIN SPECIALISATION of `../opener`: the\n * host registry, the request queue, the never-resolve-silently promise, the\n * globalThis slot and the no-host scream are all the generic engine's, and\n * what is left here is the confirm-shaped types plus the names call sites\n * already import. There is exactly ONE registry — `createOpener` reads and\n * writes the same `Symbol.for(\"ai-matrx.kit.confirm-opener-state\")` slot this\n * module always used, so a host built against any earlier version still meets\n * its callers.\n *\n * Pure TS, zero React, zero dialog markup — statically importable from\n * anywhere (hooks, utils, Redux thunks, async handlers, sync code).\n *\n * The host (`ConfirmDialogHost`, in `@ai-matrx/design-system`) registers a\n * controller on mount and unregisters on unmount. Calls made before the host\n * has hydrated queue up and resolve as soon as the host is alive — so a\n * destructive action triggered in the first ~50ms after page load still gets a\n * real confirmation, never a silent default-yes/no. With no host EVER mounted\n * the promise stays pending (it never resolves to a silent default) and the\n * opener screams on the console naming the component to mount.\n *\n * One dialog at a time: concurrent calls queue and present sequentially.\n */\n\nimport type { ReactNode } from \"react\";\n\nimport { createOpener, type OpenerHostController } from \"../opener\";\n\nexport interface ConfirmOptions {\n  title: ReactNode;\n  description?: ReactNode | undefined;\n  confirmLabel?: string | undefined;\n  /** `null` hides the cancel button (acknowledge-only dialogs). */\n  cancelLabel?: string | null | undefined;\n  variant?: \"default\" | \"destructive\" | undefined;\n}\n\n/** @internal The shape `ConfirmDialogHost` registers. */\nexport type ConfirmHostController = OpenerHostController<ConfirmOptions, boolean>;\n\n/**\n * The confirm opener itself. Exported for hosts that want the generic\n * `useOpenerHost` machinery (`@ai-matrx/kit/opener-react`) instead of\n * hand-wiring `_registerHost`.\n */\nexport const confirmOpener = createOpener<ConfirmOptions, boolean>(\n  // 🚨 The slot name is a PUBLIC name: it is how callers in one module graph\n  // (or one package) find the host in another. It has been this string since\n  // the opener existed — never change it.\n  \"ai-matrx.kit.confirm-opener-state\",\n  { hostHint: \"<ConfirmDialogHost /> from @ai-matrx/design-system\" },\n);\n\n/** @internal Called by `ConfirmDialogHost` on mount. */\nexport const _registerHost = confirmOpener._registerHost;\n\n/** @internal Called by `ConfirmDialogHost` on unmount. */\nexport const _unregisterHost = confirmOpener._unregisterHost;\n\n/** @internal Test-only: drop any registered host and pending queue. */\nexport const _resetConfirmOpenerState = confirmOpener._reset;\n\n/**\n * Imperative confirm. Returns a Promise that resolves `true` if the user\n * confirms, `false` if they cancel/dismiss. Replaces `window.confirm`.\n *\n * @example\n *   const ok = await confirm({\n *     title: \"Delete sandbox\",\n *     description: \"This cannot be undone.\",\n *     variant: \"destructive\",\n *     confirmLabel: \"Delete\",\n *   });\n *   if (!ok) return;\n */\nexport function confirm(opts: ConfirmOptions): Promise<boolean> {\n  return confirmOpener.open(opts);\n}\n"],"mappings":"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","names":[]}

package/dist/opener-react.cjs

@@ -0,0 +1,70 @@
+"use client";
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/opener-react.ts
+var opener_react_exports = {};
+__export(opener_react_exports, {
+  useOpenerHost: () => useOpenerHost
+});
+module.exports = __toCommonJS(opener_react_exports);
+var React = __toESM(require("react"), 1);
+function useOpenerHost(opener, options = {}) {
+  const [active, setActive] = React.useState(null);
+  const [tick, setTick] = React.useState(0);
+  const queueRef = React.useRef([]);
+  const onActivateRef = React.useRef(options.onActivate);
+  onActivateRef.current = options.onActivate;
+  React.useEffect(() => {
+    const controller = {
+      show: (request, resolve) => {
+        queueRef.current.push({ request, resolve });
+        setTick((n) => n + 1);
+      }
+    };
+    opener._registerHost(controller);
+    return () => opener._unregisterHost(controller);
+  }, [opener]);
+  React.useEffect(() => {
+    if (active === null && queueRef.current.length > 0) {
+      const next = queueRef.current.shift();
+      onActivateRef.current?.(next.request);
+      setActive(next);
+    }
+  }, [active, tick]);
+  const settle = React.useCallback((response) => {
+    setActive((current) => {
+      if (current === null) return null;
+      current.resolve(response);
+      return null;
+    });
+  }, []);
+  return { request: active?.request ?? null, open: active !== null, settle };
+}
+//# sourceMappingURL=opener-react.cjs.map

package/dist/opener-react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/opener-react.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/opener-react — `useOpenerHost`, the other half of `./opener`.\n *\n * Every host of an opener-backed dialog was writing the SAME twenty lines:\n * a ref-backed queue, a `tick` counter to wake a drain effect, a\n * register/unregister effect, and a `settle` callback that resolves the\n * active request exactly once and clears it. Four copies existed across kit's\n * confirm host and three matrx-frontend dialogs, each with its own chance to\n * get the stale-closure bug wrong. This is that machinery, once.\n *\n * It is a pure hook — React and nothing else. No markup, no CSS, no radix, no\n * design-system import, so it stays BELOW design-system in the package DAG\n * and any host in any package or app can use it: the dialog body is entirely\n * the host's business, and hosts differ wildly (an AlertDialog, a form, a\n * whole embedded panel).\n *\n * @example\n *   function SandboxGateHostImpl() {\n *     const { request, open, settle } = useOpenerHost(sandboxGateOpener);\n *     return (\n *       <Dialog open={open} onOpenChange={(o) => { if (!o) settle(\"cancel\"); }}>\n *         ...\n *       </Dialog>\n *     );\n *   }\n */\n\nimport * as React from \"react\";\n\nimport type { Opener, OpenerHostController } from \"./opener\";\n\ninterface ActiveRequest<TRequest, TResponse> {\n  request: TRequest;\n  resolve: (response: TResponse) => void;\n}\n\nexport interface UseOpenerHostOptions<TRequest> {\n  /**\n   * Called synchronously as a request becomes the active one, inside the same\n   * React update — the place to seed per-request form state from the request\n   * (default answers, for instance) with no intermediate render showing the\n   * previous request's values.\n   */\n  onActivate?: ((request: TRequest) => void) | undefined;\n}\n\nexport interface OpenerHostState<TRequest, TResponse> {\n  /** The request being shown, or `null` when the dialog is closed. */\n  request: TRequest | null;\n  /** Convenience for `request !== null` — feed it straight to `open=`. */\n  open: boolean;\n  /**\n   * Answer the active request and close. Safe to call when nothing is active\n   * (a no-op) and safe to call twice (the second is ignored) — a dismiss\n   * handler firing alongside a button click is the normal case, not a bug.\n   */\n  settle: (response: TResponse) => void;\n}\n\n/**\n * Mount-side of an opener: registers this component as THE host, drains\n * queued requests one at a time, and hands you the active request plus the\n * one way to answer it.\n *\n * Render this hook's component exactly ONCE per provider tree. Mounting two\n * hosts for one opener is not an error the opener can detect as such — the\n * second simply becomes the live one — so keep the mount where the other\n * global hosts live.\n */\nexport function useOpenerHost<TRequest, TResponse>(\n  opener: Opener<TRequest, TResponse>,\n  options: UseOpenerHostOptions<TRequest> = {},\n): OpenerHostState<TRequest, TResponse> {\n  const [active, setActive] = React.useState<ActiveRequest<TRequest, TResponse> | null>(null);\n  const [tick, setTick] = React.useState(0);\n  const queueRef = React.useRef<ActiveRequest<TRequest, TResponse>[]>([]);\n\n  // Read `onActivate` through a ref: the caller almost always passes an inline\n  // function, and it must not re-run the registration effect.\n  const onActivateRef = React.useRef(options.onActivate);\n  onActivateRef.current = options.onActivate;\n\n  // Register/unregister exactly once. The controller's `show` always pushes\n  // onto the queue and bumps `tick`; the drain effect below picks up from\n  // there. That indirection is what keeps `active` out of this closure.\n  React.useEffect(() => {\n    const controller: OpenerHostController<TRequest, TResponse> = {\n      show: (request, resolve) => {\n        queueRef.current.push({ request, resolve });\n        setTick((n) => n + 1);\n      },\n    };\n    opener._registerHost(controller);\n    return () => opener._unregisterHost(controller);\n  }, [opener]);\n\n  // Drain whenever nothing is showing. One dialog at a time, in call order.\n  React.useEffect(() => {\n    if (active === null && queueRef.current.length > 0) {\n      const next = queueRef.current.shift()!;\n      onActivateRef.current?.(next.request);\n      setActive(next);\n    }\n  }, [active, tick]);\n\n  const settle = React.useCallback((response: TResponse) => {\n    setActive((current) => {\n      if (current === null) return null;\n      current.resolve(response);\n      return null;\n    });\n  }, []);\n\n  return { request: active?.request ?? null, open: active !== null, settle };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BA,YAAuB;AA0ChB,SAAS,cACd,QACA,UAA0C,CAAC,GACL;AACtC,QAAM,CAAC,QAAQ,SAAS,IAAU,eAAoD,IAAI;AAC1F,QAAM,CAAC,MAAM,OAAO,IAAU,eAAS,CAAC;AACxC,QAAM,WAAiB,aAA6C,CAAC,CAAC;AAItE,QAAM,gBAAsB,aAAO,QAAQ,UAAU;AACrD,gBAAc,UAAU,QAAQ;AAKhC,EAAM,gBAAU,MAAM;AACpB,UAAM,aAAwD;AAAA,MAC5D,MAAM,CAAC,SAAS,YAAY;AAC1B,iBAAS,QAAQ,KAAK,EAAE,SAAS,QAAQ,CAAC;AAC1C,gBAAQ,CAAC,MAAM,IAAI,CAAC;AAAA,MACtB;AAAA,IACF;AACA,WAAO,cAAc,UAAU;AAC/B,WAAO,MAAM,OAAO,gBAAgB,UAAU;AAAA,EAChD,GAAG,CAAC,MAAM,CAAC;AAGX,EAAM,gBAAU,MAAM;AACpB,QAAI,WAAW,QAAQ,SAAS,QAAQ,SAAS,GAAG;AAClD,YAAM,OAAO,SAAS,QAAQ,MAAM;AACpC,oBAAc,UAAU,KAAK,OAAO;AACpC,gBAAU,IAAI;AAAA,IAChB;AAAA,EACF,GAAG,CAAC,QAAQ,IAAI,CAAC;AAEjB,QAAM,SAAe,kBAAY,CAAC,aAAwB;AACxD,cAAU,CAAC,YAAY;AACrB,UAAI,YAAY,KAAM,QAAO;AAC7B,cAAQ,QAAQ,QAAQ;AACxB,aAAO;AAAA,IACT,CAAC;AAAA,EACH,GAAG,CAAC,CAAC;AAEL,SAAO,EAAE,SAAS,QAAQ,WAAW,MAAM,MAAM,WAAW,MAAM,OAAO;AAC3E;","names":[]}

package/dist/opener-react.d.cts

@@ -0,0 +1,148 @@
+/**
+ * @ai-matrx/kit/opener — THE opener pattern, once.
+ *
+ * An "opener" is the imperative half of a global dialog: a pure-TS function
+ * you can `await` from anywhere (a Redux thunk, a util, a sync handler, an
+ * async pipeline) that resolves with what the user chose, plus a registry a
+ * React host attaches itself to on mount. The whole point is that the CALL
+ * SITE never imports the dialog: the opener is zero-React, zero-markup,
+ * zero-CSS, so hundreds of static call sites cost nothing and the heavy body
+ * stays behind a lazy host.
+ *
+ * This module is the generic engine. `./confirm-opener` is a three-line
+ * specialisation of it, and so is every app-side opener — the sandbox gate,
+ * the scope-mismatch gate, the value prompts. Before this existed each one
+ * hand-rolled the same `let host`, the same `queue`, the same
+ * `_registerHost` drain loop, the same never-resolve-silently promise; four
+ * copies of one contract, three of them with module-level state that would
+ * have split across loader graphs the moment they left the app.
+ *
+ * THE CONTRACT — every opener made here behaves identically:
+ *
+ *  • ONE host at a time. It registers on mount and unregisters on unmount;
+ *    a late unmount of a SUPERSEDED host never tears down the live one
+ *    (the React double-mount / provider-swap case).
+ *  • NEVER a silent default. With no host mounted, `open()` does NOT resolve
+ *    to some assumed yes/no — the promise stays pending and the request
+ *    queues, so a destructive action fired in the first ~50ms after page load
+ *    still gets a real dialog once the host hydrates. Requests are served in
+ *    call order.
+ *  • NOTHING FAILS SILENTLY (platform law 4). "Stays pending" would be an
+ *    invisible hang if the host is never mounted at all, so an opener that
+ *    has waited `warnWithoutHostAfterMs` with a queued request SCREAMS on the
+ *    console, naming the remedy (`hostHint`) — once per opener, cleared the
+ *    moment a host registers.
+ *  • DEDUPE is opt-in. With a `dedupeKey`, a second `open()` for the same key
+ *    while the first is unsettled returns THE SAME promise instead of
+ *    stacking a second dialog (double-clicked send buttons).
+ *  • CANCELLATION is opt-in per call. Pass an `AbortSignal` and the pending
+ *    request is dropped from the queue and settled — resolved with
+ *    `onAbortResolveWith` when the caller supplies a neutral answer
+ *    ("cancel"), rejected with an `AbortError` otherwise. A host that answers
+ *    an already-settled request is ignored, never a double-resolve.
+ *
+ * 🚨 STATE LIVES ON A `globalThis` SLOT, NEVER A MODULE LOCAL. With the
+ * package built `splitting: false` in dual ESM/CJS format — and the host
+ * routinely living in a DIFFERENT PACKAGE from the caller — each loader graph
+ * instantiates its own copy of this module. A module-level `let host` would
+ * silently split host registration from the callers: the dialog mounts, the
+ * caller queues into a different registry, and the promise hangs forever with
+ * no error anywhere. Same hazard `@ai-matrx/tap-target` documents for its link
+ * registry. Never "clean this up" into a module local; the tarball canary
+ * proves the slot spans both graphs.
+ */
+/** What a mounted host must provide. */
+interface OpenerHostController<TRequest, TResponse> {
+    show: (request: TRequest, resolve: (response: TResponse) => void) => void;
+}
+interface OpenRequestOptions<TResponse> {
+    /** Abort the request: drops it from the queue and settles the promise. */
+    signal?: AbortSignal | undefined;
+    /**
+     * On abort, resolve with this value instead of rejecting. Use it when the
+     * response type already HAS a neutral answer (`"cancel"`, `null`) — an
+     * abort is then indistinguishable from the user dismissing the dialog, and
+     * no call site needs a try/catch.
+     */
+    onAbortResolveWith?: TResponse | undefined;
+}
+interface Opener<TRequest, TResponse> {
+    /** The `globalThis` slot name this opener's state lives under. */
+    readonly slot: string;
+    /**
+     * Open the dialog. Resolves with the host's answer. With no host mounted
+     * the request queues and the promise stays pending — never a silent
+     * default.
+     */
+    open: (request: TRequest, options?: OpenRequestOptions<TResponse>) => Promise<TResponse>;
+    /** @internal Called by the host component on mount. */
+    _registerHost: (controller: OpenerHostController<TRequest, TResponse>) => void;
+    /** @internal Called by the host component on unmount. */
+    _unregisterHost: (controller: OpenerHostController<TRequest, TResponse>) => void;
+    /** @internal Test-only: drop the registered host, the queue and the timers. */
+    _reset: () => void;
+    /** @internal Diagnostics: is a host currently registered? */
+    _hasHost: () => boolean;
+}
+
+/**
+ * @ai-matrx/kit/opener-react — `useOpenerHost`, the other half of `./opener`.
+ *
+ * Every host of an opener-backed dialog was writing the SAME twenty lines:
+ * a ref-backed queue, a `tick` counter to wake a drain effect, a
+ * register/unregister effect, and a `settle` callback that resolves the
+ * active request exactly once and clears it. Four copies existed across kit's
+ * confirm host and three matrx-frontend dialogs, each with its own chance to
+ * get the stale-closure bug wrong. This is that machinery, once.
+ *
+ * It is a pure hook — React and nothing else. No markup, no CSS, no radix, no
+ * design-system import, so it stays BELOW design-system in the package DAG
+ * and any host in any package or app can use it: the dialog body is entirely
+ * the host's business, and hosts differ wildly (an AlertDialog, a form, a
+ * whole embedded panel).
+ *
+ * @example
+ *   function SandboxGateHostImpl() {
+ *     const { request, open, settle } = useOpenerHost(sandboxGateOpener);
+ *     return (
+ *       <Dialog open={open} onOpenChange={(o) => { if (!o) settle("cancel"); }}>
+ *         ...
+ *       </Dialog>
+ *     );
+ *   }
+ */
+
+interface UseOpenerHostOptions<TRequest> {
+    /**
+     * Called synchronously as a request becomes the active one, inside the same
+     * React update — the place to seed per-request form state from the request
+     * (default answers, for instance) with no intermediate render showing the
+     * previous request's values.
+     */
+    onActivate?: ((request: TRequest) => void) | undefined;
+}
+interface OpenerHostState<TRequest, TResponse> {
+    /** The request being shown, or `null` when the dialog is closed. */
+    request: TRequest | null;
+    /** Convenience for `request !== null` — feed it straight to `open=`. */
+    open: boolean;
+    /**
+     * Answer the active request and close. Safe to call when nothing is active
+     * (a no-op) and safe to call twice (the second is ignored) — a dismiss
+     * handler firing alongside a button click is the normal case, not a bug.
+     */
+    settle: (response: TResponse) => void;
+}
+/**
+ * Mount-side of an opener: registers this component as THE host, drains
+ * queued requests one at a time, and hands you the active request plus the
+ * one way to answer it.
+ *
+ * Render this hook's component exactly ONCE per provider tree. Mounting two
+ * hosts for one opener is not an error the opener can detect as such — the
+ * second simply becomes the live one — so keep the mount where the other
+ * global hosts live.
+ */
+declare function useOpenerHost<TRequest, TResponse>(opener: Opener<TRequest, TResponse>, options?: UseOpenerHostOptions<TRequest>): OpenerHostState<TRequest, TResponse>;
+
+export { type OpenerHostState, type UseOpenerHostOptions, useOpenerHost };

package/dist/opener-react.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @ai-matrx/kit/opener — THE opener pattern, once.
+ *
+ * An "opener" is the imperative half of a global dialog: a pure-TS function
+ * you can `await` from anywhere (a Redux thunk, a util, a sync handler, an
+ * async pipeline) that resolves with what the user chose, plus a registry a
+ * React host attaches itself to on mount. The whole point is that the CALL
+ * SITE never imports the dialog: the opener is zero-React, zero-markup,
+ * zero-CSS, so hundreds of static call sites cost nothing and the heavy body
+ * stays behind a lazy host.
+ *
+ * This module is the generic engine. `./confirm-opener` is a three-line
+ * specialisation of it, and so is every app-side opener — the sandbox gate,
+ * the scope-mismatch gate, the value prompts. Before this existed each one
+ * hand-rolled the same `let host`, the same `queue`, the same
+ * `_registerHost` drain loop, the same never-resolve-silently promise; four
+ * copies of one contract, three of them with module-level state that would
+ * have split across loader graphs the moment they left the app.
+ *
+ * THE CONTRACT — every opener made here behaves identically:
+ *
+ *  • ONE host at a time. It registers on mount and unregisters on unmount;
+ *    a late unmount of a SUPERSEDED host never tears down the live one
+ *    (the React double-mount / provider-swap case).
+ *  • NEVER a silent default. With no host mounted, `open()` does NOT resolve
+ *    to some assumed yes/no — the promise stays pending and the request
+ *    queues, so a destructive action fired in the first ~50ms after page load
+ *    still gets a real dialog once the host hydrates. Requests are served in
+ *    call order.
+ *  • NOTHING FAILS SILENTLY (platform law 4). "Stays pending" would be an
+ *    invisible hang if the host is never mounted at all, so an opener that
+ *    has waited `warnWithoutHostAfterMs` with a queued request SCREAMS on the
+ *    console, naming the remedy (`hostHint`) — once per opener, cleared the
+ *    moment a host registers.
+ *  • DEDUPE is opt-in. With a `dedupeKey`, a second `open()` for the same key
+ *    while the first is unsettled returns THE SAME promise instead of
+ *    stacking a second dialog (double-clicked send buttons).
+ *  • CANCELLATION is opt-in per call. Pass an `AbortSignal` and the pending
+ *    request is dropped from the queue and settled — resolved with
+ *    `onAbortResolveWith` when the caller supplies a neutral answer
+ *    ("cancel"), rejected with an `AbortError` otherwise. A host that answers
+ *    an already-settled request is ignored, never a double-resolve.
+ *
+ * 🚨 STATE LIVES ON A `globalThis` SLOT, NEVER A MODULE LOCAL. With the
+ * package built `splitting: false` in dual ESM/CJS format — and the host
+ * routinely living in a DIFFERENT PACKAGE from the caller — each loader graph
+ * instantiates its own copy of this module. A module-level `let host` would
+ * silently split host registration from the callers: the dialog mounts, the
+ * caller queues into a different registry, and the promise hangs forever with
+ * no error anywhere. Same hazard `@ai-matrx/tap-target` documents for its link
+ * registry. Never "clean this up" into a module local; the tarball canary
+ * proves the slot spans both graphs.
+ */
+/** What a mounted host must provide. */
+interface OpenerHostController<TRequest, TResponse> {
+    show: (request: TRequest, resolve: (response: TResponse) => void) => void;
+}
+interface OpenRequestOptions<TResponse> {
+    /** Abort the request: drops it from the queue and settles the promise. */
+    signal?: AbortSignal | undefined;
+    /**
+     * On abort, resolve with this value instead of rejecting. Use it when the
+     * response type already HAS a neutral answer (`"cancel"`, `null`) — an
+     * abort is then indistinguishable from the user dismissing the dialog, and
+     * no call site needs a try/catch.
+     */
+    onAbortResolveWith?: TResponse | undefined;
+}
+interface Opener<TRequest, TResponse> {
+    /** The `globalThis` slot name this opener's state lives under. */
+    readonly slot: string;
+    /**
+     * Open the dialog. Resolves with the host's answer. With no host mounted
+     * the request queues and the promise stays pending — never a silent
+     * default.
+     */
+    open: (request: TRequest, options?: OpenRequestOptions<TResponse>) => Promise<TResponse>;
+    /** @internal Called by the host component on mount. */
+    _registerHost: (controller: OpenerHostController<TRequest, TResponse>) => void;
+    /** @internal Called by the host component on unmount. */
+    _unregisterHost: (controller: OpenerHostController<TRequest, TResponse>) => void;
+    /** @internal Test-only: drop the registered host, the queue and the timers. */
+    _reset: () => void;
+    /** @internal Diagnostics: is a host currently registered? */
+    _hasHost: () => boolean;
+}
+
+/**
+ * @ai-matrx/kit/opener-react — `useOpenerHost`, the other half of `./opener`.
+ *
+ * Every host of an opener-backed dialog was writing the SAME twenty lines:
+ * a ref-backed queue, a `tick` counter to wake a drain effect, a
+ * register/unregister effect, and a `settle` callback that resolves the
+ * active request exactly once and clears it. Four copies existed across kit's
+ * confirm host and three matrx-frontend dialogs, each with its own chance to
+ * get the stale-closure bug wrong. This is that machinery, once.
+ *
+ * It is a pure hook — React and nothing else. No markup, no CSS, no radix, no
+ * design-system import, so it stays BELOW design-system in the package DAG
+ * and any host in any package or app can use it: the dialog body is entirely
+ * the host's business, and hosts differ wildly (an AlertDialog, a form, a
+ * whole embedded panel).
+ *
+ * @example
+ *   function SandboxGateHostImpl() {
+ *     const { request, open, settle } = useOpenerHost(sandboxGateOpener);
+ *     return (
+ *       <Dialog open={open} onOpenChange={(o) => { if (!o) settle("cancel"); }}>
+ *         ...
+ *       </Dialog>
+ *     );
+ *   }
+ */
+
+interface UseOpenerHostOptions<TRequest> {
+    /**
+     * Called synchronously as a request becomes the active one, inside the same
+     * React update — the place to seed per-request form state from the request
+     * (default answers, for instance) with no intermediate render showing the
+     * previous request's values.
+     */
+    onActivate?: ((request: TRequest) => void) | undefined;
+}
+interface OpenerHostState<TRequest, TResponse> {
+    /** The request being shown, or `null` when the dialog is closed. */
+    request: TRequest | null;
+    /** Convenience for `request !== null` — feed it straight to `open=`. */
+    open: boolean;
+    /**
+     * Answer the active request and close. Safe to call when nothing is active
+     * (a no-op) and safe to call twice (the second is ignored) — a dismiss
+     * handler firing alongside a button click is the normal case, not a bug.
+     */
+    settle: (response: TResponse) => void;
+}
+/**
+ * Mount-side of an opener: registers this component as THE host, drains
+ * queued requests one at a time, and hands you the active request plus the
+ * one way to answer it.
+ *
+ * Render this hook's component exactly ONCE per provider tree. Mounting two
+ * hosts for one opener is not an error the opener can detect as such — the
+ * second simply becomes the live one — so keep the mount where the other
+ * global hosts live.
+ */
+declare function useOpenerHost<TRequest, TResponse>(opener: Opener<TRequest, TResponse>, options?: UseOpenerHostOptions<TRequest>): OpenerHostState<TRequest, TResponse>;
+
+export { type OpenerHostState, type UseOpenerHostOptions, useOpenerHost };

package/dist/opener-react.js

@@ -0,0 +1,40 @@
+"use client";
+
+// src/opener-react.ts
+import * as React from "react";
+function useOpenerHost(opener, options = {}) {
+  const [active, setActive] = React.useState(null);
+  const [tick, setTick] = React.useState(0);
+  const queueRef = React.useRef([]);
+  const onActivateRef = React.useRef(options.onActivate);
+  onActivateRef.current = options.onActivate;
+  React.useEffect(() => {
+    const controller = {
+      show: (request, resolve) => {
+        queueRef.current.push({ request, resolve });
+        setTick((n) => n + 1);
+      }
+    };
+    opener._registerHost(controller);
+    return () => opener._unregisterHost(controller);
+  }, [opener]);
+  React.useEffect(() => {
+    if (active === null && queueRef.current.length > 0) {
+      const next = queueRef.current.shift();
+      onActivateRef.current?.(next.request);
+      setActive(next);
+    }
+  }, [active, tick]);
+  const settle = React.useCallback((response) => {
+    setActive((current) => {
+      if (current === null) return null;
+      current.resolve(response);
+      return null;
+    });
+  }, []);
+  return { request: active?.request ?? null, open: active !== null, settle };
+}
+export {
+  useOpenerHost
+};
+//# sourceMappingURL=opener-react.js.map

package/dist/opener-react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/opener-react.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/opener-react — `useOpenerHost`, the other half of `./opener`.\n *\n * Every host of an opener-backed dialog was writing the SAME twenty lines:\n * a ref-backed queue, a `tick` counter to wake a drain effect, a\n * register/unregister effect, and a `settle` callback that resolves the\n * active request exactly once and clears it. Four copies existed across kit's\n * confirm host and three matrx-frontend dialogs, each with its own chance to\n * get the stale-closure bug wrong. This is that machinery, once.\n *\n * It is a pure hook — React and nothing else. No markup, no CSS, no radix, no\n * design-system import, so it stays BELOW design-system in the package DAG\n * and any host in any package or app can use it: the dialog body is entirely\n * the host's business, and hosts differ wildly (an AlertDialog, a form, a\n * whole embedded panel).\n *\n * @example\n *   function SandboxGateHostImpl() {\n *     const { request, open, settle } = useOpenerHost(sandboxGateOpener);\n *     return (\n *       <Dialog open={open} onOpenChange={(o) => { if (!o) settle(\"cancel\"); }}>\n *         ...\n *       </Dialog>\n *     );\n *   }\n */\n\nimport * as React from \"react\";\n\nimport type { Opener, OpenerHostController } from \"./opener\";\n\ninterface ActiveRequest<TRequest, TResponse> {\n  request: TRequest;\n  resolve: (response: TResponse) => void;\n}\n\nexport interface UseOpenerHostOptions<TRequest> {\n  /**\n   * Called synchronously as a request becomes the active one, inside the same\n   * React update — the place to seed per-request form state from the request\n   * (default answers, for instance) with no intermediate render showing the\n   * previous request's values.\n   */\n  onActivate?: ((request: TRequest) => void) | undefined;\n}\n\nexport interface OpenerHostState<TRequest, TResponse> {\n  /** The request being shown, or `null` when the dialog is closed. */\n  request: TRequest | null;\n  /** Convenience for `request !== null` — feed it straight to `open=`. */\n  open: boolean;\n  /**\n   * Answer the active request and close. Safe to call when nothing is active\n   * (a no-op) and safe to call twice (the second is ignored) — a dismiss\n   * handler firing alongside a button click is the normal case, not a bug.\n   */\n  settle: (response: TResponse) => void;\n}\n\n/**\n * Mount-side of an opener: registers this component as THE host, drains\n * queued requests one at a time, and hands you the active request plus the\n * one way to answer it.\n *\n * Render this hook's component exactly ONCE per provider tree. Mounting two\n * hosts for one opener is not an error the opener can detect as such — the\n * second simply becomes the live one — so keep the mount where the other\n * global hosts live.\n */\nexport function useOpenerHost<TRequest, TResponse>(\n  opener: Opener<TRequest, TResponse>,\n  options: UseOpenerHostOptions<TRequest> = {},\n): OpenerHostState<TRequest, TResponse> {\n  const [active, setActive] = React.useState<ActiveRequest<TRequest, TResponse> | null>(null);\n  const [tick, setTick] = React.useState(0);\n  const queueRef = React.useRef<ActiveRequest<TRequest, TResponse>[]>([]);\n\n  // Read `onActivate` through a ref: the caller almost always passes an inline\n  // function, and it must not re-run the registration effect.\n  const onActivateRef = React.useRef(options.onActivate);\n  onActivateRef.current = options.onActivate;\n\n  // Register/unregister exactly once. The controller's `show` always pushes\n  // onto the queue and bumps `tick`; the drain effect below picks up from\n  // there. That indirection is what keeps `active` out of this closure.\n  React.useEffect(() => {\n    const controller: OpenerHostController<TRequest, TResponse> = {\n      show: (request, resolve) => {\n        queueRef.current.push({ request, resolve });\n        setTick((n) => n + 1);\n      },\n    };\n    opener._registerHost(controller);\n    return () => opener._unregisterHost(controller);\n  }, [opener]);\n\n  // Drain whenever nothing is showing. One dialog at a time, in call order.\n  React.useEffect(() => {\n    if (active === null && queueRef.current.length > 0) {\n      const next = queueRef.current.shift()!;\n      onActivateRef.current?.(next.request);\n      setActive(next);\n    }\n  }, [active, tick]);\n\n  const settle = React.useCallback((response: TResponse) => {\n    setActive((current) => {\n      if (current === null) return null;\n      current.resolve(response);\n      return null;\n    });\n  }, []);\n\n  return { request: active?.request ?? null, open: active !== null, settle };\n}\n"],"mappings":";;;AA2BA,YAAY,WAAW;AA0ChB,SAAS,cACd,QACA,UAA0C,CAAC,GACL;AACtC,QAAM,CAAC,QAAQ,SAAS,IAAU,eAAoD,IAAI;AAC1F,QAAM,CAAC,MAAM,OAAO,IAAU,eAAS,CAAC;AACxC,QAAM,WAAiB,aAA6C,CAAC,CAAC;AAItE,QAAM,gBAAsB,aAAO,QAAQ,UAAU;AACrD,gBAAc,UAAU,QAAQ;AAKhC,EAAM,gBAAU,MAAM;AACpB,UAAM,aAAwD;AAAA,MAC5D,MAAM,CAAC,SAAS,YAAY;AAC1B,iBAAS,QAAQ,KAAK,EAAE,SAAS,QAAQ,CAAC;AAC1C,gBAAQ,CAAC,MAAM,IAAI,CAAC;AAAA,MACtB;AAAA,IACF;AACA,WAAO,cAAc,UAAU;AAC/B,WAAO,MAAM,OAAO,gBAAgB,UAAU;AAAA,EAChD,GAAG,CAAC,MAAM,CAAC;AAGX,EAAM,gBAAU,MAAM;AACpB,QAAI,WAAW,QAAQ,SAAS,QAAQ,SAAS,GAAG;AAClD,YAAM,OAAO,SAAS,QAAQ,MAAM;AACpC,oBAAc,UAAU,KAAK,OAAO;AACpC,gBAAU,IAAI;AAAA,IAChB;AAAA,EACF,GAAG,CAAC,QAAQ,IAAI,CAAC;AAEjB,QAAM,SAAe,kBAAY,CAAC,aAAwB;AACxD,cAAU,CAAC,YAAY;AACrB,UAAI,YAAY,KAAM,QAAO;AAC7B,cAAQ,QAAQ,QAAQ;AACxB,aAAO;AAAA,IACT,CAAC;AAAA,EACH,GAAG,CAAC,CAAC;AAEL,SAAO,EAAE,SAAS,QAAQ,WAAW,MAAM,MAAM,WAAW,MAAM,OAAO;AAC3E;","names":[]}

package/dist/opener.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/opener.ts
+var opener_exports = {};
+__export(opener_exports, {
+  OpenerAbortError: () => OpenerAbortError,
+  createOpener: () => createOpener
+});
+module.exports = __toCommonJS(opener_exports);
+var OpenerAbortError = class extends Error {
+  name = "AbortError";
+  constructor(slot) {
+    super(`The ${slot} request was aborted before the user answered it.`);
+  }
+};
+function getState(slot) {
+  const holder = globalThis;
+  const symbol = Symbol.for(slot);
+  let state = holder[symbol];
+  if (!state) {
+    state = { host: null, queue: [], inFlight: /* @__PURE__ */ new Map(), warnTimer: null, warned: false };
+    holder[symbol] = state;
+  }
+  return state;
+}
+function createOpener(slot, options = {}) {
+  const warnAfterMs = options.warnWithoutHostAfterMs ?? 5e3;
+  const hostHint = options.hostHint;
+  const dedupeKeyOf = options.dedupeKey;
+  function clearWarnTimer(state) {
+    if (state.warnTimer !== null) {
+      clearTimeout(state.warnTimer);
+      state.warnTimer = null;
+    }
+  }
+  function armWarnTimer(state) {
+    if (warnAfterMs <= 0 || state.warned || state.warnTimer !== null) return;
+    state.warnTimer = setTimeout(() => {
+      state.warnTimer = null;
+      if (state.host || state.queue.length === 0) return;
+      state.warned = true;
+      console.error(
+        `[@ai-matrx/kit/opener] ${state.queue.length} request(s) on "${slot}" have been waiting ${warnAfterMs}ms with no host registered, so the awaiting code is stuck and the user sees nothing. REMEDY: mount ${hostHint ?? `the host for "${slot}"`} once, near the root of this provider tree.`
+      );
+    }, warnAfterMs);
+    state.warnTimer.unref?.();
+  }
+  function drainTo(state, controller) {
+    while (state.queue.length > 0) {
+      const next = state.queue.shift();
+      if (next.settled) continue;
+      controller.show(next.request, next.settle);
+    }
+  }
+  const opener = {
+    slot,
+    open(request, requestOptions = {}) {
+      const state = getState(slot);
+      const signal = requestOptions.signal;
+      const dedupeKey = dedupeKeyOf?.(request);
+      if (dedupeKey !== void 0) {
+        const existing = state.inFlight.get(dedupeKey);
+        if (existing && !existing.entry.settled) return existing.promise;
+      }
+      let entry;
+      const promise = new Promise((resolve, reject) => {
+        const finish = (run) => {
+          if (entry.settled) return;
+          entry.settled = true;
+          if (entry.dedupeKey !== void 0) state.inFlight.delete(entry.dedupeKey);
+          const queuedAt = state.queue.indexOf(entry);
+          if (queuedAt >= 0) state.queue.splice(queuedAt, 1);
+          if (state.queue.length === 0) clearWarnTimer(state);
+          run();
+        };
+        entry = {
+          request,
+          dedupeKey,
+          settled: false,
+          settle: (response) => finish(() => resolve(response))
+        };
+        const abort = () => finish(() => {
+          if ("onAbortResolveWith" in requestOptions && requestOptions.onAbortResolveWith !== void 0) {
+            resolve(requestOptions.onAbortResolveWith);
+          } else {
+            reject(new OpenerAbortError(slot));
+          }
+        });
+        if (signal?.aborted) {
+          abort();
+          return;
+        }
+        signal?.addEventListener("abort", abort, { once: true });
+      });
+      if (entry.settled) return promise;
+      if (dedupeKey !== void 0) state.inFlight.set(dedupeKey, { entry, promise });
+      if (state.host) {
+        state.host.show(entry.request, entry.settle);
+      } else {
+        state.queue.push(entry);
+        armWarnTimer(state);
+      }
+      return promise;
+    },
+    _registerHost(controller) {
+      const state = getState(slot);
+      state.host = controller;
+      state.warned = false;
+      clearWarnTimer(state);
+      drainTo(state, controller);
+    },
+    _unregisterHost(controller) {
+      const state = getState(slot);
+      if (state.host === controller) state.host = null;
+    },
+    _reset() {
+      const state = getState(slot);
+      clearWarnTimer(state);
+      state.host = null;
+      state.queue.length = 0;
+      state.inFlight.clear();
+      state.warned = false;
+    },
+    _hasHost() {
+      return getState(slot).host !== null;
+    }
+  };
+  return opener;
+}
+//# sourceMappingURL=opener.cjs.map