@drakkar.software/starfish-client 3.0.0-alpha.4 → 3.0.0-alpha.40

package/dist/bindings/zustand.js

@@ -230,7 +230,22 @@ import { useEffect, useRef, useState, useCallback } from "react";
 
 // src/client.ts
 import {
-  DEFAULT_ALG,
+  AUTHOR_PUBKEY_FIELD,
+  AUTHOR_SIGNATURE_FIELD,
+  DATA_FIELD,
+  TS_FIELD,
+  BASE_HASH_FIELD,
+  PUSH_PATH_PREFIX,
+  HEADER_AUTHORIZATION,
+  HEADER_SIG,
+  HEADER_TS,
+  HEADER_NONCE,
+  HEADER_PUB,
+  HEADER_CONTENT_TYPE,
+  HEADER_ACCEPT,
+  PARQUET_MIME_TYPE as PARQUET_MIME_TYPE_VALUE,
+  PARQUET_MIME_TYPES as PARQUET_MIME_TYPES_VALUE,
+  signAppendAuthor,
   signRequest,
   stableStringify
 } from "@drakkar.software/starfish-protocol";
@@ -250,9 +265,59 @@ var StarfishHttpError = class extends Error {
     this.name = "StarfishHttpError";
   }
 };
+var AppendHttpError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AppendHttpError";
+  }
+};
+
+// src/fetch.ts
+function parseRetryAfterMs(header, opts) {
+  const { fallbackMs, maxMs } = opts;
+  const trimmed = header?.trim();
+  if (trimmed) {
+    const seconds = Number(trimmed);
+    if (!isNaN(seconds)) return Math.min(seconds * 1e3, maxMs);
+    const date = Date.parse(trimmed);
+    if (!isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), maxMs);
+  }
+  return Math.min(fallbackMs, maxMs);
+}
+function classifyError(err) {
+  if (err instanceof Response || err && typeof err === "object" && "status" in err) {
+    const status = err.status;
+    if (typeof status !== "number" || isNaN(status)) return "unknown";
+    if (status === 0) return "network";
+    if (status === 401 || status === 403) return "auth";
+    if (status === 409) return "conflict";
+    if (status === 429) return "rate-limited";
+    if (status >= 500) return "server";
+    if (status >= 400) return "client";
+  }
+  if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message)) return "network";
+  return "unknown";
+}
 
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+var MAX_REVALIDATE_ATTEMPTS = 5;
+var REVALIDATE_INITIAL_DELAY_MS = 1e3;
+var REVALIDATE_MAX_DELAY_MS = 3e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function pullCacheKey(pathAndQuery) {
+  const q = pathAndQuery.indexOf("?");
+  return q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
+}
+function pullWasFromCache(result) {
+  return result.fromCache === true;
+}
+function stripPushPrefix(path) {
+  return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
+}
 function encodeCapAuth(cap) {
   const json = stableStringify(cap);
   if (typeof btoa === "function") {
@@ -264,8 +329,20 @@ function encodeCapAuth(cap) {
 }
 var StarfishClient = class {
   baseUrl;
+  namespace;
   capProvider;
   fetch;
+  cache;
+  cacheMaxAgeMs;
+  cacheFallbackStatuses;
+  onRevalidated;
+  revalidating = /* @__PURE__ */ new Set();
+  /**
+   * In-memory mirror of the latest document timestamp written to each cache
+   * key via {@link writeCache}. Updated synchronously so {@link revalidateLoop}
+   * can guard against stale overwrites without an extra async cache read.
+   */
+  latestCacheTimestamp = /* @__PURE__ */ new Map();
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -273,10 +350,24 @@ var StarfishClient = class {
   plugins;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.namespace = options.namespace || void 0;
     this.capProvider = options.capProvider;
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.cache = options.cache;
+    this.cacheMaxAgeMs = options.cacheMaxAgeMs;
+    this.cacheFallbackStatuses = options.cacheFallbackStatuses;
+    this.onRevalidated = options.onRevalidated;
     this.plugins = options.plugins ? [...options.plugins] : [];
   }
+  /**
+   * Mark a `PullResult` as having been served from the offline read-through
+   * cache (transport was unreachable). Non-enumerable so it doesn't leak into
+   * JSON / equality / re-caching; read via {@link pullWasFromCache}.
+   */
+  tagFromCache(result) {
+    Object.defineProperty(result, "fromCache", { value: true, enumerable: false });
+    return result;
+  }
   /**
    * Resolve the host portion of the URL the client will send to. The host
    * is folded into the signed canonical input as the `h` field so the
@@ -296,6 +387,20 @@ var StarfishClient = class {
       return "";
     }
   }
+  /**
+   * Rewrite a request path for the configured namespace. A no-op when no
+   * namespace is set; otherwise `/{action}/…` becomes `/v1/{namespace}/{action}/…`
+   * (the `/v1` protocol-version segment is part of the namespaced route, matching
+   * the Python client and the server's namespace mount).
+   *
+   * Applied to the path used for BOTH the signature and the URL so the canonical
+   * path the client signs equals the path the server reconstructs from the URL.
+   * Covers SDK-helper-built paths too — that's the point: a namespace-unaware
+   * helper passing `/push/spaces/x/_keyring` reaches `/v1/{ns}/push/spaces/x/_keyring`.
+   */
+  applyNamespace(path) {
+    return this.namespace ? `/v1/${this.namespace}${path}` : path;
+  }
   /**
    * Build auth headers for a request. When a `capProvider` is set, signs the
    * request with the device's Ed25519 private key and returns the v3 header
@@ -307,38 +412,59 @@ var StarfishClient = class {
    * The host bound into the signature is derived from `baseUrl` once per call.
    */
   async buildAuthHeaders(method, pathAndQuery, body) {
-    if (this.capProvider) {
-      const { cap, devEdPrivHex, pubHex, presenterAlg } = await this.capProvider.getCap();
-      const req = {
-        method,
-        pathAndQuery,
-        body,
-        host: this.signingHost()
-      };
-      const signAlg = cap.kind === "audience" ? presenterAlg ?? DEFAULT_ALG : cap.subAlg ?? cap.issAlg;
-      const { alg, sig, ts, nonce } = await signRequest(req, devEdPrivHex, {
-        alg: signAlg
-      });
-      const headers = {
-        Authorization: `Cap ${encodeCapAuth(cap)}`,
-        "X-Starfish-Sig": sig,
-        "X-Starfish-Ts": String(ts),
-        "X-Starfish-Nonce": nonce,
-        "X-Starfish-Alg": alg
-      };
-      if (pubHex !== void 0) headers["X-Starfish-Pub"] = pubHex;
-      return headers;
-    }
-    return {};
+    if (!this.capProvider) return {};
+    const capCtx = await this.capProvider.getCap();
+    return this.capRequestHeaders(capCtx, method, pathAndQuery, body);
+  }
+  /**
+   * Build the request-signing headers from an ALREADY-fetched cap context. Split
+   * out of {@link buildAuthHeaders} so {@link append} can fetch the cap once and
+   * reuse it for BOTH the author signature (over the element data) and the
+   * request signature (over the body), without redeeming the cap twice — a
+   * second `getCap()` could rotate keys and break the `authorPubkey ===
+   * presenter` bind the server checks.
+   */
+  async capRequestHeaders(capCtx, method, pathAndQuery, body) {
+    const { cap, devEdPrivHex, pubHex } = capCtx;
+    const req = {
+      method,
+      pathAndQuery,
+      body,
+      host: this.signingHost()
+    };
+    const { sig, ts, nonce } = await signRequest(req, devEdPrivHex);
+    const headers = {
+      [HEADER_AUTHORIZATION]: `Cap ${encodeCapAuth(cap)}`,
+      [HEADER_SIG]: sig,
+      [HEADER_TS]: String(ts),
+      [HEADER_NONCE]: nonce
+    };
+    if (pubHex !== void 0) headers[HEADER_PUB] = pubHex;
+    return headers;
+  }
+  /**
+   * Resolve the author public key to attach to a signed append: the redeemer's
+   * `pubHex` for an audience cap, else the cert subject `cap.sub` for a
+   * device/member cap. This is the SAME key that signs the request, so a server
+   * enforcing author proof can bind the stored element to its writer. Returns
+   * undefined only for a (malformed) cap with neither — the append then goes
+   * unsigned and a server requiring signatures rejects it.
+   */
+  appendAuthorKey(capCtx) {
+    const { cap, pubHex } = capCtx;
+    const authorPubHex = pubHex ?? cap.sub;
+    if (authorPubHex === void 0) return null;
+    return { authorPubHex };
   }
   async pull(path, checkpointOrOptions) {
-    let pathAndQuery = path;
+    let pathAndQuery = this.applyNamespace(path);
     let appendField;
+    let swr = false;
     if (typeof checkpointOrOptions === "number") {
       if (checkpointOrOptions) pathAndQuery += `?checkpoint=${checkpointOrOptions}`;
     } else if (checkpointOrOptions != null) {
       const opts = checkpointOrOptions;
-      const isPullOptions = opts.withKeyring !== void 0 || opts.checkpoint !== void 0;
+      const isPullOptions = opts.withKeyring !== void 0 || opts.checkpoint !== void 0 || opts.staleWhileRevalidate !== void 0;
       const params = new URLSearchParams();
       if (isPullOptions) {
         if (opts.checkpoint != null && opts.checkpoint > 0) {
@@ -347,56 +473,324 @@ var StarfishClient = class {
         if (opts.withKeyring) {
           params.set("withKeyring", "1");
         }
+        swr = opts.staleWhileRevalidate === true;
       } else {
         appendField = opts.appendField ?? APPEND_DEFAULT_FIELD;
+        if (opts.full && (opts.since != null || opts.limit != null || opts.last != null)) {
+          throw new Error("full cannot be combined with since, limit, or last");
+        }
         if (opts.since != null) {
           if (opts.since < 0) throw new Error("since must be non-negative");
           params.set("checkpoint", String(opts.since));
         }
+        if (opts.limit != null) {
+          if (opts.limit < 0) throw new Error("limit must be non-negative");
+          params.set("limit", String(opts.limit));
+        }
         if (opts.last != null) {
           if (opts.last < 0) throw new Error("last must be non-negative");
           params.set("last", String(opts.last));
         }
+        if (opts.full) {
+          params.set("full", "true");
+        }
       }
       if (params.size > 0) pathAndQuery += `?${params.toString()}`;
     }
     const url = `${this.baseUrl}${pathAndQuery}`;
     const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
-    const res = await this.fetch(url, {
-      method: "GET",
-      headers: { Accept: "application/json", ...authHeaders }
-    });
+    const cacheKey = this.cache && appendField === void 0 ? pullCacheKey(pathAndQuery) : void 0;
+    if (swr && cacheKey) {
+      const cached = await this.readCache(cacheKey);
+      if (cached) {
+        this.scheduleRevalidate(
+          cacheKey,
+          pathAndQuery,
+          null,
+          /* immediate */
+          true
+        );
+        return cached;
+      }
+    }
+    let res;
+    try {
+      res = await this.fetch(url, {
+        method: "GET",
+        headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+      });
+    } catch (err) {
+      if (cacheKey) {
+        const cached = await this.readCache(cacheKey);
+        if (cached) return cached;
+      }
+      throw err;
+    }
     if (!res.ok) {
-      throw new StarfishHttpError(res.status, await res.text());
+      const status = res.status;
+      if (cacheKey && this.cacheFallbackStatuses?.includes(status)) {
+        const retryAfterHeader = res.headers.get("Retry-After");
+        this.scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader);
+        const cached = await this.readCache(cacheKey);
+        if (cached) {
+          void res.body?.cancel();
+          return cached;
+        }
+      }
+      throw new StarfishHttpError(status, await res.text());
     }
     const result = await res.json();
     if (appendField !== void 0) {
       const list = result.data?.[appendField];
       return Array.isArray(list) ? list : [];
     }
+    if (cacheKey) this.writeCache(cacheKey, result);
     return result;
   }
+  /**
+   * Write a pull snapshot to the cache. Fire-and-forget; errors are swallowed
+   * so a failing cache never blocks the caller. No-op when no cache is configured.
+   */
+  writeCache(cacheKey, result) {
+    if (!this.cache) return;
+    if (result.timestamp > (this.latestCacheTimestamp.get(cacheKey) ?? -1)) {
+      this.latestCacheTimestamp.set(cacheKey, result.timestamp);
+    }
+    const snapshot = {
+      data: result.data,
+      hash: result.hash,
+      timestamp: result.timestamp,
+      cachedAt: Date.now()
+    };
+    void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+    });
+  }
+  /** Build the URL + auth headers for one revalidation GET. Shared between
+   *  {@link pull} and {@link revalidateLoop} to avoid duplicated fetch setup. */
+  async revalidateFetch(pathAndQuery) {
+    const url = `${this.baseUrl}${pathAndQuery}`;
+    const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+    return this.fetch(url, {
+      method: "GET",
+      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+    });
+  }
+  /**
+   * Deduplicated fire-and-forget: starts one revalidation loop per cacheKey.
+   * Used by both the {@link cacheFallbackStatuses} error path (delayed first
+   * attempt, honoring `Retry-After`) and the {@link PullOptions.staleWhileRevalidate}
+   * read path (`immediate: true` — no initial delay on the first attempt). The
+   * `revalidating` set deduplicates across both triggers so a concurrent
+   * error-triggered loop and an SWR-on-read loop for the same key collapse to one.
+   */
+  scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader, immediate = false) {
+    if (this.revalidating.has(cacheKey)) return;
+    this.revalidating.add(cacheKey);
+    void this.revalidateLoop(cacheKey, pathAndQuery, retryAfterHeader, immediate).finally(() => {
+      this.revalidating.delete(cacheKey);
+    });
+  }
+  /**
+   * Background revalidation loop shared by both {@link cacheFallbackStatuses}
+   * hits and {@link PullOptions.staleWhileRevalidate} reads.
+   *
+   * Retries (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS} times.
+   * When `immediate` is true the first attempt fires without any initial delay
+   * (SWR-on-read path). On a live 2xx the fresh snapshot is written to cache and
+   * {@link onRevalidated} fires. Stops early on a non-fallback status (403/404).
+   */
+  async revalidateLoop(cacheKey, pathAndQuery, firstRetryAfter, immediate = false) {
+    let retryAfterHeader = firstRetryAfter;
+    const fallbackSet = this.cacheFallbackStatuses ? new Set(this.cacheFallbackStatuses) : null;
+    for (let attempt = 0; attempt < MAX_REVALIDATE_ATTEMPTS; attempt++) {
+      if (!immediate || attempt > 0) {
+        const delay = parseRetryAfterMs(retryAfterHeader, {
+          fallbackMs: Math.min(
+            REVALIDATE_INITIAL_DELAY_MS * Math.pow(2, attempt),
+            REVALIDATE_MAX_DELAY_MS
+          ),
+          maxMs: REVALIDATE_MAX_DELAY_MS
+        });
+        await sleep(delay);
+      }
+      try {
+        const res = await this.revalidateFetch(pathAndQuery);
+        if (res.ok) {
+          const result = await res.json();
+          const latestTs = this.latestCacheTimestamp.get(cacheKey) ?? -1;
+          if (result.timestamp >= latestTs) {
+            this.writeCache(cacheKey, result);
+            this.onRevalidated?.(pathAndQuery, result);
+          }
+          return;
+        }
+        if (!fallbackSet?.has(res.status)) {
+          return;
+        }
+        retryAfterHeader = res.headers.get("Retry-After");
+      } catch {
+        retryAfterHeader = null;
+      }
+    }
+  }
+  /**
+   * Read the cached snapshot for a document `path` WITHOUT hitting the network —
+   * the basis for cache-first paint (seed the UI from the last-synced snapshot,
+   * then revalidate with a live {@link pull}). Returns the tagged `PullResult`,
+   * or null when no cache is configured / there's no entry. Namespacing matches
+   * {@link pull}, so the key lines up with whatever `pull` wrote.
+   */
+  async peekCache(path) {
+    if (!this.cache) return null;
+    return this.readCache(pullCacheKey(this.applyNamespace(path)));
+  }
+  /** Read + parse a cached pull snapshot, tagged {@link tagFromCache}. Returns
+   *  null on a miss or an unparseable blob (never throws — a corrupt cache entry
+   *  must not break a pull, just miss). */
+  async readCache(cacheKey) {
+    try {
+      const raw = await this.cache.get(cacheKey);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed.hash !== "string") return null;
+      if (this.cacheMaxAgeMs != null && Date.now() - (parsed.cachedAt ?? 0) > this.cacheMaxAgeMs) {
+        return null;
+      }
+      return this.tagFromCache({ data: parsed.data ?? {}, hash: parsed.hash, timestamp: parsed.timestamp ?? 0 });
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Pull several documents in one round-trip via `/batch/pull`. `collections` is
+   * the list of distinct collection names; `opts.params` supplies, per collection,
+   * an ARRAY of path-param sets — one per document to read — so the SAME collection
+   * can fan in many documents (e.g. many users' `profile`) in a single request.
+   * The server auto-fills the `{identity}` param from the authenticated caller for
+   * any set that omits it, so a self-doc collection needs no params. Returns a map
+   * of collection name → an ARRAY of pulled documents (or per-document `{ error }`),
+   * in request order. Honors the configured namespace.
+   *
+   * For the common "many docs of one collection" case prefer {@link batchPullMany}.
+   *
+   * Pass `appendParams` per entry for append-only bounded-tail reads (see {@link batchPullManyAppend}).
+   */
+  async batchPull(collections, opts = {}) {
+    const search = new URLSearchParams();
+    search.set("collections", collections.join(","));
+    if (opts.params && Object.keys(opts.params).length > 0) {
+      search.set("params", JSON.stringify(opts.params));
+    }
+    if (opts.appendParams && Object.keys(opts.appendParams).length > 0) {
+      for (const [col, optsArr] of Object.entries(opts.appendParams)) {
+        for (const ap of optsArr) {
+          if (ap.full) {
+            throw new Error(
+              `batchPull: appendParams["${col}"] contains full:true \u2014 full is not supported in batch pull`
+            );
+          }
+          if (ap.since != null && (!Number.isInteger(ap.since) || ap.since < 0)) {
+            throw new Error(`batchPull: appendParams["${col}"].since must be a non-negative integer`);
+          }
+          if (ap.last != null && (!Number.isInteger(ap.last) || ap.last < 0)) {
+            throw new Error(`batchPull: appendParams["${col}"].last must be a non-negative integer`);
+          }
+          if (ap.limit != null && (!Number.isInteger(ap.limit) || ap.limit < 0)) {
+            throw new Error(`batchPull: appendParams["${col}"].limit must be a non-negative integer`);
+          }
+        }
+      }
+      search.set("appendParams", JSON.stringify(opts.appendParams));
+    }
+    const pathAndQuery = `${this.applyNamespace("/batch/pull")}?${search.toString()}`;
+    const url = `${this.baseUrl}${pathAndQuery}`;
+    const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+    const res = await this.fetch(url, {
+      method: "GET",
+      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+    });
+    if (!res.ok) {
+      throw new StarfishHttpError(res.status, await res.text());
+    }
+    return await res.json();
+  }
+  /**
+   * Convenience over {@link batchPull} for reading MANY documents of ONE
+   * collection in a single round-trip: pass the per-document param-sets and get
+   * back the {@link BatchPullEntry} array aligned to `paramsList` by index (each
+   * entry is `{ data, hash, timestamp }` or `{ error }`). An empty `paramsList`
+   * issues no request and returns `[]`.
+   */
+  async batchPullMany(collection, paramsList) {
+    if (paramsList.length === 0) return [];
+    const res = await this.batchPull([collection], { params: { [collection]: paramsList } });
+    return res.collections[collection] ?? [];
+  }
+  /**
+   * Convenience over {@link batchPull} for reading append-only bounded tails from
+   * MANY entries of ONE collection in a single round-trip.
+   *
+   * Each request in `requests` carries optional `params` (path params) and
+   * `options` (append bounds: `since`/`last`/`limit`/`appendField`). An empty
+   * `requests` issues no request and returns `[]`.
+   *
+   * Returns an array aligned to `requests` by index. Each element is either:
+   * - the filtered array `T[]` extracted from `entry.data[appendField]`, or
+   * - `{ error: string }` if the server returned a per-entry error.
+   *
+   * The `appendField` used for extraction defaults to `"items"` and can be
+   * overridden per request via `options.appendField`.
+   *
+   * The `appendField` option is client-side only (used for result extraction, not sent to the server).
+   * It must match the collection's server-configured append field and defaults to `"items"`.
+   *
+   * Note: `full: true` is not supported in batch and is rejected client-side
+   * before the request is sent.
+   */
+  async batchPullManyAppend(collection, requests) {
+    if (requests.length === 0) return [];
+    const paramsList = requests.map((r) => r.params ?? {});
+    const appendParamsList = requests.map(({ options: { appendField: _af, ...wireOpts } }) => wireOpts);
+    const res = await this.batchPull([collection], {
+      params: { [collection]: paramsList },
+      appendParams: { [collection]: appendParamsList }
+    });
+    const entries = res.collections[collection] ?? [];
+    return entries.map((entry, i) => {
+      if (entry.error) return { error: entry.error };
+      const appendField = requests[i]?.options.appendField ?? APPEND_DEFAULT_FIELD;
+      const data = entry.data;
+      const items = data?.[appendField];
+      return Array.isArray(items) ? items : [];
+    });
+  }
   /**
    * Push synced data to the server.
    * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
    * @param data - The full document data to push
    * @param baseHash - Hash of the document this push is based on (null for first push)
    *
-   * v3 author fields (`authorPubkey` + `authorSignature`) live inside `data`
-   * and are produced by `SyncManager` when a `signer` is configured.
+   * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+   * (produced by `SyncManager` when a `signer` is configured) and sent as
+   * top-level body siblings of `data`, where the server verifies it.
    * @throws {ConflictError} if the server detects a hash mismatch (409)
    */
-  async push(path, data, baseHash) {
+  async push(path, data, baseHash, author) {
     const body = JSON.stringify({
-      data,
-      baseHash
+      [DATA_FIELD]: data,
+      [BASE_HASH_FIELD]: baseHash,
+      ...author && {
+        [AUTHOR_PUBKEY_FIELD]: author.authorPubkey,
+        [AUTHOR_SIGNATURE_FIELD]: author.authorSignature
+      }
     });
-    const authHeaders = await this.buildAuthHeaders("POST", path, body);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("POST", sendPath, body);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body
@@ -407,7 +801,12 @@ var StarfishClient = class {
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
-    return res.json();
+    const result = await res.json();
+    if (this.cache) {
+      const pullPath = sendPath.replace("/push/", "/pull/");
+      this.writeCache(pullCacheKey(pullPath), { data, hash: result.hash, timestamp: result.timestamp });
+    }
+    return result;
   }
   /**
    * Append an element to an appendOnly (`by_timestamp`) collection.
@@ -423,19 +822,37 @@ var StarfishClient = class {
    * @param opts.ts - optional client-supplied element timestamp (ms). Must be a
    *   non-negative integer strictly greater than the latest stored element's ts
    *   (else the server responds 409). Omit to let the server assign one.
-   * @throws {StarfishHttpError} on a non-2xx response (e.g. 409 for a
-   *   non-monotonic timestamp).
+   * @throws {StarfishHttpError} on a non-2xx response — e.g. 409
+   *   `{ error: "non_monotonic_timestamp" }` for a non-monotonic timestamp, or
+   *   `{ error: "append_limit_exceeded", limit }` if the collection's `maxItems`
+   *   cap is reached (partition by a path parameter for higher volume).
    */
   async append(path, data, opts = {}) {
-    const bodyObj = { data };
-    if (opts.ts !== void 0) bodyObj["ts"] = opts.ts;
+    const sendPath = this.applyNamespace(path);
+    const bodyObj = { [DATA_FIELD]: data };
+    if (opts.ts !== void 0) bodyObj[TS_FIELD] = opts.ts;
+    const capCtx = this.capProvider ? await this.capProvider.getCap() : null;
+    if (capCtx) {
+      const authorKey = this.appendAuthorKey(capCtx);
+      if (authorKey) {
+        const documentKey = stripPushPrefix(path);
+        const { authorPubkey, authorSignature } = signAppendAuthor(
+          documentKey,
+          data,
+          authorKey.authorPubHex,
+          capCtx.devEdPrivHex
+        );
+        bodyObj[AUTHOR_PUBKEY_FIELD] = authorPubkey;
+        bodyObj[AUTHOR_SIGNATURE_FIELD] = authorSignature;
+      }
+    }
     const body = JSON.stringify(bodyObj);
-    const authHeaders = await this.buildAuthHeaders("POST", path, body);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const authHeaders = capCtx ? await this.capRequestHeaders(capCtx, "POST", sendPath, body) : {};
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body
@@ -445,21 +862,78 @@ var StarfishClient = class {
     }
     return res.json();
   }
+  /**
+   * Append one element to a **public-write** append-only collection with an
+   * Ed25519 author proof but **no cap `Authorization` header**.
+   *
+   * Unlike {@link append}, which always attaches a cap-signed `Authorization`
+   * header from the configured `capProvider`, this method signs only the
+   * append-author proof (binding the element to the writer's Ed25519 key) and
+   * sends the request without authentication headers. This is required for
+   * collections with `writeRoles: ["public"]` — the server's cap-scope check
+   * would reject a request carrying a cap whose scope does not cover the path.
+   *
+   * Typical use-case: writing a sealed invitation to another user's
+   * public-write inbox collection without needing a cap scoped to the
+   * recipient's namespace. The author proof is optional on the server side
+   * (`requireAuthorSignature: false` for a public inbox), but signing anyway
+   * binds the stored element to the sender's Ed25519 key for verification in
+   * the receive path.
+   *
+   * The element is sent as `{ data, authorPubkey, authorSignature }`.
+   *
+   * @param path    The push path, e.g. `/push/inbox/{userId}/{shard}`.
+   * @param element The JSON element to append.
+   * @param signer  The sender's Ed25519 keypair (signs the author proof).
+   *
+   * @throws {AppendHttpError} on a non-2xx response.
+   */
+  async appendAnonymous(path, element, signer) {
+    const sendPath = this.applyNamespace(path);
+    const documentKey = stripPushPrefix(path);
+    const { authorPubkey, authorSignature } = signAppendAuthor(
+      documentKey,
+      element,
+      signer.edPubHex,
+      signer.edPrivHex
+    );
+    const body = JSON.stringify({
+      [DATA_FIELD]: element,
+      [AUTHOR_PUBKEY_FIELD]: authorPubkey,
+      [AUTHOR_SIGNATURE_FIELD]: authorSignature
+    });
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+      method: "POST",
+      headers: {
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json"
+      },
+      body
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new AppendHttpError(
+        res.status,
+        `anonymous append failed: HTTP ${res.status} ${detail}`.trim()
+      );
+    }
+  }
   /**
    * Pull binary data from a blob collection.
    * Returns raw bytes with the content hash from the ETag header.
    */
   async pullBlob(path) {
-    const authHeaders = await this.buildAuthHeaders("GET", path, void 0);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("GET", sendPath, void 0);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "GET",
-      headers: { Accept: "*/*", ...authHeaders }
+      headers: { [HEADER_ACCEPT]: "*/*", ...authHeaders }
     });
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
     const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? null;
-    const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+    const contentType = res.headers.get(HEADER_CONTENT_TYPE) ?? "application/octet-stream";
     const data = await res.arrayBuffer();
     return { data, hash: etag, contentType };
   }
@@ -468,12 +942,13 @@ var StarfishClient = class {
    * Binary collections use last-write-wins (no conflict detection).
    */
   async pushBlob(path, data, contentType) {
-    const authHeaders = await this.buildAuthHeaders("POST", path, void 0);
-    const res = await this.fetch(`${this.baseUrl}${path}`, {
+    const sendPath = this.applyNamespace(path);
+    const authHeaders = await this.buildAuthHeaders("POST", sendPath, void 0);
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
       method: "POST",
       headers: {
-        "Content-Type": contentType,
-        Accept: "application/json",
+        [HEADER_CONTENT_TYPE]: contentType,
+        [HEADER_ACCEPT]: "application/json",
         ...authHeaders
       },
       body: data
@@ -483,10 +958,56 @@ var StarfishClient = class {
     }
     return res.json();
   }
+  /**
+   * Push an Apache Parquet file to a Parquet collection.
+   *
+   * Thin wrapper over {@link pushBlob} that fixes `Content-Type` to
+   * `application/vnd.apache.parquet` so the S3 object is tagged correctly
+   * for DuckDB and CDN consumption.
+   *
+   * @example
+   * ```ts
+   * const parquetBytes = await generateParquet(rows)
+   * const result = await client.pushParquet("/push/analytics/alice/q1.parquet", parquetBytes)
+   * console.log("stored hash:", result.hash)
+   * ```
+   */
+  async pushParquet(path, data) {
+    return this.pushBlob(path, data, PARQUET_MIME_TYPE_VALUE);
+  }
+  /**
+   * Pull an Apache Parquet file from a Parquet collection.
+   *
+   * Thin wrapper over {@link pullBlob} for API symmetry with
+   * {@link pushParquet}.
+   *
+   * @example
+   * ```ts
+   * const result = await client.pullParquet("/pull/analytics/alice/q1.parquet")
+   * // result.data        → ArrayBuffer
+   * // result.contentType → "application/vnd.apache.parquet"
+   * ```
+   */
+  async pullParquet(path) {
+    const result = await this.pullBlob(path);
+    if (!PARQUET_MIME_TYPES_VALUE.includes(result.contentType)) {
+      throw new StarfishHttpError(
+        415,
+        `Expected a Parquet content-type, got: ${result.contentType}`
+      );
+    }
+    return result;
+  }
 };
 
 // src/sync.ts
-import { deepMerge, getBase64, stableStringify as stableStringify2 } from "@drakkar.software/starfish-protocol";
+import {
+  AUTHOR_PUBKEY_FIELD as AUTHOR_PUBKEY_FIELD2,
+  AUTHOR_SIGNATURE_FIELD as AUTHOR_SIGNATURE_FIELD2,
+  deepMerge,
+  docAuthorCanonicalInput,
+  getBase64
+} from "@drakkar.software/starfish-protocol";
 
 // src/validate.ts
 var ValidationError = class extends Error {
@@ -519,6 +1040,9 @@ var SyncManager = class {
   lastCheckpoint = 0;
   localData = {};
   aborted = false;
+  lastFromCache = false;
+  /** True once {@link seedFromCache} has successfully seeded localData from the cache. */
+  seeded = false;
   constructor(options) {
     this.client = options.client;
     this.pullPath = options.pullPath;
@@ -540,6 +1064,36 @@ var SyncManager = class {
   getData() {
     return { ...this.localData };
   }
+  /**
+   * Returns true when `pull()` / `ingest()` should merge against the current
+   * `localData` rather than replace it wholesale.
+   *
+   * Two situations establish a merge baseline:
+   * - A successful prior pull/ingest advanced `lastCheckpoint` beyond 0 (the
+   *   normal steady-state case, unchanged since alpha.36).
+   * - A cache seed painted `localData` via {@link seedFromCache} AND the store
+   *   uses a custom conflict resolver (i.e. NOT the default `deepMerge`). For a
+   *   union/custom resolver the seeded snapshot is a real baseline that must not
+   *   be clobbered by a short first live response (a cache-fallback on 429/5xx
+   *   or a momentarily-short concurrent server snapshot). For the default
+   *   `deepMerge` resolver we keep the pre-fix wholesale-replace behaviour so
+   *   non-union stores are byte-identical to alpha.36.
+   */
+  hasMergeBaseline() {
+    return this.lastCheckpoint > 0 || this.seeded && this.onConflict !== deepMerge;
+  }
+  /**
+   * Merge a remote snapshot with local (optimistic) data using this manager's
+   * conflict resolver — the same resolver the push-conflict path uses. A plain
+   * {@link pull} overwrites the store's data with the server snapshot, which
+   * would drop un-pushed local writes (they live only in the store, never in
+   * `localData` until a push succeeds). The zustand binding calls this on pull
+   * while the store is dirty so those writes survive. `local` wins by the same
+   * rules as a push conflict.
+   */
+  resolve(local, remote) {
+    return this.onConflict(local, remote);
+  }
   getHash() {
     return this.lastHash;
   }
@@ -547,9 +1101,95 @@ var SyncManager = class {
   setHash(hash) {
     this.lastHash = hash;
   }
+  /**
+   * Whether the most recent {@link pull} (or {@link seedFromCache}) was served
+   * from the client's offline read-through cache rather than a live server
+   * response. The binding surfaces this as a `stale` flag so the UI can show an
+   * offline indicator without treating a cache hit as "reachable". Reset to
+   * false by the next successful network pull.
+   */
+  getLastPullFromCache() {
+    return this.lastFromCache;
+  }
+  /**
+   * Cache-first paint: seed `localData` from the client's read-through cache
+   * WITHOUT touching the network, decrypting in memory for E2E collections.
+   * Returns whether anything was seeded (false on a miss, an expired entry, or
+   * a decrypt failure — e.g. keyring skew). Call once on store creation before
+   * the initial live {@link pull}.
+   *
+   * `lastCheckpoint` is intentionally left at 0 so the first live pull sends a
+   * full (re)sync request to the server, not a delta. However, for stores with
+   * a custom conflict resolver (e.g. `createUnionMerge`) the seeded snapshot is
+   * treated as a merge baseline: {@link hasMergeBaseline} returns true, so the
+   * first pull/ingest merges against the seed rather than replacing it wholesale.
+   * This closes the bootstrap window where a short first-pull response (a cache-
+   * fallback on 429/5xx or a momentarily-short concurrent snapshot) would
+   * silently drop items the resolver was configured to preserve. For the default
+   * `deepMerge` resolver the first pull still takes the snapshot wholesale —
+   * behaviour is byte-identical to alpha.36.
+   *
+   * Requires the client to have been built with a `cache`.
+   */
+  async seedFromCache() {
+    if (this.aborted) return false;
+    const cached = await this.client.peekCache(this.pullPath);
+    if (!cached) return false;
+    let data;
+    try {
+      data = this.encryptor ? await this.encryptor.decrypt(cached.data) : cached.data;
+    } catch {
+      return false;
+    }
+    if (this.aborted) return false;
+    this.localData = data;
+    this.lastHash = cached.hash;
+    this.seeded = true;
+    this.lastFromCache = true;
+    return true;
+  }
   getCheckpoint() {
     return this.lastCheckpoint;
   }
+  /**
+   * Apply a freshly-fetched `PullResult` to this manager's state WITHOUT
+   * firing a network request. Used by the zustand binding's `mergeResult`
+   * action to absorb a background revalidation result (delivered via
+   * {@link StarfishClientOptions.onRevalidated}) into the store.
+   *
+   * Like {@link pull}, `ingest` conflict-merges the snapshot against the
+   * established baseline via `this.onConflict` when a merge baseline exists
+   * ({@link hasMergeBaseline}) — so a union-merge store does not lose array
+   * items when a revalidation result (e.g. a stale cache-fallback on 429/5xx)
+   * is a shorter snapshot. The baseline is established by either a prior
+   * pull/ingest that advanced `lastCheckpoint`, or by a successful
+   * {@link seedFromCache} for a store with a custom resolver. The first ingest
+   * without such a baseline takes the snapshot wholesale (default `deepMerge`
+   * stores are byte-identical to alpha.36). Sets `lastFromCache = false` (a
+   * revalidation is a live response) so the binding can clear its `stale` flag.
+   *
+   * **Staleness guard**: if a `push()` advanced `lastCheckpoint` between the
+   * time the revalidation request was sent and the time it resolves, the
+   * result is from an older document version. Ingesting it would clobber the
+   * user's just-saved edit and reset `lastHash` to a stale server hash
+   * (causing a spurious 409 on the next push). We silently drop the result in
+   * that case — the store's post-push state is already correct.
+   */
+  async ingest(result) {
+    if (this.aborted) return;
+    if (result.timestamp < this.lastCheckpoint) return;
+    let incoming;
+    if (this.encryptor) {
+      incoming = await this.encryptor.decrypt(result.data);
+      if (this.aborted) return;
+    } else {
+      incoming = result.data;
+    }
+    this.localData = this.hasMergeBaseline() ? this.onConflict(this.localData, incoming) : incoming;
+    this.lastHash = result.hash;
+    this.lastCheckpoint = result.timestamp;
+    this.lastFromCache = false;
+  }
   async pull() {
     if (this.aborted) throw new AbortError();
     this.logger?.pullStart(this.loggerName);
@@ -557,17 +1197,16 @@ var SyncManager = class {
     try {
       const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
       if (this.aborted) throw new AbortError();
+      this.lastFromCache = pullWasFromCache(result);
+      let incoming;
       if (this.encryptor) {
-        const decrypted = await this.encryptor.decrypt(result.data);
+        incoming = await this.encryptor.decrypt(result.data);
         if (this.aborted) throw new AbortError();
-        this.localData = decrypted;
-        result.data = decrypted;
-      } else if (this.lastCheckpoint > 0) {
-        this.localData = deepMerge(this.localData, result.data);
-        result.data = this.localData;
       } else {
-        this.localData = result.data;
+        incoming = result.data;
       }
+      this.localData = this.hasMergeBaseline() ? this.onConflict(this.localData, incoming) : incoming;
+      result.data = this.localData;
       this.lastHash = result.hash;
       this.lastCheckpoint = result.timestamp;
       this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start));
@@ -591,23 +1230,24 @@ var SyncManager = class {
       try {
         const sealed = this.encryptor ? await this.encryptor.encrypt(pendingData) : pendingData;
         if (this.aborted) throw new AbortError();
-        let payload = sealed;
+        let author;
         if (this.signer) {
           const { devEdPubHex, sign } = await this.signer.getSigner();
           if (this.aborted) throw new AbortError();
-          const canonical = stableStringify2(sealed);
+          const documentKey = stripPushPrefix(this.pushPath);
+          const canonical = docAuthorCanonicalInput(documentKey, sealed);
           const sigBytes = await sign(new TextEncoder().encode(canonical));
           if (this.aborted) throw new AbortError();
-          payload = {
-            ...sealed,
-            authorPubkey: devEdPubHex,
-            authorSignature: getBase64().encode(sigBytes)
+          author = {
+            [AUTHOR_PUBKEY_FIELD2]: devEdPubHex,
+            [AUTHOR_SIGNATURE_FIELD2]: getBase64().encode(sigBytes)
           };
         }
         const result = await this.client.push(
           this.pushPath,
-          payload,
-          this.lastHash
+          sealed,
+          this.lastHash,
+          author
         );
         if (this.aborted) throw new AbortError();
         this.lastHash = result.hash;
@@ -722,6 +1362,38 @@ function createStarfishStore(options) {
   const { name, syncManager, storage } = options;
   const storeCreator = (rawSet, get) => {
     const set = rawSet;
+    let retryTimer;
+    let retryAttempt = 0;
+    const scheduleFlushRetry = () => {
+      const retryOpts = options.flushRetry;
+      if (!retryOpts) return;
+      const maxRetries = retryOpts.maxRetries ?? 5;
+      if (retryAttempt >= maxRetries) return;
+      const initialMs = retryOpts.initialDelayMs ?? 500;
+      const maxMs = retryOpts.maxDelayMs ?? 3e4;
+      const delayMs = Math.min(initialMs * Math.pow(2, retryAttempt), maxMs) + Math.random() * 100;
+      retryAttempt++;
+      clearTimeout(retryTimer);
+      retryTimer = setTimeout(() => {
+        if (get().dirty && get().online && !get().syncing) {
+          get().flush().catch(() => {
+          });
+        }
+      }, delayMs);
+    };
+    const cancelFlushRetry = () => {
+      clearTimeout(retryTimer);
+      retryTimer = void 0;
+      retryAttempt = 0;
+    };
+    const commitRemote = (label) => {
+      const remote = syncManager.getData();
+      const newData = get().dirty ? syncManager.resolve(get().data, remote) : remote;
+      set({ data: newData, syncing: false, hash: syncManager.getHash(), stale: syncManager.getLastPullFromCache() }, false, label);
+      if (get().online && get().dirty) get().flush().catch(() => {
+      });
+      options.onRemoteUpdate?.(newData);
+    };
     return {
       data: {},
       syncing: false,
@@ -729,20 +1401,38 @@ function createStarfishStore(options) {
       dirty: false,
       error: null,
       hash: null,
+      stale: false,
+      seed: async () => {
+        try {
+          const seeded = await syncManager.seedFromCache();
+          if (!seeded) return;
+          if (get().dirty || Object.keys(get().data).length > 0) return;
+          set({ data: syncManager.getData(), hash: syncManager.getHash(), stale: true }, false, "seed");
+        } catch {
+        }
+      },
       pull: async () => {
-        set({ syncing: true, error: null }, false, "pull/start");
+        set(get().stale ? { error: null } : { syncing: true, error: null }, false, "pull/start");
         try {
           await syncManager.pull();
-          const newData = syncManager.getData();
-          set({ data: newData, syncing: false, hash: syncManager.getHash() }, false, "pull/success");
-          options.onRemoteUpdate?.(newData);
+          commitRemote("pull/success");
         } catch (err) {
+          if (classifyError(err) === "network") {
+            set({ syncing: false, stale: true }, false, "pull/offline");
+            return;
+          }
           set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
         }
       },
+      mergeResult: async (result) => {
+        await syncManager.ingest(result);
+        commitRemote("merge/success");
+      },
       set: (modifier) => {
         try {
           const next = options.produce ? options.produce(get().data, modifier) : modifier(get().data);
+          retryAttempt = 0;
+          clearTimeout(retryTimer);
           set({ data: next, dirty: true, error: null }, false, "set");
           if (get().online) get().flush().catch(() => {
           });
@@ -758,15 +1448,22 @@ function createStarfishStore(options) {
         set({ syncing: true, error: null }, false, "flush/start");
         try {
           await syncManager.push(get().data);
-          set({ data: syncManager.getData(), syncing: false, dirty: false, hash: syncManager.getHash() }, false, "flush/success");
+          cancelFlushRetry();
+          set({ data: syncManager.getData(), syncing: false, dirty: false, hash: syncManager.getHash(), stale: false }, false, "flush/success");
         } catch (err) {
+          const isAbort = err instanceof Error && (err.name === "AbortError" || typeof DOMException !== "undefined" && err instanceof DOMException && err.name === "AbortError");
           set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "flush/error");
+          if (!isAbort) scheduleFlushRetry();
         }
       },
       setOnline: (online) => {
         set({ online }, false, "setOnline");
-        if (online && get().dirty) get().flush().catch(() => {
-        });
+        if (online && get().dirty) {
+          get().flush().catch(() => {
+          });
+        } else if (!online) {
+          cancelFlushRetry();
+        }
       }
     };
   };
@@ -804,6 +1501,9 @@ function aggregateSyncStatus(statuses) {
 function useStarfish(store) {
   return useStore(store);
 }
+function useStarfishState(store, selector) {
+  return useStore(store, selector);
+}
 function useStarfishData(store, selector) {
   return useStore(
     store,
@@ -864,7 +1564,7 @@ function useLastSynced(store) {
   }, [store, computeLabel]);
   useEffect(() => {
     const timer = setInterval(() => {
-      setLabel(computeLabel());
+      if (!document.hidden) setLabel(computeLabel());
     }, 5e3);
     return () => clearInterval(timer);
   }, [computeLabel]);
@@ -875,14 +1575,24 @@ function useSyncInit(config) {
   const onDataRef = useRef(config?.onData);
   onDataRef.current = config?.onData;
   useEffect(() => {
-    if (!config) {
-      setStore(null);
-      return;
-    }
+    if (!config) return;
     const client = new StarfishClient({
       baseUrl: config.serverUrl,
+      namespace: config.namespace,
       capProvider: config.capProvider,
-      fetch: config.fetch
+      fetch: config.fetch,
+      cache: config.cache,
+      cacheMaxAgeMs: config.cacheMaxAgeMs,
+      cacheFallbackStatuses: config.cacheFallbackStatuses,
+      // Auto-merge: when a background revalidation delivers a fresh snapshot,
+      // push it into the store so the UI heals without waiting for the next pull.
+      // newStore is referenced by closure — safe because onRevalidated only fires
+      // asynchronously, well after the store is created below.
+      onRevalidated: (path, result) => {
+        newStore.getState().mergeResult(result).catch(() => {
+        });
+        config.onRevalidated?.(path, result);
+      }
     });
     const syncManager = new SyncManager({
       client,
@@ -910,7 +1620,9 @@ function useSyncInit(config) {
       }
     });
     setStore(newStore);
-    newStore.getState().pull().catch(() => {
+    newStore.getState().seed().finally(() => {
+      newStore.getState().pull().catch(() => {
+      });
     });
     return () => {
       setStore(null);
@@ -922,18 +1634,182 @@ function useSyncInit(config) {
     config?.encryptor,
     config?.storeName
   ]);
+  return config ? store : null;
+}
+var _syncStoreRegistry = /* @__PURE__ */ new Map();
+function acquireSyncStore(config) {
+  const existing = _syncStoreRegistry.get(config.storeName);
+  if (existing) {
+    existing.refCount += 1;
+    return existing.store;
+  }
+  const client = new StarfishClient({
+    baseUrl: config.serverUrl,
+    namespace: config.namespace,
+    capProvider: config.capProvider,
+    fetch: config.fetch,
+    cache: config.cache,
+    cacheMaxAgeMs: config.cacheMaxAgeMs,
+    cacheFallbackStatuses: config.cacheFallbackStatuses,
+    // Auto-merge: push fresh revalidated snapshots into the store.
+    // store is referenced by closure — safe because onRevalidated only fires
+    // asynchronously, well after the store is created below.
+    onRevalidated: (path, result) => {
+      store.getState().mergeResult(result).catch(() => {
+      });
+      config.onRevalidated?.(path, result);
+    }
+  });
+  const syncManager = new SyncManager({
+    client,
+    pullPath: config.pullPath,
+    pushPath: config.pushPath,
+    encryptor: config.encryptor,
+    onConflict: config.onConflict,
+    logger: config.logger,
+    validate: config.validate
+  });
+  const store = createStarfishStore({
+    name: config.storeName,
+    syncManager,
+    storage: config.storage
+    // No onRemoteUpdate: consumers subscribe via store.subscribe() — see module comment.
+  });
+  const entry = { store, refCount: 1 };
+  _syncStoreRegistry.set(config.storeName, entry);
+  store.getState().seed().finally(() => {
+    if (_syncStoreRegistry.get(config.storeName) === entry) {
+      store.getState().pull().catch(() => {
+      });
+    }
+  });
   return store;
 }
+function releaseSyncStore(storeName) {
+  const entry = _syncStoreRegistry.get(storeName);
+  if (!entry) return;
+  entry.refCount -= 1;
+  if (entry.refCount <= 0) _syncStoreRegistry.delete(storeName);
+}
+function clearSyncStoreRegistry() {
+  _syncStoreRegistry.clear();
+}
+function useSharedSyncStore(config) {
+  const [store, setStore] = useState(null);
+  const storeName = config?.storeName ?? null;
+  const configRef = useRef(config);
+  configRef.current = config;
+  useEffect(() => {
+    if (!storeName) return;
+    const acquired = acquireSyncStore(configRef.current);
+    setStore(acquired);
+    return () => {
+      releaseSyncStore(storeName);
+      setStore(null);
+    };
+  }, [storeName]);
+  return storeName ? store : null;
+}
+function createStarfishLog(options) {
+  const { cursor } = options;
+  const storeCreator = (rawSet, get) => {
+    const set = rawSet;
+    return {
+      // 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(),
+      pull: async () => {
+        if (get().loading) return [];
+        set({ loading: true, error: null }, false, "log/pull/start");
+        try {
+          const batch = await cursor.pull();
+          set(
+            { items: cursor.getItems(), checkpoint: cursor.getCheckpoint(), loading: false },
+            false,
+            "log/pull/success"
+          );
+          return batch;
+        } catch (err) {
+          set({ loading: false, error: err instanceof Error ? err.message : String(err) }, false, "log/pull/error");
+          return [];
+        }
+      },
+      setOnline: (online) => {
+        set({ online }, false, "log/setOnline");
+      }
+    };
+  };
+  const withSelector = subscribeWithSelector(storeCreator);
+  return createStore()(
+    options.devtools ? options.devtools(withSelector) : withSelector
+  );
+}
+function deriveLogStatus(state) {
+  if (!state.online) return "offline";
+  if (state.error) return "error";
+  if (state.loading) return "loading";
+  return "idle";
+}
+function useStarfishLog(store) {
+  return useStore(store);
+}
+function useStarfishLogItems(store, selector) {
+  return useStore(
+    store,
+    (state) => selector ? selector(state.items) : state.items
+  );
+}
+function useLogStatus(store) {
+  return useStore(store, deriveLogStatus);
+}
+function subscribeLogStatus(store, callback) {
+  let prev = deriveLogStatus(store.getState());
+  callback(prev);
+  return store.subscribe((state) => {
+    const next = deriveLogStatus(state);
+    if (next !== prev) {
+      prev = next;
+      callback(next);
+    }
+  });
+}
+function useLogConnectivity(store) {
+  useEffect(() => {
+    const handleOnline = () => store.getState().setOnline(true);
+    const handleOffline = () => store.getState().setOnline(false);
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+    };
+  }, [store]);
+}
 export {
+  acquireSyncStore,
   aggregateSyncStatus,
+  clearSyncStoreRegistry,
+  createStarfishLog,
   createStarfishStore,
+  deriveLogStatus,
   deriveSyncStatus,
+  releaseSyncStore,
+  subscribeLogStatus,
   subscribeSyncStatus,
   useConnectivity,
   useCrossTabSync,
   useLastSynced,
+  useLogConnectivity,
+  useLogStatus,
+  useSharedSyncStore,
   useStarfish,
   useStarfishData,
+  useStarfishLog,
+  useStarfishLogItems,
+  useStarfishState,
   useSyncInit,
   useSyncStatus
 };