@warlock.js/core 5.34.2 → 5.35.0

package/package.json

@@ -25,12 +25,12 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^3.0.0",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.34.2",
-    "@warlock.js/cascade": "5.34.2",
-    "@warlock.js/context": "5.34.2",
-    "@warlock.js/fs": "5.34.2",
-    "@warlock.js/logger": "5.34.2",
-    "@warlock.js/seal": "5.34.2",
+    "@warlock.js/cache": "5.35.0",
+    "@warlock.js/cascade": "5.35.0",
+    "@warlock.js/context": "5.35.0",
+    "@warlock.js/fs": "5.35.0",
+    "@warlock.js/logger": "5.35.0",
+    "@warlock.js/seal": "5.35.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
@@ -46,7 +46,8 @@
     "mime": "^4.1.0",
     "oxc-parser": "0.154.0",
     "pluralize-esm": "^9.0.5",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "axe-core": "4.14.0"
   },
   "peerDependencies": {
     "@napi-rs/keyring": "^2.1.1",
@@ -55,12 +56,12 @@
     "@aws-sdk/lib-storage": "^3.955.0",
     "@aws-sdk/s3-request-presigner": "^3.955.0",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/access": "5.34.2",
-    "@warlock.js/ai": "5.34.2",
-    "@warlock.js/ai-tools": "5.34.2",
-    "@warlock.js/devtools": "5.34.2",
-    "@warlock.js/herald": "5.34.2",
-    "@warlock.js/notifications": "5.34.2",
+    "@warlock.js/access": "5.35.0",
+    "@warlock.js/ai": "5.35.0",
+    "@warlock.js/ai-tools": "5.35.0",
+    "@warlock.js/devtools": "5.35.0",
+    "@warlock.js/herald": "5.35.0",
+    "@warlock.js/notifications": "5.35.0",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -145,7 +146,7 @@
   "engines": {
     "node": ">=22.15"
   },
-  "version": "5.34.2",
+  "version": "5.35.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/schemas/inspect-report.schema.json

@@ -47,7 +47,8 @@
           "pages",
           "jobs",
           "schedules",
-          "packages"
+          "packages",
+          "files"
         ]
       }
     },
@@ -549,6 +550,51 @@
           }
         }
       }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "module", "role", "exports", "imports", "importedBy"],
