@drakkar.software/starfish-client 3.0.0-alpha.2 → 3.0.0-alpha.21

package/README.md

@@ -185,6 +185,8 @@ new StarfishClient({
   baseUrl: "https://api.example.com/v1",
   capProvider,            // v3 — signs every request. Replaces v2 `auth`/`authProvider`.
   fetch,                  // optional custom fetch
+  cache,                  // optional offline-first read-through cache — see below
+  cacheMaxAgeMs,          // optional TTL (ms) for cache entries
 })
 ```
 
@@ -192,6 +194,19 @@ new StarfishClient({
 
 Omit `capProvider` for unauthenticated public reads.
 
+### Offline-first read cache
+
+Pass a `cache` (a `PullCache`: `{ get(k): Promise<string|null>; set(k, v): Promise<void> }`, host-backed by `localStorage`/`AsyncStorage`/etc.) to make every structured `pull()` offline-capable:
+
+- **Write-through:** a successful pull stores the raw `{data, hash, timestamp}` keyed by document path.
+- **Offline fallback:** a pull that fails because the **transport** is unreachable (`fetch` rejects — offline/DNS/timeout) returns the last cached snapshot, tagged so callers can tell it's stale (`pullWasFromCache(result)`).
+- **Real HTTP errors propagate:** 404/403/5xx are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning.
+- **`cacheMaxAgeMs`:** an entry older than this is treated as a miss (both cache-first paint and offline fallback); omit for entries that never expire (recommended for offline-first, where any last-synced data beats none).
+- **Ciphertext-at-rest by construction:** the cache stores the raw server payload, which for E2E (`delegated`) collections is the sealed ciphertext the server holds — never the decrypted form. Decryption happens in memory on read (see `SyncManager.seedFromCache`).
+- **`client.peekCache(path)`** reads the cached snapshot *without* a network round-trip — the basis for cache-first paint.
+
+Append collections are not cached here; they own warm-start persistence via `AppendLogCursor` (`persistEncrypted`).
+
 ## `SyncManager`
 
 ```ts
