@ai-matrx/summon 0.0.0 → 0.1.1

package/dist/persistence.cjs

@@ -0,0 +1,1073 @@
+"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/persistence.ts
+var persistence_exports = {};
+__export(persistence_exports, {
+  DEFAULT_IDB_READ_BUDGET_MS: () => DEFAULT_IDB_READ_BUDGET_MS,
+  DEFAULT_SAVE_DEBOUNCE_MS: () => DEFAULT_SAVE_DEBOUNCE_MS,
+  DEFAULT_WINDOW_DATA_BYTES: () => DEFAULT_WINDOW_DATA_BYTES,
+  LOAD_TIMEOUT_ERROR: () => LOAD_TIMEOUT_ERROR,
+  MAX_PERSISTED_WINDOW_SESSIONS: () => MAX_PERSISTED_WINDOW_SESSIONS,
+  MAX_WINDOW_WORKSPACE_BYTES: () => MAX_WINDOW_WORKSPACE_BYTES,
+  MAX_WORKSPACES_PER_IDENTITY: () => MAX_WORKSPACES_PER_IDENTITY,
+  OverlayPersistence: () => OverlayPersistence,
+  PERSON_WORKSPACE_KEY: () => PERSON_WORKSPACE_KEY,
+  PersistenceLoadTimeoutError: () => PersistenceLoadTimeoutError,
+  PersistenceVersionConflictError: () => PersistenceVersionConflictError,
+  STATE_KEY_PREFIX: () => STATE_KEY_PREFIX,
+  VERSION_CONFLICT_ERROR: () => VERSION_CONFLICT_ERROR,
+  WINDOW_WORKSPACE_SCHEMA_VERSION: () => WINDOW_WORKSPACE_SCHEMA_VERSION,
+  WORKSPACE_LEASE_MS: () => WORKSPACE_LEASE_MS,
+  createIndexedDbBackend: () => createIndexedDbBackend,
+  createLocalPersistence: () => createLocalPersistence,
+  createMemoryBackend: () => createMemoryBackend,
+  createOverlayPersistenceController: () => createOverlayPersistenceController,
+  hydrateWindowWorkspace: () => hydrateWindowWorkspace,
+  identityScopedKey: () => identityScopedKey,
+  isLoadTimeout: () => isLoadTimeout,
+  isLocalPersistence: () => isLocalPersistence,
+  isVersionConflict: () => isVersionConflict,
+  persistsComponentState: () => persistsComponentState,
+  preservationFor: () => preservationFor,
+  readSession: () => readSession,
+  sanitizeJsonRecord: () => sanitizeJsonRecord,
+  serializeWindowWorkspace: () => serializeWindowWorkspace,
+  stateKey: () => stateKey,
+  tabWorkspaceKey: () => tabWorkspaceKey,
+  useOverlayPersistence: () => useOverlayPersistence
+});
+module.exports = __toCommonJS(persistence_exports);
+
+// src/persistence/backend.ts
+function createMemoryBackend() {
+  const data = /* @__PURE__ */ new Map();
+  return {
+    data,
+    get: async (key) => data.has(key) ? structuredClone(data.get(key)) : void 0,
+    set: async (key, value) => {
+      data.set(key, structuredClone(value));
+    },
+    delete: async (key) => {
+      data.delete(key);
+    },
+    keys: async (prefix) => [...data.keys()].filter((key) => key.startsWith(prefix))
+  };
+}
+function request(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("IndexedDB request failed"));
+  });
+}
+function createIndexedDbBackend(dbName = "ai-matrx-overlays", storeName = "kv") {
+  let opening = null;
+  const db = () => {
+    if (opening) return opening;
+    opening = new Promise((resolve, reject) => {
+      if (typeof indexedDB === "undefined") {
+        reject(new Error("IndexedDB is unavailable"));
+        return;
+      }
+      const req = indexedDB.open(dbName, 1);
+      req.onupgradeneeded = () => {
+        if (!req.result.objectStoreNames.contains(storeName)) req.result.createObjectStore(storeName);
+      };
+      req.onsuccess = () => {
+        const conn = req.result;
+        conn.onversionchange = () => {
+          conn.close();
+          opening = null;
+        };
+        resolve(conn);
+      };
+      req.onerror = () => reject(req.error ?? new Error("IndexedDB open failed"));
+      req.onblocked = () => reject(new Error("IndexedDB open blocked"));
+    }).catch((error) => {
+      opening = null;
+      throw error;
+    });
+    return opening;
+  };
+  const run = async (mode, body) => {
+    const conn = await db();
+    const tx = conn.transaction(storeName, mode);
+    const done = mode === "readwrite" ? new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error ?? new Error("IndexedDB transaction failed"));
+      tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+    }) : Promise.resolve();
+    const result = await request(body(tx.objectStore(storeName)));
+    await done;
+    return result;
+  };
+  return {
+    get: (key) => run("readonly", (store) => store.get(key)),
+    set: async (key, value) => {
+      await run("readwrite", (store) => store.put(value, key));
+    },
+    delete: async (key) => {
+      await run("readwrite", (store) => store.delete(key));
+    },
+    keys: async (prefix) => {
+      const range = IDBKeyRange.bound(prefix, `${prefix}\uFFFF`);
+      const keys = await run("readonly", (store) => store.getAllKeys(range));
+      return keys.filter((key) => typeof key === "string");
+    }
+  };
+}
+
+// src/persistence/errors.ts
+var VERSION_CONFLICT_ERROR = "OverlayPersistenceVersionConflict";
+var LOAD_TIMEOUT_ERROR = "OverlayPersistenceLoadTimeout";
+var PersistenceVersionConflictError = class extends Error {
+  key;
+  expectedVersion;
+  currentVersion;
+  constructor(key, expectedVersion, currentVersion) {
+    super(`[overlays/persistence] "${key}" is at version ${currentVersion}, not the expected ${expectedVersion}`);
+    this.name = VERSION_CONFLICT_ERROR;
+    this.key = key;
+    this.expectedVersion = expectedVersion;
+    this.currentVersion = currentVersion;
+  }
+};
+function isVersionConflict(error) {
+  return error instanceof Error && error.name === VERSION_CONFLICT_ERROR;
+}
+var PersistenceLoadTimeoutError = class extends Error {
+  key;
+  pending;
+  constructor(key, budgetMs, pending) {
+    super(`[overlays/persistence] "${key}" did not load within ${budgetMs}ms`);
+    this.name = LOAD_TIMEOUT_ERROR;
+    this.key = key;
+    this.pending = pending;
+  }
+};
+function isLoadTimeout(error) {
+  return error instanceof Error && error.name === LOAD_TIMEOUT_ERROR;
+}
+
+// src/persistence/keys.ts
+var PERSON_WORKSPACE_KEY = "workspace";
+var tabWorkspaceKey = (workspaceId) => `workspace:${workspaceId}`;
+var STATE_KEY_PREFIX = "state:";
+var stateKey = (instanceKey) => `${STATE_KEY_PREFIX}${instanceKey}`;
+var identityScopedKey = (identityKey, key) => `${identityKey}/${key}`;
+
+// src/persistence/localStore.ts
+var DEFAULT_IDB_READ_BUDGET_MS = 750;
+var WORKSPACE_LEASE_MS = 24 * 60 * 60 * 1e3;
+var MAX_WORKSPACES_PER_IDENTITY = 5;
+var INDEX_REFRESH_MS = 60 * 1e3;
+var RECORD_VERSION = 1;
+function isStoredRecord(value) {
+  return typeof value === "object" && value !== null && value.v === RECORD_VERSION && typeof value.version === "number" && "value" in value;
+}
+function randomId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  return `tab-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+var browserStorage = (pick) => {
+  try {
+    return typeof window === "undefined" ? null : window[pick];
+  } catch {
+    return null;
+  }
+};
+var defaultIsReload = () => {
+  try {
+    const entry = performance.getEntriesByType("navigation")[0];
+    return entry?.type === "reload";
+  } catch {
+    return false;
+  }
+};
+function isLocalPersistence(port) {
+  return Boolean(port && "workspaces" in port && typeof port.workspaces === "object");
+}
+function createLocalPersistence(options = {}) {
+  const ns = options.namespace ?? "ai-matrx.overlays";
+  const storage = options.storage === void 0 ? browserStorage("localStorage") : options.storage;
+  const session = options.session === void 0 ? browserStorage("sessionStorage") : options.session;
+  const locks = options.locks === void 0 ? typeof navigator !== "undefined" && navigator.locks ? navigator.locks : null : options.locks;
+  const backend = options.backend ?? (typeof indexedDB !== "undefined" ? createIndexedDbBackend(ns) : createMemoryBackend());
+  const budgetMs = options.idbReadBudgetMs ?? DEFAULT_IDB_READ_BUDGET_MS;
+  const now = options.now ?? Date.now;
+  const isReload = options.isReload ?? defaultIsReload;
+  const runtimeId = randomId();
+  const fallbackWorkspaceId = `fallback-${runtimeId}`;
+  const queues = /* @__PURE__ */ new Map();
+  let leased = null;
+  const mirrorKey = (key) => `${ns}:${key}`;
+  const leaseKey = (workspaceId) => `${ns}:lease:${workspaceId}`;
+  const indexPrefix = (identityKey) => `${ns}:index:${identityKey}:`;
+  const readJson = (key) => {
+    if (!storage) return null;
+    try {
+      const raw = storage.getItem(key);
+      return raw === null ? null : JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  };
+  const writeJson = (key, value) => {
+    if (!storage) return false;
+    try {
+      storage.setItem(key, JSON.stringify(value));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const removeKey = (key) => {
+    try {
+      storage?.removeItem(key);
+    } catch {
+    }
+  };
+  const storageKeys = (prefix) => {
+    if (!storage) return [];
+    const out = [];
+    try {
+      for (let i = 0; i < storage.length; i += 1) {
+        const key = storage.key(i);
+        if (key?.startsWith(prefix)) out.push(key);
+      }
+    } catch {
+    }
+    return out;
+  };
+  const readMirror = (key) => {
+    const raw = readJson(mirrorKey(key));
+    return isStoredRecord(raw) ? raw : null;
+  };
+  const enqueue = (key, operation) => {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const next = previous.catch(() => void 0).then(() => locks ? locks.request(`${ns}:${key}`, operation) : operation());
+    queues.set(key, next);
+    void next.then(
+      () => {
+        if (queues.get(key) === next) queues.delete(key);
+      },
+      () => {
+        if (queues.get(key) === next) queues.delete(key);
+      }
+    );
+    return next;
+  };
+  const readWarm = async (key) => {
+    const raw = await backend.get(key);
+    return isStoredRecord(raw) ? { value: raw.value, version: raw.version } : null;
+  };
+  const leaseBody = (workspaceId) => {
+    const raw = readJson(leaseKey(workspaceId));
+    return typeof raw === "object" && raw !== null ? raw : null;
+  };
+  const hasLiveLease = (workspaceId, at) => {
+    const body = leaseBody(workspaceId);
+    return typeof body?.expiresAt === "number" && body.expiresAt > at;
+  };
+  const claimLease = (workspaceId) => {
+    if (leased && leased !== workspaceId && leaseBody(leased)?.runtimeId === runtimeId) removeKey(leaseKey(leased));
+    leased = workspaceId;
+    writeJson(leaseKey(workspaceId), { runtimeId, expiresAt: now() + WORKSPACE_LEASE_MS });
+  };
+  const workspaces = {
+    currentId() {
+      if (!session) {
+        claimLease(fallbackWorkspaceId);
+        return fallbackWorkspaceId;
+      }
+      try {
+        const sessionKey = `${ns}:workspace-id`;
+        const existing = session.getItem(sessionKey);
+        const body = existing ? leaseBody(existing) : null;
+        const claimedElsewhere = Boolean(
+          existing && !isReload() && body?.runtimeId !== runtimeId && typeof body?.expiresAt === "number" && body.expiresAt > now()
+        );
+        const workspaceId = existing && !claimedElsewhere ? existing : randomId();
+        session.setItem(sessionKey, workspaceId);
+        claimLease(workspaceId);
+        return workspaceId;
+      } catch {
+        claimLease(fallbackWorkspaceId);
+        return fallbackWorkspaceId;
+      }
+    },
+    renew(workspaceId) {
+      claimLease(workspaceId);
+    },
+    release(workspaceId) {
+      if (leaseBody(workspaceId)?.runtimeId === runtimeId) removeKey(leaseKey(workspaceId));
+      if (leased === workspaceId) leased = null;
+    },
+    index(identityKey, workspaceId) {
+      const at = now();
+      const prefix = indexPrefix(identityKey);
+      const rows = storageKeys(prefix).map((key) => readJson(key)).filter(
+        (row) => typeof row === "object" && row !== null && typeof row.workspaceId === "string" && typeof row.lastUsedAt === "number"
+      );
+      const current = rows.find((row) => row.workspaceId === workspaceId);
+      if (current && rows.length <= MAX_WORKSPACES_PER_IDENTITY && at - current.lastUsedAt < INDEX_REFRESH_MS) return;
+      const entry = { workspaceId, lastUsedAt: current && at - current.lastUsedAt < INDEX_REFRESH_MS ? current.lastUsedAt : at };
+      writeJson(`${prefix}${workspaceId}`, entry);
+      const ordered = [...rows.filter((row) => row.workspaceId !== workspaceId), entry].sort((a, b) => b.lastUsedAt - a.lastUsedAt);
+      for (const stale of ordered.slice(MAX_WORKSPACES_PER_IDENTITY)) {
+        if (hasLiveLease(stale.workspaceId, at)) continue;
+        const key = identityScopedKey(identityKey, tabWorkspaceKey(stale.workspaceId));
+        void enqueue(key, async () => {
+          if (hasLiveLease(stale.workspaceId, now())) return;
+          removeKey(mirrorKey(key));
+          removeKey(leaseKey(stale.workspaceId));
+          removeKey(`${prefix}${stale.workspaceId}`);
+          await backend.delete(key);
+        }).catch(() => void 0);
+      }
+    }
+  };
+  return {
+    perPerson: false,
+    workspaces,
+    async load(key) {
+      const mirror = readMirror(key);
+      if (mirror) return { value: mirror.value, version: mirror.version };
+      const warm = readWarm(key).catch(() => null);
+      let timer;
+      const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), budgetMs);
+      });
+      const first = await Promise.race([warm, timeout]);
+      if (timer !== void 0) clearTimeout(timer);
+      if (first === "timeout") throw new PersistenceLoadTimeoutError(key, budgetMs, warm);
+      return first;
+    },
+    async save(key, value, saveOptions) {
+      const current = readMirror(key)?.version ?? 0;
+      const expected = saveOptions?.expectedVersion;
+      if (expected !== void 0 && expected !== current) throw new PersistenceVersionConflictError(key, expected, current);
+      const record = { v: RECORD_VERSION, version: current + 1, value };
+      if (!writeJson(mirrorKey(key), record)) removeKey(mirrorKey(key));
+      await enqueue(key, () => backend.set(key, record));
+      return { version: record.version };
+    },
+    async remove(key) {
+      removeKey(mirrorKey(key));
+      await enqueue(key, () => backend.delete(key));
+    },
+    async list(prefix) {
+      const fromMirror = storageKeys(mirrorKey(prefix)).map((key) => key.slice(ns.length + 1));
+      let fromWarm = [];
+      try {
+        fromWarm = await backend.keys(prefix);
+      } catch {
+      }
+      return [.../* @__PURE__ */ new Set([...fromMirror, ...fromWarm])].sort();
+    },
+    async purgeIdentity(identityKey) {
+      const prefix = identityScopedKey(identityKey, "");
+      for (const key of storageKeys(mirrorKey(prefix))) removeKey(key);
+      for (const key of storageKeys(indexPrefix(identityKey))) removeKey(key);
+      let warmKeys = [];
+      try {
+        warmKeys = await backend.keys(prefix);
+      } catch {
+        return;
+      }
+      await Promise.all(warmKeys.map((key) => enqueue(key, () => backend.delete(key))));
+    },
+    async idle() {
+      await Promise.all([...queues.values()].map((q) => q.catch(() => void 0)));
+    }
+  };
+}
+
+// src/persistence/workspace.ts
+var import_summon = require("@ai-matrx/summon");
+var WINDOW_WORKSPACE_SCHEMA_VERSION = 1;
+var DEFAULT_WINDOW_DATA_BYTES = 32 * 1024;
+var MAX_WINDOW_WORKSPACE_BYTES = 256 * 1024;
+var MAX_PERSISTED_WINDOW_SESSIONS = 64;
+var MAX_ID_LENGTH = 160;
+var MAX_LABEL_LENGTH = 512;
+function preservationFor(overlayId) {
+  const meta = (0, import_summon.getOverlayMeta)(overlayId);
+  const preservation = meta?.window?.preservation;
+  if (!meta || !preservation || meta.window?.ephemeral) return null;
+  return { meta, preservation };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+function utf8Bytes(value) {
+  let bytes = 0;
+  for (const ch of value) {
+    const cp = ch.codePointAt(0) ?? 0;
+    bytes += cp <= 127 ? 1 : cp <= 2047 ? 2 : cp <= 65535 ? 3 : 4;
+  }
+  return bytes;
+}
+var isWindowState = (value) => value === "windowed" || value === "maximized" || value === "minimized";
+function readRect(value) {
+  if (!isRecord(value)) return null;
+  const { x, y, width, height } = value;
+  if (!isFiniteNumber(x) || !isFiniteNumber(y) || !isFiniteNumber(width) || !isFiniteNumber(height) || width <= 0 || height <= 0) return null;
+  return { x, y, width, height };
+}
+function sanitizeJsonRecord(value, allowedKeys) {
+  if (!isRecord(value) || allowedKeys && allowedKeys.length === 0) return { data: {}, droppedUnsupported: false, bytes: 2 };
+  const ancestors = /* @__PURE__ */ new WeakSet();
+  let droppedUnsupported = false;
+  const DROPPED = /* @__PURE__ */ Symbol("dropped");
+  const copy = (item) => {
+    if (item === void 0 || typeof item === "function" || typeof item === "symbol") {
+      droppedUnsupported = true;
+      return DROPPED;
+    }
+    if (typeof item === "bigint") {
+      droppedUnsupported = true;
+      return item.toString();
+    }
+    if (typeof item === "number" && !Number.isFinite(item)) {
+      droppedUnsupported = true;
+      return null;
+    }
+    if (item === null || typeof item !== "object") return item;
+    if (item instanceof Date) return item.toJSON();
+    if (ancestors.has(item)) {
+      droppedUnsupported = true;
+      return DROPPED;
+    }
+    ancestors.add(item);
+    let result;
+    if (Array.isArray(item)) {
+      result = item.map((child) => {
+        const copied = copy(child);
+        return copied === DROPPED ? null : copied;
+      });
+    } else if (Object.getPrototypeOf(item) === Object.prototype || Object.getPrototypeOf(item) === null) {
+      result = Object.fromEntries(
+        Object.entries(item).flatMap(([key, child]) => {
+          const copied = copy(child);
+          return copied === DROPPED ? [] : [[key, copied]];
+        })
+      );
+    } else {
+      droppedUnsupported = true;
+      result = DROPPED;
+    }
+    ancestors.delete(item);
+    return result;
+  };
+  try {
+    const allowed = allowedKeys ? new Set(allowedKeys) : null;
+    const selected = Object.fromEntries(Object.entries(value).filter(([key]) => !allowed || allowed.has(key)));
+    ancestors.add(value);
+    const copied = copy(selected);
+    ancestors.delete(value);
+    const json = JSON.stringify(copied === DROPPED ? {} : copied) || "{}";
+    const parsed = JSON.parse(json);
+    return { data: isRecord(parsed) ? parsed : {}, droppedUnsupported, bytes: utf8Bytes(json) };
+  } catch {
+    return { data: {}, droppedUnsupported: true, bytes: 2 };
+  }
+}
+function invalidAllowedDataKey(data, preservation) {
+  const domains = preservation.allowedDataValues;
+  if (!domains) return null;
+  return Object.entries(domains).find(([key, allowed]) => !allowed.includes(data[key]))?.[0] ?? null;
+}
+function sessionFromWindow(entry, savedAt, diagnostics) {
+  const persistence = entry.persistence;
+  if (!persistence || persistence.closing) return null;
+  const preserved = preservationFor(persistence.overlayId);
+  if (!preserved) return null;
+  const sessionKey = (0, import_summon.windowSessionKey)(persistence.overlayId, persistence.instanceId);
+  if (persistence.instanceId.length > MAX_ID_LENGTH || entry.id.length > MAX_ID_LENGTH || entry.title.length > MAX_LABEL_LENGTH) {
+    diagnostics.push({ level: "error", code: "invalid-session", sessionKey, message: `Skipped ${sessionKey}: identity or label metadata is oversized.` });
+    return null;
+  }
+  const sanitized = sanitizeJsonRecord(persistence.data, preserved.preservation.dataKeys);
+  if (sanitized.droppedUnsupported) {
+    diagnostics.push({ level: "warning", code: "unsupported-data", sessionKey, message: `Dropped non-JSON window data for ${sessionKey}.` });
+  }
+  const maxBytes = preserved.preservation.maxDataBytes ?? DEFAULT_WINDOW_DATA_BYTES;
+  const data = sanitized.bytes <= maxBytes ? sanitized.data : {};
+  if (sanitized.bytes > maxBytes) {
+    diagnostics.push({
+      level: "error",
+      code: "window-data-too-large",
+      sessionKey,
+      message: `Discarded ${sanitized.bytes} bytes of window data for ${sessionKey}; limit is ${maxBytes}.`
+    });
+  }
+  const invalidKey = invalidAllowedDataKey(sanitized.data, preserved.preservation);
+  if (invalidKey) {
+    diagnostics.push({ level: "error", code: "invalid-session", sessionKey, message: `Skipped ${sessionKey}: ${invalidKey} is outside its allowed domain.` });
+    return null;
+  }
+  return {
+    schemaVersion: import_summon.WINDOW_SESSION_SCHEMA_VERSION,
+    sessionKey,
+    overlayId: persistence.overlayId,
+    instanceId: persistence.instanceId,
+    windowId: entry.id,
+    title: entry.title,
+    state: entry.state,
+    windowedRect: entry.state === "minimized" ? entry.preMinimizedRect ?? entry.windowed : entry.windowed,
+    traySlot: entry.state === "minimized" ? entry.traySlot : null,
+    zIndex: entry.zIndex,
+    sidebarOpen: persistence.sidebarOpen,
+    sidebarSize: persistence.sidebarSize,
+    data,
+    savedAt
+  };
+}
+function readSession(value, diagnostics) {
+  if (!isRecord(value)) return null;
+  const { overlayId, instanceId } = value;
+  const rect = readRect(value.windowedRect);
+  if (value.schemaVersion !== import_summon.WINDOW_SESSION_SCHEMA_VERSION || typeof overlayId !== "string" || typeof instanceId !== "string" || instanceId.length === 0 || !rect || !isWindowState(value.state)) {
+    diagnostics.push({ level: "error", code: "invalid-session", message: "Ignored an invalid window preservation record." });
+    return null;
+  }
+  const sessionKey = (0, import_summon.windowSessionKey)(overlayId, instanceId);
+  const meta = (0, import_summon.getOverlayMeta)(overlayId);
+  if (!meta) {
+    diagnostics.push({ level: "error", code: "unknown-overlay", sessionKey, message: `Ignored unknown overlay ${overlayId}.` });
+    return null;
+  }
+  const preserved = preservationFor(overlayId);
+  if (!preserved) {
+    diagnostics.push({ level: "warning", code: "preservation-disabled", sessionKey, message: `Ignored ${overlayId}: its definition does not preserve windows.` });
+    return null;
+  }
+  if (meta.instance !== "multi" && instanceId !== "default" || instanceId.length > MAX_ID_LENGTH || typeof value.windowId === "string" && value.windowId.length > MAX_ID_LENGTH || typeof value.title === "string" && value.title.length > MAX_LABEL_LENGTH) {
+    diagnostics.push({ level: "error", code: "invalid-session", sessionKey, message: `Ignored invalid instance or oversized metadata for ${overlayId}.` });
+    return null;
+  }
+  const sanitized = sanitizeJsonRecord(value.data, preserved.preservation.dataKeys);
+  const missing = preserved.preservation.requiredDataKeys?.find((key) => {
+    const v = sanitized.data[key];
+    return v === void 0 || v === null || v === "";
+  });
+  if (missing) {
+    diagnostics.push({ level: "warning", code: "invalid-session", sessionKey, message: `Ignored ${overlayId}: required key ${missing} was empty.` });
+    return null;
+  }
+  const invalidKey = invalidAllowedDataKey(sanitized.data, preserved.preservation);
+  if (invalidKey) {
+    diagnostics.push({ level: "error", code: "invalid-session", sessionKey, message: `Ignored ${overlayId}: ${invalidKey} is outside its allowed domain.` });
+    return null;
+  }
+  const maxBytes = preserved.preservation.maxDataBytes ?? DEFAULT_WINDOW_DATA_BYTES;
+  if (sanitized.bytes > maxBytes) {
+    diagnostics.push({
+      level: "error",
+      code: "window-data-too-large",
+      sessionKey,
+      message: `Discarded ${sanitized.bytes} bytes of restored window data for ${overlayId}; limit is ${maxBytes}.`
+    });
+  }
+  return {
+    schemaVersion: import_summon.WINDOW_SESSION_SCHEMA_VERSION,
+    sessionKey,
+    overlayId,
+    instanceId,
+    windowId: typeof value.windowId === "string" ? value.windowId : (0, import_summon.defaultWindowIdFor)(meta),
+    title: typeof value.title === "string" ? value.title : meta.label,
+    state: value.state,
+    windowedRect: rect,
+    traySlot: Number.isInteger(value.traySlot) && Number(value.traySlot) >= 0 ? Number(value.traySlot) : null,
+    zIndex: isFiniteNumber(value.zIndex) ? value.zIndex : 1e3,
+    sidebarOpen: value.sidebarOpen !== false,
+    sidebarSize: isFiniteNumber(value.sidebarSize) && value.sidebarSize > 0 ? value.sidebarSize : null,
+    data: sanitized.bytes <= maxBytes ? sanitized.data : {},
+    savedAt: isFiniteNumber(value.savedAt) ? value.savedAt : 0
+  };
+}
+function serializeWindowWorkspace(state, workspaceId, savedAt = Date.now()) {
+  const diagnostics = [];
+  const live = Object.values(state.windows).map((entry) => sessionFromWindow(entry, savedAt, diagnostics)).filter((s) => s !== null);
+  const liveKeys = new Set(live.map((s) => s.sessionKey));
+  const pending = Object.values(state.pendingRestores).filter((s) => !liveKeys.has(s.sessionKey)).map((s) => readSession({ ...s, savedAt }, diagnostics)).filter((s) => s !== null);
+  const all = [...live, ...pending].sort((a, b) => b.zIndex - a.zIndex || a.sessionKey.localeCompare(b.sessionKey));
+  const sessions = all.slice(0, MAX_PERSISTED_WINDOW_SESSIONS).sort((a, b) => a.zIndex - b.zIndex || a.sessionKey.localeCompare(b.sessionKey));
+  if (all.length > sessions.length) {
+    diagnostics.push({
+      level: "error",
+      code: "workspace-too-large",
+      message: `Window workspace exceeded ${MAX_PERSISTED_WINDOW_SESSIONS} sessions; later z-order entries were not saved.`
+    });
+  }
+  const workspace = { schemaVersion: WINDOW_WORKSPACE_SCHEMA_VERSION, workspaceId, savedAt, sessions };
+  const bytes = utf8Bytes(JSON.stringify(workspace));
+  if (bytes > MAX_WINDOW_WORKSPACE_BYTES) {
+    for (const s of sessions) s.data = {};
+    diagnostics.push({
+      level: "error",
+      code: "workspace-too-large",
+      message: `Window workspace reached ${bytes} bytes; window data was discarded while geometry was kept.`
+    });
+    while (sessions.length > 0 && utf8Bytes(JSON.stringify(workspace)) > MAX_WINDOW_WORKSPACE_BYTES) sessions.pop();
+  }
+  return { workspace, diagnostics };
+}
+function fallbackRect(viewport) {
+  return (0, import_summon.centerRectInViewport)({ x: 0, y: 0, width: Math.min(720, viewport.width), height: Math.min(480, viewport.height) }, viewport);
+}
+function hydrateWindowWorkspace(raw, viewport, expectedWorkspaceId) {
+  const diagnostics = [];
+  if (!isRecord(raw) || raw.schemaVersion !== WINDOW_WORKSPACE_SCHEMA_VERSION || !Array.isArray(raw.sessions) || typeof raw.workspaceId !== "string" || expectedWorkspaceId !== void 0 && raw.workspaceId !== expectedWorkspaceId) {
+    if (raw != null) diagnostics.push({ level: "error", code: "invalid-workspace", message: "Ignored an invalid or unsupported window workspace." });
+    return { sessions: [], diagnostics };
+  }
+  let workspaceBytes;
+  try {
+    workspaceBytes = utf8Bytes(JSON.stringify(raw));
+  } catch {
+    diagnostics.push({ level: "error", code: "invalid-workspace", message: "Ignored a window workspace that could not be serialized." });
+    return { sessions: [], diagnostics };
+  }
+  if (workspaceBytes > MAX_WINDOW_WORKSPACE_BYTES) {
+    diagnostics.push({
+      level: "error",
+      code: "workspace-too-large",
+      message: `Ignored a ${workspaceBytes}-byte window workspace above the ${MAX_WINDOW_WORKSPACE_BYTES}-byte limit.`
+    });
+    return { sessions: [], diagnostics };
+  }
+  if (raw.sessions.length > MAX_PERSISTED_WINDOW_SESSIONS) {
+    diagnostics.push({
+      level: "error",
+      code: "invalid-workspace",
+      message: `Window workspace exceeded ${MAX_PERSISTED_WINDOW_SESSIONS} sessions; extras were ignored.`
+    });
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const candidate of raw.sessions.slice(0, MAX_PERSISTED_WINDOW_SESSIONS)) {
+    const session = readSession(candidate, diagnostics);
+    if (!session) continue;
+    const existing = byKey.get(session.sessionKey);
+    if (!existing || existing.savedAt < session.savedAt || existing.savedAt === session.savedAt && JSON.stringify(existing) < JSON.stringify(session)) {
+      byKey.set(session.sessionKey, session);
+    }
+  }
+  const ordered = [...byKey.values()].sort((a, b) => a.zIndex - b.zIndex || a.sessionKey.localeCompare(b.sessionKey));
+  const minimized = ordered.filter((s) => s.state === "minimized").sort((a, b) => (a.traySlot ?? Number.MAX_SAFE_INTEGER) - (b.traySlot ?? Number.MAX_SAFE_INTEGER) || a.sessionKey.localeCompare(b.sessionKey));
+  const slotOf = new Map(minimized.map((s, i) => [s.sessionKey, i]));
+  const sessions = ordered.map((session, index) => {
+    const restoreDefaults = (0, import_summon.getOverlayMeta)(session.overlayId)?.window?.restoreDefaults;
+    const slot = slotOf.get(session.sessionKey) ?? null;
+    const renderRect = session.state === "minimized" && slot !== null ? (0, import_summon.traySlotRect)(slot, viewport.width, viewport.height, minimized.length) : session.state === "windowed" || session.state === "maximized" ? (0, import_summon.clampRectToViewport)(session.windowedRect, viewport) : fallbackRect(viewport);
+    return {
+      ...session,
+      traySlot: slot,
+      zIndex: 1e3 + index,
+      data: restoreDefaults ? { ...restoreDefaults, ...session.data } : session.data,
+      renderRect
+    };
+  });
+  return { sessions, diagnostics };
+}
+
+// src/persistence/controller.ts
+var import_summon2 = require("@ai-matrx/summon");
+var DEFAULT_SAVE_DEBOUNCE_MS = 250;
+var STALE_SWEEP_MS = 30 * 60 * 1e3;
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function openRegisteredOverlay(dispatch, overlayId, instanceId, data) {
+  const defaults = (0, import_summon2.getOverlayMeta)(overlayId)?.defaults;
+  dispatch(import_summon2.overlaysRawActions.openOverlay({ overlayId, instanceId, data, ...isRecord2(defaults) ? { defaults } : {} }));
+}
+function persistsComponentState(overlayId) {
+  const meta = (0, import_summon2.getOverlayMeta)(overlayId);
+  return Boolean(meta && (meta.keepAlive === "restore" || preservationFor(overlayId)));
+}
+function createOverlayPersistenceController(store, ports, options = {}) {
+  const port = ports.persistence;
+  const debounceMs = options.saveDebounceMs ?? DEFAULT_SAVE_DEBOUNCE_MS;
+  const seedFromPerson = options.seedFromPerson ?? true;
+  const local = isLocalPersistence(port) ? port : null;
+  const scope = options.scope ?? (port?.perPerson ? "person" : local ? "tab" : "person");
+  let identityKey = null;
+  let generation = 0;
+  let writeSafe = false;
+  let hydrated = false;
+  let workspaceId = null;
+  let saveTimer = null;
+  let lastWorkspaceFp = null;
+  let lastSavedAt = 0;
+  const versions = /* @__PURE__ */ new Map();
+  const stateFps = /* @__PURE__ */ new Map();
+  const chains = /* @__PURE__ */ new Map();
+  const closedExact = /* @__PURE__ */ new Set();
+  const closedOverlay = /* @__PURE__ */ new Set();
+  let closedAll = false;
+  const cleanups = [];
+  const setHydrated = (next) => {
+    if (hydrated === next) return;
+    hydrated = next;
+    options.onHydratedChange?.(next);
+  };
+  const report = (diagnostics) => {
+    for (const d of diagnostics) {
+      ports.errors.capture(new Error(`[overlays/persistence:${d.code}] ${d.message}`), {
+        source: "overlay-persistence",
+        level: d.level,
+        code: d.code,
+        ...d.sessionKey ? { sessionKey: d.sessionKey } : {}
+      });
+    }
+  };
+  const fail = (where) => (error) => ports.errors.capture(error, { source: "overlay-persistence", where });
+  const scoped = (key) => port?.perPerson || identityKey === null ? key : identityScopedKey(identityKey, key);
+  const workspaceKey = () => scope === "tab" && workspaceId ? tabWorkspaceKey(workspaceId) : PERSON_WORKSPACE_KEY;
+  const put = (key, value) => {
+    if (!port) return;
+    const gen = generation;
+    const run = async () => {
+      if (gen !== generation) return;
+      const expected = versions.get(key);
+      try {
+        const saved = await port.save(key, value, expected === void 0 ? void 0 : { expectedVersion: expected });
+        versions.set(key, saved.version);
+      } catch (error) {
+        if (!isVersionConflict(error) || gen !== generation) throw error;
+        const current = await port.load(key).catch(() => null);
+        const saved = await port.save(key, value, { expectedVersion: current?.version ?? 0 });
+        versions.set(key, saved.version);
+      }
+    };
+    const next = (chains.get(key) ?? Promise.resolve()).then(run).catch(fail(`save ${key}`));
+    chains.set(key, next);
+  };
+  const drop = (key) => {
+    if (!port) return;
+    const next = (chains.get(key) ?? Promise.resolve()).then(() => port.remove(key)).then(() => void versions.delete(key)).catch(fail(`remove ${key}`));
+    chains.set(key, next);
+  };
+  const saveStates = (state) => {
+    const present = /* @__PURE__ */ new Set();
+    for (const [key, entry] of Object.entries(state.overlayState.entries)) {
+      const parsed = (0, import_summon2.parseInstanceKey)(key);
+      if (!parsed || !persistsComponentState(parsed.overlayId)) continue;
+      const sanitized = sanitizeJsonRecord(entry.values, null);
+      if (sanitized.bytes > DEFAULT_WINDOW_DATA_BYTES) {
+        report([
+          {
+            level: "error",
+            code: "state-too-large",
+            sessionKey: key,
+            message: `Saved component state of ${key} is ${sanitized.bytes} bytes; limit is ${DEFAULT_WINDOW_DATA_BYTES}. Not saved.`
+          }
+        ]);
+        continue;
+      }
+      const storageKey = scoped(stateKey(key));
+      present.add(storageKey);
+      const fp = JSON.stringify(sanitized.data);
+      if (stateFps.get(storageKey) === fp) continue;
+      stateFps.set(storageKey, fp);
+      put(storageKey, sanitized.data);
+    }
+    for (const storageKey of [...stateFps.keys()]) {
+      if (present.has(storageKey)) continue;
+      stateFps.delete(storageKey);
+      drop(storageKey);
+    }
+  };
+  const saveNow = () => {
+    if (saveTimer) {
+      clearTimeout(saveTimer);
+      saveTimer = null;
+    }
+    if (!port || !writeSafe || identityKey === null) return;
+    const state = store.getState();
+    const savedAt = Math.max(Date.now(), lastSavedAt + 1);
+    const { workspace, diagnostics } = serializeWindowWorkspace(state.windowManager, workspaceId ?? PERSON_WORKSPACE_KEY, savedAt);
+    report(diagnostics);
+    const fp = JSON.stringify(workspace.sessions.map((s) => ({ ...s, savedAt: 0 })));
+    if (fp !== lastWorkspaceFp) {
+      lastWorkspaceFp = fp;
+      lastSavedAt = savedAt;
+      put(scoped(workspaceKey()), workspace);
+      if (scope === "tab" && workspaceId) {
+        if (seedFromPerson) put(scoped(PERSON_WORKSPACE_KEY), workspace);
+        local?.workspaces.index(identityKey, workspaceId);
+      }
+    }
+    saveStates(state);
+  };
+  const scheduleSave = () => {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      saveTimer = null;
+      saveNow();
+    }, debounceMs);
+  };
+  const loadValue = async (key) => {
+    if (!port) return null;
+    try {
+      return await port.load(key);
+    } catch (error) {
+      if (isLoadTimeout(error)) return error.pending;
+      throw error;
+    }
+  };
+  const teardown = () => {
+    generation += 1;
+    writeSafe = false;
+    setHydrated(false);
+    if (saveTimer) {
+      clearTimeout(saveTimer);
+      saveTimer = null;
+    }
+    const state = store.getState();
+    const identities = /* @__PURE__ */ new Map();
+    for (const entry of Object.values(state.windowManager.windows)) {
+      if (entry.persistence) {
+        const { overlayId, instanceId } = entry.persistence;
+        identities.set((0, import_summon2.windowSessionKey)(overlayId, instanceId), { overlayId, instanceId });
+      }
+    }
+    for (const session of Object.values(state.windowManager.pendingRestores)) {
+      identities.set(session.sessionKey, { overlayId: session.overlayId, instanceId: session.instanceId });
+    }
+    for (const identity of identities.values()) store.dispatch((0, import_summon2.markWindowClosing)(identity));
+    store.dispatch((0, import_summon2.closeAllOverlays)());
+    store.dispatch((0, import_summon2.clearWindowPersistenceState)());
+    for (const key of Object.keys(store.getState().overlayState.entries)) store.dispatch((0, import_summon2.clearOverlayState)({ key }));
+    closedExact.clear();
+    closedOverlay.clear();
+    closedAll = false;
+    versions.clear();
+    stateFps.clear();
+    lastWorkspaceFp = null;
+  };
+  const liveWindowFor = (windows, overlayId, instanceId) => Object.values(windows).find(
+    (entry) => entry.persistence?.overlayId === overlayId && entry.persistence.instanceId === instanceId && !entry.persistence.closing
+  );
+  const applyGeometry = (entry, session, viewport) => {
+    if (entry.state !== "windowed") store.dispatch((0, import_summon2.restoreWindow)(entry.id));
+    store.dispatch((0, import_summon2.updateWindowRect)({ id: entry.id, rect: session.state === "minimized" ? session.windowedRect : session.renderRect }));
+    if (session.state === "maximized") store.dispatch((0, import_summon2.maximizeWindow)(entry.id));
+    else if (session.state === "minimized") {
+      store.dispatch((0, import_summon2.minimizeWindow)({ id: entry.id, viewportWidth: viewport.width, viewportHeight: viewport.height }));
+    }
+  };
+  const loadIdentity = async (key) => {
+    if (!port) return;
+    const gen = generation;
+    if (scope === "tab" && local) workspaceId ??= local.workspaces.currentId();
+    else workspaceId = null;
+    const ownKey = scoped(workspaceKey());
+    let stored = await loadValue(ownKey);
+    let expectedWorkspaceId = scope === "tab" && workspaceId ? workspaceId : void 0;
+    if (stored) versions.set(ownKey, stored.version);
+    if (!stored && scope === "tab" && seedFromPerson) {
+      const personKey = scoped(PERSON_WORKSPACE_KEY);
+      stored = await loadValue(personKey);
+      if (stored) versions.set(personKey, stored.version);
+      expectedWorkspaceId = void 0;
+    }
+    const stateKeys = port.list ? await port.list(scoped(STATE_KEY_PREFIX)) : null;
+    if (gen !== generation || identityKey !== key) return;
+    const viewport = options.viewport?.() ?? (() => {
+      const { vw, vh } = (0, import_summon2.safeViewportDims)();
+      return { width: vw, height: vh };
+    })();
+    const result = hydrateWindowWorkspace(stored?.value ?? null, viewport, expectedWorkspaceId);
+    report(result.diagnostics);
+    const sessions = result.sessions.filter(
+      (s) => !closedAll && !closedOverlay.has(s.overlayId) && !closedExact.has(s.sessionKey)
+    );
+    const prefix = scoped(STATE_KEY_PREFIX);
+    const candidates = stateKeys ? stateKeys.filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length)) : sessions.map((s) => s.sessionKey);
+    const loadedStates = await Promise.all(
+      candidates.map(async (instance) => [instance, await loadValue(scoped(stateKey(instance))).catch(() => null)])
+    );
+    if (gen !== generation || identityKey !== key) return;
+    const before = store.getState();
+    const restoredKeys = new Set(sessions.map((s) => s.sessionKey));
+    const stateEntries = {};
+    for (const [instance, value] of loadedStates) {
+      const parsed = (0, import_summon2.parseInstanceKey)(instance);
+      if (!parsed || !value || !isRecord2(value.value)) continue;
+      const storageKey = scoped(stateKey(instance));
+      const meta = (0, import_summon2.getOverlayMeta)(parsed.overlayId);
+      if (!meta || !persistsComponentState(parsed.overlayId)) continue;
+      const open = before.overlays.overlays[parsed.overlayId]?.[parsed.instanceId]?.isOpen === true;
+      const wanted = meta.keepAlive === "restore" || restoredKeys.has(instance) || open;
+      if (!wanted) {
+        drop(storageKey);
+        continue;
+      }
+      versions.set(storageKey, value.version);
+      if (before.overlayState.entries[instance]) continue;
+      stateEntries[instance] = { values: value.value };
+      stateFps.set(storageKey, JSON.stringify(value.value));
+    }
+    if (Object.keys(stateEntries).length > 0) store.dispatch((0, import_summon2.hydrateOverlayState)({ entries: stateEntries }));
+    const live = [];
+    const staged = [];
+    for (const session of sessions) {
+      const entry = liveWindowFor(before.windowManager.windows, session.overlayId, session.instanceId);
+      if (entry) live.push([entry, session]);
+      else staged.push(session);
+    }
+    store.dispatch((0, import_summon2.hydrateWindowSessions)({ sessions: staged, viewportWidth: viewport.width, viewportHeight: viewport.height }));
+    for (const [entry, session] of live) applyGeometry(entry, session, viewport);
+    for (const session of staged) {
+      if (before.overlays.overlays[session.overlayId]?.[session.instanceId]?.isOpen) continue;
+      openRegisteredOverlay(store.dispatch, session.overlayId, session.instanceId, session.data);
+    }
+    lastWorkspaceFp = stored && expectedWorkspaceId !== void 0 && isRecord2(stored.value) && Array.isArray(stored.value.sessions) ? JSON.stringify(stored.value.sessions.map((s) => ({ ...s, savedAt: 0 }))) : null;
+    lastSavedAt = stored && isRecord2(stored.value) && typeof stored.value.savedAt === "number" ? stored.value.savedAt : 0;
+    writeSafe = true;
+    setHydrated(true);
+    setTimeout(() => {
+      if (gen !== generation) return;
+      saveNow();
+      closedExact.clear();
+      closedOverlay.clear();
+      closedAll = false;
+    }, 0);
+  };
+  const onIdentity = () => {
+    const current = ports.identity.current();
+    if (!current.ready) {
+      if (identityKey !== null) teardown();
+      identityKey = null;
+      return;
+    }
+    if (current.key === identityKey) return;
+    const changed = identityKey !== null;
+    if (changed) teardown();
+    else generation += 1;
+    identityKey = current.key;
+    writeSafe = false;
+    setHydrated(false);
+    const key = current.key;
+    const wait = changed ? new Promise((resolve) => setTimeout(resolve, 0)) : Promise.resolve();
+    void wait.then(() => loadIdentity(key)).catch((error) => {
+      fail("load")(error);
+      if (identityKey === key) setHydrated(true);
+    });
+  };
+  return {
+    get hydrated() {
+      return hydrated;
+    },
+    flush: saveNow,
+    start() {
+      if (!port) return;
+      cleanups.push(ports.identity.subscribe(onIdentity));
+      cleanups.push(
+        (0, import_summon2.registerCloseFlusher)((event) => {
+          if (writeSafe) {
+            saveNow();
+            return;
+          }
+          for (const intent of event.intents) {
+            if (intent.scope === "all") closedAll = true;
+            else if (intent.scope === "overlay") closedOverlay.add(intent.overlayId);
+            else closedExact.add((0, import_summon2.windowSessionKey)(intent.overlayId, intent.instanceId));
+          }
+        })
+      );
+      let previous = store.getState();
+      cleanups.push(
+        store.subscribe(() => {
+          const next = store.getState();
+          const changed = next.windowManager !== previous.windowManager || next.overlayState !== previous.overlayState;
+          previous = next;
+          if (changed && writeSafe) scheduleSave();
+        })
+      );
+      if (typeof window !== "undefined") {
+        const renew = () => {
+          if (workspaceId) local?.workspaces.renew(workspaceId);
+        };
+        const onPageHide = () => {
+          saveNow();
+          if (workspaceId) local?.workspaces.release(workspaceId);
+        };
+        const onVisibility = () => {
+          if (document.visibilityState === "hidden") saveNow();
+          else renew();
+        };
+        window.addEventListener("pagehide", onPageHide);
+        window.addEventListener("pageshow", renew);
+        window.addEventListener("focus", renew);
+        document.addEventListener("visibilitychange", onVisibility);
+        const sweep = window.setInterval(() => store.dispatch((0, import_summon2.pruneStaleInstances)({ olderThanMs: STALE_SWEEP_MS })), STALE_SWEEP_MS);
+        cleanups.push(() => {
+          window.removeEventListener("pagehide", onPageHide);
+          window.removeEventListener("pageshow", renew);
+          window.removeEventListener("focus", renew);
+          document.removeEventListener("visibilitychange", onVisibility);
+          window.clearInterval(sweep);
+        });
+      }
+      onIdentity();
+    },
+    stop() {
+      saveNow();
+      generation += 1;
+      writeSafe = false;
+      if (saveTimer) clearTimeout(saveTimer);
+      saveTimer = null;
+      for (const cleanup of cleanups.splice(0)) cleanup();
+      identityKey = null;
+    }
+  };
+}
+
+// src/persistence/OverlayPersistence.tsx
+var import_react = require("react");
+var import_react2 = require("@ai-matrx/summon/react");
+function useOverlayPersistence(options = {}) {
+  const store = (0, import_react2.useSummonStore)();
+  const ports = (0, import_react2.useSummonPorts)();
+  const [hydrated, setHydrated] = (0, import_react.useState)(false);
+  const { scope, seedFromPerson, saveDebounceMs, viewport } = options;
+  (0, import_react.useEffect)(() => {
+    const controller = createOverlayPersistenceController(store, ports, {
+      ...scope === void 0 ? {} : { scope },
+      ...seedFromPerson === void 0 ? {} : { seedFromPerson },
+      ...saveDebounceMs === void 0 ? {} : { saveDebounceMs },
+      ...viewport === void 0 ? {} : { viewport },
+      onHydratedChange: setHydrated
+    });
+    controller.start();
+    return () => controller.stop();
+  }, [store, ports, scope, seedFromPerson, saveDebounceMs, viewport]);
+  return { hydrated };
+}
+function OverlayPersistence(props) {
+  useOverlayPersistence(props);
+  return null;
+}
+//# sourceMappingURL=persistence.cjs.map