create-hozu 0.7.0 → 0.9.0

package/skill/topics/components.md

@@ -0,0 +1,67 @@
+# Components (shared UI, kits, browser code)
+
+A UI piece used by several features is a component in a kit. Start with `hozu add kit ui` (writes `ui/kit.ts`,
+`ui/tv.ts` and `project({ kits })`), then `hozu add component ui Button`; `hozu add component <feature> <Name>` makes
+one private to that feature.
+```ts
+// ui/button.ts; ui/kit.ts lists it: ui.kit({ id: 'ui', components: [button, input] })
+const styles = tv({                                            // tv from ./tv.ts
+  base: 'inline-flex gap-2 rounded px-4 py-2 disabled:opacity-50 aria-busy:cursor-wait',
+  variants: { tone: { primary: 'bg-indigo-600 text-white', ghost: 'text-slate-700 hover:bg-slate-100' } },
+  defaultVariants: { tone: 'primary' },
+})
+export const Button = ui.component({
+  tag: 'button', styles, slots: ['icon'], children: true, events: ['press'],
+  props: z.object({ type: z.enum(['button', 'submit']).default('button'), busy: z.boolean().default(false) }),
+  render: ({ props, slots, children, on }) =>
+    ui.button({ type: props.type, 'aria-busy': props.busy, on: { click: on.press } }, [slots.icon, ...children]),
+})
+```
+```ts
+ui.use(Button, { variant: { tone: 'ghost' }, props: { busy: ctx.saving }, slots: { icon: ui.span({}, ['+']) },
+  on: { press: ui.send(Save, {}) }, class: 'w-full' }, ['Save'])           // in a view; its id is ui.Button
+```
+- **`ui.use` keys:** `variant` (literals), `props` (data), `slots`, `on`, `class`; children only with
+  `children: true`. Every key is optional when the component needs none.
+- **Variants vs props:** a variant is a fixed look chosen in the view (HZ071 for data); anything that changes while
+  the page runs is a prop. Style a state through the attribute that announces it: `disabled:`, `aria-pressed:`,
+  `aria-busy:`, `aria-invalid:`, `aria-expanded:`, `open:`. `toggle` is for states without one.
+- **Render:** it reads only `props`, `slots`, `children`, `on` and `classes` (the other tv slots,
+  `classes.label`); the caller passes sends, links and text in (HZ070). Hozu puts the root class on the root.
+- **Extension:** `class` may add classes that set none of the component's properties (`w-full`, `relative`,
+  `md:hidden`). To change one, declare a variant; a one-off ends with `!` (`rounded-lg!`) (HZ072–HZ077).
+  `hozu check` counts the `!` per component; `extend: false` refuses every class.
+- A view fragment that two features inline is a component, not a `part()` (HZ080).
+
+## Client components (browser APIs, DOM libraries)
+`hozu add component <kit|feature> <Name> --client` writes the declaration, the client module, the bundle in `app.ts`
+and the `@hozu/bundle` dependency.
+```ts
+export const Map = ui.component({ tag: 'div', props: z.object({ lat: z.number(), lng: z.number() }),
+  emits: { picked: z.object({ id: z.string() }) }, client: new URL('./map.client.ts', import.meta.url),
+  load: 'visible', render: () => ui.div({}, []) })                     // 'eager' | 'visible' | 'idle'
+ui.use(Map, { props: { lat: ctx.lat, lng: ctx.lng }, on: { picked: (d) => ui.send(Pick, { id: d.id }) },
+  class: 'h-96 w-full' })
+```
+```ts
+// map.client.ts: a type-only import of the declaration
+import { implement } from '@hozu/core/component'
+import type { Map } from './components.ts'
+export default implement<typeof Map>(({ el, props, emit, signal }) => {
+  const map = createMap(el, props)                          // any DOM library
+  map.on('pick', (id) => emit('picked', { id }))
+  return { update(next) { map.move(next) }, destroy() { map.remove() } }
+})
+```
+- The render is the server HTML the module takes over; with `children: true` the children stay as the no-JS
+  fallback. The root takes no attributes or `on`: put a role or label on a wrapping element.
+- `app.ts` passes `components: bundleComponents` (`@hozu/bundle`) to `app()` (HZ045 without it). A library's CSS
+  goes in `app.css`; a map or chart host needs a height class.
+- `hozu browse /` lists each one as mounted / failed / not mounted with its size and canvases; a mounted host has
+  `data-hozu-component="<id>"` and `data-hozu-component-state="mounted"`.
+
+## Look them up
+- `hozu docs components` (this topic, then the app's list), `hozu inspect ui.Button` (variants, props, owned
+  classes, every use), `hozu impact ui.Button`.
+- `hozu render ui.Button --variant tone=ghost --props '{"busy":true}' --slot icon=+` renders it alone: HTML, root
+  class, owned properties, diagnostics.

package/skill/topics/content.md

@@ -1,7 +1,7 @@
 # Markdown, images, share images, fonts, preview, offline
 
 - **Markdown:** `@hozu/content`: `const posts = await loadCollection({ dir: new URL('./content/posts/', import.meta.url), schema })`
