cursedbelt 5.89.0 → 5.90.0

package/dist/react/optimistic/optimistic.js

@@ -0,0 +1,216 @@
+/**
+ * `optimistic()` — do what the user asked NOW, tell the server after, and take it back only if
+ * the server says no.
+ *
+ * The owner, 2026-10-22 (forge task 3583): *"I want the cursedforge apps to use optimistic
+ * updates, where the UI doesn't wait for the server before doing what the user wants … if the
+ * delete fails it can popup a toast error but it would already be on the next track either way."*
+ *
+ *   optimistic({
+ *     label: `delete “${track.title}”`,
+ *     targets: [
+ *       { set: setTracks, apply: (rows) => rows.filter((r) => r.id !== track.id) },
+ *       { set: setTotal, apply: (n) => n - 1, revert: counterRevert },
+ *     ],
+ *     request: () => api.deleteTracks({ ids: [track.id] }),
+ *   });
+ *
+ * What it does, in order:
+ *
+ * 1. **Applies every target's forward edit at once**, through a setState-shaped `set` — React's
+ *    own setter, a store's, or {@link queryTarget} for a TanStack cache. It records the state
+ *    each edit started from and produced, inside the updater, so the rollback is derived
+ *    (`revert.ts`) and no caller writes an undo by hand.
+ * 2. **Sends the request** — after any earlier request with the same `key` has settled, so two
+ *    quick edits to one record reach the server in the order they were made. The UI never waits
+ *    for that queue; only the network does.
+ * 3. **On failure**, reverts exactly what this change touched (concurrent changes survive) and
+ *    shows an error toast naming what did not happen, with **Retry** (OVL-9) — Retry applies the
+ *    change again and resends it.
+ * 4. **While anything is in flight**, the page asks before it is closed or reloaded, because the
+ *    user has already seen the change happen and would otherwise lose it without knowing.
+ *
+ * Side effects that must NOT be undone stay outside it — the user's own words: a deleted song
+ * that comes back after a failed delete comes back to the list, but the player stays on the next
+ * track. Call the player before `optimistic()`, not as a target.
+ *
+ * It never rejects: the resolved {@link OptimisticOutcome} says what happened, so a fire-and-forget
+ * call (`void optimistic(...)`) cannot leak an unhandled rejection.
+ */
+import { defaultIdOf, inverseOf } from './revert.js';
+/** Pair a setter with its edit so the two are type-checked against each other. */
+export const target = (t) => t;
+let pending = [];
+let nextId = 1;
+const listeners = new Set();
+const queues = new Map();
+const emit = () => {
+    for (const listener of listeners)
+        listener();
+};
+/** Every optimistic change whose request has not settled, oldest first. */
+export const pendingChanges = () => pending;
+/** Subscribe to {@link pendingChanges} — the `useSyncExternalStore` shape. */
+export const subscribePendingChanges = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+};
+/**
+ * Resolves once nothing is pending — the moment to re-read a list that is not a TanStack query,
+ * so a read that started before the last change landed cannot draw it as undone.
+ */
+export const whenSettled = () => pending.length === 0
+    ? Promise.resolve()
+    : new Promise((resolve) => {
+        const off = subscribePendingChanges(() => {
+            if (pending.length > 0)
+                return;
+            off();
+            resolve();
+        });
+    });
+/**
+ * Closing the tab while a change is unsent loses it, and the user has already seen it happen.
+ * The listener exists only while something is pending, so an idle page leaves bfcache alone.
+ */
+const onBeforeUnload = (event) => {
+    event.preventDefault();
+    // Chrome still wants returnValue set; the text itself is never shown.
+    event.returnValue = '';
+};
+const track = (change) => {
+    const wasIdle = pending.length === 0;
+    pending = [...pending, change];
+    if (wasIdle && typeof window !== 'undefined')
+        window.addEventListener('beforeunload', onBeforeUnload);
+    emit();
+    return () => {
+        pending = pending.filter((p) => p.id !== change.id);
+        if (pending.length === 0 && typeof window !== 'undefined') {
+            window.removeEventListener('beforeunload', onBeforeUnload);
+        }
+        emit();
+    };
+};
+/** Run `task` after every earlier task under `key` has settled. */
+const enqueue = (key, task) => {
+    if (key === undefined)
+        return task();
+    const run = (queues.get(key) ?? Promise.resolve()).then(task, task);
+    const tail = run.catch(() => undefined);
+    queues.set(key, tail);
+    void tail.then(() => {
+        if (queues.get(key) === tail)
+            queues.delete(key);
+    });
+    return run;
+};
+const isStep = (t) => typeof t.now === 'function';
+function applyStep(step) {
+    step.now();
+    return { rollback: step.undo, settled: () => undefined };
+}
+function applyTarget(t) {
+    // Captured INSIDE the updater: React runs updaters during render, not when `set` is called.
+    // The rollback updater is queued behind this one, so by the time it runs the capture is there.
+    let seen;
+    const scope = t.scope?.();
+    t.begin?.();
+    t.set((current) => {
+        const after = t.apply(current);
+        seen = { before: current, after };
+        return after;
+    });
+    return {
+        rollback: () => {
+            if (t.scope && !Object.is(t.scope(), scope))
+                return; // another view is on screen now
+            t.set((current) => {
+                if (!seen)
+                    return current; // the edit never ran (its owner unmounted) — nothing to undo
+                const { before, after } = seen;
+                return t.revert ? t.revert(current, before, after) : inverseOf(before, after, t.idOf ?? defaultIdOf)(current);
+            });
+        },
+        settled: () => t.settled?.(),
+    };
+}
+const messageOf = (error) => {
+    if (error instanceof Error)
+        return error.message || undefined;
+    if (typeof error === 'string')
+        return error || undefined;
+    return undefined;
+};
+/** Apply now, send, revert on failure. See the file header. */
+export function optimistic(options) {
+    const { label, request, key, onSuccess, onError } = options;
+    const targets = options.targets === undefined ? [] : Array.isArray(options.targets) ? options.targets : [options.targets];
+    const applied = targets.map((t) => isStep(t) ? applyStep(t) : applyTarget(t));
+    const done = track({ id: nextId++, label, key, startedAt: Date.now() });
+    return enqueue(key, request).then((value) => {
+        done();
+        for (const a of applied)
+            a.settled();
+        onSuccess?.(value);
+        return { ok: true, value };
+    }, async (error) => {
+        done();
+        // Newest-first, so a target listed twice unwinds in the order it was wound.
+        for (const a of [...applied].reverse())
+            a.rollback();
+        for (const a of applied)
+            a.settled();
+        onError?.(error);
+        if (options.toast !== false) {
+            // Loaded at the first refusal, never before: a static import would put sonner (~10 kB
+            // gzip) back on every app's entry chunk, which cursedbelt 5.64 took it off (forge task
+            // 2900) — flix's and roms' entries grew by it the first time they imported this.
+            const { toast } = await import('../Toast.js');
+            toast.error(`Couldn’t ${label}`, {
+                id: `optimistic:${key ?? label}`,
+                description: options.describeError ? options.describeError(error) : messageOf(error),
+                action: { label: 'Retry', onClick: () => void optimistic(options) },
+            });
+        }
+        return { ok: false, error };
+    });
+}
+/** Changes in flight per cache entry, so the entry is refetched once, after the LAST of them. */
+const inFlight = new Map();
+/**
+ * A TanStack cache entry as a target's `set`: cancels the key's in-flight fetch first (so a
+ * response already on the wire cannot land on top of the change), writes through `setQueryData`,
+ * and refetches the key once the request settles, so the cache ends on the server's truth.
+ * An entry with no data yet is left alone.
+ *
+ * 🔴 The refetch waits for the LAST change in flight on the entry. Refetching after each one
+ * (the first version) meant two quick deletes drew the second row back for a moment: the first
+ * answer's refetch read the server before the second delete had landed (collections and desk
+ * both met it, forge task 3583; TanStack's own docs gate on `isMutating`).
+ *
+ *   targets: [{ ...queryTarget(queryClient, ['lists']), apply: (lists) => lists.filter(...) }]
+ */
+export function queryTarget(client, queryKey, { refetch = true } = {}) {
+    const entry = JSON.stringify(queryKey);
+    return {
+        set: (updater) => {
+            void client.cancelQueries({ queryKey, exact: true });
+            client.setQueryData(queryKey, (old) => (old === undefined ? old : updater(old)));
+        },
+        begin: () => inFlight.set(entry, (inFlight.get(entry) ?? 0) + 1),
+        settled: () => {
+            const left = (inFlight.get(entry) ?? 1) - 1;
+            if (left > 0) {
+                inFlight.set(entry, left);
+                return;
+            }
+            inFlight.delete(entry);
+            if (refetch)
+                void client.invalidateQueries({ queryKey });
+        },
+    };
+}
+//# sourceMappingURL=optimistic.js.map

