@drakkar.software/starfish-client 3.0.0-alpha.5 → 3.0.0-alpha.50

package/dist/bindings/legend.js

@@ -57,7 +57,39 @@ function createStarfishObservable(options) {
   };
   return { state, pull, set, flush, setOnline };
 }
+function createStarfishLogObservable(options) {
+  const { cursor } = options;
+  const state = observable({
+    // Seed from the cursor so a warm-started cursor's items show immediately.
+    items: cursor.getItems(),
+    loading: false,
+    online: true,
+    error: null,
+    checkpoint: cursor.getCheckpoint()
+  });
+  const pull = async () => {
+    if (state.loading.get()) return [];
+    state.loading.set(true);
+    state.error.set(null);
+    try {
+      const batch = await cursor.pull();
+      state.items.set(cursor.getItems());
+      state.checkpoint.set(cursor.getCheckpoint());
+      return batch;
+    } catch (err) {
+      state.error.set(err instanceof Error ? err.message : String(err));
+      return [];
+    } finally {
+      state.loading.set(false);
+    }
+  };
+  const setOnline = (online) => {
+    state.online.set(online);
+  };
+  return { state, pull, setOnline };
+}
 export {
+  createStarfishLogObservable,
   createStarfishObservable
 };
 //# sourceMappingURL=legend.js.map