+        "properties": {
+          "file": {
+            "type": "string"
+          },
+          "module": {
+            "type": "string"
+          },
+          "role": {
+            "type": "string"
+          },
+          "exports": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "importedBy": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "imports": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["specifier", "file"],
+              "properties": {
+                "specifier": {
+                  "type": "string"
+                },
+                "file": {
+                  "type": ["string", "null"]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

package/skills/build-budgets/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: build-budgets
+description: "Configure build.budgets in warlock.config.ts, inspect per-page gzip JS/CSS and deferred assets, compare the last build, and enforce limits with warlock build --json. Use for client bundle size regressions and CI transfer-size gates. For field metrics use web measure-web-vitals."
+---
+
+# Client build budgets
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  build: {
+    budgets: {
+      page: { js: "150kb", css: "50kb" },
+      pages: { "/admin/**": { js: "220kb" } },
+      mode: "error",
+    },
+  },
+});
+```
+
+Run `npx warlock build` for the sorted table, or `npx warlock build --json`
+for `{ success, budgets, error? }`. Progress goes to stderr in JSON mode.
+`budgets` contains `version: 1`, `compression: "gzip"`, `pages` and
+`violations`. API-only builds report an empty page list.
+
+Page limits cover the hydration entry, page, layouts, root, setup registrations
+and error boundary, plus their transitive static imports. Files are counted once
+per page and gzipped individually. Dynamic imports beyond those required roots
+are reported separately and do not consume the budget. Shared files count in
+each page's first visit. This measures emitted JS/CSS, not HTML, fonts or images.
+
+`pages` keys match route paths with `*` (within a segment), `**` (across
+segments), or `?` (one non-slash character). Defaults apply first; matching rules
+merge in insertion order and the last supplied field wins. Unsupported glob
+syntax fails with an actionable error. Units are case-insensitive `b`, `kb` and
+`mb`, with 1024 bytes per kb; equality passes. Omitted fields are unlimited.
+
+Existing apps without budgets receive a report only. Configured budgets default
+to `mode: "error"`; `"warn"` logs violations and completes. New project templates
+configure 150kb JS / 50kb CSS. A failure names the page, limit, actual size and
+the ten largest rendered modules. Those module sizes are Rollup attribution
+estimates in uncompressed rendered bytes, not gzip shares; compression is not
+additive across modules inside a file.
+
+The successful build stores `build-budgets.json` in `build.outdir` (normally
+`dist`). Preserve that directory before rebuilding to obtain deltas. A failed
+build rolls back to the previous artifact and baseline. JSON output still
+contains its attempted report. Changing output directories or deleting dist
+starts a fresh baseline; new routes display no delta. Vite's private
+`client/.vite/budget-modules.json` contains the full module attribution.

package/skills/build-restful/SKILL.md

@@ -266,3 +266,59 @@ router.restfulResource("/orders", new OrdersRestful());
 - The `create-controller` topic — what the chain's handlers look like.
 - The `define-resource` topic — wire shape for the records the chain returns.
 - The `warlock-conventions` topic — controller/service/repository layering rules.
+
+## Bounded list endpoints
+
+Use `listEndpoint(request, listCallback, options)` from `@warlock.js/core` to
+produce `{ <pluralKey>: data, pagination }` from a page-based repository list.
+The callback receives repository options, with sorting translated into the
+repository's `[column, direction]` tuple. Wrap repository methods in an arrow
+to preserve their receiver. Both `list` and `listCached` work.
+
+```ts
+import { listEndpoint, type Request, type RequestHandler } from "@warlock.js/core";
+import { v, type Infer } from "@warlock.js/seal";
+import { productsRepository } from "../repositories/products.repository";
+
+const querySchema = v.object({
+  page: v.int().min(1).default(1),
+  limit: v.int().min(1).default(20),
+  orderBy: v.literal("createdAt", "name").optional(),
+  orderDir: v.literal("asc", "desc").optional(),
+  status: v.literal("active", "archived").optional(),
+});
+type Query = Infer<typeof querySchema>;
+
+export const listProducts: RequestHandler<Request<Query>> = async ({ request, response }) =>
+  response.success(
+    await listEndpoint(request, (options) => productsRepository.listCached(options), {
+      pluralKey: "products",
+      maxLimit: 100,
+      orderBy: ["createdAt", "name"],
+      filters: ["status"],
+    }),
+  );
+
+listProducts.validation = { schema: querySchema, validating: ["query"] };
+// Attach responseSchema with your ProductResource and pagination fields too.
+```
+
+`request.validated()` must already contain schema-validated query values. Seal
+handles coercion and filter validation; the helper does not read raw query or
+body values. Configure the repository's `filterBy` for the chosen filter fields.
+Only explicitly listed `filters` are forwarded; pagination and sort controls
+cannot be declared as filters in the typed API. Filters remain flat repository
+options, rather than a nested `filters` object.
+
+Defaults are page 1, limit 20, maxLimit 100. The helper clamps a positive integer
+limit to maxLimit (use `.max(100)` in the query schema instead if you prefer a
+422 for excessive requests). Invalid page/limit or unlisted sort columns throw
+`AppError("invalidListQuery", 422, ...)`. Sort directions are restricted to
+`asc`/`desc`, defaulting to `asc` when a column is provided. With no column,
+repository default ordering applies. Invalid helper configuration throws a
+`TypeError`. The plural key must be nonempty and cannot be `pagination`.
+
+The helper forces page pagination and preserves the repository's pagination
+metadata without recalculating it. Cursor and unpaginated endpoints need their
+own controller. Add authorization constraints inside the callback using trusted
+server values; never accept them as client filters.

package/skills/configure-app/SKILL.md

@@ -421,3 +421,37 @@ export default {
 Keep the domain error class in an app module imported by both the service and
 this config. Return `undefined` for errors you do not recognize; a mapped 5xx
 is opaque unless the mapper explicitly chooses a public message.
+
+## Format every JSON error response
+
+`http.errorMapper` classifies thrown non-`HttpError` errors as `{ status, message?, payload? }`. It does not see existing `HttpError` subclasses, returned validation errors, helper responses, unmatched routes, or global rate-limit failures.
+
+Use `http.errorResponse` when the application needs one JSON error envelope across those paths:
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  errorMapper: () => ({ status: 500 }),
+  errorResponse({ status, requestId }) {
+    return {
+      error: {
+        code: status >= 500 ? "serverError" : `http${status}`,
+        message: status >= 500 ? "Internal server error." : "Request failed.",
+      },
+      requestId,
+    };
+  },
+} satisfies HttpConfigurations;
+```
+
+The synchronous formatter receives `HttpErrorResponseContext`: `{ status: number, body: unknown, requestId: string }`. Narrow `body` before reading fields; it is the parsed, serialized JSON body. Return a JSON-serializable object or `undefined` to keep the original. The formatter changes only the body, preserving the HTTP status and headers except for recalculated content length, a `private, no-store` cache policy, and the correlation header. If it throws or cannot serialize its result, core logs the formatter error and retains the original body.
+
+The hook covers status 400–599 with `application/json` or an `application/*+json` content type, including Fastify parsing errors, unmatched-route 404s, validation 422s, rate-limit 429s, and 500s. Warlock responses use the ID already stamped from `request.id`. Before Warlock creates a Request, the formatter receives Fastify's `request.id` and echoes that same value under `http.requestId.header` (default `X-Request-Id`). Setting `http.requestId.enabled: false` suppresses that header; without a stamped Warlock ID, the formatter falls back to Fastify's request ID even for routed responses. Keep request-ID headers enabled when the body must correlate with Warlock request logs. HTML pages, files, raw text, streams, and errors after headers have been sent are not reformatted. With no formatter configured, existing response shapes are unchanged.
+
+## Co-located configuration tests
+
+`src/config/mail.spec.ts` and `src/config/mail.test.tsx` are never imported as
+configuration. Discovery and reload also exclude `test`, `tests`, `__tests__`,
+`__mocks__`, `__fixtures__`, and `fixtures` directories at any depth. A real
+`src/config/tests.ts` remains ordinary configuration.

package/skills/create-module/SKILL.md

@@ -195,3 +195,12 @@ Generated web starter files match the scaffold’s Oxfmt configuration and its
 built-in import sorting.
 After editing generated code, run `npm run format` and `npm run lint:check`.
 Formatting retains unused imports; the linter reports them.
+
+## Notification translation defaults
+
+After configuring `app.localeCodes`, run `npx warlock add notifications`.
+New notification dictionaries include `notFound` as a string in every configured
+locale. English ("Notification not found") is the explicit fallback for each
+locale without a bundled translation, including locale sets without English.
+Replace fallback text with your translations before publishing. Existing module
+files and existing translation keys are preserved.

package/skills/generate-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-openapi
-description: 'Generate an OpenAPI 3.1 document from the registered routes with `warlock generate.openapi` (default `storage/openapi/openapi.json`), write a Postman collection from it with `warlock generate.postman` (default `storage/postman/collection.json`), and read it live in the dev-only API docs page at `/__warlock/docs`. Documents paths, path/query parameters, request bodies from Seal validation, responses from `handler.responseSchema`, 401/422 and bearer/cookie security from `authMiddleware()`. Triggers: `generate.openapi`, `openApiGeneratorCommand`, `buildOpenApiDocument`, `getDevelopmentOpenApiDocument`, `generate.postman`, `openApiToPostmanCollection`, `getDevelopmentPostmanCollection`, `responseSchema`, `--include-pages`, `/__warlock/docs`; "OpenAPI", "Swagger", "API docs", "import my API into Postman or Insomnia", "document my routes". Skip: declaring response types on a handler — the `create-controller` topic; the devtools dashboard — the `devtools-overview` topic of the `warlock-js-devtools` skill; listing routes — the `warlock-routes` topic.'
+description: 'Generate an OpenAPI 3.1 document from the registered routes with `warlock generate.openapi` (default `storage/openapi/openapi.json`), write a Postman collection from it with `warlock generate.postman` (default `storage/postman/collection.json`), and read it live in the dev-only API docs page at `/__warlock/docs`. Documents paths, path/query parameters, request bodies from Seal validation, responses from `handler.responseSchema`, 401/422 and bearer/cookie security from `authMiddleware()`. Triggers: `generate.openapi`, `openApiGeneratorCommand`, `buildOpenApiDocument`, `getDevelopmentOpenApiDocument`, `generate.postman`, `openApiToPostmanCollection`, `getDevelopmentPostmanCollection`, `responseSchema`, `--include-pages`, `/__warlock/docs`; "OpenAPI", "Swagger", "API docs", "import my API into Postman or Insomnia", "document my routes". Skip: declaring response types on a handler — the `create-controller` topic; the devtools dashboard — the `warlock-js-devtools` skill; listing routes — the `warlock-routes` topic.'
 ---
 
 # Warlock — generate an OpenAPI document

package/skills/generate-web-ui/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: generate-web-ui
+description: "Generate web pages, schema-backed forms and CRUD UI with warlock generate page, form and crud-ui. Includes setup companions, design-system controls, useSubmitForm, optional guarded endpoints and module CRUD prerequisites."
+---
+
+# Generate web UI
+
+Run these commands from an app with `@warlock.js/web` installed and the app's
+design system in `src/web/design-system/components/`. Controls are default
+exports, imported individually through `web/design-system/components/<name>`;
+they implement Mongez `useFormControl` and accept `name`, `label`, `hint` and
+`error`. Forms import `Form` directly from `@mongez/react-form`.
+
+```sh
+npx warlock generate page account/settings
+npx warlock generate page dashboard --interactive
+npx warlock generate form contact
+npx warlock generate form feedback --module posts --endpoint
+npx warlock generate crud-ui posts --dry-run --json
+npx warlock generate crud-ui posts
+```
+
+`page account/settings` creates `src/web/account/settings.page.tsx` and
+`settings.setup.ts`, with `/account/settings`, a named route, a loader and
+`config.metadata`. `--interactive` also creates a counter feature hook under
+`hooks/`; replace that example with the feature's behavior. Executable page
+exports belong in `.setup.ts`, UI in `.page.tsx`, state and effects in hooks.
+
+`form contact` creates `src/web/forms/contact-form.tsx`, a props file, a
+`use-contact-form` hook using `useSubmitForm`, and
+`src/shared/schema/contact.schema.ts`. The starter schema has one `name`
+string field; edit that shared schema and the controls together. Its default
+submit target is `/contact`; supply a real endpoint or set the form's `path`.
+With `--module posts`, output lives under `src/web/posts/`, the shared schema
+under `src/shared/schema/posts/`, and the target is `/posts/contact`.
+The module must exist. `--endpoint` requires `--module`, adds a controller
+with `validation` and `responseSchema`, and appends a guarded POST route.
+This initial endpoint validates and echoes the input; replace that body with a
+service call to persist it. It does not create database persistence for you.
+
+For CRUD UI, first generate a full module with
+`npx warlock generate module posts`. Define its create/update schemas and
+list query schema, then run `npx warlock generate crud-ui posts`.
+The generator loads the real Seal schemas using the app loader, so their
+imports must resolve. These schema modules must be safe to import on both
+client and server. Plain string fields map to TextInput, password names to
+PasswordInput, email/date/time/date-time formats to the corresponding controls,
+and booleans to CheckboxInput. Unions, nullable fields, enums, numeric fields,
+nested objects and arrays require custom control decisions and are rejected
+before writing output. An empty module schema produces an empty form.
+
+CRUD output contains list/create/edit pages and setup companions, separate
+create/update forms, their hooks and props, list/edit/delete hooks, and a
+delete action component. Lists use the existing GET endpoint and its
+`data`/`pagination` contract (`page` and `pages`). Literal fields in
+`listPostsQuerySchema` become filter inputs; `page` is controlled by navigation
+and `limit` remains the endpoint default. Edit reads GET `/posts/:id`, create
+submits POST `/posts`, update uses PUT `/posts/:id`, and delete uses DELETE
+`/posts/:id`. Successful deletion refreshes the list. Mutation forms show
+validation errors, pending state and success feedback.
+
+CRUD generation accepts the conventional full module route file, allowing
+formatting and comments. It fails closed for custom routes/guards instead of
+inferring authorization. Pages require `requireUser({ userType: "user" })`,
+matching the starter's `guarded` helper. Configure `web.session` with the auth
+page-session resolver before visiting these pages. Endpoint guards still
+run on every API request; customized authorization requires a hand-written UI.
+
+All three commands support `--dry-run --json` through the normal generation
+report. Existing generated files are skipped unless `--force` is explicit.
+Route registration is idempotent and retains existing module content.

package/skills/index.md

@@ -1,5 +1,5 @@
 ---
-description: "The Warlock server framework: HTTP routes, controllers, responses, resources, repositories, CLI, mail, storage, security helpers. Exports `router`, `Request`, `Response`, `RequestHandler`, `useCase`, `RepositoryManager`, `defineResource`, `defineConfig`, `storage`, `sendMail`, `hashPassword`, `command`. Use for: add a route, write a controller, return a JSON response, hide a field from the response, upload a file, send an email, hash a password, add a CLI command, generate an OpenAPI document, type an API response, wire a socket, run or configure the app. Not this package: database models/queries → @warlock.js/cascade; input schemas → @warlock.js/seal; SSR pages → @warlock.js/web."
+description: 'Warlock application runtime: `router`, `Request`, `Response`, `config`, `env`, `sendMail` and `defineConfig`. Use for "add an API route", controllers, middleware, CLI commands, config, uploads, mail, sockets, OpenAPI, testing or upgrades. Not this package → @warlock.js/web for React SSR pages; @warlock.js/cascade for database queries; @warlock.js/seal for standalone schemas; @warlock.js/auth for login.'
 ---
 
 # @warlock.js/core
@@ -18,11 +18,11 @@ When the framework is wrong or missing a capability, follow the `report-framewor
 
 ## Topics by area
 
-- **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators, upgrade-from-5-29
+- **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, build-budgets, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators, upgrade-from-5-29
 - **HTTP & routing:** register-route, warlock-routes, create-controller, use-middleware, write-middleware, validate-input, use-request-locals, build-restful, wire-socket
 - **Responses & resources:** send-response, define-resource, use-model-transformers, use-localization
 - **Domain layers:** write-use-case, use-repository, write-seeder
-- **CLI & running the app:** run-app, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
+- **CLI & running the app:** generate-web-ui, run-app, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
 - **Agent tooling:** warlock-mcp, warlock-trace, warlock-agents-md, warlock-board
 - **Storage, files & mail:** store-file, upload-file, process-image, send-mail
 - **Security & utilities:** hash-password, encrypt-data, store-secrets, retry-operation, benchmark-code, request-memo, request-tracing

package/skills/run-app/SKILL.md

@@ -182,7 +182,7 @@ Omit switches to run TypeScript and installed/configured Oxlint. Set `oxlint: fa
 
 ## `warlock build` — production bundle
 
-esbuild bundle of the app down to a single JS file in `dist/`. No flags — every setting comes from `warlock.config.ts > build`.
+esbuild bundle of the app down to a single JS file in `dist/`. `--json` prints the client budget report; build settings come from `warlock.config.ts > build`. See the `build-budgets` topic for per-page gzip limits and deltas.
 
 ### `build.*` config knobs
 

package/skills/send-mail/SKILL.md

@@ -400,3 +400,28 @@ await Mail.to(user.email)
 
 - The `configure-app` topic — `src/config/mail.ts` shape and `env()` patterns.
 - The `warlock-conventions` topic — where mail-sending services live.
+
+## Preview development mail in devtools
+
+Run `npx warlock add devtools`, start development, and open `/__warlock` (or your
+configured devtools path). In the mail panel, select a captured message to read
+its recipients, subject, text, and sandboxed HTML preview. Send while the panel's
+collector is attached; captures are held in memory and disappear on restart.
+
+Use development mail mode so previews do not deliver real email:
+
+```ts
+import { setMailMode, sendMail } from "@warlock.js/core";
+
+setMailMode("development");
+await sendMail({
+  to: "reader@example.com",
+  subject: "Preview",
+  html: "<p>Your code is 123456</p>",
+});
+```
+
+Development sends emit `mailEvents.onCaptured`, which devtools consumes; console
+logs show metadata rather than sensitive bodies. Devtools is mounted only for
+the development runtime and is not mounted in production. Keep production mail
+mode configured for actual delivery. Test-mode assertions use the test mailbox.

package/skills/send-response/SKILL.md

@@ -481,3 +481,80 @@ export function requireProduct<T>(product: T | null | undefined): T {
   return product;
 }
 ```
+
+## Format every JSON error response
+
+`http.errorMapper` classifies thrown non-`HttpError` errors as `{ status, message?, payload? }`. It does not see existing `HttpError` subclasses, returned validation errors, helper responses, unmatched routes, or global rate-limit failures.
+
+Use `http.errorResponse` when the application needs one JSON error envelope across those paths:
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  errorMapper: () => ({ status: 500 }),
+  errorResponse({ status, requestId }) {
+    return {
+      error: {
+        code: status >= 500 ? "serverError" : `http${status}`,
+        message: status >= 500 ? "Internal server error." : "Request failed.",
+      },
+      requestId,
+    };
+  },
+} satisfies HttpConfigurations;
+```
+
+The synchronous formatter receives `HttpErrorResponseContext`: `{ status: number, body: unknown, requestId: string }`. Narrow `body` before reading fields; it is the parsed, serialized JSON body. Return a JSON-serializable object or `undefined` to keep the original. The formatter changes only the body, preserving the HTTP status and headers except for recalculated content length, a `private, no-store` cache policy, and the correlation header. If it throws or cannot serialize its result, core logs the formatter error and retains the original body.
+
+The hook covers status 400–599 with `application/json` or an `application/*+json` content type, including Fastify parsing errors, unmatched-route 404s, validation 422s, rate-limit 429s, and 500s. Warlock responses use the ID already stamped from `request.id`. Before Warlock creates a Request, the formatter receives Fastify's `request.id` and echoes that same value under `http.requestId.header` (default `X-Request-Id`). Setting `http.requestId.enabled: false` suppresses that header; without a stamped Warlock ID, the formatter falls back to Fastify's request ID even for routed responses. Keep request-ID headers enabled when the body must correlate with Warlock request logs. HTML pages, files, raw text, streams, and errors after headers have been sent are not reformatted. With no formatter configured, existing response shapes are unchanged.
+
+## Typed domain failures
+
+`AppError<Details, Code>` is available from `@warlock.js/core` and the lightweight
+`@warlock.js/core/errors` entry. Its constructor is
+`new AppError(code, status, publicMessage, details?)`. Status must be an integer
+from 400 to 599. The message and details are explicitly public, including for
+5xx errors: never put diagnostics, credentials or private records there.
+
+```ts
+import { AppError } from "@warlock.js/core/errors";
+
+throw new AppError("quotaExceeded", 429, "Try again later.", { retryAfter: 30 });
+```
+
+The default response is
+`{ error: { code: "quotaExceeded", message: "Try again later.", details: { retryAfter: 30 } } }`.
+Absent details are omitted; `false`, `0` and `null` details are preserved. Errors
+retain the private, no-store cache policy, and server failures are logged.
+
+`AppError` and `HttpError` are separate `Error` subclasses. Existing `HttpError`
+constructors, inheritance, `payload` and legacy `{ error: message, payload? }`
+bodies remain unchanged. Both bypass `http.errorMapper`; ordinary errors retain
+the existing opaque 500 fallback. Choose `AppError` for new domain failures
+that need stable codes, and keep existing HTTP error subclasses as they are.
+
+`http.errorResponse` receives an optional typed `appError` alongside `body`,
+`status` and `requestId`. No per-error mapper is needed:
+
+```ts
+import type { HttpErrorResponseFormatter } from "@warlock.js/core";
+
+const errorResponse: HttpErrorResponseFormatter = ({ appError, requestId }) => {
+  if (!appError) return undefined; // keep other JSON errors unchanged
+  return {
+    error: {
+      code: appError.code,
+      message: appError.publicMessage,
+      ...(appError.details === undefined ? {} : { details: appError.details }),
+    },
+    requestId,
+  };
+};
+// Set this function as http.errorResponse in your HTTP configuration.
+```
+
+The formatter sees the original instance only for thrown `AppError`s handled
+by the request lifecycle. Early Fastify rejections and returned helper responses
+have no `appError`; use `body` and `status` for those cases. Do not spread an
+error instance into the response.

package/skills/test-browser/SKILL.md

@@ -103,6 +103,7 @@ port-file handshake above when the app supports binding `0` itself.
   document. Selector helpers do not enter frames or closed shadow roots.
 
 Use `--browser /path/to/chrome` or `WARLOCK_E2E_BROWSER` if discovery fails.
+Set `browser.startupTimeoutMs` (default 30 seconds) when the browser is slow to start, for example on shared CI runners.
 `browser: { args: ["--no-sandbox"] }` is an explicit option for controlled root
 containers; it is not a default. On Windows, command arrays should invoke JS tools
 through `process.execPath`, avoiding `.cmd` executables that require a shell.
@@ -117,3 +118,56 @@ Cleanup verifies the unique supervisor command line before stopping only its
 recorded process group (Windows: verified PID tree). It retains disposable files
 if ownership verification fails and reports the failure in evidence. Do not add
 process-name or port-based kills to a spec.
+
+## Accessibility checks
+
+Call `await page.assertAccessible()` after the content is visible and again after
+opening menus, dialogs or validation feedback. The harness reads its pinned local
+axe-core distribution and injects it with CDP `Runtime.evaluate`; it never fetches
+a CDN script or adds axe to the app bundle. A missing dependency, injection error,
+unmatched selector or scan exception fails the step.
+
+```ts
+await page.assertAccessible();
+await page.assertAccessible({
+  selector: "main",
+  tags: ["wcag2a", "wcag2aa", "wcag21aa"],
+  allow: [{ id: "color-contrast", selector: ".legacy-caption" }],
+  timeoutMs: 30_000,
+});
+```
+
+Defaults run all enabled axe rules on the document. `tags` uses axe's `runOnly`
+tag filter; `selector` limits the scanned region. Allowances match exact rule IDs
+and, when supplied, an exact single-element target selector. Omitting `selector`
+from an allowance permits that rule everywhere; keep exceptions narrow. Nested
+frame/shadow targets cannot match a simple selector allowance. Allowed nodes stay
+in evidence with `allowed: true`; other nodes of the same rule still fail.
+
+Evidence's `accessibility` array contains URL, viewport, timestamp, violations
+with rule IDs and target selectors, and incomplete checks for manual review.
+Incomplete checks do not fail automatically. A passing automated scan does not
+replace keyboard, screen-reader, focus-order or contrast review. See the
+[axe API](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md) for scan
+semantics. Run at both 390 and 1280 pixels with `assertViewport()` as well.
+
+## Watched development checks
+
+Use an owned app copy with `app.env: { NODE_ENV: "development" }` and
+`app.start: [process.execPath, "node_modules/@warlock.js/core/bin/warlock.js", "dev"]`.
+Do not attach to an existing server. The fixture's `directory` is available in
+`run`; use `node:fs/promises` to edit only files inside that copy.
+
+Wait for a visible revision marker after each edit; a successful file write alone
+does not prove watcher invalidation or browser hydration. Exercise several edits,
+including setup-file creation, changes and removal. After each revision, request
+the page again, exercise a hydrated control, check imported `shared` in loaders
+and middleware, and verify concurrent requests keep distinct values. Do not
+allowlist request-store or hydration errors to make these checks pass.
+
+For forms beneath layouts, compare server-rendered IDs with the hydrated hook
+values (for example expose the hook value in a click handler), check repeated
+instances, label `for` and ARIA references, then navigate away and back. Comparing
+DOM IDs alone can miss a mismatch: React may retain the server attribute while
+client handlers capture another ID. Capture evidence and screenshots at every
+revision. Do not replace React's `useId()` globally or hide hydration warnings.