@fabrika/app 0.4.0 → 0.4.2

package/src/contract/defaults.ts

@@ -111,6 +111,11 @@ export const BROWSER_CONFIG_FILE = '__fabrika-config.json'
 /** What every `c.spa` mount serves under its prefix to the person its access admitted: label, mailbox and actions. */
 export const PAGE_CALLER_FILE = '__fabrika-me.json'
 
+/** The row of an SPA mount's bare prefix (`GET /admin`), which redirects to the mount (`/admin/`). */
+export function spaPrefixRowId(mount: string): string {
+	return `${mount}.prefix`
+}
+
 /**
  * The value a generated endpoint access case sends in an input field that names a member the handler looks up
  * (`members` of `endpoint-access.fixtures.ts`); the endpoint access kit replaces it with a real member of the directory.

package/src/implement/boot.ts

@@ -38,14 +38,14 @@ import type { FileObjectStore } from '@fabrika/platform'
 import { compileContract } from '../contract/compile'
 import { exportDescription } from '../contract/connect'
 import { isProcedure, type ProcedureDeclaration, type ProcedureTreeDeclaration, SURFACE_SECTIONS } from '../contract/declaration'
-import { exportBase, FORM_CHALLENGE_FIELD, FORM_LIMITS } from '../contract/defaults'
+import { exportBase, FORM_CHALLENGE_FIELD, FORM_LIMITS, spaPrefixRowId } from '../contract/defaults'
 import type { Schema } from '../contract/define'
 import { kitOriginOf } from '../contract/handled'
 import type { RequestExecutionContext } from '../fetch'
 import { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE, FILE_SWEEP_TIMEOUT_MS, fileCollections } from '../files/collections'
 import { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE, type FileScanner, SCAN_LIMITS } from '../files/scan'
 import { logReporter, type OperationsReporter, operationsReporter, operationsSettings, type ReportSource } from '../jobs/report'
-import { bindJobs, type ContractJobs } from '../jobs/runner'
+import { bindJobs, type ContractJobs, type HandlerErrorSink } from '../jobs/runner'
 import { browserConfigs } from './browser-config'
 import { createCapabilityIssuer, requestIsReadOnly } from './capability'
 import { type ChallengeFetch, type ChallengeVerifier, turnstileVerifier } from './challenge'
@@ -116,6 +116,16 @@ export interface BootOptions {
 	readonly operationsFetch?: (request: Request) => Promise<Response>
 	/** What asks a form's challenge provider to verify a token; `fetch` by default. */
 	readonly challengeFetch?: ChallengeFetch
+	/**
+	 * The developer's own machine only (`fabrika app dev`): the token a form's challenge admits more than once, which
+	 * Turnstile's always-passing test widget hands out for every submission. Every other token stays single use.
+	 */
+	readonly repeatableChallengeToken?: string
+	/**
+	 * The developer's own machine only (`fabrika app dev`): what a job's handler threw, which every log of a deployed
+	 * application withholds because it may carry a credential.
+	 */
+	readonly revealHandlerErrors?: HandlerErrorSink
 }
 
 export interface ContractApp {
@@ -527,6 +537,7 @@ function formAdmission(name: string, artifact: ContractArtifact, options: BootOp
 		perForm: mount.rate?.perForm ?? FORM_LIMITS.perForm,
 		fields: Object.freeze(submissionFieldsOf(mount)),
 		challenge,
+		repeatableToken: challenge === null ? null : (options.repeatableChallengeToken ?? null),
 	})
 }
 
@@ -640,6 +651,10 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 			} else if (config !== undefined && row?.kind === 'public-spa') {
 				endpoints.set(name, { kind: 'public-spa', row, prefix: mount.prefix, dir: mount.dir, config })
 			}
