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

package/README.md

@@ -185,6 +185,10 @@ 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
+  cacheFallbackStatuses,  // optional — serve cache on 429/5xx (stale-while-revalidate)
+  onRevalidated,          // optional — called after a background revalidation succeeds
 })
 ```
 
@@ -192,6 +196,29 @@ new StarfishClient({
 
 Omit `capProvider` for unauthenticated public reads.
 
+### Offline-first read cache
+
+**Persist-backed Zustand stores are offline-first for reads without a client `cache`.** When
+`createStarfishStore` is used with a `storage`, the persisted `starfish-{name}` entry rehydrates
+`data` on cold start. If the first `pull()` then fails because the transport is unreachable (offline /
+DNS / timeout), `pull()` preserves the already-shown data and sets `stale: true` — no error, no empty
+screen. HTTP errors (4xx/5xx), aborts, and decrypt failures still set `error` as usual.
+
+The client `cache` (`PullCache`) remains available for additional capabilities:
+
+Pass a `cache` (a `PullCache`: `{ get(k): Promise<string|null>; set(k, v): Promise<void> }`, host-backed by `localStorage`/`AsyncStorage`/etc.) to the client for:
+
+- **Write-through:** a successful pull stores the raw `{data, hash, timestamp}` keyed by document path.
+- **Offline fallback (without a persist-backed store):** a pull that fails because the **transport** is unreachable returns the last cached snapshot, tagged so callers can tell it's stale (`pullWasFromCache(result)`).
+- **Real HTTP errors propagate:** 404/403 are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning. 429 and 5xx can optionally be caught via `cacheFallbackStatuses` (see below).
+- **Error-triggered stale-while-revalidate:** set `cacheFallbackStatuses: [429, 500, 502, 503, 504]` to make transient server failures serve the last-synced snapshot immediately and retry in the background (honoring `Retry-After`). When the live response arrives, the cache is updated and `onRevalidated` fires. No snapshot → the error propagates as usual. Do NOT include 403/404 — they are genuine answers, not transient failures.
+- **Proactive stale-while-revalidate (`staleWhileRevalidate` pull option):** pass `{ staleWhileRevalidate: true }` to `client.pull(path, { staleWhileRevalidate: true })` to serve the cached snapshot immediately and revalidate in the background on every read (not just on errors). On a cache hit the cached result is returned at once (tagged via `pullWasFromCache`) and the background fetch fires immediately (no initial delay). On a miss it falls through to a normal network-first pull. `onRevalidated` fires on success with the fresh `PullResult`. Both SWR paths share the same dedup loop — a concurrent error-triggered loop and an SWR-on-read loop for the same document collapse to one.
+- **`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 +232,38 @@ 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:** Zustand stores backed by `storage` are offline-first without any client `cache` — a transport failure during `pull()` preserves the persisted data and sets `stale: true` on the store. When a client `cache` is also configured, `seedFromCache()` additionally populates `localData` from the ciphertext cache without a network round-trip (decrypting in memory for E2E collections); `getLastPullFromCache()` reports whether the latest `pull()`/seed came from that cache. On a zustand store, the `stale` flag tracks both sources: it is set by an offline `pull()` (no cache needed) and by `seed()` (cache-first paint before the initial live pull).
+- **`SyncManager.ingest(result: PullResult)`** applies an externally-delivered `PullResult` to the manager's state (decrypting for E2E, updating `localData`/`lastHash`/`lastCheckpoint`, clearing `lastFromCache`) without a network call. Used by the zustand binding's `mergeResult` action to absorb background revalidation results.
+
+**Auto-merge on revalidation:** when `cacheFallbackStatuses` or `staleWhileRevalidate` triggers a background revalidation, `useSyncInit` and `acquireSyncStore` automatically push the fresh `PullResult` into the bound store via `mergeResult` — the store repaints without waiting for the next explicit `pull()`. The consumer's own `onRevalidated` callback is still called after the store update. The `mergeResult` store action is also available for manual use when a caller holds a fresh `PullResult` it wants to push into the store without an extra round-trip.
+
+## `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/append-log.js

