@asteby/metacore-runtime-react 41.0.0 → 43.0.0

package/src/__tests__/dynamic-kanban-lane-reorder.test.tsx

@@ -26,7 +26,8 @@ let captured: {
     onDragEnd?: (e: any) => void | Promise<void>
     onDragStart?: (e: any) => void
 } = {}
-vi.mock('@dnd-kit/core', () => ({
+vi.mock('@dnd-kit/core', async (orig) => ({
+    ...((await orig()) as Record<string, unknown>),
     DndContext: ({ children, onDragEnd, onDragStart }: any) => {
         captured.onDragEnd = onDragEnd
         captured.onDragStart = onDragStart

package/src/__tests__/dynamic-kanban-pipelines-pro.test.tsx

@@ -0,0 +1,388 @@
+// @vitest-environment happy-dom
+//
+// DynamicKanban "pipelines pro": the pure helpers behind the optimistic move,
+// the lane totals, the card fields and the keyboard drag, plus the board
+// behaviour they add up to — lanes a card can't enter are marked while it is
+// lifted and refuse the drop (no request, no toast), a rejected move returns
+// the card to its lane, lane headers show the declared totals in the org
+// currency, and empty card fields are left out. dnd-kit is mocked down to a
+// passthrough that captures the board's drag callbacks (happy-dom can't
+// simulate a pointer drag).
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
+
+const I18N_T = (_k: string, opts?: Record<string, any>) => {
+    let s: string = opts?.defaultValue ?? _k
+    for (const [k, v] of Object.entries(opts ?? {})) s = s.replace(`{{${k}}}`, String(v))
+    return s
+}
+const I18N = { language: 'es-MX' }
+const USE_TRANSLATION = { t: I18N_T, i18n: I18N }
+vi.mock('react-i18next', () => ({
+    useTranslation: () => USE_TRANSLATION,
+}))
+
+vi.mock('@tanstack/react-router', () => ({
+    useNavigate: () => () => {},
+}))
+
+const toastError = vi.fn()
+vi.mock('sonner', () => ({
+    toast: Object.assign(vi.fn(), { error: (...a: any[]) => toastError(...a), success: vi.fn() }),
+}))
+
+let captured: {
+    onDragEnd?: (e: any) => void | Promise<void>
+    onDragStart?: (e: any) => void
+    onDragOver?: (e: any) => void
+} = {}
+vi.mock('@dnd-kit/core', async (orig) => ({
+    ...((await orig()) as Record<string, unknown>),
+    DndContext: ({ children, onDragEnd, onDragStart, onDragOver }: any) => {
+        captured.onDragEnd = onDragEnd
+        captured.onDragStart = onDragStart
+        captured.onDragOver = onDragOver
+        return children
+    },
+    DragOverlay: ({ children }: any) => <div data-testid="drag-overlay">{children}</div>,
+    useDraggable: () => ({
+        attributes: {},
+        listeners: {},
+        setNodeRef: () => {},
+        isDragging: false,
+    }),
+    useDroppable: () => ({ setNodeRef: () => {}, isOver: false }),
+}))
+vi.mock('@dnd-kit/sortable', async (orig) => ({
+    ...((await orig()) as Record<string, unknown>),
+    SortableContext: ({ children }: any) => children,
+    useSortable: () => ({
+        setNodeRef: () => {},
+        setActivatorNodeRef: () => {},
+        attributes: {},
+        listeners: {},
+        transform: null,
+        transition: undefined,
+        isDragging: false,
+        isOver: false,
+    }),
+}))
+
+import {
+    DynamicKanban,
+    applyLaneAggregatesOnMove,
+    applyStageOverrides,
+    cardMatchesLaneQuery,
+    isEmptyCardValue,
+    laneDeltasFromOverrides,
+    nextLaneCoordinates,
+    visibleCardFields,
+} from '../dynamic-kanban'
+import { PortalDragOverlay } from '../portal-drag-overlay'
+import { ApiProvider, type ApiClient } from '../api-context'
+import { OrgRuntimeProvider } from '../org-runtime-provider'
+import { useMetadataCache } from '../metadata-cache'
+import type { ColumnDefinition, TableMetadata } from '../types'
+
+const col = (key: string, extra: Partial<ColumnDefinition> = {}): ColumnDefinition =>
+    ({ key, label: key, type: 'text', sortable: false, filterable: false, ...extra }) as ColumnDefinition
+
+// ---------------------------------------------------------------------------
+// pure helpers
+// ---------------------------------------------------------------------------
+
+describe('card fields', () => {
+    it('treats unset, blank, empty lists, false and bare uuids as empty', () => {
+        const c = col('channel_id')
+        expect(isEmptyCardValue({ channel_id: null }, c)).toBe(true)
+        expect(isEmptyCardValue({ channel_id: '  ' }, c)).toBe(true)
+        expect(isEmptyCardValue({ channel_id: [] }, c)).toBe(true)
+        expect(isEmptyCardValue({ channel_id: false }, c)).toBe(true)
+        expect(isEmptyCardValue({ channel_id: '5f0c6a1e-9a55-4c1e-9d0b-2a7f3e1c9b10' }, c)).toBe(true)
+        expect(isEmptyCardValue({ channel_id: 'WhatsApp' }, c)).toBe(false)
+        expect(isEmptyCardValue({ channel_id: 0 }, c)).toBe(false)
+    })
+
+    it('shows the first fields that carry a value, skipping empty ones', () => {
+        const cols = [col('canal'), col('cliente'), col('asignado'), col('prioridad'), col('origen')]
+        const card = { canal: null, cliente: 'ACME', asignado: '', prioridad: 'alta', origen: 'web' }
+        expect(visibleCardFields(card, cols, 3).map((c) => c.key)).toEqual([
+            'cliente',
+            'prioridad',
+            'origen',
+        ])
+        expect(visibleCardFields({}, cols, 3)).toEqual([])
+    })
+})
+
+describe('optimistic overrides', () => {
+    const records = [
+        { id: 1, stage: 'backlog', amount: 100 },
+        { id: 2, stage: 'review', amount: '50.5' },
+    ]
+
+    it('paints an unconfirmed move in its destination lane without touching the records', () => {
+        const out = applyStageOverrides(records, { '1': 'review' }, 'stage')
+        expect(out[0].stage).toBe('review')
+        expect(records[0].stage).toBe('backlog')
+        expect(applyStageOverrides(records, {}, 'stage')).toBe(records)
+    })
+
+    it('shifts lane counts and sums by the moves in flight', () => {
+        const d = laneDeltasFromOverrides(records, { '1': 'review', '2': 'review' }, 'stage', ['amount'])
+        expect(d.backlog).toEqual({ count: -1, sums: { amount: -100 } })
+        expect(d.review).toEqual({ count: 1, sums: { amount: 100 } })
+    })
+
+    it('moves a confirmed card\'s values between lane totals', () => {
+        const next = applyLaneAggregatesOnMove(
+            { backlog: { amount: 300 }, review: { amount: 50 } },
+            records[0],
+            'backlog',
+            'review',
+            ['amount'],
+        )
+        expect(next).toEqual({ backlog: { amount: 200 }, review: { amount: 150 } })
+    })
+})
+
+describe('keyboard drag', () => {
+    const lanes = [
+        { id: 'a', left: 0, top: 100, width: 300 },
+        { id: 'b', left: 320, top: 100, width: 300 },
+        { id: 'c', left: 640, top: 100, width: 300 },
+    ]
+    it('jumps to the neighbouring lane on ← / →', () => {
+        const card = { left: 10, top: 180, width: 280 }
+        expect(nextLaneCoordinates('right', card, lanes)).toEqual({ x: 330, y: 180 })
+        expect(nextLaneCoordinates('left', card, lanes)).toBeUndefined()
+        const inB = { left: 330, top: 120, width: 280 }
+        expect(nextLaneCoordinates('left', inB, lanes)).toEqual({ x: 10, y: 156 })
+    })
+})
+
+describe('lane search', () => {
+    it('matches a relation by the name the card shows, not its uuid', () => {
+        const cols = [col('contact', { type: 'relation' } as any)]
+        const card = { contact: { id: 'u-1', name: 'Danny Pérez' } }
+        expect(cardMatchesLaneQuery(card, cols, 'danny')).toBe(true)
+        expect(cardMatchesLaneQuery(card, cols, 'u-1')).toBe(false)
+    })
+})
+
+describe('PortalDragOverlay', () => {
+    afterEach(cleanup)
+    it('renders into <body>, outside a transformed / glass ancestor', () => {
+        const { container } = render(
+            <div style={{ backdropFilter: 'blur(8px)', transform: 'translateX(10px)' }}>
+                <PortalDragOverlay>
+                    <span>lifted</span>
+                </PortalDragOverlay>
+            </div>,
+        )
+        const overlay = screen.getByTestId('drag-overlay')
+        expect(container.contains(overlay)).toBe(false)
+        expect(overlay.parentElement).toBe(document.body)
+    })
+})
+
+// ---------------------------------------------------------------------------
+// board behaviour
+// ---------------------------------------------------------------------------
+
+const STAGES = [
+    { key: 'nuevo', label: 'Nuevo', color: 'blue', order: 0 },
+    { key: 'abierto', label: 'Abierto', color: 'violet', order: 1 },
+    { key: 'esperando', label: 'Esperando', color: 'amber', order: 2 },
+    { key: 'resuelto', label: 'Resuelto', color: 'green', order: 3 },
+]
+
+function meta(): TableMetadata {
+    return {
+        title: 'Bandeja',
+        endpoint: '/data/conversations',
+        view_type: 'kanban',
+        group_by: 'status',
+        stages: STAGES,
+        transitions: [
+            { from: 'nuevo', to: 'abierto' },
+            { from: 'abierto', to: 'esperando' },
+            { from: 'esperando', to: 'abierto' },
+            { from: 'abierto', to: 'resuelto' },
+        ],
+        columns: [
+            { key: 'title', label: 'Contacto', type: 'text', sortable: true, filterable: false, searchable: true },
+            { key: 'channel', label: 'Canal', type: 'text', sortable: false, filterable: false },
+            {
+                key: 'amount',
+                label: 'Monto',
+                type: 'number',
+                cellStyle: 'currency',
+                styleConfig: { aggregate: 'sum' },
+                sortable: false,
+                filterable: false,
+            },
+            {
+                key: 'status',
+                label: 'Estado',
+                type: 'status',
+                sortable: false,
+                filterable: true,
+                options: STAGES.map((s) => ({ value: s.key, label: s.label, color: s.color })),
+            },
+        ],
+        actions: [],
+        perPageOptions: [50],
+        defaultPerPage: 50,
+        searchPlaceholder: 'Buscar...',
+        enableCRUDActions: true,
+        hasActions: false,
+    } as TableMetadata
+}
+
+const CARDS = [
+    { id: 1, title: 'Danny', channel: null, amount: 100, status: 'abierto' },
+    { id: 2, title: 'Ana', channel: 'WhatsApp', amount: 40, status: 'esperando' },
+]
+
+function fakeApi(over: Partial<ApiClient> = {}): ApiClient {
+    const ok = (data: unknown, meta?: unknown) => ({ data: { success: true, data, meta } })
+    // A tiny server: a PUT persists, so the lane figures re-read after a move
+    // reflect it.
+    const db = CARDS.map((c) => ({ ...c }))
+    return {
+        get: vi.fn(async (url: string, config?: any) => {
+            if (url.startsWith('/metadata/table/')) return ok(meta())
+            if (url.startsWith('/stage-layout')) return ok({ model: 'conversations', stage_order: null })
+            if (url.startsWith('/custom-stages') || url.startsWith('/stage-')) return { data: { success: false } }
+            const stage = config?.params?.f_status
+            if (url.endsWith('/aggregate')) {
+                const amount = db.filter((c) => c.status === stage).reduce((a, c) => a + c.amount, 0)
+                return ok({ amount })
+            }
+            const rows = stage ? db.filter((c) => c.status === stage) : db
+            return ok(rows, { total: rows.length })
+        }),
+        post: vi.fn(async () => ok(null)),
+        put: vi.fn(async (url: string, body: any) => {
+            const row = db.find((c) => url.endsWith(`/${c.id}`))
+            if (row) Object.assign(row, body)
+            return ok(row ?? null)
+        }),
+        delete: vi.fn(async () => ok(null)),
+        ...over,
+    }
+}
+
+const laneOf = (text: string) =>
+    screen.getByText(text).closest('[data-stage]')?.getAttribute('data-stage')
+
+function renderBoard(api: ApiClient) {
+    useMetadataCache.getState().setMetadata('conversations', meta())
+    return render(
+        <OrgRuntimeProvider currency="MXN">
+            <ApiProvider client={api}>
+                <DynamicKanban model="conversations" />
+            </ApiProvider>
+        </OrgRuntimeProvider>,
+    )
+}
+
+beforeEach(() => {
+    captured = {}
+    toastError.mockReset()
+})
+afterEach(cleanup)
+
+describe('DynamicKanban pipelines', () => {
+    it('marks the lanes a lifted card cannot enter and refuses a drop there', async () => {
+        const put = vi.fn(async () => ({ data: { success: true, data: null } }))
+        renderBoard(fakeApi({ put }))
+        await screen.findByText('Danny')
+
+        act(() => {
+            captured.onDragStart!({ active: { id: '1', data: { current: { type: 'card' } } } })
+        })
+        const drop = (key: string) =>
+            document.querySelector(`[data-stage="${key}"]`)?.getAttribute('data-drop')
+        // abierto → nuevo is not declared; abierto → esperando/resuelto are.
+        expect(drop('nuevo')).toBe('blocked')
+        expect(drop('esperando')).toBeNull()
+        expect(drop('resuelto')).toBeNull()
+        expect(drop('abierto')).toBeNull()
+
+        act(() => {
+            captured.onDragOver!({ active: { id: '1' }, over: { id: 'nuevo' } })
+        })
+        expect(screen.getByTestId('lane-blocked-nuevo')).toBeTruthy()
+
+        await act(async () => {
+            await captured.onDragEnd!({
+                active: { id: '1', data: { current: { type: 'card' } } },
+                over: { id: 'nuevo' },
+            })
+        })
+        expect(put).not.toHaveBeenCalled()
+        expect(toastError).not.toHaveBeenCalled()
+        expect(laneOf('Danny')).toBe('abierto')
+        expect(drop('nuevo')).toBeNull()
+    })
+
+    it('moves a card at once and sends it back when the server refuses', async () => {
+        let reject!: (e: unknown) => void
+        const put = vi.fn(
+            () =>
+                new Promise((_res, rej) => {
+                    reject = rej
+                }),
+        )
+        renderBoard(fakeApi({ put: put as any }))
+        await screen.findByText('Danny')
+
+        await act(async () => {
+            await captured.onDragEnd!({
+                active: { id: '1', data: { current: { type: 'card' } } },
+                over: { id: 'resuelto' },
+            })
+        })
+        expect(put.mock.calls[0]).toEqual(['/data/conversations/1', { status: 'resuelto' }])
+        // Optimistic: already in the destination while the request is in flight.
+        await waitFor(() => expect(laneOf('Danny')).toBe('resuelto'))
+
+        await act(async () => {
+            reject({ response: { data: { message: 'bloqueado por una regla' } } })
+        })
+        await waitFor(() => expect(laneOf('Danny')).toBe('abierto'))
+        expect(toastError).toHaveBeenCalledWith(
+            'No se pudo mover la tarjeta: bloqueado por una regla',
+        )
+    })
+
+    it('shows each lane\'s declared total in the org currency and follows a move', async () => {
+        renderBoard(fakeApi())
+        await screen.findByText('Danny')
+        const total = (key: string) =>
+            screen.queryByTestId(`lane-total-${key}-amount`)?.textContent?.replace(/\s/g, ' ')
+        await waitFor(() => expect(total('abierto')).toMatch(/100\.00/))
+        expect(total('abierto')).toMatch(/\$/)
+        expect(total('esperando')).toMatch(/40\.00/)
+
+        await act(async () => {
+            await captured.onDragEnd!({
+                active: { id: '1', data: { current: { type: 'card' } } },
+                over: { id: 'esperando' },
+            })
+        })
+        await waitFor(() => expect(total('esperando')).toMatch(/140\.00/))
+        expect(total('abierto')).toMatch(/0\.00/)
+    })
+
+    it('leaves out a card field with no value instead of a "Canal: —" row', async () => {
+        renderBoard(fakeApi())
+        const danny = (await screen.findByText('Danny')).closest('[data-card-id]') as HTMLElement
+        const ana = screen.getByText('Ana').closest('[data-card-id]') as HTMLElement
+        expect(danny.textContent).not.toContain('Canal')
+        expect(ana.textContent).toContain('Canal')
+        expect(ana.textContent).toContain('WhatsApp')
+    })
+})

package/src/__tests__/dynamic-kanban.test.tsx

@@ -171,9 +171,22 @@ describe('isTransitionAllowed', () => {
         expect(isTransitionAllowed(TRANSITIONS, 'done', 'done')).toBe(true)
     })
 
-    it('is unrestricted when no transitions are declared', () => {
+    it('is unrestricted when the metadata carries no transitions', () => {
         expect(isTransitionAllowed(undefined, 'done', 'backlog')).toBe(true)
-        expect(isTransitionAllowed([], 'done', 'backlog')).toBe(true)
+    })
+
+    it('an empty list allows no moves between stages (kernel rule)', () => {
+        expect(isTransitionAllowed([], 'done', 'backlog')).toBe(false)
+        expect(isTransitionAllowed([], 'done', 'done')).toBe(true)
+    })
+
+    it('places a card that has no stage, or one outside the machine, in any stage', () => {
+        const keys = new Set(['backlog', 'in_progress', 'review', 'done'])
+        expect(isTransitionAllowed(TRANSITIONS, '', 'done', keys)).toBe(true)
+        expect(isTransitionAllowed(TRANSITIONS, 'legacy_open', 'done', keys)).toBe(true)
+        expect(isTransitionAllowed([], '', 'backlog', keys)).toBe(true)
+        // …but only into a stage of the machine.
+        expect(isTransitionAllowed(TRANSITIONS, '', 'nowhere', keys)).toBe(false)
     })
 
     it('honors wildcards on either side', () => {

package/src/__tests__/image-cell-lucide.test.tsx

@@ -4,7 +4,7 @@
 // kebab, as stored by the `icon` form widget) renders the glyph instead of a
 // broken <img>; real paths/urls keep rendering an <img>.
 import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, render } from '@testing-library/react'
+import { cleanup, render, waitFor } from '@testing-library/react'
 import { ImageCell } from '../dynamic-columns'
 import { isLucideIconName, resolveLucideIconName } from '../dynamic-icon'
 
@@ -13,15 +13,17 @@ afterEach(cleanup)
 const getImageUrl = (p: string) => `/img${p}`
 
 describe('ImageCell con nombre lucide', () => {
-    it('renderiza el ícono (svg) para un nombre PascalCase, sin <img>', () => {
+    it('renderiza el ícono (svg) para un nombre PascalCase, sin <img>', async () => {
         const { container } = render(<ImageCell value="CreditCard" getImageUrl={getImageUrl} />)
-        expect(container.querySelector('svg')).toBeTruthy()
+        // The glyph loads once; its box is held meanwhile.
+        await waitFor(() => expect(container.querySelector('svg')).toBeTruthy())
         expect(container.querySelector('img')).toBeNull()
     })
 
-    it('renderiza el ícono también para el slug kebab "credit-card"', () => {
+    it('renderiza el ícono también para el slug kebab "credit-card"', async () => {
         const { container } = render(<ImageCell value="credit-card" getImageUrl={getImageUrl} />)
-        expect(container.querySelector('svg')).toBeTruthy()
+        // The glyph loads once; its box is held meanwhile.
+        await waitFor(() => expect(container.querySelector('svg')).toBeTruthy())
         expect(container.querySelector('img')).toBeNull()
     })
 

package/src/__tests__/use-persisted-query.test.tsx

@@ -0,0 +1,132 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { createPersistedSnapshot, usePersistedQuery } from '../use-persisted-query'
+
+type Layout = { order: string[] }
+
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+  return { promise, resolve }
+}
+
+function wrapperFor(qc: QueryClient) {
+  return ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+  )
+}
+
+const newClient = () => new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+describe('createPersistedSnapshot', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('round-trips per scope and version', () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    const ts = Date.now() - 1000
+    snap.write('org-a', { order: ['a'] }, { ts })
+    expect(snap.read('org-a')).toEqual({ data: { order: ['a'] }, ts })
+    expect(snap.read('org-b')).toBeUndefined()
+    const v2 = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 2 })
+    expect(v2.read('org-a')).toBeUndefined()
+  })
+
+  it('ignores expired and corrupt entries', () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1, maxAgeMs: 1000 })
+    snap.write('org-a', { order: ['a'] }, { ts: Date.now() - 5000 })
+    expect(snap.read('org-a')).toBeUndefined()
+    localStorage.setItem('test:layout:v1:org-b', '{not json')
+    expect(snap.read('org-b')).toBeUndefined()
+  })
+})
+
+describe('usePersistedQuery', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('paints the persisted value on the first render, then revalidates and persists', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    snap.write('org-a', { order: ['cached'] }, { ts: Date.now() - 60_000 })
+    const net = deferred<Layout>()
+    const renders: (Layout | undefined)[] = []
+    const { result } = renderHook(
+      () => {
+        const q = usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn: () => net.promise,
+          staleTime: 1000,
+          persist: { snapshot: snap, scope: 'org-a' },
+        })
+        renders.push(q.data)
+        return q
+      },
+      { wrapper: wrapperFor(newClient()) },
+    )
+    expect(renders[0]).toEqual({ order: ['cached'] })
+    await act(async () => net.resolve({ order: ['fresh'] }))
+    await waitFor(() => expect(result.current.data).toEqual({ order: ['fresh'] }))
+    expect(snap.read('org-a')?.data).toEqual({ order: ['fresh'] })
+  })
+
+  it('revalidates a seed once per load even when it is younger than staleTime', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    snap.write('org-a', { order: ['cached'] }, { ts: Date.now() - 1000 })
+    const queryFn = vi.fn(async () => ({ order: ['changed-elsewhere'] }))
+    const { result } = renderHook(
+      () =>
+        usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn,
+          staleTime: 60_000,
+          persist: { snapshot: snap, scope: 'org-a' },
+        }),
+      { wrapper: wrapperFor(newClient()) },
+    )
+    expect(result.current.data).toEqual({ order: ['cached'] })
+    await waitFor(() => expect(result.current.data).toEqual({ order: ['changed-elsewhere'] }))
+    expect(queryFn).toHaveBeenCalledTimes(1)
+    expect(snap.read('org-a')?.data).toEqual({ order: ['changed-elsewhere'] })
+  })
+
+  it('persists the raw payload, not the selected shape, and setQueryData writes back', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    const qc = newClient()
+    const { result } = renderHook(
+      () =>
+        usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn: async () => ({ order: ['x', 'y'] }),
+          select: (d: Layout) => d.order.length,
+          persist: { snapshot: snap, scope: 'org-a' },
+        }),
+      { wrapper: wrapperFor(qc) },
+    )
+    await waitFor(() => expect(result.current.data).toBe(2))
+    await waitFor(() => expect(snap.read('org-a')?.data).toEqual({ order: ['x', 'y'] }))
+    act(() => {
+      qc.setQueryData<Layout>(['layout'], { order: ['z'] })
+    })
+    await waitFor(() => expect(snap.read('org-a')?.data).toEqual({ order: ['z'] }))
+  })
+
+  it('does not read or write without a scope', async () => {
+    const snap = createPersistedSnapshot<Layout>({ key: 'test:layout', version: 1 })
+    snap.write('org-a', { order: ['cached'] })
+    const { result } = renderHook(
+      () =>
+        usePersistedQuery({
+          queryKey: ['layout'],
+          queryFn: async () => ({ order: ['fresh'] }),
+          persist: { snapshot: snap, scope: null },
+        }),
+      { wrapper: wrapperFor(newClient()) },
+    )
+    expect(result.current.data).toBeUndefined()
+    await waitFor(() => expect(result.current.data).toEqual({ order: ['fresh'] }))
+    expect(snap.read('org-a')?.data).toEqual({ order: ['cached'] })
+  })
+})

