@fabrika/app 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -47,6 +47,11 @@
 			"types": "./src/react/index.ts",
 			"default": "./src/react/index.ts"
 		},
+		"./react/testing": {
+			"bun": "./src/react/testing.ts",
+			"types": "./src/react/testing.ts",
+			"default": "./src/react/testing.ts"
+		},
 		"./implement": {
 			"bun": "./src/implement/index.ts",
 			"types": "./src/implement/index.ts",
@@ -88,20 +93,24 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.4.0",
-		"@fabrika/auth-core": "^0.4.0",
-		"@fabrika/db": "^0.4.0",
-		"@fabrika/jwks": "^0.4.0",
-		"@fabrika/platform": "^0.4.0",
-		"@fabrika/platform-node": "^0.4.0",
-		"@fabrika/proxy-core": "^0.4.0",
+		"@fabrika/auth": "^0.4.1",
+		"@fabrika/auth-core": "^0.4.1",
+		"@fabrika/db": "^0.4.1",
+		"@fabrika/jwks": "^0.4.1",
+		"@fabrika/platform": "^0.4.1",
+		"@fabrika/platform-node": "^0.4.1",
+		"@fabrika/proxy-core": "^0.4.1",
 		"jose": "^5.9.0"
 	},
 	"peerDependencies": {
+		"@happy-dom/global-registrator": "^20.11.2",
 		"react": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"peerDependenciesMeta": {
+		"@happy-dom/global-registrator": {
+			"optional": true
+		},
 		"react": {
 			"optional": true
 		}

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.4.0
+version: 0.4.1
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors

package/skill/references/app-setup.md

@@ -19,11 +19,11 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "^0.4.0",
-		"@fabrika/db": "^0.4.0",
-		"@fabrika/provider-zerops": "^0.4.0",
-		"@fabrika/proxy-core": "^0.4.0",
-		"@fabrika/ui": "^0.4.0",
+		"@fabrika/app": "^0.4.1",
+		"@fabrika/db": "^0.4.1",
+		"@fabrika/provider-zerops": "^0.4.1",
+		"@fabrika/proxy-core": "^0.4.1",
+		"@fabrika/ui": "^0.4.1",
 		"@sentry/browser": "10.69.0",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
@@ -31,9 +31,9 @@ the SPA is added with it.
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "^0.4.0",
-		"@fabrika/cli": "^0.4.0",
-		"@fabrika/platform": "^0.4.0",
+		"@fabrika/check": "^0.4.1",
+		"@fabrika/cli": "^0.4.1",
+		"@fabrika/platform": "^0.4.1",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",
@@ -63,6 +63,12 @@ the SPA is added with it.
   `dependencies` of `install.json`, add its `overrides`, and run `bun install`. Then run the checker as
   `fabrika-check --packed <dir>/release-manifest.json`: without the flag it refuses the tarballs. A deployed
   application never takes this form; the platform build installs from the registry.
+- The local pack is the one way to run a platform checkout's packages in an application. Never `bun link` a
+  `@fabrika/*` package: a linked package resolves its dependencies and peers from the checkout, so the application
+  runs a second React (every hook fails), a second zod and a second kysely. Installed from `vendor/`, the packages
+  resolve `react`, `zod` and `kysely` from the application's own `node_modules`. The pack's version names the
+  checkout's commit: after a change in the platform, commit it, pack again, and replace the block with the new
+  `install.json`.
 
 ```json tsconfig.json
 {

package/skill/references/dev.md

@@ -50,18 +50,41 @@ export default seed
 - `scopes` names the values the seed made, by dimension, with the label a person knows them by; the picker offers
   them for a membership role.
 - Check every call the seed makes: an endpoint that refuses answers a status, and the seed goes on without its data.
-  A seed that throws stops `app dev` with `seed_failed` and no message, because the message may carry a credential;
-  run the same calls in a test to see why.
-- Mail the application sends through its own stand-ins is the seed's business. The invitations IAM would e-mail are
-  listed by `app dev` itself.
+  Throw when one does: a seed that throws stops `app dev` and prints its error with the stack.
+- `dev.runJob('<job>')` runs a cron job from the seed (`app dev` runs none on its schedule). A job's `ctx.links` works:
+  the stand-in IAM takes the job's own key. What a job's handler throws is printed with its stack, here only.
+
+## Outside the application
+
+- `dev/dev.env` holds the application's variables for `app dev`, one `NAME=value` per line (`#` comments, quotes
+  optional). They win over the shell's; a `FABRIKA_*` name is refused. Commit it: it holds stand-in values, never a
+  real secret.
+- A form's challenge passes in `app dev`: the stand-in answers Turnstile's siteverify for any token. Set the form's
+  `secret` variable to any value in `dev/dev.env`, and send a fresh `challengeToken` with each submission, as a test
+  does: a token is single use. For the widget on a page, set the `siteKey` variable to Turnstile's always-passing test
+  key `1x00000000000000000000AA`. Its token is the same every time, and `app dev` admits that one token again at each
+  submission; a deployed application records it like any other, so there it passes once.
+- Point an outside provider at the dev outbox: `app dev` captures every request the process sends to
+  `https://outbox.invalid` (`DEV_OUTBOX_ORIGIN` of `@fabrika/app/testing`) and answers `200 {"id": …}`. The mail view
+  lists each one, by the `to` and `subject` of a JSON body, and opens its body; its headers are not kept.
+- The seed's second argument reads the outbox: `outside.outbox()` is every captured request, oldest first
+  (`{ id, method, path, contentType, body }`), so the seed can open a link the application mailed.
+
+```text dev/dev.env
+# Stand-in values for fabrika app dev.
+TURNSTILE_SECRET=dev
+TURNSTILE_SITE_KEY=1x00000000000000000000AA
+MAIL_API_URL=https://outbox.invalid/mail
+MAIL_API_KEY=dev
+```
 
 ## In the browser
 
 - `/__fabrika/dev` is the picker: the personas, another role of the vocabulary (a membership role with a scope value),
-  anonymous, the link pages, and the mail IAM sent. It speaks the vocabulary's `locale` and shows its `displayName`.
+  anonymous, the link pages, and the mail: what IAM sent and what reached the dev outbox. It speaks the vocabulary's `locale` and shows its `displayName`.
 - Every SPA page carries a toolbar in the bottom corner: who you are, the personas to switch to (the page reloads as
   that caller), the picker, the link pages, and the mail. An invitation's link accepts it; the browser is the invited
   person from then on.
 - The choice stays in a cookie the application never sees. The data is gone when the command stops.
 - It serves this machine only (`--host` is a loopback address, `--port=0` picks a free port), answers no request
-  addressed to another host name, and runs no cron job: test those with `kit.runJob`.
+  addressed to another host name, and runs no cron job on its schedule: the seed runs one with `dev.runJob`, a test with `kit.runJob`.

package/skill/references/endpoint.md

@@ -342,7 +342,9 @@ A function of the slice's `queries.ts` takes the handle as a parameter typed wit
 It decides no authorization: the capability already bounds the handle.
 
 ```ts src/reports/queries.ts
-import type { DbHandle } from '@fabrika/app/contract'
+import type { DbHandle, SqlHandle } from '@fabrika/app/contract'
+import type { Ref } from '@fabrika/app/implement'
+import { z } from 'zod/v4'
 import type { app } from '../app-kit'
 
 export const statusCounts = async (
@@ -353,10 +355,34 @@ export const statusCounts = async (
 		Number(rows.find((row) => row.status === status)?.count ?? 0)
 	return { open: count('open'), doing: count('doing'), done: count('done') }
 }
+
+export const WorkloadRow = z.strictObject({
+	assignee: z.nullable(z.string()),
+	open: z.int(),
+	overdue: z.int(),
+})
+
+export const workloadRows = (
+	sql: SqlHandle<typeof app, 'read'>,
+	org: Ref<'org', 'tasks.read'>,
+	status: string | null,
+) =>
+	sql(WorkloadRow)`
+		select t.assignee,
+			count(*) filter (where t.status <> 'done')::int as open,
+			count(*) filter (where t.status <> 'done' and t.due_on < current_date)::int as overdue
+		from tasks t
+		where ${sql.scope(org, 'tasks', 't')}
+			and (${status}::text is null or t.status::text = ${status})
+		group by t.assignee
+		order by t.assignee`
 ```
 
 `DbHandle<typeof app, 'on' | 'in', '<dimension>', '<action>', 'mutation'>` is `ctx.db.target` of that form;
-`DbHandle<typeof app, 'over', …>` is `ctx.db.within`.
+`DbHandle<typeof app, 'over', …>` is `ctx.db.within`. `SqlHandle<typeof app, 'read'>` is `ctx.sql` (a `'write'` site's
+`ctx.sql` is one too; `SqlHandle<typeof app, 'write'>` for a helper that writes), and the capability is the endpoint's
+`ctx.target` (`Ref<'<dimension>', '<action>'>`) or `ctx.within` (`Within<…>`), both types of `@fabrika/app/implement`.
+`sql.scope(capability, '<table>')` is checked against the app's tables as it is in the handler.
 
 ## Raw SQL: `sql: 'read'`
 
@@ -368,18 +394,13 @@ import { attachment } from '@fabrika/app/contract'
 import { z } from 'zod/v4'
 import { app } from '../app-kit'
 import { TaskStatus } from '../schemas'
-import { statusCounts } from './queries'
+import { statusCounts, WorkloadRow, workloadRows } from './queries'
 
 const Workload = z.strictObject({
 	orgId: z.string().min(1).max(100),
 	status: TaskStatus.optional(),
 })
 const ByProject = z.strictObject({ projectId: z.uuid() })
-const WorkloadRow = z.strictObject({
-	assignee: z.nullable(z.string()),
-	open: z.int(),
-	overdue: z.int(),
-})
 const WorkloadReport = z.strictObject({ rows: z.array(WorkloadRow) })
 const Counts = z.strictObject({ open: z.int(), doing: z.int(), done: z.int() })
 const TaskExportRow = z.strictObject({
@@ -402,19 +423,9 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
 		access: { action: 'tasks.read', in: 'org', from: 'orgId' },
 		sql: 'read',
 	})
-		.handle(async ({ input, ctx }) => {
-			const status = input.status ?? null
-			const rows = await ctx.sql(WorkloadRow)`
-				select t.assignee,
-					count(*) filter (where t.status <> 'done')::int as open,
-					count(*) filter (where t.status <> 'done' and t.due_on < current_date)::int as overdue
-				from tasks t
-				where ${ctx.sql.scope(ctx.target, 'tasks', 't')}
-					and (${status}::text is null or t.status::text = ${status})
-				group by t.assignee
-				order by t.assignee`
-			return { rows }
-		}),
+		.handle(async ({ input, ctx }) => ({
+			rows: await workloadRows(ctx.sql, ctx.target, input.status ?? null),
+		})),
 	counts: r.query({
 		output: Counts,
 		access: { action: 'tasks.read', over: 'project' },
@@ -452,7 +463,9 @@ export const reports = app.group({ callers: ['human'] }, (r) => ({
   `read` action (the intake job of `references/public-intake.md`).
 - **A fragment carries its action into the statement.** On the table an `update` or `delete` writes it needs the
   table's own update or delete action (`ctx.within('tasks.write', 'project')` for `update tasks`), so a read action
-  never scopes a write; anywhere else it needs an action the handles read the table with. `insert … on conflict do
+  never scopes a write. A column's own write action (`columns: { assignee: { write: 'tasks.assign' } }`) scopes an
+  `update` too, when every column its `set` assigns declares that action: a table with only column writes is updated
+  this way; anywhere else it needs an action the handles read the table with. `insert … on conflict do
   update … where ${…}` is an update of the inserted table. The fragment answers for its own query block: a CTE that
   updates and a statement that deletes take one capability each, and another occurrence of the written table (a
   subquery, `from tasks other`) reads with a read capability under its own alias. A refused fragment fails the call

package/skill/references/errors.md

@@ -23,7 +23,7 @@ The refusals agents meet most, and their fix:
 | `type-assertion`      | `as T` (other than `as const`), `<T>x`                                                                                                                           | fix the type; `fromRow` parses a row into a schema's type                               |
 | `sensitive-log`       | a log of an error object, a request, headers or the environment                                                                                                  | log a short fixed message                                                               |
 | `migration-name`      | a migration not named `YYYYMMDDHHMMSS_slug.sql` (UTC)                                                                                                            | `bunx fabrika db new <slug>`                                                            |
-| `test-only-import`    | `@fabrika/app/testing` or `@fabrika/db/testing` outside a test file                                                                                              | import them only from `*.test.ts` or `__tests__/`                                       |
+| `test-only-import`    | `@fabrika/app/testing`, `@fabrika/app/react/testing` or `@fabrika/db/testing` outside a test file                                                                | import them only from `*.test.ts` or `__tests__/`                                       |
 | `spa-server-import`   | the SPA loads a server module                                                                                                                                    | the SPA imports `@fabrika/app/client`, the contract, `src/schemas.ts` and `src/shared/` |
 | `shared-import`       | a module under `src/shared/` loads a slice, `src/db/`, `@fabrika/*` or a builtin                                                                                 | a shared module imports `zod/v4` and other shared modules only                          |
 | `skipped-test`        | `.skip`, `.only`, `.todo`                                                                                                                                        | run the test                                                                            |

package/skill/references/spa.md

@@ -6,11 +6,12 @@ write a DOM element builder, a router, a cache or a component set of your own: w
 from the kit's components and the theme's tokens in the application's own stylesheet. `app-setup.md` shows the
 dependencies, `tsconfig.json` (`"jsx": "react-jsx"`) and `build-web.ts`.
 
-| Module                | Holds                                                                                                                                      |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@fabrika/app/client` | `createClient(contract, 'api')`: one function per procedure, its answer parsed by the output schema                                        |
-| `@fabrika/app/react`  | `FabrikaProvider`, `useQuery`, `useInfiniteQuery`, `useMutation`, `useAction`, `useInvalidate`, `skip`, `useCaller`, `Can`, `FabrikaError` |
-| `@fabrika/ui`         | the components below, `createRouter`, and `@fabrika/ui/styles.css`                                                                         |
+| Module                       | Holds                                                                                                                                                     |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@fabrika/app/client`        | `createClient(contract, 'api')`: one function per procedure, its answer parsed by the output schema                                                       |
+| `@fabrika/app/react`         | `FabrikaProvider`, `useQuery`, `useInfiniteQuery`, `useMutation`, `useAction`, `useDownload`, `useInvalidate`, `skip`, `useCaller`, `Can`, `FabrikaError` |
+| `@fabrika/app/react/testing` | `installDom`, `type`, `controlByLabel`, `waitForText`: a screen test's DOM and typing                                                                     |
+| `@fabrika/ui`                | the components below, `createRouter`, and `@fabrika/ui/styles.css`                                                                                        |
 
 ## The provider and the routes
 
@@ -94,7 +95,8 @@ if (root !== null) {
 
 - `FabrikaProvider` holds the clients of the mounts the page calls. A hook takes a procedure of a client
   (`api.tasks.get`) as the typed name of the call and runs it on the provider's client of that mount; a test hands the
-  provider a client over the test kit instead (below). An SPA mounted under a prefix passes it: `spa="/app"`.
+  provider a client over the test kit instead (below). An SPA mounted under a prefix passes it: `spa="/app"`. Its bare
+  prefix (`/app`) redirects to `/app/`, so a link may name either.
 - `createRouter` answers typed paths: `href('task', { id })`, `navigate('project', { orgId, projectId })`, `<Link
   to="task" params={{ id }}>`, and `useRoute()`, the match or `null`. `<Router>` makes every plain `<a href>` under the
   SPA navigate without a reload: the kit's components render links that way. Pass `{ base: '/app' }` for a prefix.
@@ -248,6 +250,12 @@ export function MyTasks() {
 - `useInfiniteQuery(procedure, input)` is for a list that answers `{ items, next }` and takes `after`: `items` are the
   loaded pages, `hasMore` and `loadMore()` the next page. `{ pages: 'all' }` reads every page at once, for a picker's
   options; use it for small lists only.
+- An offset list that answers `{ items, total }` and takes `limit` and `offset` is `useQuery` with `{ keepPrevious:
+  true }`: while the answer of a new `limit` or `offset` loads, `data` stays the previous answer (`status: 'success'`,
+  `fetching: true`), so the table keeps its rows. "Load more (n of N)" grows `limit` in the page's state:
+  `useQuery(api.tasks.queue, { orgId, limit, offset: 0 }, { keepPrevious: true })` with `loadMore={{ hasMore:
+  data.items.length < data.total, loading: queue.fetching, onLoadMore: () => setLimit(limit + 50) }}`; a pager sets
+  `offset` instead. A filter change resets `limit` or `offset`.
 
 ## Writing: useMutation, forms and their errors
 
@@ -350,6 +358,9 @@ export function EditTask(
 - A call that is no procedure — a file collection's `api.files.<name>.upload(owner, file)`, `list`, `download` —
   runs through `useAction(async (input) => …)`, with the same state and error union; it refetches only what
   `invalidates` names.
+- An attachment procedure (`output: attachment(…)`) downloads through `useDownload(api.reports.exportProject)`:
+  `mutate(input)` saves the file and answers it, with the same state and error union. It runs on the provider's client,
+  so a screen test downloads over the kit; never call `download(api.…)` of the module's client from a screen.
 
 ## Who is signed in: useCaller and Can
 
@@ -598,31 +609,31 @@ export function TaskView({ id }: { readonly id: string }) {
 All are named exports of `@fabrika/ui`, keyboard operable, and labelled for assistive technology. Text they render
 themselves ("Load more", "Clear selection", "Close", "Retry") is a prop with an English default.
 
-| Component                                                                                    | What it is                                                                                      |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `AppShell({ brand, nav, user, actions })`                                                    | sidebar navigation (`{ label, href, active, count }`), top bar with the caller, the main region |
-| `PageHeader({ title, lead, back, actions, meta })`                                           | the screen's `h1`, a line of purpose, a back link, its buttons; one `primary` button per screen |
-| `Tabs({ label, items, active, onChange })`                                                   | tabs with counts; arrow keys, Home and End                                                      |
-| `FilterBar({ onReset })` + `Field`                                                           | a row of filters with a reset                                                                   |
-| `Field({ label, name, hint, error, required })`                                              | label, hint and error around one control; the error comes from the `Form` by `name`             |
-| `Input`, `Textarea`, `Select({ options, placeholder })`                                      | the controls; native props pass through                                                         |
-| `DateInput`, `DateRange({ from, to, onChange })`                                             | a day, and a from–to pair of days                                                               |
-| `Checkbox({ label, checked, onChange, indeterminate })`                                      | one checkbox                                                                                    |
-| `RadioGroup({ label, name, options, value, onChange })`                                      | a fieldset of radios                                                                            |
-| `Button({ variant, size, loading })`, `ButtonLink`                                           | `primary`, `secondary` (default), `ghost`, `danger`; `loading` disables and shows a spinner     |
-| `DataTable({ columns, rows, rowKey, status, selection, selectionActions, loadMore, empty })` | compact rows, loading/error/empty rows, a selection toolbar, a load-more button                 |
-| `useSelection()`                                                                             | the `selection` a `DataTable` takes, with `clear()`                                             |
-| `StatusPill({ tone })`                                                                       | `neutral`, `info`, `success`, `warning`, `danger`, `accent`                                     |
-| `FieldList({ items, columns })`                                                              | label/value pairs; an empty value shows a dash                                                  |
-| `Card({ title, actions, footer })`, `Section({ title, description, actions })`               | a framed block, and a titled block without the frame                                            |
-| `Columns` + `SidePanel`                                                                      | the main column and a side column, stacked on a narrow screen                                   |
-| `Dialog({ open, title, onClose })`, `ConfirmDialog`                                          | modal: focus moves in and is trapped, Escape closes, focus returns                              |
-| `ToastProvider`, `useToast().show({ tone, message })`                                        | short notices that leave by themselves                                                          |
-| `Timeline({ items, empty })`                                                                 | history and notes: `{ id, at, title, body }`                                                    |
-| `EmptyState`, `ErrorState({ text, onRetry })`, `LoadingState`, `Spinner`, `CountBadge`       | the states of a region                                                                          |
-| `Stack({ gap })`, `Inline({ gap, align, justify, wrap })`                                    | layout with the spacing scale                                                                   |
-| `Form({ onSubmit, error })`, `FormActions`                                                   | a form that shows a hook's error: the summary and each field's message                          |
-| `createRouter(routes, { base })`                                                             | `Router`, `Link`, `useRoute`, `href`, `navigate`, typed by the patterns                         |
+| Component                                                                                    | What it is                                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AppShell({ brand, nav, user, actions, topBar, navStyle })`                                  | sidebar navigation (`{ label, href, active, count }`), a top bar with the caller (none without `user` or `actions`, or with `topBar={false}`), the main region; `navStyle="filled"` fills the current item |
+| `PageHeader({ title, lead, back, actions, meta })`                                           | the screen's `h1`, a line of purpose, a back link, its buttons; one `primary` button per screen                                                                                                            |
+| `Tabs({ label, items, active, onChange, variant })`                                          | tabs with counts; arrow keys, Home and End; `variant="boxed"` frames each tab, its count after a dot                                                                                                       |
+| `FilterBar({ onReset })` + `Field`                                                           | a row of filters with a reset                                                                                                                                                                              |
+| `Field({ label, name, hint, error, required })`                                              | label, hint and error around one control; the error comes from the `Form` by `name`                                                                                                                        |
+| `Input`, `Textarea`, `Select({ options, placeholder })`                                      | the controls; native props pass through                                                                                                                                                                    |
+| `DateInput`, `DateRange({ from, to, onChange })`                                             | a day, and a from–to pair of days                                                                                                                                                                          |
+| `Checkbox({ label, checked, onChange, indeterminate })`                                      | one checkbox                                                                                                                                                                                               |
+| `RadioGroup({ label, name, options, value, onChange })`                                      | a fieldset of radios                                                                                                                                                                                       |
+| `Button({ variant, size, loading })`, `ButtonLink`                                           | `primary`, `secondary` (default), `ghost`, `danger`; `loading` disables and shows a spinner                                                                                                                |
+| `DataTable({ columns, rows, rowKey, status, selection, selectionActions, loadMore, empty })` | compact rows, loading/error/empty rows, a selection toolbar, a load-more button; a column takes `width` (`'xs'`…`'xl'`) and `wrap`                                                                         |
+| `useSelection()`                                                                             | the `selection` a `DataTable` takes, with `clear()`                                                                                                                                                        |
+| `StatusPill({ tone, dot })`                                                                  | `neutral`, `info`, `success`, `warning`, `danger`, `accent`; `dot={false}` leaves the dot out                                                                                                              |
+| `FieldList({ items, columns })`                                                              | label/value pairs; an empty value shows a dash                                                                                                                                                             |
+| `Card({ title, actions, footer })`, `Section({ title, description, actions })`               | a framed block, and a titled block without the frame                                                                                                                                                       |
+| `Columns` + `SidePanel`                                                                      | the main column and a side column, stacked on a narrow screen                                                                                                                                              |
+| `Dialog({ open, title, onClose })`, `ConfirmDialog`                                          | modal: focus moves in and is trapped, Escape closes, focus returns                                                                                                                                         |
+| `ToastProvider`, `useToast().show({ tone, message })`                                        | short notices that leave by themselves                                                                                                                                                                     |
+| `Timeline({ items, empty })`                                                                 | history and notes: `{ id, at, title, body }`                                                                                                                                                               |
+| `EmptyState`, `ErrorState({ text, onRetry })`, `LoadingState`, `Spinner`, `CountBadge`       | the states of a region                                                                                                                                                                                     |
+| `Stack({ gap })`, `Inline({ gap, align, justify, wrap })`                                    | layout with the spacing scale                                                                                                                                                                              |
+| `Form({ onSubmit, error })`, `FormActions`                                                   | a form that shows a hook's error: the summary and each field's message                                                                                                                                     |
+| `createRouter(routes, { base })`                                                             | `Router`, `Link`, `useRoute`, `href`, `navigate`, typed by the patterns                                                                                                                                    |
 
 ## Theming
 
@@ -646,6 +657,12 @@ body {
 - The palette is neutral with one accent (`--fui-accent*`), plus tones for status (`--fui-success`, `--fui-warning`,
   `--fui-danger`, `--fui-info`, each with `-soft` and `-text`). Typography (`--fui-font-family`, `--fui-text-*`),
   spacing (`--fui-space-1`…`8`), radii, borders and shadows are tokens too.
+- So are the parts a design changes most: the main region's padding (`--fui-main-padding`, `-narrow` below the
+  breakpoint), a field's label (`--fui-label-size`, `--fui-label-weight`, `--fui-label-color`), a table's column heads
+  (`--fui-table-head-size`, `-weight`, `-color`, `-transform`, `-tracking`: `uppercase` and `0.04em` for small
+  capitals) and the column widths (`--fui-column-width-xs`…`xl`). Change the look through tokens and the components'
+  props (`navStyle`, `variant`, `dot`, a column's `width` and `wrap`); never restyle a kit class name (`.fui-…`), which
+  is no contract and changes with the kit.
 - Light is the default. `<html data-theme="dark">` switches to the dark token set; the page decides when (a toggle, or
   `matchMedia('(prefers-color-scheme: dark)')`).
 - The kit loads nothing from another origin, so it runs under the default CSP. The font token is a system stack; for
@@ -657,30 +674,21 @@ body {
 
 A screen test renders the page in happy-dom (`@happy-dom/global-registrator`, a devDependency) over the application
 itself, behind the test kit's proxy decision: the provider gets a client whose `fetch` is the kit's browser for a
-test caller.
+test caller. `installDom` of `@fabrika/app/react/testing` sets the DOM up.
 
 ```ts web/__tests__/dom.ts
-import { GlobalRegistrator } from '@happy-dom/global-registrator'
+import { installDom } from '@fabrika/app/react/testing'
 import { afterAll } from 'bun:test'
 
-const runtime = {
-	fetch: globalThis.fetch,
-	Request: globalThis.Request,
-	Response: globalThis.Response,
-	Headers: globalThis.Headers,
-}
-GlobalRegistrator.register({ url: 'http://tasks.test/' })
-Object.assign(globalThis, runtime)
-afterAll(async () => {
-	await new Promise((resolve) => setTimeout(resolve, 50))
-	await GlobalRegistrator.unregister()
-})
+const dom = installDom({ url: 'http://tasks.test/' })
+afterAll(() => dom.uninstall())
 ```
 
 ```tsx web/__tests__/mine.test.tsx
 import './dom'
 import { createClient } from '@fabrika/app/client'
 import { FabrikaProvider } from '@fabrika/app/react'
+import { waitForText } from '@fabrika/app/react/testing'
 import { testKit } from '@fabrika/app/testing'
 import { testDatabase } from '@fabrika/db/testing'
 import { ToastProvider } from '@fabrika/ui'
@@ -718,14 +726,7 @@ if (postgres !== null) {
 				</ToastProvider>
 			</FabrikaProvider>,
 		)
-		for (
-			let tries = 0;
-			tries < 200
-			&& !document.body.textContent?.includes('Nothing assigned to you.');
-			tries++
-		) {
-			await new Promise((resolve) => setTimeout(resolve, 10))
-		}
+		await waitForText('Nothing assigned to you.')
 		expect(document.body.textContent).toContain('Nothing assigned to you.')
 		expect(document.querySelector('[role="toolbar"]')).toBeNull()
 		root.unmount()
@@ -733,9 +734,13 @@ if (postgres !== null) {
 }
 ```
 
-- `web/__tests__/dom.ts` comes first: imports run in order, and React reads `window` when it loads. Bun's `fetch` is
-  kept, because the clients and the kit run on it. Run the tests with `bun test --isolate`, which gives each file its
-  own globals.
+- `web/__tests__/dom.ts` comes first: imports run in order, and React reads `window` when it loads. `installDom` keeps
+  Bun's `fetch`, `AbortController`, `URL`, `Blob`, `File` and `FormData`, because the clients, the kit, a form's
+  challenge and a download run on them, and turns navigation off, so a download's link click leaves the page for the
+  next test. Run the tests with `bun test --isolate`, which gives each file its own globals.
+- `await type('Title', 'report')` types into the control whose label (or `aria-label`) is `Title` as React reads a
+  person typing; a select takes the option's value. `controlByLabel(label)` answers the control, and
+  `waitForText(text)` waits until the page shows it.
 - Wait for what the page shows, as a person does; assert on text, roles and ARIA, never on layout (happy-dom lays out
   nothing). A refused twin is a caller without the role: the button is gone, and the endpoint still answers 403.
 - Pure mapping (a label, a tone, a field's value) is a function of `web/` with a plain test.

package/skill/references/tests.md

@@ -281,14 +281,17 @@ if (postgres !== null) {
 - `kit.testCaller(grants, { disabled: true })` is a person an operator disabled: the directory lists and finds them
   with `disabled: true`, so an assignment of them answers your handler's 400, and their own requests are refused (401 for
   a session, 403 for a key).
-- `kit.runJob('<job>')` runs a cron job once and answers `{ status: 'succeeded', attempts }`.
+- `kit.runJob('<job>')` runs a cron job once and answers `{ status: 'succeeded', attempts }`. A job's `ctx.links`
+  reaches the kit's stand-in IAM under the job's own key, so a job that declares `issues` issues and revokes links in a
+  plain `testKit` and under `fabrika app dev`, as IAM allows it: for its declared mount only.
 - An application with files passes `files: new MemoryFileObjects()` (`@fabrika/platform/testing`) to `testKit`;
   without it the application does not boot. With `scan: true`, an upload stays `quarantined` until
   `kit.runJob(FILE_SCAN_JOB)` (`@fabrika/app/implement`) runs with a `scanner` passed to `testKit`: a `FileScanner`
   stand-in, or the real ClamAV one, `clamscanScanner()` of `@fabrika/app/bun`.
 - A form's challenge token is single use: a second submission with the same token answers 400 `challenge_failed`,
   also when the test's `challengeFetch` answers success. Send a fresh token with each submission
-  (`crypto.randomUUID()`).
+  (`crypto.randomUUID()`). `passingChallenge` (`@fabrika/app/testing`) is a `challengeFetch` that passes every token;
+  a stand-in of your own receives the check (`hostname`, `action`) a passing answer must confirm as its second argument.
 - `testKit` takes no `deps`, and a test may not start a server (`Bun.serve` is `forbidden-global`). Stand in for an
   outbound dependency through its variables: `env` points it at a test URL, and `spyOn(globalThis, 'fetch')` answers
   that URL only and passes every other request on (`src/__tests__/mail-stand-in.ts` in `references/public-intake.md`).

package/src/client/contract.ts

@@ -175,20 +175,34 @@ export interface AttachmentProcedure<I> {
 	readonly [attachmentInput]?: I
 }
 
-/** The request each attachment procedure sends, kept beside it so the value itself carries no key. */
-const downloads = new WeakMap<object, { readonly url: string; readonly options: ClientOptions; readonly bounce: BounceConfig | null }>()
+/** The request each attachment procedure sends and where it lies, kept beside it so the value itself carries no key. */
+interface DownloadRequest {
+	readonly url: string
+	readonly filename: string
+	readonly options: ClientOptions
+	readonly bounce: BounceConfig | null
+	readonly at: { readonly mount: string; readonly path: string }
+}
+
+const downloads = new WeakMap<object, DownloadRequest>()
 
 function attachmentProcedure(
 	target: CallTarget,
+	at: TreeAt,
 	filename: string,
 	options: ClientOptions,
 	bounce: BounceConfig | null,
 ): AttachmentProcedure<unknown> {
 	const procedure = Object.freeze({ id: target.id, filename })
-	downloads.set(procedure, { url: target.url, options, bounce })
+	downloads.set(procedure, { url: target.url, filename, options, bounce, at: { mount: at.mount, path: at.path } })
 	return procedure
 }
 
+/** The mount and path of an attachment procedure of a client, or `null` for any other value. */
+export function attachmentAt(value: unknown): { readonly mount: string; readonly path: string } | null {
+	return typeof value === 'object' && value !== null ? (downloads.get(value)?.at ?? null) : null
+}
+
 /** The input `download` takes: the procedure's, or none. */
 export type DownloadInput<I> = [I] extends [InputSchema] ? [input: z.input<I>] : [input?: Record<never, never>]
 
@@ -196,13 +210,21 @@ export type DownloadInput<I> = [I] extends [InputSchema] ? [input: z.input<I>] :
  * Calls an attachment procedure and saves its file: in a browser the page offers it as a download under the declared
  * name. Answers the file, also where there is no page to save it from (a script, a test). A refusal is an `RpcError`.
  */
-export async function download<I>(procedure: AttachmentProcedure<I>, ...input: DownloadInput<I>): Promise<File> {
+export function download<I>(procedure: AttachmentProcedure<I>, ...input: DownloadInput<I>): Promise<File> {
+	if (!downloads.has(procedure)) {
+		return Promise.reject(new Error(`'${procedure.id}' is not an attachment procedure of a client`))
+	}
+	return downloadFile(procedure, input[0])
+}
+
+/** `download` of any attachment procedure of a client, its input unchecked: the provider's `useDownload` runs it. */
+export async function downloadFile(procedure: object, input: unknown): Promise<File> {
 	const request = downloads.get(procedure)
 	if (request === undefined) {
-		throw new Error(`'${procedure.id}' is not an attachment procedure of a client`)
+		throw new Error('download takes an attachment procedure of a client createClient made')
 	}
-	const { body } = await exchangeFile(request.options.fetch ?? fetch, request.url, requestOf(request.options, input[0]), request.bounce)
-	const file = new File([body], procedure.filename, { type: body.type })
+	const { body } = await exchangeFile(request.options.fetch ?? fetch, request.url, requestOf(request.options, input), request.bounce)
+	const file = new File([body], request.filename, { type: body.type })
 	saveFile(file)
 	return file
 }
@@ -283,7 +305,7 @@ export function createClient<const C extends AnyContract, const M extends Client
 	}
 	const procedures = clientTree(node.procedures, { mount, origin, base, path: '' }, (target, at) => {
 		const mark = attachmentOf(target.output)
-		return mark === null ? caller(target, at, options, bounce) : attachmentProcedure(target, mark.declaration.filename, options, bounce)
+		return mark === null ? caller(target, at, options, bounce) : attachmentProcedure(target, at, mark.declaration.filename, options, bounce)
 	})
 	const transport: FileTransport = { origin, fetch: options.fetch ?? fetch, key: options.key, bounce }
 	const collections = Object.entries(surface.files ?? {}).flatMap(([name, collection]): (readonly [string, FileClient | LinkFileClient])[] => {

package/src/contract/build.ts

@@ -83,6 +83,7 @@ import {
 	joinPath,
 	JSON_ADMISSION,
 	LINK_API_SEGMENT,
+	spaPrefixRowId,
 	WEBHOOK_ACCOUNT_PATTERN,
 	WEBHOOK_BINDING_PARAMETER,
 	WEBHOOK_SCOPE_FIELD,
@@ -499,23 +500,18 @@ class ArtifactBuilder {
 					this.#prefix(where, mount.prefix)
 				}
 				this.#nonEmpty(`${where} dir`, mount.dir)
-				const path = joinPath(mount.prefix, '*')
 				const requirement = this.#spaRequirement(where, mount.access)
-				if (requirement === 'public') {
-					this.#anonymous(name, 'public-spa', 'GET', path, null, null)
-				} else if (requirement !== null) {
-					this.#row({
-						id: name,
-						source: { kind: 'mount', name },
-						kind: 'spa',
-						method: 'GET',
-						path,
-						callers: ['human'],
-						requirement,
-						admission: null,
-						input: null,
-						output: null,
-					})
+				// The bare prefix (`/admin`) is the mount's too, under its access: it redirects to `/admin/`.
+				const rows = mount.prefix === '/'
+					? [{ id: name, path: joinPath(mount.prefix, '*') }]
+					: [{ id: name, path: joinPath(mount.prefix, '*') }, { id: spaPrefixRowId(name), path: mount.prefix }]
+				for (const { id, path } of rows) {
+					const source = { kind: 'mount' as const, name }
+					if (requirement === 'public') {
+						this.#row({ id, source, kind: 'public-spa', method: 'GET', path, callers: [], requirement: null, admission: null, input: null, output: null })
+					} else if (requirement !== null) {
+						this.#row({ id, source, kind: 'spa', method: 'GET', path, callers: ['human'], requirement, admission: null, input: null, output: null })
+					}
 				}
 				const publicVariables = this.#spaPublic(where, mount.public)
 				return { kind: 'spa', prefix: mount.prefix, dir: mount.dir, ...(publicVariables.length === 0 ? {} : { public: publicVariables }) }

package/src/contract/context.ts

@@ -435,3 +435,10 @@ export type AppHandle<A, Act extends string, K extends DataKind = 'query'> = App
 
 /** The type of `ctx.db.reference`, for a query function that takes it. */
 export type ReferenceHandle<A> = ReferenceTables<IndexOf<A>>
+
+/**
+ * The type of `ctx.sql`, for a function of `src/<slice>/queries.ts` that takes it: `SqlHandle<typeof app, 'read'>`.
+ * A `'write'` site's `ctx.sql` is assignable to it, and `sql.scope(capability, table)` checks the table against the
+ * app's own tables.
+ */
+export type SqlHandle<A, M extends SqlMode> = SqlTag<IndexOf<A>, M>