@ai-matrx/summon 0.0.0-stage → 0.1.0

package/dist/persistence.d.ts

@@ -0,0 +1,236 @@
+import { OverlayPersistencePort, PersistedWindowSession, HydratedWindowSession, AnyOverlayMeta, WindowPreservation, WindowManagerState, SummonRootState, SummonPorts } from '@ai-matrx/summon';
+export { L as LOAD_TIMEOUT_ERROR, a as PersistenceLoadTimeoutError, P as PersistenceVersionConflictError, V as VERSION_CONFLICT_ERROR, b as isLoadTimeout, i as isVersionConflict } from './errors-eJrKXq33.js';
+import { Dispatch, UnknownAction } from '@reduxjs/toolkit';
+
+/**
+ * The warm tier behind the local store: a tiny async key/value interface, implemented over raw
+ * IndexedDB (no Dexie) and in memory (tests, SSR, browsers without IndexedDB).
+ */
+interface KeyValueBackend {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Every key starting with `prefix`. */
+    keys(prefix: string): Promise<string[]>;
+}
+declare function createMemoryBackend(): KeyValueBackend & {
+    readonly data: Map<string, unknown>;
+};
+/**
+ * One object store in one database. The connection opens lazily on first use and is reused; a
+ * blocked/failed open rejects every call (the local store then lives on its synchronous mirror).
+ */
+declare function createIndexedDbBackend(dbName?: string, storeName?: string): KeyValueBackend;
+
+/**
+ * createLocalPersistence — an OverlayPersistencePort over the browser: a synchronous localStorage
+ * mirror (the fast, pagehide-safe tier) plus IndexedDB (the warm tier). Ported from matrx-frontend
+ * `localWindowSessionStore.ts` + `lib/sync/persistence/*` with the same safety:
+ *
+ *  - write ordering: the mirror is written synchronously first; IndexedDB follows in a per-key
+ *    queue under `navigator.locks` (cross-tab) when available. A mirror write that fails removes
+ *    the old mirror, so a stale value never looks authoritative.
+ *  - reads: a valid mirror answers at once; otherwise IndexedDB gets a 750 ms budget, after which
+ *    load rejects with a PersistenceLoadTimeoutError carrying the still-pending answer.
+ *  - per-tab workspaces (`workspaces`): sessionStorage id + 24 h lease; a duplicated tab (same
+ *    sessionStorage, another live document holds the lease, not a reload) gets a fresh id; an
+ *    index per identity caps workspaces at 5 and GC skips any workspace with a live lease.
+ *  - identity isolation: keys arrive scoped (`<identityKey>/<key>`); `purgeIdentity` removes
+ *    everything one identity stored, both tiers (the old store missed the mirror keys).
+ *
+ * All state lives in the store instance (no module state). Create ONE per app.
+ */
+
+declare const DEFAULT_IDB_READ_BUDGET_MS = 750;
+declare const WORKSPACE_LEASE_MS: number;
+declare const MAX_WORKSPACES_PER_IDENTITY = 5;
+/** The slice of the Web Storage API the store uses. */
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    key(index: number): string | null;
+    readonly length: number;
+}
+/** The slice of `navigator.locks` the store uses. */
+interface LocksLike {
+    request<T>(name: string, callback: () => Promise<T>): Promise<T>;
+}
+interface LocalPersistenceOptions {
+    /** Prefix of every localStorage key and the IndexedDB database name. Default "ai-matrx.overlays". */
+    readonly namespace?: string;
+    /** Warm tier. Default: IndexedDB when present, else in-memory. */
+    readonly backend?: KeyValueBackend;
+    /** Default: window.localStorage (absent → memory-only mirror is skipped). */
+    readonly storage?: StorageLike | null;
+    /** Default: window.sessionStorage. */
+    readonly session?: StorageLike | null;
+    /** Default: navigator.locks. */
+    readonly locks?: LocksLike | null;
+    readonly idbReadBudgetMs?: number;
+    /** Is this document a reload? Default: the Navigation Timing entry. */
+    readonly isReload?: () => boolean;
+    readonly now?: () => number;
+}
+interface LocalWorkspaces {
+    /** This tab's workspace id (stable across reloads, fresh for a duplicated tab). Claims its lease. */
+    currentId(): string;
+    /** Event-driven lease heartbeat (focus, pageshow, visible). */
+    renew(workspaceId: string): void;
+    /** Release the lease this document holds (pagehide). */
+    release(workspaceId: string): void;
+    /** Record use of a workspace for an identity; evicts the oldest beyond the cap (live leases spared). */
+    index(identityKey: string, workspaceId: string): void;
+}
+interface LocalOverlayPersistence extends OverlayPersistencePort {
+    readonly perPerson: false;
+    readonly workspaces: LocalWorkspaces;
+    list(prefix: string): Promise<readonly string[]>;
+    /** Remove everything stored under one identity (both tiers). */
+    purgeIdentity(identityKey: string): Promise<void>;
+    /** Resolves once every queued IndexedDB write has finished (tests, shutdown). */
+    idle(): Promise<void>;
+}
+declare function isLocalPersistence(port: OverlayPersistencePort | null | undefined): port is LocalOverlayPersistence;
+declare function createLocalPersistence(options?: LocalPersistenceOptions): LocalOverlayPersistence;
+
+/** Storage keys the orchestration writes (before identity scoping). */
+declare const PERSON_WORKSPACE_KEY = "workspace";
+declare const tabWorkspaceKey: (workspaceId: string) => string;
+declare const STATE_KEY_PREFIX = "state:";
+declare const stateKey: (instanceKey: string) => string;
+/** `<identityKey>/<key>` for stores that are not per-person themselves. */
+declare const identityScopedKey: (identityKey: string, key: string) => string;
+
+/**
+ * The window workspace record: serialize the window manager into a compact JSON record and
+ * validate a stored one back into staged sessions. Ported from matrx-frontend
+ * `windowSessionSerialization.ts`; the old metadata table is now each definition's `window`
+ * options in the registry.
+ *
+ * DEFAULT DENY: a window is saved and restored only when its definition has `window.preservation`
+ * and is not `ephemeral`; only `preservation.dataKeys` of its data are kept; unknown overlay ids
+ * are rejected with a diagnostic. `window.restoreDefaults` is merged UNDER saved data on restore.
+ */
+
+declare const WINDOW_WORKSPACE_SCHEMA_VERSION: 1;
+declare const DEFAULT_WINDOW_DATA_BYTES: number;
+declare const MAX_WINDOW_WORKSPACE_BYTES: number;
+declare const MAX_PERSISTED_WINDOW_SESSIONS = 64;
+interface PersistedWindowWorkspace {
+    schemaVersion: typeof WINDOW_WORKSPACE_SCHEMA_VERSION;
+    workspaceId: string;
+    savedAt: number;
+    sessions: PersistedWindowSession[];
+}
+type WindowPersistenceDiagnosticCode = "unsupported-data" | "window-data-too-large" | "workspace-too-large" | "invalid-workspace" | "invalid-session" | "unknown-overlay" | "preservation-disabled" | "state-too-large";
+interface WindowPersistenceDiagnostic {
+    level: "warning" | "error";
+    code: WindowPersistenceDiagnosticCode;
+    sessionKey?: string;
+    message: string;
+}
+interface Preserved {
+    readonly meta: AnyOverlayMeta;
+    readonly preservation: WindowPreservation;
+}
+/** The definition's preservation, or null when the window is not preserved (default deny). */
+declare function preservationFor(overlayId: string): Preserved | null;
+interface JsonSanitizeResult {
+    data: Record<string, unknown>;
+    droppedUnsupported: boolean;
+    bytes: number;
+}
+/**
+ * Copy `allowedKeys` (all keys when `null`) into plain JSON. Functions, symbols, undefined and
+ * circular references are dropped; BigInt becomes text; class instances are dropped.
+ */
+declare function sanitizeJsonRecord(value: unknown, allowedKeys: readonly string[] | null): JsonSanitizeResult;
+/** Validate one stored session against the registry (default deny). */
+declare function readSession(value: unknown, diagnostics: WindowPersistenceDiagnostic[]): PersistedWindowSession | null;
+declare function serializeWindowWorkspace(state: WindowManagerState, workspaceId: string, savedAt?: number): {
+    workspace: PersistedWindowWorkspace;
+    diagnostics: WindowPersistenceDiagnostic[];
+};
+/**
+ * Validate a stored workspace into staged sessions: rects clamped to the viewport, tray slots
+ * renumbered, `restoreDefaults` merged under the saved data. `expectedWorkspaceId` (tab scope)
+ * rejects a record written by another workspace.
+ */
+declare function hydrateWindowWorkspace(raw: unknown, viewport: {
+    width: number;
+    height: number;
+}, expectedWorkspaceId?: string): {
+    sessions: HydratedWindowSession[];
+    diagnostics: WindowPersistenceDiagnostic[];
+};
+
+/**
+ * The persistence orchestration, framework-free: one controller per overlays store. The React
+ * component (`OverlayPersistence`) only starts and stops it.
+ *
+ *  - identity ready → load the workspace (tab or person scope) and saved component state →
+ *    validate (default deny, see workspace.ts) → stage/apply → open what is not open yet.
+ *  - window manager / overlayState change → save debounced 250 ms; flush on pagehide, hidden
+ *    visibility and every close (close-lifecycle flusher). Writes stay gated until the load for
+ *    the CURRENT identity has applied, so an unknown stored value is never overwritten.
+ *  - identity change → close everything, clear staged persistence and component state, load the
+ *    new identity. Nothing of one identity is ever written under another.
+ *
+ * LINK vs RESTORE (deterministic in both orders, for the same instance):
+ *   the link's DATA wins, the restored GEOMETRY wins.
+ *   - restore after link: an instance already open keeps its data (no re-open); its saved
+ *     geometry is staged (window not registered yet → `registerWindow` takes the staged rect and
+ *     merges staged data UNDER the live data) or applied to the live window directly.
+ *   - link after restore: the link's open replaces the overlay's data; the staged/applied
+ *     geometry is untouched by an open.
+ */
+
+type PersistenceScope = "tab" | "person";
+interface OverlayPersistenceOptions {
+    /**
+     * `tab`: one workspace per browser tab (the local store's default). `person`: one workspace per
+     * person (`workspace`) — windows follow the person across devices (the data adapter's default).
+     */
+    readonly scope?: PersistenceScope;
+    /** Tab scope: a tab with no workspace of its own starts from the person's last one. Default true. */
+    readonly seedFromPerson?: boolean;
+    readonly saveDebounceMs?: number;
+    /** Viewport used to clamp restored rects. Default: the sanitized window size. */
+    readonly viewport?: () => {
+        width: number;
+        height: number;
+    };
+    /** Called whenever `hydrated` flips. */
+    readonly onHydratedChange?: (hydrated: boolean) => void;
+}
+interface PersistenceStore {
+    getState(): SummonRootState;
+    dispatch: Dispatch<UnknownAction>;
+    subscribe(listener: () => void): () => void;
+}
+interface OverlayPersistenceController {
+    start(): void;
+    stop(): void;
+    /** Save now (skips unchanged records). */
+    flush(): void;
+    readonly hydrated: boolean;
+}
+declare const DEFAULT_SAVE_DEBOUNCE_MS = 250;
+/** Component state is saved for definitions with keepAlive "restore" or a preserved window. */
+declare function persistsComponentState(overlayId: string): boolean;
+declare function createOverlayPersistenceController(store: PersistenceStore, ports: SummonPorts, options?: OverlayPersistenceOptions): OverlayPersistenceController;
+
+/**
+ * Turn persistence on for the nearest <SummonProvider> (reads `ports.persistence` and
+ * `ports.identity`; inert when persistence is null). Mount ONCE. Returns whether the current
+ * identity's saved layout has been applied.
+ */
+declare function useOverlayPersistence(options?: Omit<OverlayPersistenceOptions, "onHydratedChange">): {
+    hydrated: boolean;
+};
+type OverlayPersistenceProps = Omit<OverlayPersistenceOptions, "onHydratedChange">;
+/** Component form of `useOverlayPersistence` — mount once inside <SummonProvider>. */
+declare function OverlayPersistence(props: OverlayPersistenceProps): null;
+
+export { DEFAULT_IDB_READ_BUDGET_MS, DEFAULT_SAVE_DEBOUNCE_MS, DEFAULT_WINDOW_DATA_BYTES, type KeyValueBackend, type LocalOverlayPersistence, type LocalPersistenceOptions, type LocalWorkspaces, type LocksLike, MAX_PERSISTED_WINDOW_SESSIONS, MAX_WINDOW_WORKSPACE_BYTES, MAX_WORKSPACES_PER_IDENTITY, OverlayPersistence, type OverlayPersistenceController, type OverlayPersistenceOptions, type OverlayPersistenceProps, PERSON_WORKSPACE_KEY, type PersistedWindowWorkspace, type PersistenceScope, type PersistenceStore, STATE_KEY_PREFIX, type StorageLike, WINDOW_WORKSPACE_SCHEMA_VERSION, WORKSPACE_LEASE_MS, type WindowPersistenceDiagnostic, type WindowPersistenceDiagnosticCode, createIndexedDbBackend, createLocalPersistence, createMemoryBackend, createOverlayPersistenceController, hydrateWindowWorkspace, identityScopedKey, isLocalPersistence, persistsComponentState, preservationFor, readSession, sanitizeJsonRecord, serializeWindowWorkspace, stateKey, tabWorkspaceKey, useOverlayPersistence };