@drakkar.software/starfish-client 1.5.0 → 1.7.0

package/dist/bindings/zustand.d.ts

@@ -30,6 +30,26 @@ export interface CreateStarfishStoreOptions {
     devtools?: boolean | DevtoolsOptions;
     /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */
     produce?: <T>(base: T, recipe: (draft: T) => T | void) => T;
+    /**
+     * Called when remote data arrives via `pull()` — **not** called for local `set()` writes.
+     *
+     * Use this to restore domain stores after a pull without worrying about feedback loops.
+     * The callback fires **after** the Starfish store state is updated, so the store already
+     * reflects the new data when this runs.
+     *
+     * Replaces the manual `isRestoring` flag pattern:
+     * ```ts
+     * createStarfishStore({
+     *   name: "app",
+     *   syncManager,
+     *   onRemoteUpdate: (data) => {
+     *     taskStore.setState({ tasks: data.tasks as Task[] })
+     *     settingsStore.setState({ settings: data.settings as Settings })
+     *   },
+     * })
+     * ```
+     */
+    onRemoteUpdate?: (data: Record<string, unknown>) => void;
 }
 export type { DevtoolsOptions };
 export declare function createStarfishStore(options: CreateStarfishStoreOptions): StoreApi<StarfishStore>;
@@ -48,6 +68,22 @@ export declare function useStarfish(store: StoreApi<StarfishStore>): StarfishSto
 export declare function useStarfishData<T = Record<string, unknown>>(store: StoreApi<StarfishStore>, selector?: (data: Record<string, unknown>) => T): T;
 /** Use the derived sync status (synced | syncing | pending | error | offline). */
 export declare function useSyncStatus(store: StoreApi<StarfishStore>): SyncStatus;
+/**
+ * Subscribe to sync status changes outside of React.
+ *
+ * Framework-agnostic — works in React Native, Node.js, or anywhere hooks are unavailable.
+ * The callback is invoked immediately with the current status and then on every change.
+ *
+ * ```ts
+ * const unsub = subscribeSyncStatus(store, (status) => {
+ *   updateStatusBar(status)
+ * })
+ *
+ * // Later, to stop listening:
+ * unsub()
+ * ```
+ */
+export declare function subscribeSyncStatus(store: StoreApi<StarfishStore>, callback: (status: SyncStatus) => void): () => void;
 /** Sets up cross-tab sync for a Starfish store. Cleans up on unmount. */
 export declare function useCrossTabSync(store: StoreApi<StarfishStore>, name: string): void;
 /** Binds browser online/offline events to the store's setOnline action. Cleans up on unmount. */

package/dist/bindings/zustand.js