-  in `server.ts` gives `{ slug, data, html, headings }`; return it from query resolvers and render `ui.html(post.html)`.
+  in `app.ts` gives `{ slug, data, html, headings }`; return it from query resolvers and render `ui.html(post.html)`.
 - **Images:** `ui.img({ src: ui.asset(new URL('./hero.jpg', import.meta.url)), alt, width, height })` (HZ028 without
   dimensions). With `@hozu/image`, `hozu build` adds WebP `srcset` widths.
 - **Share images:** `head.render → image: ui.og({ title, subtitle })` (needs `og: ogImage` from `@hozu/image` in

package/skill/topics/contracts.md

@@ -1,8 +1,11 @@
 # Contracts
 
-A transition that **decides** needs a contract: a guard, a `navigate`, or a `fn()` in its values (HZ016 prints each
-missing one, ready to paste). Transitions that only copy values need none: `hozu.lock.json` records every transition
-in readable form, and a change shows as HZ018 `was: … now: …` until `hozu check --update-lock` accepts it.
+A transition that **decides** needs a contract: a guard, a `navigate`, or a `fn()`, a comparison or a computing
+operator (`+ - ?? ?: .length .includes`) in its values (HZ016 prints each missing one, ready to paste). Transitions that
+only copy values need none (a contract there is HZ058). `hozu.lock.json` records every transition readably and must
+equal the computed lock: any difference is HZ057 until `hozu check --update-lock` accepts it; then list the accepted
+`now:` lines in your summary. A deciding change also needs a contract that fails against the old behaviour (HZ018);
+renaming or copying a contract does not count.
 ```ts
 export const addsValid = contract(m, {
   given: { state: 'idle' },                          // context: initialContext; { touring: true } overrides fields

package/skill/topics/data.md

@@ -4,8 +4,8 @@
 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' = per-session data (needs project({ session }))
-  freshness: 'static',              // | { revalidate: seconds } | { swr: seconds } | 'live'
+  scope: 'public',                  // 'user' = the session's data (needs project({ session }))
+  freshness: 'static',              // | 'request' | { revalidate: seconds } | { swr: seconds } | 'live'
   tags: () => [itemsTag()],          // optional; (input) => [...]
 })
 export const getItem = query({ input: Key, output: Item, errors: { NotFound: Key }, scope: 'public',
@@ -25,13 +25,24 @@ export const visible = fn({                   // computation: pure JS; may call
   it. Imported names and `let` state are not (HZ047): pass them as input.
 - Rendering is derived: `scope` and `freshness` decide static, ISR, SWR, streamed or client rendering;
   `scope: 'user'` data never reaches a cached page (HZ022). A mutation's tags can read only its input.
-- **Resolvers** (`server.ts`, or `features/<name>/server.ts` from the scaffold):
+- Freshness: public data is `'static'` with tags unless it changes without a declared writer. `'request'` reads
+  once per request (any scope; a public one makes its page uncacheable). User data is `'request'` or `'live'` only
+  (HZ049). `'live'` is only for push updates and needs tags (HZ050).
+- `invalidates` drives the refresh: after a mutation or endpoint, cached pages and entries with those tags are
+  dropped and the page's queries with those tags are re-read. `endpoint({ …, invalidates: (input) => [tag()] })`
+  applies when it succeeds (use POST; a GET write is HZ062).
+- Writes from outside (a webhook, a job): `await server.revalidate([itemsTag()])` → `{ entries, pages }`.
+- **Query resolvers only read.** Writes happen in mutation and endpoint resolvers: a query that creates a row on read
+  runs again on every request, on prefetch and after a delete (the account comes back). Keep two helpers:
+  `listOf(user)` returns the stored list or `[]` for queries; `ownListOf(user)` creates it, for mutations only.
+- **Resolvers** (in `app.ts`, or `features/<name>/server.ts` from the scaffold, spread into it) get the
+  schema-parsed input (defaults and transforms applied):
 ```ts
-export const createResolvers = () => resolvers(project, (implement) => [
+export default app({ resolvers: resolvers(project, (implement) => [
   implement(listItems, () => items.map((i) => ({ ...i }))),
   implement(getItem, ({ id }, { fail }) => items.find((i) => i.id === id) ?? fail('NotFound', { id })),
   implement(addItem, ({ title }, { fail, session }) => /* … */ ),
-])
+]) })
 ```
 - Every mutation also has `Invalid` = `{ message, fields }` (input failing its schema, or
   `fail('Invalid', { message, fields: { title: 'Taken' } })`); never declare `Invalid` or `Unexpected` yourself.

package/skill/topics/deploy.md

@@ -1,12 +1,16 @@
 # Deployment
 
-- **Node:** `npm start` (`node --import @hozu/transform/register serve.ts`). `hozu build` writes `dist/public/`,
-  `dist/manifest.json` and `dist/server/render.js`; serve with
-  `createServer({ build: buildProject(project, { manifest }), manifest, publicDir: 'dist/public', … })`.
+- **One app module:** `project({ app: new URL('./app.ts', import.meta.url) })`, and `app.ts` default-exports
+  `app({ resolvers: resolvers(project, (implement) => [...]), session?, components?, og?, csp?, onError?, preview? })`
+  from `@hozu/runtime-server`. `hozu serve`, `hozu check`, `hozu get`, `hozu browse` and `testApp(app)` all run this
+  module, so what the tools verify is what production serves. There is no wrapper position: headers go through
+  `project({ http })`, statuses through `head.failed` and endpoint `failed`, the language through the URL.
+- **Node:** `npm start` is `hozu serve`: adapter-node on `PORT` (and `HOST`), `process.env`, styles, images and
+  `public/`. `hozu build` writes `dist/public/`, `dist/manifest.json` and `dist/server/render.js`.
 - **Edge (Bun, Deno, Workers, Vercel):** bundle with `hozuTransform()` from `@hozu/transform/esbuild`, then
-  `createHandler({ build: buildProject(project, { manifest }), manifest, render, resolvers })` from
-  `@hozu/runtime-server`, `export default { fetch: handler.fetch }`, where `render` is `import * as render from
-  './dist/server/render.js'`.
-- **Static host (GitHub Pages):** `exportStatic({ build, styles, resolvers, outDir })` from `@hozu/adapter-static`
-  writes every page without per-request data plus the files they link to, and lists skipped routes.
-- Set `SESSION_SECRET` (and `SESSION_SECURE=true`) when the app has sessions.
+  `createHandler(app, { manifest, render, env })` from `@hozu/runtime-server` and
+  `export default { fetch: handler.fetch }`, where `render` is `import * as render from './dist/server/render.js'`.
+- **Static host (GitHub Pages):** `exportStatic({ build, styles, resolvers: appOptionsOf(app).resolvers, outDir })`
+  from `@hozu/adapter-static` writes every page without per-request data, and lists skipped routes.
+- Set `SESSION_SECRET` when the app has sessions (production refuses to start without it). The default store keeps
+  sessions in memory per process; an edge or multi-instance deployment passes a shared store as `app({ session })`.

package/skill/topics/diagnostics.md

@@ -15,21 +15,22 @@ around the rule.
 | HZ009 | a guardless transition shadows later ones | put guarded transitions first |
 | HZ014 | wrong builder output, or a method called on data (`.map`, `.toUpperCase()`) | follow the builder signature; lists: `ui.each`; computation: a `fn()` |
 | HZ015 / HZ017 | a contract fails / contract data does not match its schema | fix the machine or the contract (decide the intended behaviour first) |
-| HZ016 | a transition that decides (guard, `navigate`, `fn`) has no contract | add the contract from the snippet |
-| HZ018 | behaviour changed; the message shows `was: … now: …` | decision: update its contract; copy-only transition: `--update-lock` if intended |
-| HZ021 | a query or mutation without a resolver | `implement(...)` it in server.ts |
+| HZ016 | a transition that decides (guard, `navigate`, a `fn`, comparison or `+ - ?? ?: .length .includes` in a value) has no contract | add the contract from the snippet |
+| HZ018 | a deciding transition changed (fields first, then `was:` / `now:`) and no covering contract fails against the old behaviour | change or add a contract that specifies the new behaviour; renaming or copying one does not count |
+| HZ021 | a query, mutation or endpoint without a resolver | `implement(...)` it in the resolvers of `app.ts` |
 | HZ022 | user data in a cacheable region | keep `scope: 'user'` queries out of cached pages |
-| HZ024 / HZ025 | route params mismatch (keys, or a schema that does not fit `:x?`/`:x+`/`:x*`) / page with params but no `entries` | align them / add `entries` |
+| HZ024 / HZ025 | route params mismatch (keys, or a schema that does not fit `:x?`/`:x+`/`:x*`) / page with params but no `entries` (a user-scoped head is private: no sitemap, no warning) | align them / add `entries` |
 | HZ026 | a class produces no CSS | fix the Tailwind class |
 | HZ027 | a DOM field used outside an event, or wrong for this event | read `ui.dom.*` only in `ui.send` payloads |
 | HZ028 | `img` without width/height | add both |
+| HZ029 | a client component's module is missing, or a handler for an event it does not emit | create the module (`hozu add component … --client`); handle declared `emits` only |
 | HZ030 | `ui.html` of untrusted data | render text instead |
 | HZ031 | a literal not allowed by its schema | use an allowed value (the patch suggests one) |
-| HZ032 | internal link written as a string | `ui.link(route, params)` |
-| HZ033 | DOM text into an enum, number or boolean field | a `<select>` with enum options / `valueAsNumber` / `checked` |
+| HZ032 | internal link or form action written as a string | `ui.link(route, params)` / `ui.link(endpoint)` |
+| HZ033 | DOM text into an enum, number or boolean field | a `<select>`, radios or submit buttons with enum values; in a form, a flag through `ui.dom.formAll` and numbers parsed in the mutation input |
 | HZ034 | a state both handles and ignores an event | remove it from one of the two |
 | HZ035 | search schema is not a flat object of scalars with defaults | `z.object({ key: scalar.default(…) })` |
-| HZ036 | (warning) a form needs JavaScript | read its values with `ui.dom.form('name')` |
+| HZ036 | (warning) a form needs JavaScript | read its values with `ui.dom.form('name')` / `ui.dom.formAll('name')` |
 | HZ037 | a redirect is not a path, hides a page or another redirect, or targets an unknown route | change or remove the `from` key; point `to` at `ui.link(...)` |
 | HZ038 | `http.headers` sets a header the framework owns, or an invalid name/value | remove it (`cache-control` is derived; CSP is `createServer({ csp })`) |
 | HZ039 | `basePath` is not `''` or `/segment[/segment…]` | e.g. `'/shop'`, no trailing slash |
@@ -37,8 +38,34 @@ around the rule.
 | HZ041 | a machine uses a message, `ui.format` or `locale` | store a code in context; choose the message in the view |
 | 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 | `serve.ts` misses the widget bundle or the session store | add `widgets: await bundleWidgets(build)` / `session: sessionCookie(…)` |
-| HZ046 | an endpoint path is reserved, has params, or collides with a page, redirect or endpoint | use a static path such as `/api/…` (patch) |
+| 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 })` |
+| HZ046 | an endpoint path is reserved, has params or collides; an error without a status; a form posting to it with another method or an undeclared field | a static path such as `/api/…` (patch); map every error in `failed` |
 | 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 |
+| 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` |
+| HZ053 | (runtime) an endpoint answered `text/html`: a 500 | make it a `ui.page`; statuses and redirects go through `head.failed` |
+| HZ054 | `ui.dom.form` reads one value of a list field or of a repeated name | `ui.dom.formAll('name')` (patch) |
+| HZ055 | a form read names no control of the form | the name it suggests (patch), or add the control |
+| 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()` |
+| 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) |
+| HZ063 | (warning) as HZ055, in a form holding `ui.html`, a client component or another view | as HZ055 |
+| HZ064 | two contracts with identical IR | remove one (patch) |
+| HZ070 | a component's render references a declaration (event, query, route, message…) | pass a `Send` through `on`, an `Href` prop, text as a prop or slot |
+| HZ071 | a variant from data | make it a prop, styled through an attribute (`aria-pressed:`, `data-[x=y]:`) |
+| HZ072 | a caller's `class` sets a property the component owns | declare a variant; a one-off ends with `!` (snippet) |
+| HZ073 / HZ074 | `!` inside a component / a leading `!x` | remove it (patch in the tv config, snippet in the render) / write `x!` (patch) |
+| HZ075 | (warning) a caller's inherited class (colour, font) is hidden by an inner element | a variant, or style the inner element |
+| HZ076 | (warning) a component owns a margin | remove it (patch); outer spacing is the caller's |
+| HZ077 | (warning) `!` on a property the component does not own | remove the `!` (patch) |
+| HZ078 | the kit's `tv.ts` config differs from the design system | `hozu add kit <id> --sync` |
+| HZ079 | two classes of one element set the same property | the patch: a complementary toggle, or remove the one that never wins |
+| HZ080 | (warning) a `part()` view inlined by two features | the snippet: the same `ui.component` in a kit |
 | 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'`) |

