cursedbelt 5.89.0 → 5.91.0

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>
+  );
+}

package/src/react/components/DataTable/DataTable.tsx

@@ -260,6 +260,19 @@ export interface DataTableProps<TRow extends Record<string, unknown>> {
    *  lists must never strand the reader without column context — STANDARDS §5c).
    *  Works inside any vertical scroll ancestor (`ScrollArea`). */
   stickyHeader?: boolean;
+  /**
+   * Draw the column-header row. Default `true`.
+   *
+   * `false` for a list whose columns say what they are by their content — music's tracks, where a
+   * title and a length need no `TITLE` / `LENGTH` over them (owner, 2026-10-23: *"remove the row
+   * of table headers like "TITLE" because it will save space and users will already know they are
+   * seeing the title and length"*). The row is collapsed to nothing rather than removed: each `<th>`
+   * keeps its width (a `table-fixed` table takes its column tracks from it) and its name, read by a
+   * screen reader only, so a cell is still announced under its column. What the row carried that a
+   * reader acts on moves: the select-all box to its own line above the rows (the line the phone
+   * cards already draw), and sorting to the caller's own sort control — a hidden header sorts nothing.
+   */
+  columnHeaders?: boolean;
   /**
    * Freeze the FIRST visible column so it stays on screen while the rest of the
    * table scrolls sideways (owner, 2026-08-15, on auth's people matrix: *"if the
@@ -890,6 +903,12 @@ const HIDE_BELOW_CLASS = {
 } as const;
 
 /** `ColDef.priority`'s collapse — {@link HIDE_BELOW_CLASS}'s, unconditional, for the same reason. */
+/**
+ * A header cell of a table whose header row is not drawn (`columnHeaders={false}`): no height, no
+ * rule under it, its width kept — `table-fixed` takes the column tracks from this row — and its
+ * content an sr-only name.
+ */
+const HIDDEN_HEADER_CELL = 'h-0 py-0! border-b-0! leading-none';
 const COLLAPSED_CLASS = 'w-0! min-w-0! p-0! border-0 invisible text-[length:0] [&>*]:hidden';
 const NOTHING_DROPPED: ReadonlySet<string> = new Set();
 
