@ai-matrx/summon 0.0.0 → 0.1.0

package/dist/testing.d.cts

@@ -0,0 +1,44 @@
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import * as _ai_matrx_summon from '@ai-matrx/summon';
+import { IdentityPort, RouterPort, OverlayPersistencePort, StoredValue, NotifyPort, ErrorSinkPort, SummonPorts } from '@ai-matrx/summon';
+
+interface ControllableIdentity extends IdentityPort {
+    set(key: string, ready?: boolean): void;
+}
+declare function createTestIdentity(key?: string, ready?: boolean): ControllableIdentity;
+interface ControllableRouter extends RouterPort {
+    /** Simulate a navigation: new pathname (and optional search), listeners notified. */
+    navigate(pathname: string, search?: string): void;
+}
+declare function createTestRouter(pathname?: string, search?: string): ControllableRouter;
+declare class TestVersionConflictError extends Error {
+    readonly key: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(key: string, expected: number, actual: number);
+}
+/** An in-memory, versioned persistence port (per person, like the database adapter). */
+declare function createMemoryPersistence(options?: {
+    readonly perPerson?: boolean;
+}): OverlayPersistencePort & {
+    readonly rows: Map<string, StoredValue>;
+};
+interface RecordedMessage {
+    readonly level: "info" | "warn" | "error";
+    readonly message: string;
+}
+/** Notify + error ports that record instead of printing. */
+declare function createRecordingPorts(): {
+    notify: NotifyPort;
+    errors: ErrorSinkPort;
+    messages: RecordedMessage[];
+    captured: unknown[];
+};
+/** Test ports: quiet recording notify/errors, controllable identity and router, persistence off. */
+declare function createTestPorts(overrides?: Partial<SummonPorts>): SummonPorts & ReturnType<typeof createRecordingPorts>;
+/** A real overlays store wired to test ports. */
+declare function createTestSummonStore(ports?: SummonPorts): _reduxjs_toolkit.EnhancedStore<_ai_matrx_summon.SummonRootState, _reduxjs_toolkit.UnknownAction, _reduxjs_toolkit.Tuple<[_reduxjs_toolkit.StoreEnhancer<{
+    dispatch: _reduxjs_toolkit.ThunkDispatch<_ai_matrx_summon.SummonRootState, undefined, _reduxjs_toolkit.UnknownAction>;
+}>, _reduxjs_toolkit.StoreEnhancer]>>;
+
+export { type ControllableIdentity, type ControllableRouter, type RecordedMessage, TestVersionConflictError, createMemoryPersistence, createRecordingPorts, createTestIdentity, createTestPorts, createTestRouter, createTestSummonStore };

package/dist/testing.d.ts

@@ -0,0 +1,44 @@
+import * as _reduxjs_toolkit from '@reduxjs/toolkit';
+import * as _ai_matrx_summon from '@ai-matrx/summon';
+import { IdentityPort, RouterPort, OverlayPersistencePort, StoredValue, NotifyPort, ErrorSinkPort, SummonPorts } from '@ai-matrx/summon';
+
+interface ControllableIdentity extends IdentityPort {
+    set(key: string, ready?: boolean): void;
+}
+declare function createTestIdentity(key?: string, ready?: boolean): ControllableIdentity;
+interface ControllableRouter extends RouterPort {
+    /** Simulate a navigation: new pathname (and optional search), listeners notified. */
+    navigate(pathname: string, search?: string): void;
+}
+declare function createTestRouter(pathname?: string, search?: string): ControllableRouter;
+declare class TestVersionConflictError extends Error {
+    readonly key: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(key: string, expected: number, actual: number);
+}
+/** An in-memory, versioned persistence port (per person, like the database adapter). */
+declare function createMemoryPersistence(options?: {
+    readonly perPerson?: boolean;
+}): OverlayPersistencePort & {
+    readonly rows: Map<string, StoredValue>;
+};
+interface RecordedMessage {
+    readonly level: "info" | "warn" | "error";
+    readonly message: string;
+}
+/** Notify + error ports that record instead of printing. */
+declare function createRecordingPorts(): {
+    notify: NotifyPort;
+    errors: ErrorSinkPort;
+    messages: RecordedMessage[];
+    captured: unknown[];
+};
+/** Test ports: quiet recording notify/errors, controllable identity and router, persistence off. */
+declare function createTestPorts(overrides?: Partial<SummonPorts>): SummonPorts & ReturnType<typeof createRecordingPorts>;
+/** A real overlays store wired to test ports. */
+declare function createTestSummonStore(ports?: SummonPorts): _reduxjs_toolkit.EnhancedStore<_ai_matrx_summon.SummonRootState, _reduxjs_toolkit.UnknownAction, _reduxjs_toolkit.Tuple<[_reduxjs_toolkit.StoreEnhancer<{
+    dispatch: _reduxjs_toolkit.ThunkDispatch<_ai_matrx_summon.SummonRootState, undefined, _reduxjs_toolkit.UnknownAction>;
+}>, _reduxjs_toolkit.StoreEnhancer]>>;
+
+export { type ControllableIdentity, type ControllableRouter, type RecordedMessage, TestVersionConflictError, createMemoryPersistence, createRecordingPorts, createTestIdentity, createTestPorts, createTestRouter, createTestSummonStore };