package/skill/topics/endpoints.md

@@ -1,12 +1,24 @@
-# Endpoints (webhooks, JSON APIs, auth callbacks)
+# Endpoints (webhooks, JSON APIs, auth callbacks, downloads)
 
 ```ts
-export const orderHook = endpoint({ method: 'POST', path: '/api/hooks/order',
-  input: z.object({ id: z.string() }), output: z.object({ received: z.string() }) })   // exported from model.ts
-implement(orderHook, ({ id }, { request, session, setSession, env }) => ({ received: id }))   // in resolvers
+export const exportNotes = endpoint({ method: 'GET', path: '/api/export',        // exported from model.ts
+  input: z.object({ format: z.enum(['json', 'csv']).default('json') }), output: z.object({ notes: z.array(Note) }),
+  errors: { Unauthorized: z.object({ message: z.string() }) }, failed: { Unauthorized: 401 } })
+implement(exportNotes, (input, { session, fail }) =>                             // in the app's resolvers
+  session ? { notes: notesOf(session.user) } : fail('Unauthorized', { message: 'Sign in' }))
 ```
-- GET input comes from the query string, POST input from a JSON or form body; invalid input answers 400
-  `{ message, fields }`. The output is validated and sent as JSON.
-- `output: 'response'`: return a web `Response` yourself (redirects, headers); `setSession(value)` adds the cookie.
-- Paths are static and outside pages, redirects and `/_hozu/` (HZ046, with a patch). Cross-site browser POSTs are
-  rejected; server-to-server calls (no `Origin`) are accepted. `hozu get /api/x` tries one without a server.
+- GET input comes from the query string (coerced by the schema), POST input from a JSON or form body. Invalid input
+  answers 400 `{ error: 'Invalid', message, fields }`; `fail(name, payload)` answers `failed[name]` with
+  `{ error, message, fields? }` (statuses 400 401 403 404 409 410 422 429; every declared error is mapped, HZ046).
+- `output` is one of: a schema (validated, sent as JSON); `'redirect'`, returning `redirect(ui.link(route, params))`
+  from the context (303, with basePath); `'response'`, a web `Response` for files and protocol bodies that are
+  neither JSON nor HTML. A `text/html` response is a 500 with HZ053: a page is a `ui.page` with `head.failed`.
+- `input: 'raw'` (POST only) skips parsing and gives the resolver `bytes` (a `Uint8Array`), for signed webhooks.
+- `setSession(value)` works on GET too (auth callbacks); OIDC form_post callbacks use `output: 'redirect'`.
+- `invalidates: (input) => [itemsTag()]` refreshes like a mutation's when the endpoint succeeds. A GET endpoint with
+  `invalidates` is HZ062 (warning).
+- Links: `ui.link(getEndpoint, input)` is the URL of a GET endpoint (flat scalar input, HZ035);
+  `ui.form({ method: 'post', action: ui.link(postEndpoint) }, [...])` posts a native form to a POST endpoint, whose
+  input declares every field name (HZ046). Another feature links to it only when it is in `exports` and imported (HZ006).
+- Paths are static and outside pages, redirects and `/_hozu/` (HZ046, with a patch). Responses carry `nosniff` and a
+  referrer policy. Cross-site browser POSTs are rejected; server-to-server calls (no `Origin`) are accepted.