package/dist/react/optimistic/optimistic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimistic.js","sourceRoot":"","sources":["../../../src/react/optimistic/optimistic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,WAAW,EAAa,SAAS,EAAE,MAAM,aAAa,CAAC;AAsEhE,kFAAkF;AAClF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAI,CAAsB,EAAuB,EAAE,CAAC,CAAC,CAAC;AAW5E,IAAI,OAAO,GAA6B,EAAE,CAAC;AAC3C,IAAI,MAAM,GAAG,CAAC,CAAC;AACf,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;AACxC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;AAEnD,MAAM,IAAI,GAAG,GAAG,EAAE;IAChB,KAAK,MAAM,QAAQ,IAAI,SAAS;QAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,cAAc,GAAG,GAA6B,EAAE,CAAC,OAAO,CAAC;AAEtE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,QAAoB,EAAgB,EAAE;IAC5E,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAkB,EAAE,CAC7C,OAAO,CAAC,MAAM,KAAK,CAAC;IAClB,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE;IACnB,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACtB,MAAM,GAAG,GAAG,uBAAuB,CAAC,GAAG,EAAE;YACvC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO;YAC/B,GAAG,EAAE,CAAC;YACN,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AAET;;;GAGG;AACH,MAAM,cAAc,GAAG,CAAC,KAAwB,EAAE,EAAE;IAClD,KAAK,CAAC,cAAc,EAAE,CAAC;IACvB,sEAAsE;IACtE,KAAK,CAAC,WAAW,GAAG,EAAE,CAAC;AACzB,CAAC,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,MAAqB,EAAgB,EAAE;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,OAAO,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IACtG,IAAI,EAAE,CAAC;IACP,OAAO,GAAG,EAAE;QACV,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAC1D,MAAM,CAAC,mBAAmB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC,CAAC;AAEF,mEAAmE;AACnE,MAAM,OAAO,GAAG,CAAI,GAAuB,EAAE,IAAsB,EAAc,EAAE;IACjF,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;QAClB,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI;YAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AASF,MAAM,MAAM,GAAG,CAAC,CAA6C,EAAuB,EAAE,CACpF,OAAQ,CAAoB,CAAC,GAAG,KAAK,UAAU,CAAC;AAElD,SAAS,SAAS,CAAC,IAAoB;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;IACX,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,WAAW,CAAI,CAAsB;IAC5C,4FAA4F;IAC5F,+FAA+F;IAC/F,IAAI,IAAyC,CAAC;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;IAC1B,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;IACZ,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAChB,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE;YACb,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC;gBAAE,OAAO,CAAC,gCAAgC;YACrF,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;gBAChB,IAAI,CAAC,IAAI;oBAAE,OAAO,OAAO,CAAC,CAAC,6DAA6D;gBACxF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;gBAC/B,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,IAAI,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC;YAChH,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAG,CAAC,KAAc,EAAsB,EAAE;IACvD,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,IAAI,SAAS,CAAC;IAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,IAAI,SAAS,CAAC;IACzD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,+DAA+D;AAC/D,MAAM,UAAU,UAAU,CAAI,OAA6B;IACzD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1H,MAAM,OAAO,GAAI,OAA0D,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACpF,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAC1C,CAAC;IACF,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAExE,OAAO,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,IAAI,CAC/B,CAAC,KAAK,EAAwB,EAAE;QAC9B,IAAI,EAAE,CAAC;QACP,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACrC,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC,EACD,KAAK,EAAE,KAAc,EAAiC,EAAE;QACtD,IAAI,EAAE,CAAC;QACP,4EAA4E;QAC5E,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE;YAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;QACrD,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACrC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACjB,IAAI,OAAO,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YAC5B,sFAAsF;YACtF,uFAAuF;YACvF,iFAAiF;YACjF,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;YAC9C,KAAK,CAAC,KAAK,CAAC,YAAY,KAAK,EAAE,EAAE;gBAC/B,EAAE,EAAE,cAAc,GAAG,IAAI,KAAK,EAAE;gBAChC,WAAW,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC;gBACpF,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,UAAU,CAAC,OAAO,CAAC,EAAE;aACpE,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC,CACF,CAAC;AACJ,CAAC;AAcD,iGAAiG;AACjG,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,MAA6B,EAC7B,QAA4B,EAC5B,EAAE,OAAO,GAAG,IAAI,KAA4B,EAAE;IAE9C,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO;QACL,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE;YACf,KAAK,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAQ,CAAC,CAAC,CAAC,CAAC;QACxF,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAChE,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC5C,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;gBACb,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBAC1B,OAAO;YACT,CAAC;YACD,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvB,IAAI,OAAO;gBAAE,KAAK,MAAM,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/react/optimistic/revert.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The rollback half of an optimistic change, DERIVED from the change itself.
+ *
+ * A caller writes only the forward edit (`rows => rows.filter(r => r.id !== id)`); this works out
+ * what that edit touched by comparing the state before and after it, and returns an inverse that
+ * undoes exactly that — applied to whatever the state is when the request fails, not to a
+ * snapshot. That difference is the whole reason this file exists:
+ *
+ *   delete A, delete B, A fails → restoring the snapshot taken before A would bring back B too
+ *   (or, taken before B, drop a rename made since). The inverse instead puts A back where it
+ *   was and leaves B gone and the rename standing.
+ *
+ * The rules, by shape (recursing through plain objects and arrays, so a patch three levels down
+ * reverts three levels down):
+ *
+ * | shape | the change | its inverse, against the current state |
+ * |---|---|---|
+ * | array of records (`id`) or primitives | item removed | put back after its nearest surviving neighbor, unless it is back already |
+ * | | item added | taken out by id |
+ * | | item changed | recurse into it by id (only fields still holding the optimistic value revert) |
+ * | | reordered | the old order back, only if the current order is still the optimistic one |
+ * | plain object | key changed / added / removed | per key, recursing |
+ * | `Set` / `Map` | member added / removed | the member out / back |
+ * | anything else | replaced | the old value back only if the current one is still the optimistic one |
+ *
+ * "Only if it still holds the optimistic value" is what lets two edits race: rename to "B", then
+ * to "C" — if the first request fails, the title is "C" by now, so it stays "C".
+ *
+ * Returns the current state UNCHANGED (same reference) when nothing needs reverting, so a React
+ * setter given the inverse does not re-render.
+ */
+/** How an array item is identified. Records by `id` (or `key`), primitives by value. */
+export type IdOf = (item: unknown) => unknown;
+export declare const defaultIdOf: IdOf;
+/**
+ * The inverse of the change `before → after`, as a function of the state at revert time.
+ * `idOf` names array items; the default reads `id`, then `key`, and uses a primitive's value.
+ */
+export declare function inverseOf<S>(before: S, after: S, idOf?: IdOf): (current: S) => S;
+/**
+ * A counter's inverse: give back the difference the change made, whatever has happened since.
+ * The whole-value rule is wrong for a count — two deletes take a total 10 → 9 → 8, and when the
+ * first fails the total is 8, not 9, so "revert only if still optimistic" would never fire. Pass
+ * it as a target's `revert`: `{ set: setTotal, apply: (n) => n - 1, revert: counterRevert }`.
+ */
+export declare const counterRevert: (current: number, before: number, after: number) => number;
+//# sourceMappingURL=revert.d.ts.map