@@ -19,7 +19,11 @@ export function createStarfishStore(options) {
                 set({ syncing: true, error: null }, false, "pull/start");
                 try {
                     await syncManager.pull();
-                    set({ data: syncManager.getData(), syncing: false }, false, "pull/success");
+                    const newData = syncManager.getData();
+                    set({ data: newData, syncing: false }, false, "pull/success");
+                    // Fire after state update so domain stores can read the updated Starfish state if needed.
+                    // Calling set() inside onRemoteUpdate does NOT re-enter pull(), so no feedback loop.
+                    options.onRemoteUpdate?.(newData);
                 }
                 catch (err) {
                     set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
@@ -118,6 +122,32 @@ export function useStarfishData(store, selector) {
 export function useSyncStatus(store) {
     return useStore(store, deriveSyncStatus);
 }
+/**
+ * Subscribe to sync status changes outside of React.
+ *
+ * Framework-agnostic — works in React Native, Node.js, or anywhere hooks are unavailable.
+ * The callback is invoked immediately with the current status and then on every change.
+ *
+ * ```ts
+ * const unsub = subscribeSyncStatus(store, (status) => {
+ *   updateStatusBar(status)
+ * })
+ *
+ * // Later, to stop listening:
+ * unsub()
+ * ```
+ */
+export function subscribeSyncStatus(store, callback) {
+    let prev = deriveSyncStatus(store.getState());
+    callback(prev);
+    return store.subscribe((state) => {
+        const next = deriveSyncStatus(state);
+        if (next !== prev) {
+            prev = next;
+            callback(next);
+        }
+    });
+}
 /** Sets up cross-tab sync for a Starfish store. Cleans up on unmount. */
 export function useCrossTabSync(store, name) {
     useEffect(() => {
@@ -209,15 +239,9 @@ export function useSyncInit(config) {
             name: config.storeName ?? "sync",
             syncManager,
             storage: config.storage,
-        });
-        // Subscribe to data changes from pulls (not local sets)
-        let lastDataRef = newStore.getState().data;
-        const unsub = newStore.subscribe((state) => {
-            const data = state.data;
-            // Only call onData when data changes and store is not dirty
-            // (dirty = false means data came from a pull, not a local set)
-            if (data !== lastDataRef && !state.dirty) {
-                lastDataRef = data;
+            // onRemoteUpdate fires only for pull() results, never for local set() writes —
+            // so no isRestoring flag is needed.
+            onRemoteUpdate: (data) => {
                 try {
                     onDataRef.current?.(data);
                 }
@@ -226,16 +250,12 @@ export function useSyncInit(config) {
                         error: `onData failed: ${err instanceof Error ? err.message : String(err)}`,
                     });
                 }
-            }
-            else {
-                lastDataRef = data;
-            }
+            },
         });
         setStore(newStore);
         // Initial pull — errors are stored in state.error by the pull() action
         newStore.getState().pull().catch(() => { });
         return () => {
-            unsub();
             setStore(null);
         };
         // Intentionally depend on serializable config values, not the object reference

package/dist/debounced-sync.d.ts

@@ -0,0 +1,131 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { StarfishStore } from "./bindings/zustand.js";
+import type { SyncManager } from "./sync.js";
+export interface DebouncedSyncOptions {
+    /**
+     * How long to wait after the last `notify()` call before pushing (default: 2000 ms).
+     * Shorter values reduce latency; longer values batch more edits into a single push.
+     */
+    delayMs?: number;
+    /**
+     * Emit a warning when the estimated encrypted payload exceeds this byte count (default: 900 KB).
+     * The estimate multiplies the JSON size by 1.34 (base64 overhead for encrypted blobs).
+     * Set to `Infinity` to disable.
+     */
+    warnBytes?: number;
+    /**
+     * Block the push when the estimated encrypted payload exceeds this byte count (default: 1 MB).
+     * Prevents cryptic 413 errors from the server. Set to `Infinity` to disable.
+     */
+    maxBytes?: number;
+    /**
+     * Serialize store data to a sync document before pushing.
+     * Called inside the debounce timer, so it always captures the latest state.
+     * If omitted, `store.getState().data` is used as-is.
+     */
+    serialize?: (currentData: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Called when the estimated payload size exceeds `warnBytes` but is still below `maxBytes`.
+     * Use to show a warning in the UI.
+     */
+    onSizeWarning?: (estimatedBytes: number) => void;
+    /**
+     * Called when the estimated payload size exceeds `maxBytes`.
+     * The push is blocked. Use to alert the user that data needs to be pruned.
+     * If omitted, a console error is printed.
+     */
+    onSizeExceeded?: (estimatedBytes: number) => void;
+}
+export interface DebouncedSync {
+    /**
+     * Schedule a push. If called again within `delayMs`, the timer resets.
+     * Safe to call on every domain store mutation.
+     */
+    notify: () => void;
+    /** Cancel any pending debounced push. Does not affect an already-in-flight push. */
+    cancel: () => void;
+}
+export interface DebouncedPushOptions {
+    /**
+     * How long to wait after the last `notify()` call before pushing (default: 2000 ms).
+     */
+    delayMs?: number;
+    /**
+     * Required: provides the document to push when the debounce timer fires.
+     * Called inside the timer so it always captures the latest state.
+     */
+    serialize: () => Record<string, unknown>;
+    /**
+     * Emit a warning when the estimated encrypted payload exceeds this byte count (default: 900 KB).
+     * Set to `Infinity` to disable.
+     */
+    warnBytes?: number;
+    /**
+     * Block the push when the estimated encrypted payload exceeds this byte count (default: 1 MB).
+     * Set to `Infinity` to disable.
+     */
+    maxBytes?: number;
+    /**
+     * Called when the estimated payload size exceeds `warnBytes` but is below `maxBytes`.
+     */
+    onSizeWarning?: (estimatedBytes: number) => void;
+    /**
+     * Called when the estimated payload size exceeds `maxBytes`. The push is blocked.
+     * If omitted, a console error is printed.
+     */
+    onSizeExceeded?: (estimatedBytes: number) => void;
+    /**
+     * Called when `syncManager.push()` throws. Default: `console.warn`.
+     */
+    onError?: (err: unknown) => void;
+}
+export interface DebouncedPush {
+    /**
+     * Schedule a push. If called again within `delayMs`, the timer resets.
+     */
+    notify: () => void;
+    /** Cancel any pending debounced push. Does not affect an already-in-flight push. */
+    cancel: () => void;
+}
+/**
+ * Creates a debounced push helper that coalesces rapid mutations into a single sync.
+ *
+ * Designed to be called on every domain store mutation (e.g., every keystroke).
+ * The push is delayed by `delayMs` after the **last** call, so typing quickly
+ * results in one push, not one per character.
+ *
+ * Also estimates the encrypted payload size before pushing and warns / blocks
+ * if it approaches the server's body size limit.
+ *
+ * ```ts
+ * const { notify } = createDebouncedSync(starfishStore, {
+ *   serialize: () => ({ tasks: taskStore.getState().tasks }),
+ * })
+ *
+ * // Call on every domain store mutation:
+ * taskStore.subscribe(() => notify())
+ * ```
+ */
+export declare function createDebouncedSync(store: StoreApi<StarfishStore>, options?: DebouncedSyncOptions): DebouncedSync;
+/**
+ * Creates a debounced push helper that calls `syncManager.push()` directly,
+ * without requiring a Zustand store.
+ *
+ * Use this for one-way publishing workflows: public pages, derived snapshots,
+ * or any case where you want to push data without a full `createStarfishStore` setup.
+ *
+ * ```ts
+ * const syncManager = new SyncManager({ client, pullPath, pushPath })
+ *
+ * const { notify, cancel } = createDebouncedPush(syncManager, {
+ *   serialize: () => buildPublicPageDocument(),
+ * })
+ *
+ * // Push after every relevant store mutation:
+ * planningStore.subscribe(() => notify())
+ *
+ * // Clean up on teardown:
+ * cancel()
+ * ```
+ */
+export declare function createDebouncedPush(syncManager: SyncManager, options: DebouncedPushOptions): DebouncedPush;

package/dist/debounced-sync.js

@@ -0,0 +1,120 @@
+// ── Implementation ────────────────────────────────────────────────────────────
+const DEFAULT_DELAY_MS = 2000;
+const DEFAULT_WARN_BYTES = 900 * 1024; // 900 KB
+const DEFAULT_MAX_BYTES = 1024 * 1024; // 1 MB
+/** Returns true if the push should be blocked. */
+function checkPayloadSize(doc, opts) {
+    // Estimate encrypted payload size. AES-GCM output is similar to input size;
+    // base64 encoding adds ~33% overhead, plus a small IV/tag overhead.
+    const estimatedBytes = Math.ceil(JSON.stringify(doc).length * 1.34);
+    if (estimatedBytes > opts.maxBytes) {
+        if (opts.onSizeExceeded) {
+            opts.onSizeExceeded(estimatedBytes);
+        }
+        else {
+            console.error(`[starfish] Push blocked: estimated payload ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                `exceeds limit of ${(opts.maxBytes / 1024).toFixed(0)} KB. Prune your data before syncing.`);
+        }
+        return true;
+    }
+    if (estimatedBytes > opts.warnBytes) {
+        if (opts.onSizeWarning) {
+            opts.onSizeWarning(estimatedBytes);
+        }
+        else {
+            console.warn(`[starfish] Payload approaching limit: estimated ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                `(warn threshold: ${(opts.warnBytes / 1024).toFixed(0)} KB).`);
+        }
+    }
+    return false;
+}
+/**
+ * Creates a debounced push helper that coalesces rapid mutations into a single sync.
+ *
+ * Designed to be called on every domain store mutation (e.g., every keystroke).
+ * The push is delayed by `delayMs` after the **last** call, so typing quickly
+ * results in one push, not one per character.
+ *
+ * Also estimates the encrypted payload size before pushing and warns / blocks
+ * if it approaches the server's body size limit.
+ *
+ * ```ts
+ * const { notify } = createDebouncedSync(starfishStore, {
+ *   serialize: () => ({ tasks: taskStore.getState().tasks }),
+ * })
+ *
+ * // Call on every domain store mutation:
+ * taskStore.subscribe(() => notify())
+ * ```
+ */
+export function createDebouncedSync(store, options = {}) {
+    const { delayMs = DEFAULT_DELAY_MS, warnBytes = DEFAULT_WARN_BYTES, maxBytes = DEFAULT_MAX_BYTES, serialize, onSizeWarning, onSizeExceeded, } = options;
+    let timer = null;
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function notify() {
+        cancel();
+        timer = setTimeout(() => {
+            timer = null;
+            const current = store.getState().data;
+            const doc = serialize ? serialize(current) : current;
+            if (checkPayloadSize(doc, { warnBytes, maxBytes, onSizeWarning, onSizeExceeded }))
+                return;
+            store.getState().set(() => doc);
+        }, delayMs);
+    }
+    return { notify, cancel };
+}
+/**
+ * Creates a debounced push helper that calls `syncManager.push()` directly,
+ * without requiring a Zustand store.
+ *
+ * Use this for one-way publishing workflows: public pages, derived snapshots,
+ * or any case where you want to push data without a full `createStarfishStore` setup.
+ *
+ * ```ts
+ * const syncManager = new SyncManager({ client, pullPath, pushPath })
+ *
+ * const { notify, cancel } = createDebouncedPush(syncManager, {
+ *   serialize: () => buildPublicPageDocument(),
+ * })
+ *
+ * // Push after every relevant store mutation:
+ * planningStore.subscribe(() => notify())
+ *
+ * // Clean up on teardown:
+ * cancel()
+ * ```
+ */
+export function createDebouncedPush(syncManager, options) {
+    const { delayMs = DEFAULT_DELAY_MS, warnBytes = DEFAULT_WARN_BYTES, maxBytes = DEFAULT_MAX_BYTES, serialize, onSizeWarning, onSizeExceeded, onError, } = options;
+    let timer = null;
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function notify() {
+        cancel();
+        timer = setTimeout(() => {
+            timer = null;
+            const doc = serialize();
+            if (checkPayloadSize(doc, { warnBytes, maxBytes, onSizeWarning, onSizeExceeded }))
+                return;
+            syncManager.push(doc).catch((err) => {
+                if (onError) {
+                    onError(err);
+                }
+                else {
+                    console.warn("[starfish] Push failed:", err);
+                }
+            });
+        }, delayMs);
+    }
+    return { notify, cancel };
+}

package/dist/identity.d.ts

@@ -0,0 +1,72 @@
+declare const WORDLIST: string[];
+/** Credentials derived from a passphrase. Pass directly to SyncManager / StarfishClient. */
+export interface DerivedCredentials {
+    /** Hex-encoded auth token. Use as `Bearer ${authToken}` in request headers. */
+    authToken: string;
+    /**
+     * Short identifier derived from the auth token (first 16 hex chars = 8 bytes).
+     * Used as the user/namespace segment in collection paths.
+     */
+    userId: string;
+    /**
+     * Hex-encoded key suitable as `encryptionSecret` for SyncManager.
+     * Combined with `encryptionSalt` to derive the AES-256-GCM key via HKDF.
+     */
+    encryptionSecret: string;
+    /**
+     * Value suitable as `encryptionSalt` for SyncManager. Equals `userId`.
+     * Using a per-identity salt ensures that even if two users share a passphrase,
+     * their encryption keys are different.
+     */
+    encryptionSalt: string;
+}
+/**
+ * Generates a cryptographically random passphrase from the built-in 256-word list.
+ *
+ * Each word represents one byte of entropy (256 words = one byte per word, zero modulo bias).
+ * A 12-word passphrase gives 96 bits of entropy — stronger than a random UUID.
+ *
+ * @param wordCount Number of words (default: 12).
+ * @param wordlist Custom word list (must have exactly 256 entries).
+ */
+export declare function generatePassphrase(wordCount?: number, wordlist?: string[]): string;
+/**
+ * Derives auth credentials from a passphrase.
+ *
+ * All derivations are deterministic — the same passphrase always produces the same credentials.
+ * Sharing the passphrase grants access on any device.
+ *
+ * The returned values map directly to Starfish options:
+ * ```ts
+ * const creds = await deriveCredentials(passphrase)
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: serverUrl,
+ *   auth: () => ({ Authorization: `Bearer ${creds.authToken}` }),
+ * })
+ * const syncManager = new SyncManager({
+ *   client,
+ *   pullPath: `/pull/${creds.userId}/wedding`,
+ *   pushPath: `/push/${creds.userId}/wedding`,
+ *   encryptionSecret: creds.encryptionSecret,
+ *   encryptionSalt: creds.encryptionSalt,
+ * })
+ * ```
+ */
+export declare function deriveCredentials(passphrase: string): Promise<DerivedCredentials>;
+/**
+ * Encodes an invite payload as a URL-safe token and appends it as `?t=<token>`.
+ *
+ * ```ts
+ * const url = buildInviteUrl("myapp://join", { name: "Alice & Bob", p: passphrase })
+ * // → "myapp://join?t=eyJuYW1lIjoiQWxpY2UgJiBCb2IifQ"
+ * ```
+ */
+export declare function buildInviteUrl(baseUrl: string, payload: Record<string, unknown>): string;
+/**
+ * Decodes an invite URL produced by `buildInviteUrl`.
+ *
+ * Returns the decoded payload, or `null` if the URL is missing or malformed.
+ */
+export declare function parseInviteUrl(url: string): Record<string, unknown> | null;
+export { WORDLIST as DEFAULT_WORDLIST };

package/dist/identity.js

@@ -0,0 +1,161 @@
+import { getCrypto, getBase64 } from "@drakkar.software/starfish-protocol";
+// ── Word list ─────────────────────────────────────────────────────────────────
+// 256 common English words, one per index (0-255). One byte of entropy per word.
+// 12 words = 96 bits of entropy (stronger than a random UUID).
+const WORDLIST = [
+    "able", "acid", "aged", "also", "area", "army", "away", "back",
+    "ball", "band", "bank", "base", "bath", "bean", "bear", "beat",
+    "bell", "best", "bird", "blue", "boat", "bold", "bolt", "bone",
+    "born", "bowl", "burn", "calm", "call", "camp", "card", "care",
+    "cash", "cast", "cave", "city", "clam", "clay", "clip", "coal",
+    "coat", "coin", "cold", "cook", "cool", "corn", "cost", "cozy",
+    "dark", "data", "dawn", "dead", "deal", "deck", "deep", "dew",
+    "dish", "dome", "door", "down", "draw", "drop", "drum", "dusk",
+    "dust", "each", "earn", "east", "edge", "even", "ever", "face",
+    "fact", "fair", "fall", "fame", "farm", "fast", "felt", "file",
+    "fill", "fire", "fish", "fist", "flag", "flat", "flew", "flow",
+    "foam", "fold", "fond", "food", "foot", "form", "frog", "fuel",
+    "full", "gain", "game", "gate", "gave", "gaze", "gift", "glad",
+    "glow", "glue", "goal", "good", "grab", "gray", "grip", "grow",
+    "gulf", "gust", "half", "hall", "hand", "hard", "harm", "have",
+    "hawk", "head", "heal", "heap", "heat", "held", "helm", "help",
+    "herb", "here", "hero", "high", "hill", "hint", "hold", "hole",
+    "home", "hope", "horn", "hour", "huge", "hunt", "idea", "inch",
+    "into", "iris", "isle", "jade", "jail", "join", "jump", "just",
+    "keep", "kind", "king", "knot", "know", "lack", "lake", "land",
+    "lane", "last", "late", "lawn", "lead", "leaf", "lean", "leap",
+    "left", "lend", "less", "life", "lift", "like", "lime", "line",
+    "lion", "list", "live", "load", "lock", "loft", "long", "look",
+    "loop", "loud", "love", "luck", "lung", "made", "main", "mark",
+    "mast", "math", "maze", "meal", "meet", "melt", "mild", "mind",
+    "mint", "mist", "mode", "moon", "more", "most", "move", "much",
+    "must", "name", "near", "neck", "need", "next", "nice", "nine",
+    "none", "noon", "note", "noun", "oath", "once", "open", "oval",
+    "over", "pack", "page", "paid", "pain", "pale", "palm", "park",
+    "part", "path", "pave", "peak", "pier", "pile", "pine", "pipe",
+    "plan", "plum", "poem", "pole", "pool", "port", "pose", "post",
+    "pray", "prey", "pull", "pure", "push", "quit", "race", "rack",
+];
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sha256Hex(input) {
+    const c = getCrypto();
+    const encoded = new TextEncoder().encode(input);
+    const hash = await c.subtle.digest("SHA-256", encoded);
+    return bytesToHex(new Uint8Array(hash));
+}
+// URL-safe base64 (RFC 4648 §5): replaces + → -, / → _, strips trailing =
+function base64UrlEncode(data) {
+    const b64 = getBase64();
+    return b64
+        .encode(data)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function base64UrlDecode(encoded) {
+    const b64 = getBase64();
+    // Restore standard base64 padding
+    const padded = encoded.replace(/-/g, "+").replace(/_/g, "/");
+    const rem = padded.length % 4;
+    const padded2 = rem === 0 ? padded : padded + "=".repeat(4 - rem);
+    return b64.decode(padded2);
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Generates a cryptographically random passphrase from the built-in 256-word list.
+ *
+ * Each word represents one byte of entropy (256 words = one byte per word, zero modulo bias).
+ * A 12-word passphrase gives 96 bits of entropy — stronger than a random UUID.
+ *
+ * @param wordCount Number of words (default: 12).
+ * @param wordlist Custom word list (must have exactly 256 entries).
+ */
+export function generatePassphrase(wordCount = 12, wordlist = WORDLIST) {
+    if (wordlist.length !== 256) {
+        throw new Error(`Word list must have exactly 256 entries, got ${wordlist.length}`);
+    }
+    const c = getCrypto();
+    const bytes = c.getRandomValues(new Uint8Array(wordCount));
+    return Array.from(bytes, (b) => wordlist[b]).join(" ");
+}
+/**
+ * Derives auth credentials from a passphrase.
+ *
+ * All derivations are deterministic — the same passphrase always produces the same credentials.
+ * Sharing the passphrase grants access on any device.
+ *
+ * The returned values map directly to Starfish options:
+ * ```ts
+ * const creds = await deriveCredentials(passphrase)
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: serverUrl,
+ *   auth: () => ({ Authorization: `Bearer ${creds.authToken}` }),
+ * })
+ * const syncManager = new SyncManager({
+ *   client,
+ *   pullPath: `/pull/${creds.userId}/wedding`,
+ *   pushPath: `/push/${creds.userId}/wedding`,
+ *   encryptionSecret: creds.encryptionSecret,
+ *   encryptionSalt: creds.encryptionSalt,
+ * })
+ * ```
+ */
+export async function deriveCredentials(passphrase) {
+    if (!passphrase.trim())
+        throw new Error("Passphrase must not be empty");
+    // authToken = SHA-256(passphrase) — used as Bearer token
+    const authToken = await sha256Hex(passphrase);
+    // userId = first 16 hex chars of authToken (8 bytes)
+    const userId = authToken.slice(0, 16);
+    // encryptionSecret = SHA-256(passphrase + ":" + userId)
+    // Domain separation from authToken ensures they cannot be recovered from each other.
+    const encryptionSecret = await sha256Hex(`${passphrase}:${userId}`);
+    return {
+        authToken,
+        userId,
+        encryptionSecret,
+        encryptionSalt: userId,
+    };
+}
+/**
+ * Encodes an invite payload as a URL-safe token and appends it as `?t=<token>`.
+ *
+ * ```ts
+ * const url = buildInviteUrl("myapp://join", { name: "Alice & Bob", p: passphrase })
+ * // → "myapp://join?t=eyJuYW1lIjoiQWxpY2UgJiBCb2IifQ"
+ * ```
+ */
+export function buildInviteUrl(baseUrl, payload) {
+    const json = JSON.stringify(payload);
+    const bytes = new TextEncoder().encode(json);
+    const token = base64UrlEncode(bytes);
+    const separator = baseUrl.includes("?") ? "&" : "?";
+    return `${baseUrl}${separator}t=${token}`;
+}
+/**
+ * Decodes an invite URL produced by `buildInviteUrl`.
+ *
+ * Returns the decoded payload, or `null` if the URL is missing or malformed.
+ */
+export function parseInviteUrl(url) {
+    try {
+        const tokenMatch = url.match(/[?&]t=([^&]+)/);
+        if (!tokenMatch?.[1])
+            return null;
+        const bytes = base64UrlDecode(tokenMatch[1]);
+        const json = new TextDecoder().decode(bytes);
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// Export word list for consumers that want to provide localized alternatives
+export { WORDLIST as DEFAULT_WORDLIST };

package/dist/index.d.ts

@@ -34,3 +34,9 @@ export type { BackgroundSyncOptions } from "./background-sync.js";
 export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
 export type { ServiceWorkerOptions } from "./service-worker.js";
 export { createSuspenseResource } from "./bindings/suspense.js";
+export { createDebouncedSync, createDebouncedPush } from "./debounced-sync.js";
+export type { DebouncedSyncOptions, DebouncedSync, DebouncedPushOptions, DebouncedPush } from "./debounced-sync.js";
+export { createMobileLifecycle } from "./mobile-lifecycle.js";
+export type { AppStateModule, NetInfoModule, MobileLifecycleDeps, MobileLifecycleOptions } from "./mobile-lifecycle.js";
+export { createMultiStoreSync } from "./multi-store.js";
+export type { StoreSlice, BackupDocument, MultiStoreMigrationFn, MultiStoreSyncOptions, MultiStoreSync, } from "./multi-store.js";

package/dist/index.js

@@ -17,3 +17,6 @@ export { exportData, importData, exportToBlob } from "./export.js";
 export { isBackgroundSyncSupported, registerBackgroundSync } from "./background-sync.js";
 export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
 export { createSuspenseResource } from "./bindings/suspense.js";
+export { createDebouncedSync, createDebouncedPush } from "./debounced-sync.js";
+export { createMobileLifecycle } from "./mobile-lifecycle.js";
+export { createMultiStoreSync } from "./multi-store.js";

package/dist/mobile-lifecycle.d.ts

@@ -0,0 +1,71 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { StarfishStore } from "./bindings/zustand.js";
+/**
+ * Minimal interface matching React Native's `AppState` module.
+ * Pass `AppState` from `react-native` directly.
+ */
+export interface AppStateModule {
+    addEventListener: (type: "change", listener: (state: string) => void) => {
+        remove: () => void;
+    };
+}
+/**
+ * Minimal interface matching `@react-native-community/netinfo`'s default export.
+ * Pass `NetInfo` from `@react-native-community/netinfo` directly.
+ */
+export interface NetInfoModule {
+    addEventListener: (listener: (state: {
+        isConnected: boolean | null;
+    }) => void) => () => void;
+}
+export interface MobileLifecycleDeps {
+    /** React Native `AppState` module. */
+    appState: AppStateModule;
+    /**
+     * Optional: NetInfo module from `@react-native-community/netinfo`.
+     * When provided, connectivity changes are forwarded to `store.getState().setOnline()`.
+     */
+    netInfo?: NetInfoModule;
+}
+export interface MobileLifecycleOptions {
+    /**
+     * Pull remote changes when the app returns to the foreground.
+     * Only pulls if the store is online and not already syncing.
+     * Default: `true`.
+     */
+    pullOnForeground?: boolean;
+    /**
+     * Flush dirty data when the app transitions to the background.
+     * Only flushes if the store has unsaved changes.
+     * Default: `true`.
+     */
+    flushOnBackground?: boolean;
+}
+/**
+ * Wires React Native app lifecycle events to a Starfish store.
+ *
+ * - **Background**: flushes pending changes before the OS suspends the app.
+ * - **Foreground**: pulls remote changes when the user returns to the app.
+ * - **NetInfo**: forwards connectivity changes to `store.getState().setOnline()`.
+ *
+ * Uses dependency injection so no `react-native` or `netinfo` imports are needed
+ * in this package. Pass the modules directly:
+ *
+ * ```ts
+ * import { AppState } from "react-native"
+ * import NetInfo from "@react-native-community/netinfo"
+ * import { createMobileLifecycle } from "@drakkar.software/starfish-client"
+ *
+ * // Call once, after the store is created:
+ * const cleanup = createMobileLifecycle(
+ *   store,
+ *   { appState: AppState, netInfo: NetInfo },
+ * )
+ *
+ * // In a React component (e.g. root layout):
+ * useEffect(() => cleanup, [])
+ * ```
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+export declare function createMobileLifecycle(store: StoreApi<StarfishStore>, deps: MobileLifecycleDeps, options?: MobileLifecycleOptions): () => void;

package/dist/mobile-lifecycle.js

@@ -0,0 +1,55 @@
+// ── Implementation ────────────────────────────────────────────────────────────
+/**
+ * Wires React Native app lifecycle events to a Starfish store.
+ *
+ * - **Background**: flushes pending changes before the OS suspends the app.
+ * - **Foreground**: pulls remote changes when the user returns to the app.
+ * - **NetInfo**: forwards connectivity changes to `store.getState().setOnline()`.
+ *
+ * Uses dependency injection so no `react-native` or `netinfo` imports are needed
+ * in this package. Pass the modules directly:
+ *
+ * ```ts
+ * import { AppState } from "react-native"
+ * import NetInfo from "@react-native-community/netinfo"
+ * import { createMobileLifecycle } from "@drakkar.software/starfish-client"
+ *
+ * // Call once, after the store is created:
+ * const cleanup = createMobileLifecycle(
+ *   store,
+ *   { appState: AppState, netInfo: NetInfo },
+ * )
+ *
+ * // In a React component (e.g. root layout):
+ * useEffect(() => cleanup, [])
+ * ```
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+export function createMobileLifecycle(store, deps, options = {}) {
+    const { pullOnForeground = true, flushOnBackground = true } = options;
+    const appSub = deps.appState.addEventListener("change", (appState) => {
+        if (appState === "background" && flushOnBackground) {
+            if (store.getState().dirty) {
+                store.getState().flush().catch(() => { });
+            }
+        }
+        else if (appState === "active" && pullOnForeground) {
+            const { online, syncing } = store.getState();
+            if (online && !syncing) {
+                store.getState().pull().catch(() => { });
+            }
+        }
+        // "inactive" (iOS transition) and other states are intentionally ignored
+    });
+    let netUnsub = null;
+    if (deps.netInfo) {
+        netUnsub = deps.netInfo.addEventListener(({ isConnected }) => {
+            store.getState().setOnline(!!isConnected);
+        });
+    }
+    return () => {
+        appSub.remove();
+        netUnsub?.();
+    };
+}

package/dist/multi-store.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Serializer/deserializer pair for one slice of application state.
+ *
+ * `serialize` snapshots the current state into a plain object.
+ * `restore` applies a snapshot (potentially from a different app version after migration).
+ */
+export interface StoreSlice<T = unknown> {
+    /**
+     * Snapshot the current state of this slice into a serializable value.
+     * Called during `serialize()`.
+     */
+    serialize: () => T;
+    /**
+     * Apply a snapshot to this slice.
+     * Called during `restore()` — data may be from an older schema version after migration.
+     */
+    restore: (data: T) => void;
+}
+/**
+ * A versioned backup document produced by `MultiStoreSync.serialize()`.
+ * Safe to pass to `store.set()` as the Starfish sync document.
+ */
+export interface BackupDocument<T = Record<string, unknown>> {
+    /** Schema version declared in `createMultiStoreSync`. */
+    version: number;
+    /** Unix timestamp (ms) when this backup was created. */
+    timestamp: number;
+    /** Serialized slice data, keyed by slice name. */
+    data: T;
+}
+/**
+ * A migration function that transforms data from one version to the next.
+ * Receives the full `data` object and must return an updated `data` object.
+ * Only the `data` field is passed; `version` and `timestamp` are managed automatically.
+ */
+export type MultiStoreMigrationFn = (data: Record<string, unknown>) => Record<string, unknown>;
+export interface MultiStoreSyncOptions<T extends Record<string, unknown>> {
+    /**
+     * Named slices to include in the backup document.
+     * Each slice provides `serialize()` and `restore()` methods.
+     *
+     * @example
+     * ```ts
+     * slices: {
+     *   tasks: {
+     *     serialize: () => taskStore.getState().tasks,
+     *     restore: (data) => taskStore.setState({ tasks: data }),
+     *   },
+     *   settings: {
+     *     serialize: () => settingsStore.getState().settings,
+     *     restore: (data) => settingsStore.setState({ settings: data }),
+     *   },
+     * }
+     * ```
+     */
+    slices: {
+        [K in keyof T]: StoreSlice<T[K]>;
+    };
+    /**
+     * Current schema version. Increment when slices are added, renamed, or their shape changes.
+     * Used to detect forward-incompatible documents from future app versions.
+     */
+    version: number;
+    /**
+     * Optional migration chain. Key is the version number that produced the data;
+     * value is a function that upgrades it to the next version.
+     *
+     * Migrations run sequentially from the document version up to the current version.
+     *
+     * @example
+     * ```ts
+     * migrations: {
+     *   1: (data) => ({ ...data, settings: { ...data.settings, theme: "light" } }),
+     *   2: (data) => ({ ...data, tasks: data.todos, todos: undefined }),
+     * }
+     * ```
+     */
+    migrations?: Record<number, MultiStoreMigrationFn>;
+}
+/**
+ * Returned by `createMultiStoreSync`. Serialize and restore coordinated multi-store state.
+ */
+export interface MultiStoreSync<T extends Record<string, unknown>> {
+    /**
+     * Snapshot all slices into a `BackupDocument`.
+     * Pass the result to `starfishStore.getState().set(() => multiSync.serialize())`.
+     */
+    serialize: () => BackupDocument<T>;
+    /**
+     * Apply a `BackupDocument` to all slices, running migrations as needed.
+     *
+     * Throws if the document version is newer than the current version (forward-incompatible).
+     * Silently migrates older documents.
+     */
+    restore: (doc: BackupDocument) => void;
+    /** Current schema version as declared in options. */
+    readonly version: number;
+}
+/**
+ * Creates a multi-store sync coordinator.
+ *
+ * Collects multiple application stores into a single Starfish sync document,
+ * with versioned schema migrations for backward compatibility.
+ *
+ * ```ts
+ * const multiSync = createMultiStoreSync({
+ *   slices: {
+ *     tasks: {
+ *       serialize: () => taskStore.getState().tasks,
+ *       restore: (tasks) => taskStore.setState({ tasks }),
+ *     },
+ *     settings: {
+ *       serialize: () => settingsStore.getState().settings,
+ *       restore: (settings) => settingsStore.setState({ settings }),
+ *     },
+ *   },
+ *   version: 2,
+ *   migrations: {
+ *     // data from version 1 → upgrade to version 2
+ *     1: (data) => ({ ...data, settings: { ...(data.settings as object), darkMode: false } }),
+ *   },
+ * })
+ *
+ * // Push:
+ * starfishStore.getState().set(() => multiSync.serialize())
+ *
+ * // Restore on pull (pass as onRemoteUpdate to createStarfishStore):
+ * createStarfishStore({
+ *   name: "app",
+ *   syncManager,
+ *   onRemoteUpdate: (doc) => multiSync.restore(doc as BackupDocument),
+ * })
+ * ```
+ */
+export declare function createMultiStoreSync<T extends Record<string, unknown>>(options: MultiStoreSyncOptions<T>): MultiStoreSync<T>;

package/dist/multi-store.js

@@ -0,0 +1,92 @@
+// ── Types ─────────────────────────────────────────────────────────────────────
+// ── Implementation ────────────────────────────────────────────────────────────
+/**
+ * Creates a multi-store sync coordinator.
+ *
+ * Collects multiple application stores into a single Starfish sync document,
+ * with versioned schema migrations for backward compatibility.
+ *
+ * ```ts
+ * const multiSync = createMultiStoreSync({
+ *   slices: {
+ *     tasks: {
+ *       serialize: () => taskStore.getState().tasks,
+ *       restore: (tasks) => taskStore.setState({ tasks }),
+ *     },
+ *     settings: {
+ *       serialize: () => settingsStore.getState().settings,
+ *       restore: (settings) => settingsStore.setState({ settings }),
+ *     },
+ *   },
+ *   version: 2,
+ *   migrations: {
+ *     // data from version 1 → upgrade to version 2
+ *     1: (data) => ({ ...data, settings: { ...(data.settings as object), darkMode: false } }),
+ *   },
+ * })
+ *
+ * // Push:
+ * starfishStore.getState().set(() => multiSync.serialize())
+ *
+ * // Restore on pull (pass as onRemoteUpdate to createStarfishStore):
+ * createStarfishStore({
+ *   name: "app",
+ *   syncManager,
+ *   onRemoteUpdate: (doc) => multiSync.restore(doc as BackupDocument),
+ * })
+ * ```
+ */
+export function createMultiStoreSync(options) {
+    const { slices, version, migrations = {} } = options;
+    // Validate migration chain at construction time (fail fast)
+    for (const fromVersion of Object.keys(migrations)) {
+        const v = Number(fromVersion);
+        if (isNaN(v) || v < 1) {
+            throw new Error(`Migration key must be a positive integer, got: "${fromVersion}"`);
+        }
+    }
+    function serialize() {
+        const data = {};
+        for (const key of Object.keys(slices)) {
+            data[key] = slices[key].serialize();
+        }
+        return { version, timestamp: Date.now(), data };
+    }
+    function restore(doc) {
+        if (typeof doc !== "object" || doc === null) {
+            throw new Error("restore: expected a BackupDocument object");
+        }
+        const docVersion = doc.version ?? 1;
+        if (typeof docVersion !== "number" || !Number.isInteger(docVersion) || docVersion < 1) {
+            throw new Error(`restore: invalid document version: ${String(doc.version)}`);
+        }
+        if (docVersion > version) {
+            throw new Error(`restore: document version ${docVersion} is newer than current version ${version}. ` +
+                `Update the app to restore this backup.`);
+        }
+        // Run migrations sequentially from docVersion up to current version
+        let data = typeof doc.data === "object" && doc.data !== null
+            ? { ...doc.data }
+            : {};
+        for (let v = docVersion; v < version; v++) {
+            const migration = migrations[v];
+            if (!migration)
+                continue;
+            try {
+                data = migration(data);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`restore: migration from version ${v} to ${v + 1} failed: ${msg}`);
+            }
+        }
+        // Restore each slice
+        for (const key of Object.keys(slices)) {
+            const sliceData = data[key];
+            if (sliceData !== undefined) {
+                slices[key].restore(sliceData);
+            }
+        }
+    }
+    return { serialize, restore, version };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -37,6 +37,10 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
+    },
+    "./identity": {
+      "types": "./dist/identity.d.ts",
+      "import": "./dist/identity.js"
     }
   },
   "peerDependencies": {