@@ -0,0 +1,267 @@
+import { verifyAppendAuthor, } from "@drakkar.software/starfish-protocol";
+/** The `/pull/` action prefix; mirrors `PUSH_PATH_PREFIX` for the read side. */
+const PULL_PATH_PREFIX = "/pull/";
+/** The storage `documentKey` for a pull `path`: the path with the `/pull/`
+ *  action prefix stripped (the namespace lives only in the URL). The author
+ *  signature binds to this key, so a reader re-derives it the same way the
+ *  writer did from `/push/…`. */
+function stripPullPrefix(path) {
+    return path.startsWith(PULL_PATH_PREFIX) ? path.slice(PULL_PATH_PREFIX.length) : path;
+}
+/** Thrown when an append element's author signature fails verification. */
+export class AppendAuthorError extends Error {
+    ts;
+    constructor(ts) {
+        super(`append element author verification failed (ts=${ts})`);
+        this.ts = ts;
+        this.name = "AppendAuthorError";
+    }
+}
+/** 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 function checkpointOf(items) {
+    let max = 0;
+    for (const it of items)
+        if (it.ts > max)
+            max = it.ts;
+    return max;
+}
+/** Copy the optional author fields from `src` onto a fresh element with `data`. */
+function withAuthor(ts, data, src) {
+    const out = { ts, data };
+    if (src.authorPubkey !== undefined)
+        out.authorPubkey = src.authorPubkey;
+    if (src.authorSignature !== undefined)
+        out.authorSignature = src.authorSignature;
+    return out;
+}
+/**
+ * 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 class AppendLogCursor {
+    client;
+    pullPath;
+    appendField;
+    encryptor;
+    verifyAuthor;
+    onElementError;
+    persistEncrypted;
+    documentKey;
+    logger;
+    loggerName;
+    items;
+    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. */
+    pullChain = Promise.resolve();
+    constructor(options) {
+        this.client = options.client;
+        this.pullPath = options.pullPath;
+        this.appendField = options.appendField ?? "items";
+        this.encryptor = options.encryptor;
+        this.verifyAuthor = options.verifyAuthor;
+        this.onElementError = options.onElementError ?? "throw";
+        this.persistEncrypted = options.persistEncrypted ?? false;
+        this.documentKey = stripPullPrefix(options.pullPath);
+        this.logger = options.logger;
+        this.loggerName =
+            options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
+        const seed = options.initialItems ?? [];
+        const seedCheckpoint = checkpointOf(seed);
+        if (options.since != null) {
+            if (options.since < 0)
+                throw new Error("since must be non-negative");
+            if (options.since < seedCheckpoint) {
+                throw new Error("since must be >= the max ts of initialItems");
+            }
+            this.lastCheckpoint = options.since;
+        }
+        else {
+            this.lastCheckpoint = seedCheckpoint;
+        }
+        this.items = [...seed];
+    }
+    /**
+     * 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.
+     */
+    async pull() {
+        // Chain onto the previous pull (whether it resolved or rejected) so calls
+        // run one-at-a-time against the latest checkpoint. `pullChain` swallows
+        // outcomes to stay alive; the caller still sees this call's real result.
+        const run = this.pullChain.then(() => this.doPull(), () => this.doPull());
+        this.pullChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async doPull() {
+        this.logger?.pullStart(this.loggerName);
+        const start = performance.now();
+        try {
+            const since = this.lastCheckpoint;
+            // Omit `since` on cold start so the request carries no `?checkpoint=`.
+            const opts = since > 0 ? { appendField: this.appendField, since } : { appendField: this.appendField };
+            const raw = await this.client.pull(this.pullPath, opts);
+            const batch = []; // decrypted, returned to the caller
+            const stored = []; // what we keep in `items` (cipher- or plaintext)
+            let maxTs = since;
+            let skipped = 0;
+            for (const el of raw) {
+                // Defensive: guard a misbehaving/mocked server from making us
+                // double-append a held element. Gated on `since > 0` to mirror the
+                // server (which only filters when checkpoint > 0): on a cold start
+                // `since` is 0 and we must NOT drop a legitimate `ts: 0` first element.
+                if (since > 0 && el.ts <= since)
+                    continue;
+                // Advance past every windowed element BEFORE verify/decrypt so a skipped
+                // element still moves the checkpoint and is never re-fetched.
+                if (el.ts > maxTs)
+                    maxTs = el.ts;
+                let decrypted = null;
+                try {
+                    this.verifyOne(el);
+                    const data = this.encryptor ? await this.encryptor.decrypt(el.data) : el.data;
+                    decrypted = withAuthor(el.ts, data, el);
+                }
+                catch (err) {
+                    // "throw" rethrows here, before any state mutation below — atomic.
+                    if (this.onElementError !== "skip")
+                        throw err;
+                    skipped++;
+                }
+                if (this.persistEncrypted) {
+                    // Keep the original ciphertext envelope (even for a skipped element:
+                    // it is valid data we simply cannot read now — a later key might).
+                    stored.push(withAuthor(el.ts, el.data, el));
+                }
+                else if (decrypted) {
+                    stored.push(decrypted);
+                }
+                if (decrypted)
+                    batch.push(decrypted);
+            }
+            this.items.push(...stored);
+            this.lastCheckpoint = maxTs;
+            this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start), skipped > 0 ? { skippedCount: skipped } : undefined);
+            return batch;
+        }
+        catch (err) {
+            this.logger?.pullError(this.loggerName, err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }
+    /** 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. */
+    verifyOne(el) {
+        if (!this.verifyAuthor)
+            return;
+        const policy = typeof this.verifyAuthor === "object" ? this.verifyAuthor : {};
+        const { authorPubkey, authorSignature } = el;
+        if (!authorPubkey || !authorSignature)
+            throw new AppendAuthorError(el.ts);
+        // Public keys are hex, which is case-insensitive — compare normalized so a
+        // caller passing a differently-cased `expectedAuthorPubkey` isn't falsely rejected.
+        if (policy.expectedAuthorPubkey &&
+            authorPubkey.toLowerCase() !== policy.expectedAuthorPubkey.toLowerCase()) {
+            throw new AppendAuthorError(el.ts);
+        }
+        void policy;
+        const ok = verifyAppendAuthor(this.documentKey, el.data, authorPubkey, authorSignature);
+        if (!ok)
+            throw new AppendAuthorError(el.ts);
+    }
+    /** 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() {
+        return [...this.items];
+    }
+    /**
+     * 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.
+     */
+    async getDecryptedItems() {
+        const snapshot = [...this.items];
+        if (!this.encryptor || !this.persistEncrypted)
+            return snapshot;
+        const out = [];
+        for (const el of snapshot) {
+            try {
+                this.verifyOne(el);
+                const data = await this.encryptor.decrypt(el.data);
+                out.push(withAuthor(el.ts, data, el));
+            }
+            catch (err) {
+                if (this.onElementError !== "skip")
+                    throw err;
+            }
+        }
+        return out;
+    }
+    /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
+     *  when nothing has been pulled or seeded. */
+    getCheckpoint() {
+        return this.lastCheckpoint;
+    }
+    /** 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) {
+        if (ts < checkpointOf(this.items)) {
+            throw new Error("checkpoint must be >= the max ts already held");
+        }
+        this.lastCheckpoint = ts;
+    }
+}

package/dist/background-sync.js

@@ -0,0 +1,29 @@
+/**
+ * Background Sync API integration for pending changes.
+ * Uses the Web Background Sync API to retry failed sync operations
+ * when connectivity is restored, even if the app is closed.
+ */
+/** Check if the Background Sync API is supported in the current environment. */
+export function isBackgroundSyncSupported() {
+    return (typeof navigator !== "undefined" &&
+        "serviceWorker" in navigator &&
+        "SyncManager" in globalThis);
+}
+/**
+ * Register a background sync event with the active service worker.
+ * Returns true if registration succeeded, false if not supported or no active SW.
+ */
+export async function registerBackgroundSync(opts) {
+    if (!isBackgroundSyncSupported())
+        return false;
+    const tag = opts?.tag ?? "starfish-sync";
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        // @ts-expect-error - SyncManager types may not be available
+        await registration.sync.register(tag);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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;