package/dist/testing.js

@@ -0,0 +1,115 @@
+"use client";
+
+// src/testing.ts
+import {
+  createSummonStore,
+  DEFAULT_PORTS
+} from "@ai-matrx/summon";
+function createTestIdentity(key = "test-person", ready = true) {
+  let current = { key, ready };
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    current: () => current,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    set(next, nextReady = true) {
+      current = { key: next, ready: nextReady };
+      for (const listener of listeners) listener();
+    }
+  };
+}
+function createTestRouter(pathname = "/", search = "") {
+  let path = pathname;
+  let query = search;
+  const listeners = /* @__PURE__ */ new Set();
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+  return {
+    pathname: () => path,
+    search: () => query,
+    replaceSearch: (next) => {
+      query = next && !next.startsWith("?") ? `?${next}` : next;
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    navigate(nextPath, nextSearch = "") {
+      path = nextPath;
+      query = nextSearch;
+      notify();
+    }
+  };
+}
+var TestVersionConflictError = class extends Error {
+  constructor(key, expected, actual) {
+    super(`version conflict on "${key}": expected ${expected}, found ${actual}`);
+    this.key = key;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "TestVersionConflictError";
+  }
+  key;
+  expected;
+  actual;
+};
+function createMemoryPersistence(options = {}) {
+  const rows = /* @__PURE__ */ new Map();
+  return {
+    perPerson: options.perPerson ?? true,
+    rows,
+    load: async (key) => rows.get(key) ?? null,
+    save: async (key, value, saveOptions) => {
+      const current = rows.get(key)?.version ?? 0;
+      if (saveOptions?.expectedVersion !== void 0 && saveOptions.expectedVersion !== current) {
+        throw new TestVersionConflictError(key, saveOptions.expectedVersion, current);
+      }
+      rows.set(key, { value: structuredClone(value), version: current + 1 });
+      return { version: current + 1 };
+    },
+    remove: async (key) => {
+      rows.delete(key);
+    },
+    list: async (prefix) => [...rows.keys()].filter((key) => key.startsWith(prefix))
+  };
+}
+function createRecordingPorts() {
+  const messages = [];
+  const captured = [];
+  return {
+    messages,
+    captured,
+    notify: {
+      info: (message) => void messages.push({ level: "info", message }),
+      warn: (message) => void messages.push({ level: "warn", message }),
+      error: (message) => void messages.push({ level: "error", message })
+    },
+    errors: { capture: (error) => void captured.push(error) }
+  };
+}
+function createTestPorts(overrides = {}) {
+  const recording = createRecordingPorts();
+  return {
+    ...DEFAULT_PORTS,
+    identity: createTestIdentity(),
+    router: createTestRouter(),
+    ...recording,
+    ...overrides
+  };
+}
+function createTestSummonStore(ports = createTestPorts()) {
+  return createSummonStore({ ports });
+}
+export {
+  TestVersionConflictError,
+  createMemoryPersistence,
+  createRecordingPorts,
+  createTestIdentity,
+  createTestPorts,
+  createTestRouter,
+  createTestSummonStore
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["// @ai-matrx/summon/testing — fakes for hosts testing code that opens overlays: controllable\n// identity and router ports, an in-memory versioned persistence port, a quiet notify/error pair,\n// and a test store with all of them wired. No test-runner dependency.\nimport {\n  createSummonStore,\n  DEFAULT_PORTS,\n  type IdentityPort,\n  type NotifyPort,\n  type ErrorSinkPort,\n  type OverlayPersistencePort,\n  type SummonPorts,\n  type RouterPort,\n  type StoredValue,\n} from \"@ai-matrx/summon\";\n\nexport interface ControllableIdentity extends IdentityPort {\n  set(key: string, ready?: boolean): void;\n}\n\nexport function createTestIdentity(key = \"test-person\", ready = true): ControllableIdentity {\n  let current = { key, ready };\n  const listeners = new Set<() => void>();\n  return {\n    current: () => current,\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    set(next, nextReady = true) {\n      current = { key: next, ready: nextReady };\n      for (const listener of listeners) listener();\n    },\n  };\n}\n\nexport interface ControllableRouter extends RouterPort {\n  /** Simulate a navigation: new pathname (and optional search), listeners notified. */\n  navigate(pathname: string, search?: string): void;\n}\n\nexport function createTestRouter(pathname = \"/\", search = \"\"): ControllableRouter {\n  let path = pathname;\n  let query = search;\n  const listeners = new Set<() => void>();\n  const notify = () => {\n    for (const listener of listeners) listener();\n  };\n  return {\n    pathname: () => path,\n    search: () => query,\n    replaceSearch: (next) => {\n      query = next && !next.startsWith(\"?\") ? `?${next}` : next;\n    },\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    navigate(nextPath, nextSearch = \"\") {\n      path = nextPath;\n      query = nextSearch;\n      notify();\n    },\n  };\n}\n\nexport class TestVersionConflictError extends Error {\n  constructor(readonly key: string, readonly expected: number, readonly actual: number) {\n    super(`version conflict on \"${key}\": expected ${expected}, found ${actual}`);\n    this.name = \"TestVersionConflictError\";\n  }\n}\n\n/** An in-memory, versioned persistence port (per person, like the database adapter). */\nexport function createMemoryPersistence(options: { readonly perPerson?: boolean } = {}): OverlayPersistencePort & {\n  readonly rows: Map<string, StoredValue>;\n} {\n  const rows = new Map<string, StoredValue>();\n  return {\n    perPerson: options.perPerson ?? true,\n    rows,\n    load: async <T>(key: string) => (rows.get(key) as StoredValue<T> | undefined) ?? null,\n    save: async (key, value, saveOptions) => {\n      const current = rows.get(key)?.version ?? 0;\n      if (saveOptions?.expectedVersion !== undefined && saveOptions.expectedVersion !== current) {\n        throw new TestVersionConflictError(key, saveOptions.expectedVersion, current);\n      }\n      rows.set(key, { value: structuredClone(value), version: current + 1 });\n      return { version: current + 1 };\n    },\n    remove: async (key) => {\n      rows.delete(key);\n    },\n    list: async (prefix) => [...rows.keys()].filter((key) => key.startsWith(prefix)),\n  };\n}\n\nexport interface RecordedMessage {\n  readonly level: \"info\" | \"warn\" | \"error\";\n  readonly message: string;\n}\n\n/** Notify + error ports that record instead of printing. */\nexport function createRecordingPorts(): { notify: NotifyPort; errors: ErrorSinkPort; messages: RecordedMessage[]; captured: unknown[] } {\n  const messages: RecordedMessage[] = [];\n  const captured: unknown[] = [];\n  return {\n    messages,\n    captured,\n    notify: {\n      info: (message) => void messages.push({ level: \"info\", message }),\n      warn: (message) => void messages.push({ level: \"warn\", message }),\n      error: (message) => void messages.push({ level: \"error\", message }),\n    },\n    errors: { capture: (error) => void captured.push(error) },\n  };\n}\n\n/** Test ports: quiet recording notify/errors, controllable identity and router, persistence off. */\nexport function createTestPorts(overrides: Partial<SummonPorts> = {}): SummonPorts & ReturnType<typeof createRecordingPorts> {\n  const recording = createRecordingPorts();\n  return {\n    ...DEFAULT_PORTS,\n    identity: createTestIdentity(),\n    router: createTestRouter(),\n    ...recording,\n    ...overrides,\n  };\n}\n\n/** A real overlays store wired to test ports. */\nexport function createTestSummonStore(ports: SummonPorts = createTestPorts()) {\n  return createSummonStore({ ports });\n}\n"],"mappings":"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","names":[]}

package/dist/url.cjs

@@ -0,0 +1,362 @@
+"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/url.ts
+var url_exports = {};
+__export(url_exports, {
+  OverlayLinkManager: () => OverlayLinkManager,
+  canonicalLinkKey: () => canonicalLinkKey,
+  canonicalizeToken: () => canonicalizeToken,
+  decodeLinkPart: () => decodeLinkPart,
+  encodeLinkArg: () => encodeLinkArg,
+  encodeLinkId: () => encodeLinkId,
+  formatLinkToken: () => formatLinkToken,
+  hydrateLinkToken: () => hydrateLinkToken,
+  mergeManagedLinkParam: () => mergeManagedLinkParam,
+  openFromLink: () => openFromLink,
+  openPanelRequest: () => openPanelRequest,
+  openRegisteredOverlay: () => openRegisteredOverlay,
+  parseLinkParam: () => parseLinkParam,
+  parseLinkToken: () => parseLinkToken,
+  readPanelsParam: () => readPanelsParam,
+  serializeLinkEntries: () => serializeLinkEntries,
+  unopenedWindowNotice: () => unopenedWindowNotice,
+  useOverlayLink: () => useOverlayLink,
+  withPanelsParam: () => withPanelsParam,
+  withUnresolvedTokens: () => withUnresolvedTokens
+});
+module.exports = __toCommonJS(url_exports);
+
+// src/url/useOverlayLink.ts
+var import_react = require("react");
+var import_summon = require("@ai-matrx/summon");
+var import_react2 = require("@ai-matrx/summon/react");
+function useOverlayLink(linkKey, id, args) {
+  const dispatch = (0, import_react2.useSummonDispatch)();
+  const argsKey = args ? JSON.stringify(
+    Object.keys(args).sort().map((k) => [k, args[k]])
+  ) : "";
+  const stableArgs = (0, import_react.useMemo)(() => args ? { ...args } : void 0, [argsKey]);
+  (0, import_react.useEffect)(() => {
+    if (!linkKey || !id) return void 0;
+    dispatch((0, import_summon.registerSyncEntry)(stableArgs ? { typeKey: linkKey, instanceId: id, args: stableArgs } : { typeKey: linkKey, instanceId: id }));
+    return () => {
+      dispatch((0, import_summon.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
+var import_react3 = require("react");
+var import_summon3 = require("@ai-matrx/summon");
+var import_react4 = require("@ai-matrx/summon/react");
+
+// src/url/door.ts
+var import_summon2 = require("@ai-matrx/summon");
+function openRegisteredOverlay(dispatch, overlayId, instanceId = import_summon2.DEFAULT_INSTANCE_ID, data) {
+  const defaults = (0, import_summon2.getOverlayMeta)(overlayId)?.defaults;
+  dispatch(
+    import_summon2.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 (0, import_summon2.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 = (0, import_summon2.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 ?? import_summon2.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) => !(0, import_summon2.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 (!(0, import_summon2.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 ?? import_summon2.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 = (0, import_react4.useSummonPorts)();
+  const dispatch = (0, import_react4.useSummonDispatch)();
+  const entries = (0, import_react4.useSummonSelector)(import_summon3.selectUrlSyncEntries);
+  const isHydrated = (0, import_react4.useSummonSelector)(import_summon3.selectIsUrlHydrated);
+  const router = ports.router;
+  const search = (0, import_react3.useSyncExternalStore)(router.subscribe ?? noopSubscribe, router.search, () => "");
+  const initialLoadDone = (0, import_react3.useRef)(false);
+  const unresolved = (0, import_react3.useRef)(/* @__PURE__ */ new Map());
+  const announced = (0, import_react3.useRef)(/* @__PURE__ */ new Set());
+  const [noticeDue, setNoticeDue] = (0, import_react3.useState)(false);
+  const [asyncTick, setAsyncTick] = (0, import_react3.useState)(0);
+  const deadline = noticeDeadlineMs ?? import_summon3.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 = (0, import_react3.useRef)(announce);
+  announceRef.current = announce;
+  (0, import_react3.useEffect)(() => {
+    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 (!(0, import_summon3.getOverlayMetaByLinkKey)(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((0, import_summon3.setHydrated)());
+  }, [dispatch, managedKeys, router, ports]);
+  (0, import_react3.useEffect)(() => {
+    if (!isHydrated || unresolved.current.size === 0) return void 0;
+    const timer = setTimeout(() => setNoticeDue(true), deadline);
+    return () => clearTimeout(timer);
+  }, [isHydrated, deadline]);
+  (0, import_react3.useEffect)(() => {
+    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;
+}
+//# sourceMappingURL=url.cjs.map