@voltro/cli 0.33.0 → 0.35.0

package/templates/apps/frontend-admin/src/pages/admin/entity.test.tsx

@@ -5,7 +5,13 @@
 // renders one of three observable states: a loading skeleton, an "unknown
 // entity" banner, or the bound CRUD surface (heading + AutoForm + DataTable).
 // We mock @voltro/web (useParams + the AutoForm/DataTable components) and
-// @voltro/client (the discovery + gating hooks).
+// @voltro/client (the discovery + access hooks).
+//
+// The access cases below are the point of this file. The page must gate on the
+// DECLARED access the manifest carries, never on a scope string it invented,
+// and it must SHOW an `unknown` decision instead of hiding it — a per-row guard
+// is the server's to answer, and hiding it empties the admin for every
+// multi-tenant app whose subjects hold no global scopes.
 
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
@@ -19,20 +25,25 @@ vi.mock('@voltro/web', () => ({
   useParams: () => params(),
   AutoForm: ({ mutation }: { mutation: string }) =>
     createElement('div', { 'data-testid': 'auto-form' }, mutation),
-  DataTable: ({ query }: { query: string }) =>
-    createElement('div', { 'data-testid': 'data-table' }, query),
+  DataTable: ({ query, rowActions }: { query: string; rowActions?: (r: Record<string, unknown>) => ReactNode }) =>
+    createElement('div', { 'data-testid': 'data-table' }, query, rowActions?.({ id: 'r1', entryNo: 'e1' })),
 }))
 
 interface ManifestState { manifest: unknown; loading: boolean }
 const capabilityManifest = vi.fn<() => ManifestState>()
 const entityAdmins = vi.fn<() => Array<Record<string, unknown>>>()
-const can = vi.fn<() => boolean>()
+const accessDecision = vi.fn<() => 'allowed' | 'denied' | 'unknown'>()
+const mutate = vi.fn()
 
 vi.mock('@voltro/client', () => ({
   useCapabilityManifest: () => capabilityManifest(),
   deriveEntityAdmins: () => entityAdmins(),
-  useCan: () => can(),
-  useMutation: () => ({ mutate: vi.fn() }),
+  useAccessDecision: () => accessDecision(),
+  requiredScopes: (guards?: ReadonlyArray<{ kind: string; scope?: ReadonlyArray<string> }>) =>
+    (guards ?? []).flatMap((g) => (g.kind === 'scope' ? [...(g.scope ?? [])] : [])),
+  openAccessReason: (guards?: ReadonlyArray<{ kind: string; reason?: string }>) =>
+    (guards ?? []).find((g) => g.kind === 'open')?.reason,
+  useMutation: () => ({ mutate }),
   useProvenance: () => ({ data: undefined, loading: false, error: undefined }),
 }))
 