@@ -955,7 +974,8 @@ export function DataTable<TRow extends Record<string, unknown>>({
   hidePagination,
   caption,
   className,
-  stickyHeader,
+  stickyHeader: stickyHeaderProp,
+  columnHeaders = true,
   stickyFirstColumn,
   renderExpanded,
   expandedRowId,
@@ -1006,6 +1026,8 @@ export function DataTable<TRow extends Record<string, unknown>>({
   columnsPersistKey,
   ...passThrough
 }: DataTableProps<TRow>) {
+  // A header that is not drawn has nothing to pin (see `columnHeaders`).
+  const stickyHeader = stickyHeaderProp && columnHeaders;
   // Vertical cell padding for the wide grid tier — the one lever the density knob
   // pulls (headers + body cells stay aligned by sharing it).
   const cellPadY = density === 'compact' ? 'py-1.5' : 'py-2.5';
@@ -1889,11 +1911,12 @@ export function DataTable<TRow extends Record<string, unknown>>({
               beside them: a card grid already reflows, so a second breakpoint
               ladder inside it would only fight the container query. ── */}
           {/* Select-all for the tiers with no header row to carry it: the phone
-              cards, and the card view at every width. */}
-          {selectionShown && (viewMode === 'card' || mobileCards) ? (
+              cards, the card view at every width, and every tier of a table whose header row
+              is not drawn (`columnHeaders`). */}
+          {selectionShown && (viewMode === 'card' || mobileCards || !columnHeaders) ? (
             <div
               data-cb-table-select-all=''
-              className={cn('flex items-center px-2 py-1', viewMode !== 'card' && '@xl:hidden')}
+              className={cn('flex items-center px-2 py-1', viewMode !== 'card' && columnHeaders && '@xl:hidden')}
             >
               {headerCheckbox('Select all')}
             </div>
@@ -2124,7 +2147,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                 });
                 return (
                   <>
-                    {header}
+                    {columnHeaders ? header : null}
                     <div
                       ref={activeTier === 'list' && narrowTiers ? (bodyRef as Ref<HTMLDivElement>) : undefined}
                       className='divide-y divide-border'
@@ -2213,6 +2236,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                             // rides the <th> (not the <tr>) so it pins with stickyHeader.
                             'border-b border-border px-4 text-caption font-bold uppercase tracking-wider text-muted-foreground',
                             cellPadY,
+                            !columnHeaders && HIDDEN_HEADER_CELL,
                             align === 'right' ? 'text-right' : 'text-left',
                             meta?.numeric && 'tabular-nums',
                             // Under `fit` the column takes its CONTENT's width, and a truncating
@@ -2237,7 +2261,11 @@ export function DataTable<TRow extends Record<string, unknown>>({
                         >
                           {h.isPlaceholder
                             ? null
-                            : renderTemplate(h.column.columnDef.header, h.getContext())}
+                            : columnHeaders
+                              ? renderTemplate(h.column.columnDef.header, h.getContext())
+                              : // The name alone, for a screen reader: the header's sort button would be
+                                // a Tab stop nobody can see.
+                                <span className='sr-only'>{labelOf(h.column.id)}</span>}
                         </th>
                       );
                     };
@@ -2254,12 +2282,13 @@ export function DataTable<TRow extends Record<string, unknown>>({
                         data-cb-selection-cell=''
                         className={cn(
                           'w-11 border-b border-border px-0 text-center',
+                          !columnHeaders && HIDDEN_HEADER_CELL,
                           stickyHeader && 'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
                           stickyFirstColumn && 'sticky left-0 bg-card',
                           stickyFirstColumn && (stickyHeader ? 'z-30' : 'z-20'),
                         )}
                       >
-                        {headerCheckbox()}
+                        {columnHeaders ? headerCheckbox() : <span className='sr-only'>Select</span>}
                       </th>
                     ) : null}
                           {hg.headers.filter((h) => !isLeading(h)).map(renderHeader)}
@@ -2275,6 +2304,7 @@ export function DataTable<TRow extends Record<string, unknown>>({
                             : kebabOnly
                               ? 'w-11 border-b border-border px-0'
                               : 'w-20 border-b border-border px-2',
+                          !columnHeaders && HIDDEN_HEADER_CELL,
                           stickyHeader && 'sticky top-0 z-10 bg-card/95 backdrop-blur-sm',
                         )}
                         aria-label='Row actions'

package/src/react/components/DataTable/columnHeaders.spec.tsx

@@ -0,0 +1,83 @@
+import { afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { useState } from 'react';
+import { DataTable, preloadDataTableParts } from './DataTable.js';
+import type { ColDef } from './types.js';
+
+// `columnHeaders={false}` — the owner, 2026-10-23, on music's tracks: *"remove the row of table
+// headers like "TITLE" because it will save space"*. The row is collapsed, not deleted: its
+// widths and its screen-reader names stay, and what a reader acts on in it moves.
+beforeAll(preloadDataTableParts);
+afterEach(cleanup);
+
+interface Song extends Record<string, unknown> {
+  id: string;
+  title: string;
+  seconds: number;
+}
+const COLUMNS: ColDef<Song>[] = [
+  { key: 'title', label: 'Title', type: 'text', sortable: true },
+  { key: 'seconds', label: 'Length', type: 'number', sortable: true, width: 80 },
+];
+const SONGS: Song[] = [
+  { id: 's1', title: 'Alpha', seconds: 10 },
+  { id: 's2', title: 'Beta', seconds: 20 },
+];
+
+function Picking({ columnHeaders }: { columnHeaders: boolean }) {
+  const [selected, setSelected] = useState<ReadonlySet<string>>(new Set());
+  return (
+    <DataTable
+      columnHeaders={columnHeaders}
+      columns={COLUMNS}
+      data={SONGS}
+      getRowId={(row) => row.id}
+      mobileCards={false}
+      onSelectionChange={setSelected}
+      selectedIds={selected}
+      stickyHeader
+    />
+  );
+}
+
+describe('DataTable columnHeaders={false}', () => {
+  test('🔴 no column name is DRAWN, and no sort button stands in the row', () => {
+    const { container } = render(<Picking columnHeaders={false} />);
+    const ths = [...container.querySelectorAll('thead th')];
+    expect(ths.length).toBe(COLUMNS.length + 1);
+    for (const th of ths) {
+      // Every cell is a zero-height cell whose only content is an sr-only name.
+      expect(th.className).toContain('h-0');
+      expect(th.className).not.toContain('sticky');
+      for (const child of th.children) expect(child.className).toContain('sr-only');
+    }
+    expect(container.querySelector('thead button')).toBeNull();
+    expect(container.querySelector('thead [role="checkbox"]')).toBeNull();
+  });
+
+  test('the names are still there for a screen reader, and the widths for the column tracks', () => {
+    const { container } = render(<Picking columnHeaders={false} />);
+    const names = [...container.querySelectorAll('thead th[scope="col"]')].map((th) => th.textContent);
+    expect(names).toEqual(['Select', 'Title', 'Length']);
+    const length = [...container.querySelectorAll('thead th')].find((th) => th.textContent === 'Length') as HTMLElement;
+    expect(length.style.width).toBe('80px');
+  });
+
+  test('select-all moves to its own line above the rows, and still selects', () => {
+    const { container } = render(<Picking columnHeaders={false} />);
+    const line = container.querySelector('[data-cb-table-select-all]') as HTMLElement;
+    expect(line).not.toBeNull();
+    // Shown at every width, not only under the phone breakpoint.
+    expect(line.className).not.toContain('@xl:hidden');
+    fireEvent.click(line.querySelector('[role="checkbox"]') as HTMLElement);
+    expect(container.querySelectorAll('tbody [role="checkbox"][aria-checked="true"]').length).toBe(SONGS.length);
+  });
+
+  test('the default draws the row exactly as before', () => {
+    const { container } = render(<Picking columnHeaders />);
+    expect(container.querySelector('thead button')).not.toBeNull();
+    expect(container.querySelector('thead [role="checkbox"]')).not.toBeNull();
+    expect(container.querySelector('thead th')?.className).toContain('sticky');
+    expect(container.querySelector('[data-cb-table-select-all]')).toBeNull();
+  });
+});

package/src/react/components/Drawer.tsx

@@ -33,6 +33,13 @@ export interface DrawerProps {
   open: boolean;
   onClose: () => void;
   title?: ReactNode;
+  /**
+   * Icon controls on the title's line, before Close — a sidebar drawer's utilities (help, theme,
+   * account, collapse-all), where an app with no top bar keeps them on a phone (owner,
+   * 2026-10-23, music: *"Put all the other header buttons in the side menu"*). One line, so the
+   * drawer spends no second row on them.
+   */
+  actions?: ReactNode;
   /** Width on a left/right drawer, height on a bottom drawer. */
   size?: DrawerSize;
   side?: DrawerSide;
@@ -74,6 +81,7 @@ export function Drawer({
   open,
   onClose,
   title,
+  actions,
   size = 'md',
   side = 'right',
   isDirty,
@@ -149,6 +157,11 @@ export function Drawer({
             ) : (
               <DialogTitle className='sr-only'>Panel</DialogTitle>
             )}
+            {actions ? (
+              <div data-cb-drawer-actions='' className='flex shrink-0 items-center gap-0.5'>
+                {actions}
+              </div>
+            ) : null}
             <IconButton label='Close' onClick={guardedClose}>
               <X />
             </IconButton>

package/src/react/components/Modal.spec.tsx

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
 import { confirm } from '../confirm.js';
+import { Button } from './Button.js';
 import { ConfirmDialog } from './ConfirmDialog.js';
 import { Drawer } from './Drawer.js';
 import { Input } from './Input.js';
@@ -336,6 +337,19 @@ describe('Drawer', () => {
     expect(panel?.className).toContain('max-h-[var(--sheet-h-lg)]');
   });
 
+  test('`actions` stand on the title line, before Close (a phone sidebar keeps its utilities there)', () => {
+    render(
+      <Drawer actions={<Button tooltip='Help'>Help</Button>} open onClose={() => {}} side='left' title='Music'>
+        x
+      </Drawer>,
+    );
+    const slot = document.querySelector('[data-cb-drawer-actions]') as HTMLElement;
+    expect(slot.textContent).toBe('Help');
+    const close = document.querySelector('[data-cb-drawer-handle] button[aria-label="Close"]') as HTMLElement;
+    expect(slot.compareDocumentPosition(close) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(slot.parentElement).toBe(close.parentElement);
+  });
+
   test('left side: slides in from the left', () => {
     render(
       <Drawer open onClose={() => {}} side='left' title='Palette'>

package/src/react/components/Page.spec.tsx

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { cleanup, fireEvent, render } from '@testing-library/react';
+import { Button } from './Button.js';
 import { GuideRoute, GuideSection } from './Guide.js';
 import { PageContainer, PageHeader, ReadableColumn } from './Page.js';
 
@@ -58,6 +59,25 @@ describe('PageHeader — NAV-11: one h1, a one-line subtitle', () => {
     expect(container.querySelector('[data-cb-page-subtitle] button')).toBeNull();
   });
 
+  test('`leading` stands before the title on its line, OUTSIDE the heading', () => {
+    // The phone's sidebar button in an app with no top bar (owner, 2026-10-23, music).
+    const { container } = render(
+      <PageHeader leading={<Button tooltip='Open the sidebar'>Open the sidebar</Button>} title='Queue' />,
+    );
+    const h1 = container.querySelector('h1') as HTMLElement;
+    expect(h1.textContent).toBe('Queue');
+    const slot = container.querySelector('[data-cb-page-header-leading]') as HTMLElement;
+    expect(slot.textContent).toBe('Open the sidebar');
+    expect(slot.contains(h1)).toBe(false);
+    // Before the title, in document order.
+    expect(slot.compareDocumentPosition(h1) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  test('no `leading`, no slot', () => {
+    const { container } = render(<PageHeader title='Queue' />);
+    expect(container.querySelector('[data-cb-page-header-leading]')).toBeNull();
+  });
+
   test('🔴 a subtitle wider than its line gets an InfoHint carrying the whole text', () => {
     const proto = HTMLElement.prototype;
     const scroll = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');

package/src/react/components/Page.tsx

@@ -100,6 +100,14 @@ export function ReadableColumn({ className, ...p }: HTMLAttributes<HTMLDivElemen
 
 export interface PageHeaderProps {
   title: ReactNode;
+  /**
+   * One control BEFORE the title, on its line and outside the heading — the phone's sidebar button,
+   * where an app with no top bar keeps its way into the sidebar (owner, 2026-10-23, music: *"put the
+   * sidebar opening icon for small views to be to the left of the folder or section name … There
+   * will not be a top header row anymore"*; Linear's and Slack's phone layouts). Outside the `h1`,
+   * so the heading's name is the title alone.
+   */
+  leading?: ReactNode;
   /**
    * Inline telemetry beside the title — metric pills (`Badge`/`StatusPill`, e.g.
    * `19 apps` `1 running`), never a raw muted-text counter string that disappears
@@ -154,6 +162,7 @@ const SHORT_LANDSCAPE_TITLE = '[@media(orientation:landscape)_and_(max-height:50
  */
 export function PageHeader({
   title,
+  leading,
   subtitle,
   meta,
   actions,
@@ -167,6 +176,23 @@ export function PageHeader({
 }: PageHeaderProps) {
   const Heading = level === 2 ? 'h2' : 'h1';
   const inContainer = useContext(InPageContainer);
+  const titleBlock = (
+    <div className='min-w-0'>
+      <div className='flex min-w-0 flex-wrap items-baseline gap-x-3 gap-y-1'>
+        <Heading
+          className={cn(
+            'font-bold tracking-tight text-foreground',
+            dense ? 'text-h3' : cn('text-h1', SHORT_LANDSCAPE_TITLE),
+            !titleOnMobile && 'hidden sm:block',
+          )}
+        >
+          {title}
+        </Heading>
+        {meta && <span className='flex flex-wrap items-center gap-1.5'>{meta}</span>}
+      </div>
+      {subtitle && <PageSubtitle dense={dense}>{subtitle}</PageSubtitle>}
+    </div>
+  );
   return (
     <Split
       {...rest}
@@ -184,21 +210,16 @@ export function PageHeader({
         className,
       )}
     >
-      <div className='min-w-0'>
-        <div className='flex min-w-0 flex-wrap items-baseline gap-x-3 gap-y-1'>
-          <Heading
-            className={cn(
-              'font-bold tracking-tight text-foreground',
-              dense ? 'text-h3' : cn('text-h1', SHORT_LANDSCAPE_TITLE),
-              !titleOnMobile && 'hidden sm:block',
-            )}
-          >
-            {title}
-          </Heading>
-          {meta && <span className='flex flex-wrap items-center gap-1.5'>{meta}</span>}
+      {leading != null ? (
+        <div className='flex min-w-0 items-center gap-2'>
+          <span data-cb-page-header-leading='' className='flex shrink-0 items-center'>
+            {leading}
+          </span>
+          {titleBlock}
         </div>
-        {subtitle && <PageSubtitle dense={dense}>{subtitle}</PageSubtitle>}
-      </div>
+      ) : (
+        titleBlock
+      )}
       {(actions || guide) && (
         <div className='flex items-center gap-2'>
           {guide ? <PageGuideButton>{guide}</PageGuideButton> : null}

package/src/react/createApiHooks.spec.tsx

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, type Mock, spyOn, test } from 'bun:test';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act, renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { createApiHooks, OptimisticFailure } from './createApiHooks.js';
+import { toast } from './Toast.js';
+
+type Rom = { id: string; favorite: boolean };
+
+let toastError: Mock<typeof toast.error>;
+beforeEach(() => {
+  toastError = spyOn(toast, 'error').mockImplementation(() => 0);
+});
+afterEach(() => toastError.mockRestore());
+
+const setup = (request: (rom: Rom) => Promise<void>) => {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  queryClient.setQueryData<Rom[]>(['roms'], [{ id: 'r1', favorite: false }]);
+  const appToaster = { success: () => undefined, error: () => undefined };
+  const errorSpy = spyOn(appToaster, 'error');
+  const { useApiMutation } = createApiHooks({ useClient: () => null, useToaster: () => appToaster });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  const { result } = renderHook(
+    () =>
+      useApiMutation<Rom, void>({
+        mutationFn: (_client, rom) => request(rom),
+        optimistic: {
+          label: (rom) => `favorite ${rom.id}`,
+          edits: (rom) => [
+            {
+              queryKey: ['roms'],
+              apply: (roms: Rom[]) => roms.map((r) => (r.id === rom.id ? { ...r, favorite: !r.favorite } : r)),
+            },
+          ],
+        },
+      }),
+    { wrapper },
+  );
+  return { queryClient, result, errorSpy };
+};
+
+describe('useApiMutation — optimistic', () => {
+  test('the cache changes before the request settles', async () => {
+    let finish!: () => void;
+    const { queryClient, result } = setup(() => new Promise<void>((resolve) => (finish = resolve)));
+    let done!: Promise<void>;
+    act(() => {
+      done = result.current.mutateAsync({ id: 'r1', favorite: false });
+    });
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(queryClient.getQueryData<Rom[]>(['roms'])?.[0]?.favorite).toBe(true);
+    await act(async () => {
+      finish();
+      await done;
+    });
+  });
+
+  test('a refusal reverts the cache, shows ONE Retry toast, and rejects with the cause', async () => {
+    const { queryClient, result, errorSpy } = setup(() => Promise.reject(new Error('nope')));
+    let caught: unknown;
+    await act(async () => {
+      await result.current.mutateAsync({ id: 'r1', favorite: false }).catch((e: unknown) => {
+        caught = e;
+      });
+    });
+    expect(queryClient.getQueryData<Rom[]>(['roms'])?.[0]?.favorite).toBe(false);
+    expect(caught).toBeInstanceOf(OptimisticFailure);
+    expect((caught as Error).cause).toBeInstanceOf(Error);
+    expect(toastError).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+});

package/src/react/createApiHooks.ts

@@ -6,6 +6,8 @@ import {
   useQueryClient,
 } from '@tanstack/react-query';
 import type { ReactNode } from 'react';
+import { type OptimisticQueryClient, optimistic as runOptimistic, queryTarget } from './optimistic/optimistic.js';
+import type { IdOf } from './optimistic/revert.js';
 
 // IMPORTANT: this factory's PUBLIC surface is deliberately free of @tanstack's
 // class-shaped types (UseQueryResult/UseQueryOptions/QueryClient). Those carry
@@ -121,6 +123,32 @@ export interface ApiMutationConfig<Client, TArgs, TData> {
   onSuccess?: (data: TData, args: TArgs) => void;
   /** Extra error handling, in addition to the automatic error toast. */
   onError?: (error: unknown, args: TArgs) => void;
+  /**
+   * Show the change before the server answers (STA-10). Each edit is a cache entry and the
+   * forward change to its data; the rollback is derived, and a refusal reverts only what this
+   * call touched and toasts "Couldn't <label>" with Retry — in place of the plain error toast.
+   * Every edited key is refetched once the request settles.
+   *
+   *   optimistic: {
+   *     label: (rom) => `favorite “${rom.title}”`,
+   *     edits: (rom) => [{ queryKey: ['roms'], apply: (roms: Rom[]) => roms.map(...) }],
+   *   }
+   */
+  optimistic?: ApiOptimistic<TArgs>;
+}
+
+export interface ApiOptimistic<TArgs> {
+  /** The verb phrase the failure toast completes: "Couldn't " + label. */
+  label: string | ((args: TArgs) => string);
+  /** The cache entries to change at once, each with its forward edit. */
+  edits: (args: TArgs) => ReadonlyArray<{
+    queryKey: QueryKey;
+    apply: (data: any) => any;
+    /** How the entry's array items are told apart when they carry neither `id` nor `key`. */
+    idOf?: IdOf;
+  }>;
+  /** Serialize requests that share a key — e.g. the record's id. */
+  key?: (args: TArgs) => string;
 }
 
 export interface ApiHooks<Client> {
@@ -130,6 +158,14 @@ export interface ApiHooks<Client> {
   ) => ApiMutationResult<TArgs, TData>;
 }
 
+/** The rejection an optimistic mutation's `mutateAsync` gives: the server's own error is `cause`. */
+export class OptimisticFailure extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = 'OptimisticFailure';
+  }
+}
+
 /**
  * Build a pair of TanStack-Query hooks bound to your app's request client + toaster.
  * Standardizes the data-fetching boilerplate every app reinvents: apply a fallback
@@ -182,12 +218,28 @@ export const createApiHooks = <Client>({
     invalidate,
     onSuccess,
     onError,
+    optimistic,
   }: ApiMutationConfig<Client, TArgs, TData>): ApiMutationResult<TArgs, TData> => {
     const client = useClient();
     const queryClient = useQueryClient();
     const toaster = useToaster?.();
     return useMutation<TData, unknown, TArgs>({
-      mutationFn: (args) => mutationFn(client, args),
+      mutationFn: optimistic
+        ? async (args) => {
+            const outcome = await runOptimistic({
+              label: typeof optimistic.label === 'function' ? optimistic.label(args) : optimistic.label,
+              key: optimistic.key?.(args),
+              targets: optimistic.edits(args).map(({ queryKey, apply, idOf }) => ({
+                ...queryTarget(queryClient as unknown as OptimisticQueryClient, queryKey),
+                apply,
+                ...(idOf ? { idOf } : {}),
+              })),
+              request: () => mutationFn(client, args),
+            });
+            if (!outcome.ok) throw new OptimisticFailure(outcome.error);
+            return outcome.value;
+          }
+        : (args) => mutationFn(client, args),
       onSuccess: (data, args) => {
         if (successToast && toaster) {
           toaster.success(
@@ -201,6 +253,11 @@ export const createApiHooks = <Client>({
         onSuccess?.(data, args);
       },
       onError: (error, args) => {
+        // An optimistic call has already reverted and shown its own Retry toast.
+        if (error instanceof OptimisticFailure) {
+          onError?.(error.cause, args);
+          return;
+        }
         toaster?.error(error);
         onError?.(error, args);
       },

package/src/react/file-tree/FileTree.spec.tsx

@@ -678,6 +678,20 @@ describe('where you are', () => {
     expect(scrolled).toEqual(['Dinos']);
   });
 
+  test('🔴 a revealed row lands in the MIDDLE of the tree, as VS Code lands it — not on its last line', () => {
+    // Owner, 2026-10-23: `nearest` parked a row revealed from below at the bottom of the sidebar.
+    const asked: (ScrollIntoViewOptions | boolean | undefined)[] = [];
+    const view = tree({ selectedId: null });
+    for (const row of screen.getAllByRole('treeitem') as HTMLElement[]) {
+      row.scrollIntoView = (options?: ScrollIntoViewOptions | boolean) => asked.push(options);
+      row.getBoundingClientRect = () => ({ top: 900, bottom: 920 }) as DOMRect;
+    }
+    (view.container.querySelector('.cbft-scroll') as HTMLElement).getBoundingClientRect = () =>
+      ({ top: 0, bottom: 400 }) as DOMRect;
+    view.rerender(<FileTree nodes={TREE} selectedId='dinos' onSelect={() => undefined} />);
+    expect(asked).toEqual([{ block: 'center', inline: 'nearest' }]);
+  });
+
   test('a row already in view does not jump', () => {
     const scrolled: string[] = [];
     const view = tree({ selectedId: null });

package/src/react/file-tree/FileTree.tsx

@@ -1462,9 +1462,15 @@ export function FileTree({
      */
     const frame = (scroll === 'host' ? hostScroller(scroller) : scroller).getBoundingClientRect();
     if (box.top >= frame.top && box.bottom <= frame.bottom) return;
-    // `nearest` on both axes: the least movement that makes the row visible, and no sideways
-    // travel in a list that does not scroll sideways.
-    row.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+    // 🔴 `center`, as VS Code's explorer lands a revealed file: in the middle of the tree, with its
+    // neighbors above and below it, wherever the scroll has room (the browser clamps it at either
+    // end). It was `nearest`, the least movement, which parked a row revealed from below on the
+    // tree's last line — owner, 2026-10-23, music's "Show in folders": *"have them show the
+    // highlighted track in the middle of the screen when there is enough scroll space, instead of
+    // letting them be at other places like at the bottom of the side menu. This is how vscode shows
+    // files when you click between them in the file tree."* `nearest` sideways: no travel in a list
+    // that does not scroll sideways.
+    row.scrollIntoView({ block: 'center', inline: 'nearest' });
   }, [selectedId, revealOpened, revealKey]);
 
   // ── The drag ──────────────────────────────────────────────────────────────────────────