package/dist/react/optimistic/revert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revert.d.ts","sourceRoot":"","sources":["../../../src/react/optimistic/revert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,wFAAwF;AACxF,MAAM,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;AAI9C,eAAO,MAAM,WAAW,EAAE,IAMzB,CAAC;AAQF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,GAAE,IAAkB,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAE7F;AA6KD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,MACnD,CAAC"}

package/dist/react/optimistic/revert.js

@@ -0,0 +1,235 @@
+/**
+ * The rollback half of an optimistic change, DERIVED from the change itself.
+ *
+ * A caller writes only the forward edit (`rows => rows.filter(r => r.id !== id)`); this works out
+ * what that edit touched by comparing the state before and after it, and returns an inverse that
+ * undoes exactly that — applied to whatever the state is when the request fails, not to a
+ * snapshot. That difference is the whole reason this file exists:
+ *
+ *   delete A, delete B, A fails → restoring the snapshot taken before A would bring back B too
+ *   (or, taken before B, drop a rename made since). The inverse instead puts A back where it
+ *   was and leaves B gone and the rename standing.
+ *
+ * The rules, by shape (recursing through plain objects and arrays, so a patch three levels down
+ * reverts three levels down):
+ *
+ * | shape | the change | its inverse, against the current state |
+ * |---|---|---|
+ * | array of records (`id`) or primitives | item removed | put back after its nearest surviving neighbor, unless it is back already |
+ * | | item added | taken out by id |
+ * | | item changed | recurse into it by id (only fields still holding the optimistic value revert) |
+ * | | reordered | the old order back, only if the current order is still the optimistic one |
+ * | plain object | key changed / added / removed | per key, recursing |
+ * | `Set` / `Map` | member added / removed | the member out / back |
+ * | anything else | replaced | the old value back only if the current one is still the optimistic one |
+ *
+ * "Only if it still holds the optimistic value" is what lets two edits race: rename to "B", then
+ * to "C" — if the first request fails, the title is "C" by now, so it stays "C".
+ *
+ * Returns the current state UNCHANGED (same reference) when nothing needs reverting, so a React
+ * setter given the inverse does not re-render.
+ */
+const NO_ID = Symbol('no-id');
+export const defaultIdOf = (item) => {
+    if (item === null || typeof item !== 'object')
+        return item;
+    const record = item;
+    if (record.id !== undefined)
+        return record.id;
+    if (record.key !== undefined)
+        return record.key;
+    return NO_ID;
+};
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+/**
+ * The inverse of the change `before → after`, as a function of the state at revert time.
+ * `idOf` names array items; the default reads `id`, then `key`, and uses a primitive's value.
+ */
+export function inverseOf(before, after, idOf = defaultIdOf) {
+    return (current) => revertValue(before, after, current, idOf);
+}
+function revertValue(before, after, current, idOf) {
+    if (Object.is(before, after))
+        return current;
+    if (Array.isArray(before) && Array.isArray(after) && Array.isArray(current)) {
+        const reverted = revertArray(before, after, current, idOf);
+        if (reverted !== undefined)
+            return reverted;
+    }
+    if (before instanceof Set && after instanceof Set && current instanceof Set) {
+        return revertSet(before, after, current);
+    }
+    if (before instanceof Map && after instanceof Map && current instanceof Map) {
+        return revertMap(before, after, current, idOf);
+    }
+    if (isPlainObject(before) && isPlainObject(after) && isPlainObject(current)) {
+        return revertObject(before, after, current, idOf);
+    }
+    return Object.is(current, after) ? before : current;
+}
+function revertObject(before, after, current, idOf) {
+    let out;
+    const write = (key, value, remove = false) => {
+        out ??= { ...current };
+        if (remove)
+            delete out[key];
+        else
+            out[key] = value;
+    };
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const had = Object.hasOwn(before, key);
+        const has = Object.hasOwn(after, key);
+        if (had && has) {
+            if (Object.is(before[key], after[key]))
+                continue;
+            if (!Object.hasOwn(current, key))
+                continue; // removed since — not ours to bring back
+            const next = revertValue(before[key], after[key], current[key], idOf);
+            if (!Object.is(next, current[key]))
+                write(key, next);
+        }
+        else if (has) {
+            // Added by the change: take it out if it is still what the change put there.
+            if (Object.hasOwn(current, key) && Object.is(current[key], after[key]))
+                write(key, undefined, true);
+        }
+        else if (!Object.hasOwn(current, key)) {
+            write(key, before[key]); // removed by the change, and still gone
+        }
+    }
+    return out ?? current;
+}
+/** `undefined` when the items cannot be identified — the caller falls back to whole-value. */
+function revertArray(before, after, current, idOf) {
+    const ids = (list) => list.map(idOf);
+    const beforeIds = ids(before);
+    const afterIds = ids(after);
+    const unique = (list) => !list.includes(NO_ID) && new Set(list).size === list.length;
+    if (!unique(beforeIds) || !unique(afterIds))
+        return undefined;
+    const beforeById = new Map(beforeIds.map((id, i) => [id, before[i]]));
+    const afterById = new Map(afterIds.map((id, i) => [id, after[i]]));
+    let out = current;
+    let touched = false;
+    const edit = () => {
+        if (!touched) {
+            out = [...current];
+            touched = true;
+        }
+    };
+    // 1 · Items the change ADDED go, if they are still there.
+    const added = afterIds.filter((id) => !beforeById.has(id));
+    if (added.length > 0) {
+        const drop = new Set(added);
+        const kept = out.filter((item) => !drop.has(idOf(item)));
+        if (kept.length !== out.length) {
+            out = kept;
+            touched = true;
+        }
+    }
+    // 2 · Items the change CHANGED revert field by field.
+    for (const [id, was] of beforeById) {
+        const now = afterById.get(id);
+        if (now === undefined || Object.is(was, now))
+            continue;
+        const at = out.findIndex((item) => Object.is(idOf(item), id));
+        if (at < 0)
+            continue;
+        const next = revertValue(was, now, out[at], idOf);
+        if (!Object.is(next, out[at])) {
+            edit();
+            out[at] = next;
+        }
+    }
+    // 3 · Items the change REMOVED come back beside the neighbor they had.
+    const removed = beforeIds.flatMap((id, index) => (afterById.has(id) ? [] : [{ id, index }]));
+    for (const { id, index } of removed) {
+        if (out.some((item) => Object.is(idOf(item), id)))
+            continue;
+        edit();
+        let at = 0;
+        for (let i = index - 1; i >= 0; i--) {
+            const neighbor = out.findIndex((item) => Object.is(idOf(item), beforeIds[i]));
+            if (neighbor >= 0) {
+                at = neighbor + 1;
+                break;
+            }
+        }
+        out.splice(at, 0, beforeById.get(id));
+    }
+    // 4 · A REORDER: the old order back, only where the optimistic order still stands.
+    const kept = beforeIds.filter((id) => afterById.has(id));
+    const keptAfter = afterIds.filter((id) => beforeById.has(id));
+    if (kept.some((id, i) => !Object.is(id, keptAfter[i]))) {
+        const keep = new Set(kept);
+        const positions = [];
+        out.forEach((item, i) => {
+            if (keep.has(idOf(item)))
+                positions.push(i);
+        });
+        const nowOrder = positions.map((i) => idOf(out[i]));
+        if (nowOrder.length === keptAfter.length && nowOrder.every((id, i) => Object.is(id, keptAfter[i]))) {
+            const byId = new Map(positions.map((i) => [idOf(out[i]), out[i]]));
+            edit();
+            positions.forEach((slot, i) => {
+                out[slot] = byId.get(kept[i]);
+            });
+        }
+    }
+    return touched ? out : current;
+}
+function revertSet(before, after, current) {
+    let out;
+    const copy = () => {
+        out ??= new Set(current);
+        return out;
+    };
+    for (const member of after) {
+        if (!before.has(member) && current.has(member))
+            copy().delete(member);
+    }
+    for (const member of before) {
+        if (!after.has(member) && !current.has(member))
+            copy().add(member);
+    }
+    return out ?? current;
+}
+function revertMap(before, after, current, idOf) {
+    let out;
+    const copy = () => {
+        out ??= new Map(current);
+        return out;
+    };
+    for (const key of new Set([...before.keys(), ...after.keys()])) {
+        const had = before.has(key);
+        const has = after.has(key);
+        if (had && has) {
+            if (Object.is(before.get(key), after.get(key)) || !current.has(key))
+                continue;
+            const next = revertValue(before.get(key), after.get(key), current.get(key), idOf);
+            if (!Object.is(next, current.get(key)))
+                copy().set(key, next);
+        }
+        else if (has) {
+            if (current.has(key) && Object.is(current.get(key), after.get(key)))
+                copy().delete(key);
+        }
+        else if (!current.has(key)) {
+            copy().set(key, before.get(key));
+        }
+    }
+    return out ?? current;
+}
+/**
+ * A counter's inverse: give back the difference the change made, whatever has happened since.
+ * The whole-value rule is wrong for a count — two deletes take a total 10 → 9 → 8, and when the
+ * first fails the total is 8, not 9, so "revert only if still optimistic" would never fire. Pass
+ * it as a target's `revert`: `{ set: setTotal, apply: (n) => n - 1, revert: counterRevert }`.
+ */
+export const counterRevert = (current, before, after) => current + (before - after);
+//# sourceMappingURL=revert.js.map

