@hozu/cli 0.23.0 → 0.25.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hozu/cli",
-  "version": "0.23.0",
-  "description": "The hozu command: check, map, why, show, get, browse, call, plan, add, build, dev, serve, docs, migrate and skill (all with --json)",
+  "version": "0.25.0",
+  "description": "The hozu command: check, map, why, show, get, browse, call, plan, add, build, export, gen, dev, serve, docs, migrate and skill (all with --json)",
   "keywords": [
     "hozu",
     "framework",
@@ -48,14 +48,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@hozu/core": "0.23.0",
-    "@hozu/devtools": "0.23.0",
-    "@hozu/validator": "0.23.0",
-    "@hozu/machine": "0.23.0",
-    "@hozu/compiler": "0.23.0",
-    "@hozu/transform": "0.23.0"
+    "@hozu/core": "0.25.0",
+    "@hozu/devtools": "0.25.0",
+    "@hozu/machine": "0.25.0",
+    "@hozu/compiler": "0.25.0",
+    "@hozu/transform": "0.25.0",
+    "@hozu/validator": "0.25.0"
   },
   "devDependencies": {
-    "create-hozu": "0.23.0"
+    "create-hozu": "0.25.0"
   }
 }

package/schema/browse.schema.json

@@ -207,6 +207,23 @@
           "additionalProperties": false,
           "description": "Elements the step removed and built again unchanged: same tag, class, text, `name`, `id`, `href`, `src`, `type` and parent path (ADR 0067 C2, ADR 0069 A3). `count` counts every such element, `elements` names the outermost ones as CSS-like paths (`main > form > input[name=card]`)."
         },
+        "arrived": {
+          "type": "object",
+          "properties": {
+            "prerendered": {
+              "type": "boolean"
+            },
+            "ms": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "prerendered",
+            "ms"
+          ],
+          "additionalProperties": false,
+          "description": "How a navigation arrived (ADR 0072 D3): from a speculation prerender or loaded, and the milliseconds from the activation (prerendered) or the navigation start to the first contentful paint."
+        },
         "shift": {
           "type": "number",
           "description": "Layout shift no input explains (layout-shift entries without recent input, summed, as CLS counts them)."

package/schema/call.schema.json

@@ -77,7 +77,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Tags a mutation invalidated."
+          "description": "Tags a mutation or a writing endpoint invalidated."
         },
         "refreshes": {
           "type": "array",

package/schema/gen.schema.json

@@ -53,7 +53,7 @@
                 "items": {
                   "type": "string"
                 },
-                "description": "Number fields named like an id or a count, which may want z.int() (ADR 0070 C4); not diagnostics."
+                "description": "Number fields named like an id or a count, which may want z.int() (ADR 0070 C4), and enums without a title that became several Go types, which a title makes one; not diagnostics."
               }
             },
             "required": [

package/schema/inspect.schema.json

@@ -747,7 +747,9 @@
         "alternate",
         "env",
         "session",
-        "state"
+        "state",
+        "route",
+        "here"
       ]
     },
     "GuardExpr": {
@@ -1427,6 +1429,13 @@
         },
         "payload": {
           "$ref": "#/definitions/ValueExpr"
+        },
+        "keys": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Only these key presses send it, and they do not reach the browser's own shortcuts (ADR 0072 B)."
         }
       },
       "required": [

package/schema/migrate.schema.json

@@ -41,15 +41,23 @@
               },
               "summary": {
                 "type": "string"
+              },
+              "changes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
               }
             },
             "required": [
               "from",
               "to",
-              "summary"
+              "summary",
+              "changes"
             ],
             "additionalProperties": false