+			const bare = rows.get(spaPrefixRowId(name))
+			if (bare !== undefined) {
+				endpoints.set(bare.id, { kind: 'spa-prefix', row: bare, prefix: mount.prefix })
+			}
 		} else if (mount.kind === 'rpc' || mount.kind === 'link') {
 			if (mount.kind === 'link') {
 				const row = rows.get(name)
@@ -728,6 +743,7 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
 		membership,
 		capabilities: issuer.authority,
 		containers,
+		...(options.revealHandlerErrors === undefined ? {} : { revealHandlerErrors: options.revealHandlerErrors }),
 	}, problems)
 	for (const id of jobs.declared) {
 		declared.add(id)

package/src/implement/challenge.ts

@@ -20,7 +20,11 @@ export const CHALLENGE_LIMITS = {
 	maxSkewMs: 60_000,
 } as const
 
-export type ChallengeFetch = (request: Request) => Promise<Response>
+/**
+ * How the siteverify request reaches the provider. `check` is what a passing answer confirms (the host and the form),
+ * for a stand-in that answers as the provider would; the provider itself reads only the request.
+ */
+export type ChallengeFetch = (request: Request, check: ChallengeCheck) => Promise<Response>
 
 /** `failed` is the visitor's (400); `unavailable` and `misconfigured` are the platform's or the operator's (503). */
 export type ChallengeOutcome = 'passed' | 'failed' | 'unavailable' | 'misconfigured'
@@ -73,6 +77,7 @@ export function turnstileVerifier(secret: string, fetch: ChallengeFetch, now: ()
 						redirect: 'manual',
 						signal: deadline.signal,
 					}),
