@asteby/metacore-runtime-react 39.3.0 → 41.0.0

package/dist/use-optimistic-mutation.d.ts

@@ -0,0 +1,73 @@
+import { type QueryKey } from '@tanstack/react-query';
+export interface UseOptimisticMutationOptions<TData, TVariables, TCache> {
+    /** Query whose cached value the mutation changes. */
+    queryKey: QueryKey;
+    mutationFn: (variables: TVariables) => Promise<TData>;
+    /**
+     * Cache value to show while the request is in flight. Runs synchronously on
+     * `mutate`, so the UI repaints on the same frame as the click. Return
+     * `undefined` to leave the cache untouched.
+     */
+    optimistic: (current: TCache | undefined, variables: TVariables) => TCache | undefined;
+    /**
+     * Cache value once the server confirms. Write/apply endpoints that return
+     * the resulting resource should map it here, so nothing is refetched.
+     * Default: keep the optimistic value.
+     */
+    reconcile?: (data: TData, variables: TVariables, current: TCache | undefined) => TCache | undefined;
+    /**
+     * Coalesce bursts (drag and drop, sliders): the cache updates on every
+     * call, and only the last variables are sent once `debounceMs` pass
+     * without a new call. Pending work is flushed on unmount.
+     */
+    debounceMs?: number;
+    /**
+     * A call equal to the one already in flight is ignored (double clicks).
+     * Default: structural equality via JSON.
+     */
+    isEqual?: (a: TVariables, b: TVariables) => boolean;
+    /** Other queries to refresh in the background after a confirmed write. */
+    invalidate?: QueryKey[];
+    onSuccess?: (data: TData, variables: TVariables) => void;
+    /**
+     * Runs after the cache was rolled back to the last confirmed value. Only
+     * the latest call reports: a superseded write that fails stays silent.
+     */
+    onError?: (error: unknown, variables: TVariables) => void;
+}
+export interface UseOptimisticMutationResult<TVariables> {
+    /** Apply optimistically and persist. Safe to call repeatedly. */
+    mutate: (variables: TVariables) => void;
+    /** True from the first `mutate` until the last one settles. */
+    isPending: boolean;
+    /** Variables of the latest unconfirmed call (e.g. which card is applying). */
+    pendingVariables: TVariables | undefined;
+    error: unknown;
+    /** Re-send the variables of the last call that failed (toast "Reintentar"). */
+    retry: () => void;
+}
+/**
+ * Optimistic write over a TanStack Query cache entry, with rollback.
+ *
+ * ```tsx
+ * const apply = useOptimisticMutation({
+ *   queryKey: ['org-sidebar-layout'],
+ *   mutationFn: (key: string) => api.post('/apply', { key }).then((r) => r.data),
+ *   optimistic: (current, key) => ({ ...current, template_key: key }),
+ *   reconcile: (server) => server,
+ *   onError: (_e, key) => toast.error('No se aplicó', {
+ *     action: { label: 'Reintentar', onClick: () => apply.mutate(key) },
+ *   }),
+ * })
+ * <Card aria-busy={apply.pendingVariables === tpl.key} onClick={() => apply.mutate(tpl.key)} />
+ * ```
+ *
+ * - The cache is patched before the request, so the screen answers at once.
+ * - Writes to the same `queryKey` run one at a time, in call order (mutation
+ *   `scope`), so the last click is the last write the server sees.
+ * - Only the latest call decides what the cache shows: an older response
+ *   never overwrites a newer optimistic value. If the latest call fails, the
+ *   cache returns to the last value the server confirmed.
+ */
+export declare function useOptimisticMutation<TData, TVariables, TCache = TData>(options: UseOptimisticMutationOptions<TData, TVariables, TCache>): UseOptimisticMutationResult<TVariables>;
+//# sourceMappingURL=use-optimistic-mutation.d.ts.map

