cursedbelt 5.89.0 → 5.91.0

package/src/react/index.ts

@@ -757,6 +757,7 @@ export { Wizard } from './components/Wizard/Wizard.js';
 export * from './confirm.js';
 export { VIEWPORT_META } from './constants/viewport.js';
 export * from './createApiHooks.js';
+export * from './optimistic/index.js';
 export {
   EmojiAutocomplete,
   type EmojiAutocompleteProps,
@@ -960,6 +961,7 @@ export * from './nav/index.js';
 export * from './palette/index.js';
 export * from './prompt.js';
 export { sessionAuthHeaders } from './sessionAuth.js';
+export { LazyToaster } from './LazyToaster.js';
 export { Toaster, type ToasterProps, toast } from './Toast.js';
 export { TestReportViewer, type TestReportViewerProps } from './testReport/index.js';
 export { UiScaleControl, type UiScaleControlProps } from './uiScale/UiScaleControl.js';

package/src/react/nav/RailPlaces.spec.tsx

@@ -26,6 +26,12 @@ describe('RailPlaces — the top bar moved into the sidebar (owner, 2026-10-20)'
     expect(getByRole('link', { name: 'Stats · 3' }).getAttribute('href')).toBe('#/stats');
   });
 
+  test('no brand (a drawer titled with the app): the places alone, no brand line', () => {
+    const { container, getByRole } = render(<RailPlaces items={items} />);
+    expect(container.querySelector('[data-cb-rail-brand]')).toBeNull();
+    expect(getByRole('link', { name: 'Library' }).getAttribute('href')).toBe('#/');
+  });
+
   test('the current place is marked three ways (NAV-6): aria-current, the raised fill, the 3px accent edge', () => {
     const { getByRole } = render(<RailPlaces brand={brand} items={items} />);
     const library = getByRole('link', { name: 'Library' });

package/src/react/nav/RailPlaces.tsx

@@ -6,8 +6,12 @@ import { NAV_BADGE_TONE } from './navShared.js';
 import type { TopBarItem, TopBarProps } from './TopBar.js';
 
 export interface RailPlacesProps {
-  /** The app's mark and name, linking to its root — the same shape `TopBar` takes. */
-  brand: TopBarProps['brand'];
+  /**
+   * The app's mark and name, linking to its root — the same shape `TopBar` takes. Absent where the
+   * sidebar's container already names the app (a phone's drawer, titled with it, whose title line
+   * carries the utilities too — `Drawer`'s `actions`): then only the places are drawn.
+   */
+  brand?: TopBarProps['brand'];
   /** The app's places, in IA order — the same items a `TopBar` would have drawn. */
   items: readonly TopBarItem[];
   /**
@@ -67,6 +71,7 @@ export function RailPlaces({
       data-cb-rail-places=''
       className={cn('flex flex-none flex-col gap-1 border-b border-rule px-2 pt-2 pb-2', className)}
     >
+      {brand ? (
       <div className={cn('flex h-10 min-w-0 items-center gap-1', collapsed && 'justify-center')}>
         <Brand
           {...brand.linkProps}
@@ -96,6 +101,11 @@ export function RailPlaces({
           </div>
         ) : null}
       </div>
+      ) : trailing && !collapsed ? (
+        <div data-cb-rail-utilities='' data-cb-nav-utility='' className='flex h-10 items-center justify-end gap-0.5'>
+          {trailing}
+        </div>
+      ) : null}
       {trailing && collapsed ? (
         <div data-cb-rail-utilities='' data-cb-nav-utility='' className='flex flex-col items-center gap-0.5'>
           {trailing}

package/src/react/optimistic/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Optimistic changes — the UI does what the user asked at once, the server is told after, and
+ * only a refusal takes it back (with a Retry toast). `optimistic.ts` has the contract; the rule
+ * for WHEN to use it is STA-10 in the design law (`docs/design/states-and-feedback.md`).
+ */
+import { useSyncExternalStore } from 'react';
+import { type PendingChange, pendingChanges, subscribePendingChanges } from './optimistic.js';
+
+export {
+  type OptimisticOptions,
+  type OptimisticOutcome,
+  type OptimisticQueryClient,
+  type OptimisticStep,
+  type OptimisticTarget,
+  optimistic,
+  type PendingChange,
+  pendingChanges,
+  queryTarget,
+  subscribePendingChanges,
+  target,
+  whenSettled,
+} from './optimistic.js';
+export { counterRevert } from './revert.js';
+
+const none: readonly PendingChange[] = [];
+
+/**
+ * The optimistic changes still waiting on the server — all of them, or those under one `key`.
+ * For a quiet "Saving…" beside a record, or a sync dot in the shell; never a spinner that holds
+ * the user back, since the change has already happened on screen.
+ */
+export function usePendingChanges(key?: string): readonly PendingChange[] {
+  const all = useSyncExternalStore(subscribePendingChanges, pendingChanges, () => none);
+  if (key === undefined) return all;
+  return all.filter((change) => change.key === key);
+}

package/src/react/optimistic/optimistic.spec.tsx

@@ -0,0 +1,225 @@
+import { afterEach, beforeEach, describe, expect, type Mock, spyOn, test } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useState } from 'react';
+import { toast } from '../Toast.js';
+import { counterRevert, optimistic, pendingChanges, queryTarget, usePendingChanges, whenSettled } from './index.js';
+
+// A spy on the real toast, restored after each test — `mock.module` would outlive this file.
+let toastError: Mock<typeof toast.error>;
+beforeEach(() => {
+  toastError = spyOn(toast, 'error').mockImplementation(() => 0);
+});
+afterEach(() => toastError.mockRestore());
+
+type Row = { id: string; title: string };
+const rows: Row[] = [
+  { id: 'a', title: 'A' },
+  { id: 'b', title: 'B' },
+  { id: 'c', title: 'C' },
+];
+
+/** A promise the test settles by hand — the server's answer, on the test's schedule. */
+const deferred = <T,>() => {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+
+/** Plain state with a setState-shaped setter, standing in for a store. */
+const box = <S,>(initial: S) => {
+  const b = {
+    value: initial,
+    set: (updater: (s: S) => S) => {
+      b.value = updater(b.value);
+    },
+  };
+  return b;
+};
+
+describe('optimistic', () => {
+  test('the change shows BEFORE the request settles, and stays when it succeeds', async () => {
+    const state = box(rows);
+    const server = deferred<string>();
+    const done = optimistic({
+      label: 'delete “B”',
+      targets: { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+      request: () => server.promise,
+    });
+    expect(state.value.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(pendingChanges()).toHaveLength(1);
+    server.resolve('ok');
+    expect(await done).toEqual({ ok: true, value: 'ok' });
+    expect(state.value.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(pendingChanges()).toHaveLength(0);
+    expect(toastError).not.toHaveBeenCalled();
+  });
+
+  test('a refusal reverts only its own change, toasts with Retry, and Retry tries again', async () => {
+    const state = box(rows);
+    const total = box(3);
+    const first = deferred<void>();
+    const failing = optimistic({
+      label: 'delete “A”',
+      targets: [
+        { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'a') },
+        { set: total.set, apply: (n: number) => n - 1, revert: counterRevert },
+      ],
+      request: () => first.promise,
+    });
+    const second = optimistic({
+      label: 'delete “B”',
+      targets: [
+        { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+        { set: total.set, apply: (n: number) => n - 1, revert: counterRevert },
+      ],
+      request: () => Promise.resolve(),
+    });
+    await second;
+    first.reject(new Error('the server said no'));
+    const outcome = await failing;
+    expect(outcome.ok).toBe(false);
+    expect(state.value.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(total.value).toBe(2);
+
+    expect(toastError).toHaveBeenCalledTimes(1);
+    const [message, data] = toastError.mock.calls[0] as unknown as [string, { description: string; action: { label: string; onClick: () => void } }];
+    expect(message).toBe('Couldn’t delete “A”');
+    expect(data.description).toBe('the server said no');
+    expect(data.action.label).toBe('Retry');
+  });
+
+  test('a step (imperative now/undo) runs at once and undoes on a refusal', async () => {
+    const log: string[] = [];
+    await optimistic({
+      label: 'favorite',
+      toast: false,
+      targets: { now: () => log.push('now'), undo: () => log.push('undo') },
+      request: () => Promise.reject(new Error('no')),
+    });
+    expect(log).toEqual(['now', 'undo']);
+  });
+
+  test('a rollback skips state that belongs to another view by now', async () => {
+    const state = box(rows);
+    let view = 'folder-1';
+    const server = deferred<void>();
+    const done = optimistic({
+      label: 'delete “A”',
+      toast: false,
+      targets: { set: state.set, apply: (r: Row[]) => r.filter((x) => x.id !== 'a'), scope: () => view },
+      request: () => server.promise,
+    });
+    view = 'folder-2';
+    state.value = [{ id: 'z', title: 'Z' }];
+    server.reject(new Error('no'));
+    await done;
+    expect(state.value.map((r) => r.id)).toEqual(['z']);
+  });
+
+  test('requests under one key reach the server in order; the UI never waits for the queue', async () => {
+    const state = box({ title: 'A' });
+    const order: string[] = [];
+    const gate = deferred<void>();
+    const one = optimistic({
+      label: 'rename',
+      key: 'row-a',
+      targets: { set: state.set, apply: (s: { title: string }) => ({ ...s, title: 'X' }) },
+      request: async () => {
+        order.push('X sent');
+        await gate.promise;
+        order.push('X done');
+      },
+    });
+    const two = optimistic({
+      label: 'rename',
+      key: 'row-a',
+      targets: { set: state.set, apply: (s: { title: string }) => ({ ...s, title: 'Y' }) },
+      request: async () => {
+        order.push('Y sent');
+      },
+    });
+    expect(state.value.title).toBe('Y');
+    await Promise.resolve();
+    expect(order).toEqual(['X sent']);
+    gate.resolve();
+    await Promise.all([one, two]);
+    expect(order).toEqual(['X sent', 'X done', 'Y sent']);
+  });
+
+  test('the page asks before closing while a change is unsent, and stops asking after', async () => {
+    const server = deferred<void>();
+    const done = optimistic({ label: 'save', request: () => server.promise, toast: false });
+    const event = new Event('beforeunload', { cancelable: true });
+    window.dispatchEvent(event);
+    expect(event.defaultPrevented).toBe(true);
+    server.resolve();
+    await done;
+    const later = new Event('beforeunload', { cancelable: true });
+    window.dispatchEvent(later);
+    expect(later.defaultPrevented).toBe(false);
+  });
+
+  test('works through a React setter, and usePendingChanges follows the request', async () => {
+    const server = deferred<void>();
+    const { result } = renderHook(() => {
+      const [list, setList] = useState(rows);
+      return { list, setList, pending: usePendingChanges('row-b') };
+    });
+    let done!: Promise<unknown>;
+    act(() => {
+      done = optimistic({
+        label: 'delete “B”',
+        key: 'row-b',
+        targets: { set: result.current.setList, apply: (r: Row[]) => r.filter((x) => x.id !== 'b') },
+        request: () => server.promise,
+      });
+    });
+    expect(result.current.list.map((r) => r.id)).toEqual(['a', 'c']);
+    expect(result.current.pending).toHaveLength(1);
+    await act(async () => {
+      server.reject(new Error('no'));
+      await done;
+    });
+    expect(result.current.list.map((r) => r.id)).toEqual(['a', 'b', 'c']);
+    expect(result.current.pending).toHaveLength(0);
+  });
+
+  test('queryTarget cancels the in-flight fetch, writes the cache, and refetches on settle', async () => {
+    const calls: string[] = [];
+    let data: unknown = rows;
+    const client = {
+      cancelQueries: () => void calls.push('cancel'),
+      setQueryData: (_k: readonly unknown[], updater: (old: unknown) => unknown) => {
+        data = updater(data);
+        calls.push('set');
+      },
+      invalidateQueries: () => void calls.push('invalidate'),
+    };
+    await optimistic({
+      label: 'delete “C”',
+      targets: { ...queryTarget<Row[]>(client, ['rows']), apply: (r: Row[]) => r.filter((x) => x.id !== 'c') },
+      request: () => Promise.resolve(),
+    });
+    expect((data as Row[]).map((r) => r.id)).toEqual(['a', 'b']);
+    expect(calls).toEqual(['cancel', 'set', 'invalidate']);
+  });
+
+  test('whenSettled resolves once nothing is pending', async () => {
+    const server = deferred<void>();
+    const done = optimistic({ label: 'save', toast: false, request: () => server.promise });
+    let quiet = false;
+    const waiting = whenSettled().then(() => {
+      quiet = true;
+    });
+    await Promise.resolve();
+    expect(quiet).toBe(false);
+    server.resolve();
+    await done;
+    await waiting;
+    expect(quiet).toBe(true);
+  });
+});

package/src/react/optimistic/optimistic.ts

@@ -0,0 +1,326 @@
+/**
+ * `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, type IdOf, inverseOf } from './revert.js';
+
+/** A setState-shaped writer: takes an updater from the current state to the next. */
+export type Setter<S> = (updater: (current: S) => S) => void;
+
+export interface OptimisticTarget<S> {
+  /** Where the state lives — `setRows` from `useState`, a store's setter, `queryTarget(...)`. */
+  set: Setter<S>;
+  /** The forward change. Pure: React may call it twice in StrictMode. */
+  apply: (current: S) => S;
+  /** Replace the derived rollback — e.g. {@link counterRevert} for a count. */
+  revert?: (current: S, before: S, after: S) => S;
+  /** How array items are told apart, when they carry neither `id` nor `key`. */
+  idOf?: IdOf;
+  /** Runs once, when the change is made — {@link queryTarget} counts its changes in flight here. */
+  begin?: () => void;
+  /** Runs once the request settles either way — {@link queryTarget} refetches the truth here. */
+  settled?: () => void;
+  /**
+   * Which view this state belongs to, when one piece of state is reused for many — a track list
+   * that holds whichever folder is open. Read when the change is made and again when it would be
+   * reverted: if it differs, the state is a different list by now, so the rollback leaves it alone
+   * (that view's next load is the server's truth). Without it, a failed delete made in one folder
+   * would put the row back into whatever folder is open when the refusal arrives.
+   */
+  scope?: () => unknown;
+}
+
+/**
+ * A change to state that is not setState-shaped — an imperative store, a player's queue, a
+ * callback that patches rows. `now` makes the change; `undo` takes it back if the server refuses.
+ * Prefer a {@link OptimisticTarget} when there is a setter: its rollback is derived, and survives
+ * changes made since. An `undo` here is the caller's, so it should undo only what `now` did.
+ */
+export interface OptimisticStep {
+  now: () => void;
+  undo: () => void;
+}
+
+export interface OptimisticOptions<R> {
+  /**
+   * What the user did, as a verb phrase the failure toast completes: `delete “Song”` →
+   * "Couldn't delete “Song”". Also names the change in {@link pendingChanges}.
+   */
+  label: string;
+  /**
+   * The state edits to make at once. Typed loosely on purpose: one change usually spans several
+   * pieces of state of different types (rows, a count, a selection). Each target's own `apply` is
+   * still checked against its `set` where it is written — {@link target} keeps them paired.
+   */
+  targets?: OptimisticTarget<any> | OptimisticStep | ReadonlyArray<OptimisticTarget<any> | OptimisticStep>;
+  /** The server call. A rejection is a failure; anything it resolves to is success. */
+  request: () => Promise<R>;
+  /**
+   * Requests with the same key go one at a time, in order — use the record's id for edits to one
+   * record. No key: the request goes at once.
+   */
+  key?: string;
+  /** After the server said yes — reconcile a temporary id, refresh a summary. Not reverted. */
+  onSuccess?: (result: R) => void;
+  /** After the rollback, beside the toast. */
+  onError?: (error: unknown) => void;
+  /** `false` silences the failure toast (the caller shows the failure itself). Default on. */
+  toast?: boolean;
+  /** The toast's second line. Default: the error's own message. */
+  describeError?: (error: unknown) => string | undefined;
+}
+
+export type OptimisticOutcome<R> = { ok: true; value: R } | { ok: false; error: unknown };
+
+/** Pair a setter with its edit so the two are type-checked against each other. */
+export const target = <S>(t: OptimisticTarget<S>): OptimisticTarget<S> => t;
+
+// ── what is in flight ─────────────────────────────────────────────────────────────────────
+
+export interface PendingChange {
+  id: number;
+  label: string;
+  key?: string;
+  startedAt: number;
+}
+
+let pending: readonly PendingChange[] = [];
+let nextId = 1;
+const listeners = new Set<() => void>();
+const queues = new Map<string, Promise<unknown>>();
+
+const emit = () => {
+  for (const listener of listeners) listener();
+};
+
+/** Every optimistic change whose request has not settled, oldest first. */
+export const pendingChanges = (): readonly PendingChange[] => pending;
+
+/** Subscribe to {@link pendingChanges} — the `useSyncExternalStore` shape. */
+export const subscribePendingChanges = (listener: () => void): (() => void) => {
+  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 = (): Promise<void> =>
+  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: BeforeUnloadEvent) => {
+  event.preventDefault();
+  // Chrome still wants returnValue set; the text itself is never shown.
+  event.returnValue = '';
+};
+
+const track = (change: PendingChange): (() => void) => {
+  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 = <R>(key: string | undefined, task: () => Promise<R>): Promise<R> => {
+  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;
+};
+
+// ── the change ────────────────────────────────────────────────────────────────────────────
+
+interface Applied {
+  rollback: () => void;
+  settled: () => void;
+}
+
+const isStep = (t: OptimisticTarget<unknown> | OptimisticStep): t is OptimisticStep =>
+  typeof (t as OptimisticStep).now === 'function';
+
+function applyStep(step: OptimisticStep): Applied {
+  step.now();
+  return { rollback: step.undo, settled: () => undefined };
+}
+
+function applyTarget<S>(t: OptimisticTarget<S>): Applied {
+  // 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: { before: S; after: S } | undefined;
+  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: unknown): string | undefined => {
+  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<R>(options: OptimisticOptions<R>): Promise<OptimisticOutcome<R>> {
+  const { label, request, key, onSuccess, onError } = options;
+  const targets = options.targets === undefined ? [] : Array.isArray(options.targets) ? options.targets : [options.targets];
+  const applied = (targets as (OptimisticTarget<unknown> | OptimisticStep)[]).map((t) =>
+    isStep(t) ? applyStep(t) : applyTarget(t),
+  );
+  const done = track({ id: nextId++, label, key, startedAt: Date.now() });
+
+  return enqueue(key, request).then(
+    (value): OptimisticOutcome<R> => {
+      done();
+      for (const a of applied) a.settled();
+      onSuccess?.(value);
+      return { ok: true, value };
+    },
+    async (error: unknown): Promise<OptimisticOutcome<R>> => {
+      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 };
+    },
+  );
+}
+
+// ── TanStack Query ────────────────────────────────────────────────────────────────────────
+
+/**
+ * The query-client surface {@link queryTarget} needs — structural, so this module never imports
+ * `@tanstack/react-query` (an optional peer) and a second copy of it cannot break the types.
+ */
+export interface OptimisticQueryClient {
+  cancelQueries: (filters: { queryKey: readonly unknown[]; exact?: boolean }) => unknown;
+  setQueryData: (queryKey: readonly unknown[], updater: (old: unknown) => unknown) => unknown;
+  invalidateQueries: (filters: { queryKey: readonly unknown[] }) => unknown;
+}
+
+/** Changes in flight per cache entry, so the entry is refetched once, after the LAST of them. */
+const inFlight = new Map<string, number>();
+
+/**
+ * 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<S>(
+  client: OptimisticQueryClient,
+  queryKey: readonly unknown[],
+  { refetch = true }: { refetch?: boolean } = {},
+): Pick<OptimisticTarget<S>, 'set' | 'begin' | 'settled'> {
+  const entry = JSON.stringify(queryKey);
+  return {
+    set: (updater) => {
+      void client.cancelQueries({ queryKey, exact: true });
+      client.setQueryData(queryKey, (old) => (old === undefined ? old : updater(old as S)));
+    },
+    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 });
+    },
+  };
+}