package/skill/topics/feature.md

@@ -0,0 +1,79 @@
+# A new feature: the files and a complete example
+
+Start with `npx hozu add feature <name> --page / --with auth,detail,toggle,filter,remove` and edit the texts it
+lists. It writes the files below and the first `hozu.lock.json`.
+
+## How it works
+- A feature is **declarations**: events, queries / mutations (the only side effects), one machine, views,
+  contracts. Builders record them as data (an IR) that is validated, then rendered on the server. Only views bound
+  to the machine ship JS.
+- **Callbacks are ordinary TypeScript** (`render`, `guard`, `assign`, `navigate`, `ui.each` / `ui.query`
+  callbacks): `===`, `!==`, `<`, `&&`, `||`, `!`, `??`, `c ? a : b`, template strings, `+`, `-`, `.length`, and in
+  `assign`, `ctx.x = v`, `ctx.n += 1`, `ctx.list.push(v)`, `ctx.list = ctx.list.filter((i) => i.id !== e.id)`.
+  Methods on data (`.map`, `.toUpperCase()`…) are not: use `ui.each` for lists and a `fn()` for computation.
+- 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.
+- Reusable view logic is a `part((…) => …)`, inlined where it is used (`hozu docs views`).
+
+## Files
+```
+hozu.config.ts  project({ schema, app, site, routes, pages, features })  routes.ts  route() declarations
+features/<name>/model.ts  schemas, events, effects, fns, machine        views.ts  views, contracts
+features/<name>/feature.ts  feature({ declarations: [model, views] })    app.ts  app({ resolvers })
+```
+Relative imports end in `.ts`.
+
+## A feature in one screen
+```ts
+// model.ts
+export const Item = z.object({ id: z.string(), title: z.string(), done: z.boolean() })
+export const Add = event({ payload: z.object({ title: z.string() }) })
+export const itemsTag = tag({ param: null })
+export const listItems = query({ input: z.object({}), output: z.array(Item), scope: 'public',
+  freshness: 'static', tags: () => [itemsTag()] })
+export const addItem = mutation({ input: z.object({ title: z.string().min(2, 'Too short') }), output: Item,
+  errors: { Duplicate: z.object({ title: z.string() }) }, invalidates: () => [itemsTag()] })
+export const items = machine({
+  context: z.object({ draft: z.string(), error: z.string().nullable() }),
+  initialContext: { draft: '', error: null },
+  initial: 'idle',
+  states: ({ ctx }) => ({
+    idle: { on: [on(Add, { target: 'adding', assign: (e) => { ctx.draft = e.title; ctx.error = null } })] },
+    adding: {
+      invoke: invoke(addItem, {
+        input: { title: ctx.draft },
+        done: { target: 'idle', assign: () => { ctx.draft = '' } },
+        failed: {
+          Duplicate: { target: 'idle', assign: () => { ctx.error = 'Already listed' } },
+          Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } },
+        },
+      }),
+    },
+  }),
+})
+// views.ts
+export const Board = ui.view({
+  machine: items,
+  render: ({ ctx, when }) =>
+    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']),
+      ]),
+      ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error]),
+      when(['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']) },
+      }),
+    ]),
+})
+// feature.ts
+import * as model from './model.ts'
+import * as views from './views.ts'
+export const todos = feature({ id: 'todos', intent: { summary: 'A to-do list' }, declarations: [model, views] })
+```
+Every declaration a listed module exports is registered under its name; schemas and helpers are ignored. Resolvers:
+`implement(addItem, ({ title }, { fail }) => exists ? fail('Duplicate', { title }) : save(title))`.