package/dist/use-optimistic-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-mutation.d.ts","sourceRoot":"","sources":["../src/use-optimistic-mutation.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,4BAA4B,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM;IACrE,qDAAqD;IACrD,QAAQ,EAAE,QAAQ,CAAA;IAClB,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;IACrD;;;;OAIG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAA;IACtF;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAA;IACnG;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,CAAA;IACnD,0EAA0E;IAC1E,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAA;IACvB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,KAAK,IAAI,CAAA;IACxD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,KAAK,IAAI,CAAA;CAC1D;AAED,MAAM,WAAW,2BAA2B,CAAC,UAAU;IACrD,iEAAiE;IACjE,MAAM,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,IAAI,CAAA;IACvC,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAA;IAClB,8EAA8E;IAC9E,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAA;IACxC,KAAK,EAAE,OAAO,CAAA;IACd,+EAA+E;IAC/E,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,EACrE,OAAO,EAAE,4BAA4B,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,GAC/D,2BAA2B,CAAC,UAAU,CAAC,CAoIzC"}

package/dist/use-optimistic-mutation.js

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useMutation, useQueryClient, } from '@tanstack/react-query';
+const jsonEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * Optimistic write over a TanStack Query cache entry, with rollback.
+ *
+ * ```tsx
+ * const apply = useOptimisticMutation({
+ *   queryKey: ['org-sidebar-layout'],
+ *   mutationFn: (key: string) => api.post('/apply', { key }).then((r) => r.data),
+ *   optimistic: (current, key) => ({ ...current, template_key: key }),
+ *   reconcile: (server) => server,
+ *   onError: (_e, key) => toast.error('No se aplicó', {
+ *     action: { label: 'Reintentar', onClick: () => apply.mutate(key) },
+ *   }),
+ * })
+ * <Card aria-busy={apply.pendingVariables === tpl.key} onClick={() => apply.mutate(tpl.key)} />
+ * ```
+ *
+ * - The cache is patched before the request, so the screen answers at once.
+ * - Writes to the same `queryKey` run one at a time, in call order (mutation
+ *   `scope`), so the last click is the last write the server sees.
+ * - Only the latest call decides what the cache shows: an older response
+ *   never overwrites a newer optimistic value. If the latest call fails, the
+ *   cache returns to the last value the server confirmed.
+ */
+export function useOptimisticMutation(options) {
+    const qc = useQueryClient();
+    const optionsRef = useRef(options);
+    useEffect(() => {
+        optionsRef.current = options;
+    });
+    const seqRef = useRef(0);
+    // Last value the server confirmed, captured before the first unconfirmed
+    // optimistic write. Null while nothing is in flight.
+    const confirmedRef = useRef(null);
+    const inFlightRef = useRef(undefined);
+    const timerRef = useRef(null);
+    const queuedRef = useRef(null);
+    const [pendingVariables, setPendingVariables] = useState(undefined);
+    const [error, setError] = useState(null);
+    const failedRef = useRef(null);
+    const scopeId = `optimistic:${JSON.stringify(options.queryKey)}`;
+    const settleLatest = useCallback(() => {
+        confirmedRef.current = null;
+        inFlightRef.current = undefined;
+        setPendingVariables(undefined);
+    }, []);
+    const mutation = useMutation({
+        scope: { id: scopeId },
+        mutationFn: ({ variables }) => optionsRef.current.mutationFn(variables),
+        onSuccess: (data, { variables, seq }) => {
+            const opts = optionsRef.current;
+            const latest = seq === seqRef.current && queuedRef.current === null;
+            if (latest) {
+                const current = qc.getQueryData(opts.queryKey);
+                const next = opts.reconcile ? opts.reconcile(data, variables, current) : current;
+                if (next !== undefined)
+                    qc.setQueryData(opts.queryKey, next);
+                settleLatest();
+                setError(null);
+                for (const key of opts.invalidate ?? [])
+                    void qc.invalidateQueries({ queryKey: key });
+            }
+            else if (confirmedRef.current) {
+                // A newer call owns the screen; only move the rollback point forward.
+                const base = confirmedRef.current.value;
+                const next = opts.reconcile
+                    ? opts.reconcile(data, variables, base)
+                    : opts.optimistic(base, variables);
+                confirmedRef.current = { value: next ?? base };
+            }
+            opts.onSuccess?.(data, variables);
+        },
+        onError: (err, { variables, seq }) => {
+            const opts = optionsRef.current;
+            const latest = seq === seqRef.current && queuedRef.current === null;
+            // A superseded write that fails is moot: the newer call decides what
+            // the screen shows and whether the user sees an error.
+            if (!latest)
+                return;
+            const confirmed = confirmedRef.current;
+            if (confirmed && confirmed.value !== undefined) {
+                qc.setQueryData(opts.queryKey, confirmed.value);
+            }
+            settleLatest();
+            // The server may have partially applied; resync in the background.
+            void qc.invalidateQueries({ queryKey: opts.queryKey, exact: true });
+            failedRef.current = { variables };
+            setError(err);
+            opts.onError?.(err, variables);
+        },
+    });
+    const mutateRef = useRef(mutation.mutate);
+    useEffect(() => {
+        mutateRef.current = mutation.mutate;
+    });
+    const send = useCallback((envelope) => {
+        inFlightRef.current = envelope.variables;
+        mutateRef.current(envelope);
+    }, []);
+    const flush = useCallback(() => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = null;
+        const queued = queuedRef.current;
+        queuedRef.current = null;
+        if (queued)
+            send(queued);
+    }, [send]);
+    const mutate = useCallback((variables) => {
+        const opts = optionsRef.current;
+        const isEqual = opts.isEqual ?? jsonEqual;
+        const latestPending = queuedRef.current?.variables ?? inFlightRef.current;
+        if (latestPending !== undefined && isEqual(latestPending, variables))
+            return;
+        const seq = ++seqRef.current;
+        if (!confirmedRef.current) {
+            confirmedRef.current = { value: qc.getQueryData(opts.queryKey) };
+        }
+        // A refetch landing mid-write would paint the old value back.
+        void qc.cancelQueries({ queryKey: opts.queryKey, exact: true });
+        const next = opts.optimistic(qc.getQueryData(opts.queryKey), variables);
+        if (next !== undefined)
+            qc.setQueryData(opts.queryKey, next);
+        setPendingVariables(variables);
+        setError(null);
+        failedRef.current = null;
+        const envelope = { variables, seq };
+        if (opts.debounceMs && opts.debounceMs > 0) {
+            queuedRef.current = envelope;
+            if (timerRef.current)
+                clearTimeout(timerRef.current);
+            timerRef.current = setTimeout(flush, opts.debounceMs);
+            return;
+        }
+        send(envelope);
+    }, [qc, flush, send]);
+    // Never drop a debounced write because the editor closed.
+    useEffect(() => flush, [flush]);
+    const retry = useCallback(() => {
+        const failed = failedRef.current;
+        if (failed)
+            mutate(failed.variables);
+    }, [mutate]);
+    return {
+        mutate,
+        isPending: pendingVariables !== undefined,
+        pendingVariables,
+        error,
+        retry,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "39.3.0",
+  "version": "41.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
   },
   "peerDependencies": {
     "@asteby/metacore-sdk": "^3.8.0",
-    "@asteby/metacore-ui": "^2.18.3",
+    "@asteby/metacore-ui": "^2.21.0",
     "@tanstack/react-query": ">=5",
     "@tanstack/react-router": ">=1.100",
     "@tanstack/react-table": ">=8",
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@asteby/metacore-sdk": "3.8.0",
-    "@asteby/metacore-ui": "2.18.3",
+    "@asteby/metacore-ui": "2.21.0",
     "@tanstack/react-query": "^5.95.0",
     "@tanstack/react-router": "^1.168.0",
     "@tanstack/react-table": "^8.20.0",

package/src/__tests__/motion.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, afterEach, vi } from 'vitest'
+import { motionDuration, motionEasing, MOTION_DEFAULTS } from '../motion'
+
+afterEach(() => {
+  document.documentElement.style.cssText = ''
+  vi.restoreAllMocks()
+})
+
+describe('motion tokens', () => {
+  it('falls back to the theme defaults when the host defines no variables', () => {
+    expect(motionDuration('moderate')).toBe(MOTION_DEFAULTS.duration.moderate)
+    expect(motionEasing('standard')).toBe(MOTION_DEFAULTS.easing.standard)
+  })
+
+  it('reads the host theme variables (ms and s)', () => {
+    document.documentElement.style.setProperty('--motion-duration-moderate', '0.3s')
+    document.documentElement.style.setProperty('--motion-duration-fast', '90ms')
+    document.documentElement.style.setProperty('--motion-ease-standard', 'linear')
+    expect(motionDuration('moderate')).toBe(300)
+    expect(motionDuration('fast')).toBe(90)
+    expect(motionEasing('standard')).toBe('linear')
+  })
+
+  it('is zero under prefers-reduced-motion', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({ matches: true } as MediaQueryList)
+    expect(motionDuration('slow')).toBe(0)
+  })
+})

