create-hozu 0.4.2 → 0.5.0

package/skill/topics/contracts.md

@@ -0,0 +1,21 @@
+# 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.
+```ts
+export const addsValid = contract(m, {
+  given: { state: 'idle' },                          // context defaults to initialContext
+  when: [
+    { send: Add, payload: { title: 'Milk' } },
+    { done: addItem, result: { id: 'i9', title: 'Milk', done: false } },
+  ],                                                 // or { failed: addItem, error: 'Duplicate', data } / { elapse: ms }
+  expect: {
+    state: 'idle',
+    changes: { draft: '' },                          // only what changes; nested objects are patches
+    effects: [{ effect: addItem, input: { title: 'Milk' } }, { navigate: '/items/i9' }],  // default: none
+  },
+})
+```
+Add contracts to the feature's `declarations`. When a contract fails (HZ015), decide which is intended — the
+machine or the contract — before changing either.

package/skill/topics/data.md

@@ -0,0 +1,35 @@
+# Data: queries, mutations, tags, fn, resolvers
+
+```ts
+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'
+  tags: () => [itemsTag()],          // optional; (input) => [...]
+})
+export const getItem = query({ input: Key, output: Item, errors: { NotFound: Key }, scope: 'public',
+  freshness: 'static', tags: (k) => [itemTag(k.id)] })
+export const addItem = mutation({
+  input: z.object({ title: z.string().min(2, 'Use at least 2 characters') }), output: Item,
+  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 closures)
+  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', …)`.
+- 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):
+```ts
+export const createResolvers = () => 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

@@ -0,0 +1,12 @@
+# 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', … })`.
+- **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.

package/skill/{diagnostics.md → topics/diagnostics.md}

@@ -9,14 +9,14 @@ around the rule.
 | 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) |
 | 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 that does not handle it | `ignore: [Event]` in that state, or show the node only via `when` |
+| 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` |
 | HZ008 | a path does not exist in the schema | fix the property name |
 | HZ009 | a guardless transition shadows later ones | put guarded transitions first |
-| HZ014 | wrong builder output | follow the builder signature |
+| 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 without a contract | add the contract from the snippet |
-| HZ018 | behaviour changed without a contract change | update the contracts, then `--update-lock` |
+| 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 |
 | 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` |
@@ -36,4 +36,7 @@ around the rule.
 | HZ040 | a locale lacks a message, or uses other `{placeholders}` | add/translate the key in that locale |
 | HZ041 | a machine uses a message, `ui.format` or `locale` | store a code in context; choose the message in the view |
 | 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) |
 | 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

@@ -0,0 +1,12 @@
+# Endpoints (webhooks, JSON APIs, auth callbacks)
+
+```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
+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
+  `{ 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.

package/skill/topics/env.md

@@ -0,0 +1,5 @@
+# Environment
+
+`project({ env: { server: z.object({ DB_URL: z.string() }), public: z.object({ SUPPORT_EMAIL: z.string().email() }) } })`.
+Both are parsed at startup (defaults and `z.coerce` apply; a missing value stops startup). Resolvers read
+`ctx.env`; views read public values with `ui.env(PublicEnv).SUPPORT_EMAIL`. Machines cannot read env (HZ041).

package/skill/topics/forms.md

@@ -0,0 +1,24 @@
+# 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">`).
+```ts
+ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) } }, [
+  ui.label({ for: 'title' }, ['Title']),
+  ui.input({ id: 'title', name: 'title', required: true, minlength: 2, value: ctx.draft,
+    'aria-invalid': ctx.fields.title !== null, 'aria-describedby': 'title-error',
+    on: { input: ui.send(Draft, { text: ui.dom.value }) } }),
+  ui.select({ name: 'kind', 'aria-label': 'Kind' }, kinds.map((k) => ui.option({ value: k, selected: ctx.kind === k }, [k]))),
+  ui.button({ type: 'submit' }, ['Add']),
+])
+ui.p({ id: 'title-error', class: 'text-sm text-rose-600' }, [ctx.fields.title])
+```
+- **Field errors:** context `fields: z.object({ title: z.string().nullable() })`, reset on submit
+  (`ctx.fields = { title: null }`), and `failed.Invalid: { target: 'idle', assign: (e) => { ctx.fields = e.fields } }`.
+  Limits live in the mutation's input schema: `z.string().min(2, 'Use at least 2 characters')`.
+- **Server error:** a declared error sets `ctx.error`; show `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`.
+- **Clear after success:** bind `value: ctx.draft` and reset it in `done`.
+- **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).