@@ -58,12 +69,36 @@ const render = (node: ReactNode): void => {
 const cell = (id: string): string | null =>
   container.querySelector(`[data-testid="${id}"]`)?.textContent ?? null
 
+/** A derived spec in its current shape. */
+const spec = (over: Record<string, unknown> = {}): Record<string, unknown> => ({
+  table: 'todos',
+  columns: [{ name: 'id' }, { name: 'title' }],
+  serverOnlyColumns: [],
+  sensitiveColumns: [],
+  reactive: true,
+  pkColumn: 'id',
+  editable: true,
+  list: { tag: 'todos.list' },
+  create: { tag: 'todos.create', guards: [{ kind: 'scope', scope: ['todos:manage'], mode: 'all', resourceScoped: false }] },
+  update: {},
+  delete: { tag: 'todos.delete' },
+  ...over,
+})
+
+const showEntity = (over: Record<string, unknown> = {}): void => {
+  params.mockReturnValue({ entity: (over['table'] as string) ?? 'todos' })
+  capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+  entityAdmins.mockReturnValue([spec(over)])
+  render(createElement(EntityPage))
+}
+
 beforeEach(() => {
   params.mockReset()
   capabilityManifest.mockReset()
   entityAdmins.mockReset()
-  can.mockReset()
-  can.mockReturnValue(true)
+  accessDecision.mockReset()
+  mutate.mockReset()
+  accessDecision.mockReturnValue('allowed')
 })
 
 afterEach(() => {
@@ -98,22 +133,94 @@ describe('entity page — render states', () => {
   })
 
   test('renders the bound CRUD surface (heading + AutoForm + DataTable) for a known entity', () => {
-    params.mockReturnValue({ entity: 'todos' })
-    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
-    entityAdmins.mockReturnValue([
-      {
-        table: 'todos',
-        columns: ['id', 'title'],
-        listTag: 'todos.list',
-        createTag: 'todos.create',
-        createScope: 'todos:create',
-        deleteScope: 'todos:delete',
-        deleteTag: 'todos.delete',
-      },
-    ])
-    render(createElement(EntityPage))
+    showEntity()
     expect(container.querySelector('h1')!.textContent).toBe('todos')
     expect(cell('auto-form')).toBe('todos.create')
-    expect(cell('data-table')).toBe('todos.list')
+    expect(cell('data-table')).toContain('todos.list')
+  })
+})
+
+describe('entity page — gates on the DECLARED access', () => {
+  test('shows the create form when the api says the caller may create', () => {
+    accessDecision.mockReturnValue('allowed')
+    showEntity()
+    expect(cell('auto-form')).toBe('todos.create')
+  })
+
+  test('hides it on a DEFINITE denial', () => {
+    accessDecision.mockReturnValue('denied')
+    showEntity()
+    expect(container.querySelector('[data-testid="auto-form"]')).toBeNull()
+    // …and the list is still there. A denied write is not a denied read.
+    expect(cell('data-table')).toContain('todos.list')
+  })
+
+  test('SHOWS it on an indeterminate decision, and says why', () => {
+    // The false-deny trap: a per-row guard cannot be pre-computed in a browser.
+    // Hiding it would empty the admin for exactly the multi-tenant apps whose
+    // subjects carry no global scopes.
+    accessDecision.mockReturnValue('unknown')
+    showEntity()
+    expect(cell('auto-form')).toBe('todos.create')
+    expect(container.textContent).toContain('checks permission per row')
+  })
+
+  test('names the scope the api ACTUALLY requires, so a refusal is readable', () => {
+    showEntity()
+    expect(container.textContent).toContain('requires todos:manage')
+  })
+
+  test('reports an openAccess decision with its reason', () => {
+    showEntity({ create: { tag: 'todos.create', guards: [{ kind: 'open', reason: 'demo seeding' }] } })
+    expect(container.textContent).toContain('open access — demo seeding')
+  })
+
+  test('says so when a procedure declared no access at all', () => {
+    showEntity({ create: { tag: 'todos.create' } })
+    expect(container.textContent).toContain('no access decision declared')
+  })
+
+  test('renders nothing to create when the api exposes no create mutation', () => {
+    showEntity({ create: {} })
+    expect(container.querySelector('[data-testid="auto-form"]')).toBeNull()
+  })
+})
+
+describe('entity page — the three exposure axes', () => {
+  test('names the .serverOnly() columns it withheld, and why', () => {
+    showEntity({ serverOnlyColumns: ['pwHash', 'internalNote'] })
+    expect(container.textContent).toContain('2 server-only columns')
+    expect(container.textContent).toContain('pwHash, internalNote')
+    expect(container.textContent).toContain('cannot be submitted')
+  })
+
+  test('flags .sensitive() columns as export-masked, NOT as hidden', () => {
+    // The category error to avoid: `.sensitive()` is the export axis. The value
+    // is real wire data the operator is meant to see.
+    showEntity({ sensitiveColumns: ['email'] })
+    expect(container.textContent).toContain('masked in exports: email')
+  })
+
+  test('says nothing when no column is marked', () => {
+    showEntity()
+    expect(container.textContent).not.toContain('server-only')
+    expect(container.textContent).not.toContain('masked in exports')
+  })
+})
+
+describe('entity page — row identity', () => {
+  test('keys the delete on the pk the api declares, not a hard-coded id', () => {
+    showEntity({ pkColumn: 'entryNo' })
+    const del = container.querySelector('button.danger')!
+    act(() => { del.dispatchEvent(new MouseEvent('click', { bubbles: true })) })
+    // A hard-coded `id` would have sent `{ id: 'r1' }` — or `{ id: '' }` for a
+    // table that has no `id` column at all.
+    expect(mutate).toHaveBeenCalledWith({ entryNo: 'e1' })
+  })
+
+  test('offers no delete for a table with no addressable row', () => {
+    showEntity({ editable: false, pkColumn: undefined })
+    expect(container.querySelector('button.danger')).toBeNull()
+    expect(container.textContent).toContain('No single primary key')
   })
 })

package/templates/apps/frontend-admin/src/pages/admin/layout.tsx

@@ -69,8 +69,9 @@ export default function AdminLayout({ children }: { readonly children: ReactNode
   )
 
   return (
-    // PermissionProvider feeds the current subject's scopes to useCan across the
-    // admin. DEMO scopes here — swap for your session's scopes (see lib/admin.ts).
+    // PermissionProvider feeds the current subject's scopes to useAccessDecision
+    // across the admin, which judges them against each procedure's OWN declared
+    // guards. DEMO scopes here — swap for your session's (see lib/admin.ts).
     <PermissionProvider scopes={DEMO_SCOPES}>
       <div className="admin">
         <aside>

package/templates/apps/frontend-admin/src/pages/admin/page.test.tsx

@@ -57,11 +57,16 @@ describe('admin overview — config', () => {
 })
 
 describe('admin overview — render', () => {
+  const spec = (over: Record<string, unknown>): Record<string, unknown> => ({
+    columns: [], serverOnlyColumns: [], sensitiveColumns: [], reactive: false, editable: true,
+    list: {}, create: {}, update: {}, delete: {}, ...over,
+  })
+
   test('renders a linked card per entity with its column count and ops', () => {
     capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
     entityAdmins.mockReturnValue([
-      { table: 'todos', columns: ['id', 'title'], reactive: true, listTag: 'todos.list', createTag: 'todos.create' },
-      { table: 'notes', columns: ['id'], reactive: false, listTag: 'notes.list' },
+      spec({ table: 'todos', columns: ['id', 'title'], reactive: true, list: { tag: 'todos.list' }, create: { tag: 'todos.create' } }),
+      spec({ table: 'notes', columns: ['id'], list: { tag: 'notes.list' } }),
     ])
 
     render(createElement(AdminOverview))
@@ -72,6 +77,18 @@ describe('admin overview — render', () => {
     expect(container.textContent).toContain('list · create')
   })
 
+  test('says how many columns are withheld rather than just showing fewer', () => {
+    // `columns` already excludes `.serverOnly()`, so a card that only printed the
+    // count would silently under-report the table. "2 columns" and "2 columns +
+    // 1 hidden" are different facts about the same entity.
+    capabilityManifest.mockReturnValue({ manifest: {}, loading: false })
+    entityAdmins.mockReturnValue([
+      spec({ table: 'users', columns: ['id', 'email'], serverOnlyColumns: ['pwHash'], list: { tag: 'users.list' } }),
+    ])
+    render(createElement(AdminOverview))
+    expect(container.textContent).toContain('1 server-only column, hidden')
+  })
+
   test('shows the error banner when the capability map is unreachable', () => {
     capabilityManifest.mockReturnValue({ manifest: undefined, loading: false, error: 'boom' })
     entityAdmins.mockReturnValue([])

package/templates/apps/frontend-admin/src/pages/admin/page.tsx

@@ -39,19 +39,24 @@ export default function AdminOverview(): ReactNode {
         <div className="cards" style={{ marginTop: '1.25rem' }}>
           {entities.map((e) => {
             const ops = [
-              e.listTag && 'list',
-              e.createTag && 'create',
-              e.updateTag && 'edit',
-              e.deleteTag && 'delete',
+              e.list.tag && 'list',
+              e.create.tag && 'create',
+              e.update.tag && 'edit',
+              e.delete.tag && 'delete',
             ].filter(Boolean)
             return (
               <a className="card" key={e.table} href={`/admin/${e.table}`}>
                 <div className="value">{e.table}</div>
                 <div className="label">
+                  {/* `columns` already excludes `.serverOnly()` — the count is
+                      what an admin can actually show, not what the table has. */}
                   <T id="overview.columns" values={{ count: e.columns.length }} />
                   {e.reactive ? <T id="overview.reactiveSuffix" /> : null}
                 </div>
                 <div className="meta">{ops.length > 0 ? ops.join(' · ') : <T id="overview.readonly" />}</div>
+                {e.serverOnlyColumns.length > 0 ? (
+                  <div className="meta"><T id="overview.serverOnly" values={{ count: e.serverOnlyColumns.length }} /></div>
+                ) : null}
               </a>
             )
           })}

package/templates/apps/frontend-app/app.config.ts

@@ -31,9 +31,10 @@ export default {
   // more languages by adding a code here + a `src/locales/<code>.ts`.
   locales:       ['en', 'de'] as const,
   defaultLocale: 'en'         as const,
-  // The api this frontend consumes. The NAME ('app') is the lookup key the
-  // hooks use — `useSubscription('app', 'notes.list')`, `useMutation('app',
-  // 'notes.create')`. The `package` resolves the sibling api in this project
+  // The api this frontend consumes. The NAME ('app') is the lookup key — spelled
+  // ONCE, in `src/lib/api.ts`'s `createHooks<AppProcedures>('app')`, after which
+  // pages just call `useSubscription('notes.list')` and
+  // `useMutation('notes.create')`. The `package` resolves the sibling api
   // (scaffold it with `--api=api-backend`); its port is auto-discovered from
   // its own app.config.ts, and codegen pulls its typed rpc surface so the
   // hooks are end-to-end typed. Add more entries to consume more apis.

package/templates/apps/frontend-app/package.json

@@ -12,21 +12,24 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/client": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/i18n": "0.33.0",
-    "@voltro/ui-shadcn": "0.33.0",
-    "@voltro/web": "0.33.0",
+    "@{{projectName}}/api": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/client": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/i18n": "0.35.0",
+    "@voltro/ui-shadcn": "0.35.0",
+    "@voltro/web": "0.35.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.33.0",
+    "@voltro/devtools": "0.35.0",
+    "@voltro/testing": "0.35.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/frontend-app/src/lib/api.ts

@@ -0,0 +1,25 @@
+// The typed hook surface for the `app` api — bound ONCE, here, and imported by
+// every page instead of `@voltro/client`.
+//
+// `AppProcedures` is emitted by codegen into the api's `rpcGroup.generated.ts`:
+// a type-level map of every rpc tag to the descriptor behind it. Feeding it to
+// `createHooks` makes the tag a literal union and the input/output types INFER:
+//
+//     const { data } = useSubscription('notes.list')   // rows, typed
+//     const create   = useMutation('notes.create')     // input + output typed
+//
+// So no page declares a row `interface` mirroring the api any more. The old
+// `useSubscription<ReadonlyArray<Note>>('app', 'notes.list')` spelled the api
+// name at every call site, left the tag an unchecked string (a typo was a
+// runtime error), and the `<T>` was an ASSERTION nothing compared against the
+// server. All three are compile-checked now.
+//
+// `'app'` is the key this web app gave the api in `app.config.ts` -> `apis`.
+// `import type` is erased, so the binding costs the browser bundle nothing.
+import { createHooks } from '@voltro/client'
+import type { AppProcedures } from '@{{projectName}}/api/rpcGroup'
+
+// Destructured on purpose - `react-hooks/rules-of-hooks` only treats a member
+// call as a hook when the object is PascalCase, so top-level `useX` identifiers
+// are what keep the React lint rules working at every call site.
+export const { useSubscription, useMutation, useAction } = createHooks<AppProcedures>('app')

package/templates/apps/frontend-app/src/pages/page.test.tsx

@@ -1,50 +1,70 @@
 // @vitest-environment jsdom
 //
-// `/` — the reactive notes page. It binds `useSubscription('app','notes.list')`
-// + `useMutation('app','notes.create')` from @voltro/client. We mock that module
-// so the render is deterministic and assert the observable output: loading /
-// empty / list states, optimistic-row styling, subscription-error banner, and
-// the submit path calling create.mutate with the trimmed title + body + tenant.
+// `/` — the reactive notes page, driven through `makeVoltroTestClient`
+// (`@voltro/testing/client`) rather than a `vi.mock` of anything.
+//
+// WHY THE HARNESS HERE. The old suite faked `src/lib/api` — the app's own typed
+// binding — with the argument that mocking `@voltro/client` underneath would be
+// the wrong seam. That argument was right about the seam and reached the wrong
+// conclusion, because the harness does not mock `@voltro/client` at all: it
+// PROVIDES the runtime context the real hooks read. So `createHooks` runs, the
+// real `useSubscription` / `useMutation` run, and the fake stops at the
+// transport — one layer below the binding rather than on top of it.
+//
+// What that buys, concretely: the page is the framework's flagship example of
+// the reactive loop, and every "different data" case here used to be a fresh
+// mount with a different mock return. Nothing pushed a delta into a MOUNTED
+// tree, which is the one behaviour the page exists to demonstrate. The last two
+// cases do, via `setSubscription`.
 
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
 import { I18nProvider } from '@voltro/i18n'
+import { makeVoltroTestClient, type VoltroTestClient } from '@voltro/testing/client'
 import enCatalog from '../locales/en'
-
-interface SubState {
-  data: unknown
-  revision?: number
-  emittedAt?: number
-  error?: unknown
-  pendingPatches?: number
-}
-
-const useSubscription = vi.fn<() => SubState>()
-const mutate = vi.fn<(input: unknown) => Promise<unknown>>()
-const useMutation = vi.fn(() => ({ mutate, pending: false, error: undefined, data: undefined }))
-
-vi.mock('@voltro/client', () => ({
-  useSubscription: (...a: unknown[]) => useSubscription(...(a as [])),
-  useMutation: (...a: unknown[]) => useMutation(...(a as [])),
-}))
-
-const { default: IndexPage } = await import('./page')
+import IndexPage from './page'
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
 
+const LIST = 'notes.list'
+
 let container: HTMLDivElement
 let root: Root
+let client: VoltroTestClient
+
+const note = (over: Partial<{ id: string; title: string; body: string; optimistic: boolean }> = {}) => ({
+  id: over.id ?? 'n_1',
+  title: over.title ?? 'first',
+  body: over.body ?? '',
+  done: false,
+  tenantId: 'acme',
+  createdAt: new Date(0),
+  ...(over.optimistic === true ? { optimistic: true } : {}),
+})
+
+/** `notes.create` resolves by default; a case that needs the failure path
+ *  overrides it. The harness records every call on `client.calls`. */
+const harness = (
+  subscriptions: Readonly<Record<string, unknown>> = {},
+  create: (input: unknown) => unknown = () => undefined,
+): VoltroTestClient =>
+  makeVoltroTestClient({ subscriptions, mutations: { 'notes.create': create } })
 
 // The page uses <T>/useTFn, so it needs an <I18nProvider>. Wrap with the real
 // English catalog (the framework auto-wires this provider in the running app).
-const render = (node: ReactNode): void => {
+const render = (): void => {
   container = document.createElement('div')
   document.body.appendChild(container)
   act(() => {
     root = createRoot(container)
     root.render(
-      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+      createElement(I18nProvider, {
+        locale: 'en',
+        messages: enCatalog,
+        defaultLocale: 'en',
+        children: createElement(client.Provider, null, createElement(IndexPage) as ReactNode),
+      }),
     )
   })
 }
@@ -61,13 +81,14 @@ const setInput = (el: HTMLInputElement | HTMLTextAreaElement, value: string): vo
   })
 }
 
-beforeEach(() => {
-  useSubscription.mockReset()
-  mutate.mockReset()
-  mutate.mockResolvedValue(undefined)
-  useMutation.mockClear()
-  useMutation.mockReturnValue({ mutate, pending: false, error: undefined, data: undefined })
-})
+const submit = async (): Promise<void> => {
+  const form = container.querySelector('form') as HTMLFormElement
+  await act(async () => {
+    form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+  })
+}
+
+beforeEach(() => { client = harness() })
 
 afterEach(() => {
   if (root) act(() => root.unmount())
@@ -76,53 +97,43 @@ afterEach(() => {
 })
 
 describe('index — subscription states', () => {
-  test('shows the loading hint before the first snapshot (data undefined)', () => {
-    useSubscription.mockReturnValue({ data: undefined, revision: -1 })
-    render(createElement(IndexPage))
+  test('shows the loading hint before the first snapshot', () => {
+    // A tag with no fixture IS the cold state — no stub had to invent one.
+    render()
     expect(container.textContent).toContain('loading…')
     expect(container.querySelectorAll('li')).toHaveLength(0)
   })
 
   test('shows the empty state once a snapshot arrives with no rows', () => {
-    useSubscription.mockReturnValue({ data: [], revision: 0 })
-    render(createElement(IndexPage))
+    client = harness({ [LIST]: [] })
+    render()
     expect(container.textContent).toContain('No notes yet')
   })
 
   test('renders each note with its title and body', () => {
-    useSubscription.mockReturnValue({
-      data: [
-        { id: 'n_1', title: 'first', body: 'body one', done: false, tenantId: 'acme', createdAt: new Date(0) },
-        { id: 'n_2', title: 'second', body: '', done: false, tenantId: 'acme', createdAt: new Date(0) },
-      ],
-      revision: 3,
-    })
-    render(createElement(IndexPage))
-    const items = Array.from(container.querySelectorAll('li'))
-    expect(items).toHaveLength(2)
+    client = harness({ [LIST]: [note({ id: 'n_1', title: 'first', body: 'body one' }), note({ id: 'n_2', title: 'second' })] })
+    render()
+    expect(container.querySelectorAll('li')).toHaveLength(2)
     expect(container.textContent).toContain('first')
     expect(container.textContent).toContain('body one')
     expect(container.textContent).toContain('second')
   })
 
-  test('renders optimistic rows faintly + italicised', () => {
-    useSubscription.mockReturnValue({
-      data: [
-        { id: 'n_opt', title: 'pending', body: '', done: false, tenantId: 'acme', createdAt: new Date(0), optimistic: true },
-      ],
-      revision: 1,
-      pendingPatches: 1,
+  test('renders optimistic rows faintly + italicised, with the pending count', () => {
+    client = harness({ [LIST]: [] })
+    render()
+    act(() => {
+      client.setSubscription(LIST, [note({ id: 'n_opt', title: 'pending', optimistic: true })], { pendingPatches: 1 })
     })
-    render(createElement(IndexPage))
     const li = container.querySelector('li')!
     expect(li.style.opacity).toBe('0.5')
     expect(li.style.fontStyle).toBe('italic')
     expect(container.textContent).toContain('1 pending')
   })
 
-  test('renders the subscription error banner when error is set', () => {
-    useSubscription.mockReturnValue({ data: undefined, error: 'boom', revision: -1 })
-    render(createElement(IndexPage))
+  test('renders the subscription error banner when the stream fails', () => {
+    render()
+    act(() => { client.failSubscription(LIST, 'boom') })
     expect(container.textContent).toContain('subscription error')
     expect(container.textContent).toContain('boom')
   })
@@ -130,38 +141,75 @@ describe('index — subscription states', () => {
 
 describe('index — create form', () => {
   test('the Add button is disabled until a non-empty title is typed', () => {
-    useSubscription.mockReturnValue({ data: [], revision: 0 })
-    render(createElement(IndexPage))
+    client = harness({ [LIST]: [] })
+    render()
     const button = container.querySelector('button[type="submit"]') as HTMLButtonElement
     expect(button.disabled).toBe(true)
     setInput(container.querySelector('input') as HTMLInputElement, 'a note')
     expect(button.disabled).toBe(false)
   })
 
-  test('submitting calls create.mutate with the trimmed title + body + tenant, then clears', async () => {
-    useSubscription.mockReturnValue({ data: [], revision: 0 })
-    render(createElement(IndexPage))
-    const input = container.querySelector('input') as HTMLInputElement
-    const textarea = container.querySelector('textarea') as HTMLTextAreaElement
-    setInput(input, '  my title  ')
-    setInput(textarea, '  my body  ')
-    const form = container.querySelector('form') as HTMLFormElement
-    await act(async () => {
-      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
-    })
-    expect(mutate).toHaveBeenCalledWith({ tenantId: 'acme', title: 'my title', body: 'my body' })
-    expect(input.value).toBe('')
-    expect(textarea.value).toBe('')
+  test('submitting calls notes.create with the trimmed title + body + tenant, then clears', async () => {
+    client = harness({ [LIST]: [] })
+    render()
+    setInput(container.querySelector('input') as HTMLInputElement, '  my title  ')
+    setInput(container.querySelector('textarea') as HTMLTextAreaElement, '  my body  ')
+    await submit()
+
+    expect(client.calls).toEqual([
+      { kind: 'mutation', tag: 'notes.create', input: { tenantId: 'acme', title: 'my title', body: 'my body' } },
+    ])
+    expect((container.querySelector('input') as HTMLInputElement).value).toBe('')
+    expect((container.querySelector('textarea') as HTMLTextAreaElement).value).toBe('')
   })
 
   test('a whitespace-only title does not fire a mutation', async () => {
-    useSubscription.mockReturnValue({ data: [], revision: 0 })
-    render(createElement(IndexPage))
+    client = harness({ [LIST]: [] })
+    render()
     setInput(container.querySelector('input') as HTMLInputElement, '   ')
-    const form = container.querySelector('form') as HTMLFormElement
-    await act(async () => {
-      form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+    await submit()
+    expect(client.calls).toEqual([])
+  })
+
+  test('a REJECTED create leaves the form cleared and the list untouched', async () => {
+    client = harness({ [LIST]: [] }, () => { throw new Error('TenantMismatch') })
+    render()
+    setInput(container.querySelector('input') as HTMLInputElement, 'nope')
+    await submit()
+    expect(client.calls).toHaveLength(1)
+    expect(container.textContent).toContain('No notes yet')
+  })
+})
+
+// The reactive loop itself — a server delta into a MOUNTED tree. This is what
+// the page is a demonstration of, and what a per-mount mock cannot express.
+describe('index — the reactive loop', () => {
+  test('a delta pushed by the server re-renders the list in place', () => {
+    client = harness({ [LIST]: [note({ id: 'n_1', title: 'first' })] })
+    render()
+    expect(container.querySelectorAll('li')).toHaveLength(1)
+
+    act(() => {
+      client.setSubscription(LIST, [note({ id: 'n_1', title: 'first' }), note({ id: 'n_2', title: 'second' })])
     })
-    expect(mutate).not.toHaveBeenCalled()
+
+    expect(container.querySelectorAll('li')).toHaveLength(2)
+    expect(container.textContent).toContain('second')
+  })
+
+  test('the confirming delta clears the optimistic styling AND the pending count', () => {
+    client = harness({ [LIST]: [] })
+    render()
+    act(() => {
+      client.setSubscription(LIST, [note({ id: 'n_tmp', title: 'mine', optimistic: true })], { pendingPatches: 1 })
+    })
+    expect(container.querySelector('li')!.style.opacity).toBe('0.5')
+    expect(container.textContent).toContain('1 pending')
+
+    // The server confirms: the real row replaces the optimistic one.
+    act(() => { client.setSubscription(LIST, [note({ id: 'n_1', title: 'mine' })]) })
+
+    expect(container.querySelector('li')!.style.opacity).toBe('1')
+    expect(container.textContent).not.toContain('1 pending')
   })
 })