@ikonai/sdk-ui 1.0.66 → 1.0.68

package/live-snapshot.d.ts

@@ -0,0 +1,71 @@
+import { StreamSnapshot } from './ui-store';
+import { UiStreamSnapshotWire } from './ui-store-ops';
+import { UiStylePayload } from './ikon-ui-core';
+export interface LiveSnapshotConfig {
+    /** Stable per-app identifier (e.g. the space id). Part of the storage key. */
+    appId: string;
+    /**
+     * 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 a live snapshot, shaped for `UiStore.applyStoreOp(ReplaceStreamSnapshot)`. */
+export interface LiveSnapshotState {
+    streams: UiStreamSnapshotWire[];
+    styles: UiStylePayload[];
+}
+/**
+ * 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 miss
+ * always degrades cleanly to the live connect path.
+ *
+ * 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. A missing user id
+ * disables the live snapshot rather than falling back to a shared key.
+ */
+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;
+    /** 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.
+     */
+    save(streams: StreamSnapshot[], styles: readonly UiStylePayload[]): void;
+    /** Write any pending state immediately and synchronously (used on dispose / unmount). */
+    flush(): void;
+    dispose(): void;
+    private writePending;
+    private writeNow;
+    private remove;
+    private pruneOtherUsers;
+}

package/package.json

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