package/src/api-context.tsx

@@ -90,11 +90,13 @@ export function useApi(): ApiClient {
     // remembered, so the refresh after a save reads the saved row. The
     // wrapper is stable while the host client is.
     return useMemo<ApiClient>(() => ({
-        get: (url, config) => batchGet(ctx, url, config),
-        post: (url, body, config) =>
-            isWrite('post', url) ? mutating(ctx.post(url, body, config)) : ctx.post(url, body, config),
-        put: (url, body, config) => mutating(ctx.put(url, body, config)),
-        delete: (url, config) => mutating(ctx.delete(url, config)),
+        // Each call reaches the host client with the arguments it was given —
+        // never a trailing `undefined` it didn't ask for.
+        get: (...args: Parameters<ApiClient['get']>) => batchGet(ctx, ...args),
+        post: (...args: Parameters<ApiClient['post']>) =>
+            isWrite('post', args[0]) ? mutating(ctx.post(...args)) : ctx.post(...args),
+        put: (...args: Parameters<ApiClient['put']>) => mutating(ctx.put(...args)),
+        delete: (...args: Parameters<ApiClient['delete']>) => mutating(ctx.delete(...args)),
     }), [ctx])
 }
 

package/src/dynamic-icon.tsx

@@ -1,7 +1,9 @@
 // DynamicIcon resolves a lucide glyph by name without pulling the full icon