package/dist/react/optimistic/revert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revert.js","sourceRoot":"","sources":["../../../src/react/optimistic/revert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;AAE9B,MAAM,CAAC,MAAM,WAAW,GAAS,CAAC,IAAI,EAAE,EAAE;IACxC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAuC,CAAC;IACvD,IAAI,MAAM,CAAC,EAAE,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,EAAE,CAAC;IAC9C,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC;IAChD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,KAAc,EAAoC,EAAE;IACzE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACtD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAI,MAAS,EAAE,KAAQ,EAAE,OAAa,WAAW;IACxE,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAM,CAAC;AACrE,CAAC;AAED,SAAS,WAAW,CAAC,MAAe,EAAE,KAAc,EAAE,OAAgB,EAAE,IAAU;IAChF,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5E,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3D,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;IAC9C,CAAC;IACD,IAAI,MAAM,YAAY,GAAG,IAAI,KAAK,YAAY,GAAG,IAAI,OAAO,YAAY,GAAG,EAAE,CAAC;QAC5E,OAAO,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,MAAM,YAAY,GAAG,IAAI,KAAK,YAAY,GAAG,IAAI,OAAO,YAAY,GAAG,EAAE,CAAC;QAC5E,OAAO,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5E,OAAO,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;AACtD,CAAC;AAED,SAAS,YAAY,CACnB,MAA+B,EAC/B,KAA8B,EAC9B,OAAgC,EAChC,IAAU;IAEV,IAAI,GAAwC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,MAAM,GAAG,KAAK,EAAE,EAAE;QAC5D,GAAG,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC;QACvB,IAAI,MAAM;YAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;;YACvB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;gBAAE,SAAS;YACjD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC;gBAAE,SAAS,CAAC,yCAAyC;YACrF,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;YACtE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;gBAAE,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,GAAG,EAAE,CAAC;YACf,6EAA6E;YAC7E,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;gBAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QACtG,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;YACxC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,wCAAwC;QACnE,CAAC;IACH,CAAC;IACD,OAAO,GAAG,IAAI,OAAO,CAAC;AACxB,CAAC;AAED,8FAA8F;AAC9F,SAAS,WAAW,CAAC,MAAiB,EAAE,KAAgB,EAAE,OAAkB,EAAE,IAAU;IACtF,MAAM,GAAG,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC;IAChG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,IAAI,GAAG,GAAG,OAAO,CAAC;IAClB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;YACnB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;IAEF,0DAA0D;IAC1D,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACzD,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC;YAC/B,GAAG,GAAG,IAAI,CAAC;YACX,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,SAAS;QACvD,MAAM,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC9D,IAAI,EAAE,GAAG,CAAC;YAAE,SAAS;QACrB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YAC9B,IAAI,EAAE,CAAC;YACP,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7F,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,OAAO,EAAE,CAAC;QACpC,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YAAE,SAAS;QAC5D,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,GAAG,CAAC,CAAC;QACX,KAAK,IAAI,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9E,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;gBAClB,EAAE,GAAG,QAAQ,GAAG,CAAC,CAAC;gBAClB,MAAM;YACR,CAAC;QACH,CAAC;QACD,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,mFAAmF;IACnF,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9D,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACtB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnG,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnE,IAAI,EAAE,CAAC;YACP,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;gBAC5B,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACjC,CAAC;AAED,SAAS,SAAS,CAAC,MAAoB,EAAE,KAAmB,EAAE,OAAqB;IACjF,IAAI,GAA6B,CAAC;IAClC,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,GAAG,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACxE,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,IAAI,OAAO,CAAC;AACxB,CAAC;AAED,SAAS,SAAS,CAChB,MAA6B,EAC7B,KAA4B,EAC5B,OAA8B,EAC9B,IAAU;IAEV,IAAI,GAAsC,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,GAAG,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC/D,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC9E,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;YAClF,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAChE,CAAC;aAAM,IAAI,GAAG,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAAE,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1F,CAAC;aAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,IAAI,OAAO,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAe,EAAE,MAAc,EAAE,KAAa,EAAU,EAAE,CACtF,OAAO,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.89.0",
+	"version": "5.90.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",