+					check,
 				)
 				const type = response.headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase()
 				if (response.status !== 200 || type !== 'application/json') {

package/src/implement/dispatch.ts

@@ -124,6 +124,8 @@ export type ServedEndpoint =
 	/** What an export's consumer vendors, behind the export's own callers. */
 	| { readonly kind: 'description'; readonly row: CredentialedEndpoint; readonly description: ExportDescription }
 	| { readonly kind: 'spa'; readonly row: CredentialedEndpoint; readonly prefix: string; readonly dir: string; readonly config: BrowserConfig }
+	/** An SPA mount's bare prefix (`/admin`): the proxy admitted it under the mount's access; it redirects to `/admin/`. */
+	| { readonly kind: 'spa-prefix'; readonly row: EndpointRow; readonly prefix: string }
 	/** An SPA anyone opens: anonymous, served without a token. */
 	| { readonly kind: 'public-spa'; readonly row: EndpointRow; readonly prefix: string; readonly dir: string; readonly config: BrowserConfig }
 	| { readonly kind: 'health'; readonly row: EndpointRow }
@@ -172,6 +174,8 @@ export interface FormAdmission {
 	readonly fields: SubmissionFields
 	/** The challenge's verifier, with the secret the application variable holds; `null` without a challenge. */
 	readonly challenge: ChallengeVerifier | null
+	/** The one token the challenge does not record, so it passes again: `fabrika app dev`'s test widget's; `null` otherwise. */
+	readonly repeatableToken: string | null
 }
 
 export interface RuntimeParts {
@@ -290,6 +294,8 @@ export class ContractRuntime {
 				}
 				case 'public-spa':
 					return await this.#spaFile(served, request, null)
+				case 'spa-prefix':
+					return new Response(null, { status: 308, headers: { Location: `${served.prefix}/${new URL(request.url).search}` } })
 				case 'link-spa':
 					if (rawRequestTarget(request.url).pathname === bootstrapPath(served.prefix)) {
 						return bootstrapResponse()
@@ -720,7 +726,7 @@ export class ContractRuntime {
 			return jsonResponse({ result: { received: true } }, 200)
 		}
 		if (admission.challenge !== null) {
-			await this.#challenge(served.form, admission.challenge, submission.token, request)
+			await this.#challenge(served.form, admission.challenge, submission.token, request, admission.repeatableToken)
 		}
 		// One transaction: a row that fails to insert gives its place in the form's bucket back.
 		if (!(await this.#framework().appendToInbox(served.form, submission.row, { bucket: ACCEPTED_BUCKET, limit: admission.perForm }))) {
@@ -734,8 +740,11 @@ export class ContractRuntime {
 		return jsonResponse({ result: { received: true } }, 200)
 	}
 
-	/** The token verifies for this host and this form, and was not accepted before: a failure is 400, an unreachable provider 503. */
-	async #challenge(form: string, verifier: ChallengeVerifier, token: string | null, request: Request): Promise<void> {
+	/**
+	 * The token verifies for this host and this form, and was not accepted before unless it is the `repeatable` one: a
+	 * failure is 400, an unreachable provider 503.
+	 */
+	async #challenge(form: string, verifier: ChallengeVerifier, token: string | null, request: Request, repeatable: string | null): Promise<void> {
 		const outcome = token === null ? 'failed' : await verifier.verify({ token, hostname: new URL(request.url).hostname, action: form })
 		if (outcome === 'unavailable') {
 			throw new ServerFault('challenge_unavailable', `the ${verifier.provider} challenge of '${form}' could not be verified`, 503)
@@ -744,7 +753,8 @@ export class ContractRuntime {
 			throw new ServerFault('challenge_misconfigured', `the ${verifier.provider} challenge of '${form}' refused the application's secret`, 503)
 		}
 		const refused = token === null || outcome === 'failed'
-			|| !(await this.#framework().forms.recordChallenge(form, sha256Hex(token), CHALLENGE_LIMITS.maxAgeMs + CHALLENGE_LIMITS.maxSkewMs))
+			|| (token !== repeatable
+				&& !(await this.#framework().forms.recordChallenge(form, sha256Hex(token), CHALLENGE_LIMITS.maxAgeMs + CHALLENGE_LIMITS.maxSkewMs)))
 		if (refused) {
 			throw new HttpError(400, 'challenge_failed', 'The challenge did not verify; solve it again')
 		}

package/src/jobs/runner.ts

@@ -158,8 +158,12 @@ interface RunnerContext {
 	readonly membership: IamMembership | null
 	readonly capabilities: CapabilityAuthority
 	readonly containers: ReadonlyMap<string, readonly string[]>
+	readonly revealHandlerErrors: HandlerErrorSink | null
 }
 
+/** Where `fabrika app dev` shows what a handler threw, on the developer's own machine; nothing else sets one. */
+export type HandlerErrorSink = (where: string, error: unknown) => void
+
 export interface JobBindingInput {
 	readonly artifact: ContractArtifact
 	/** The handler tree `boot` binds; a job's handler is `handlers.jobs.<name>`. */
@@ -186,6 +190,8 @@ export interface JobBindingInput {
 	readonly capabilities: CapabilityAuthority
 	/** Each dimension's containers, nearest first: a link's chain. */
 	readonly containers: ReadonlyMap<string, readonly string[]>
+	/** What a job's handler threw, for `fabrika app dev`; without it the error is only its fixed code. */
+	readonly revealHandlerErrors?: HandlerErrorSink
 }
 
 interface BoundFrameworkJob {
@@ -278,6 +284,7 @@ export function bindJobs(input: JobBindingInput, problems: string[]): BoundJobs
 		membership: input.membership,
 		capabilities: input.capabilities,
 		containers: input.containers,
+		revealHandlerErrors: input.revealHandlerErrors ?? null,
 	})
 	const jobs: ContractJobs = Object.freeze({
 		names,
@@ -598,7 +605,11 @@ async function attemptOnce(
 	try {
 		const ran = runInRequest(frame, async () => {
 			await job.handler({ ctx })
-		}).then(() => null, failureOf)
+		}).then(() => null, (error: unknown) => {
+			const failed = failureOf(error)
+			if (failed.code === 'handler_failed') context.revealHandlerErrors?.(`job '${job.name}' attempt ${attempt}`, error)
+			return failed
+		})
 		const timeout = clock.wait(job.timeoutMs, timer.signal).then((): typeof TIMED_OUT => TIMED_OUT)
 		const result = await Promise.race([ran, timeout])
 		return result === TIMED_OUT ? failure('timeout') : result

package/src/react/hooks.ts

@@ -1,9 +1,10 @@
-// The data hooks over the typed client: `useQuery`, `useInfiniteQuery`, `useMutation`, `useAction` and
+// The data hooks over the typed client: `useQuery`, `useInfiniteQuery`, `useMutation`, `useAction`, `useDownload` and
 // `useInvalidate`. Each takes a client procedure (`api.deals.get`) as the typed name of the call; the answer comes back
 // through the procedure's own output schema, so its type is the contract's.
 
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
 import { z } from 'zod/v4'
+import type { AttachmentProcedure, DownloadInput } from '../client/contract'
 import type { Schema } from '../contract/define'
 import { type FabrikaError, toFabrikaError } from './errors'
 import { parentOf, prefixOf, useFabrika } from './provider'
@@ -42,6 +43,14 @@ function useLoad(entry: QueryEntry | PagesEntry | null): void {
 	}, [entry])
 }
 
+export interface QueryOptions {
+	/**
+	 * While a new input's answer loads, keep the previous input's answer as `success` data, with `fetching` true: an
+	 * offset list (`{ items, total }`) whose `limit` or `offset` changes keeps its rows on screen.
+	 */
+	readonly keepPrevious?: boolean
+}
+
 /**
  * The answer of a query, cached by procedure and input: every view of one call shares one request, and a mutation
  * that invalidates it refetches it. Pass `skip` as the input to wait for a value the input needs.
@@ -50,8 +59,16 @@ export function useQuery<O extends Schema>(
 	procedure: TypedProcedure<Record<never, never> | undefined, O>,
 	input?: typeof skip,
 ): QueryState<z.output<O>>
-export function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, input: I | typeof skip): QueryState<z.output<O>>
-export function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, input?: I | typeof skip): QueryState<z.output<O>> {
+export function useQuery<I, O extends Schema>(
+	procedure: TypedProcedure<I, O>,
+	input: I | typeof skip,
+	options?: QueryOptions,
+): QueryState<z.output<O>>
+export function useQuery<I, O extends Schema>(
+	procedure: TypedProcedure<I, O>,
+	input?: I | typeof skip,
+	options: QueryOptions = {},
+): QueryState<z.output<O>> {
 	const fabrika = useFabrika('useQuery')
 	const target = useMemo(() => fabrika.target(procedure, 'useQuery'), [fabrika, procedure])
 	if (target.node.procedure?.type === 'mutation') throw new Error(`useQuery: '${target.id}' is a mutation; use useMutation`)
@@ -63,7 +80,7 @@ export function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, i
 	const snapshot = useSyncExternalStore((listener) => source.subscribe(listener), () => source.snapshot, () => source.snapshot)
 	useLoad(entry)
 	const refetch = useCallback(() => entry?.load() ?? Promise.resolve(), [entry])
-	return useMemo((): QueryState<z.output<O>> => {
+	const state = useMemo((): QueryState<z.output<O>> => {
 		if (snapshot === null) return IDLE
 		const fetching = snapshot.fetching
 		if (snapshot.status === 'loading') return { status: 'loading', data: undefined, error: null, fetching, refetch }
@@ -75,6 +92,15 @@ export function useQuery<I, O extends Schema>(procedure: TypedProcedure<I, O>, i
 			? { status: 'loading', data: undefined, error: null, fetching, refetch }
 			: { status: 'success', data, error: null, fetching, refetch }
 	}, [snapshot, procedure, refetch])
+	const previous = useRef<z.output<O> | undefined>(undefined)
+	useEffect(() => {
+		if (state.status === 'success') previous.current = state.data
+	}, [state])
+	const kept = previous.current
+	if (options.keepPrevious === true && state.status === 'loading' && kept !== undefined) {
+		return { status: 'success', data: kept, error: null, fetching: true, refetch }
+	}
+	return state
 }
 
 export interface InfiniteQueryOptions {
@@ -136,6 +162,22 @@ export function useInfiniteQuery<I extends { readonly after?: string } | undefin
 	}, [snapshot, procedure, loadMore, refetch])
 }
 
+/** What `useDownload`'s `mutate` takes: the attachment procedure's input, or none. */
+export type DownloadArgument<I> = DownloadInput<I>[0]
+
+/**
+ * The download of an attachment procedure (`api.reports.export`) through the provider's client of its mount, so a test
+ * that hands the provider a client over the kit downloads over the kit. `mutate(input)` saves the file in a browser and
+ * answers it as `data`; a refusal is the state's `error`, as for `useMutation`. It refetches nothing.
+ */
+export function useDownload<I>(procedure: AttachmentProcedure<I>): MutationState<DownloadArgument<I>, File> {
+	const fabrika = useFabrika('useDownload')
+	const run = useMemo(() => fabrika.attachment(procedure, 'useDownload'), [fabrika, procedure])
+	return useRun(run, NOTHING_AFTER)
+}
+
+const NOTHING_AFTER = (): Promise<void> => Promise.resolve()
+
 export type MutationResult<T> = { readonly ok: true; readonly data: T } | { readonly ok: false; readonly error: FabrikaError }
 
 export interface MutationState<I, T> {

package/src/react/index.ts

@@ -3,14 +3,17 @@
 export { type Caller, callerOf, type CallerScope, Can, type CanProps, useCaller } from './caller'
 export { type FabrikaError, type FabrikaErrorKind, fieldError, toFabrikaError } from './errors'
 export {
+	type DownloadArgument,
 	type InfiniteQueryOptions,
 	type InfiniteQueryState,
 	type MutationOptions,
 	type MutationResult,
 	type MutationState,
+	type QueryOptions,
 	type QueryState,
 	skip,
 	useAction,
+	useDownload,
 	useInfiniteQuery,
 	useInvalidate,
 	useMutation,

package/src/react/provider.tsx

@@ -5,7 +5,7 @@
 import { createContext, type ReactNode, useContext, useState } from 'react'
 import { z } from 'zod/v4'
 import { type PageCaller, parsePageCaller } from '../client/caller'
-import { type ClientNode, clientNodeOf } from '../client/contract'
+import { attachmentAt, type ClientNode, clientNodeOf, downloadFile } from '../client/contract'
 import { RpcError, type RpcFetch } from '../client/transport'
 import { joinPath, PAGE_CALLER_FILE } from '../contract/defaults'
 import { type FabrikaError, toFabrikaError } from './errors'
@@ -59,6 +59,8 @@ export interface Fabrika {
 	readonly caller: CallerSource
 	/** The call of `procedure` on the provider's client of its mount. */
 	target(procedure: unknown, hook: string): ResolvedProcedure
+	/** The download of attachment `procedure` on the provider's client of its mount. */
+	attachment(procedure: unknown, hook: string): (input: unknown) => Promise<File>
 }
 
 export interface ResolvedProcedure extends StoreTarget {
@@ -108,15 +110,27 @@ function fabrika(clients: readonly object[], spa: string, fetch: RpcFetch): Fabr
 		if (byMount.has(node.mount)) throw new Error(`FabrikaProvider holds two clients of mount '${node.mount}'`)
 		byMount.set(node.mount, client)
 	}
+	const clientOf = (mount: string, hook: string): object => {
+		const client = byMount.get(mount)
+		if (client === undefined) throw new Error(`${hook}: the FabrikaProvider holds no client of mount '${mount}'`)
+		return client
+	}
 	return {
 		store: new QueryStore(toFabrikaError),
 		caller: new CallerSource(joinPath(spa, PAGE_CALLER_FILE), fetch),
+		attachment(procedure, hook) {
+			const at = attachmentAt(procedure)
+			if (at === null) throw new Error(`${hook} takes an attachment procedure of a client createClient made`)
+			const own = procedureAt(clientOf(at.mount, hook), at.path)
+			if (attachmentAt(own) === null || typeof own !== 'object' || own === null) {
+				throw new Error(`${hook}: '${at.mount}.${at.path}' is not an attachment procedure of the provider's client`)
+			}
+			return (input) => downloadFile(own, input)
+		},
 		target(procedure, hook) {
 			const node = clientNodeOf(procedure)
 			if (node?.procedure == null) throw new Error(`${hook} takes a procedure of a client createClient made`)
-			const client = byMount.get(node.mount)
-			if (client === undefined) throw new Error(`${hook}: the FabrikaProvider holds no client of mount '${node.mount}'`)
-			const call = procedureAt(client, node.path)
+			const call = procedureAt(clientOf(node.mount, hook), node.path)
 			if (typeof call !== 'function') throw new Error(`${hook}: '${idOf(node)}' is not a procedure of the provider's client`)
 			return {
 				id: idOf(node),

package/src/react/testing.ts

@@ -0,0 +1,144 @@
+// @fabrika/app/react/testing — what a screen test of an SPA needs: happy-dom's document over Bun's own web platform,
+// and typing that React reads. No test-runner dependency; happy-dom's registrator is an optional peer dependency.
+
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+import { act } from 'react'
+
+/**
+ * The classes and functions of Bun's web platform a screen test keeps: the client, the test kit, a form's challenge and
+ * a download run on them, and happy-dom's own differ (a happy-dom `File` of a Bun `Blob` holds `[object Blob]`).
+ */
+const BUN_GLOBALS = [
+	'fetch',
+	'Request',
+	'Response',
+	'Headers',
+	'AbortController',
+	'AbortSignal',
+	'URL',
+	'URLSearchParams',
+	'Blob',
+	'File',
+	'FormData',
+	'TextEncoder',
+	'TextDecoder',
+	'ReadableStream',
+] as const
+
+export interface InstalledDom {
+	/** Closes the window and removes its globals; call it from the test file's `afterAll`. */
+	uninstall(): Promise<void>
+}
+
+export interface DomOptions {
+	/** The page's address; `http://app.test/` by default. A router needs a real origin. */
+	readonly url?: string
+}
+
+/**
+ * Installs happy-dom's window as the globals, keeping Bun's fetch, abort, URL, blob, file and form classes, with
+ * navigation off: a download's link click leaves the page where it is, so a later test of the file still has it. Call
+ * it in a module the test file imports first: React reads `window` when it loads.
+ */
+export function installDom(options: DomOptions = {}): InstalledDom {
+	const kept = BUN_GLOBALS.map((name) => [name, Reflect.get(globalThis, name)] as const)
+	GlobalRegistrator.register({
+		url: options.url ?? 'http://app.test/',
+		settings: {
+			navigation: {
+				disableMainFrameNavigation: true,
+				disableChildFrameNavigation: true,
+				disableChildPageNavigation: true,
+				disableFallbackToSetURL: true,
+			},
+		},
+	})
+	for (const [name, value] of kept) Reflect.set(globalThis, name, value)
+	Reflect.set(globalThis, 'IS_REACT_ACT_ENVIRONMENT', true)
+	return {
+		async uninstall() {
+			// A request a screen started may still settle: let it, before its window goes.
+			await new Promise((resolve) => setTimeout(resolve, 50))
+			await GlobalRegistrator.unregister()
+		},
+	}
+}
+
+type Control = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+
+/**
+ * The text a label gives its control: what is hidden from assistive technology (a required marker) left out, and so
+ * is a control the label wraps.
+ */
+function readText(element: Element): string {
+	const copy = element.cloneNode(true)
+	if (copy instanceof Element) {
+		for (const left of copy.querySelectorAll('[aria-hidden="true"], input, textarea, select')) left.remove()
+	}
+	return (copy.textContent ?? '').replace(/\s+/g, ' ').trim()
+}
+
+/** A control's accessible name: its `aria-label`, the elements `aria-labelledby` names, or its `<label>`. */
+function nameOf(control: Control): string {
+	const aria = control.getAttribute('aria-label')
+	if (aria !== null) return aria.trim()
+	const labelledBy = control.getAttribute('aria-labelledby')
+	if (labelledBy !== null) {
+		return labelledBy.split(/\s+/).map((id) => {
+			const label = control.ownerDocument.getElementById(id)
+			return label === null ? '' : readText(label)
+		}).join(' ').trim()
+	}
+	const labels = control.labels === null ? [] : [...control.labels]
+	return labels.map(readText).join(' ').trim()
+}
+
+const isControl = (element: Element): element is Control =>
+	element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement
+
+/** The one input, textarea or select whose accessible name is `label`; throws when there is none or more than one. */
+export function controlByLabel(label: string, within: ParentNode = document.body): Control {
+	const found = [...within.querySelectorAll('input, textarea, select')].filter(isControl).filter((control) => nameOf(control) === label)
+	const [control] = found
+	if (control === undefined || found.length > 1) {
+		throw new Error(`${found.length === 0 ? 'no' : found.length} control${found.length > 1 ? 's' : ''} labelled '${label}'`)
+	}
+	return control
+}
+
+/** The prototype whose `value` setter React's own value tracking does not see, so the next event reads as a change. */
+function valueSetter(control: Control): ((value: string) => void) | undefined {
+	const prototype = control instanceof HTMLTextAreaElement
+		? HTMLTextAreaElement.prototype
+		: control instanceof HTMLSelectElement
+		? HTMLSelectElement.prototype
+		: HTMLInputElement.prototype
+	return Object.getOwnPropertyDescriptor(prototype, 'value')?.set
+}
+
+/**
+ * Types `value` into the control labelled `label`, as React reads a person typing: it focuses the control, sets the
+ * value past React's tracking, and sends `input`, `change` and `keyup`. A select takes the option's value.
+ */
+export async function type(label: string, value: string, within?: ParentNode): Promise<void> {
+	const control = controlByLabel(label, within)
+	await act(async () => {
+		control.focus()
+		valueSetter(control)?.call(control, value)
+		control.dispatchEvent(new Event('input', { bubbles: true }))
+		control.dispatchEvent(new Event('change', { bubbles: true }))
+		control.dispatchEvent(new KeyboardEvent('keyup', { bubbles: true }))
+	})
+}
+
+/** Waits, letting React render, until the text of `within` holds `text`; throws after `timeoutMs` (2 s by default). */
+export async function waitForText(text: string, options: { readonly within?: Element; readonly timeoutMs?: number } = {}): Promise<void> {
+	const within = options.within ?? document.body
+	const deadline = Date.now() + (options.timeoutMs ?? 2000)
+	while (!(within.textContent ?? '').includes(text)) {
+		if (Date.now() > deadline) throw new Error(`the page did not show '${text}' in time`)
+		await act(async () => {
+			await new Promise((resolve) => setTimeout(resolve, 10))
+		})
+	}
+}

package/src/testing/challenge.ts

@@ -0,0 +1,10 @@
+// A stand-in for a form challenge's provider, for a test kit and for `fabrika app dev`.
+
+import type { ChallengeFetch } from '../implement/challenge'
+
+/** The token Turnstile's always-passing test widget (site key `1x00000000000000000000AA`) hands out every time. */
+export const TURNSTILE_TEST_TOKEN = 'XXXX.DUMMY.TOKEN.XXXX'
+
+/** Turnstile's siteverify that passes every token: a fresh answer for the host and the form the check expects. */
+export const passingChallenge: ChallengeFetch = (_request, check) =>
+	Promise.resolve(Response.json({ success: true, challenge_ts: new Date().toISOString(), hostname: check.hostname, action: check.action }))

package/src/testing/dev.ts

@@ -3,6 +3,7 @@
 import type { AnyContract, DimensionOf } from '../contract/define'
 import type { ContractImplementation } from '../implement/implement'
 import type { PersonTestCaller, TestCaller } from './caller'
+import { passingChallenge, TURNSTILE_TEST_TOKEN } from './challenge'
 import { bootTestKit, type TestKit, type TestKitOptions } from './kit'
 import type { SentInvitation, TestMembership } from './membership'
 
@@ -37,11 +38,30 @@ export interface DevSeedResult<C extends AnyContract> {
 	readonly scopes?: { readonly [D in DimensionOf<C>]?: readonly DevScopeValue[] }
 }
 
+/** The origin `fabrika app dev` captures every request to: an outside provider's stand-in, named by its path. */
+export const DEV_OUTBOX_ORIGIN = 'https://outbox.invalid'
+
+/** A request the application sent to `DEV_OUTBOX_ORIGIN` under `fabrika app dev`: its body, never its headers. */
+export interface DevOutboxMessage {
+	readonly id: number
+	readonly method: string
+	/** The path it was sent to: `/mail`. */
+	readonly path: string
+	readonly contentType: string | null
+	readonly body: string
+}
+
+/** What `fabrika app dev` stands in for outside the application, for the seed to read. */
+export interface DevOutside {
+	/** Every request sent to `DEV_OUTBOX_ORIGIN` so far, oldest first. */
+	outbox(): readonly DevOutboxMessage[]
+}
+
 /**
  * The default export of `dev/seed.ts`: it receives the application's test kit, the API its tests use, writes through the
- * endpoints, and answers who and what the picker offers.
+ * endpoints, and answers who and what the picker offers. `outside` reads what the application sent to the dev outbox.
  */
-export type DevSeed<C extends AnyContract> = (dev: TestKit<C>) => Promise<DevSeedResult<C>> | DevSeedResult<C>
+export type DevSeed<C extends AnyContract> = (dev: TestKit<C>, outside: DevOutside) => Promise<DevSeedResult<C>> | DevSeedResult<C>
 
 export interface DevKit<C extends AnyContract> {
 	readonly kit: TestKit<C>
@@ -55,9 +75,15 @@ export interface DevKit<C extends AnyContract> {
 
 const isPerson = (caller: TestCaller): caller is PersonTestCaller => caller.kind === 'human' && caller.email !== null
 
-/** The test kit of `app` with its stand-in IAM, and what `fabrika app dev` shows of it. */
+/**
+ * The test kit of `app` with its stand-in IAM, and what `fabrika app dev` shows of it. A form's challenge passes
+ * (`passingChallenge`) unless `options.challengeFetch` answers it, and admits the test widget's token
+ * (`TURNSTILE_TEST_TOKEN`) at every submission; any other token is single use, as deployed.
+ */
 export function devKit<C extends AnyContract>(app: ContractImplementation<C>, options: Omit<TestKitOptions, 'membership'> = {}): DevKit<C> {
-	const { kit, standIn, callerOf } = bootTestKit(app, options)
+	const { kit, standIn, callerOf } = bootTestKit(app, { challengeFetch: passingChallenge, ...options }, {
+		repeatableChallengeToken: TURNSTILE_TEST_TOKEN,
+	})
 	if (standIn === null) {
 		throw new Error('a kit without its own membership transport stands in for IAM')
 	}

package/src/testing/endpoint-access.ts

@@ -227,16 +227,19 @@ const cleanScanner: FileScanner = {
 }
 
 /**
- * The variables `boot` requires of `app` that a generated case never uses: each form challenge's secret, since no case
- * submits a form. The kit's challenge stand-in refuses every token, so no verification leaves the process.
+ * The variables `boot` requires of `app` that a generated case never uses: each form challenge's secret and site key,
+ * since no case submits a form, and each SPA mount's `public` variables, since no case reads a page's config. The
+ * kit's challenge stand-in refuses every token, so no verification leaves the process.
  */
 function unusedVariables(app: ContractImplementation<AnyContract>): ApplicationEnvironment {
 	const artifact = compileContract(app.contract, app.database?.tables ?? {})
-	return Object.fromEntries(
-		Object.values(artifact.mounts).flatMap((
-			mount,
-		) => (mount.kind === 'form' && mount.challenge !== undefined ? [[mount.challenge.secret, 'unused']] : [])),
-	)
+	const names = Object.values(artifact.mounts).flatMap((mount): readonly string[] => {
+		if (mount.kind === 'form' && mount.challenge !== undefined) {
+			return mount.challenge.siteKey === undefined ? [mount.challenge.secret] : [mount.challenge.secret, mount.challenge.siteKey]
+		}
+		return mount.kind === 'spa' ? (mount.public ?? []) : []
+	})
+	return Object.fromEntries(names.map((name) => [name, 'unused']))
 }
 
 /**

package/src/testing/index.ts

@@ -6,6 +6,7 @@ refuseInProduction('@fabrika/app/testing')
 export type { IamMembershipRpc } from '@fabrika/auth-core'
 export type { FileScanner } from '../files/scan'
 export type { ChallengeFetch } from '../implement/challenge'
+export type { HandlerErrorSink } from '../jobs/runner'
 export type {
 	LabelledTestCaller,
 	LinkTestCaller,
@@ -17,7 +18,19 @@ export type {
 	TestLink,
 	TestScope,
 } from './caller'
-export { type DevKit, devKit, type DevLink, type DevPersona, type DevScopeValue, type DevSeed, type DevSeedResult } from './dev'
+export { passingChallenge } from './challenge'
+export {
+	DEV_OUTBOX_ORIGIN,
+	type DevKit,
+	devKit,
+	type DevLink,
+	type DevOutboxMessage,
+	type DevOutside,
+	type DevPersona,
+	type DevScopeValue,
+	type DevSeed,
+	type DevSeedResult,
+} from './dev'
 export { type JobName, TEST_ENVIRONMENT, TEST_ISSUER, type TestConnection, type TestKit, testKit, type TestKitOptions } from './kit'
 export type { SentInvitation, TestMembership } from './membership'
 export { statusOf } from './status'