cursedbelt 5.17.0 → 5.19.0

package/dist/styles-areas/fields.css

@@ -18,7 +18,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 114 candidate(s).
+ * 115 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -39,9 +39,9 @@
 @source inline("group-focus-within:opacity-100 h-12 h-3.5 h-5 h-[420px]");
 @source inline("has-[[aria-invalid=true]]:border-field-error hover:bg-border hover:bg-destructive/10");
 @source inline("hover:bg-muted/50 hover:border-field-ring hover:scale-110 hover:text-warning italic leading-5");
-@source inline("left-0 list-none max-h-64 max-h-[40dvh] max-h-[65dvh] max-h-[85dvh] max-w-40 min-h-20 min-w-24");
-@source inline("min-w-64 min-w-[var(--anchor-width)] min-w-max mix-blend-difference mr-2 p-1.5 pl-1.5 pl-2");
-@source inline("pl-2.5 pointer-coarse:before:absolute pointer-coarse:before:bottom-[-10px]");
+@source inline("left-0 left-2.5 list-none max-h-64 max-h-[40dvh] max-h-[65dvh] max-h-[85dvh] max-w-40 min-h-20");
+@source inline("min-w-24 min-w-64 min-w-[var(--anchor-width)] min-w-max mix-blend-difference mr-2 p-1.5 pl-1.5");
+@source inline("pl-2 pl-2.5 pointer-coarse:before:absolute pointer-coarse:before:bottom-[-10px]");
 @source inline("pointer-coarse:before:left-[-4px] pointer-coarse:before:right-[-4px]");
 @source inline("pointer-coarse:before:top-[-10px] pointer-coarse:items-center pr-1 pr-16 pr-2 pr-3 pr-9");
 @source inline("resize-none resize-y right-1.5 right-3 ring-accent/30 ring-field-error/30 rounded-l-xl");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.17.0",
+	"version": "5.19.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.",
@@ -750,7 +750,7 @@
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
 		"cmdk": "^1.1.1",
-		"cursedbelt-core": "^2.6.0",
+		"cursedbelt-core": "^2.10.0",
 		"cwip": "^4.6.0",
 		"lucide-react": "^1.21.0",
 		"react-hook-form": "^7.80.0",

package/scripts/styleAreas.ts