package/scripts/styleAreas.ts

@@ -122,11 +122,14 @@ export const AREAS: readonly Area[] = [
 			'authSignal.ts',
 			'sessionAuth.ts',
 			'createApiHooks.ts',
+			// Draws nothing; `createApiHooks` imports it, and every app's changes go through it (STA-10).
+			'optimistic',
 			'usePagedList.ts',
 			'lazy',
 			'confirm.tsx',
 			'prompt.tsx',
 			'Toast.tsx',
+			'LazyToaster.tsx',
 			'colorScheme',
 			// The look store and its picker: the sibling of colorScheme, installed at boot beside it.
 			'look',

package/src/react/LazyToaster.spec.tsx

@@ -0,0 +1,18 @@
+import { describe, expect, test } from 'bun:test';
+import { act, render } from '@testing-library/react';
+import { LazyToaster } from './LazyToaster.js';
+import { toast } from './Toast.js';
+
+describe('LazyToaster', () => {
+  test('mounts the stack once its chunk lands, and a toast shows in it', async () => {
+    const { container } = render(<LazyToaster />);
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    });
+    await act(async () => {
+      toast('Saved');
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    });
+    expect(container.ownerDocument.body.textContent).toContain('Saved');
+  });
+});

package/src/react/LazyToaster.tsx

