create-hozu 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-hozu",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Create a Hozu app, set up for Claude Code or for agents that read AGENTS.md",
   "keywords": [
     "hozu",

package/skill/SKILL.md

@@ -20,12 +20,14 @@ Hozu is not in your training data; this file and `hozu docs <topic>` are the who
   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. Contracts are needed only where a transition decides (a guard, `navigate`, a `fn`).
+- 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.
 
 ## Files and commands
 ```
 hozu.config.ts  project({ schema, site, routes, pages, features })      routes.ts  route() declarations
-features/<name>/model.ts  schemas, events, effects, machine             views.ts  views, contracts, feature()
-features/<name>/server.ts  implement(...) resolvers                     serve.ts  createServer(...)
+features/<name>/model.ts  schemas, events, effects, fns, machine        views.ts  views, contracts
+features/<name>/feature.ts  feature({ declarations: [model, views] })    server.ts  implement(...) resolvers
 ```
 ```
 npx hozu check                      # after every edit: types, rules, contracts
@@ -84,10 +86,12 @@ export const Board = ui.view({
       }),
     ]),
 })
-export const todos = feature({ id: 'todos', intent: { summary: 'A to-do list' },
-  declarations: { Add, itemsTag, listItems, addItem, items, Board } })
+// 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 goes in `declarations` once, under its name. Resolvers:
+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))`.
 
 ## Topics (`hozu docs <topic>`)
@@ -100,7 +104,8 @@ Every declaration goes in `declarations` once, under its name. Resolvers:
 | routes, params, search, pages, `head`, 404, sitemap | `pages` |
 | forms without JS, field errors, selects | `forms` |
 | sign-in, sessions, per-user data | `auth` |
-| common UI: filters, empty states, per-item actions, load more, optimistic | `patterns` |
+| common UI: filters, search in the URL, modes, per-item actions, load more | `patterns` |
+| worked changes: enum field, bulk action, detail field / page | `recipes` |
 | webhooks and JSON APIs | `endpoints` |
 | browser APIs and DOM libraries (maps, charts) | `widgets` |
 | languages, env, HTTP, Markdown, images, preview, PWA, tests, deployment | `i18n`, `env`, `http`, `content`, `testing`, `deploy` |

package/skill/changing.md

@@ -5,65 +5,19 @@ 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.
+  Open only the lines the change touches. *model* is `model.ts` (schemas, events, effects, `fn`s, the machine),
+  *views* is `views.ts` (views, contracts); `feature.ts` lists both modules, so new exports need no registration.
+- The API is in `SKILL.md`. `hozu docs recipes` has worked steps for an enum field in the add form, a bulk action
+  button, a detail field and a detail page; `hozu docs <topic>` for anything 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
+## 2. What to touch
 | 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). |