package/src/__tests__/use-flip-animation.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { useRef } from 'react'
+import { useFlipAnimation } from '../use-flip-animation'
+
+function List({ order, reduced }: { order: string[]; reduced?: boolean }) {
+  const ref = useRef<HTMLUListElement>(null)
+  useFlipAnimation(ref, order.join(','), { disabled: reduced })
+  return (
+    <ul ref={ref}>
+      {order.map((k) => (
+        <li key={k} data-flip-key={k}>
+          {k}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// happy-dom has no layout: place each item by its index in the list.
+function fakeLayout() {
+  vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+    const parent = this.parentElement
+    const index = parent && this.dataset.flipKey ? Array.from(parent.children).indexOf(this) : 0
+    const top = this.dataset.flipKey ? index * 40 : 0
+    return { top, left: 0, width: 100, height: 40, right: 100, bottom: top + 40, x: 0, y: top, toJSON() {} } as DOMRect
+  })
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+})
+
+describe('useFlipAnimation', () => {
+  it('animates moved items from their old position', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+
+    const view = render(<List order={['a', 'b', 'c']} />)
+    vi.advanceTimersByTime(400) // at-rest snapshot
+    view.rerender(<List order={['c', 'a', 'b']} />)
+
+    const moves = animate.mock.calls.map(([frames]) => (frames as Keyframe[])[0]!.transform)
+    // c: 80 → 0, a: 0 → 40, b: 40 → 80
+    expect(moves).toContain('translate(0px, 80px)')
+    expect(moves).toContain('translate(0px, -40px)')
+    expect(animate).toHaveBeenCalledTimes(3)
+  })
+
+  it('stays still when disabled (reduced motion path)', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+
+    const view = render(<List order={['a', 'b']} reduced />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<List order={['b', 'a']} reduced />)
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('stays still under prefers-reduced-motion', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+    vi.spyOn(window, 'matchMedia').mockImplementation(
+      (query: string) => ({ matches: query.includes('reduce'), media: query }) as MediaQueryList,
+    )
+
+    const view = render(<List order={['a', 'b']} />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<List order={['b', 'a']} />)
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('works with a root resolved from the DOM instead of a wrapper element', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+    const domRef = {
+      get current() {
+        return document.querySelector<HTMLElement>('[data-slot="list"]')
+      },
+    }
+    function Resolved({ order }: { order: string[] }) {
+      useFlipAnimation(domRef, order.join(','))
+      return (
+        <ul data-slot="list">
+          {order.map((k) => (
+            <li key={k} data-flip-key={k}>
+              {k}
+            </li>
+          ))}
+        </ul>
+      )
+    }
+
+    const view = render(<Resolved order={['a', 'b']} />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<Resolved order={['b', 'a']} />)
+    expect(animate).toHaveBeenCalledTimes(2)
+  })
+})

package/src/__tests__/use-optimistic-mutation.test.tsx

@@ -0,0 +1,201 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { useOptimisticMutation } from '../use-optimistic-mutation'
+
+type Doc = { template: string }
+const KEY = ['layout']
+
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  let reject!: (e: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+function setup(
+  mutationFn: (template: string) => Promise<Doc>,
+  extra: { debounceMs?: number; onError?: (e: unknown, v: string) => void } = {},
+) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })
+  qc.setQueryData<Doc>(KEY, { template: 'default' })
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+  )
+  const hook = renderHook(
+    () =>
+      useOptimisticMutation<Doc, string, Doc>({
+        queryKey: KEY,
+        mutationFn,
+        optimistic: (_current, template) => ({ template }),
+        reconcile: (data) => data,
+        ...extra,
+      }),
+    { wrapper },
+  )
+  return { qc, hook }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('useOptimisticMutation', () => {
+  it('patches the cache before the request resolves and reconciles with the response', async () => {
+    const req = deferred<Doc>()
+    const { qc, hook } = setup(() => req.promise)
+
+    act(() => hook.result.current.mutate('classic'))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+    expect(hook.result.current.isPending).toBe(true)
+    expect(hook.result.current.pendingVariables).toBe('classic')
+
+    await act(async () => req.resolve({ template: 'classic-server' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic-server' })
+  })
+
+  it('rolls back to the confirmed value and reports the error', async () => {
+    const req = deferred<Doc>()
+    const onError = vi.fn()
+    const { qc, hook } = setup(() => req.promise, { onError })
+
+    act(() => hook.result.current.mutate('classic'))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+
+    await act(async () => req.reject(new Error('boom')))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+    expect(onError).toHaveBeenCalledWith(expect.any(Error), 'classic')
+  })
+
+  it('ignores a repeated call while the same write is in flight (double click)', async () => {
+    const req = deferred<Doc>()
+    const fn = vi.fn(() => req.promise)
+    const { hook } = setup(fn)
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('classic')
+    })
+    await act(async () => req.resolve({ template: 'classic' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('runs writes in call order and an older response never overwrites a newer choice', async () => {
+    const first = deferred<Doc>()
+    const second = deferred<Doc>()
+    const calls: string[] = []
+    const fn = vi.fn((t: string) => {
+      calls.push(t)
+      return t === 'classic' ? first.promise : second.promise
+    })
+    const { qc, hook } = setup(fn)
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('default')
+    })
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+
+    await act(async () => first.resolve({ template: 'classic' }))
+    // Serialized: the second write starts only after the first settles.
+    await waitFor(() => expect(calls).toEqual(['classic', 'default']))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+    expect(hook.result.current.pendingVariables).toBe('default')
+
+    await act(async () => second.resolve({ template: 'default' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+  })
+
+  it('rolls back to the last server-confirmed value when only the newest write fails', async () => {
+    const first = deferred<Doc>()
+    const second = deferred<Doc>()
+    const { qc, hook } = setup((t) => (t === 'classic' ? first.promise : second.promise))
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('custom')
+    })
+    await act(async () => first.resolve({ template: 'classic' }))
+    await act(async () => second.reject(new Error('nope')))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+  })
+
+  it('keeps a superseded failure silent when the newest write succeeds', async () => {
+    const first = deferred<Doc>()
+    const second = deferred<Doc>()
+    const onError = vi.fn()
+    const { qc, hook } = setup((t) => (t === 'classic' ? first.promise : second.promise), { onError })
+
+    act(() => {
+      hook.result.current.mutate('classic')
+      hook.result.current.mutate('custom')
+    })
+    await act(async () => first.reject(new Error('stale')))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'custom' })
+    await act(async () => second.resolve({ template: 'custom' }))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(onError).not.toHaveBeenCalled()
+    expect(hook.result.current.error).toBeNull()
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'custom' })
+  })
+
+  it('debounces bursts: every call paints, only the last one is sent', async () => {
+    vi.useFakeTimers()
+    const fn = vi.fn((t: string) => Promise.resolve({ template: t }))
+    const { qc, hook } = setup(fn, { debounceMs: 400 })
+
+    act(() => hook.result.current.mutate('a'))
+    act(() => hook.result.current.mutate('b'))
+    act(() => hook.result.current.mutate('c'))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'c' })
+    expect(fn).not.toHaveBeenCalled()
+
+    await act(async () => {
+      vi.advanceTimersByTime(400)
+    })
+    vi.useRealTimers()
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(fn).toHaveBeenCalledWith('c')
+  })
+
+  it('flushes a pending debounced write on unmount', async () => {
+    vi.useFakeTimers()
+    const fn = vi.fn((t: string) => Promise.resolve({ template: t }))
+    const { hook } = setup(fn, { debounceMs: 400 })
+
+    act(() => hook.result.current.mutate('saved-on-close'))
+    hook.unmount()
+    vi.useRealTimers()
+    await waitFor(() => expect(fn).toHaveBeenCalledWith('saved-on-close'))
+  })
+})
+
+describe('useOptimisticMutation retry', () => {
+  it('re-sends the failed variables and re-applies them optimistically', async () => {
+    let fail = true
+    const fn = vi.fn((t: string) => (fail ? Promise.reject(new Error('offline')) : Promise.resolve({ template: t })))
+    const { qc, hook } = setup(fn)
+
+    act(() => hook.result.current.mutate('classic'))
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'default' })
+
+    fail = false
+    act(() => hook.result.current.retry())
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+    await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(qc.getQueryData(KEY)).toEqual({ template: 'classic' })
+  })
+})