@@ -0,0 +1,26 @@
+/**
+ * `<LazyToaster />` — the toast stack, mounted without putting sonner on the entry chunk.
+ *
+ * Rollup colors a module into the chunk of its static importers, so an app that mounts `Toaster`
+ * from its root pays for the whole stack (~15 kB gzip, measured in family, forge task 2900) on
+ * first paint, however lazily its toasts are CALLED (`Button`, `optimistic()`). family solved it
+ * by hand with a lazy wrapper of its own; flix, roms and station mounted `Toaster` statically the
+ * day they first needed a toast (forge task 3583) and their entries grew by it. This is that
+ * wrapper, once: the stack's chunk loads after first paint, and a toast raised before it lands
+ * waits for it (sonner queues calls made before its Toaster mounts).
+ *
+ * Takes `Toaster`'s props. Mount it once, at the app's root, in place of `Toaster`.
+ */
+import { Suspense } from 'react';
+import { lazyWithReload } from './lazy/staleChunk.js';
+import type { ToasterProps } from './Toast.js';
+
+const Stack = lazyWithReload(() => import('./Toast.js').then((m) => ({ default: m.Toaster })));
+
+export function LazyToaster(props: ToasterProps) {
+  return (
+    <Suspense fallback={null}>
+      <Stack {...props} />
+    </Suspense>
+  );
+}