-// set into the shared chunk. Each glyph is its own dynamic import.
-import { lazy, Suspense, useMemo, type ComponentType } from 'react'
+// set into the shared chunk. It draws through the shared glyph registry of
+// @asteby/metacore-ui: a glyph seen before renders in the first frame, and an
+// unseen one holds its box until it loads, so the label next to it stays put.
 import dynamicIconImports from 'lucide-react/dynamicIconImports'
+import { Glyph } from '@asteby/metacore-ui/icons'
 
 export interface DynamicIconProps {
     name: string
@@ -25,24 +27,18 @@ function kebabToPascal(kebab: string): string {
 }
 
 function loaderFor(pascal: string) {
-    const kebab = pascalToKebab(pascal) as IconName
-    return dynamicIconImports[kebab]
+    const kebab = pascalToKebab(pascal)
+    // Lucide keys split digits ("building-2"); "building2" is not one.
+    return (
+        dynamicIconImports[kebab as IconName] ??
+        dynamicIconImports[kebab.replace(/([a-z])(\d)/g, '$1-$2') as IconName]
+    )
 }
 
 export function DynamicIcon({ name, className }: DynamicIconProps) {
     const resolved = resolveLucideIconName(name)
-    const Icon = useMemo(() => {
-        if (!resolved) return null
-        const loader = loaderFor(resolved)
-        if (!loader) return null
-        return lazy(loader as () => Promise<{ default: ComponentType<{ className?: string }> }>)
-    }, [resolved])
-    if (!Icon) return null
-    return (
-        <Suspense fallback={null}>
-            <Icon className={className} />
-        </Suspense>
-    )
+    if (!resolved) return null
+    return <Glyph name={resolved} className={className} />
 }
 
 // resolveLucideIconName — canonical PascalCase lucide name for a value that is