package/dist/bindings/legend.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/bindings/legend.ts"],
-  "sourcesContent": ["import { observable } from \"@legendapp/state\"\nimport type { Observable } from \"@legendapp/state\"\nimport type { SyncManager } from \"../sync.js\"\n\nexport interface StarfishLegendState {\n  data: Record<string, unknown>\n  syncing: boolean\n  online: boolean\n  dirty: boolean\n  error: string | null\n}\n\nexport interface StarfishLegendStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLegendState>\n  pull: () => Promise<void>\n  set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void\n  flush: () => Promise<void>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishObservableOptions {\n  /** Unique name for this collection (used for persistence keys when applicable). */\n  name: string\n  syncManager: SyncManager\n  /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */\n  produce?: <T>(base: T, recipe: (draft: T) => T | void) => T\n}\n\nexport function createStarfishObservable(\n  options: CreateStarfishObservableOptions,\n): StarfishLegendStore {\n  const state = observable<StarfishLegendState>({\n    data: {},\n    syncing: false,\n    online: true,\n    dirty: false,\n    error: null,\n  })\n\n  const flush = async (): Promise<void> => {\n    if (state.syncing.get() || !state.dirty.get()) return\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.push(state.data.get())\n      state.data.set(options.syncManager.getData())\n      state.dirty.set(false)\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const pull = async (): Promise<void> => {\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.pull()\n      state.data.set(options.syncManager.getData())\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const set = (\n    modifier: (current: Record<string, unknown>) => Record<string, unknown>,\n  ): void => {\n    try {\n      const current = state.data.get()\n      const next = options.produce\n        ? options.produce(\n            current,\n            modifier as (draft: Record<string, unknown>) => Record<string, unknown> | void,\n          )\n        : modifier(current)\n      state.data.set(next)\n      state.dirty.set(true)\n      state.error.set(null)\n      if (state.online.get()) flush().catch(() => {})\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n    if (online && state.dirty.get()) flush().catch(() => {})\n  }\n\n  return { state, pull, set, flush, setOnline }\n}\n"],
-  "mappings": ";AAAA,SAAS,kBAAkB;AA6BpB,SAAS,yBACd,SACqB;AACrB,QAAM,QAAQ,WAAgC;AAAA,IAC5C,MAAM,CAAC;AAAA,IACP,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,OAAO;AAAA,EACT,CAAC;AAED,QAAM,QAAQ,YAA2B;AACvC,QAAI,MAAM,QAAQ,IAAI,KAAK,CAAC,MAAM,MAAM,IAAI,EAAG;AAC/C,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,IAAI,CAAC;AAC/C,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAC5C,YAAM,MAAM,IAAI,KAAK;AAAA,IACvB,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,OAAO,YAA2B;AACtC,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK;AAC/B,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAAA,IAC9C,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,MAAM,CACV,aACS;AACT,QAAI;AACF,YAAM,UAAU,MAAM,KAAK,IAAI;AAC/B,YAAM,OAAO,QAAQ,UACjB,QAAQ;AAAA,QACN;AAAA,QACA;AAAA,MACF,IACA,SAAS,OAAO;AACpB,YAAM,KAAK,IAAI,IAAI;AACnB,YAAM,MAAM,IAAI,IAAI;AACpB,YAAM,MAAM,IAAI,IAAI;AACpB,UAAI,MAAM,OAAO,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAChD,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE;AAAA,EACF;AAEA,QAAM,YAAY,CAAC,WAA0B;AAC3C,UAAM,OAAO,IAAI,MAAM;AACvB,QAAI,UAAU,MAAM,MAAM,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzD;AAEA,SAAO,EAAE,OAAO,MAAM,KAAK,OAAO,UAAU;AAC9C;",
+  "sourcesContent": ["import { observable } from \"@legendapp/state\"\nimport type { Observable } from \"@legendapp/state\"\nimport type { SyncManager } from \"../sync.js\"\nimport type { AppendLogCursor, AppendElement } from \"../append-log.js\"\n\nexport interface StarfishLegendState {\n  data: Record<string, unknown>\n  syncing: boolean\n  online: boolean\n  dirty: boolean\n  error: string | null\n}\n\nexport interface StarfishLegendStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLegendState>\n  pull: () => Promise<void>\n  set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void\n  flush: () => Promise<void>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishObservableOptions {\n  /** Unique name for this collection (used for persistence keys when applicable). */\n  name: string\n  syncManager: SyncManager\n  /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */\n  produce?: <T>(base: T, recipe: (draft: T) => T | void) => T\n}\n\nexport function createStarfishObservable(\n  options: CreateStarfishObservableOptions,\n): StarfishLegendStore {\n  const state = observable<StarfishLegendState>({\n    data: {},\n    syncing: false,\n    online: true,\n    dirty: false,\n    error: null,\n  })\n\n  const flush = async (): Promise<void> => {\n    if (state.syncing.get() || !state.dirty.get()) return\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.push(state.data.get())\n      state.data.set(options.syncManager.getData())\n      state.dirty.set(false)\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const pull = async (): Promise<void> => {\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.pull()\n      state.data.set(options.syncManager.getData())\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const set = (\n    modifier: (current: Record<string, unknown>) => Record<string, unknown>,\n  ): void => {\n    try {\n      const current = state.data.get()\n      const next = options.produce\n        ? options.produce(\n            current,\n            modifier as (draft: Record<string, unknown>) => Record<string, unknown> | void,\n          )\n        : modifier(current)\n      state.data.set(next)\n      state.dirty.set(true)\n      state.error.set(null)\n      if (state.online.get()) flush().catch(() => {})\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n    if (online && state.dirty.get()) flush().catch(() => {})\n  }\n\n  return { state, pull, set, flush, setOnline }\n}\n\n// \u2500\u2500 Append-only log binding \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// The reactive counterpart for an append-only collection, backed by an\n// `AppendLogCursor`. Read-only (a log only grows): no `set`/`flush`/`dirty`.\n// The cursor owns the items + checkpoint; persist via `getItems()` and\n// rehydrate by constructing the cursor with `initialItems`.\n//\n// The store assumes it is the SOLE driver of its cursor (it seeds from\n// `cursor.getItems()` at construction and updates only via its own `pull()`);\n// don't also call `cursor.pull()` directly, or the observable will go stale.\n\nexport interface StarfishLogObservableState {\n  /** The full accumulated log, newest appended last. */\n  items: AppendElement[]\n  /** A `pull()` is in flight. */\n  loading: boolean\n  online: boolean\n  error: string | null\n  /** The cursor's checkpoint (max `ts` held). */\n  checkpoint: number\n}\n\nexport interface StarfishLogObservableStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLogObservableState>\n  /** Pull elements newer than the checkpoint, append them, return the new batch.\n   *  Errors are captured into `state.error`. */\n  pull: () => Promise<AppendElement[]>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishLogObservableOptions {\n  cursor: AppendLogCursor\n}\n\nexport function createStarfishLogObservable(\n  options: CreateStarfishLogObservableOptions,\n): StarfishLogObservableStore {\n  const { cursor } = options\n  const state = observable<StarfishLogObservableState>({\n    // Seed from the cursor so a warm-started cursor's items show immediately.\n    items: cursor.getItems(),\n    loading: false,\n    online: true,\n    error: null,\n    checkpoint: cursor.getCheckpoint(),\n  })\n\n  const pull = async (): Promise<AppendElement[]> => {\n    if (state.loading.get()) return []\n    state.loading.set(true)\n    state.error.set(null)\n    try {\n      const batch = await cursor.pull()\n      state.items.set(cursor.getItems())\n      state.checkpoint.set(cursor.getCheckpoint())\n      return batch\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n      return []\n    } finally {\n      state.loading.set(false)\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n  }\n\n  return { state, pull, setOnline }\n}\n"],
+  "mappings": ";AAAA,SAAS,kBAAkB;AA8BpB,SAAS,yBACd,SACqB;AACrB,QAAM,QAAQ,WAAgC;AAAA,IAC5C,MAAM,CAAC;AAAA,IACP,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,OAAO;AAAA,EACT,CAAC;AAED,QAAM,QAAQ,YAA2B;AACvC,QAAI,MAAM,QAAQ,IAAI,KAAK,CAAC,MAAM,MAAM,IAAI,EAAG;AAC/C,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,IAAI,CAAC;AAC/C,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAC5C,YAAM,MAAM,IAAI,KAAK;AAAA,IACvB,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,OAAO,YAA2B;AACtC,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK;AAC/B,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAAA,IAC9C,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,MAAM,CACV,aACS;AACT,QAAI;AACF,YAAM,UAAU,MAAM,KAAK,IAAI;AAC/B,YAAM,OAAO,QAAQ,UACjB,QAAQ;AAAA,QACN;AAAA,QACA;AAAA,MACF,IACA,SAAS,OAAO;AACpB,YAAM,KAAK,IAAI,IAAI;AACnB,YAAM,MAAM,IAAI,IAAI;AACpB,YAAM,MAAM,IAAI,IAAI;AACpB,UAAI,MAAM,OAAO,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAChD,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE;AAAA,EACF;AAEA,QAAM,YAAY,CAAC,WAA0B;AAC3C,UAAM,OAAO,IAAI,MAAM;AACvB,QAAI,UAAU,MAAM,MAAM,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzD;AAEA,SAAO,EAAE,OAAO,MAAM,KAAK,OAAO,UAAU;AAC9C;AAqCO,SAAS,4BACd,SAC4B;AAC5B,QAAM,EAAE,OAAO,IAAI;AACnB,QAAM,QAAQ,WAAuC;AAAA;AAAA,IAEnD,OAAO,OAAO,SAAS;AAAA,IACvB,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,YAAY,OAAO,cAAc;AAAA,EACnC,CAAC;AAED,QAAM,OAAO,YAAsC;AACjD,QAAI,MAAM,QAAQ,IAAI,EAAG,QAAO,CAAC;AACjC,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,MAAM,OAAO,KAAK;AAChC,YAAM,MAAM,IAAI,OAAO,SAAS,CAAC;AACjC,YAAM,WAAW,IAAI,OAAO,cAAc,CAAC;AAC3C,aAAO;AAAA,IACT,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAChE,aAAO,CAAC;AAAA,IACV,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,YAAY,CAAC,WAA0B;AAC3C,UAAM,OAAO,IAAI,MAAM;AAAA,EACzB;AAEA,SAAO,EAAE,OAAO,MAAM,UAAU;AAClC;",
   "names": []
 }

