@ikonai/sdk-ui 1.0.67 → 1.0.68

package/{last-snapshot-cache.d.ts → live-snapshot.d.ts}

@@ -1,47 +1,61 @@
 import { StreamSnapshot } from './ui-store';
 import { UiStreamSnapshotWire } from './ui-store-ops';
 import { UiStylePayload } from './ikon-ui-core';
-export interface LastSnapshotCacheConfig {
+export interface LiveSnapshotConfig {
     /** Stable per-app identifier (e.g. the space id). Part of the storage key. */
     appId: string;
-    /** Connected user id, or null/undefined for anonymous. Part of the storage key. */
-    userId?: string | null;
-    /** Cached state older than this is treated as missing. Default 7 days. */
+    /**
+     * The connected user's id — real when logged in, or the unique id issued by anonymous auth (stable
+     * per browser instance). Part of the storage key. There is deliberately NO fallback: a falsy id
+     * disables the live snapshot entirely (it never reads, writes, or prunes), so an unidentified
+     * session can never paint another session's UI on a shared device.
+     */
+    userId: string;
+    /**
+     * Stored state older than this is treated as missing. Default 5 minutes — kept under the app
+     * server's idle-kill window (per-space, default 15 min). Set this to the space's configured
+     * idle-kill time so the live snapshot never outlives the server it was captured from (a longer
+     * value risks flashing a stale tree that then snaps to the cold-started server's default view).
+     */
     maxAgeMs?: number;
     /** Serialized envelopes larger than this are dropped (not written). Default ~5 MB. */
     maxBytes?: number;
     /** Throttle window for writes (at most one write per window). Default 1000 ms. */
     debounceMs?: number;
 }
-/** UI state recovered from the cache, shaped for `UiStore.applyStoreOp(ReplaceStreamSnapshot)`. */
-export interface CachedUiState {
+/** UI state recovered from a live snapshot, shaped for `UiStore.applyStoreOp(ReplaceStreamSnapshot)`. */
+export interface LiveSnapshotState {
     streams: UiStreamSnapshotWire[];
     styles: UiStylePayload[];
 }
 /**
- * Persists the last rendered UI snapshot (view tree + styles) per app/user in `localStorage`, so a
+ * Persists the last rendered live snapshot (view tree + styles) per app/user in `localStorage`, so a
  * return visit can paint the cached tree before the WebSocket connects. The store is
- * schema-versioned, age-bounded, size-bounded, and silent on quota/serialization failure — a cache
- * miss always degrades cleanly to the live connect path.
+ * schema-versioned, age-bounded, size-bounded, and silent on quota/serialization failure — a miss
+ * always degrades cleanly to the live connect path.
  *
- * Binary payloads (images etc.) are **not** cached: they would dominate the size and make every
- * write re-encode unchanged bytes. The cached tree paints layout + text instantly; payload-backed
+ * Binary payloads (images etc.) are **not** stored: they would dominate the size and make every
+ * write re-encode unchanged bytes. The seeded tree paints layout + text instantly; payload-backed
  * content fills in once the live connection delivers it. Writes are throttled and run at idle time.
  *
  * The key embeds the user id, and sibling keys for other users of the same app are pruned on
- * construction so a shared device never paints one user's UI for another.
+ * construction so a shared device never paints one user's UI for another. A missing user id
+ * disables the live snapshot rather than falling back to a shared key.
  */
-export declare class LastSnapshotCache {
+export declare class LiveSnapshotCache {
     private readonly key;
     private readonly appId;
     private readonly userId;
+    private readonly disabled;
     private readonly maxAgeMs;
     private readonly maxBytes;
     private readonly debounceMs;
     private writeTimer;
     private pending;
-    constructor(config: LastSnapshotCacheConfig);
-    load(): CachedUiState | null;
+    /** Remove every stored live snapshot (all apps and users) from localStorage. Call on logout. */
+    static clearAll(): void;
+    constructor(config: LiveSnapshotConfig);
+    load(): LiveSnapshotState | null;
     /**
      * Schedule a throttled write of the current UI state (at most one write per window, captured at
      * the trailing edge). Streams with no root are skipped. The actual write runs at idle time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikonai/sdk-ui",
-  "version": "1.0.67",
+  "version": "1.0.68",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",