create-hozu 0.6.0 → 0.8.0

package/skill/topics/patterns.md

@@ -6,12 +6,13 @@ Each pattern is complete here; there is no need to open other files.
   `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
   and the refreshed query shows the real item.
-- **Filter and empty state** (in context): two `fn`s over the list:
+- **Filter and empty state** (in context): one helper, two `fn`s over the list:
 ```ts
+const shows = (i: Item, show: Show) => show === 'all' || (show === 'done') === i.done   // sent with the fns
 export const visible = fn({ input: z.object({ items: z.array(Item), show: Show }), output: z.array(Item),
-  impl: ({ items, show }) => items.filter((i) => show === 'all' || (show === 'done') === i.done) })
+  impl: ({ items, show }) => items.filter((i) => shows(i, show)) })
 export const isEmpty = fn({ input: z.object({ items: z.array(Item), show: Show }), output: z.boolean(),
-  impl: ({ items, show }) => !items.some((i) => show === 'all' || (show === 'done') === i.done) })
+  impl: ({ items, show }) => !items.some((i) => shows(i, show)) })
 // view
 isEmpty({ items, show: ctx.show })
   ? ui.p({ class: 'text-slate-500' }, ['No items'])
@@ -24,6 +25,17 @@ isEmpty({ items, show: ctx.show })
   `ui.button({ type: 'button', 'aria-pressed': ctx.show === s.value, on: { click: ui.send(SetShow, { show: s.value }) } }, [s.label])`.
 - **Filter in the URL** (shareable, no JS): `search` on the route, options as
   `ui.a({ href: ui.link(home, null, { show: s.value }), 'aria-current': search.show === s.value }, [s.label])`.
+- **In the URL and as you type** (`/?q=park` works without JS, typing filters live): seed the machine from the URL
+  and read only the context. A GET form with `name="q"` submits it without JS.
+```ts
+export const Board = ui.view({ machine: m, route: home, seed: ({ search }) => ({ q: search.q, district: search.district }),
+  render: ({ ctx }) => ui.form({ method: 'get' }, [
+    ui.input({ type: 'search', name: 'q', 'aria-label': 'Search', value: ctx.q, on: { input: ui.send(Search, { q: ui.dom.value }) } }),
+    /* … */ ui.each(visible({ items, q: ctx.q, district: ctx.district }), 'id', (s) => …) ]) })
+```
+- **A mode with shared controls** (a tour, an edit mode): put what every mode handles the same way in
+  `machine({ on: [on(Search, { assign: (e) => { ctx.q = e.q } })] })` (no `target`: stays in its state); each state
+  lists only what differs.
 - **Per-item action** (toggle, pin, delete): each item gets its own small form, so it works without JS:
 ```ts
 ui.form({ on: { submit: ui.send(Toggle, { id: ui.dom.form('id') }) } }, [
@@ -33,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

@@ -0,0 +1,48 @@
+# Recipes for common changes
+
+Names follow `hozu add feature items`: `Item`, `NewItem`, `Add`, `addItem`, `itemsMachine`, `ItemsBoard`.
+
+## A field chosen in the add form (an enum)
+- **model:**
+  - `export const Priority = z.enum(['low', 'normal', 'high'])`;
+  - add `priority: Priority` to `Item`, `NewItem` and the `Add` payload;
+  - context: `priority: Priority`, with `priority: 'normal'` in `initialContext`;
+  - `fields` gets `priority: z.string().nullable()`, with `priority: null` in `initialContext` and in the `Add`
+    assign that resets it;
+  - the `Add` assign also gets `ctx.priority = e.priority`, and the add `invoke` input becomes
+    `{ title: ctx.draft, priority: ctx.priority }`.
+- **views:**
+  - the form's submit sends `{ title: ui.dom.form('title'), priority: ui.dom.form('priority') }`;
+  - inside the form add
+    `ui.select({ name: 'priority', 'aria-label': 'Priority', class: 'rounded border px-2' }, ['low', 'normal', 'high'].map((p) => ui.option({ value: p, selected: p === 'normal' }, [p])))`;
+  - in the item: `ui.span({ class: 'text-xs' }, [item.priority])`.
+- **Contracts:** if the app has contracts that send `Add` or return an item, add `priority` to their payloads,
+  inputs and results. These transitions only copy values, so they need no new contract.
+- **server:** store `priority` (seed items included) and return it.
+
+## An action button that works on many items (e.g. "Clear done")
+- **model:**
+  - `export const ClearDone = event({ payload: z.object({}) })`;
+  - `export const clearDone = mutation({ input: z.object({}), output: z.object({ removed: z.number() }), invalidates: () => [itemsTag()] })`;
+  - in `idle`: `on(ClearDone, { target: 'clearing', assign: () => { ctx.error = null } })`;
+  - a state
+    `clearing: { invoke: invoke(clearDone, { input: {}, done: 'idle', failed: { Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } } } }) }`
+    (busy states drop events they do not handle, so no `ignore`).
+- **views:** the control
+  `ui.form({ on: { submit: ui.send(ClearDone, {}) } }, [ui.button({ type: 'submit', class: 'text-sm underline' }, ['Clear done'])])`.
+- 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 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
+item.
+
+## A detail page, when the feature has none
+Run a fresh scaffold into a scratch app with `--with detail`, and copy the parts it prints:
+- the route with params;
+- the `get` query and its resolver;
+- the detail view;
+- the link in the list;
+- `ui.page(...)` with `head` and `entries`.

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 widget 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 widgets 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.

package/skill/topics/views.md

@@ -4,6 +4,7 @@
 export const Board = ui.view({
   machine: m,        // optional: without it, no ctx / when / events, and 0 JS
   route: home,       // optional: render gets { params, search } typed by the route
+  seed: ({ search }) => ({ q: search.q }),   // optional, with machine + route: context fields from the URL
   render: ({ ctx, when, params, search, locale }) => ui.main({ class: 'mx-auto max-w-xl' }, [ /* children */ ]),
 })
 ```
