@ai-matrx/summon 0.0.0-stage → 0.1.0

package/dist/url.js

@@ -0,0 +1,352 @@
+"use client";
+
+// src/url/useOverlayLink.ts
+import { useEffect, useMemo } from "react";
+import { registerSyncEntry, unregisterSyncEntry } from "@ai-matrx/summon";
+import { useSummonDispatch } from "@ai-matrx/summon/react";
+function useOverlayLink(linkKey, id, args) {
+  const dispatch = useSummonDispatch();
+  const argsKey = args ? JSON.stringify(
+    Object.keys(args).sort().map((k) => [k, args[k]])
+  ) : "";
+  const stableArgs = useMemo(() => args ? { ...args } : void 0, [argsKey]);
+  useEffect(() => {
+    if (!linkKey || !id) return void 0;
+    dispatch(registerSyncEntry(stableArgs ? { typeKey: linkKey, instanceId: id, args: stableArgs } : { typeKey: linkKey, instanceId: id }));
+    return () => {
+      dispatch(unregisterSyncEntry({ typeKey: linkKey, instanceId: id }));
+    };
+  }, [dispatch, linkKey, id, stableArgs]);
+}
+
+// src/url/grammar.ts
+var hex = (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+function encodeLinkId(id) {
+  return id.replace(/[%,:]/g, hex);
+}
+function encodeLinkArg(value) {
+  return value.replace(/[%,:_-]/g, hex);
+}
+function decodeLinkPart(value) {
+  if (!value.includes("%")) return value;
+  return value.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+    try {
+      return decodeURIComponent(run);
+    } catch {
+      return run;
+    }
+  });
+}
+function parseLinkToken(raw) {
+  if (!raw) return null;
+  const first = raw.indexOf(":");
+  const key = first === -1 ? raw : raw.slice(0, first);
+  if (!key) return null;
+  if (first === -1) return { raw, key, id: void 0, args: void 0 };
+  const rest = raw.slice(first + 1);
+  const second = rest.indexOf(":");
+  const idPart = second === -1 ? rest : rest.slice(0, second);
+  const argsPart = second === -1 ? void 0 : rest.slice(second + 1);
+  let args;
+  if (argsPart) {
+    args = {};
+    for (const pair of argsPart.split("_")) {
+      const at = pair.indexOf("-");
+      if (at <= 0 || at === pair.length - 1) continue;
+      args[decodeLinkPart(pair.slice(0, at))] = decodeLinkPart(pair.slice(at + 1));
+    }
+  }
+  return { raw, key: decodeLinkPart(key), id: decodeLinkPart(idPart), args };
+}
+function parseLinkParam(param) {
+  if (!param) return [];
+  const out = [];
+  for (const raw of param.split(",")) {
+    const token = parseLinkToken(raw);
+    if (token) out.push(token);
+  }
+  return out;
+}
+function formatLinkToken(entry) {
+  let token = `${encodeLinkId(entry.key)}:${encodeLinkId(entry.id)}`;
+  const args = entry.args;
+  if (args) {
+    const keys = Object.keys(args).sort();
+    if (keys.length > 0) {
+      token += `:${keys.map((k) => `${encodeLinkArg(k)}-${encodeLinkArg(args[k] ?? "")}`).join("_")}`;
+    }
+  }
+  return token;
+}
+function readPanelsParam(searchOrUrl) {
+  const q = searchOrUrl.indexOf("?");
+  const hash = searchOrUrl.indexOf("#");
+  let search;
+  if (q === -1) {
+    search = searchOrUrl.includes("=") && !searchOrUrl.includes("/") ? searchOrUrl : "";
+  } else {
+    search = searchOrUrl.slice(q + 1, hash > q ? hash : void 0);
+  }
+  return new URLSearchParams(search).get("panels");
+}
+function withPanelsParam(search, param) {
+  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+  if (param) params.set("panels", param);
+  else params.delete("panels");
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+
+// src/url/OverlayLinkManager.tsx
+import { useEffect as useEffect2, useRef, useState, useSyncExternalStore } from "react";
+import {
+  LAZY_WINDOW_MOUNT_DEADLINE_MS,
+  getOverlayMetaByLinkKey as getOverlayMetaByLinkKey2,
+  selectIsUrlHydrated,
+  selectUrlSyncEntries,
+  setHydrated
+} from "@ai-matrx/summon";
+import { useSummonDispatch as useSummonDispatch2, useSummonPorts, useSummonSelector } from "@ai-matrx/summon/react";
+
+// src/url/door.ts
+import {
+  DEFAULT_INSTANCE_ID,
+  getOverlayMeta,
+  getOverlayMetaByLinkKey,
+  isRegisteredOverlay,
+  overlaysRawActions
+} from "@ai-matrx/summon";
+function openRegisteredOverlay(dispatch, overlayId, instanceId = DEFAULT_INSTANCE_ID, data) {
+  const defaults = getOverlayMeta(overlayId)?.defaults;
+  dispatch(
+    overlaysRawActions.openOverlay({
+      overlayId,
+      instanceId,
+      ...data === void 0 ? {} : { data },
+      ...isRecord(defaults) ? { defaults } : {}
+    })
+  );
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalLinkKey(key) {
+  return getOverlayMetaByLinkKey(key)?.link?.key ?? key;
+}
+function canonicalizeToken(raw) {
+  const at = raw.indexOf(":");
+  const key = at === -1 ? raw : raw.slice(0, at);
+  const canonical = canonicalLinkKey(key);
+  if (canonical === key) return raw;
+  return at === -1 ? canonical : `${canonical}${raw.slice(at)}`;
+}
+function hydrateLinkToken(token, dispatch, onError) {
+  const meta = getOverlayMetaByLinkKey(token.key);
+  const link = meta?.link;
+  if (!meta || !link) return "unknown";
+  const ownerId = meta.id;
+  const settle = (result) => result === "refused" ? "refused" : "opened";
+  const fail = (error) => {
+    onError?.(error, token);
+    return "failed";
+  };
+  try {
+    const result = link.hydrate({
+      id: token.id ?? "",
+      args: token.args ?? {},
+      open: (options) => openRegisteredOverlay(dispatch, ownerId, options?.instanceId ?? DEFAULT_INSTANCE_ID, options?.data),
+      // The host's store dispatch IS the host dispatch at runtime; its thunk-aware type is the
+      // host's augmentation (`OverlayHostTypes`), which the package cannot see.
+      dispatch
+    });
+    if (result && typeof result.then === "function") {
+      return Promise.resolve(result).then(settle, fail);
+    }
+    return settle(result);
+  } catch (error) {
+    return fail(error);
+  }
+}
+async function openFromLink(searchOrUrl, options) {
+  const tokens = parseLinkParam(readPanelsParam(searchOrUrl));
+  const result = { opened: [], refused: [], unknown: [], failed: [] };
+  const unknown = tokens.filter((token) => !getOverlayMetaByLinkKey(token.key)?.link);
+  if (options.requireAll && unknown.length > 0) {
+    result.unknown.push(...unknown.map((token) => token.raw));
+    return result;
+  }
+  const outcomes = tokens.map((token) => hydrateLinkToken(token, options.dispatch, options.onError));
+  const settled = await Promise.all(outcomes.map((outcome) => Promise.resolve(outcome)));
+  settled.forEach((outcome, index) => {
+    const raw = tokens[index]?.raw ?? "";
+    result[outcome === "opened" ? "opened" : outcome].push(raw);
+  });
+  return result;
+}
+function readOpenPanelRequest(raw) {
+  if (!isRecord(raw)) return "payload must be an object";
+  const { panelId, instanceId, data } = raw;
+  if (typeof panelId !== "string" || panelId.length === 0) return "panelId must be a non-empty string";
+  if (instanceId !== void 0 && instanceId !== null && (typeof instanceId !== "string" || instanceId.length === 0)) {
+    return "instanceId must be a non-empty string when given";
+  }
+  if (data !== void 0 && data !== null && !isRecord(data)) return "data must be an object when given";
+  return {
+    panelId,
+    ...typeof instanceId === "string" ? { instanceId } : {},
+    ...isRecord(data) ? { data } : {}
+  };
+}
+function openPanelRequest(rawPayload, options) {
+  const request = readOpenPanelRequest(rawPayload);
+  if (typeof request === "string") return { ok: false, error: "invalid_payload", details: request };
+  if (!isRegisteredOverlay(request.panelId)) {
+    return {
+      ok: false,
+      error: "unknown_panel",
+      details: { panelId: request.panelId, hint: "panelId must be the id of a registered overlay definition." }
+    };
+  }
+  openRegisteredOverlay(options.dispatch, request.panelId, request.instanceId ?? DEFAULT_INSTANCE_ID, request.data);
+  return { ok: true, opened: true, panelId: request.panelId, instanceId: request.instanceId ?? null };
+}
+
+// src/url/OverlayLinkManager.tsx
+function serializeLinkEntries(entries, managedKeys) {
+  const managed = managedKeys ? new Set(managedKeys) : null;
+  return Object.values(entries).filter((entry) => !managed || managed.has(entry.typeKey)).map((entry) => formatLinkToken({ key: entry.typeKey, id: entry.instanceId, args: entry.args })).join(",");
+}
+function mergeManagedLinkParam(currentParam, nextManaged, managedKeys) {
+  if (!managedKeys) return nextManaged;
+  const managed = new Set(managedKeys);
+  const unmanaged = currentParam.split(",").filter(Boolean).filter((token) => !managed.has(token.split(":")[0] ?? ""));
+  return [...unmanaged, ...nextManaged.split(",").filter(Boolean)].join(",");
+}
+function withUnresolvedTokens(managedParam, unresolvedTokens) {
+  if (unresolvedTokens.length === 0) return managedParam;
+  const managed = managedParam.split(",").filter(Boolean);
+  const represented = new Set(managed.map((token) => canonicalLinkKey(token.split(":")[0] ?? "")));
+  const kept = unresolvedTokens.filter((token) => Boolean(token) && !represented.has(canonicalLinkKey(token.split(":")[0] ?? "")));
+  return [...managed, ...kept].join(",");
+}
+function unopenedWindowNotice(keys) {
+  return `This link names a window this build could not open: ${keys.join(", ")}. The link is unchanged in your address bar \u2014 reload to try again, or report it if it keeps failing.`;
+}
+var noopSubscribe = () => () => {
+};
+function OverlayLinkManager({ managedKeys, noticeDeadlineMs }) {
+  const ports = useSummonPorts();
+  const dispatch = useSummonDispatch2();
+  const entries = useSummonSelector(selectUrlSyncEntries);
+  const isHydrated = useSummonSelector(selectIsUrlHydrated);
+  const router = ports.router;
+  const search = useSyncExternalStore(router.subscribe ?? noopSubscribe, router.search, () => "");
+  const initialLoadDone = useRef(false);
+  const unresolved = useRef(/* @__PURE__ */ new Map());
+  const announced = useRef(/* @__PURE__ */ new Set());
+  const [noticeDue, setNoticeDue] = useState(false);
+  const [asyncTick, setAsyncTick] = useState(0);
+  const deadline = noticeDeadlineMs ?? LAZY_WINDOW_MOUNT_DEADLINE_MS;
+  const announce = (keys, reason) => {
+    const fresh = keys.filter((key) => !announced.current.has(key));
+    if (fresh.length === 0) return;
+    for (const key of fresh) announced.current.add(key);
+    const joined = fresh.join(", ");
+    const why = reason === "no-hydrator" ? `no registered definition owns ${fresh.length > 1 ? "these keys" : "this key"}` : reason === "hydrator-threw" ? "its hydrator threw" : `hydrated, but no window registered its link within ${deadline}ms`;
+    const message = `[overlays/url] ?panels= token(s) [${joined}]: ${why}. The token is KEPT in the address. Give the overlay definition a matching \`link\` (key or alias), or stop publishing the link.`;
+    ports.errors.capture(new Error(message), {
+      source: "url-panel-unopened",
+      relation: `?panels=${joined}`,
+      code: reason,
+      typeKeys: fresh,
+      deadlineMs: deadline,
+      userMessage: unopenedWindowNotice(fresh)
+    });
+    ports.notify.error(unopenedWindowNotice(fresh), { duration: 12e3 });
+  };
+  const announceRef = useRef(announce);
+  announceRef.current = announce;
+  useEffect2(() => {
+    if (initialLoadDone.current) return;
+    initialLoadDone.current = true;
+    const managed = managedKeys ? new Set(managedKeys) : null;
+    const tokens = parseLinkParam(readPanelsParam(router.search()));
+    const noHydrator = [];
+    for (const token of tokens) {
+      if (managed && !managed.has(token.key)) continue;
+      const canonicalKey = canonicalLinkKey(token.key);
+      const pendingKey = `${canonicalKey}\0${token.id ?? ""}`;
+      const pending = { token: canonicalizeToken(token.raw), tokenKey: token.key, canonicalKey };
+      if (!getOverlayMetaByLinkKey2(token.key)?.link) {
+        unresolved.current.set(pendingKey, { ...pending, token: token.raw });
+        noHydrator.push(token.key);
+        continue;
+      }
+      unresolved.current.set(pendingKey, pending);
+      const outcome = hydrateLinkToken(token, dispatch, (error) => {
+        ports.errors.capture(error, { source: "url-panel-hydrator", token: token.raw });
+      });
+      const apply = (result) => {
+        if (result === "refused" && unresolved.current.get(pendingKey) === pending) {
+          unresolved.current.delete(pendingKey);
+          setAsyncTick((n) => n + 1);
+        }
+      };
+      if (typeof outcome === "string") apply(outcome);
+      else void outcome.then(apply);
+    }
+    if (noHydrator.length > 0) announceRef.current(noHydrator, "no-hydrator");
+    dispatch(setHydrated());
+  }, [dispatch, managedKeys, router, ports]);
+  useEffect2(() => {
+    if (!isHydrated || unresolved.current.size === 0) return void 0;
+    const timer = setTimeout(() => setNoticeDue(true), deadline);
+    return () => clearTimeout(timer);
+  }, [isHydrated, deadline]);
+  useEffect2(() => {
+    if (!isHydrated) return;
+    const observed = new Set(Object.values(entries).map((entry) => canonicalLinkKey(entry.typeKey)));
+    for (const [key, pending] of [...unresolved.current.entries()]) {
+      if (observed.has(pending.canonicalKey)) unresolved.current.delete(key);
+    }
+    const stillPending = [...unresolved.current.values()];
+    if (noticeDue && stillPending.length > 0) {
+      announceRef.current(
+        stillPending.map((pending) => pending.tokenKey),
+        "never-registered"
+      );
+    }
+    const liveSearch = router.search();
+    const currentParam = readPanelsParam(liveSearch) ?? "";
+    const nextManaged = withUnresolvedTokens(
+      serializeLinkEntries(entries, managedKeys),
+      stillPending.map((pending) => pending.token)
+    );
+    const nextParam = mergeManagedLinkParam(currentParam, nextManaged, managedKeys);
+    if (currentParam !== nextParam) router.replaceSearch(withPanelsParam(liveSearch, nextParam));
+  }, [entries, isHydrated, managedKeys, router, search, noticeDue, asyncTick]);
+  return null;
+}
+export {
+  OverlayLinkManager,
+  canonicalLinkKey,
+  canonicalizeToken,
+  decodeLinkPart,
+  encodeLinkArg,
+  encodeLinkId,
+  formatLinkToken,
+  hydrateLinkToken,
+  mergeManagedLinkParam,
+  openFromLink,
+  openPanelRequest,
+  openRegisteredOverlay,
+  parseLinkParam,
+  parseLinkToken,
+  readPanelsParam,
+  serializeLinkEntries,
+  unopenedWindowNotice,
+  useOverlayLink,
+  withPanelsParam,
+  withUnresolvedTokens
+};
+//# sourceMappingURL=url.js.map

package/dist/url.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/url/useOverlayLink.ts","../src/url/grammar.ts","../src/url/OverlayLinkManager.tsx","../src/url/door.ts"],"sourcesContent":["import { useEffect, useMemo } from \"react\";\nimport { registerSyncEntry, unregisterSyncEntry } from \"@ai-matrx/summon\";\nimport { useSummonDispatch } from \"@ai-matrx/summon/react\";\n\n/**\n * Publish an open instance's address into `?panels=` while it is mounted. `linkKey` undefined →\n * nothing is published (a window with no link); so is an undefined or empty `id`. The token is `linkKey:id[:args]`; args are\n * compared by value, so a new object with equal contents never re-registers.\n */\nexport function useOverlayLink(linkKey: string | undefined, id: string | undefined, args?: Readonly<Record<string, string>>): void {\n  const dispatch = useSummonDispatch();\n  const argsKey = args\n    ? JSON.stringify(\n        Object.keys(args)\n          .sort()\n          .map((k) => [k, args[k]]),\n      )\n    : \"\";\n  // Rebuilt only when the VALUES change (argsKey), never on a fresh object with equal contents.\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const stableArgs = useMemo(() => (args ? { ...args } : undefined), [argsKey]);\n\n  useEffect(() => {\n    if (!linkKey || !id) return undefined;\n    dispatch(registerSyncEntry(stableArgs ? { typeKey: linkKey, instanceId: id, args: stableArgs } : { typeKey: linkKey, instanceId: id }));\n    return () => {\n      dispatch(unregisterSyncEntry({ typeKey: linkKey, instanceId: id }));\n    };\n  }, [dispatch, linkKey, id, stableArgs]);\n}\n","/**\n * The `?panels=` link grammar.\n *\n *   panels = token (\",\" token)*\n *   token  = key [\":\" id [\":\" args]]\n *   args   = k \"-\" v (\"_\" k \"-\" v)*\n *\n * GRAMMAR v2 (this file): on WRITE, ids are percent-encoded for `% , :` and arg keys and values\n * for `% , : _ -`, so any value — a uuid, a date, a path, a list — survives the round trip.\n * Keys and ids keep `-` and `_` unencoded: they are not separators inside an id, and leaving them means a\n * uuid id writes byte-identically to v1. On READ, v1 tokens (unencoded) parse unchanged: an arg\n * pair splits on its FIRST hyphen, and decoding only touches well-formed `%XX` escapes.\n *\n * Framework-free; this is the one grammar every door (address bar, notifications, extension)\n * shares.\n */\n\nexport interface LinkToken {\n  /** The token exactly as it appeared (the verbatim form written back while unresolved). */\n  readonly raw: string;\n  readonly key: string;\n  /** `undefined` for a bare-key token (`keyword_research`). */\n  readonly id: string | undefined;\n  /** `undefined` when the token carries no args segment. */\n  readonly args: Readonly<Record<string, string>> | undefined;\n}\n\nexport interface LinkEntry {\n  readonly key: string;\n  readonly id: string;\n  readonly args?: Readonly<Record<string, string>> | undefined;\n}\n\nconst hex = (ch: string): string => `%${ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, \"0\")}`;\n\n/** Encode a token id (`% , :`). */\nexport function encodeLinkId(id: string): string {\n  return id.replace(/[%,:]/g, hex);\n}\n\n/** Encode an arg key or value (`% , : _ -`). */\nexport function encodeLinkArg(value: string): string {\n  return value.replace(/[%,:_-]/g, hex);\n}\n\n/** Decode well-formed `%XX` escapes; anything else (a v1 literal `%`) is kept as written. */\nexport function decodeLinkPart(value: string): string {\n  if (!value.includes(\"%\")) return value;\n  return value.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {\n    try {\n      return decodeURIComponent(run);\n    } catch {\n      return run;\n    }\n  });\n}\n\n/** Parse one token (v1 or v2). Returns `null` for an empty token. */\nexport function parseLinkToken(raw: string): LinkToken | null {\n  if (!raw) return null;\n  const first = raw.indexOf(\":\");\n  const key = first === -1 ? raw : raw.slice(0, first);\n  if (!key) return null;\n  if (first === -1) return { raw, key, id: undefined, args: undefined };\n  const rest = raw.slice(first + 1);\n  const second = rest.indexOf(\":\");\n  const idPart = second === -1 ? rest : rest.slice(0, second);\n  const argsPart = second === -1 ? undefined : rest.slice(second + 1);\n  let args: Record<string, string> | undefined;\n  if (argsPart) {\n    args = {};\n    for (const pair of argsPart.split(\"_\")) {\n      // Split on the FIRST hyphen only: a v1 value may hold hyphens (uuid, date).\n      const at = pair.indexOf(\"-\");\n      if (at <= 0 || at === pair.length - 1) continue;\n      args[decodeLinkPart(pair.slice(0, at))] = decodeLinkPart(pair.slice(at + 1));\n    }\n  }\n  return { raw, key: decodeLinkPart(key), id: decodeLinkPart(idPart), args };\n}\n\n/** Parse a whole `panels` value. Empty segments are skipped. */\nexport function parseLinkParam(param: string | null | undefined): LinkToken[] {\n  if (!param) return [];\n  const out: LinkToken[] = [];\n  for (const raw of param.split(\",\")) {\n    const token = parseLinkToken(raw);\n    if (token) out.push(token);\n  }\n  return out;\n}\n\n/** Write one entry as a v2 token. Args are written in key order so equal entries write equal tokens. */\nexport function formatLinkToken(entry: LinkEntry): string {\n  let token = `${encodeLinkId(entry.key)}:${encodeLinkId(entry.id)}`;\n  const args = entry.args;\n  if (args) {\n    const keys = Object.keys(args).sort();\n    if (keys.length > 0) {\n      token += `:${keys.map((k) => `${encodeLinkArg(k)}-${encodeLinkArg(args[k] ?? \"\")}`).join(\"_\")}`;\n    }\n  }\n  return token;\n}\n\n/** The `panels` value from a search string or a full URL (`null` when absent). */\nexport function readPanelsParam(searchOrUrl: string): string | null {\n  const q = searchOrUrl.indexOf(\"?\");\n  const hash = searchOrUrl.indexOf(\"#\");\n  let search: string;\n  if (q === -1) {\n    // A bare query string without \"?\" (`panels=…`) or a URL with no query.\n    search = searchOrUrl.includes(\"=\") && !searchOrUrl.includes(\"/\") ? searchOrUrl : \"\";\n  } else {\n    search = searchOrUrl.slice(q + 1, hash > q ? hash : undefined);\n  }\n  return new URLSearchParams(search).get(\"panels\");\n}\n\n/** `search` with `panels` set to `param` (removed when empty). Returns \"\" or \"?…\". */\nexport function withPanelsParam(search: string, param: string): string {\n  const params = new URLSearchParams(search.startsWith(\"?\") ? search.slice(1) : search);\n  if (param) params.set(\"panels\", param);\n  else params.delete(\"panels\");\n  const qs = params.toString();\n  return qs ? `?${qs}` : \"\";\n}\n","/**\n * OverlayLinkManager — the address bar's `?panels=` channel (successor of matrx-frontend's\n * UrlPanelManager). Mount ONCE inside <SummonProvider>. Driven entirely by `ports.router`.\n *\n *  1. On mount: read `?panels=`, hydrate each token through the one door (`hydrateLinkToken`).\n *  2. After that: write back the union of registered link entries (`useOverlayLink`) plus every\n *     pasted token that has not been settled yet, via `router.replaceSearch` — never navigation.\n *\n * THE ADDRESS IS NEVER DESTROYED BY A CLOCK (matrx-frontend V-28 NEW-5). A token whose window has\n * not registered yet is kept verbatim in the address however long its lazy chunk takes. The\n * deadline (12 s prod / 45 s dev) decides one thing only: when to stop waiting silently and tell\n * the person, through `ports.notify` and `ports.errors`.\n *\n * A token is SETTLED when ANY registered entry carries its canonical key — the window a hydrator\n * opens may publish a different id (a vault link names an item, the vault window publishes its\n * singleton id) and may even be a different overlay than the one owning the key (key `agent`\n * opens display-mode shells). An alias resolves to its definition's own `link.key`.\n */\nimport { useEffect, useRef, useState, useSyncExternalStore } from \"react\";\nimport {\n  LAZY_WINDOW_MOUNT_DEADLINE_MS,\n  getOverlayMetaByLinkKey,\n  selectIsUrlHydrated,\n  selectUrlSyncEntries,\n  setHydrated,\n  type UrlSyncEntry,\n} from \"@ai-matrx/summon\";\nimport { useSummonDispatch, useSummonPorts, useSummonSelector } from \"@ai-matrx/summon/react\";\nimport { canonicalLinkKey, canonicalizeToken, hydrateLinkToken } from \"./door\";\nimport { formatLinkToken, parseLinkParam, readPanelsParam, withPanelsParam } from \"./grammar\";\n\nexport interface OverlayLinkManagerProps {\n  /**\n   * Restrict hydration and write-back to these link keys (a route-scoped manager). Tokens of\n   * other keys are preserved verbatim and never hydrated. Omit for the app-wide manager.\n   */\n  readonly managedKeys?: readonly string[];\n  /** Override the notice deadline (ms). Default: 12 s in production, 45 s in development. */\n  readonly noticeDeadlineMs?: number;\n}\n\n/** Serialize registered entries as v2 tokens (only managed keys when given). */\nexport function serializeLinkEntries(entries: Readonly<Record<string, UrlSyncEntry>>, managedKeys?: readonly string[]): string {\n  const managed = managedKeys ? new Set(managedKeys) : null;\n  return Object.values(entries)\n    .filter((entry) => !managed || managed.has(entry.typeKey))\n    .map((entry) => formatLinkToken({ key: entry.typeKey, id: entry.instanceId, args: entry.args }))\n    .join(\",\");\n}\n\n/** Keep the current param's unmanaged tokens; replace the managed ones with `nextManaged`. */\nexport function mergeManagedLinkParam(currentParam: string, nextManaged: string, managedKeys?: readonly string[]): string {\n  if (!managedKeys) return nextManaged;\n  const managed = new Set(managedKeys);\n  const unmanaged = currentParam\n    .split(\",\")\n    .filter(Boolean)\n    .filter((token) => !managed.has(token.split(\":\")[0] ?? \"\"));\n  return [...unmanaged, ...nextManaged.split(\",\").filter(Boolean)].join(\",\");\n}\n\n/**\n * Re-attach pasted tokens no window has settled. A token is skipped when its CANONICAL key is\n * already represented by a live entry, so a late registration replaces the placeholder.\n */\nexport function withUnresolvedTokens(managedParam: string, unresolvedTokens: readonly string[]): string {\n  if (unresolvedTokens.length === 0) return managedParam;\n  const managed = managedParam.split(\",\").filter(Boolean);\n  const represented = new Set(managed.map((token) => canonicalLinkKey(token.split(\":\")[0] ?? \"\")));\n  const kept = unresolvedTokens.filter((token) => Boolean(token) && !represented.has(canonicalLinkKey(token.split(\":\")[0] ?? \"\")));\n  return [...managed, ...kept].join(\",\");\n}\n\n/** The honest sentence for a link naming a window that did not open. */\nexport function unopenedWindowNotice(keys: readonly string[]): string {\n  return (\n    `This link names a window this build could not open: ${keys.join(\", \")}. ` +\n    `The link is unchanged in your address bar — reload to try again, or report it if it keeps failing.`\n  );\n}\n\ninterface PendingToken {\n  /** What is written back while unsettled (canonical key, pasted id and args). */\n  readonly token: string;\n  /** The key the person pasted (named in the notice). */\n  readonly tokenKey: string;\n  readonly canonicalKey: string;\n}\n\nconst noopSubscribe = () => () => {};\n\nexport function OverlayLinkManager({ managedKeys, noticeDeadlineMs }: OverlayLinkManagerProps): null {\n  const ports = useSummonPorts();\n  const dispatch = useSummonDispatch();\n  const entries = useSummonSelector(selectUrlSyncEntries);\n  const isHydrated = useSummonSelector(selectIsUrlHydrated);\n  const router = ports.router;\n  // Re-run the write-back after ANY address change the router reports.\n  const search = useSyncExternalStore(router.subscribe ?? noopSubscribe, router.search, () => \"\");\n\n  const initialLoadDone = useRef(false);\n  // Keyed by canonical key + id so two tokens that canonicalise together never overwrite each\n  // other (V-30 NEW-5); the settle sweep still runs on canonical key.\n  const unresolved = useRef(new Map<string, PendingToken>());\n  const announced = useRef(new Set<string>());\n  const [noticeDue, setNoticeDue] = useState(false);\n  const [asyncTick, setAsyncTick] = useState(0);\n  const deadline = noticeDeadlineMs ?? LAZY_WINDOW_MOUNT_DEADLINE_MS;\n\n  const announce = (keys: readonly string[], reason: \"no-hydrator\" | \"never-registered\" | \"hydrator-threw\"): void => {\n    const fresh = keys.filter((key) => !announced.current.has(key));\n    if (fresh.length === 0) return;\n    for (const key of fresh) announced.current.add(key);\n    const joined = fresh.join(\", \");\n    const why =\n      reason === \"no-hydrator\"\n        ? `no registered definition owns ${fresh.length > 1 ? \"these keys\" : \"this key\"}`\n        : reason === \"hydrator-threw\"\n          ? \"its hydrator threw\"\n          : `hydrated, but no window registered its link within ${deadline}ms`;\n    const message =\n      `[overlays/url] ?panels= token(s) [${joined}]: ${why}. The token is KEPT in the address. ` +\n      `Give the overlay definition a matching \\`link\\` (key or alias), or stop publishing the link.`;\n    ports.errors.capture(new Error(message), {\n      source: \"url-panel-unopened\",\n      relation: `?panels=${joined}`,\n      code: reason,\n      typeKeys: fresh,\n      deadlineMs: deadline,\n      userMessage: unopenedWindowNotice(fresh),\n    });\n    ports.notify.error(unopenedWindowNotice(fresh), { duration: 12_000 });\n  };\n  const announceRef = useRef(announce);\n  announceRef.current = announce;\n\n  // 1. HYDRATION (address → store), once.\n  useEffect(() => {\n    if (initialLoadDone.current) return;\n    initialLoadDone.current = true;\n    const managed = managedKeys ? new Set(managedKeys) : null;\n    const tokens = parseLinkParam(readPanelsParam(router.search()));\n    const noHydrator: string[] = [];\n    for (const token of tokens) {\n      if (managed && !managed.has(token.key)) continue; // preserved verbatim by the write-back\n      const canonicalKey = canonicalLinkKey(token.key);\n      const pendingKey = `${canonicalKey}\\u0000${token.id ?? \"\"}`;\n      const pending: PendingToken = { token: canonicalizeToken(token.raw), tokenKey: token.key, canonicalKey };\n      if (!getOverlayMetaByLinkKey(token.key)?.link) {\n        unresolved.current.set(pendingKey, { ...pending, token: token.raw });\n        noHydrator.push(token.key);\n        continue;\n      }\n      unresolved.current.set(pendingKey, pending);\n      const outcome = hydrateLinkToken(token, dispatch, (error) => {\n        ports.errors.capture(error, { source: \"url-panel-hydrator\", token: token.raw });\n      });\n      const apply = (result: string): void => {\n        // A refused link is dropped from the address; it is not \"still to come\".\n        if (result === \"refused\" && unresolved.current.get(pendingKey) === pending) {\n          unresolved.current.delete(pendingKey);\n          setAsyncTick((n) => n + 1);\n        }\n      };\n      if (typeof outcome === \"string\") apply(outcome);\n      else void outcome.then(apply);\n    }\n    if (noHydrator.length > 0) announceRef.current(noHydrator, \"no-hydrator\");\n    dispatch(setHydrated());\n  }, [dispatch, managedKeys, router, ports]);\n\n  // The notice deadline: never gates a write; only turns a silent wait into a visible notice.\n  useEffect(() => {\n    if (!isHydrated || unresolved.current.size === 0) return undefined;\n    const timer = setTimeout(() => setNoticeDue(true), deadline);\n    return () => clearTimeout(timer);\n  }, [isHydrated, deadline]);\n\n  // 2. WRITE-BACK (store → address).\n  useEffect(() => {\n    if (!isHydrated) return;\n    const observed = new Set(Object.values(entries).map((entry) => canonicalLinkKey(entry.typeKey)));\n    for (const [key, pending] of [...unresolved.current.entries()]) {\n      if (observed.has(pending.canonicalKey)) unresolved.current.delete(key);\n    }\n    const stillPending = [...unresolved.current.values()];\n    if (noticeDue && stillPending.length > 0) {\n      announceRef.current(\n        stillPending.map((pending) => pending.tokenKey),\n        \"never-registered\",\n      );\n    }\n    // The LIVE address, never a snapshot: the page may have written `?view=` a moment ago.\n    const liveSearch = router.search();\n    const currentParam = readPanelsParam(liveSearch) ?? \"\";\n    const nextManaged = withUnresolvedTokens(\n      serializeLinkEntries(entries, managedKeys),\n      stillPending.map((pending) => pending.token),\n    );\n    const nextParam = mergeManagedLinkParam(currentParam, nextManaged, managedKeys);\n    if (currentParam !== nextParam) router.replaceSearch(withPanelsParam(liveSearch, nextParam));\n  }, [entries, isHydrated, managedKeys, router, search, noticeDue, asyncTick]);\n\n  return null;\n}\n","/**\n * The ONE door every link source goes through: the address-bar manager on load, a notification\n * that opens its link in place, the extension bridge. A token is resolved through the registry —\n * `getOverlayMetaByLinkKey(key).link.hydrate({ id, args, open, dispatch })` — never a side table.\n */\nimport type { Dispatch, UnknownAction } from \"@reduxjs/toolkit\";\nimport {\n  DEFAULT_INSTANCE_ID,\n  getOverlayMeta,\n  getOverlayMetaByLinkKey,\n  isRegisteredOverlay,\n  overlaysRawActions,\n  type AnyOverlayMeta,\n  type OverlayHostDispatch,\n} from \"@ai-matrx/summon\";\nimport { parseLinkParam, readPanelsParam, type LinkToken } from \"./grammar\";\n\n/** Any Redux dispatch that takes plain actions (a host's thunk-aware dispatch qualifies). */\nexport type LinkDispatch = Dispatch<UnknownAction>;\n\n/**\n * Open an overlay by its registry id from inside the package. Uses the raw action so internal\n * code passes plain strings (a host's augmented `OverlayId` union never needs a cast here); the\n * definition's `defaults` are merged underneath exactly as the typed creator does.\n */\nexport function openRegisteredOverlay(\n  dispatch: LinkDispatch,\n  overlayId: string,\n  instanceId: string = DEFAULT_INSTANCE_ID,\n  data?: unknown,\n): void {\n  const defaults = getOverlayMeta(overlayId)?.defaults;\n  dispatch(\n    overlaysRawActions.openOverlay({\n      overlayId,\n      instanceId,\n      ...(data === undefined ? {} : { data }),\n      ...(isRecord(defaults) ? { defaults } : {}),\n    }),\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** The key a token is judged by: the owning definition's own `link.key` (aliases resolve to it). */\nexport function canonicalLinkKey(key: string): string {\n  return getOverlayMetaByLinkKey(key)?.link?.key ?? key;\n}\n\n/** The token with its key replaced by the canonical key; id and args carry across untouched. */\nexport function canonicalizeToken(raw: string): string {\n  const at = raw.indexOf(\":\");\n  const key = at === -1 ? raw : raw.slice(0, at);\n  const canonical = canonicalLinkKey(key);\n  if (canonical === key) return raw;\n  return at === -1 ? canonical : `${canonical}${raw.slice(at)}`;\n}\n\nexport type TokenOutcome = \"opened\" | \"refused\" | \"unknown\" | \"failed\";\n\n/**\n * Run one token's hydrator. Synchronous hydrators dispatch before this returns; an async one\n * yields a promise. A throw (sync or async) is `\"failed\"` and is reported to `onError`.\n */\nexport function hydrateLinkToken(\n  token: LinkToken,\n  dispatch: LinkDispatch,\n  onError?: (error: unknown, token: LinkToken) => void,\n): TokenOutcome | Promise<TokenOutcome> {\n  const meta: AnyOverlayMeta | undefined = getOverlayMetaByLinkKey(token.key);\n  const link = meta?.link;\n  if (!meta || !link) return \"unknown\";\n  const ownerId = meta.id;\n  const settle = (result: void | \"refused\"): TokenOutcome => (result === \"refused\" ? \"refused\" : \"opened\");\n  const fail = (error: unknown): TokenOutcome => {\n    onError?.(error, token);\n    return \"failed\";\n  };\n  try {\n    const result = link.hydrate({\n      id: token.id ?? \"\",\n      args: token.args ?? {},\n      open: (options) => openRegisteredOverlay(dispatch, ownerId, options?.instanceId ?? DEFAULT_INSTANCE_ID, options?.data),\n      // The host's store dispatch IS the host dispatch at runtime; its thunk-aware type is the\n      // host's augmentation (`OverlayHostTypes`), which the package cannot see.\n      dispatch: dispatch as unknown as OverlayHostDispatch,\n    });\n    if (result && typeof (result as PromiseLike<unknown>).then === \"function\") {\n      return Promise.resolve(result).then(settle, fail);\n    }\n    return settle(result as void | \"refused\");\n  } catch (error) {\n    return fail(error);\n  }\n}\n\nexport interface OpenFromLinkResult {\n  /** Tokens (verbatim) whose hydrator ran and did not refuse. */\n  readonly opened: string[];\n  /** Tokens whose hydrator declined the link on purpose. */\n  readonly refused: string[];\n  /** Tokens whose key no registered definition owns. */\n  readonly unknown: string[];\n  /** Tokens whose hydrator threw. */\n  readonly failed: string[];\n}\n\nexport interface OpenFromLinkOptions {\n  readonly dispatch: LinkDispatch;\n  /**\n   * All or nothing: when any token's key is unknown, open NOTHING and report the unknown tokens\n   * (a notification then opens the link in a new tab instead of half of it in place).\n   */\n  readonly requireAll?: boolean;\n  readonly onError?: (error: unknown, token: LinkToken) => void;\n}\n\n/**\n * Open every `?panels=` token of a search string or URL through its definition's hydrator.\n * Synchronous hydrators have dispatched by the time this returns; the promise settles once\n * async hydrators finish.\n */\nexport async function openFromLink(searchOrUrl: string, options: OpenFromLinkOptions): Promise<OpenFromLinkResult> {\n  const tokens = parseLinkParam(readPanelsParam(searchOrUrl));\n  const result: OpenFromLinkResult = { opened: [], refused: [], unknown: [], failed: [] };\n  const unknown = tokens.filter((token) => !getOverlayMetaByLinkKey(token.key)?.link);\n  if (options.requireAll && unknown.length > 0) {\n    result.unknown.push(...unknown.map((token) => token.raw));\n    return result;\n  }\n  const outcomes = tokens.map((token) => hydrateLinkToken(token, options.dispatch, options.onError));\n  const settled = await Promise.all(outcomes.map((outcome) => Promise.resolve(outcome)));\n  settled.forEach((outcome, index) => {\n    const raw = tokens[index]?.raw ?? \"\";\n    result[outcome === \"opened\" ? \"opened\" : outcome].push(raw);\n  });\n  return result;\n}\n\n// ── The extension door ──────────────────────────────────────────────────────────────────────\n\nexport interface OpenPanelRequest {\n  readonly panelId: string;\n  readonly instanceId?: string;\n  readonly data?: Readonly<Record<string, unknown>>;\n}\n\nexport type OpenPanelResult =\n  | { readonly ok: true; readonly opened: true; readonly panelId: string; readonly instanceId: string | null }\n  | { readonly ok: false; readonly error: \"invalid_payload\" | \"unknown_panel\"; readonly details?: unknown };\n\nfunction readOpenPanelRequest(raw: unknown): OpenPanelRequest | string {\n  if (!isRecord(raw)) return \"payload must be an object\";\n  const { panelId, instanceId, data } = raw;\n  if (typeof panelId !== \"string\" || panelId.length === 0) return \"panelId must be a non-empty string\";\n  if (instanceId !== undefined && instanceId !== null && (typeof instanceId !== \"string\" || instanceId.length === 0)) {\n    return \"instanceId must be a non-empty string when given\";\n  }\n  if (data !== undefined && data !== null && !isRecord(data)) return \"data must be an object when given\";\n  return {\n    panelId,\n    ...(typeof instanceId === \"string\" ? { instanceId } : {}),\n    ...(isRecord(data) ? { data } : {}),\n  };\n}\n\n/**\n * Open a registered overlay by id for an outside caller (the browser extension's `openPanel`\n * envelope). Validates the payload and the id; failures come back as values, never throws, so\n * the bridge can reply verbatim. `instanceId: null` in the reply = the caller used the singleton.\n */\nexport function openPanelRequest(rawPayload: unknown, options: { readonly dispatch: LinkDispatch }): OpenPanelResult {\n  const request = readOpenPanelRequest(rawPayload);\n  if (typeof request === \"string\") return { ok: false, error: \"invalid_payload\", details: request };\n  if (!isRegisteredOverlay(request.panelId)) {\n    return {\n      ok: false,\n      error: \"unknown_panel\",\n      details: { panelId: request.panelId, hint: \"panelId must be the id of a registered overlay definition.\" },\n    };\n  }\n  openRegisteredOverlay(options.dispatch, request.panelId, request.instanceId ?? DEFAULT_INSTANCE_ID, request.data);\n  return { ok: true, opened: true, panelId: request.panelId, instanceId: request.instanceId ?? null };\n}\n"],"mappings":";;;AAAA,SAAS,WAAW,eAAe;AACnC,SAAS,mBAAmB,2BAA2B;AACvD,SAAS,yBAAyB;AAO3B,SAAS,eAAe,SAA6B,IAAwB,MAA+C;AACjI,QAAM,WAAW,kBAAkB;AACnC,QAAM,UAAU,OACZ,KAAK;AAAA,IACH,OAAO,KAAK,IAAI,EACb,KAAK,EACL,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;AAAA,EAC5B,IACA;AAGJ,QAAM,aAAa,QAAQ,MAAO,OAAO,EAAE,GAAG,KAAK,IAAI,QAAY,CAAC,OAAO,CAAC;AAE5E,YAAU,MAAM;AACd,QAAI,CAAC,WAAW,CAAC,GAAI,QAAO;AAC5B,aAAS,kBAAkB,aAAa,EAAE,SAAS,SAAS,YAAY,IAAI,MAAM,WAAW,IAAI,EAAE,SAAS,SAAS,YAAY,GAAG,CAAC,CAAC;AACtI,WAAO,MAAM;AACX,eAAS,oBAAoB,EAAE,SAAS,SAAS,YAAY,GAAG,CAAC,CAAC;AAAA,IACpE;AAAA,EACF,GAAG,CAAC,UAAU,SAAS,IAAI,UAAU,CAAC;AACxC;;;ACIA,IAAM,MAAM,CAAC,OAAuB,IAAI,GAAG,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,GAAG,GAAG,CAAC;AAG7F,SAAS,aAAa,IAAoB;AAC/C,SAAO,GAAG,QAAQ,UAAU,GAAG;AACjC;AAGO,SAAS,cAAc,OAAuB;AACnD,SAAO,MAAM,QAAQ,YAAY,GAAG;AACtC;AAGO,SAAS,eAAe,OAAuB;AACpD,MAAI,CAAC,MAAM,SAAS,GAAG,EAAG,QAAO;AACjC,SAAO,MAAM,QAAQ,yBAAyB,CAAC,QAAQ;AACrD,QAAI;AACF,aAAO,mBAAmB,GAAG;AAAA,IAC/B,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,CAAC;AACH;AAGO,SAAS,eAAe,KAA+B;AAC5D,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,QAAQ,IAAI,QAAQ,GAAG;AAC7B,QAAM,MAAM,UAAU,KAAK,MAAM,IAAI,MAAM,GAAG,KAAK;AACnD,MAAI,CAAC,IAAK,QAAO;AACjB,MAAI,UAAU,GAAI,QAAO,EAAE,KAAK,KAAK,IAAI,QAAW,MAAM,OAAU;AACpE,QAAM,OAAO,IAAI,MAAM,QAAQ,CAAC;AAChC,QAAM,SAAS,KAAK,QAAQ,GAAG;AAC/B,QAAM,SAAS,WAAW,KAAK,OAAO,KAAK,MAAM,GAAG,MAAM;AAC1D,QAAM,WAAW,WAAW,KAAK,SAAY,KAAK,MAAM,SAAS,CAAC;AAClE,MAAI;AACJ,MAAI,UAAU;AACZ,WAAO,CAAC;AACR,eAAW,QAAQ,SAAS,MAAM,GAAG,GAAG;AAEtC,YAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,UAAI,MAAM,KAAK,OAAO,KAAK,SAAS,EAAG;AACvC,WAAK,eAAe,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,IAAI,eAAe,KAAK,MAAM,KAAK,CAAC,CAAC;AAAA,IAC7E;AAAA,EACF;AACA,SAAO,EAAE,KAAK,KAAK,eAAe,GAAG,GAAG,IAAI,eAAe,MAAM,GAAG,KAAK;AAC3E;AAGO,SAAS,eAAe,OAA+C;AAC5E,MAAI,CAAC,MAAO,QAAO,CAAC;AACpB,QAAM,MAAmB,CAAC;AAC1B,aAAW,OAAO,MAAM,MAAM,GAAG,GAAG;AAClC,UAAM,QAAQ,eAAe,GAAG;AAChC,QAAI,MAAO,KAAI,KAAK,KAAK;AAAA,EAC3B;AACA,SAAO;AACT;AAGO,SAAS,gBAAgB,OAA0B;AACxD,MAAI,QAAQ,GAAG,aAAa,MAAM,GAAG,CAAC,IAAI,aAAa,MAAM,EAAE,CAAC;AAChE,QAAM,OAAO,MAAM;AACnB,MAAI,MAAM;AACR,UAAM,OAAO,OAAO,KAAK,IAAI,EAAE,KAAK;AACpC,QAAI,KAAK,SAAS,GAAG;AACnB,eAAS,IAAI,KAAK,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,CAAC,IAAI,cAAc,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,GAAG,CAAC;AAAA,IAC/F;AAAA,EACF;AACA,SAAO;AACT;AAGO,SAAS,gBAAgB,aAAoC;AAClE,QAAM,IAAI,YAAY,QAAQ,GAAG;AACjC,QAAM,OAAO,YAAY,QAAQ,GAAG;AACpC,MAAI;AACJ,MAAI,MAAM,IAAI;AAEZ,aAAS,YAAY,SAAS,GAAG,KAAK,CAAC,YAAY,SAAS,GAAG,IAAI,cAAc;AAAA,EACnF,OAAO;AACL,aAAS,YAAY,MAAM,IAAI,GAAG,OAAO,IAAI,OAAO,MAAS;AAAA,EAC/D;AACA,SAAO,IAAI,gBAAgB,MAAM,EAAE,IAAI,QAAQ;AACjD;AAGO,SAAS,gBAAgB,QAAgB,OAAuB;AACrE,QAAM,SAAS,IAAI,gBAAgB,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI,MAAM;AACpF,MAAI,MAAO,QAAO,IAAI,UAAU,KAAK;AAAA,MAChC,QAAO,OAAO,QAAQ;AAC3B,QAAM,KAAK,OAAO,SAAS;AAC3B,SAAO,KAAK,IAAI,EAAE,KAAK;AACzB;;;AC5GA,SAAS,aAAAA,YAAW,QAAQ,UAAU,4BAA4B;AAClE;AAAA,EACE;AAAA,EACA,2BAAAC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,SAAS,qBAAAC,oBAAmB,gBAAgB,yBAAyB;;;ACrBrE;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAWA,SAAS,sBACd,UACA,WACA,aAAqB,qBACrB,MACM;AACN,QAAM,WAAW,eAAe,SAAS,GAAG;AAC5C;AAAA,IACE,mBAAmB,YAAY;AAAA,MAC7B;AAAA,MACA;AAAA,MACA,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,KAAK;AAAA,MACrC,GAAI,SAAS,QAAQ,IAAI,EAAE,SAAS,IAAI,CAAC;AAAA,IAC3C,CAAC;AAAA,EACH;AACF;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAGO,SAAS,iBAAiB,KAAqB;AACpD,SAAO,wBAAwB,GAAG,GAAG,MAAM,OAAO;AACpD;AAGO,SAAS,kBAAkB,KAAqB;AACrD,QAAM,KAAK,IAAI,QAAQ,GAAG;AAC1B,QAAM,MAAM,OAAO,KAAK,MAAM,IAAI,MAAM,GAAG,EAAE;AAC7C,QAAM,YAAY,iBAAiB,GAAG;AACtC,MAAI,cAAc,IAAK,QAAO;AAC9B,SAAO,OAAO,KAAK,YAAY,GAAG,SAAS,GAAG,IAAI,MAAM,EAAE,CAAC;AAC7D;AAQO,SAAS,iBACd,OACA,UACA,SACsC;AACtC,QAAM,OAAmC,wBAAwB,MAAM,GAAG;AAC1E,QAAM,OAAO,MAAM;AACnB,MAAI,CAAC,QAAQ,CAAC,KAAM,QAAO;AAC3B,QAAM,UAAU,KAAK;AACrB,QAAM,SAAS,CAAC,WAA4C,WAAW,YAAY,YAAY;AAC/F,QAAM,OAAO,CAAC,UAAiC;AAC7C,cAAU,OAAO,KAAK;AACtB,WAAO;AAAA,EACT;AACA,MAAI;AACF,UAAM,SAAS,KAAK,QAAQ;AAAA,MAC1B,IAAI,MAAM,MAAM;AAAA,MAChB,MAAM,MAAM,QAAQ,CAAC;AAAA,MACrB,MAAM,CAAC,YAAY,sBAAsB,UAAU,SAAS,SAAS,cAAc,qBAAqB,SAAS,IAAI;AAAA;AAAA;AAAA,MAGrH;AAAA,IACF,CAAC;AACD,QAAI,UAAU,OAAQ,OAAgC,SAAS,YAAY;AACzE,aAAO,QAAQ,QAAQ,MAAM,EAAE,KAAK,QAAQ,IAAI;AAAA,IAClD;AACA,WAAO,OAAO,MAA0B;AAAA,EAC1C,SAAS,OAAO;AACd,WAAO,KAAK,KAAK;AAAA,EACnB;AACF;AA4BA,eAAsB,aAAa,aAAqB,SAA2D;AACjH,QAAM,SAAS,eAAe,gBAAgB,WAAW,CAAC;AAC1D,QAAM,SAA6B,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC,GAAG,QAAQ,CAAC,EAAE;AACtF,QAAM,UAAU,OAAO,OAAO,CAAC,UAAU,CAAC,wBAAwB,MAAM,GAAG,GAAG,IAAI;AAClF,MAAI,QAAQ,cAAc,QAAQ,SAAS,GAAG;AAC5C,WAAO,QAAQ,KAAK,GAAG,QAAQ,IAAI,CAAC,UAAU,MAAM,GAAG,CAAC;AACxD,WAAO;AAAA,EACT;AACA,QAAM,WAAW,OAAO,IAAI,CAAC,UAAU,iBAAiB,OAAO,QAAQ,UAAU,QAAQ,OAAO,CAAC;AACjG,QAAM,UAAU,MAAM,QAAQ,IAAI,SAAS,IAAI,CAAC,YAAY,QAAQ,QAAQ,OAAO,CAAC,CAAC;AACrF,UAAQ,QAAQ,CAAC,SAAS,UAAU;AAClC,UAAM,MAAM,OAAO,KAAK,GAAG,OAAO;AAClC,WAAO,YAAY,WAAW,WAAW,OAAO,EAAE,KAAK,GAAG;AAAA,EAC5D,CAAC;AACD,SAAO;AACT;AAcA,SAAS,qBAAqB,KAAyC;AACrE,MAAI,CAAC,SAAS,GAAG,EAAG,QAAO;AAC3B,QAAM,EAAE,SAAS,YAAY,KAAK,IAAI;AACtC,MAAI,OAAO,YAAY,YAAY,QAAQ,WAAW,EAAG,QAAO;AAChE,MAAI,eAAe,UAAa,eAAe,SAAS,OAAO,eAAe,YAAY,WAAW,WAAW,IAAI;AAClH,WAAO;AAAA,EACT;AACA,MAAI,SAAS,UAAa,SAAS,QAAQ,CAAC,SAAS,IAAI,EAAG,QAAO;AACnE,SAAO;AAAA,IACL;AAAA,IACA,GAAI,OAAO,eAAe,WAAW,EAAE,WAAW,IAAI,CAAC;AAAA,IACvD,GAAI,SAAS,IAAI,IAAI,EAAE,KAAK,IAAI,CAAC;AAAA,EACnC;AACF;AAOO,SAAS,iBAAiB,YAAqB,SAA+D;AACnH,QAAM,UAAU,qBAAqB,UAAU;AAC/C,MAAI,OAAO,YAAY,SAAU,QAAO,EAAE,IAAI,OAAO,OAAO,mBAAmB,SAAS,QAAQ;AAChG,MAAI,CAAC,oBAAoB,QAAQ,OAAO,GAAG;AACzC,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO;AAAA,MACP,SAAS,EAAE,SAAS,QAAQ,SAAS,MAAM,6DAA6D;AAAA,IAC1G;AAAA,EACF;AACA,wBAAsB,QAAQ,UAAU,QAAQ,SAAS,QAAQ,cAAc,qBAAqB,QAAQ,IAAI;AAChH,SAAO,EAAE,IAAI,MAAM,QAAQ,MAAM,SAAS,QAAQ,SAAS,YAAY,QAAQ,cAAc,KAAK;AACpG;;;AD/IO,SAAS,qBAAqB,SAAiD,aAAyC;AAC7H,QAAM,UAAU,cAAc,IAAI,IAAI,WAAW,IAAI;AACrD,SAAO,OAAO,OAAO,OAAO,EACzB,OAAO,CAAC,UAAU,CAAC,WAAW,QAAQ,IAAI,MAAM,OAAO,CAAC,EACxD,IAAI,CAAC,UAAU,gBAAgB,EAAE,KAAK,MAAM,SAAS,IAAI,MAAM,YAAY,MAAM,MAAM,KAAK,CAAC,CAAC,EAC9F,KAAK,GAAG;AACb;AAGO,SAAS,sBAAsB,cAAsB,aAAqB,aAAyC;AACxH,MAAI,CAAC,YAAa,QAAO;AACzB,QAAM,UAAU,IAAI,IAAI,WAAW;AACnC,QAAM,YAAY,aACf,MAAM,GAAG,EACT,OAAO,OAAO,EACd,OAAO,CAAC,UAAU,CAAC,QAAQ,IAAI,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC;AAC5D,SAAO,CAAC,GAAG,WAAW,GAAG,YAAY,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC,EAAE,KAAK,GAAG;AAC3E;AAMO,SAAS,qBAAqB,cAAsB,kBAA6C;AACtG,MAAI,iBAAiB,WAAW,EAAG,QAAO;AAC1C,QAAM,UAAU,aAAa,MAAM,GAAG,EAAE,OAAO,OAAO;AACtD,QAAM,cAAc,IAAI,IAAI,QAAQ,IAAI,CAAC,UAAU,iBAAiB,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;AAC/F,QAAM,OAAO,iBAAiB,OAAO,CAAC,UAAU,QAAQ,KAAK,KAAK,CAAC,YAAY,IAAI,iBAAiB,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;AAC/H,SAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EAAE,KAAK,GAAG;AACvC;AAGO,SAAS,qBAAqB,MAAiC;AACpE,SACE,uDAAuD,KAAK,KAAK,IAAI,CAAC;AAG1E;AAUA,IAAM,gBAAgB,MAAM,MAAM;AAAC;AAE5B,SAAS,mBAAmB,EAAE,aAAa,iBAAiB,GAAkC;AACnG,QAAM,QAAQ,eAAe;AAC7B,QAAM,WAAWC,mBAAkB;AACnC,QAAM,UAAU,kBAAkB,oBAAoB;AACtD,QAAM,aAAa,kBAAkB,mBAAmB;AACxD,QAAM,SAAS,MAAM;AAErB,QAAM,SAAS,qBAAqB,OAAO,aAAa,eAAe,OAAO,QAAQ,MAAM,EAAE;AAE9F,QAAM,kBAAkB,OAAO,KAAK;AAGpC,QAAM,aAAa,OAAO,oBAAI,IAA0B,CAAC;AACzD,QAAM,YAAY,OAAO,oBAAI,IAAY,CAAC;AAC1C,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,KAAK;AAChD,QAAM,CAAC,WAAW,YAAY,IAAI,SAAS,CAAC;AAC5C,QAAM,WAAW,oBAAoB;AAErC,QAAM,WAAW,CAAC,MAAyB,WAAwE;AACjH,UAAM,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,UAAU,QAAQ,IAAI,GAAG,CAAC;AAC9D,QAAI,MAAM,WAAW,EAAG;AACxB,eAAW,OAAO,MAAO,WAAU,QAAQ,IAAI,GAAG;AAClD,UAAM,SAAS,MAAM,KAAK,IAAI;AAC9B,UAAM,MACJ,WAAW,gBACP,iCAAiC,MAAM,SAAS,IAAI,eAAe,UAAU,KAC7E,WAAW,mBACT,uBACA,sDAAsD,QAAQ;AACtE,UAAM,UACJ,qCAAqC,MAAM,MAAM,GAAG;AAEtD,UAAM,OAAO,QAAQ,IAAI,MAAM,OAAO,GAAG;AAAA,MACvC,QAAQ;AAAA,MACR,UAAU,WAAW,MAAM;AAAA,MAC3B,MAAM;AAAA,MACN,UAAU;AAAA,MACV,YAAY;AAAA,MACZ,aAAa,qBAAqB,KAAK;AAAA,IACzC,CAAC;AACD,UAAM,OAAO,MAAM,qBAAqB,KAAK,GAAG,EAAE,UAAU,KAAO,CAAC;AAAA,EACtE;AACA,QAAM,cAAc,OAAO,QAAQ;AACnC,cAAY,UAAU;AAGtB,EAAAC,WAAU,MAAM;AACd,QAAI,gBAAgB,QAAS;AAC7B,oBAAgB,UAAU;AAC1B,UAAM,UAAU,cAAc,IAAI,IAAI,WAAW,IAAI;AACrD,UAAM,SAAS,eAAe,gBAAgB,OAAO,OAAO,CAAC,CAAC;AAC9D,UAAM,aAAuB,CAAC;AAC9B,eAAW,SAAS,QAAQ;AAC1B,UAAI,WAAW,CAAC,QAAQ,IAAI,MAAM,GAAG,EAAG;AACxC,YAAM,eAAe,iBAAiB,MAAM,GAAG;AAC/C,YAAM,aAAa,GAAG,YAAY,KAAS,MAAM,MAAM,EAAE;AACzD,YAAM,UAAwB,EAAE,OAAO,kBAAkB,MAAM,GAAG,GAAG,UAAU,MAAM,KAAK,aAAa;AACvG,UAAI,CAACC,yBAAwB,MAAM,GAAG,GAAG,MAAM;AAC7C,mBAAW,QAAQ,IAAI,YAAY,EAAE,GAAG,SAAS,OAAO,MAAM,IAAI,CAAC;AACnE,mBAAW,KAAK,MAAM,GAAG;AACzB;AAAA,MACF;AACA,iBAAW,QAAQ,IAAI,YAAY,OAAO;AAC1C,YAAM,UAAU,iBAAiB,OAAO,UAAU,CAAC,UAAU;AAC3D,cAAM,OAAO,QAAQ,OAAO,EAAE,QAAQ,sBAAsB,OAAO,MAAM,IAAI,CAAC;AAAA,MAChF,CAAC;AACD,YAAM,QAAQ,CAAC,WAAyB;AAEtC,YAAI,WAAW,aAAa,WAAW,QAAQ,IAAI,UAAU,MAAM,SAAS;AAC1E,qBAAW,QAAQ,OAAO,UAAU;AACpC,uBAAa,CAAC,MAAM,IAAI,CAAC;AAAA,QAC3B;AAAA,MACF;AACA,UAAI,OAAO,YAAY,SAAU,OAAM,OAAO;AAAA,UACzC,MAAK,QAAQ,KAAK,KAAK;AAAA,IAC9B;AACA,QAAI,WAAW,SAAS,EAAG,aAAY,QAAQ,YAAY,aAAa;AACxE,aAAS,YAAY,CAAC;AAAA,EACxB,GAAG,CAAC,UAAU,aAAa,QAAQ,KAAK,CAAC;AAGzC,EAAAD,WAAU,MAAM;AACd,QAAI,CAAC,cAAc,WAAW,QAAQ,SAAS,EAAG,QAAO;AACzD,UAAM,QAAQ,WAAW,MAAM,aAAa,IAAI,GAAG,QAAQ;AAC3D,WAAO,MAAM,aAAa,KAAK;AAAA,EACjC,GAAG,CAAC,YAAY,QAAQ,CAAC;AAGzB,EAAAA,WAAU,MAAM;AACd,QAAI,CAAC,WAAY;AACjB,UAAM,WAAW,IAAI,IAAI,OAAO,OAAO,OAAO,EAAE,IAAI,CAAC,UAAU,iBAAiB,MAAM,OAAO,CAAC,CAAC;AAC/F,eAAW,CAAC,KAAK,OAAO,KAAK,CAAC,GAAG,WAAW,QAAQ,QAAQ,CAAC,GAAG;AAC9D,UAAI,SAAS,IAAI,QAAQ,YAAY,EAAG,YAAW,QAAQ,OAAO,GAAG;AAAA,IACvE;AACA,UAAM,eAAe,CAAC,GAAG,WAAW,QAAQ,OAAO,CAAC;AACpD,QAAI,aAAa,aAAa,SAAS,GAAG;AACxC,kBAAY;AAAA,QACV,aAAa,IAAI,CAAC,YAAY,QAAQ,QAAQ;AAAA,QAC9C;AAAA,MACF;AAAA,IACF;AAEA,UAAM,aAAa,OAAO,OAAO;AACjC,UAAM,eAAe,gBAAgB,UAAU,KAAK;AACpD,UAAM,cAAc;AAAA,MAClB,qBAAqB,SAAS,WAAW;AAAA,MACzC,aAAa,IAAI,CAAC,YAAY,QAAQ,KAAK;AAAA,IAC7C;AACA,UAAM,YAAY,sBAAsB,cAAc,aAAa,WAAW;AAC9E,QAAI,iBAAiB,UAAW,QAAO,cAAc,gBAAgB,YAAY,SAAS,CAAC;AAAA,EAC7F,GAAG,CAAC,SAAS,YAAY,aAAa,QAAQ,QAAQ,WAAW,SAAS,CAAC;AAE3E,SAAO;AACT;","names":["useEffect","getOverlayMetaByLinkKey","useSummonDispatch","useSummonDispatch","useEffect","getOverlayMetaByLinkKey"]}