package/skill/topics/http.md

@@ -0,0 +1,17 @@
+# HTTP
+
+Without `http`, the site is served at `/` without trailing slashes (`/about/` answers 308 → `/about`).
+```ts
+http: {
+  basePath: '/shop',                   // every URL and /_hozu/* move under it (HZ039)
+  trailingSlash: 'always',             // or 'never'; the other form answers 308
+  redirects: {                         // keyed by the old path; never a path a page owns (HZ037)
+    '/blog/:slug': { to: (p) => ui.link(post, { slug: p.slug }), permanent: true },
+    '/docs': { to: 'https://docs.example.com', permanent: false },
+  },
+  headers: [{ routes: 'all', set: { 'permissions-policy': 'camera=()' } }],   // not cache-control (HZ038)
+},
+```
+Server options: `createServer({ build, styles, resolvers, session?, widgets?, onError?, csp?, images?, 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

@@ -0,0 +1,11 @@
+# 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} 筆' } })`
+  in the feature's `declarations`; 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.

package/skill/topics/machine.md

@@ -0,0 +1,40 @@
+# Machine (one per feature)
+
+```ts
+export const m = machine({
+  context: z.object({ draft: z.string(), error: z.string().nullable(), target: z.string() }),
+  initialContext: { draft: '', error: null, target: '' },
+  initial: 'idle',
+  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 } }),
+      ],
+    },
+    adding: {                                   // runs addItem on entry; drops events it does not handle
+      invoke: invoke(addItem, {
+        input: { title: ctx.draft },
+        done: { target: 'idle', assign: () => { ctx.draft = '' }, navigate: (r) => ui.link(itemPage, { id: r.id }) },
+        failed: {                               // every declared error + Unexpected (+ optional Invalid)
+          Duplicate: { target: 'idle', assign: () => { ctx.error = 'Already exists' } },
+          Unexpected: { target: 'idle', assign: (e) => { ctx.error = e.message } },
+        },
+      }),
+    },
+    removing: { invoke: invoke(removeItem, { input: { id: ctx.target }, done: 'idle', failed: { Unexpected: 'idle' } }) },
+    flash: { after: [{ ms: 3000, target: 'idle' }], ignore: [Add] },    // timers; ignore only without invoke
+  }),
+})
+```
+- **assign** writes context: `ctx.x = v`, `ctx.n += 1`, `ctx.list.push(item)`,
+  `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.
+- `done` and each `failed` entry take a state name, one transition, or a list of guarded transitions.
+- 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/pages.md

@@ -0,0 +1,39 @@
+# Routes and pages
+
+```ts
+// routes.ts
+export const home = route({ path: '/', params: null, search: z.object({ show: Show.default('all') }) })
+export const itemPage = route({ path: '/items/:id', params: z.object({ id: z.string() }), search: null })
+export const docs = route({ path: '/docs/:path+', params: z.object({ path: z.array(z.string()).min(1) }), search: null })
+```
+- `:x` one segment, `:x?` optional (nullable), `:x+` / `:x*` one-or-more / zero-or-more (string[]) (HZ024).
+- `search`: flat scalars or enums, each with a default or nullable (HZ035). URLs are canonical (keys sorted,
+  defaults left out). Changing `search` is a navigation: a filter in the URL is a plain `ui.link`, no machine.
+
+```ts
+// hozu.config.ts
+export default project({
+  schema: zodAdapter, styles: new URL('./app.css', import.meta.url),
+  site: { url: 'https://example.com', name: 'Items', lang: 'en' },
+  routes: { home, itemPage }, notFound: missing,           // notFound / error: routes rendered for 404 / 500
+  pages: [
+    ui.page(home, { views: [Board], head: { render: () => ({ title: 'Items' }) } }),
+    ui.page(itemPage, {
+      views: [Detail],
+      head: {
+        query: getItem,                                    // its failure sets the status (NotFound → 404)
+        input: (params) => ({ id: params.id }),
+        render: (item) => ({ title: item.title, description: item.title, type: 'article' }),
+      },
+      entries: { query: listItems, input: {}, params: (item) => ({ id: item.id }) },   // sitemap + static export
+    }),
+  ],
+  features: [items],
+})
+```
+- `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.
+- 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`.

package/skill/topics/patterns.md

@@ -0,0 +1,45 @@
+# Common UI patterns
+
+Each pattern is complete here; there is no need to open other files.
+
+- **Busy state:** render every control once; the state with `invoke` drops repeated submits. Progress:
+  `when(['adding'], [ui.p({ 'aria-busy': 'true' }, ['Saving…'])])`. Do not duplicate controls under `when`.
+- **Optimistic item:** `when(['adding'], [ui.li({ class: 'opacity-50' }, [ctx.draft])])`; leaving the state removes it
+  and the refreshed query shows the real item.
+- **Filter and empty state** (in context): two `fn`s over the list:
+```ts
+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) })
+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) })
+// view
+isEmpty({ items, show: ctx.show })
+  ? ui.p({ class: 'text-slate-500' }, ['No items'])
+  : ui.ul({}, [ui.each(visible({ items, show: ctx.show }), 'id', (i) => ui.li({}, [i.title]))])
+```
+- **Search as you type:** context `search: z.string()`; `ui.input({ type: 'search', 'aria-label': 'Search', value:
+  ctx.search, on: { input: ui.send(Search, { text: ui.dom.value }) } })`; `on(Search, { target: 'idle', assign: (e) =>
+  { ctx.search = e.text } })`; filter with a `fn({ input: z.object({ items, text: z.string() }), … })`.
+- **Toggle buttons:** for each option of a constant list,
+  `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])`.
+- **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') }) } }, [
+  ui.input({ type: 'hidden', name: 'id', value: item.id }),
+  ui.button({ type: 'submit' }, [item.done ? 'Reopen' : 'Done']),
+])
+// 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 /`.
+- **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 }) }`.
+- **Detail page with a 404:** `hozu docs pages`.
+- **UI kept across links** (a cart, a player): list the same machine view on each page, in the same order.
+- **Load more:** context `{ cursors: [null], last: null }`;
+  `ui.each(ctx.cursors, null, (cursor) => ui.query(listPage, { cursor }, { ready: (page) => … }))`; on the last page
+  (`cursor === ctx.last && page.next !== null`) a sentinel `on: { visible: ui.send(More, { cursor: page.next }) }`;
+  `More` pushes the cursor, guarded by `e.cursor !== null && e.cursor !== ctx.last`.

package/skill/topics/testing.md

@@ -0,0 +1,12 @@
+# 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 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.
+- 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

@@ -0,0 +1,34 @@
+# Views
+
+```ts
+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
+  render: ({ ctx, when, params, search, locale }) => ui.main({ class: 'mx-auto max-w-xl' }, [ /* children */ ]),
+})
+```
+- **Elements:** `ui.<tag>(attrs, children)` for every HTML and SVG element; void tags (`input`, `img`) take only attrs.
+  Children are nodes, strings, numbers, data values, and `null` / `false` (render nothing).
+- **Attributes:** HTML names in lower case (`for`, `minlength`, `aria-pressed`, `data-x`), typed per tag. Values are
+  literals or data: `'aria-pressed': ctx.show === 'all'`, `title: ctx.error ?? 'OK'`.
+- **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')`.
+- **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` ``.
+- **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).
+- **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`.
+  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',
+  import.meta.url))`, `ui.window({ on })` / `ui.document({ on })`, `ui.embed(OtherView)`.

package/skill/topics/widgets.md

@@ -0,0 +1,25 @@
+# Widgets (browser APIs, DOM libraries)
+
+Start with `hozu add widget <feature> <Name>`: it writes the declaration, the client module, the `serve.ts` bundle
+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
+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
+```
+```ts
+// map.client.ts: a type-only import of the declaration
+import { implement } from '@hozu/core/widget'
+import type { Map } from './widgets.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() } }
+})
+```
+- `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
+  height class.

package/skill/patterns.md

@@ -1,57 +0,0 @@
-# Hozu patterns
-
-Patterns marked *(example)* are used in `example/features/bookmarks/model.ts` and `views.ts`, next to this file;
-read only the part you need.
-
-- **Form with a server-side error** *(example)*:
-  - `ui.form({ on: { submit: ui.send(Add, { title: ui.dom.form('title') }) } }, [label, input, button])`.
-  - The machine goes to `adding`, which invokes the mutation. `failed.Duplicate` sets `ctx.error`.
-  - Show the error with `ui.if(op.neq(ctx.error, null), [ui.p({ role: 'alert' }, [ctx.error])], [])`.
-  - To clear the input after success, bind `value: ctx.draft` and reset `draft` in `done`.
-- **Busy states (a mutation in flight)** *(example)*: render every control **once**. In each busy state, `ignore` the events
-  those controls send. Do not duplicate controls under `when`. Handling them there would re-enter the busy state
-  instead, and HZ005 would reject leaving them unhandled.
-- **Filtering and empty state** *(example)*: `ui.each(visible({ items, show: ctx.show }), 'id', …)` and
-  `ui.if(isEmpty({ items, show: ctx.show }), [ui.p({}, ['No items'])], [ui.ul(...)])`, both using `fn`s.
-- **Toggle buttons** (`aria-pressed`): `'aria-pressed': op.eq(ctx.show, s.value)` plus
-  `on: { click: ui.send(SetShow, { show: s.value }) }` for each option of a constant list.
-- **Per-item action** *(example)*:
-  - `ui.send(ToggleRead, { id: item.id })` → a `toggling` state that stores `ctx.target` and invokes the mutation
-    with `{ id: ctx.target }`.
-  - Label text by data: `ui.if(op.eq(item.read, true), ['Mark unread'], ['Mark read'])`.
-- **Select bound to an enum**:
-  `ui.select({ 'aria-label': 'Kind', on: { change: ui.send(PickKind, { kind: ui.dom.value }) } }, kinds.map((k) => ui.option({ value: k, selected: op.eq(ctx.kind, k) }, [k])))`,
-  where the event payload is `{ kind: Kind }`, the zod enum.
-- **Detail page with a 404** *(example)*: a view with `route: itemPage` and no machine,
-  `ui.query(getItem, { id: params.id }, { ready, pending: null, failed: { NotFound: () => ..., Unexpected: () => ... } })`,
-  plus `head.query: getItem`.
-- **Refresh after a mutation** *(example)*: tag the query, and list the tag in the mutation's `invalidates`. A mutation can
-  read only its input for tag params; use a list-wide tag when it affects many items.
-
-- **Filter in the URL** *(example)* (shareable, works without JS): declare `search` on the route, render the options as
-  `ui.link(home, null, { show: s.value })` links with `'aria-current': op.eq(search.show, s.value)`, and filter with
-  `fn`s over `search.show`. Only use machine context for filters that should not survive a reload.
-- **Go to what was just created** *(example)*: `done: [{ target: 'idle', navigate: (r) => ui.link(itemPage, { id: r.id }) }]`.
-- **No-JS form** *(example)*: every value the submit needs is a named field read with `ui.dom.form('name')`; the server runs the
-  machine for a native post. Per-item actions without JS: wrap the button in its own small form.
-- **UI that survives following a link** (a cart, a player, a chat box): list the same
-  view with a machine on every page that should keep it, in the same order, e.g. `views: [ProductGrid, CartPanel]`
-  and `views: [ProductDetail, CartPanel]`. Links between those pages then swap only the other views; the kept view's
-  DOM and machine state stay. Nothing to declare: a view is kept only if it never reads `params`/`search` (neither
-  in its tree nor in its machine). `hozu plan <route>` lists what is kept per target route. Style the loading
-  state with `html[data-hozu-navigating]`.
-- **Two languages**: `site.locales`, one `ui.messages` per feature, a language switcher of
-  `ui.a({ href: ui.alternate('en'), hreflang: 'en', lang: 'en' }, ['English'])` links, and `ui.format.date` for dates.
-- **Load more / infinite scroll**: context `{ cursors: [null], last: null }`;
-  `ui.each(ctx.cursors, null, (cursor) => ui.query(listPage, { cursor }, { ready: (page) => ... }))`; in the last page
-  (`op.and(op.eq(cursor, ctx.last), op.neq(page.next, null))`) render a button with `on: { click: ui.send(More,
-  { cursor: page.next }) }` and a sentinel `ui.div({ class: 'h-px', on: { visible: ui.send(More, …) } }, [])`.
-  `More` appends the cursor and sets `last`, guarded by `op.and(op.neq(ctx.last, e.cursor), op.neq(e.cursor, null))`
-  so a page loads once. It needs JS; a list that must work without JS pages through `search` links.
-- **Optimistic item** *(example)*: while the mutation runs, render the pending value from context
-  in the busy state: `when(['adding'], [ui.p({ class: 'opacity-50', 'aria-busy': 'true' }, ['Adding ', ctx.draft, '…'])])`.
-  Leaving the state (done or failed) removes it; the refreshed query shows the real item.
-- **Field errors** *(example)*: context `fields: z.object({ title: z.string().nullable(), kind:
-  z.string().nullable() })`, reset it on submit, `failed.Invalid: [{ target: 'idle', assign: (e) => [op.set(ctx.fields,
-  e.fields)] }]`, and render `ui.p({ id: 'title-error' }, [ctx.fields.title])` with `'aria-invalid': op.neq(ctx.fields.title,
-  null)` on the input. It also works without JS.

package/skill/reference.md

@@ -1,177 +0,0 @@
-# Hozu reference
-
-Open the section the task needs. The core API is in `SKILL.md`.
-
-## Routes
-```ts
-export const docs = route({ path: '/docs/:path+', params: z.object({ path: z.array(z.string()).min(1) }), search: null })
-```
-- `:x` one segment (string), `:x?` optional (nullable string), `:x+` one or more / `:x*` zero or more (string[])
-  (HZ024).
-- `search`: a flat object of scalars or enums, each with a default or nullable (HZ035); `null` = no query string.
-- URLs are canonical: keys sorted, defaults left out. `ui.link(home, null, { show: 'unread' })`. Changing `search`
-  is a navigation, so a filter in the URL is a plain link and needs no machine.
-
-## Views: events and DOM fields
-- Any DOM event name, plus `visible` (the element entered the viewport).
-- `ui.dom.value`: text. Into an enum field only from a `<select>` whose literal option values are all members
-  (HZ033).
-- `ui.dom.form('name')`: a named field of the submitted form (on `submit`; the browser runs `required` /
-  `minlength` first). Into an enum field when the name belongs to a `<select>` (or radios) in the form whose
-  literal option values are all members, so one submit carries a title and a priority.
-- `ui.dom.valueAsNumber` (number | null), `ui.dom.checked`, `ui.dom.key`, and similar event fields.
-- Also: `ui.html(value)` (trusted HTML from query data only, HZ030), `ui.asset(new URL('./x.png', import.meta.url))`,
-  `ui.window({ on })` / `ui.document({ on })` for global listeners, widgets (see Widgets) for browser APIs and
-  third-party DOM libraries.
-
-## Widgets (browser APIs, DOM libraries)
-There is no `widget` export: declare with `ui.widget`, place with `ui.use`, list the declaration in the feature's
-`declarations`, and implement it in a client module.
-```ts
-export const Copy = ui.widget({ tag: 'button', props: z.object({ text: z.string() }),
-  events: { copied: z.object({}) }, client: new URL('./copy.client.ts', import.meta.url), load: 'visible', wraps: true })
-ui.use(Copy, { props: { text: block.code }, on: { copied: () => ui.send(Copied, {}) }, class: 'btn' }, ['Copy'])
-```
-```ts
-// copy.client.ts: a type-only import of the declaration
-import { implement } from '@hozu/core/widget'
-import type { Copy } from './widgets.ts'
-export default implement<typeof Copy>(({ el, props, emit, signal }) => {
-  el.addEventListener('click', () => navigator.clipboard.writeText(props.text).then(() => emit('copied', {})), { signal })
-  return { update(next) { props = next } }
-})
-```
-`load`: `'eager' | 'visible' | 'idle'`; `wraps: true` keeps the children as server HTML.
-**Serving them is a separate step.** Run `npm install @hozu/bundle`, then pass `widgets: await bundleWidgets(build)`
-to `createServer` in `serve.ts` (and to `exportStatic`). Without it the server refuses to start; `hozu build` bundles
-widgets itself. HZ029 is a client module that does not bundle. A library's own CSS goes in `app.css`
-(`@import "leaflet/dist/leaflet.css";`), and a map or chart host needs a height class (`h-96`).
-
-## Forms without JavaScript
-A submit whose payload reads only `ui.dom.form('name')`, literals, context, params and search also works without JS
-(otherwise HZ036 warns). The server runs the same machine and mutation, then redirects (on `navigate`, or when the
-machine is back where it started) or re-renders the page with the result (for example an error alert). Put every
-value the submit needs in named fields: a `<select name="kind">`, not a separate change event.
-
-## Field errors (`Invalid`)
-Every mutation also has the framework error `Invalid` = `{ message, fields }`: one key per top-level input field
-(`string | null`). It is returned when the input fails its schema (put limits there:
-`z.string().min(2, 'Use at least 2 characters')`), and a resolver can return it:
-`fail('Invalid', { message, fields: { title: 'Already taken' } })`.
-- `failed.Invalid` is optional (without it, `Unexpected` handles it).
-- With it: `assign: (e) => [op.set(ctx.fields, e.fields)]`, and show `ctx.fields.title` under the input with
-  `'aria-invalid': op.neq(ctx.fields.title, null)`.
-- Never declare errors named `Invalid` or `Unexpected` yourself (HZ014).
-
-## Pages
-`ui.page(route, { views, head, entries?, assert? })`.
-- `head.render` returns `{ title, description?, type?: 'website' | 'article', image?, published?, noindex? }`.
-  `head.query` + `head.input: (params, locale) => …` load data for it; a failing head query sets the HTTP status
-  (NotFound → 404). `head.redirects` maps declared errors to routes.
-- `entries: { query, input, params: (item) => … }` lists the pages of a route with params for the sitemap.
-- `project({ notFound: route, error: route })` renders those pages for 404 / 500.
-- A view listed with a machine on several pages, in the same order, stays mounted when links move between them
-  (see `patterns.md`).
-- **JS per page is derived:** a page loads the client only when a machine-bound node renders on it. An island
-  inside `ui.each`, `ui.if`, `when` or a query branch loads it only on pages where it renders; `hozu plan <route>`
-  says `always` or `only when rendered`. Do not add views or flags to avoid JS.
-
-## Sessions
-- **Start from the scaffold:** `hozu add feature notes --page / --with auth` writes `features/account`
-  (sign-in page, sign-out, `me`), the session cookie in `serve.ts`, per-user resolvers, and a redirect to `/login`
-  when signed out. Replace the name-only sign-in with real credentials before production; set `SESSION_SECRET`
-  (and `SESSION_SECURE=true` behind HTTPS).
-- `project({ session: z.object({ user: z.string() }) })` declares the identity. Queries with `scope: 'user'` and
-  mutations receive `session`; public resolvers never do.
-- `createServer({ session: (request) => value })`, or `sessionCookie({ name, secret })` from
-  `@hozu/runtime-server` for a signed cookie. Mutations can call `setSession(value)`.
-
-## Languages (i18n)
-- `site: { lang: 'en', locales: ['en', 'zh-TW'], … }`: every URL gets a locale prefix (`/en/posts/a`). Routes and
-  `ui.link` stay locale-free; links keep the current locale. `/` and locale-less URLs redirect by
-  `Accept-Language`. `<html lang>`, hreflang, og:locale and the sitemap are derived.
-- Text: `export const text = ui.messages('en', { en: { saved: '{count} saved' }, 'zh-TW': { saved: '已儲存 {count} 筆' } })`,
-  added to the feature's `declarations`. 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}}'`; `select` also works.
-- Machines never hold translated text (HZ041): store a code (`'duplicate'`) and pick 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 scope and the second argument of `head.input`. `ui.alternate('zh-TW')` is the current
-  page in another locale.
-
-## Environment
-`project({ env: { server: z.object({ DB_URL: z.string() }), public: z.object({ SUPPORT_EMAIL: z.string().email() }) } })`.
-Both are parsed when the server starts (defaults and `z.coerce` apply; a missing value stops startup). Resolvers get
-`ctx.env` (server values). Views read public values with `ui.env(PublicEnv).SUPPORT_EMAIL`. Machines cannot read env
-(HZ041).
-
-## HTTP
-Without `http`, the site is served at `/` without trailing slashes (`/about/` answers 308 → `/about`).
-```ts
-http: {
-  basePath: '/shop',                   // every URL and /_hozu/* move under it (HZ039)
-  trailingSlash: 'always',             // or 'never'; the other form answers 308
-  redirects: {                         // keyed by the old path; never a path a page owns (HZ037)
-    '/blog/:slug': { to: (p) => ui.link(post, { slug: p.slug }), permanent: true },   // 308
-    '/docs': { to: 'https://docs.example.com', permanent: false },                     // 307
-  },
-  headers: [{ routes: 'all', set: { 'permissions-policy': 'camera=()' } }],   // or routes: [post]; not cache-control (HZ038)
-},
-```
-There are no rewrites: one URL has one owner.
-
-## Server options
-`createServer({ build, styles, resolvers, session?, onError?, csp?, images?, og?, preview? })` from
-`@hozu/adapter-node`.
-- `onError(error, { effect | path })` receives every unexpected failure.
-- A strict CSP, `nosniff` and a cross-site POST check are on by default (`csp` adds sources, e.g.
-  `{ script: ['https://analytics.example'] }`, or `false`).
-- Test a mutation with curl:
-  `curl -X POST localhost:4700/_hozu/effect -H 'content-type: application/json' -d '{"effect":"items.addItem","input":{"title":"x"},"keys":[]}'`.
-
-## Content, images, share images, fonts
-- **Markdown:** `@hozu/content` turns `content/posts/*.md` (YAML front matter checked by a schema) into
-  `{ slug, data, html, headings }`: `const posts = await loadCollection({ dir: new URL('./content/posts/', import.meta.url), schema })`
-  in `server.ts`, returned from ordinary query resolvers; render the body with `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` installed, pass `images: await optimizeImages(build)` to `createServer` (and
-  `hozu build` does it itself): raster assets get WebP `srcset` widths and `sizes`.
-- **Share images:** `head.render` → `image: ui.og({ title, subtitle })` renders a 1200×630 card; pass
-  `og: ogImage` (from `@hozu/image`) to `createServer`. On a static host, use a file instead:
-  `image: ui.asset(new URL('./share.png', import.meta.url))` (made absolute with `site.url`).
-- **Fonts:** a local `@font-face` gets a size-matched `"<Family> Fallback"` automatically.
-- **Page transitions:** the stylesheet turns on cross-document view transitions, so links between pages cross-fade
-  instead of flashing (no JS). Turn them off with `@view-transition { navigation: none; }` in `app.css`; style them
-  with `::view-transition-*`.
-
-## Preview (drafts)
-`createServer({ preview: { secret } })`; `GET /_hozu/preview?secret=…&path=/posts/a` turns preview on (a signed
-cookie), `/_hozu/preview/exit` turns it off. Resolvers get `ctx.preview`; preview responses are never cached and are
-noindex.
-
-## PWA and offline
-A web app manifest is derived from `site` (`name`, `themeColor`, `icon`). `site.offline: route` is a static page
-shown when the network is down; a service worker is generated (HZ043: no params, no per-request data).
-
-## Testing rendered pages
-`const app = testApp({ build, resolvers })` from `@hozu/testing`; `await app.get('/')` gives
-`{ status, headers, html, text, payload }`; `app.post(path, fields)` submits a native form. In a browser test (Playwright),
-wait for `html[data-hozu-ready]` before clicking: it is set when the page has hydrated.
-
-## Deployment
-`hozu build` writes `dist/public/` (static files for any host or CDN) and `dist/manifest.json`. On Node:
-`createServer({ build: buildProject(project, { manifest }), manifest, publicDir: 'dist/public', … })`. On Bun, Deno,
-Cloudflare Workers or Vercel the server is `createHandler({ build, manifest, resolvers, render })` from
-`@hozu/runtime-server` with `export default { fetch: handler.fetch }`, where
-`import * as render from './dist/server/render.js'` is the page code `hozu build` generates (edge runtimes cannot
-generate it at startup). Page cache and tag revalidation are per instance.
-A fully static site (GitHub Pages, any file host): `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.
-```ts
-import manifest from './dist/manifest.json' with { type: 'json' }
-import * as render from './dist/server/render.js'
-const handler = createHandler({ build: buildProject(project, { manifest }), manifest, render, resolvers: createResolvers() })
-export default { fetch: handler.fetch }
-```