@@ -14,20 +15,24 @@ export const Board = ui.view({
 - **Classes:** `class` is a static string of Tailwind classes that must exist (HZ026). Conditional classes:
   `toggle: { 'bg-indigo-600 text-white': ctx.tab === t }`. CSS variables: `vars: { '--hue': item.hue }`. No `style`.
 - **Conditions:** `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`, `item.done ? 'done' : 'open'`,
-  `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`. With an enter/leave animation:
-  `ui.if(cond, [then], [else], 'fade')`.
+  `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`; a branch may be a list: `open ? [a, b] : null`, also as what a query branch or an each item returns.
+  With an enter/leave animation: `ui.if(cond, [then], [else], 'fade')` (the motion name is required).
 - **By machine state:** `when(['adding', 'saving'], [ui.p({}, ['Saving…'])])`.
 - **Lists:** `ui.each(items, 'id', (item) => ui.li({}, [item.title]))`; `ui.each(tags, null, (t) => …)` for primitives.
   Never `.map` over data (only over constants: `['a', 'b'].map((k) => ui.option({ value: k }, [k]))`).
 - **Text:** template strings work: `` `${n} items` ``.
+- **Reuse:** `export const row = part((item: Item) => ui.li({}, [item.done ? 'Done' : item.title]))`, called as
+  `row(item)`; it is inlined, so the IR equals the inline form. A plain function that receives data is HZ059.
 - **Events:** `on: { click: ui.send(Event, payload) }`, any DOM event name plus `visible` (entered the viewport).
-  Payload fields: literals, data, `ui.dom.value`, `ui.dom.form('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`,
-  `ui.dom.key`. `ui.dom.value` / `ui.dom.form` fill an enum field only from a `<select>` or radios whose literal
-  option values are all members (HZ033).
+  Payload fields: literals, data, `ui.dom.value`, `ui.dom.form('name')` / `ui.dom.formAll('name')` (submit; `hozu docs
+  forms`), `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`. `ui.dom.value` / `ui.dom.form` fill an enum field
+  only from a `<select>`, radios or submit buttons whose literal values are all members (HZ033).
 - **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032). The third
-  argument exists only when the route declares `search`: `ui.link(home, null, { show: 'done' })`.
+  argument is optional and exists only when the route declares `search`: omitted means every default, and a search
+  lists only the fields that differ: `ui.link(home, null, { show: 'done' })`.
 - **Data:** `ui.query(listItems, input, { ready: (items) => …, pending: ui.p({}, ['Loading…']), failed: { NotFound:
-  () => …, Unexpected: () => … } })`; `pending` is optional, `failed` lists every declared error plus `Unexpected`.
+  () => …, Unexpected: () => … } })`; `pending` is optional, `failed` lists every declared error plus `Unexpected`; a branch may return `null` to render
+  nothing.
   Server-fetched data is sent with the page and never fetched again; after a mutation, queries whose tags it
   invalidates refresh in place.
 - **Also:** `ui.html(post.html)` (trusted HTML from query data only, HZ030), `ui.asset(new URL('./x.png',

package/skill/topics/widgets.md

@@ -1,11 +1,11 @@
 # Widgets (browser APIs, DOM libraries)
 
-Start with `hozu add widget <feature> <Name>`: it writes the declaration, the client module, the `serve.ts` bundle
+Start with `hozu add widget <feature> <Name>`: it writes the declaration, the client module, the bundle in `app.ts`
 and the `@hozu/bundle` dependency. There is no `widget` export; the pieces are:
 ```ts
 export const Map = ui.widget({ tag: 'div', props: z.object({ lat: z.number(), lng: z.number() }),
   events: { picked: z.object({ id: z.string() }) }, client: new URL('./map.client.ts', import.meta.url),
-  load: 'visible', wraps: false })                                      // in declarations
+  load: 'visible', wraps: false })                                      // widgets.ts; the feature lists the module
 ui.use(Map, { props: { lat: ctx.lat, lng: ctx.lng }, on: { picked: (d) => ui.send(Pick, { id: d.id }) },
   class: 'h-96 w-full' }, [])                                           // in a view
 ```
@@ -19,9 +19,11 @@ export default implement<typeof Map>(({ el, props, emit, signal }) => {
   return { update(next) { map.move(next) }, destroy() { map.remove() } }
 })
 ```
+- `on` is optional. `ui.use` takes no other attributes: put a role or label on a wrapping element,
+  `ui.section({ role: 'region', 'aria-label': 'Map' }, [ui.use(Map, { props }, [])])`.
 - `load`: `'eager' | 'visible' | 'idle'`; `wraps: true` keeps the children as server HTML.
-- `serve.ts` passes `widgets: await bundleWidgets(build)` (the server refuses to start without it; `hozu build` bundles
-  them itself). A library's CSS goes in `app.css` (`@import "leaflet/dist/leaflet.css";`); a map or chart host needs a
+- `app.ts` passes `widgets: bundleWidgets` to `app()` (`import { bundleWidgets } from '@hozu/bundle'`; without it
+  the server refuses to start and `hozu check` reports HZ045; `hozu build` bundles them itself). A library's CSS goes in `app.css` (`@import "leaflet/dist/leaflet.css";`); a map or chart host needs a
   height class.
 - Check it with `hozu browse /` (no server): each widget is listed as mounted / failed / not mounted with its size
   and canvases, next to any error it threw. A mounted host carries `data-hozu-widget="<feature>.<Name>"` and

package/templates/app/app.ts

@@ -0,0 +1,7 @@
+import { resolvers } from '@hozu/data'
+import { app } from '@hozu/runtime-server'
+import project from './hozu.config.ts'
+
+export default app({
+  resolvers: resolvers(project, () => []),
+})

package/templates/app/features/site/feature.ts

@@ -0,0 +1,8 @@
+import { feature } from '@hozu/core'
+import * as views from './views.ts'
+
+export const site = feature({
+  id: 'site',
+  intent: { summary: 'The start page' },
+  declarations: [views],
+})

package/templates/app/features/site/views.ts

@@ -1,4 +1,4 @@
-import { feature, ui } from '@hozu/core'
+import { ui } from '@hozu/core'
 
 export const Home = ui.view({
   render: () =>
@@ -7,9 +7,3 @@ export const Home = ui.view({
       ui.p({ class: 'text-slate-600' }, ['Edit features/site/views.ts to get started.']),
     ]),
 })
-
-export const site = feature({
-  id: 'site',
-  intent: { summary: 'The start page' },
-  declarations: { Home },
-})

package/templates/app/hozu.config.ts

@@ -1,11 +1,13 @@
 import { project, ui } from '@hozu/core'
 import { zodAdapter } from '@hozu/schema-zod'
-import { Home, site } from './features/site/views.ts'
+import { site } from './features/site/feature.ts'
+import { Home } from './features/site/views.ts'
 import { home } from './routes.ts'
 
 export default project({
   schema: zodAdapter,
   styles: new URL('./app.css', import.meta.url),
+  app: new URL('./app.ts', import.meta.url),
   site: { url: 'http://localhost:3000', name: '__NAME__', lang: 'en' },
   routes: { home },
   pages: [ui.page(home, { views: [Home], head: { render: () => ({ title: '__NAME__' }) } })],

package/templates/guide.md

@@ -3,24 +3,12 @@
 A web app built with Hozu (`@hozu/*`). Hozu is not in your training data.
 
 ## Before writing code
-- __READ__
-- Changing existing code: read `__SKILL__/changing.md` first.
+- __READ__ It has the change loop, the commands and the rules no diagnostic checks.
 - The files in `__SKILL__/` are the whole API. Do not read the framework source in `node_modules/@hozu`.
-
-## The loop
-```
-__RUN__ hozu add feature tasks --page / --with detail,toggle,filter,remove   # then edit the texts it lists
-                                          # add auth to the list for sign-in and per-user data
-__RUN__ hozu map                           # outline of the app with file:line, before a change
-__RUN__ hozu check                         # after every change: types, rules, contracts
-__RUN__ hozu check --update-lock           # only to accept a clean, intended behaviour change
-__RUN__ hozu get / --select button --forms  # try pages without a server: text, attributes, forms
-__RUN__ hozu post / --field title=Ship --next /   # submit a form like a browser
-__RUN__ hozu browse / --do 'click Save'     # real browser, no server: errors, widgets, text after steps
-```
 __NOTE__
 ## Rules
 - After `hozu add feature`, do not print the generated files: edit the texts it lists; `hozu map` shows the rest.
 - Apply the fix each diagnostic gives; do not work around a rule.
-- Every behaviour change comes with a contract change.
-- Do not edit `__SKILL__/`: `__RUN__ hozu skill` rewrites it for the installed Hozu version.
+- `__RUN__ hozu get` and `__RUN__ hozu browse` run the same app as `npm start`; do not start a server to check.
+- Do not edit `__SKILL__/` or the text between the `hozu` markers: `__RUN__ hozu skill` rewrites both for the
+  installed Hozu version.

package/skill/changing.md

@@ -1,91 +0,0 @@
-# Changing a Hozu app
-
-Keep the loop short: map once, edit everything, check once, verify once.
-
-## 1. Read
-- The change request.
-- `pnpm exec hozu map`: every route, query, mutation, event, state, view and contract, each with its `file:line`.
-  Open only the lines the change touches. Below, *model* is where the app keeps schemas, events, effects and
-  the machine (`model.ts`), and *views* where it keeps views, contracts and `feature()`.
-- The API is in `SKILL.md`. Use a recipe below when one fits; run `hozu docs <topic>` only for
-  something else.
-
-## 2. Recipes
-Names follow `hozu add feature items`: `Item`, `NewItem`, `Add`, `addItem`, `itemsMachine`, `ItemsBoard`.
-
-### A field chosen in the add form (an enum)
-- **model:**
-  - `export const Priority = z.enum(['low', 'normal', 'high'])`;
-  - add `priority: Priority` to `Item`, `NewItem` and the `Add` payload;
-  - context: `priority: Priority`, with `priority: 'normal'` in `initialContext`;
-  - `fields` gets `priority: z.string().nullable()`, with `priority: null` in `initialContext` and in the `Add`
-    assign that resets it;
-  - the `Add` assign also gets `ctx.priority = e.priority`, and the add `invoke` input becomes
-    `{ title: ctx.draft, priority: ctx.priority }`.
-- **views:**
-  - the form's submit sends `{ title: ui.dom.form('title'), priority: ui.dom.form('priority') }`;
-  - inside the form add
-    `ui.select({ name: 'priority', 'aria-label': 'Priority', class: 'rounded border px-2' }, ['low', 'normal', 'high'].map((p) => ui.option({ value: p, selected: p === 'normal' }, [p])))`;
-  - in the item: `ui.span({ class: 'text-xs' }, [item.priority])`.
-- **Contracts:** if the app has contracts that send `Add` or return an item, add `priority` to their payloads,
-  inputs and results. These transitions only copy values, so they need no new contract.
-- **server:** store `priority` (seed items included) and return it.
-
-### An action button that works on many items (e.g. "Clear done")
-- **model:**
-  - `export const ClearDone = event({ payload: z.object({}) })`;
-  - `export const clearDone = mutation({ input: z.object({}), output: z.object({ removed: z.number() }), invalidates: () => [itemsTag()] })`;
-  - in `idle`: `on(ClearDone, { target: 'clearing', assign: () => { ctx.error = null } })`;
-  - a state
-    `clearing: { invoke: invoke(clearDone, { input: {}, done: 'idle', failed: { Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } } } }) }`
-    (busy states drop events they do not handle, so no `ignore`).
-- **views:** the control
-  `ui.form({ on: { submit: ui.send(ClearDone, {}) } }, [ui.button({ type: 'submit', class: 'text-sm underline' }, ['Clear done'])])`.
-- Add `ClearDone` and `clearDone` to `declarations`. The new transitions only copy values, so they need no contract.
-- **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 /`.
-
-### 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
-item.
-
-### A detail page, when the feature has none
-Run a fresh scaffold into a scratch app with `--with detail`, and copy the parts it prints:
-- the route with params;
-- the `get` query and its resolver;
-- the detail view;
-- the link in the list;
-- `ui.page(...)` with `head` and `entries`.
-
-### Other changes
-| Change | Touch |
-|---|---|
-| New UI-only state (a tab) | model: the context field and its initial value, an event, an `on` whose `assign` sets it → views: the control, the event in `declarations` (no contract: it only copies a value). |
-| Filter / sort / page in the URL | the route's `search` schema (with a default) → links with `ui.link(route, params, { key: value })` → read `search.key` in the view. No machine change. |
-| New page | `routes.ts` → a view with `route`, in `declarations` → `ui.page(...)` in `hozu.config.ts` (`head`, and `entries` when the route has params). |
-
-Whenever the machine changes:
-- A transition that decides something (a guard, `navigate`, or a `fn` in its values) needs a contract; HZ016
-  prints each missing one ready to paste. Transitions that only copy values are reviewed through the lock.
-- States with `invoke` drop unhandled events by themselves. Other states must handle or `ignore` every event their
-  visible controls send; HZ005 prints the missing entries.
-
-## 3. Check (once, after all edits)
-```
-pnpm exec hozu check
-```
-Fix what it reports. When the behaviour change is intended, run `pnpm exec hozu check --update-lock`: HZ018 shows
-each changed transition as `was: … now: …`, and accepting it updates the lock.
-
-## 4. Verify (once, no server needed)
-- **Pages:** `pnpm exec hozu get / /items/i1` prints the status, title, alerts and visible text.
-- **Attributes and forms:** `--select button` (or `'[role=alert]'`, `a[href]`, `#id`) prints elements with their
-  attributes, e.g. `aria-pressed`; `--forms` lists each form's fields and buttons. Never start a server for this.
-- **Forms:** `pnpm exec hozu post / --field title=A --field priority=high --next /items` fills the form like a
-  browser (other fields keep their defaults). It follows the redirect, then runs the next steps in the same
-  process.
-- **Chaining:** chain what must share data, e.g. `--next 'POST / title=a'` (fields as `a=1&b=2`) or
-  `--next /items/i3`.
-- **A form with only a button:** `--button 'Clear done'`, or `--next 'POST / @Clear done'`. With one form per item,
-  `--field id=t2` picks the item's form.

package/skill/example/serve.ts

@@ -1,14 +0,0 @@
-import { createServer } from '@hozu/adapter-node'
-import { buildProject } from '@hozu/core/ir'
-import { compileStyles } from '@hozu/css'
-import project from './hozu.config.ts'
-import { createResolvers } from './server.ts'
-
-const port = Number(process.env.PORT ?? 3000)
-const build = buildProject(project, { sources: false })
-
-createServer({
-  build,
-  styles: await compileStyles(build),
-  resolvers: createResolvers(),
-}).listen(port, () => console.log(`Bookmarks on http://localhost:${port}`))

package/templates/app/serve.ts

@@ -1,14 +0,0 @@
-import { createServer } from '@hozu/adapter-node'
-import { buildProject } from '@hozu/core/ir'
-import { compileStyles } from '@hozu/css'
-import project from './hozu.config.ts'
-import { createResolvers } from './server.ts'
-
-const port = Number(process.env.PORT ?? 3000)
-const build = buildProject(project, { sources: false })
-
-createServer({
-  build,
-  styles: await compileStyles(build),
-  resolvers: createResolvers(),
-}).listen(port, () => console.log(`__NAME__ on http://localhost:${port}`))

package/templates/app/server.ts

@@ -1,6 +0,0 @@
-import { resolvers } from '@hozu/data'
-import project from './hozu.config.ts'
-
-export function createResolvers() {
-  return resolvers(project, () => [])
-}