package/dist/window-host.cjs

@@ -0,0 +1,123 @@
+"use client";
+"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/window-host.ts
+var window_host_exports = {};
+__export(window_host_exports, {
+  DEFAULT_ESCAPE_YIELD_SELECTOR: () => DEFAULT_ESCAPE_YIELD_SELECTOR,
+  DEFAULT_MOBILE_TOP_OFFSET: () => DEFAULT_MOBILE_TOP_OFFSET,
+  DEFAULT_WINDOW_CONFIG: () => DEFAULT_WINDOW_CONFIG,
+  WindowSelectionSurface: () => WindowSelectionSurface,
+  WindowTraySync: () => WindowTraySync,
+  WindowsProvider: () => WindowsProvider,
+  getTrayPreviewEntry: () => getTrayPreviewEntry,
+  registerTrayPreview: () => registerTrayPreview,
+  resetTrayPreviews: () => resetTrayPreviews,
+  useWindowConfig: () => useWindowConfig
+});
+module.exports = __toCommonJS(window_host_exports);
+
+// src/window/config.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function PassthroughSurface({ children }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children });
+}
+var DEFAULT_ESCAPE_YIELD_SELECTOR = "[data-overlay-escape-yield]";
+var DEFAULT_MOBILE_TOP_OFFSET = "var(--header-height, 0px)";
+var DEFAULT_WINDOW_CONFIG = {
+  escapeYieldSelector: DEFAULT_ESCAPE_YIELD_SELECTOR,
+  mobileTopOffset: DEFAULT_MOBILE_TOP_OFFSET,
+  selectionSurface: PassthroughSurface
+};
+var WindowConfigContext = (0, import_react.createContext)(DEFAULT_WINDOW_CONFIG);
+WindowConfigContext.displayName = "WindowConfigContext";
+function WindowsProvider({ escapeYieldSelector, mobileTopOffset, selectionSurface, children }) {
+  const value = (0, import_react.useMemo)(
+    () => ({
+      escapeYieldSelector: escapeYieldSelector ?? DEFAULT_WINDOW_CONFIG.escapeYieldSelector,
+      mobileTopOffset: mobileTopOffset ?? DEFAULT_WINDOW_CONFIG.mobileTopOffset,
+      selectionSurface: selectionSurface ?? DEFAULT_WINDOW_CONFIG.selectionSurface
+    }),
+    [escapeYieldSelector, mobileTopOffset, selectionSurface]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(WindowConfigContext.Provider, { value, children });
+}
+function useWindowConfig() {
+  return (0, import_react.useContext)(WindowConfigContext);
+}
+function WindowSelectionSurface({ children }) {
+  const Surface = useWindowConfig().selectionSurface;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Surface, { children });
+}
+
+// src/window/WindowTraySync.tsx
+var import_react2 = require("react");
+var import_react3 = require("@ai-matrx/summon/react");
+var import_summon = require("@ai-matrx/summon");
+var import_summon2 = require("@ai-matrx/summon");
+var DEBOUNCE_MS = 500;
+function WindowTraySync() {
+  const dispatch = (0, import_react3.useSummonDispatch)();
+  (0, import_react2.useEffect)(() => {
+    let timer = null;
+    const syncWindowGeometry = () => {
+      const { vw, vh, degenerate } = (0, import_summon2.safeViewportDims)();
+      if (degenerate) return;
+      dispatch(
+        (0, import_summon.recomputeTrayPositions)({ viewportWidth: vw, viewportHeight: vh })
+      );
+      dispatch((0, import_summon.clampAllWindowRects)({ viewportWidth: vw, viewportHeight: vh }));
+    };
+    syncWindowGeometry();
+    const handleResize = () => {
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        syncWindowGeometry();
+      }, DEBOUNCE_MS);
+    };
+    window.addEventListener("resize", handleResize, { passive: true });
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      if (timer !== null) clearTimeout(timer);
+    };
+  }, [dispatch]);
+  return null;
+}
+
+// src/window/tray/trayPreviewRegistry.ts
+var import_global_slot = require("@ai-matrx/kit/global-slot");
+var EMPTY = {};
+var registry = () => (0, import_global_slot.globalSlot)("ai-matrx.summon.window.trayPreviews", () => /* @__PURE__ */ new Map());
+function registerTrayPreview(overlayId, preview) {
+  const entry = typeof preview === "function" ? { Preview: preview } : preview;
+  registry().set(overlayId, entry);
+  return () => {
+    if (registry().get(overlayId) === entry) registry().delete(overlayId);
+  };
+}
+function getTrayPreviewEntry(overlayId) {
+  return registry().get(overlayId) ?? EMPTY;
+}
+function resetTrayPreviews() {
+  registry().clear();
+}
+//# sourceMappingURL=window-host.cjs.map