package/src/agent-result-registry.test.tsx

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+import {
+    AgentResultView,
+    clearAgentResultRenderers,
+    listAgentResultRenderers,
+    registerAgentResultRenderer,
+    resolveAgentResultRenderer,
+    type AgentResultRendererProps,
+} from './agent-result-registry'
+
+const Generic = ({ result }: AgentResultRendererProps) => <span>generic:{String(result.title)}</span>
+const Invoice = ({ result }: AgentResultRendererProps) => <span>invoice:{String(result.title)}</span>
+
+afterEach(() => clearAgentResultRenderers())
+
+describe('agent result registry', () => {
+    it('renders a result through the renderer of its kind', () => {
+        registerAgentResultRenderer('record', Generic)
+        const html = renderToStaticMarkup(
+            <AgentResultView result={{ kind: 'record', model: 'products', title: 'Llanta' }} />,
+        )
+        expect(html).toBe('<span>generic:Llanta</span>')
+    })
+
+    it('prefers a model-specific renderer over the generic one', () => {
+        registerAgentResultRenderer('record', Generic)
+        registerAgentResultRenderer('record', Invoice, { model: 'invoices' })
+        expect(resolveAgentResultRenderer({ kind: 'record', model: 'invoices' })).toBe(Invoice)
+        expect(resolveAgentResultRenderer({ kind: 'record', model: 'products' })).toBe(Generic)
+    })
+
+    it('renders nothing (never the raw payload) for an unknown kind', () => {
+        const html = renderToStaticMarkup(
+            <AgentResultView result={{ kind: 'mystery', secret: 'Model: warehouses' }} />,
+        )
+        expect(html).toBe('')
+        expect(
+            renderToStaticMarkup(
+                <AgentResultView result={{ kind: 'mystery' }} fallback={<i>sin vista</i>} />,
+            ),
+        ).toBe('<i>sin vista</i>')
+    })
+
+    it('unregister only removes its own registration', () => {
+        const off = registerAgentResultRenderer('count', Generic)
+        registerAgentResultRenderer('count', Invoice)
+        off()
+        expect(resolveAgentResultRenderer({ kind: 'count' })).toBe(Invoice)
+        expect(listAgentResultRenderers()).toEqual(['count'])
+    })
+})