+| 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 (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. If the page also filters as you type, `seed: ({ search }) => ({ key: search.key })` on the view and read `ctx.key` only. |
+| A per-item action stored on the server (pin, archive, star) | model: a field on the item, an event, a mutation that `invalidates` the list tag, `on(Event, { target: 'pinning', assign: (e) => { ctx.target = e.id } })` and a state with `invoke` → views: the per-item form from `hozu docs patterns` → server: store it and sort in the list resolver. These transitions only copy values: no contract. |
+| A control that works in every mode | `machine({ on: [...] })` instead of repeating it per state. |
+| New page | `routes.ts` → a view with `route` in `views.ts` → `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

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

@@ -0,0 +1,13 @@
+import { feature } from '@hozu/core'
+import * as model from './model.ts'
+import * as views from './views.ts'
+
+export const bookmarks = feature({
+  id: 'bookmarks',
+  intent: {
+    summary:
+      'A shared reading list: add bookmarks with a kind, mark them read, filter unread, one page each.',
+    invariants: ['Titles are unique, case-insensitive', 'New bookmarks are listed first'],
+  },
+  declarations: [model, views],
+})

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

@@ -1,10 +1,9 @@
-import { contract, feature, ui } from '@hozu/core'
+import { contract, ui } from '@hozu/core'
 import { bookmarkPage, home } from '../../routes.ts'
 import {
   Add,
   addBookmark,
   bookmarksMachine,
-  bookmarksTag,
   Draft,
   DUPLICATE,
   getBookmark,
@@ -210,35 +209,3 @@ export const toggleFails = contract(bookmarksMachine, {
   when: [{ failed: toggleRead, error: 'Unexpected', data: { message: 'offline' } }],
   expect: { state: 'idle', changes: { error: 'offline' } },
 })
-
-export const bookmarks = feature({
-  id: 'bookmarks',
-  intent: {
-    summary:
-      'A shared reading list: add bookmarks with a kind, mark them read, filter unread, one page each.',
-    invariants: ['Titles are unique, case-insensitive', 'New bookmarks are listed first'],
-  },
-  declarations: {
-    bookmarksTag,
-    Draft,
-    Add,
-    ToggleRead,
-    listBookmarks,
-    getBookmark,
-    addBookmark,
-    toggleRead,
-    visible,
-    isEmpty,
-    bookmarksMachine,
-    Board,
-    Detail,
-    typesDraft,
-    addsBookmark,
-    rejectsDuplicate,
-    rejectsInvalidTitle,
-    addFails,
-    togglesRead,
-    toggleMissing,
-    toggleFails,
-  },
-})

package/skill/example/hozu.config.ts

@@ -1,7 +1,8 @@
 import { project, ui } from '@hozu/core'
 import { zodAdapter } from '@hozu/schema-zod'
+import { bookmarks } from './features/bookmarks/feature.ts'
 import { getBookmark, listBookmarks } from './features/bookmarks/model.ts'
-import { Board, bookmarks, Detail } from './features/bookmarks/views.ts'
+import { Board, Detail } from './features/bookmarks/views.ts'
 import { bookmarkPage, home } from './routes.ts'
 
 export default project({

package/skill/topics/contracts.md

@@ -5,7 +5,7 @@ missing one, ready to paste). Transitions that only copy values need none: `hozu
 in readable form, and a change shows as HZ018 `was: … now: …` until `hozu check --update-lock` accepts it.
 ```ts
 export const addsValid = contract(m, {
-  given: { state: 'idle' },                          // context defaults to initialContext
+  given: { state: 'idle' },                          // context: initialContext; { touring: true } overrides fields
   when: [
     { send: Add, payload: { title: 'Milk' } },
     { done: addItem, result: { id: 'i9', title: 'Milk', done: false } },
@@ -17,5 +17,5 @@ export const addsValid = contract(m, {
   },
 })
 ```
-Add contracts to the feature's `declarations`. When a contract fails (HZ015), decide which is intended — the
+Export contracts from `views.ts` (or any module the feature lists). When a contract fails (HZ015), decide which is intended — the
 machine or the contract — before changing either.

package/skill/topics/data.md

@@ -15,12 +15,14 @@ export const addItem = mutation({
   errors: { Duplicate: z.object({ title: z.string() }) },          // optional: declared failures
   invalidates: () => [itemsTag()],                                  // refreshes queries with these tags
 })
-export const visible = fn({                   // computation: pure JS, self-contained (no imports, no helpers outside impl: HZ047)
+export const visible = fn({                   // computation: pure JS; may call const/function helpers of this module
   input: z.object({ items: z.array(Item), show: Show }), output: z.array(Item),
   impl: ({ items, show }) => items.filter((i) => show === 'all' || !i.done),
 })
 ```
 - Call a `fn` from views or machines with data: `ui.each(visible({ items, show: ctx.show }), 'id', …)`.
+- A `fn` body may call functions and JSON constants declared in the same module; they are sent to the browser with
+  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):

package/skill/topics/diagnostics.md

@@ -7,7 +7,7 @@ around the rule.
 |---|---|---|
 | HZ001 | state unreachable | add a transition to it or delete it |
 | HZ002 | event handled nowhere | handle it in a state or remove it |
-| HZ003 / HZ007 | unknown effect / reference | add it to `feature({ declarations })`, or fix the name (the patch suggests one) |
+| HZ003 / HZ007 | unknown effect / reference | 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 | `ignore: [Event]` in that state, or show the node only via `when` |
 | HZ006 | crossing a feature boundary | import the feature and use its `exports` |
@@ -39,5 +39,6 @@ around the rule.
 | 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) |
-| HZ047 | a `fn` body uses a helper or constant defined outside `impl` (it is sent to the browser as source) | write the helper inside `impl`, or pass the value as input |
+| 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 |
 | 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

@@ -2,7 +2,7 @@
 
 ```ts
 export const orderHook = endpoint({ method: 'POST', path: '/api/hooks/order',
-  input: z.object({ id: z.string() }), output: z.object({ received: z.string() }) })   // in declarations
+  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
 ```
 - GET input comes from the query string, POST input from a JSON or form body; invalid input answers 400

package/skill/topics/i18n.md

@@ -3,7 +3,7 @@
 - `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} 筆' } })`
-  in the feature's `declarations`; use `text.title` or `text.saved({ count })` in views and `head.render`. Every locale
+  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' })`,

package/skill/topics/machine.md

@@ -5,10 +5,10 @@ export const m = machine({
   context: z.object({ draft: z.string(), error: z.string().nullable(), target: z.string() }),
   initialContext: { draft: '', error: null, target: '' },
   initial: 'idle',
+  on: ({ ctx }) => [on(Draft, { assign: (e) => { ctx.draft = e.text } })],   // shared by every state without invoke
   states: ({ ctx }) => ({
     idle: {
       on: [
-        on(Draft, { target: 'idle', assign: (e) => { ctx.draft = e.text } }),
         on(Add, { target: 'adding', guard: (e) => e.title.length >= 2 }),   // first matching guard wins
         on(Add, { target: 'idle', assign: () => { ctx.error = 'Too short' } }),
         on(Remove, { target: 'removing', assign: (e) => { ctx.target = e.id } }),
@@ -35,6 +35,12 @@ export const m = machine({
 - **guard** returns a condition: comparisons, `&&`, `||`, `!`, or a boolean `fn()`.
 - **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
+  contract covers every copy.
+- **Start from the URL:** a view with a `route` may declare `seed: ({ params, search }) => ({ q: search.q })`; the
+  page's machine then starts with those context fields (server render, hydration and no-JS posts alike). One view
+  per page may seed a machine (HZ048).
 - A transition to the same state re-enters it and re-runs its `invoke`: do not handle the busy event in the busy
   state. Machines never hold translated text (store a code, choose the message in the view).
 - Events: `export const Add = event({ payload: z.object({ title: z.string() }) })`.

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') }) } }, [

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 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`.

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 */ ]),
 })
 ```
@@ -27,7 +28,8 @@ export const Board = ui.view({
 - **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' })`.
 - **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

@@ -5,7 +5,7 @@ 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,6 +19,8 @@ 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

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,6 +1,7 @@
 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({