package/dist/window-host.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/window-host.ts","../src/window/config.tsx","../src/window/WindowTraySync.tsx","../src/window/tray/trayPreviewRegistry.ts"],"sourcesContent":["// @ai-matrx/summon/window-host — the light half of the window section, safe to mount at the app\n// root: window configuration (WindowsProvider), the viewport/tray sync, and tray-preview\n// registration. Importing it never loads WindowPanel; the window section reads this section's\n// context through the package name, so both share one context.\nexport {\n  WindowsProvider,\n  useWindowConfig,\n  WindowSelectionSurface,\n  DEFAULT_WINDOW_CONFIG,\n  DEFAULT_ESCAPE_YIELD_SELECTOR,\n  DEFAULT_MOBILE_TOP_OFFSET,\n  type WindowConfig,\n  type WindowsProviderProps,\n  type WindowSelectionSurfaceProps,\n} from \"./window/config\";\nexport { WindowTraySync } from \"./window/WindowTraySync\";\nexport {\n  registerTrayPreview,\n  getTrayPreviewEntry,\n  resetTrayPreviews,\n  type TrayPreviewContext,\n  type TrayPreviewEntry,\n  type TraySnapshotCapture,\n} from \"./window/tray/trayPreviewRegistry\";\n","\"use client\";\n\n/**\n * WindowsProvider — the window section's host options, read by every WindowPanel through context.\n * Everything has a working default, so no provider is needed at all; a host passes only what it\n * has (AI Matrx: its right-click selection menu and its header offset).\n */\nimport { createContext, useContext, useMemo, type ComponentType, type ReactNode } from \"react\";\n\nexport interface WindowSelectionSurfaceProps {\n  readonly children: ReactNode;\n}\n\nexport interface WindowConfig {\n  /**\n   * Visible elements matching this selector own the Escape key: a window with `closeOnEscape`\n   * yields to them (menus, popovers, listboxes and open dialogs always do). Default\n   * `[data-overlay-escape-yield]` — mark any host surface that must take Escape first.\n   */\n  readonly escapeYieldSelector: string;\n  /** Top offset of a phone fullscreen window (below the host's header). Default `var(--header-height, 0px)`. */\n  readonly mobileTopOffset: string;\n  /**\n   * Wraps every window body (desktop, popped out, and all three phone presentations). Default:\n   * passthrough. AI Matrx injects its selection toolbar + right-click menu here.\n   */\n  readonly selectionSurface: ComponentType<WindowSelectionSurfaceProps>;\n}\n\nfunction PassthroughSurface({ children }: WindowSelectionSurfaceProps) {\n  return <>{children}</>;\n}\n\nexport const DEFAULT_ESCAPE_YIELD_SELECTOR = \"[data-overlay-escape-yield]\";\nexport const DEFAULT_MOBILE_TOP_OFFSET = \"var(--header-height, 0px)\";\n\nexport const DEFAULT_WINDOW_CONFIG: WindowConfig = {\n  escapeYieldSelector: DEFAULT_ESCAPE_YIELD_SELECTOR,\n  mobileTopOffset: DEFAULT_MOBILE_TOP_OFFSET,\n  selectionSurface: PassthroughSurface,\n};\n\nconst WindowConfigContext = createContext<WindowConfig>(DEFAULT_WINDOW_CONFIG);\nWindowConfigContext.displayName = \"WindowConfigContext\";\n\nexport interface WindowsProviderProps extends Partial<WindowConfig> {\n  readonly children?: ReactNode;\n}\n\nexport function WindowsProvider({ escapeYieldSelector, mobileTopOffset, selectionSurface, children }: WindowsProviderProps) {\n  const value = useMemo<WindowConfig>(\n    () => ({\n      escapeYieldSelector: escapeYieldSelector ?? DEFAULT_WINDOW_CONFIG.escapeYieldSelector,\n      mobileTopOffset: mobileTopOffset ?? DEFAULT_WINDOW_CONFIG.mobileTopOffset,\n      selectionSurface: selectionSurface ?? DEFAULT_WINDOW_CONFIG.selectionSurface,\n    }),\n    [escapeYieldSelector, mobileTopOffset, selectionSurface],\n  );\n  return <WindowConfigContext.Provider value={value}>{children}</WindowConfigContext.Provider>;\n}\n\nexport function useWindowConfig(): WindowConfig {\n  return useContext(WindowConfigContext);\n}\n\n/** The configured selection surface, as a component. */\nexport function WindowSelectionSurface({ children }: WindowSelectionSurfaceProps) {\n  const Surface = useWindowConfig().selectionSurface;\n  return <Surface>{children}</Surface>;\n}\n","\"use client\";\n\n/**\n * WindowTraySync\n *\n * Mounts ONCE in the root layout. Attaches a single debounced resize listener\n * that:\n *  1. Recomputes the positions of all minimized windows (tray slots can change\n *     when chips-per-row shifts on viewport resize).\n *  2. Clamps every docked windowed window into the new viewport so windows\n *     positioned for a larger screen stay reachable after a downsize.\n *\n * Zero re-renders — fires and forgets.\n *\n * Debounce: 500ms — a continuous window-drag generates exactly one dispatch\n * when the user stops moving. Short bursts (e.g. snapping) are ignored.\n *\n * Usage (in both authenticated and SSR root layouts):\n *   <WindowTraySync />\n */\n\nimport { useEffect } from \"react\";\nimport { useSummonDispatch } from \"@ai-matrx/summon/react\";\nimport {\n  recomputeTrayPositions,\n  clampAllWindowRects,\n} from \"@ai-matrx/summon\";\nimport { safeViewportDims } from \"@ai-matrx/summon\";\n\nconst DEBOUNCE_MS = 500;\n\nexport function WindowTraySync() {\n  const dispatch = useSummonDispatch();\n\n  useEffect(() => {\n    let timer: ReturnType<typeof setTimeout> | null = null;\n\n    const syncWindowGeometry = () => {\n      // A resize that measures 0×0 is a hidden/undisplayed tab or a\n      // display:none ancestor, never a real screen. Bail WITHOUT dispatching:\n      // reacting to it would rewrite every window rect and every tray slot\n      // against invented dimensions, and the next real measurement would\n      // then have to undo it. No measurement, no write.\n      const { vw, vh, degenerate } = safeViewportDims();\n      if (degenerate) return;\n      dispatch(\n        recomputeTrayPositions({ viewportWidth: vw, viewportHeight: vh }),\n      );\n      dispatch(clampAllWindowRects({ viewportWidth: vw, viewportHeight: vh }));\n    };\n\n    // This island may load after the viewport already changed. Synchronising\n    // once on mount closes that event-listener gap for persisted windows.\n    syncWindowGeometry();\n\n    const handleResize = () => {\n      if (timer !== null) clearTimeout(timer);\n      timer = setTimeout(() => {\n        timer = null;\n        syncWindowGeometry();\n      }, DEBOUNCE_MS);\n    };\n\n    window.addEventListener(\"resize\", handleResize, { passive: true });\n\n    return () => {\n      window.removeEventListener(\"resize\", handleResize);\n      if (timer !== null) clearTimeout(timer);\n    };\n  }, [dispatch]);\n\n  return null;\n}\n\nexport default WindowTraySync;\n","/**\n * Tray previews — overlay id → a semantic minimized preview and/or a custom snapshot capture.\n *\n * The host registers its previews once (AI Matrx keeps its own preview components in the app):\n *\n *   registerTrayPreview(\"notesWindow\", NotesTrayPreview);\n *   registerTrayPreview(\"canvasWindow\", { captureTraySnapshot: captureCanvas });\n *\n * A window with a preview component skips snapshot capture entirely (cheaper, higher fidelity).\n * A window with neither gets the default capture (`defaultTraySnapshotCapture`, html-to-image when\n * the host installed it). State lives in a global slot (kit globalSlot, D9).\n */\nimport type { ComponentType } from \"react\";\nimport { globalSlot } from \"@ai-matrx/kit/global-slot\";\n\nexport interface TrayPreviewContext {\n  /** The window's allowlisted semantic data (open data merged with what `onCollectData` returned). */\n  readonly data: Readonly<Record<string, unknown>>;\n  /** Stable overlay id (the registry key). */\n  readonly overlayId: string;\n  /** Instance id — `\"default\"` for singleton windows. */\n  readonly instanceId: string;\n  /** The display title. */\n  readonly title: string;\n}\n\nexport type TraySnapshotCapture = (bodyEl: HTMLElement) => Promise<Blob | null>;\n\nexport interface TrayPreviewEntry {\n  readonly Preview?: ComponentType<TrayPreviewContext>;\n  readonly captureTraySnapshot?: TraySnapshotCapture;\n}\n\nconst EMPTY: TrayPreviewEntry = {};\n\nconst registry = (): Map<string, TrayPreviewEntry> =>\n  globalSlot<Map<string, TrayPreviewEntry>>(\"ai-matrx.summon.window.trayPreviews\", () => new Map());\n\n/**\n * Register the minimized preview for an overlay (or any window id). Pass a component, or an entry\n * with `Preview` and/or `captureTraySnapshot`. Re-registering replaces. Returns an unregister.\n */\nexport function registerTrayPreview(\n  overlayId: string,\n  preview: ComponentType<TrayPreviewContext> | TrayPreviewEntry,\n): () => void {\n  const entry: TrayPreviewEntry = typeof preview === \"function\" ? { Preview: preview } : preview;\n  registry().set(overlayId, entry);\n  return () => {\n    if (registry().get(overlayId) === entry) registry().delete(overlayId);\n  };\n}\n\nexport function getTrayPreviewEntry(overlayId: string): TrayPreviewEntry {\n  return registry().get(overlayId) ?? EMPTY;\n}\n\n/** Test-only. */\nexport function resetTrayPreviews(): void {\n  registry().clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOA,mBAAuF;AAuB9E;AADT,SAAS,mBAAmB,EAAE,SAAS,GAAgC;AACrE,SAAO,2EAAG,UAAS;AACrB;AAEO,IAAM,gCAAgC;AACtC,IAAM,4BAA4B;AAElC,IAAM,wBAAsC;AAAA,EACjD,qBAAqB;AAAA,EACrB,iBAAiB;AAAA,EACjB,kBAAkB;AACpB;AAEA,IAAM,0BAAsB,4BAA4B,qBAAqB;AAC7E,oBAAoB,cAAc;AAM3B,SAAS,gBAAgB,EAAE,qBAAqB,iBAAiB,kBAAkB,SAAS,GAAyB;AAC1H,QAAM,YAAQ;AAAA,IACZ,OAAO;AAAA,MACL,qBAAqB,uBAAuB,sBAAsB;AAAA,MAClE,iBAAiB,mBAAmB,sBAAsB;AAAA,MAC1D,kBAAkB,oBAAoB,sBAAsB;AAAA,IAC9D;AAAA,IACA,CAAC,qBAAqB,iBAAiB,gBAAgB;AAAA,EACzD;AACA,SAAO,4CAAC,oBAAoB,UAApB,EAA6B,OAAe,UAAS;AAC/D;AAEO,SAAS,kBAAgC;AAC9C,aAAO,yBAAW,mBAAmB;AACvC;AAGO,SAAS,uBAAuB,EAAE,SAAS,GAAgC;AAChF,QAAM,UAAU,gBAAgB,EAAE;AAClC,SAAO,4CAAC,WAAS,UAAS;AAC5B;;;AChDA,IAAAA,gBAA0B;AAC1B,IAAAA,gBAAkC;AAClC,oBAGO;AACP,IAAAC,iBAAiC;AAEjC,IAAM,cAAc;AAEb,SAAS,iBAAiB;AAC/B,QAAM,eAAW,iCAAkB;AAEnC,+BAAU,MAAM;AACd,QAAI,QAA8C;AAElD,UAAM,qBAAqB,MAAM;AAM/B,YAAM,EAAE,IAAI,IAAI,WAAW,QAAI,iCAAiB;AAChD,UAAI,WAAY;AAChB;AAAA,YACE,sCAAuB,EAAE,eAAe,IAAI,gBAAgB,GAAG,CAAC;AAAA,MAClE;AACA,mBAAS,mCAAoB,EAAE,eAAe,IAAI,gBAAgB,GAAG,CAAC,CAAC;AAAA,IACzE;AAIA,uBAAmB;AAEnB,UAAM,eAAe,MAAM;AACzB,UAAI,UAAU,KAAM,cAAa,KAAK;AACtC,cAAQ,WAAW,MAAM;AACvB,gBAAQ;AACR,2BAAmB;AAAA,MACrB,GAAG,WAAW;AAAA,IAChB;AAEA,WAAO,iBAAiB,UAAU,cAAc,EAAE,SAAS,KAAK,CAAC;AAEjE,WAAO,MAAM;AACX,aAAO,oBAAoB,UAAU,YAAY;AACjD,UAAI,UAAU,KAAM,cAAa,KAAK;AAAA,IACxC;AAAA,EACF,GAAG,CAAC,QAAQ,CAAC;AAEb,SAAO;AACT;;;AC3DA,yBAA2B;AAoB3B,IAAM,QAA0B,CAAC;AAEjC,IAAM,WAAW,UACf,+BAA0C,uCAAuC,MAAM,oBAAI,IAAI,CAAC;AAM3F,SAAS,oBACd,WACA,SACY;AACZ,QAAM,QAA0B,OAAO,YAAY,aAAa,EAAE,SAAS,QAAQ,IAAI;AACvF,WAAS,EAAE,IAAI,WAAW,KAAK;AAC/B,SAAO,MAAM;AACX,QAAI,SAAS,EAAE,IAAI,SAAS,MAAM,MAAO,UAAS,EAAE,OAAO,SAAS;AAAA,EACtE;AACF;AAEO,SAAS,oBAAoB,WAAqC;AACvE,SAAO,SAAS,EAAE,IAAI,SAAS,KAAK;AACtC;AAGO,SAAS,oBAA0B;AACxC,WAAS,EAAE,MAAM;AACnB;","names":["import_react","import_summon"]}