@@ -205,6 +220,35 @@ new SyncManager({
 
 - `signer.getSigner()` returns `{ devEdPubHex, sign(payload) }`. When set, every push attaches `authorPubkey = cap.sub` and `authorSignature = base64(Ed25519(payload))` over the encrypted payload (without the author fields).
 - `encryptor` is the only encryption option — the v2 single-secret `encryptionSecret`/`encryptionSalt` shorthand was removed in v3.
+- `onConflict` resolves write conflicts on push *and* reconciles a pull against un-pushed local writes. On a zustand-bound store, a `pull()` while the store is `dirty` merges the fetched snapshot with the local data through this resolver (rather than overwriting it), so an optimistic write isn't lost when a pull races a `set()`. Use a union/CRDT-style resolver (`createUnionMerge`) for append-style collections so both the local and remote writes survive; `SyncManager.resolve(local, remote)` exposes the same merge for callers that need it.
+- **Offline-first (with a client `cache`):** `seedFromCache()` populates `localData` from the client's read-through cache without a network round-trip, decrypting in memory for E2E collections — the merge-doc counterpart to `AppendLogCursor.getDecryptedItems()`. `getLastPullFromCache()` reports whether the latest `pull()`/seed came from cache. On a zustand store these power cache-first paint: `useSyncInit` seeds before the initial pull, and the store exposes a `stale` flag (`seed()` action + `state.stale`) so the UI can show an "offline / showing last-synced data" indicator that clears on the next live pull.
+
+## `AppendLogCursor`
+
+Incremental, stateful cursor over an append-only collection — the log counterpart to `SyncManager`. It owns the accumulated array and pulls only what's new; the checkpoint is **derived from the last element it holds**, so it resumes from persisted data on a fresh page.
+
+```ts
+const log = new AppendLogCursor({
+  client, pullPath: "/pull/events",
+  appendField,            // default "items"
+  initialItems,           // warm-start seed (raw {ts,data} envelopes) — or pass `since`
+  encryptor,              // optional: decrypt each element's data (ts/author preserved)
+  verifyAuthor,           // optional: true | { expectedAuthorPubkey?, alg? }
+  onElementError,         // optional: "throw" (default) | "skip" — see below
+  persistEncrypted,       // optional: keep ciphertext for E2EE-safe persistence — see below
+})
+const fresh = await log.pull()  // only elements newer than the last held (safe to call concurrently)
+log.getItems()                  // full accumulated log (ciphertext under persistEncrypted)
+await log.getDecryptedItems()   // full log decrypted — render warm-started history
+log.getCheckpoint()             // max ts held — persist, and restore via setCheckpoint()
+```
+
+- Cold start (no seed) → first `pull()` fetches the whole collection; warm start (seeded) → resumes incrementally.
+- `verifyAuthor` verifies each element's author signature over the stored (pre-decryption) data and throws `AppendAuthorError` atomically on any failure (nothing is appended, checkpoint unchanged).
+- `onElementError: "skip"` drops an element that fails verify/decrypt **and advances the checkpoint past it** (never re-fetched), so one unreadable element in a multi-writer / E2EE log can't blank the whole log. Default `"throw"` keeps the atomic behavior. SECURITY: `"skip"` also drops author-verification failures silently — combine with `verifyAuthor.expectedAuthorPubkey` or a post-pull `authorPubkey` check for strict authorship.
+- `persistEncrypted: true` (with an `encryptor`) stores each element's **ciphertext** so `getItems()` is safe to persist at rest for an E2EE log; `pull()` still returns decrypted, and `getDecryptedItems()` decrypts the full held log for warm-start rendering.
+- `pull()` is safe to call concurrently — overlapping calls serialize internally so they never double-append a window.
+- **Reactive bindings:** `createStarfishLog` (Zustand, `./zustand`) + hooks `useStarfishLog` / `useStarfishLogItems` / `useLogStatus` / `useLogConnectivity`; `createStarfishLogObservable` (Legend, `./legend`); `createAppendLogMobileLifecycle` (pull on app foreground). `startPolling` and `createSuspenseResource` work with `cursor.pull()` directly.
 
 ## Other utilities
 

package/dist/append-log.d.ts

@@ -0,0 +1,228 @@
+import { type Encryptor } from "@drakkar.software/starfish-protocol";
+import type { StarfishClient } from "./client.js";
+import type { SyncLogger } from "./logger.js";
+/**
+ * A single stored element of an append-only collection, exactly as returned by
+ * `client.pull(path, { appendField })`. `ts` is the server-assigned, strictly
+ * increasing element timestamp; `data` is the payload (plaintext under the
+ * `"none"` encryption mode, the opaque encryptor wrapper under `"delegated"`).
+ *
+ * When an {@link AppendLogCursor} is given an `encryptor`, the elements it
+ * stores and returns carry the **decrypted** `data` while preserving `ts` and
+ * the author fields — so the shape is uniform and re-seedable. The exception is
+ * `persistEncrypted` mode (see {@link AppendLogCursorOptions.persistEncrypted}),
+ * where the stored elements keep their **ciphertext** `data` (E2EE-safe to
+ * persist) and decryption happens only on read via {@link AppendLogCursor.pull}
+ * and {@link AppendLogCursor.getDecryptedItems}.
+ */
+export interface AppendElement {
+    ts: number;
+    data: Record<string, unknown>;
+    authorPubkey?: string;
+    authorSignature?: string;
+}
+/** Per-element author-signature verification policy for {@link AppendLogCursor}. */
+export interface AuthorVerifier {
+    /** If set, every element's `authorPubkey` MUST equal this key (compared as
+     *  case-insensitive hex), else the pull fails. Omit to accept any signing key
+     *  (verify only that the signature is valid for the element's self-declared
+     *  `authorPubkey` — see the `verifyAuthor` note on restricting authors). */
+    expectedAuthorPubkey?: string;
+}
+/**
+ * What to do when a single element fails verification or decryption during a
+ * {@link AppendLogCursor.pull} (or {@link AppendLogCursor.getDecryptedItems}).
+ *
+ * - `"throw"` (default): the pull is **atomic** — the first bad element throws
+ *   and NO state is mutated, so the checkpoint never advances past an element
+ *   that could not be re-fetched. Use when every element must be readable.
+ * - `"skip"`: a bad element is dropped from the returned/decrypted batch and the
+ *   checkpoint still **advances past it** (so it is never re-fetched), letting one
+ *   poison element fail without blanking the whole log. Intended for tolerating
+ *   **decrypt** failures in a multi-writer / E2EE log (keyring skew, a foreign or
+ *   corrupt element). SECURITY NOTE: `"skip"` ALSO silently drops elements that
+ *   fail *author* verification rather than failing loudly — so if you also need
+ *   strict authorship, set `verifyAuthor.expectedAuthorPubkey` (single author) or
+ *   check each element's `authorPubkey` against your authorized set after pull.
+ */
+export type ElementErrorPolicy = "throw" | "skip";
+export interface AppendLogCursorOptions {
+    client: StarfishClient;
+    /** Pull endpoint path, e.g. `"/pull/events"`. */
+    pullPath: string;
+    /** Array field name in the pulled document. Defaults to `"items"`. */
+    appendField?: string;
+    /**
+     * Warm-start seed: raw envelopes the caller persisted last session. The
+     * cursor adopts them verbatim and derives its initial checkpoint from their
+     * max `ts`. Under the default mode they are taken as already-decrypted (and
+     * never re-decrypted/re-verified); under `persistEncrypted` they are the
+     * persisted **ciphertext** and are decrypted on read (see `persistEncrypted`).
+     */
+    initialItems?: AppendElement[];
+    /**
+     * Explicit checkpoint-only seed (ms). Resume incrementally without
+     * rehydrating history. When given together with `initialItems`, it must be
+     * `>= max(ts of initialItems)` (a lower value would re-fetch held items).
+     */
+    since?: number;
+    /**
+     * When set, each freshly-pulled element's `.data` is decrypted via this
+     * encryptor (the `ts`/author fields are preserved). Author verification, when
+     * enabled, runs over the original (pre-decryption) `data`.
+     *
+     * Caveat (default mode): a returned / `getItems()` element then holds DECRYPTED
+     * `data` but an `authorSignature` computed over the stored CIPHERTEXT — they no
+     * longer match, so do NOT re-verify a decrypted element with `verifyAppendAuthor`.
+     * The cursor already verified it (over the ciphertext) at pull time when
+     * `verifyAuthor` is on; `authorPubkey` is retained for identity. (Under
+     * `persistEncrypted` the stored elements keep their ciphertext, so this caveat
+     * does not apply to `getItems()`.)
+     */
+    encryptor?: Encryptor;
+    /**
+     * Per-element failure policy for verification/decryption. Defaults to
+     * `"throw"` (atomic pull — preserves the pre-existing behavior). See
+     * {@link ElementErrorPolicy}.
+     */
+    onElementError?: ElementErrorPolicy;
+    /**
+     * Keep the **ciphertext** form of each element in the cursor's accumulated log
+     * instead of the decrypted form (requires `encryptor`; a no-op without one,
+     * since plaintext is already its own stored form). This makes
+     * {@link AppendLogCursor.getItems} return the persistable ciphertext — safe to
+     * write to disk for an end-to-end-encrypted log without leaking plaintext at
+     * rest — while {@link AppendLogCursor.pull} still returns the freshly-decrypted
+     * batch and {@link AppendLogCursor.getDecryptedItems} returns the full log
+     * decrypted (for warm-start rendering). Defaults to `false` (store decrypted).
+     */
+    persistEncrypted?: boolean;
+    /**
+     * `true` to verify every element's author signature, or a policy object.
+     *
+     * This verifies the signature is valid for the element's self-declared
+     * `authorPubkey` — it does NOT by itself restrict WHICH authors are accepted.
+     * To restrict authorship, set `expectedAuthorPubkey` (single author), or check
+     * each `el.authorPubkey` against your own authorization source (keyring /
+     * member list / cap allow-list) after pull — for a multi-writer log, the
+     * authorized set lives there and changes over time, not here.
+     *
+     * The signature covers `data` + the document key, but NOT `ts`: a malicious
+     * server cannot forge content, but can reorder or re-timestamp authentic
+     * elements, so trust `ts` only as far as you trust the server.
+     */
+    verifyAuthor?: boolean | AuthorVerifier;
+    /** Structured logger for pull events. */
+    logger?: SyncLogger;
+    /** Name passed to logger methods (default: derived from `pullPath`). */
+    loggerName?: string;
+}
+/** Thrown when an append element's author signature fails verification. */
+export declare class AppendAuthorError extends Error {
+    readonly ts: number;
+    constructor(ts: number);
+}
+/** Largest `ts` among `items`, or `0` when empty. The checkpoint for an
+ *  append-only log is exactly this — the server returns elements with
+ *  `ts > checkpoint`, and element timestamps are strictly increasing. */
+export declare function checkpointOf(items: readonly {
+    ts: number;
+}[]): number;
+/**
+ * A stateful cursor over an append-only collection. It owns the accumulated
+ * array of elements and pulls only what is new: each {@link pull} derives the
+ * checkpoint from the last element it holds and asks the server for elements
+ * with a greater `ts`.
+ *
+ * This is the incremental, stateful counterpart to the deliberately stateless
+ * `client.pull(path, { appendField, since })`, and the sibling of
+ * {@link SyncManager} for append-only logs (no merge / push-conflict
+ * machinery — a log only grows).
+ *
+ * The cursor accumulates every pulled element in memory; for an unboundedly
+ * large log, pull a bounded window with raw `client.pull(path, { last })` instead.
+ *
+ * Cold start (nothing persisted) — first `pull()` fetches the whole collection:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events" })
+ * const all = await log.pull()
+ * ```
+ * Warm start (resume from persisted data) — first `pull()` fetches only newer
+ * elements; persistence is a round-trip of `getItems()`:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events",
+ *   initialItems: await store.load() })
+ * const fresh = await log.pull()
+ * await store.save(log.getItems())
+ * ```
+ * Warm start for an **E2EE** log — persist ciphertext, render decrypted:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/streamchat",
+ *   encryptor, persistEncrypted: true, onElementError: "skip",
+ *   initialItems: await store.load() })           // ciphertext from disk
+ * const history = await log.getDecryptedItems()    // render persisted history
+ * const fresh = await log.pull()                   // decrypted delta
+ * await store.save(log.getItems())                 // ciphertext back to disk
+ * ```
+ */
+export declare class AppendLogCursor {
+    private readonly client;
+    private readonly pullPath;
+    private readonly appendField;
+    private readonly encryptor?;
+    private readonly verifyAuthor?;
+    private readonly onElementError;
+    private readonly persistEncrypted;
+    private readonly documentKey;
+    private readonly logger?;
+    private readonly loggerName;
+    private readonly items;
+    private lastCheckpoint;
+    /** Tail of the serialized pull chain. Concurrent `pull()` calls queue behind
+     *  it so each runs against the checkpoint the previous one advanced — no two
+     *  overlapping fetches read the same checkpoint and double-append a window. */
+    private pullChain;
+    constructor(options: AppendLogCursorOptions);
+    /**
+     * Fetch elements newer than the current checkpoint, verify + decrypt them,
+     * append them to the local log, and return ONLY the newly-fetched batch
+     * (decrypted when an `encryptor` is set).
+     *
+     * Atomic under `onElementError: "throw"` (the default): the batch is fully
+     * verified and decrypted into a local before any state mutation, so a
+     * verify/decrypt failure throws without advancing the checkpoint past elements
+     * that could never be re-fetched. Under `"skip"`, a failing element is dropped
+     * from the returned batch but the checkpoint still advances past it.
+     *
+     * Safe to call concurrently: overlapping calls are serialized internally, so
+     * each runs against the checkpoint the previous one advanced (no double-fetch
+     * of the same window). The next pull after one completes will pick up anything
+     * that arrived in between.
+     */
+    pull(): Promise<AppendElement[]>;
+    private doPull;
+    /** Verify a single element's author signature over its RAW (pre-decryption)
+     *  `data`. Throws {@link AppendAuthorError} on any failure. No-op when
+     *  verification is disabled. */
+    private verifyOne;
+    /** The full accumulated log (a shallow copy), in `ts` order. Under
+     *  `persistEncrypted` these carry CIPHERTEXT `data` (persist them as-is, then
+     *  re-seed via `initialItems`); otherwise they carry decrypted/plaintext data. */
+    getItems(): AppendElement[];
+    /**
+     * The full accumulated log, DECRYPTED — for rendering warm-started history in
+     * `persistEncrypted` mode (where {@link getItems} holds ciphertext). Honors
+     * `onElementError` (a `"skip"` cursor drops elements it cannot read). When the
+     * cursor has no `encryptor`, or is not in `persistEncrypted` mode, the held
+     * elements are already plaintext/decrypted and are returned as-is.
+     */
+    getDecryptedItems(): Promise<AppendElement[]>;
+    /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
+     *  when nothing has been pulled or seeded. */
+    getCheckpoint(): number;
+    /** Restore the checkpoint without seeding items — for persistence layers that
+     *  store only the checkpoint. Used to resume incrementally across restarts.
+     *  Rejects a value below the max `ts` already held: rewinding would make the
+     *  next pull re-deliver, and duplicate, elements the cursor already has. */
+    setCheckpoint(ts: number): void;
+}

package/dist/bindings/legend.d.ts

@@ -1,5 +1,6 @@
 import type { Observable } from "@legendapp/state";
 import type { SyncManager } from "../sync.js";
+import type { AppendLogCursor, AppendElement } from "../append-log.js";
 export interface StarfishLegendState {
     data: Record<string, unknown>;
     syncing: boolean;
@@ -23,3 +24,25 @@ export interface CreateStarfishObservableOptions {
     produce?: <T>(base: T, recipe: (draft: T) => T | void) => T;
 }
 export declare function createStarfishObservable(options: CreateStarfishObservableOptions): StarfishLegendStore;
+export interface StarfishLogObservableState {
+    /** 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 StarfishLogObservableStore {
+    /** The observable state tree — read fields with `.get()` inside `observer` components. */
+    state: Observable<StarfishLogObservableState>;
+    /** Pull elements newer than the checkpoint, append them, return the new batch.
+     *  Errors are captured into `state.error`. */
+    pull: () => Promise<AppendElement[]>;
+    setOnline: (online: boolean) => void;
+}
+export interface CreateStarfishLogObservableOptions {
+    cursor: AppendLogCursor;
+}
+export declare function createStarfishLogObservable(options: CreateStarfishLogObservableOptions): StarfishLogObservableStore;

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": "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",
   "names": []
 }

package/dist/bindings/zustand.d.ts

@@ -3,7 +3,8 @@ import { type StateStorage } from "zustand/middleware";
 import type { DevtoolsOptions } from "zustand/middleware";
 import type { Encryptor } 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 { 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,14 @@ 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>;
 }
 export type StarfishStore = StarfishState & StarfishActions;
 export interface CreateStarfishStoreOptions {
@@ -104,6 +121,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 +139,16 @@ 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;
     logger?: SyncLogger;
     validate?: Validator;
 }
@@ -128,3 +162,40 @@ export interface SyncInitConfig {
  * Pass `null` to disable sync (returns `null`).
  */
 export declare function useSyncInit(config: SyncInitConfig | 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;