@@ -150,6 +150,7 @@ export const AREAS: readonly Area[] = [
 			'components/Button.tsx',
 			'components/ButtonGroup.tsx',
 			'components/ButtonLink.tsx',
+			'components/CardDisplayControls.tsx',
 			'components/CardTapTarget.tsx',
 			'components/Checkbox.tsx',
 			'components/ChoiceGroup.tsx',
@@ -251,6 +252,7 @@ export const AREAS: readonly Area[] = [
 			'components/OtpInput.tsx',
 			'components/RatingField.tsx',
 			'components/RenderField.tsx',
+			'components/SearchInput.tsx',
 			'components/SecretInput.tsx',
 			'components/SliderField.tsx',
 			'components/StarRating.tsx',

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

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import type { CardDisplay } from '../lib/cardDisplay.js';
+import { CardDisplayControls } from './CardDisplayControls.js';
+
+afterEach(cleanup);
+
+const LARGE_WITH_WORDS: CardDisplay = { size: 'large', captions: true };
+
+describe('CardDisplayControls', () => {
+  test('a size segment reports the size, keeping the captions choice', () => {
+    const onChange = mock((_: CardDisplay) => {});
+    const { getByTestId } = render(
+      <CardDisplayControls value={{ size: 'large', captions: false }} onChange={onChange} />,
+    );
+    // Radix Tabs activates on mousedown, not click.
+    fireEvent.mouseDown(getByTestId('card-size-small'), { button: 0 });
+    expect(onChange).toHaveBeenLastCalledWith({ size: 'small', captions: false });
+  });
+
+  test('the captions toggle flips the words and keeps the size, pressed when they are hidden', () => {
+    const onChange = mock((_: CardDisplay) => {});
+    const { getByTestId, rerender } = render(
+      <CardDisplayControls value={{ size: 'medium', captions: true }} onChange={onChange} captionsNoun='film titles' imageNoun='posters' />,
+    );
+    const toggle = getByTestId('card-captions');
+    expect(toggle.getAttribute('aria-pressed')).toBe('false');
+    expect(toggle.getAttribute('aria-label')).toBe('Hide film titles — show the posters only');
+    fireEvent.click(toggle);
+    expect(onChange).toHaveBeenLastCalledWith({ size: 'medium', captions: false });
+
+    rerender(
+      <CardDisplayControls value={{ size: 'medium', captions: false }} onChange={onChange} captionsNoun='film titles' imageNoun='posters' />,
+    );
+    expect(getByTestId('card-captions').getAttribute('aria-pressed')).toBe('true');
+    expect(getByTestId('card-captions').getAttribute('aria-label')).toBe('Show film titles under the posters');
+  });
+
+  test('offers only the sizes asked for, with the labels asked for', () => {
+    const { queryByTestId, getByTestId } = render(
+      <CardDisplayControls
+        value={LARGE_WITH_WORDS}
+        onChange={() => {}}
+        sizes={['large', 'small']}
+        sizeLabels={{ small: 'Tiny' }}
+      />,
+    );
+    expect(queryByTestId('card-size-medium')).toBeNull();
+    expect(getByTestId('card-size-large').textContent).toBe('L');
+    expect(getByTestId('card-size-small').textContent).toBe('Tiny');
+  });
+
+  test('a disabled reason leaves both controls visible and inert', () => {
+    const onChange = mock((_: CardDisplay) => {});
+    const { getByTestId } = render(
+      <CardDisplayControls
+        value={LARGE_WITH_WORDS}
+        onChange={onChange}
+        sizeDisabledReason='Card size applies to the grid view'
+        captionsDisabledReason='Titles are always shown in the list view'
+      />,
+    );
+    const small = getByTestId('card-size-small') as HTMLButtonElement;
+    const toggle = getByTestId('card-captions') as HTMLButtonElement;
+    expect(small.disabled).toBe(true);
+    expect(toggle.disabled).toBe(true);
+    fireEvent.mouseDown(small, { button: 0 });
+    fireEvent.click(toggle);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

package/src/react/components/CardDisplayControls.tsx

@@ -0,0 +1,120 @@
+import type { ReactNode } from 'react';
+import { cn } from '../lib/cn.js';
+import type { ControlSize } from '../lib/field.js';
+import { IconButton } from './IconButton.js';
+import { SegmentedControl } from './SegmentedControl.js';
+import { Tooltip } from './Tooltip.js';
+import { CARD_SIZES, type CardDisplay, type CardSize } from '../lib/cardDisplay.js';
+
+const DEFAULT_SIZE_LABELS: Readonly<Record<CardSize, ReactNode>> = { large: 'L', medium: 'M', small: 'S' };
+
+const capitalized = (word: string): string => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`;
+
+export interface CardDisplayControlsProps {
+  value: CardDisplay;
+  onChange: (next: CardDisplay) => void;
+  /** Which sizes to offer, in order. Default {@link CARD_SIZES}. */
+  sizes?: readonly CardSize[];
+  /** What each segment says. Default `L` / `M` / `S`. */
+  sizeLabels?: Partial<Record<CardSize, ReactNode>>;
+  /** What the words under a card are called, lower-case — `"game titles"`. Default `"titles"`. */
+  captionsNoun?: string;
+  /** What the image is called, lower-case — `"art"`, `"posters"`. Default `"images"`. */
+  imageNoun?: string;
+  /**
+   * Set when the size does not apply (a list view). The segments stay VISIBLE and inert with
+   * this on hover — one UI, never a hidden control.
+   */
+  sizeDisabledReason?: string | null;
+  /** The same, for the captions toggle — `"Titles are always shown in the list view"`. */
+  captionsDisabledReason?: string | null;
+  /** Height on the shared control scale. Default `sm` — this sits in a toolbar. */
+  controlSize?: Extract<ControlSize, 'sm' | 'md'>;
+  className?: string;
+}
+
+/**
+ * The S / M / L switch and the captions toggle, side by side. The why, and the model it draws,
+ * are in `../lib/cardDisplay.ts`.
+ *
+ * Controlled: the app owns the state and where it is kept (`useCardDisplay` is the hook for
+ * that). The captions toggle is `aria-pressed` when the words are HIDDEN — pressing it is the act
+ * of hiding them, and its icon shows the card with or without its lines.
+ *
+ * Test hooks: `card-size-<size>` on each segment and `card-captions` on the toggle.
+ */
+export function CardDisplayControls({
+  value,
+  onChange,
+  sizes = CARD_SIZES,
+  sizeLabels,
+  captionsNoun = 'titles',
+  imageNoun = 'images',
+  sizeDisabledReason = null,
+  captionsDisabledReason = null,
+  controlSize = 'sm',
+  className,
+}: CardDisplayControlsProps) {
+  const labels = { ...DEFAULT_SIZE_LABELS, ...sizeLabels };
+  const { captions } = value;
+  const toggle = (
+    <IconButton
+      size={controlSize}
+      variant='ghost'
+      disabled={captionsDisabledReason !== null}
+      onClick={() => onChange({ ...value, captions: !captions })}
+      aria-pressed={!captions}
+      data-testid='card-captions'
+      label={
+        captions
+          ? `Hide ${captionsNoun} — show the ${imageNoun} only`
+          : `Show ${captionsNoun} under the ${imageNoun}`
+      }
+      tooltip={captions ? `${capitalized(imageNoun)} only — hide the ${captionsNoun}` : `Show the ${captionsNoun}`}
+    >
+      <svg
+        viewBox='0 0 24 24'
+        fill='none'
+        stroke='currentColor'
+        strokeWidth={2}
+        strokeLinecap='round'
+        strokeLinejoin='round'
+        aria-hidden='true'
+      >
+        <rect x='4' y='3' width='16' height='12' rx='1.5' />
+        {captions ? (
+          <>
+            <line x1='4' y1='18.5' x2='20' y2='18.5' />
+            <line x1='4' y1='21.5' x2='14' y2='21.5' />
+          </>
+        ) : null}
+      </svg>
+    </IconButton>
+  );
+  return (
+    <div className={cn('inline-flex items-center gap-1', className)} data-cb-card-display=''>
+      <SegmentedControl<CardSize>
+        size={controlSize}
+        aria-label='Card size'
+        value={value.size}
+        onChange={(size) => onChange({ ...value, size })}
+        options={sizes.map((size) => ({
+          value: size,
+          label: labels[size],
+          disabled: sizeDisabledReason !== null,
+          tooltip: sizeDisabledReason ?? `${capitalized(size)} cards`,
+          'data-testid': `card-size-${size}`,
+        }))}
+      />
+      {captionsDisabledReason === null ? (
+        toggle
+      ) : (
+        // A disabled button takes no pointer events, so its own tooltip can never open —
+        // the span carries the reason instead (SegmentedControl does the same per segment).
+        <Tooltip content={captionsDisabledReason}>
+          <span className='inline-flex'>{toggle}</span>
+        </Tooltip>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { SearchInput } from './SearchInput.js';
+
+afterEach(cleanup);
+
+const badge = (container: HTMLElement) => container.querySelector('[data-testid="search-syntax-badge"]');
+
+describe('SearchInput', () => {
+  test('reports what was typed, not an event', () => {
+    const onChange = mock((_: string) => {});
+    const { getByRole } = render(<SearchInput value='' onChange={onChange} placeholder='Search films' />);
+    const input = getByRole('searchbox');
+    expect(input.getAttribute('aria-label')).toBe('Search films');
+    fireEvent.change(input, { target: { value: 'hunt*red' } });
+    expect(onChange).toHaveBeenLastCalledWith('hunt*red');
+  });
+
+  test('no badge while the text is plain words — the nine searches in ten', () => {
+    const { container } = render(<SearchInput value='the office' onChange={() => {}} />);
+    expect(badge(container)).toBeNull();
+  });
+
+  test('a star shows the wildcard badge, and the input makes room for it', () => {
+    const { container, getByRole } = render(<SearchInput value='the*the' onChange={() => {}} />);
+    expect(badge(container)?.getAttribute('data-kind')).toBe('wildcard');
+    expect(badge(container)?.getAttribute('aria-label')).toBe('Wildcard search');
+    expect(getByRole('searchbox').className).toContain('pr-9');
+  });
+
+  test('syntax={false} makes a star an ordinary character', () => {
+    const { container } = render(<SearchInput value='M*A*S*H' onChange={() => {}} syntax={false} />);
+    expect(badge(container)).toBeNull();
+  });
+
+  test('regex is off unless asked for; on, a broken one paints the field invalid', () => {
+    const off = render(<SearchInput value='/(broken/' onChange={() => {}} />);
+    expect(badge(off.container)).toBeNull();
+    off.unmount();
+
+    const on = render(<SearchInput value='/(broken/' onChange={() => {}} syntax={{ regex: true }} />);
+    expect(badge(on.container)?.getAttribute('data-kind')).toBe('invalid');
+    expect(on.getByRole('searchbox').getAttribute('aria-invalid')).toBe('true');
+  });
+
+  test('a working regex gets its own badge and a valid field', () => {
+    const { container, getByRole } = render(
+      <SearchInput value='/^the (mask|agony)/' onChange={() => {}} syntax={{ regex: true }} />,
+    );
+    expect(badge(container)?.getAttribute('data-kind')).toBe('regex');
+    expect(getByRole('searchbox').getAttribute('aria-invalid')).toBeNull();
+  });
+
+  test('showSyntaxBadge={false} hides it without changing what the text means', () => {
+    const { container, getByRole } = render(<SearchInput value='hunt*red' onChange={() => {}} showSyntaxBadge={false} />);
+    expect(badge(container)).toBeNull();
+    expect(getByRole('searchbox').className).not.toContain('pr-9');
+  });
+});

package/src/react/components/SearchInput.tsx

@@ -0,0 +1,117 @@
+import { Asterisk, Regex, Search, TriangleAlert } from 'lucide-react';
+import { useMemo } from 'react';
+import {
+  parseSearchPattern,
+  type SearchPattern,
+  type SearchSyntaxOptions,
+} from 'cursedbelt-core/search-pattern';
+import { cn } from '../lib/cn.js';
+import { Input, type InputProps } from './Input.js';
+import { Tooltip } from './Tooltip.js';
+
+export interface SearchInputProps extends Omit<InputProps, 'value' | 'onChange' | 'type'> {
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Which syntaxes the box understands — the SAME options the app hands
+   * `parseSearchPattern` when it runs the query, so the badge here is the syntax
+   * the query ran in. Default: `*` wildcard on, `/regex/` off. `false` is plain
+   * text only (a `*` is just a character).
+   */
+  syntax?: SearchSyntaxOptions | false;
+  /** Show the badge that says a wildcard or regex is in play. Default `true`. */
+  showSyntaxBadge?: boolean;
+  /** Classes for the wrapper, which carries the width. */
+  className?: string;
+  /** Classes for the `<input>` itself — colours, radius, text size. */
+  inputClassName?: string;
+}
+
+const PLAIN_ONLY: SearchSyntaxOptions = { wildcard: false, regex: false };
+
+/** What the badge says, per pattern kind that has one. */
+function badgeFor(pattern: SearchPattern) {
+  switch (pattern.kind) {
+    case 'wildcard':
+      return {
+        icon: Asterisk,
+        label: 'Wildcard search',
+        tip: '* matches any characters, in order — hunt*red finds The Hunt for Red October.',
+      };
+    case 'regex':
+      return { icon: Regex, label: 'Regular expression', tip: `Matching /${pattern.source}/, ignoring case.` };
+    case 'invalid':
+      return { icon: TriangleAlert, label: 'Search cannot run', tip: pattern.message };
+    default:
+      return null;
+  }
+}
+
+/**
+ * The one search box — a magnifier, a themed {@link Input}, and a badge the
+ * moment the text stops being plain words.
+ *
+ * ── Why a badge, and only then ──────────────────────────────────────────────
+ * `*` means "any characters" here (owner request via flix, 2026-09-28 —
+ * `cursedbelt-core/search-pattern` has the whole semantics). A search that
+ * silently changed meaning when a star appeared would read as a bug the first
+ * time it returned something the words alone would not; a badge that is ALWAYS
+ * there is noise for the nine searches in ten that are plain. So it appears
+ * exactly while a syntax is in play, and its tooltip is where a viewer learns
+ * what the star does. An uncompilable regex paints the field invalid
+ * (`aria-invalid`, the Input's own error state) and the tooltip says why.
+ *
+ * Parsing is the app's too: this component only DISPLAYS the pattern. An app
+ * that filters in memory calls `createSearchMatcher(value, syntax)`; one that
+ * queries a server parses there with the same options.
+ */
+export function SearchInput({
+  value,
+  onChange,
+  syntax,
+  showSyntaxBadge = true,
+  className,
+  inputClassName,
+  placeholder = 'Search…',
+  'aria-label': ariaLabel,
+  ...inputProps
+}: SearchInputProps) {
+  const pattern = useMemo(() => parseSearchPattern(value, syntax === false ? PLAIN_ONLY : syntax), [value, syntax]);
+  const badge = showSyntaxBadge ? badgeFor(pattern) : null;
+  const invalid = pattern.kind === 'invalid';
+
+  return (
+    <div className={cn('relative min-w-0', className)}>
+      <Search
+        aria-hidden
+        className='-translate-y-1/2 pointer-events-none absolute top-1/2 left-2.5 size-4 text-muted-foreground'
+      />
+      <Input
+        {...inputProps}
+        type='search'
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+        placeholder={placeholder}
+        aria-label={ariaLabel ?? (typeof placeholder === 'string' ? placeholder : 'Search')}
+        aria-invalid={invalid || undefined}
+        className={cn('pl-8', badge && 'pr-9', inputClassName)}
+      />
+      {badge ? (
+        <Tooltip content={badge.tip} side='bottom' multiline>
+          <span
+            role='img'
+            aria-label={badge.label}
+            data-testid='search-syntax-badge'
+            data-kind={pattern.kind}
+            className={cn(
+              '-translate-y-1/2 absolute top-1/2 right-2 inline-flex size-6 items-center justify-center rounded-full',
+              invalid ? 'bg-destructive/15 text-destructive' : 'bg-primary/15 text-primary',
+            )}
+          >
+            <badge.icon className='size-3.5' aria-hidden />
+          </span>
+        </Tooltip>
+      ) : null}
+    </div>
+  );
+}

package/src/react/hooks/useCardDisplay.spec.tsx

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
+import type { CardDisplay } from '../lib/cardDisplay.js';
+import { useCardDisplay } from './useCardDisplay.js';
+
+afterEach(cleanup);
+
+const WAIT = 20;
+const settle = () => new Promise((resolve) => setTimeout(resolve, WAIT * 3));
+
+type Save = (display: CardDisplay, options: { keepalive: boolean }) => void | Promise<void>;
+const saver = (impl?: Save) => mock<Save>(impl ?? (() => {}));
+
+describe('useCardDisplay', () => {
+  test('starts from `initial`, or large cards with their words', () => {
+    expect(renderHook(() => useCardDisplay({ save: () => {} })).result.current.value).toEqual({
+      size: 'large',
+      captions: true,
+    });
+    const { result } = renderHook(() =>
+      useCardDisplay({ save: () => {}, initial: () => ({ size: 'small', captions: false }) }),
+    );
+    expect(result.current.value).toEqual({ size: 'small', captions: false });
+    expect(result.current.ready).toBe(true);
+  });
+
+  test('draws a change at once and keeps only the SETTLED value of a burst, once', async () => {
+    const save = saver();
+    const { result } = renderHook(() => useCardDisplay({ save, debounceMs: WAIT }));
+    act(() => result.current.setValue({ size: 'medium', captions: true }));
+    act(() => result.current.setValue({ size: 'small', captions: true }));
+    act(() => result.current.setValue({ size: 'small', captions: false }));
+    expect(result.current.value).toEqual({ size: 'small', captions: false });
+    expect(save).not.toHaveBeenCalled();
+    await settle();
+    expect(save).toHaveBeenCalledTimes(1);
+    expect(save).toHaveBeenLastCalledWith({ size: 'small', captions: false }, { keepalive: false });
+  });
+
+  test('a burst that ends where it started saves nothing', async () => {
+    const save = saver();
+    const { result } = renderHook(() => useCardDisplay({ save, debounceMs: WAIT }));
+    act(() => result.current.setValue({ size: 'large', captions: false }));
+    act(() => result.current.setValue({ size: 'large', captions: true }));
+    await settle();
+    expect(save).not.toHaveBeenCalled();
+  });
+
+  test('adopts the stored choice, and a stored equal value is not written back', async () => {
+    const save = saver();
+    const { result } = renderHook(() =>
+      useCardDisplay({ save, debounceMs: WAIT, load: async () => ({ size: 'medium', captions: false }) }),
+    );
+    expect(result.current.ready).toBe(false);
+    await waitFor(() => expect(result.current.ready).toBe(true));
+    expect(result.current.value).toEqual({ size: 'medium', captions: false });
+    act(() => result.current.setValue({ size: 'small', captions: false }));
+    act(() => result.current.setValue({ size: 'medium', captions: false }));
+    await settle();
+    expect(save).not.toHaveBeenCalled();
+  });
+
+  test('🔴 a tap made while the stored choice is in flight wins over it', async () => {
+    let answer: (value: Partial<CardDisplay>) => void = () => {};
+    const save = saver();
+    const { result } = renderHook(() =>
+      useCardDisplay({
+        save,
+        debounceMs: WAIT,
+        load: () => new Promise<Partial<CardDisplay>>((resolve) => (answer = resolve)),
+      }),
+    );
+    act(() => result.current.setValue({ size: 'small', captions: true }));
+    await act(async () => answer({ size: 'medium', captions: false }));
+    await waitFor(() => expect(result.current.ready).toBe(true));
+    expect(result.current.value).toEqual({ size: 'small', captions: true });
+    await settle();
+    expect(save).toHaveBeenLastCalledWith({ size: 'small', captions: true }, { keepalive: false });
+  });
+
+  test('a malformed stored value is ignored field by field; a failed read keeps what is drawn', async () => {
+    const { result } = renderHook(() =>
+      useCardDisplay({ save: () => {}, load: async () => ({ size: 'huge' as never, captions: false }) }),
+    );
+    await waitFor(() => expect(result.current.value).toEqual({ size: 'large', captions: false }));
+
+    const failed = renderHook(() =>
+      useCardDisplay({ save: () => {}, load: () => Promise.reject(new Error('500')) }),
+    );
+    await waitFor(() => expect(failed.result.current.ready).toBe(true));
+    expect(failed.result.current.value).toEqual({ size: 'large', captions: true });
+  });
+
+  test('does not read until enabled', async () => {
+    const load = mock(async () => ({ size: 'small' as const }));
+    const { result, rerender } = renderHook(({ on }) => useCardDisplay({ save: () => {}, load, enabled: on }), {
+      initialProps: { on: false },
+    });
+    expect(result.current.ready).toBe(true);
+    expect(load).not.toHaveBeenCalled();
+    rerender({ on: true });
+    await waitFor(() => expect(result.current.value.size).toBe('small'));
+    expect(load).toHaveBeenCalledTimes(1);
+  });
+
+  test('🔴 a rejected save is not counted as kept — the same value goes again', async () => {
+    let fail = true;
+    const save = saver(() => (fail ? Promise.reject(new Error('offline')) : undefined));
+    const { result } = renderHook(() => useCardDisplay({ save, debounceMs: WAIT }));
+    act(() => result.current.setValue({ size: 'small', captions: true }));
+    await settle();
+    expect(save).toHaveBeenCalledTimes(1);
+    fail = false;
+    act(() => result.current.setValue({ size: 'small', captions: true }));
+    await settle();
+    expect(save).toHaveBeenCalledTimes(2);
+  });
+
+  test('a change still pending when the page hides or the view unmounts is kept, with keepalive', async () => {
+    const save = saver();
+    const { result, unmount } = renderHook(() => useCardDisplay({ save, debounceMs: 10_000 }));
+    act(() => result.current.setValue({ size: 'medium', captions: true }));
+    globalThis.dispatchEvent(new Event('pagehide'));
+    expect(save).toHaveBeenLastCalledWith({ size: 'medium', captions: true }, { keepalive: true });
+
+    act(() => result.current.setValue({ size: 'small', captions: true }));
+    unmount();
+    expect(save).toHaveBeenLastCalledWith({ size: 'small', captions: true }, { keepalive: true });
+    expect(save).toHaveBeenCalledTimes(2);
+  });
+});