package/dist/window-host.d.cts

@@ -0,0 +1,72 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+
+interface WindowSelectionSurfaceProps {
+    readonly children: ReactNode;
+}
+interface WindowConfig {
+    /**
+     * Visible elements matching this selector own the Escape key: a window with `closeOnEscape`
+     * yields to them (menus, popovers, listboxes and open dialogs always do). Default
+     * `[data-overlay-escape-yield]` — mark any host surface that must take Escape first.
+     */
+    readonly escapeYieldSelector: string;
+    /** Top offset of a phone fullscreen window (below the host's header). Default `var(--header-height, 0px)`. */
+    readonly mobileTopOffset: string;
+    /**
+     * Wraps every window body (desktop, popped out, and all three phone presentations). Default:
+     * passthrough. AI Matrx injects its selection toolbar + right-click menu here.
+     */
+    readonly selectionSurface: ComponentType<WindowSelectionSurfaceProps>;
+}
+declare const DEFAULT_ESCAPE_YIELD_SELECTOR = "[data-overlay-escape-yield]";
+declare const DEFAULT_MOBILE_TOP_OFFSET = "var(--header-height, 0px)";
+declare const DEFAULT_WINDOW_CONFIG: WindowConfig;
+interface WindowsProviderProps extends Partial<WindowConfig> {
+    readonly children?: ReactNode;
+}
+declare function WindowsProvider({ escapeYieldSelector, mobileTopOffset, selectionSurface, children }: WindowsProviderProps): react.JSX.Element;
+declare function useWindowConfig(): WindowConfig;
+/** The configured selection surface, as a component. */
+declare function WindowSelectionSurface({ children }: WindowSelectionSurfaceProps): react.JSX.Element;
+
+declare function WindowTraySync(): null;
+
+/**
+ * Tray previews — overlay id → a semantic minimized preview and/or a custom snapshot capture.
+ *
+ * The host registers its previews once (AI Matrx keeps its own preview components in the app):
+ *
+ *   registerTrayPreview("notesWindow", NotesTrayPreview);
+ *   registerTrayPreview("canvasWindow", { captureTraySnapshot: captureCanvas });
+ *
+ * A window with a preview component skips snapshot capture entirely (cheaper, higher fidelity).
+ * A window with neither gets the default capture (`defaultTraySnapshotCapture`, html-to-image when
+ * the host installed it). State lives in a global slot (kit globalSlot, D9).
+ */
+
+interface TrayPreviewContext {
+    /** The window's allowlisted semantic data (open data merged with what `onCollectData` returned). */
+    readonly data: Readonly<Record<string, unknown>>;
+    /** Stable overlay id (the registry key). */
+    readonly overlayId: string;
+    /** Instance id — `"default"` for singleton windows. */
+    readonly instanceId: string;
+    /** The display title. */
+    readonly title: string;
+}
+type TraySnapshotCapture = (bodyEl: HTMLElement) => Promise<Blob | null>;
+interface TrayPreviewEntry {
+    readonly Preview?: ComponentType<TrayPreviewContext>;
+    readonly captureTraySnapshot?: TraySnapshotCapture;
+}
+/**
+ * Register the minimized preview for an overlay (or any window id). Pass a component, or an entry
+ * with `Preview` and/or `captureTraySnapshot`. Re-registering replaces. Returns an unregister.
+ */
+declare function registerTrayPreview(overlayId: string, preview: ComponentType<TrayPreviewContext> | TrayPreviewEntry): () => void;
+declare function getTrayPreviewEntry(overlayId: string): TrayPreviewEntry;
+/** Test-only. */
+declare function resetTrayPreviews(): void;
+
+export { DEFAULT_ESCAPE_YIELD_SELECTOR, DEFAULT_MOBILE_TOP_OFFSET, DEFAULT_WINDOW_CONFIG, type TrayPreviewContext, type TrayPreviewEntry, type TraySnapshotCapture, type WindowConfig, WindowSelectionSurface, type WindowSelectionSurfaceProps, WindowTraySync, WindowsProvider, type WindowsProviderProps, getTrayPreviewEntry, registerTrayPreview, resetTrayPreviews, useWindowConfig };