package/skill/topics/forms.md

@@ -1,8 +1,8 @@
 # Forms
 
-- **Works without JavaScript** when the submit payload reads only `ui.dom.form('name')`, literals, context, params
-  and search (else HZ036 warns): the server runs the same machine for a native post, then redirects or re-renders
-  with the result. Put every value the submit needs in a named field (a `<select name="kind">`).
+- **Works without JavaScript** when the submit payload reads only `ui.dom.form('name')`, `ui.dom.formAll('name')`,
+  literals, context, params and search (else HZ036 warns): the server runs the same machine for a native post, then
+  redirects or re-renders with the result. Put every value the submit needs in a named field (a `<select name="kind">`).
 ```ts
 ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) } }, [
   ui.label({ for: 'title' }, ['Title']),
@@ -22,3 +22,14 @@ ui.p({ id: 'title-error', class: 'text-sm text-rose-600' }, [ctx.fields.title])
 - **Per-item actions without JS:** wrap each button in its own small form.
 - **Enum from a select:** `ui.dom.form('kind')` or `ui.dom.value` fills an enum field only when every literal
   option value is a member (HZ033).
+- **Several values:** `ui.dom.formAll('ids')` is every value of the name in tree order (`[]` when none) for checkbox
+  groups, `select multiple` and controls inside `ui.each`, into a list field; `ui.dom.form(name)` is the first (HZ054).
+- **Which button:** give submit buttons `name` and a literal `value` and read `ui.dom.form('action')` in the form's
+  submit; JS and no-JS read the same value. Into an enum only when every submit button of the form has that name and
+  a member value, else make the field nullable (HZ033). No `on.click` on a submit button (HZ056).
+- **Controls outside the form** (forms cannot nest): `const bulk = ui.formRef()` at module level,
+  `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()`).
+- **Invalid without JS:** a native post whose payload or mutation input fails re-renders with 400 through
+  `failed.Invalid`, like the JS submit. Keep limits out of the event payload (HZ061).

package/skill/topics/http.md

@@ -12,6 +12,6 @@ http: {
   headers: [{ routes: 'all', set: { 'permissions-policy': 'camera=()' } }],   // not cache-control (HZ038)
 },
 ```