-          }
+          },
+          "description": "Each step's changes: `summary` joins `changes` with \"; \"."
         },
         "changed": {
           "type": "array",

package/skill/SKILL.md

@@ -15,18 +15,17 @@ Hozu is not in your training data: this file and `npx hozu docs <topic>` are the
 2. Edit everything the change needs (table below).
 3. `npx hozu check` once. For an intended behaviour change, `npx hozu check --update-lock`, then list the accepted
    `now:` lines in your summary.
-4. Verify once with the line `hozu map` prints: `npx hozu browse <path> --session '…' --do '…'` (no server, no
-   `curl`).
+4. Verify with the line `hozu map` prints: `npx hozu browse <path> --session '…' --do '…'` (no server).
 5. Show the person the change: `npx hozu show <file:line> --note "<in their words>"`.
 
 ## What to touch
 | Change | Touch |
 |---|---|
-| UI-only state (a tab, a toggle) | a context field → views: `on: { click: ui.set(ctx.tab, 'design') }` |
-| Filter / sort in the URL | the route's `search` (with a default) → `ui.link(route, params, { key })` → `search.key`; while typing: `seed` from `search`, `replace: () => ui.link(…)` |
+| UI state or a mode (a tab, paused) | a context field → views: `on: { click: ui.set(ctx.tab, 'design') }` |
+| Filter / sort in the URL | the route's `search` → `ui.link(route, params, { key })` → `search.key`; while typing: `seed` from `search`, `replace: () => ui.link(…)` |
 | A per-item action (pin, archive) | model: the item field, an event, a mutation that `invalidates` the list tag, an `on` into a state with `invoke` → views: the per-item form (`hozu docs patterns`) |
 | A control every state handles | `machine({ on: [...] })` |
-| Refresh (a button, a timer) | `refresh: () => [tag()]` on a transition |
+| Refresh | data that changes alone: `freshness: { poll: s }`; on a button or pause: `refresh: () => [tag()]` |
 | New page | `routes.ts` → a view with `route` → `ui.page(...)` in `hozu.config.ts` |
 | UI (a button, a field) | `ui.use` of a kit component (`npx hozu docs components`) |
 

package/skill/example/features/bookmarks/views.ts

@@ -24,7 +24,7 @@ const shows = [
 export const Board = ui.view({
   machine: bookmarksMachine,
   route: home,
-  render: ({ ctx, search, when }) =>
+  render: ({ ctx, search, is }) =>
     ui.main({ class: 'mx-auto max-w-xl space-y-6 px-4 py-12' }, [
       ui.h1({ class: 'text-3xl font-bold' }, ['Bookmarks']),
       ui.form(
@@ -55,20 +55,16 @@ export const Board = ui.view({
             { name: 'kind', 'aria-label': 'Kind', class: 'rounded border px-2 py-2' },
             kinds.map((k) => ui.option({ value: k, selected: ctx.kind === k }, [k])),
           ),
-          ui.use(Button, { props: { type: 'submit' } }, ['Add']),
+          ui.use(Button, { props: { type: 'submit', disabled: is(['adding']) } }, ['Add']),
         ],
       ),
       ctx.error !== null && ui.p({ role: 'alert', class: 'text-rose-600' }, [ctx.error]),
-      when(
-        ['adding'],
-        [
-          ui.p({ class: 'rounded border px-4 py-3 opacity-50', 'aria-busy': 'true' }, [
-            'Adding ',
-            ctx.draft,
-            '…',
-          ]),
-        ],
-      ),
+      is(['adding']) &&
+        ui.p({ class: 'rounded border px-4 py-3 opacity-50', 'aria-busy': 'true' }, [
+          'Adding ',
+          ctx.draft,
+          '…',
+        ]),
       ui.nav(
         { class: 'flex gap-2', 'aria-label': 'Show' },
         shows.map((s) =>

package/skill/example/ui/button.ts

@@ -16,8 +16,12 @@ const styles = tv({
 export const Button = ui.component({
   tag: 'button',
   styles,
-  props: z.object({ type: z.enum(['button', 'submit']).default('button') }),
+  props: z.object({
+    type: z.enum(['button', 'submit']).default('button'),
+    disabled: z.boolean().default(false),
+  }),
   children: true,
   events: ['press'],
-  render: ({ props, children, on }) => ui.button({ type: props.type, on: { click: on.press } }, children),
+  render: ({ props, children, on }) =>
+    ui.button({ type: props.type, disabled: props.disabled, on: { click: on.press } }, children),
 })

package/skill/topics/auth.md

@@ -1,7 +1,7 @@
 # Sign-in, sessions, who may read and change what
 
 - **Start:** `hozu add feature notes --page / --with auth` (sign-in page, sign-out, `me`); set `SESSION_SECRET`.
-- `project({ session: z.object({ user: z.string() }) })`. `scope: 'user'` queries and mutations get `session`;
+- `project({ session: z.object({ user: z.string() }) })`. `scope: 'user'` queries and every mutation get `session`;
   a mutation calls `setSession(value)` (`null` signs out).
 - **Every server-run user query and mutation says who may run it**, like `runs` (HZ088):
   - `access: 'signedIn'`: any signed-in visitor; the resolver reads that visitor's data by `session`.
@@ -29,7 +29,7 @@
 - Sessions live on the server: the default store is `memorySessions()` (from `@hozu/runtime-server`); the cookie holds
   only an opaque, signed, HttpOnly id, so `setSession(null)` revokes it and the session never reaches browser
   JavaScript. It is per process: a restart signs everyone out, and an edge or multi-instance deployment passes a
-  shared store explicitly (`createHandler({ session })`).
+  shared store explicitly (`createHandler(app, { session })`).
 - `setSession` also applies in a failing mutation (expiry: `setSession(null)` then `fail('Expired', …)`).
 - After a sign-in or sign-out the page's queries are re-read with the new session; nothing from the old one stays.
 - A role on top of sign-in: `'signedIn'` plus a declared error (`NotAdmin`) mapped to 403 keeps "signed out → login"

package/skill/topics/contracts.md

@@ -23,7 +23,7 @@ changing either.
   and the contract.
 ```ts
 export const addsValid = contract(m, {
-  given: { state: 'idle' },                          // context: initialContext; { touring: true } overrides fields
+  given: { state: 'idle' },                          // context omitted = initialContext; context: { touring: true } patches it
   when: [
     { send: Add, payload: { title: 'Milk' } },
     { done: addItem, result: { id: 'i9', title: 'Milk', done: false } },
@@ -35,3 +35,5 @@ export const addsValid = contract(m, {
   },
 })
 ```
+- Other effects: `{ refresh: [itemsTag()] }`, `{ copy: 'https://…' }` (the clipboard text) and
+  `{ replace: '/?q=milk' }` (the address written in place).

package/skill/topics/data.md

@@ -6,7 +6,7 @@
 |---|---|---|
 | the visitor's own, no sign-in (a watchlist, favourites, settings) | `'browser'` / `'user'` | `localStorage`, in `fetch.ts` (`hozu docs recipes`) |
 | a signed-in user's, on every device | `'server'` / `'user'` + `access` | the app's database |
-| everyone's (posts, a shared board) | `'server'` / `'public'` + a deliberate `access` | the app's database |
+| everyone's (posts, a shared board) | `'server'` / `'public'`; `access` on its mutations | the app's database |
 | a public third-party API (quotes, weather) | `'either'` / `'public'` | nowhere: read it |
 
 The arrays in Hozu's examples and scaffolds are stand-ins that keep them short: one list for every visitor, gone on
@@ -16,7 +16,7 @@ restart. Never ship one; replace it with the store above.
 export const itemsTag = tag({ param: null })                    // tag({ param: z.string() }) → itemTag(id)
 export const listItems = query({
   input: z.object({}), output: z.array(Item),
-  scope: 'public',                  // 'user' = the session's data (needs project({ session }))
+  scope: 'public',                  // 'user' = per visitor (server-run: needs project({ session }))
   freshness: 'static',              // | 'request' | { revalidate: s } | { swr: s } | 'live' | { poll: s }
   tags: () => [itemsTag()],          // optional; (input) => [...]
   runs: 'server',                   // where the implementation lives: 'server' | 'browser' | 'either' (required); hozu docs fetch
@@ -144,9 +144,13 @@ func main() {
 - Route params and form fields are strings: a numeric id is `z.coerce.number()` in the query or mutation input
   (a query input that fails its schema is a program error, reported to `onError` with the field).
 - Data the whole staff shares but only staff may read is `scope: 'user'` with `access` (it is never cached across
-  requests). Share one rule: `const staffOnly = part(({ session }) => session.role !== 'editor')`, then
+  requests). Share one rule: `const staffOnly = part(({ session }) => session.role === 'staff')`, then
   `access: { allow: staffOnly }` on each effect.
-- A resolver may answer `fail('Forbidden', { message })` (a row deleted meanwhile, a check `access` cannot make);
-  with `access: 'signedIn'` its `session` is never null.
+- A resolver may answer `fail('Forbidden', { message })` (a check `access` cannot make); with any access but
+  `'anyone'` its `session` is never null.
+- A failure you can expect (a row gone, a state that forbids the change) is a declared error of the effect
+  (`errors: { NotFound }`, `fail('NotFound', …)`), handled in `failed` with and without JavaScript. A thrown error is
+  `Unexpected`: a server fault (500 on a native post, `Internal error` in production).
 - Another app writing the same database: give the reading app a signed `endpoint` that `invalidates` the tags, and
-  call it after a write (`hozu docs endpoints`).
+  call it after a write (`hozu docs endpoints`). Every query that app's writes change needs a tag, or only its
+  freshness time refreshes it.

package/skill/topics/deploy.md

@@ -15,7 +15,8 @@
 
 ## Details
 - **App options:** `app({ resolvers: resolvers(project, (implement) => [...]), session?, components?, og?, csp?,
-  onError?, preview? })`. There is no wrapper position: headers go through `project({ http })`, statuses through
+  onError?, preview?, refreshSession?, dispose?, dataCache?, cache?, bus?, staticTtl? })` (`refreshSession`:
+  `hozu docs auth`; `dispose` closes a database pool; the caches and `bus`: below). There is no wrapper position: headers go through `project({ http })`, statuses through
   `head.failed` and endpoint `failed`, the language through the URL.
 - **Node:** adapter-node serves `process.env`, styles and every `ui.asset` (hashed under `/_hozu/a/`). There is no
   `public/` folder served at the root: a file the page shows is a `ui.asset(new URL(...))`; a file named in data
@@ -44,7 +45,8 @@
   handler: `createHandler(app, { manifest, render, env, session: kvSessions(env.SESSIONS, { secret:
   env.SESSION_SECRET }) })`. Cloudflare KV may take up to a minute to show a sign-out in other regions.
 - **Another store:** implement `SessionStore` (`read`, `write`, `issue`) and pass it as `app({ session })` or the
-  handler's `session`; keep the cookie an opaque signed id (ADR 0043 B).
+  handler's `session`; keep the cookie an opaque signed id (ADR 0043 B). With `app({ refreshSession })` it also
+  needs `update(request, value)`: replace the value under the request's id, keep the id, and say whether it did.
 
 ## Caches and many instances
 - **Bounded caches:** public query results and cached pages are LRU caches, at most 10,000 entries and 5,000 pages

package/skill/topics/diagnostics.md

@@ -12,11 +12,11 @@ around the rule. `npx hozu docs HZ083` prints one code: its cause, its fix and t
 | --- | --- | --- |
 | HZ001 | state unreachable | add a transition to it or delete it |
 | HZ002 | event handled nowhere | handle it in a state or remove it |
-| HZ003 | unknown effect / reference | export it from a module the feature lists in `declarations`, or fix the name (the patch suggests one) |
+| HZ003 | unknown effect / query | export it from a module the feature lists in `declarations`, or fix the name (the patch suggests one) |
 | HZ004 | a declared error is not handled | add every `failed` key, plus `Unexpected`, in `invoke` and `ui.query` |
-| HZ005 | a node sends an event in a state (without `invoke`) that does not handle it | handle it there (`machine({ on })` handles it in every state), show the node only via `when`, or `ignore: [Event]` to drop it |
+| HZ005 | a node sends an event in a state (without `invoke`) that does not handle it | handle it there (`machine({ on })` handles it in every state), show the node only in the states that handle it (`is([...]) && …`), or `ignore: [Event]` to drop it |
 | HZ006 | crossing a feature boundary | import the feature and use its `exports` |
-| HZ007 | unknown effect / reference | export it from a module the feature lists in `declarations`, or fix the name (the patch suggests one) |
+| HZ007 | unknown effect, reference, route or state name; `'previous'` with nothing to return to; `given.previous` naming a state with `invoke`; a `current()` param the route lacks | export it from a module the feature lists in `declarations`, register it, or fix the name (the patch suggests one) |
 | HZ008 | a path does not exist in the schema | fix the property name |
 | HZ009 | a guardless transition shadows later ones | put guarded transitions first |
 | HZ010 (warning) | a state has no way out (not final; no `on`, `invoke` or `after`) | mark it `final: true` or add a transition out of it |
@@ -50,15 +50,15 @@ around the rule. `npx hozu docs HZ083` prints one code: its cause, its fix and t
 | HZ038 | `http.headers` sets a header the framework owns, or an invalid name/value | remove it (`cache-control` is derived; CSP is `app({ csp })`) |
 | HZ039 | `basePath` is not `''` or `/segment[/segment…]` | e.g. `'/shop'`, no trailing slash |
 | HZ040 | a locale lacks a message, or uses other `{placeholders}` | add/translate the key in that locale |
-| HZ041 | a machine uses a message, `ui.format` or `locale` | store a code in context; choose the message in the view |
+| HZ041 | a machine uses a message, `ui.format`, `locale` or the env | store a code in context; choose the message in the view |
 | HZ042 | `site.locales` empty / missing `site.lang` / not a canonical tag, or `ui.alternate` of an undeclared locale | fix the list (`'zh-TW'`, not `'zh_tw'`) |
 | HZ043 | `site.offline` has params, no page, or per-request data | point it at a static page, or remove `offline` |
 | HZ044 | a feature file was loaded without the Hozu transform | run node with `--import @hozu/transform/register` (`npm start` does), or add `hozuTransform()` to Vite / Vitest |
-| HZ045 | no `project({ app })`, its default export is not `app(…)`, or views use client components and `app()` has no bundle | `export default app({ resolvers, components: bundleComponents })` |
+| HZ045 | no `project({ app })`, its default export is not `app(…)`, or views use client components (or a feature has `fetch.ts`) and `app()` has no bundle | `export default app({ resolvers, components: bundleComponents })` |
 | HZ046 | an endpoint path is reserved, has params or collides; an error without a status, or with one an endpoint error cannot answer; a form posting to it with another method or an undeclared field | a static path such as `/api/…` (patch); map every error in `failed` to 400, 401, 403, 404, 409, 410, 422 or 429 |
 | HZ047 | a `fn` body uses an imported name or `let` state (it is sent to the browser as source) | pass the value as input, or write it as a `const` helper in the module |
 | HZ048 | `seed` names a field the context lacks, has no machine or route, or two views on one page seed a machine | seed top-level context fields, on one view per page |
-| HZ049 | a `scope: 'user'` query is cached (`'static'`, `revalidate`, `swr`) | `freshness: 'request'` (patch), or `'live'` for push |
+| HZ049 | a `scope: 'user'` query is cached (`'static'`, `revalidate`, `swr`) | `freshness: 'request'` (patch), `'live'` for push, or `{ poll: s }` for a timer |
 | HZ050 | a `'live'` query has no tags | add the tags its writers invalidate, or use `'request'` |
 | HZ051 | `head.failed` misses a declared error of the head query, or maps another one | choose per error: a route (303), `403`, `404` or `410` (an intent decision: no patch) |
 | HZ052 | a route that no page renders | link to the endpoint with `ui.link(endpoint, input)` (patch), or add its `ui.page` |
@@ -68,7 +68,7 @@ around the rule. `npx hozu docs HZ083` prints one code: its cause, its fix and t
 | HZ056 (warning) | a submit button also sends on click | `name`/`value` on the button, read in submit; or `type: 'button'` |
 | HZ057 | `hozu.lock.json` differs from the computed lock (new, removed or copy-only changes, contract maps, a missing or 0.7 file) | if intended, `hozu check --update-lock`, then list the accepted `now:` lines in your summary |
 | HZ058 (warning) | contracts that fire only copy-only transitions and evaluate no guard | none needed: the lock entries it names review those transitions |
-| HZ059 | data reached plain JavaScript: a plain helper, a global (`Boolean`, `Object.keys`, `String`…), `typeof`, a spread or `in` | make the helper a `part()`; for a global use an operator or a `fn()` |
+| HZ059 | data reached plain JavaScript: a plain helper, a global (`Boolean`, `Object.keys`, `String`…), `typeof`, an array spread or `in` (an object spread such as `{ ...search, x }` is lowered) | make the helper a `part()`; for a global use an operator or a `fn()` |
 | HZ060 | a page route starts with a locale segment (`/de/…` under `site.locales`) | rename the route (patch); the locale prefix is added for you |
 | HZ061 (warning) | a form-fed event payload declares limits | move them to the mutation input |
 | HZ062 (warning) | a GET endpoint declares `invalidates` | `method: 'POST'`, or keep it on purpose (e-mail links) |
@@ -97,4 +97,4 @@ around the rule. `npx hozu docs HZ083` prints one code: its cause, its fix and t
 | HZ090 (warning) | `access: 'anyone'` on a `scope: 'user'` query: every visitor, signed in or not, may read it | say who may read it (`'signedIn'`, `{ owner: { row, session } }`), or accept the warning with a reason |
 | HZ091 | a query with `owner` access returned rows the visitor does not own (reported at run time) | read only the visitor's rows in the resolver (filter by the session); production drops the extra rows and logs this |
 | HZ092 | a preview in `project({ previews })` no longer fits the app: data off its query output schema, an error the query does not declare, a route without a page, or a component use that does not build | update the preview to the current schema, error, page or component (previews are for people: they never ship) |
-| HZ093 | a `remote()` resolver that cannot answer: its generated contract is missing or stale, or it lists an effect the browser runs or a non-JSON endpoint | run `hozu gen` and rebuild the service; implement browser-run effects in fetch.ts and non-JSON endpoints in TypeScript |
+| HZ093 | a `remote()` resolver that cannot answer: its generated contract is missing or stale, its secret is missing, undeclared in `env.server` or under 16 characters, or it lists an effect the browser runs or a non-JSON endpoint | run `hozu gen` and rebuild the service; set a 16+ character secret from `env.server`; implement browser-run effects in fetch.ts and non-JSON endpoints in TypeScript |

package/skill/topics/feature.md

@@ -29,7 +29,7 @@ export const items = machine({
         done: { target: 'idle', assign: () => { ctx.draft = '' } },
         failed: {
           Duplicate: { target: 'idle', assign: () => { ctx.error = 'Already listed' } },
-          Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } },
+          Unexpected: { target: 'idle', assign: () => { ctx.error = 'Try again' } },
         },
       }),
     },
@@ -38,14 +38,14 @@ export const items = machine({
 // views.ts
 export const Board = ui.view({
   machine: items,
-  render: ({ ctx, when }) =>
+  render: ({ ctx, is }) =>
     ui.main({ class: 'mx-auto max-w-xl' }, [
       ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title') }) } }, [
         ui.input({ name: 'title', required: true, value: ctx.draft }),
-        ui.button({ type: 'submit' }, ['Add']),
+        ui.button({ type: 'submit', disabled: is(['adding']) }, ['Add']),
       ]),
       ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error]),
-      when(['adding'], [ui.p({ 'aria-busy': 'true' }, [`Adding ${ctx.draft}…`])]),
+      is(['adding']) && ui.p({ 'aria-busy': 'true' }, [`Adding ${ctx.draft}…`]),
       ui.query(listItems, {}, {
         ready: (list) => ui.ul({}, [ui.each(list, 'id', (i) => ui.li({}, [i.title, i.done ? ' ✓' : '']))]),
         failed: { Unexpected: () => ui.p({ role: 'alert' }, ['Unavailable']) },
@@ -73,7 +73,7 @@ Every declaration a listed module exports is registered under its name; schemas
 - A mutation runs when the machine **enters** a state whose `invoke` calls it; that state drops other events, and
   `done` / `failed` leave it.
 - A filter in the URL starts the machine: `seed: ({ search }) => ({ q: search.q })` on the view, then read `ctx.q`.
-  `machine({ on })` holds transitions every idle state shares; `fn` bodies may call helpers from the same module.
+  `machine({ on })` holds transitions every state without `invoke` shares; `fn` bodies may call helpers from the same module.
 - Reusable view logic is a `part((…) => …)`, inlined where it is used (`hozu docs views`).
 
 ## Files

package/skill/topics/forms.md

@@ -43,5 +43,7 @@ ui.use(Button, { props: { type: 'submit' } }, ['Add']),
   `ui.form({ ref: bulk, … })`, `ui.input({ form: bulk, … })`; a string `form` is HZ014, a name no control has HZ055.
 - **A flag or a number:** a checkbox posts `'on'` only while checked: `ui.dom.formAll('remember')` into
   `z.array(z.string())`, or a radio pair. Send numbers as text and parse them in the mutation input (`z.coerce.number()`).
+- **Several steps without JavaScript** (a checkout): each step is a state; every form carries the machine's state
+  in a signed hidden field, so the next native post continues from it (`hozu docs recipes`, "A multi-step checkout").
 - **An invalid native post:** a native post whose payload or mutation input fails re-renders with 400 through
   `failed.Invalid`, like the JS submit.

package/skill/topics/http.md

@@ -17,6 +17,7 @@ http: {
   headers: [{ routes: 'all', set: { 'permissions-policy': 'camera=()' } }],   // not cache-control (HZ038)
 },
 ```
-Server options live in the app module: `app({ resolvers, session?, components?, onError?, csp?, og?, preview? })`.
+Server options live in the app module: `app({ resolvers, session?, components?, onError?, csp?, og?, preview?,
+refreshSession?, dispose?, dataCache?, cache?, bus?, staticTtl? })` (`hozu docs deploy`).
 A strict CSP, `nosniff` and a cross-site POST check are on by default; `csp: { img: ['https://…'] }` adds sources
 (`script style img font connect frame media`).

package/skill/topics/i18n.md

@@ -6,7 +6,7 @@
 - `export const text = ui.messages('en', { en: { saved: '{count} saved' }, de: { saved: '{count} gespeichert' } })`
   in a listed module; `text.saved({ count })` in views. Every locale needs every key (HZ040).
 - Machines never hold translated text (HZ041): store a code.
-- **Data per language:** `locale` (in every view, and the second argument of `head.input` / `head.render`) goes into
+- **Data per language:** `locale` (in every view, 2nd argument of `head.input`, 3rd of `head.render`) goes into
   the query input: `ui.query(listPosts, { locale })`; `head: { input: (params, locale) => ({ slug: params.slug,
   locale }) }`. It is typed `string`: declare the input `z.string()`, or narrow it with `locale as Locale`.
 
@@ -23,7 +23,9 @@
   `{placeholders}` (HZ040). Plurals: `'{n, plural, =0 {none} one {# item} other {# items}}'`.
 - Machines store a code and the view chooses the message.
 - `ui.format.number(x, { style: 'currency', currency: 'EUR' })`, `ui.format.date(x, { dateStyle: 'medium' })`,
-  `ui.format.relative(n, 'day')`, `ui.format.list(xs)`. `locale` is in every view.
+  `ui.format.relative(n, 'day')`, `ui.format.list(xs)`, `ui.format.plural(n, { one: '# item', other: '# items' })`.
+  `locale` is in every view.
+- Head signatures: `input: (params, locale, search)`, `render: (data, params, locale, search)`.
 - Resolvers have no locale of their own; it reaches them only through the input. The sitemap lists one entry per
   `entries` input in every locale.
 - `ui.format.date` takes an ISO string or a timestamp and formats it in the page's locale, in the time zone of the

package/skill/topics/machine.md

@@ -11,7 +11,7 @@ export const m = machine({
       invoke: invoke(addItem, {
         input: { title: ctx.draft },
         done: { target: 'idle', assign: () => { ctx.draft = '' } },
-        failed: { Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } } },
+        failed: { Unexpected: { target: 'idle', assign: () => { ctx.error = 'Try again' } } },
       }),
     },
   }),
@@ -29,8 +29,8 @@ export const m = machine({
 - `target: 'previous'` (or `done: 'previous'`) returns to the last state without `invoke`, so a busy state entered
   from two modes (viewing, editing) needs no copy per mode.
 - **refresh** reads the page's queries with those tags again: `on(RefreshNow, { refresh: () => [quotesTag()] })`;
-  every 30 s while live: `live: { after: [{ ms: 30_000, target: 'live', refresh: () => [quotesTag()] }] }` (Pause is
-  another state). **copy** writes text to the clipboard: `on(CopyLink, { copy: (e) => e.url })` (on an event: the
+  every 30 s unless paused: `after: [{ ms: 30_000, target: 'idle', guard: () => !ctx.paused, refresh: … }]`. A mode
+  the person sets (paused) is a context field: busy states keep it. **copy** writes text to the clipboard: `on(CopyLink, { copy: (e) => e.url })` (on an event: the
   browser allows it only right after a click). **replace** writes the address without loading a page:
   `replace: () => ui.link(home, null, { q: ctx.q })`, so a reload or a shared link keeps it (with `seed`). Effects
   and `navigate` read the context after `assign`.
@@ -59,7 +59,7 @@ export const m = machine({
         done: { target: 'idle', assign: () => { ctx.draft = '' }, navigate: (r) => ui.link(itemPage, { id: r.id }) },
         failed: {                               // every declared error + Unexpected (+ optional Invalid)
           Duplicate: { target: 'idle', assign: () => { ctx.error = 'Already exists' } },
-          Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } },
+          Unexpected: { target: 'idle', assign: () => { ctx.error = 'unexpected' } },   // a code; the view words it
         },
       }),
     },
@@ -68,7 +68,11 @@ export const m = machine({
   }),
 })
 ```
-- Calm state follows the visitor to a page that shows the same view, and back to the same address.
+- **Across pages:** the calm state (the last state without `invoke`, with its context) is kept in `sessionStorage`
+  and resumed on a page that shows the same machine view, or on the same address; a reload or a page without that
+  view starts from `initialContext` (or `seed`).
+- `Unexpected`'s `message` is `Internal error (call <id>)` in production (the real one reaches `onError`): store a
+  code or a fixed text, never `e.message`.
 - **assign** values are event (`e`), result (`r`) or error fields, context, literals, operators and `fn()` calls.
 - **guard** conditions: a field (`() => ctx.auto`), comparisons, `&&`, `||`, `!`, or a boolean `fn()`.
 - **navigate** sends the browser to `ui.link(route, params, search?)` after the transition. It returns one link: to

package/skill/topics/pages.md

@@ -66,4 +66,6 @@ export default project({
 - A detail view: `ui.view({ route: itemPage, render: ({ params }) => ui.query(getItem, { id: params.id }, { ready,
   failed: { NotFound: () => ui.p({}, ['Not found']), Unexpected: () => … } }) })`.
 - A page loads JS only when a machine-bound part renders on it (`hozu plan <route or path>`). Every link loads a document;
-  state across pages lives in the URL (`seed`), on the server (queries) or in a client component's own storage.
+  a machine whose view both pages show (or the same address) resumes its calm state, the last state without `invoke`,
+  from `sessionStorage`; a reload or a page without that view starts from `initialContext` (or `seed`). What must
+  survive a reload lives in the URL (`seed`), on the server (queries) or in a client component's own storage.

package/skill/topics/patterns.md

@@ -3,9 +3,9 @@
 The controls are plain elements; in an app with a kit, use its components (`ui.use(Button, …)`,
 `hozu docs components`).
 
-- **Busy state:** render every control once; the state with `invoke` drops repeated submits. Progress:
-  `when(['adding'], [ui.p({ 'aria-busy': 'true' }, ['Saving…'])])`. Do not duplicate controls under `when`.
-- **Optimistic item:** `when(['adding'], [ui.li({ class: 'opacity-50' }, [ctx.draft])])`; leaving the state removes it
+- **Busy state:** render every control once and disable it: `disabled: is(['adding'])` (`invoke` drops repeats).
+  Progress: `is(['adding']) && ui.p({ 'aria-busy': 'true' }, ['Saving…'])`.
+- **Optimistic item:** `is(['adding']) && ui.li({ class: 'opacity-50' }, [ctx.draft])`; leaving the state removes it
   and the refreshed query shows the real item.
 - **Refresh after a mutation:** tag the query, list the tag in the mutation's `invalidates`.
 - **Go to what was just created:** `done: { target: 'idle', navigate: (r) => ui.link(itemPage, { id: r.id }) }`.
@@ -82,6 +82,7 @@ ui.each(items, 'id', (item) => ui.li({}, [ui.input({ type: 'checkbox', form: bul
   `ui.each(ctx.cursors, null, (cursor) => ui.query(listPage, { cursor }, { ready: (page) => … }))`; on the last page
   (`cursor === ctx.last && page.next !== null`) a sentinel `on: { visible: ui.send(More, { cursor: page.next }) }`;
   `More` pushes the cursor, guarded by `e.cursor !== null && e.cursor !== ctx.last`.
-- **A link starts the page again:** every internal link is a document navigation, so a machine's context starts
-  from `initialContext` (or `seed`). Keep what must survive in the URL: put both filters in `search` and `seed` the
-  context from it, instead of one in the URL and one in context.
+- **What a link keeps:** every internal link loads a document. A machine whose view both pages show (or the same
+  address) resumes its calm state, the last state without `invoke`, from `sessionStorage`; a reload or a page
+  without that view starts from `initialContext` (or `seed`). Keep what must survive a reload or a shared link in
+  the URL: put both filters in `search` and `seed` the context from it, not one in the URL and one in context.

package/skill/topics/recipes.md

@@ -20,8 +20,8 @@ The list is the visitor's own: it lives in their browser, so two visitors never
 - **feature.ts:** `fetch: new URL('./fetch.ts', import.meta.url)`; `app.ts`: `components: bundleComponents`.
 - **Data about the items** (quotes, prices) is public: a `runs: 'server'` (or `'either'`) query inside the list's
   `ready` branch, `ui.query(quotes, { symbols }, …)`.
-- Refresh controls (Pause / Resume / Refresh now): states `live` / `paused`, `refresh: () => [quotesTag()]` on
-  `RefreshNow` and on `live`'s `after: [{ ms: 30_000, target: 'live', … }]`; adds return with `done: 'previous'`.
+- Pause / Resume / Refresh now: `paused` is a context field (a mode), `refresh: () => [quotesTag()]` on
+  `RefreshNow`, on `Resume` (`target: 'idle'` restarts the timer) and on the guarded `after` (`hozu docs machine`).
 - **Ask the server before saving** (normalize "2330" to "2330.TW"): a `runs: 'server'` query `resolveSymbol`, then
   the browser mutation: `looking: { invoke: invoke(resolveSymbol, { input: { q: ctx.symbol }, done: { target:
   'saving', assign: (r) => { ctx.symbol = r.symbol } }, failed: { … target: 'previous' } }) }`, `saving: { invoke:
@@ -89,7 +89,16 @@ const staffHead = { query: me, render: (m) => ({ title: `${m.name} · Admin` }),
 const staff = (route, View) => ui.page(route, { views: [Sidebar, View], head: staffHead })
 export default project({ /* … */ pages: [staff(orders, OrderList), staff(orderDetail, OrderPage), …] })
 ```
-The sidebar's links mark the page shown with `aria-current` by themselves (`aria-[current]:font-bold`).
+The sidebar marks its sections with `current(route)` from its render, one line per section:
+```ts
+render: ({ current }) => ui.nav({}, [
+  ...[
+    [orders, 'Orders', current(orders) || current(orderDetail)],
+    [customers, 'Customers', current(customers) || current(customer)],
+  ].map(([r, label, here]) => ui.a({ href: ui.link(r, null), 'aria-current': here, class: 'aria-[current]:font-bold' }, [label])),
+])
+```
+A store's categories: `current(shop, { category: c })` over a constant list of categories.
 
 ## Screens with different state
 One machine per feature: an order list (filters, selection) and an order page (shipping, refund) are two features,
@@ -98,8 +107,9 @@ One machine per feature: an order list (filters, selection) and an order page (s
 ## A multi-step checkout that also works without JavaScript
 Each step is a state and each step's form posts only its own fields: after a native post the server renders the next
 step, and every form on that page carries the machine's state in a signed hidden field, so the next post continues
-from it (going back to edit a step too). Prefill from the member with
-`seed: ({ query }) => ({ email: query(me, {}).email })`.
+from it (going back to edit a step too; the field is `__hozu_state`, sealed with `SESSION_SECRET`). Prefill from
+the member on the view that has both `machine` and `route` (HZ048):
+`ui.view({ machine: checkout, route: checkoutPage, seed: ({ query }) => ({ email: query(me, {}).email }), render })`.
 
 ## A notice after saving
 A `notice` context field set in `done` and cleared by `after: [{ ms: 4000, target: 'idle' }]` on a `saved` state;

package/skill/topics/testing.md

@@ -80,6 +80,13 @@
     `--select <css>`, `--screenshot shot.png` (after the steps), `--viewport 390x844` (a phone; default 1280x800) and
     `--reduced-motion`.
   - It also prints the client components on the page (mounted, failed, size, canvases).
+- **More checks in a step:**
+  - A click that would land on another element fails the step: `the click would land on <h3>, which contains it, above
+    <a href="/x">: a person cannot click it` (an overlay, a card covering its link).
+  - A navigation shows how it arrived: `→ /x (loaded, 32 ms)` or `(prerendered, 4 ms)`; with `--js both`, per mode.
+  - `--select` prints each element's `class` too. An element moved to another parent is not a flash.
+- A server error that `get` or `browse` lists is noted once with `a production server shows "Internal error" here`:
+  the visitor sees that text and the call id; `onError` gets the message.
 - **`testApp`:** `app` is the default export of `app.ts`; `.post(path, fields)` submits a native form, with fields as
   a record or as `[name, value]` pairs for repeated names. `testApp(app, { session: store })` may swap only the
   session store (a test issuer). `testApp` reads no env files: pass `testApp(app, { env: process.env })` (or a record)