package/dist/bindings/suspense.js

@@ -0,0 +1,49 @@
+/**
+ * React Suspense integration for Starfish sync data.
+ * Creates resources that throw Promises while loading (Suspense protocol).
+ */
+/**
+ * Create a Suspense-compatible resource from an async fetcher.
+ * The first call to `read()` triggers the fetch. While loading, `read()` throws
+ * a Promise (which React Suspense catches to show a fallback). Once resolved,
+ * `read()` returns the value synchronously.
+ *
+ * @example
+ * ```tsx
+ * const resource = createSuspenseResource(() => syncManager.pull())
+ * function MyComponent() {
+ *   const data = resource.read() // throws while loading, returns data when ready
+ *   return <div>{JSON.stringify(data)}</div>
+ * }
+ * ```
+ */
+export function createSuspenseResource(fetcher) {
+    let status = "pending";
+    let result;
+    let error;
+    let promise = null;
+    function init() {
+        if (promise)
+            return promise;
+        promise = fetcher().then((value) => {
+            status = "resolved";
+            result = value;
+        }, (err) => {
+            status = "rejected";
+            error = err;
+        });
+        return promise;
+    }
+    return {
+        read() {
+            switch (status) {
+                case "pending":
+                    throw init();
+                case "resolved":
+                    return result;
+                case "rejected":
+                    throw error;
+            }
+        },
+    };
+}