-Server options: `createServer({ build, styles, resolvers, session?, widgets?, onError?, csp?, images?, og?, preview? })`.
+Server options live in the app module: `app({ resolvers, session?, components?, onError?, csp?, og?, preview? })`.
 A strict CSP, `nosniff` and a cross-site POST check are on by default; `csp: { script: ['https://…'] }` adds sources.
 There are no rewrites: one URL has one owner. For your own HTTP routes, see `hozu docs endpoints`.

package/skill/topics/i18n.md

@@ -1,11 +1,16 @@
 # Languages
 
-- `site: { lang: 'en', locales: ['en', 'zh-TW'], … }`: every URL gets a locale prefix (`/en/posts/a`); routes and
-  `ui.link` stay locale-free; `/` redirects by `Accept-Language`. `<html lang>`, hreflang and the sitemap are derived.
-- `export const text = ui.messages('en', { en: { saved: '{count} saved' }, 'zh-TW': { saved: '已儲存 {count} 筆' } })`
+- **The URL holds the language.** Reload, sign-in and sign-out keep it, because every link and `navigate` resolves
+  `ui.link` in the page's locale. Do not add a cookie, a session field or a server rewrite for the language.
+- `site: { lang: 'en', locales: ['en', 'de'], … }`: the default locale keeps its URLs (`/posts/a`), the others are
+  prefixed (`/de/posts/a`); `/en/posts/a` answers 308 `/posts/a`. There is no `Accept-Language` redirect: a new visit
+  to an unprefixed URL shows `site.lang`. Routes and `ui.link` stay locale-free; contracts expect the default URLs.
+  `<html lang>`, hreflang and the sitemap are derived. A page route starting with a locale segment is HZ060.
+- A language switch is a link: `ui.a({ href: ui.alternate('de') }, ['Deutsch'])`, or
+  `locale === 'en' ? ui.alternate('de') : ui.alternate('en')`.
+- `export const text = ui.messages('en', { en: { saved: '{count} saved' }, de: { saved: '{count} gespeichert' } })`
   exported from a module the feature lists; use `text.title` or `text.saved({ count })` in views and `head.render`. Every locale
   needs every key with the same `{placeholders}` (HZ040). Plurals: `'{n, plural, =0 {none} one {# item} other {# items}}'`.
 - Machines never hold translated text (HZ041): store a code and choose the message in the view.
 - `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.alternate('zh-TW')` links the
-  current page in another language.
+  `ui.format.relative(n, 'day')`, `ui.format.list(xs)`. `locale` is in every view.

package/skill/topics/machine.md