package/dist/bindings/zustand.d.ts

@@ -1,9 +1,10 @@
 import { type StoreApi } from "zustand/vanilla";
 import { type StateStorage } from "zustand/middleware";
 import type { DevtoolsOptions } from "zustand/middleware";
-import type { Encryptor } from "@drakkar.software/starfish-protocol";
+import type { Encryptor, PullResult } from "@drakkar.software/starfish-protocol";
 import { SyncManager } from "../sync.js";
-import type { StarfishCapProvider, ConflictResolver } from "../types.js";
+import { AppendLogCursor, type AppendElement } from "../append-log.js";
+import type { StarfishClientOptions, StarfishCapProvider, ConflictResolver, PullCache } from "../types.js";
 import type { SyncLogger } from "../logger.js";
 import type { Validator } from "../validate.js";
 export interface StarfishState {
@@ -14,6 +15,14 @@ export interface StarfishState {
     error: string | null;
     /** Last-known server hash, persisted alongside `data`/`dirty`. Restored into the bound SyncManager on hydration. */
     hash: string | null;
+    /**
+     * True when the currently-shown `data` came from the offline read-through
+     * cache (a cache-first {@link StarfishActions.seed} or a {@link StarfishActions.pull}
+     * the client served from cache because the transport was unreachable) rather
+     * than a live server response. A successful live pull/flush clears it. Use it
+     * to drive an "offline / showing last-synced data" indicator.
+     */
+    stale: boolean;
 }
 export interface StarfishActions {
     pull: () => Promise<void>;
@@ -22,6 +31,26 @@ export interface StarfishActions {
     restore: (data: Record<string, unknown>) => void;
     flush: () => Promise<void>;
     setOnline: (online: boolean) => void;
+    /**
+     * Cache-first paint: populate `data` from the client's offline read-through
+     * cache (decrypting in memory for E2E collections) without touching the
+     * network. A no-op when the client has no cache configured or there's no
+     * (unexpired) entry. {@link useSyncInit} calls this once before the initial
+     * pull; the live pull then supersedes the seeded snapshot.
+     */
+    seed: () => Promise<void>;
+    /**
+     * Apply a freshly-fetched `PullResult` to the store WITHOUT firing a network
+     * request. Decrypts in memory for E2E collections, conflict-merges against
+     * any local optimistic writes (same logic as a live pull), and clears `stale`.
+     *
+     * Primarily called automatically by the binding when
+     * {@link StarfishClientOptions.onRevalidated} fires (background revalidation
+     * delivered a fresh snapshot after a 429/5xx hit or an SWR-on-read). Also
+     * available for manual use when a caller holds a fresh `PullResult` it wants
+     * to push into the store without a second network round-trip.
+     */
+    mergeResult: (result: PullResult) => Promise<void>;
 }
 export type StarfishStore = StarfishState & StarfishActions;
 export interface CreateStarfishStoreOptions {
@@ -62,6 +91,20 @@ export interface CreateStarfishStoreOptions {
      * ```
      */
     onRemoteUpdate?: (data: Record<string, unknown>) => void;
+    /**
+     * Auto re-attempt a failed flush with exponential backoff while the store
+     * stays dirty + online. Omit to keep the current no-retry behavior.
+     *
+     * Defaults when the option is present: `maxRetries: 5`, `initialDelayMs: 500`,
+     * `maxDelayMs: 30_000`. Backoff is `min(initial * 2^attempt, max) + jitter(100ms)`.
+     * A successful flush resets the counter. Going offline cancels any pending retry.
+     * `AbortError`s are never retried.
+     */
+    flushRetry?: {
+        maxRetries?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+    };
 }
 export type { DevtoolsOptions };
 export declare function createStarfishStore(options: CreateStarfishStoreOptions): StoreApi<StarfishStore>;
@@ -76,6 +119,8 @@ export declare function deriveSyncStatus(state: StarfishState): SyncStatus;
 export declare function aggregateSyncStatus(statuses: SyncStatus[]): SyncStatus;
 /** Use the full Starfish store state and actions. */
 export declare function useStarfish(store: StoreApi<StarfishStore>): StarfishStore;
+/** Subscribe to a fine-grained slice of Starfish store state. Avoids re-renders on unrelated field changes. */
+export declare function useStarfishState<T>(store: StoreApi<StarfishStore>, selector: (state: StarfishState) => T): T;
 /** Use only the synced data, with an optional selector for fine-grained subscriptions. */
 export declare function useStarfishData<T = Record<string, unknown>>(store: StoreApi<StarfishStore>, selector?: (data: Record<string, unknown>) => T): T;
 /** Use the derived sync status (synced | syncing | pending | error | offline). */
@@ -104,6 +149,13 @@ export declare function useConnectivity(store: StoreApi<StarfishStore>): void;
 export declare function useLastSynced(store: StoreApi<StarfishStore>): string;
 export interface SyncInitConfig {
     serverUrl: string;
+    /**
+     * Optional server namespace, forwarded to the underlying {@link StarfishClient}
+     * so `pullPath`/`pushPath` are rewritten to `/v1/<namespace>/…` (signed AND sent).
+     * Leave unset for a root-mounted server. Pass the bare name (e.g. `"octochat"`),
+     * not `/v1/octochat` — the `/v1/` is added by the client.
+     */
+    namespace?: string;
     capProvider?: StarfishCapProvider;
     pullPath: string;
     pushPath: string;
@@ -115,6 +167,29 @@ export interface SyncInitConfig {
     storeName?: string;
     storage?: StateStorage | false;
     fetch?: typeof globalThis.fetch;
+    /**
+     * Offline-first read-through cache for the underlying {@link StarfishClient}
+     * (see {@link StarfishClientOptions.cache}). When set, the store seeds from the
+     * last-synced ciphertext on creation (cache-first paint, decrypted in memory)
+     * and the live pull falls back to it when the transport is unreachable; the
+     * store's `stale` flag reflects whether the shown data is from cache.
+     */
+    cache?: PullCache;
+    /** Max age (ms) for {@link cache} entries; see {@link StarfishClientOptions.cacheMaxAgeMs}. */
+    cacheMaxAgeMs?: number;
+    /**
+     * HTTP status codes for which pulls fall back to the last-cached snapshot rather than
+     * throwing — stale-while-revalidate for transient server failures.
+     * See {@link StarfishClientOptions.cacheFallbackStatuses}.
+     * Recommended set for offline-first apps: `[429, 500, 502, 503, 504]`.
+     */
+    cacheFallbackStatuses?: number[];
+    /**
+     * Called after a background revalidation following a {@link cacheFallbackStatuses} hit:
+     * the server returned a live response and the fresh snapshot has been written through.
+     * See {@link StarfishClientOptions.onRevalidated}.
+     */
+    onRevalidated?: StarfishClientOptions["onRevalidated"];
     logger?: SyncLogger;
     validate?: Validator;
 }
@@ -128,3 +203,93 @@ export interface SyncInitConfig {
  * Pass `null` to disable sync (returns `null`).
  */
 export declare function useSyncInit(config: SyncInitConfig | null): StoreApi<StarfishStore> | null;
+/**
+ * Config for a shared sync store — identical to {@link SyncInitConfig} EXCEPT:
+ *  - `onData` is omitted: it is not safe to fan out a single `onRemoteUpdate`
+ *    callback to multiple independent subscribers. Consumers should instead
+ *    subscribe to the returned store via `store.subscribe(...)`.
+ *  - `storeName` is REQUIRED: it is the registry key, not an optional label.
+ */
+export type SharedSyncConfig = Omit<SyncInitConfig, "onData" | "storeName"> & {
+    /** Registry key AND store persistence label. Required; there is no default. */
+    storeName: string;
+};
+/**
+ * Return (or create) the shared zustand store for `config.storeName`.
+ *
+ * On the **first** acquire, constructs `StarfishClient` → `SyncManager` → store
+ * (forwarding all config fields, including `cacheFallbackStatuses` and `onRevalidated`
+ * for native stale-while-revalidate), then fires `seed().finally(pull())`. On every
+ * subsequent acquire of the same `storeName`, the existing store is returned — **no**
+ * new pull fires.
+ *
+ * Always pair with {@link releaseSyncStore}. Call {@link clearSyncStoreRegistry}
+ * on account switch / sign-out.
+ */
+export declare function acquireSyncStore(config: SharedSyncConfig): StoreApi<StarfishStore>;
+/**
+ * Release a previously acquired store. Decrements the refCount; on 0 the entry is
+ * evicted — the store, client, and sync manager are dropped and GC'd (mirrors
+ * `useSyncInit`'s own teardown, which simply drops the local store reference).
+ */
+export declare function releaseSyncStore(storeName: string): void;
+/**
+ * Clear all registry entries.
+ *
+ * Call on account switch or sign-out alongside any other per-session cache clears.
+ * An identity guard inside {@link acquireSyncStore} prevents any in-flight pull from
+ * firing against the old session's cap after this is called.
+ */
+export declare function clearSyncStoreRegistry(): void;
+/**
+ * React hook that returns (or creates) the shared zustand store for
+ * `config.storeName` — a drop-in replacement for {@link useSyncInit} when the
+ * same logical document is consumed from multiple components.
+ *
+ * **Key design decision — effect deps include only `storeName`:** config identity
+ * churn (fresh `capProvider`/`encryptor` refs per render) is intentionally ignored.
+ * For a given `(user, space)` the cap and keyring are functionally equivalent across
+ * refs, and no `onData` fan-out is needed, so the shared store never needs to rebuild
+ * on churn. The `configRef` pattern ensures the latest config values are captured at
+ * acquire-time without re-running the effect.
+ *
+ * Pass `null` to disable sync (returns `null`).
+ */
+export declare function useSharedSyncStore(config: SharedSyncConfig | null): StoreApi<StarfishStore> | null;
+export interface StarfishLogState {
+    /** The full accumulated log, newest appended last. */
+    items: AppendElement[];
+    /** A `pull()` is in flight. */
+    loading: boolean;
+    online: boolean;
+    error: string | null;
+    /** The cursor's checkpoint (max `ts` held). */
+    checkpoint: number;
+}
+export interface StarfishLogActions {
+    /** Pull elements newer than the checkpoint, append them, and return the new
+     *  batch. Errors are captured into `error` (mirroring the SyncManager store). */
+    pull: () => Promise<AppendElement[]>;
+    setOnline: (online: boolean) => void;
+}
+export type StarfishLogStore = StarfishLogState & StarfishLogActions;
+export interface CreateStarfishLogOptions {
+    cursor: AppendLogCursor;
+    devtools?: (storeCreator: any) => any;
+}
+export declare function createStarfishLog(options: CreateStarfishLogOptions): StoreApi<StarfishLogStore>;
+/** Derived status for an append-log store. */
+export type LogStatus = "idle" | "loading" | "error" | "offline";
+/** Derive a single status from log store state. */
+export declare function deriveLogStatus(state: StarfishLogState): LogStatus;
+/** Use the full append-log store state and actions. */
+export declare function useStarfishLog(store: StoreApi<StarfishLogStore>): StarfishLogStore;
+/** Use only the accumulated items, with an optional selector for fine-grained subscriptions. */
+export declare function useStarfishLogItems<T = AppendElement[]>(store: StoreApi<StarfishLogStore>, selector?: (items: AppendElement[]) => T): T;
+/** Use the derived log status (idle | loading | error | offline). */
+export declare function useLogStatus(store: StoreApi<StarfishLogStore>): LogStatus;
+/** Subscribe to log status changes outside of React. Invoked immediately with the
+ *  current status, then on every change. Returns an unsubscribe function. */
+export declare function subscribeLogStatus(store: StoreApi<StarfishLogStore>, callback: (status: LogStatus) => void): () => void;
+/** Binds browser online/offline events to the log store's setOnline action. Cleans up on unmount. */
+export declare function useLogConnectivity(store: StoreApi<StarfishLogStore>): void;