@@ -33,7 +33,7 @@ export const m = machine({
   `ctx.list = ctx.list.filter((i) => i.id !== e.id)`. Values are event (`e`), result (`r`) or error fields,
   context, literals, operators and `fn()` calls.
 - **guard** returns a condition: comparisons, `&&`, `||`, `!`, or a boolean `fn()`.
-- **navigate** sends the browser to `ui.link(route, params, search)` after the transition.
+- **navigate** sends the browser to `ui.link(route, params, search?)` after the transition.
 - `done` and each `failed` entry take a state name, one transition, or a list of guarded transitions.
 - **Shared transitions:** `machine({ on })` entries are copied into every state that has no `invoke`, is not final,
   and neither handles nor ignores the event itself. Without `target` they stay in the state they fire in; one

package/skill/topics/pages.md

@@ -21,9 +21,10 @@ export default project({
     ui.page(itemPage, {
       views: [Detail],
       head: {
-        query: getItem,                                    // its failure sets the status (NotFound → 404)
+        query: getItem,
         input: (params) => ({ id: params.id }),
         render: (item) => ({ title: item.title, description: item.title, type: 'article' }),
+        failed: { NotFound: 404 },                         // every declared error of the query (HZ051)
       },
       entries: { query: listItems, input: {}, params: (item) => ({ id: item.id }) },   // sitemap + static export
     }),
@@ -32,8 +33,21 @@ export default project({
 })
 ```
 - `head.render` fields: `title`, `description`, `type` (`'website' | 'article'`), `image` (a URL, `ui.asset(...)`
-  or `ui.og({ title })`), `published`, `noindex`. `head.redirects: { Unauthorized: login }` maps errors to routes.
+  or `ui.og({ title })`), `published`, `noindex`.
+- `head.failed` maps each declared error of the head query to a route without params (303) or to `403`, `404` or
+  `410`: `failed: { Unauthorized: login, Forbidden: 403 }`. It is exhaustive (HZ051); `Unexpected` is always 500.
+  It maps declared errors only: a head query that always fails is not a redirect.
+- **Which redirect** (one per purpose):
+
+| Need | Form |
+|---|---|
+| a static path moved | `http.redirects` (`hozu docs http`) |
+| this visitor may not see the page | `head.failed` |
+| a decision on success, e.g. `/` by session | a GET endpoint with `output: 'redirect'` (`hozu docs endpoints`) |
+| after a machine transition | `navigate` |
+
+- A route no page renders is HZ052; link to an endpoint with `ui.link(endpoint, input)` instead.
 - 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>`). A view with a machine listed
-  on several pages, in the same order, keeps its DOM and state across links when it never reads `params` / `search`.
+- A page loads JS only when a machine-bound part renders on it (`hozu plan <route>`). 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.

package/skill/topics/patterns.md

@@ -45,7 +45,25 @@ ui.form({ on: { submit: ui.send(Toggle, { id: ui.dom.form('id') }) } }, [
 // machine: on(Toggle, { target: 'toggling', assign: (e) => { ctx.target = e.id } })
 // toggling: { invoke: invoke(toggleItem, { input: { id: ctx.target }, done: 'idle', failed: { Unexpected: 'idle' } }) }
 ```
-  Try it without a server: `hozu post / --field title=x --next 'POST / id=i1&@Done' --next /`.
+  Try it without a server: `hozu browse / --do 'fill Title=x' --do 'press Enter' --do 'click Done in "x"'`.
+- **Select many, then act** (bulk delete): checkboxes in the list join one form through a formRef; the invoke
+  state drops events, so the checkboxes are disabled while it runs:
+```ts
+const bulk = ui.formRef()   // module level; context { selected: z.array(z.string()), busy: z.boolean() }
+ui.form({ ref: bulk, on: { submit: ui.send(Bulk, { ids: ui.dom.formAll('ids'), action: ui.dom.form('action') }) } }, [
+  ui.button({ type: 'submit', name: 'action', value: 'delete' }, ['Delete selected']),
+  ui.button({ type: 'submit', name: 'action', value: 'pin' }, ['Pin selected']),
+])
+ui.each(items, 'id', (item) => ui.li({}, [ui.input({ type: 'checkbox', form: bulk, name: 'ids', value: item.id,
+  'aria-label': `Select ${item.text}`, checked: ctx.selected.includes(item.id), disabled: ctx.busy,
+  on: { change: ui.send(Select, { id: item.id, checked: ui.dom.checked }) } }), item.text]))
+// on(Select, { target: 'idle', guard: (e) => e.checked === true, assign: (e) => { ctx.selected.push(e.id) } }),
+// on(Select, { target: 'idle', assign: (e) => { ctx.selected = ctx.selected.filter((id) => id !== e.id) } }),
+// on(Bulk, { target: 'removingMany', guard: (e) => e.action === 'delete', assign: (e) => { ctx.selected = e.ids; ctx.busy = true } }),
+// removingMany: invoke(removeNotes, { input: { ids: ctx.selected }, done/failed: reset selected and busy })
+```
+  The mutation input holds the limit (`z.array(z.string()).min(1, 'Select at least one note')`). Reference app:
+  `examples/notes`.
 - **Sorted or pinned first:** sort in the resolver (the list query returns items in display order), or in a `fn`.
 - **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 }) }`.

package/skill/topics/recipes.md

@@ -33,7 +33,7 @@ Names follow `hozu add feature items`: `Item`, `NewItem`, `Add`, `addItem`, `ite
 - The new transitions only copy values, so they need no contract (the feature lists `model`, so both are registered).
 - **server:**
   `implement(clearDone, () => { const before = items.length; items.splice(0, items.length, ...items.filter((i) => !i.done)); return { removed: before - items.length } })`.
-- **Try it:** `hozu post / --button 'Clear done' --next /`.
+- **Try it:** `hozu browse / --do 'click Clear done'` (with and without JS).
 
 ## A field shown on the detail page
 In the detail view's `ready`: `ui.p({}, ['Priority: ', item.priority])`. The detail query already returns the whole

package/skill/topics/testing.md

@@ -1,21 +1,46 @@
 # Testing
 
-- **Without a server** (no need to start one): `hozu get /path --select 'button[aria-pressed=true]' --forms` and
-  `hozu post / --field title=A --next 'POST / @Delete' --next /`.
-  - `post` submits like a browser **without JavaScript** (a native form post), so it also checks no-JS behaviour.
-  - Each step prints its status, redirect and `set-cookie` attributes (`HttpOnly`, `SameSite`); the session cookie
-    is kept across `--next` steps. Two users: run two commands.
-  - Endpoints: `hozu get '/api/items?x=1'`.
-- **In a real browser, still without a server:** `hozu browse / --do 'fill Search=park' --do 'click Tech Park'`.
-  - It uses the installed Chrome / Chromium / Edge (`HOZU_CHROME=/path` to choose), loads the page, waits for
-    hydration and runs the steps in order: `fill <label>=<value>`, `select <label>=<option>`, `check <label>`,
-    `click <name>`, `press <key>`, `wait <ms>`, `goto <path>`. Labels and names are what a user reads (aria-label,
-    `<label>`, placeholder, button text, `title`).
-  - It prints the uncaught exceptions, `console.error`s and failed requests, every widget on the page (mounted,
-    failed, size, canvases), the visible text and `--select <css>` elements; exit code 1 when anything failed.
-  - `--screenshot shot.png` saves the viewport (open it to look); `--reduced-motion` emulates reduced motion.
-  - Use it once after client-side work (widgets, islands); `get` / `post` stay the fast checks.
-- In code: `const app = testApp({ build, resolvers })` from `@hozu/testing`; `await app.get('/')` →
-  `{ status, headers, html, text, payload }`; `app.post(path, fields)` submits a native form.
+- **Read a page without a server:** `hozu get /path --select 'button[aria-pressed=true]' --forms`.
+  - It prints the status, redirect, `set-cookie` attributes (`HttpOnly`, `SameSite`), title, alerts and visible text.
+  - `--forms` lists each form: fields with their defaults, checkbox / radio groups with every value (checked ones
+    marked ✓), controls that join through `form=` (marked `(form=)`), and submit buttons with their name and value.
+  - Endpoints: `hozu get '/api/items?x=1'`. It needs no browser.
+- **Drive the app in a real browser, still without a server:**
+  `hozu browse / --session '{"user":"ada"}' --do 'fill New note=Milk' --do 'press Enter' --do 'click Pin in "Milk"'`.
+  - It uses the installed Chrome / Chromium / Edge (`HOZU_CHROME=/path` to choose); without one it is a config
+    error. The app runs in-process, exactly as `npm start` serves it.
+  - `--js both` (the default) runs every step with JS and with JS switched off in the same Chrome, side by side. Use
+    `--js on` or `--js off` for one mode.
+  - Steps: `fill <label>=<value>` (a second fill of a repeated name fills the next field), `select <label>=<option>`,
+    `check <label>` / `uncheck <label>` (set the state), `click <name>` (a submit button posts with its name and
+    value), `submit "<form>"` (a form's `aria-label` or its submit button text), `press <key>`, `wait <ms>`,
+    `goto <path>`. Labels and names are what a user reads (aria-label, `<label>`, placeholder, button text,
+    `title`), or a field's `name`.
+  - A target may end with `in "<text>"`: the smallest list item, table row or form containing that text
+    (`click Delete in "Buy milk"`).
+  - To drive both modes with one step list, submit with `press Enter` or `submit "<form>"`. A step with no native
+    effect prints `js-only (<reason>)` in the off column, e.g. a `type=button` button.
+- **Other users, other pages, after a reload, after sign-out:** verify any such statement once, in one `browse`
+  chain with `--js both`.
+  - `--as <name>` starts an actor with its own browser; the steps after it are that actor's, and a later
+    `--as <name>` switches back. `--session` right after an `--as` signs that actor in. All actors share one app
+    (one data store, one session store), so what ada writes is what bob reads.
+  - Signing out and in again inside one actor's chain also works (`click Sign out`, `fill Name=bob`, `press Enter`).
+  - `hozu browse /notes --as ada --session '{"user":"ada"}' --as bob --session '{"user":"bob"}' --as ada --do 'click Share in "Milk"' --as bob --do 'goto /inbox'`
+- **The output** is small on purpose: per step, only the lines it added (`+`) or removed (`−`), once when both modes
+  agree and per mode where they differ; a navigation prints `→ <path>` and the new page's lines; a live update on
+  another actor's page prints under the step (`bob: + Milk`). A passing six-step run stays under 1.5 KB.
+  - `≠ DIFFERS` marks a step where both modes made a request and the resulting text differs: a no-JS/JS parity bug.
+  - Errors: uncaught exceptions, `console.error`s, CSP violations and failed requests, each with the page, the
+    resource type and the mode. A 400 re-render of an invalid native post is not an error.
+  - Exit code 1 when a step failed, the modes differ, a client component failed or any error was printed. `--json` has every
+    line; `--full` prints them all; `--select <css>`, `--screenshot shot.png` and `--reduced-motion` as before.
+  - It also prints the client components on the page (mounted, failed, size, canvases).
+- In code: `const page = await testApp(app).get('/')` from `@hozu/testing`, with `app` the default export of
+  `app.ts` → `{ status, headers, html, text, payload }`; `.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).
+- `hozu get`, `hozu browse` and `testApp` build the app module; a build with errors exits 1 (throws) and renders
+  nothing: run `hozu check`.
 - Vitest: add `hozuTransform()` from `@hozu/transform/vite` to `plugins`.
 - Browser tests: wait for `html[data-hozu-ready]` (set after hydration) before clicking.