@hozu/cli 0.18.2 → 0.20.0

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

@@ -0,0 +1,156 @@
+import { contract, ui } from '@hozu/core'
+import { bookmarkPage, home } from '../../routes.ts'
+import { Badge } from '../../ui/badge.ts'
+import { Button } from '../../ui/button.ts'
+import { Field } from '../../ui/field.ts'
+import { Input } from '../../ui/input.ts'
+import {
+  Add,
+  addBookmark,
+  bookmarksMachine,
+  Draft,
+  getBookmark,
+  isEmpty,
+  listBookmarks,
+  ToggleRead,
+  visible,
+} from './model.ts'
+
+const kinds = ['article', 'video', 'podcast'] as const
+const shows = [
+  { value: 'all', label: 'All' },
+  { value: 'unread', label: 'Unread' },
+] as const
+
+export const Board = ui.view({
+  machine: bookmarksMachine,
+  route: home,
+  render: ({ ctx, search, when }) =>
+    ui.main({ class: 'mx-auto max-w-xl space-y-6 px-4 py-12' }, [
+      ui.h1({ class: 'text-3xl font-bold' }, ['Bookmarks']),
+      ui.form(
+        {
+          class: 'flex items-start gap-2',
+          on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) },
+        },
+        [
+          ui.use(Field, {
+            props: { for: 'title', label: 'Title', error: ctx.fields.title, errorId: 'title-error' },
+            slots: {
+              control: ui.use(Input, {
+                props: {
+                  id: 'title',
+                  name: 'title',
+                  value: ctx.draft,
+                  required: true,
+                  minlength: 2,
+                  maxlength: 80,
+                  invalid: ctx.fields.title !== null,
+                  describedby: 'title-error',
+                },
+                on: { input: ui.send(Draft, { text: ui.dom.value }) },
+              }),
+            },
+          }),
+          ui.select(
+            { name: 'kind', 'aria-label': 'Kind', class: 'rounded border px-2 py-2' },
+            kinds.map((k) => ui.option({ value: k, selected: ctx.kind === k }, [k])),
+          ),
+          ui.use(Button, { props: { type: 'submit' } }, ['Add']),
+        ],
+      ),
+      ctx.error !== null && ui.p({ role: 'alert', class: 'text-rose-600' }, [ctx.error]),
+      when(
+        ['adding'],
+        [
+          ui.p({ class: 'rounded border px-4 py-3 opacity-50', 'aria-busy': 'true' }, [
+            'Adding ',
+            ctx.draft,
+            '…',
+          ]),
+        ],
+      ),
+      ui.nav(
+        { class: 'flex gap-2', 'aria-label': 'Show' },
+        shows.map((s) =>
+          ui.a(
+            {
+              href: ui.link(home, null, { show: s.value }),
+              'aria-current': search.show === s.value,
+              class:
+                'rounded-full border px-3 py-1 aria-[current=true]:bg-indigo-600 aria-[current=true]:text-white',
+            },
+            [s.label],
+          ),
+        ),
+      ),
+      ui.query(
+        listBookmarks,
+        {},
+        {
+          ready: (items) =>
+            isEmpty({ items, show: search.show })
+              ? ui.p({ class: 'text-slate-500' }, ['No bookmarks'])
+              : ui.ul({ class: 'divide-y rounded border' }, [
+                  ui.each(visible({ items, show: search.show }), 'id', (b) =>
+                    ui.li({ class: 'flex items-center gap-3 px-4 py-3' }, [
+                      ui.a({ href: ui.link(bookmarkPage, { id: b.id }), class: 'flex-1 underline' }, [
+                        b.title,
+                      ]),
+                      ui.use(Badge, {}, [b.kind]),
+                      ui.use(
+                        Button,
+                        { variant: { tone: 'quiet' }, on: { press: ui.send(ToggleRead, { id: b.id }) } },
+                        [b.read ? 'Mark unread' : 'Mark read'],
+                      ),
+                    ]),
+                  ),
+                ]),
+          pending: ui.p({}, ['Loading…']),
+          failed: { Unexpected: () => ui.p({ role: 'alert' }, ['Bookmarks are unavailable']) },
+        },
+      ),
+    ]),
+})
+
+export const Detail = ui.view({
+  route: bookmarkPage,
+  render: ({ params }) =>
+    ui.main({ class: 'mx-auto max-w-xl space-y-4 px-4 py-12' }, [
+      ui.query(
+        getBookmark,
+        { id: params.id },
+        {
+          ready: (b) =>
+            ui.article({}, [
+              ui.h1({ class: 'text-3xl font-bold' }, [b.title]),
+              ui.p({}, ['Kind: ', b.kind]),
+              ui.use(Badge, {}, [b.read ? 'Read' : 'Unread']),
+            ]),
+          pending: null,
+          failed: {
+            NotFound: () => ui.p({ role: 'alert' }, ['Bookmark not found']),
+            Unexpected: () => ui.p({ role: 'alert' }, ['Bookmark unavailable']),
+          },
+        },
+      ),
+      ui.a({ href: ui.link(home, null), class: 'underline' }, ['Back']),
+    ]),
+})
+
+export const addsBookmark = contract(bookmarksMachine, {
+  given: { state: 'idle' },
+  when: [
+    { send: Add, payload: { title: 'Hozu talk', kind: 'podcast' } },
+    { send: Draft, payload: { text: 'ignored while adding' } },
+    { done: addBookmark, result: { id: 'b3', title: 'Hozu talk', kind: 'podcast', read: false } },
+  ],
+  expect: {
+    state: 'idle',
+    changes: { kind: 'podcast' },
+    effects: [
+      { effect: addBookmark, input: { title: 'Hozu talk', kind: 'podcast' } },
+      { navigate: '/bookmarks/b3' },
+    ],
+  },
+})

package/skill/example/hozu.config.ts

@@ -0,0 +1,34 @@
+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, Detail } from './features/bookmarks/views.ts'
+import { bookmarkPage, home } from './routes.ts'
+import { kit as uiKit } from './ui/kit.ts'
+
+export default project({
+  schema: zodAdapter,
+  app: new URL('./app.ts', import.meta.url),
+  previews: new URL('./previews.ts', import.meta.url),
+  styles: new URL('./app.css', import.meta.url),
+  site: { url: 'http://localhost:3000', name: 'Bookmarks', lang: 'en' },
+  routes: { home, bookmarkPage },
+  pages: [
+    ui.page(home, {
+      views: [Board],
+      head: { render: () => ({ title: 'Bookmarks', description: 'A shared reading list.' }) },
+    }),
+    ui.page(bookmarkPage, {
+      views: [Detail],
+      head: {
+        query: getBookmark,
+        input: (params) => ({ id: params.id }),
+        failed: { NotFound: 404 },
+        render: (b) => ({ title: b.title, description: b.title, type: 'article' }),
+      },
+      entries: { query: listBookmarks, input: {}, params: (b) => ({ id: b.id }) },
+    }),
+  ],
+  kits: [uiKit],
+  features: [bookmarks],
+})

package/skill/example/previews.ts

@@ -0,0 +1,13 @@
+import { previews } from '@hozu/core/preview'
+import { listBookmarks } from './features/bookmarks/model.ts'
+import { home } from './routes.ts'
+import { Button } from './ui/button.ts'
+
+export default previews((p) => [
+  p.component(Button, 'Long label', {
+    variant: { tone: 'primary' },
+    children: 'Add it to the shared reading list',
+  }),
+  p.page(home, 'Empty list', [p.data(listBookmarks, [])]),
+  p.page(home, 'List failed', [p.fail(listBookmarks, 'Unexpected')]),
+])

package/skill/example/routes.ts

@@ -0,0 +1,11 @@
+import { route } from '@hozu/core'
+import { z } from 'zod'
+
+export const Show = z.enum(['all', 'unread'])
+
+export const home = route({ path: '/', params: null, search: z.object({ show: Show.default('all') }) })
+export const bookmarkPage = route({
+  path: '/bookmarks/:id',
+  params: z.object({ id: z.string() }),
+  search: null,
+})

package/skill/example/ui/badge.ts

@@ -0,0 +1,11 @@
+import { ui } from '@hozu/core'
+import { tv } from './tv.ts'
+
+const styles = tv({ base: 'rounded-full bg-slate-100 px-2 py-0.5 text-xs text-slate-600' })
+
+export const Badge = ui.component({
+  tag: 'span',
+  styles,
+  children: true,
+  render: ({ children }) => ui.span({}, children),
+})

package/skill/example/ui/button.ts

@@ -0,0 +1,23 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({
+  base: 'inline-flex items-center justify-center gap-2 rounded px-4 py-2 font-medium',
+  variants: {
+    tone: {
+      primary: 'bg-indigo-600 text-white hover:bg-indigo-700',
+      quiet: 'px-2 py-1 text-sm text-slate-600 hover:text-slate-900',
+    },
+  },
+  defaultVariants: { tone: 'primary' },
+})
+
+export const Button = ui.component({
+  tag: 'button',
+  styles,
+  props: z.object({ type: z.enum(['button', 'submit']).default('button') }),
+  children: true,
+  events: ['press'],
+  render: ({ props, children, on }) => ui.button({ type: props.type, on: { click: on.press } }, children),
+})

package/skill/example/ui/field.ts

@@ -0,0 +1,20 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({
+  slots: { base: 'flex-1 space-y-1', label: 'sr-only', error: 'text-sm text-rose-600' },
+})
+
+export const Field = ui.component({
+  tag: 'div',
+  styles,
+  props: z.object({ for: z.string(), label: z.string(), error: z.string().nullable(), errorId: z.string() }),
+  slots: ['control'],
+  render: ({ props, slots, classes }) =>
+    ui.div({}, [
+      ui.label({ for: props.for, class: classes.label }, [props.label]),
+      slots.control,
+      ui.p({ id: props.errorId, class: classes.error }, [props.error]),
+    ]),
+})

package/skill/example/ui/input.ts

@@ -0,0 +1,33 @@
+import { ui } from '@hozu/core'
+import { z } from 'zod'
+import { tv } from './tv.ts'
+
+const styles = tv({ base: 'w-full rounded border px-3 py-2 aria-invalid:border-rose-500' })
+
+export const Input = ui.component({
+  tag: 'input',
+  styles,
+  props: z.object({
+    id: z.string(),
+    name: z.string(),
+    value: z.string(),
+    required: z.boolean().default(false),
+    minlength: z.number().optional(),
+    maxlength: z.number().optional(),
+    invalid: z.boolean().default(false),
+    describedby: z.string().optional(),
+  }),
+  events: ['input'],
+  render: ({ props, on }) =>
+    ui.input({
+      id: props.id,
+      name: props.name,
+      value: props.value,
+      required: props.required,
+      minlength: props.minlength,
+      maxlength: props.maxlength,
+      'aria-invalid': props.invalid,
+      'aria-describedby': props.describedby,
+      on: { input: on.input },
+    }),
+})

package/skill/example/ui/kit.ts

@@ -0,0 +1,7 @@
+import { ui } from '@hozu/core'
+import * as badge from './badge.ts'
+import * as button from './button.ts'
+import * as field from './field.ts'
+import * as input from './input.ts'
+
+export const kit = ui.kit({ id: 'ui', components: [button, input, field, badge] })

package/skill/example/ui/tv.ts

@@ -0,0 +1,12 @@
+import { createTV } from '@hozu/variants'
+
+// hozu:variants-config ui
+const twMergeConfig = {
+  extend: {
+    theme: {},
+    classGroups: {},
+  },
+}
+// /hozu:variants-config
+
+export const tv = createTV({ twMergeConfig })

package/skill/topics/auth.md

@@ -0,0 +1,56 @@
+# Sign-in, sessions, who may read and change what
+
+- **Start:** `hozu add feature notes --page / --with auth` (sign-in page, sign-out, `me`); set `SESSION_SECRET`.
+- `project({ session: z.object({ user: z.string() }) })`. `scope: 'user'` queries and mutations get `session`;
+  a mutation calls `setSession(value)` (`null` signs out).
+- **Every server-run user query and mutation says who may run it**, like `runs` (HZ088):
+  - `access: 'signedIn'`: any signed-in visitor; the resolver reads that visitor's data by `session`.
+  - `access: { owner: { row: (n) => n.owner, session: (s) => s.user } }`: the framework checks the output. One row
+    that is not the visitor's is `Forbidden` (a missing owner on either side never matches); a list holding such
+    rows is HZ091 (the resolver read too much).
+  - On a mutation, `{ owner: { load: getNote, input: (i) => ({ id: i.id }), row: (n) => n.owner, session: (s) =>
+    s.user } }` reads the row and checks it before the resolver runs; if `load` fails for any reason (`NotFound`
+    too), the answer is `Forbidden` and the resolver does not run.
+  - `access: { allow: ({ session, input }) => session.role === 'admin' }`.
+  - `access: 'anyone'`: sign-in, a newsletter. On user data it is HZ090.
+- **Refused** is the framework error `Forbidden`, before the resolver runs: optional in `failed` (otherwise
+  `Unexpected`). A page answers 403, or maps it: `head: { query: me, …, failed: { Forbidden: login } }`.
+- Check it as two visitors: `hozu call <effect> --session '{"user":"bob"}'`, or in one chain: `hozu browse /
+  --as ada --session '{"user":"ada"}' --do 'remember note from li a @href' --as bob --session '{"user":"bob"}'
+  --do 'goto $note'` (bob gets 403). `post <path> a=1` forges a native post as the current actor.
+
+<!-- more -->
+
+## Details
+- The scaffold writes `features/account` (sign-in page, sign-out, `me`), per-user resolvers, and a redirect to
+  `/login` when signed out. Replace the name-only sign-in with real credentials before production; production
+  without `SESSION_SECRET` refuses to start.
+- Public queries never receive `session`.
+- Sessions live on the server: the default store is `memorySessions()` (from `@hozu/runtime-server`); the cookie holds
+  only an opaque, signed, HttpOnly id, so `setSession(null)` revokes it and the session never reaches browser
+  JavaScript. It is per process: a restart signs everyone out, and an edge or multi-instance deployment passes a
+  shared store explicitly (`createHandler({ session })`).
+- `setSession` also applies in a failing mutation (expiry: `setSession(null)` then `fail('Expired', …)`).
+- After a sign-in or sign-out the page's queries are re-read with the new session; nothing from the old one stays.
+- A role on top of sign-in: `'signedIn'` plus a declared error (`NotAdmin`) mapped to 403 keeps "signed out → login"
+  apart from "not allowed → 403" (`failed: { Forbidden: login, NotAdmin: 403 }`); `{ allow }` answers Forbidden for both.
+- `access` is recorded in `hozu.lock.json`, so a change to it is reviewed like a transition.
+- `owner` needs the row to carry its owner field (HZ088 otherwise): add it to the output, or use `'signedIn'` and
+  read only the visitor's rows. In production a list's foreign rows are dropped and logged once.
+- Public queries never see the session, and a browser-run effect is guarded by the API it calls: `access` there is
+  HZ089.
+- **A token that expires:** keep it and its expiry in the session, and refresh it in `app({ refreshSession: async
+  (session, { env }) => session.expires > Date.now() ? undefined : { ...session, token: await renew(session) } })`.
+  It runs once per request before any resolver reads the session (queries stay read-only); the new value replaces
+  the old one in place (the cookie stays), `null` signs out, `undefined` keeps it. Requests of one session in one process share one call
+  (and its result for ten seconds); a sign-out while it runs wins; a throw keeps the session and reaches `onError`. Do not keep tokens in module variables: a restart or a second
+  instance loses them.
+- Calling another API with a token: a token your server holds goes in the session and is read in a `runs: 'server'`
+  resolver; a token that lives in the browser (OIDC / SSO, `localStorage`) is read in a `runs: 'browser'` effect
+  (`hozu docs fetch`) and never reaches your server.
+- `SESSION_SECRET` is at least 32 characters: `openssl rand -hex 32`. Keep it in a git-ignored `.env` and list
+  it in `.env.example` (`npx hozu env --example`).
+- **A refused page** renders the page's views with status 403 (the `<title>` falls back to the site name). For a
+  page of its own, map `Forbidden` (or a declared error) to a route: `failed: { Forbidden: login }`.
+- **Order on a mutation:** the input schema first (`Invalid` with field errors), then access (`Forbidden`), then the
+  resolver.

package/skill/topics/components.md

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

package/skill/topics/content.md

@@ -0,0 +1,37 @@
+# Markdown, images, share images, fonts, preview, offline
+
+- **Markdown:** `npm install @hozu/content` (not in the scaffold), then in `app.ts`
+  `const posts = await loadCollection({ dir: new URL('./content/posts/', import.meta.url), schema })`: one
+  `{ slug, data, html, headings }` per `.md` file. Return them from query resolvers and render `ui.html(post.html)`.
+- **Images:** `ui.img({ src: ui.asset(new URL('./hero.jpg', import.meta.url)), alt, width, height })` (HZ028 without
+  dimensions).
+
+<!-- more -->
+
+- **Collections in detail:**
+  - `slug` is the file name without `.md`.
+  - Only the folder's own files are read, not sub-folders; entries come in file-name order (sort them in the
+    resolver).
+  - `data` is the front matter parsed as YAML 1.2 and checked against `schema`. An unquoted date such as
+    `2026-09-12` stays a string, so `z.iso.date()` fits.
+  - A front matter error or a schema mismatch throws with the file name at startup.
+  - There are no conventional fields: a draft flag or an excerpt is a field in your schema.
+  - `html` is GFM; headings get ids, listed in `headings`.
+  - Style it with your own CSS for the container (the `prose` class needs the Tailwind typography plugin in
+    `app.css`, otherwise HZ026).
+
+- **Images:** with `@hozu/image`, `hozu build` adds WebP `srcset` widths.
+- **Share images:** `head.render → image: ui.og({ title, subtitle })` (needs `app({ og: ogImage })` with `ogImage`
+  from `@hozu/image`); on a static host use `image: ui.asset(new URL('./share.png', import.meta.url))`.
+- **Fonts:** prefer local font files: a local `@font-face` gets a size-matched fallback automatically. A remote font
+  is `@import url('https://fonts.googleapis.com/css2?family=…');` in `app.css` (moved to the top of the output) plus
+  its CSP sources: `app({ csp: { style: ['https://fonts.googleapis.com'], font: ['https://fonts.gstatic.com'] } })`.
+- **Page transitions:** links cross-fade (CSS view transitions, no JS); turn off with
+  `@view-transition { navigation: none; }` in `app.css`.
+- **Preview:** `app({ preview: { secret } })`; `/_hozu/preview?secret=…&path=/posts/a` turns it on; resolvers
+  read `ctx.preview`; preview responses are never cached.
+- **Offline:** `site.offline: route` (a static page) makes a service worker (HZ043).
+- **One collection per language:** a folder per locale (`content/en`, `content/de`), loaded by the query for the
+  page's locale (`head.input`'s second argument).
+- **Images named in front matter** (`cover: night.png`): serve them with a GET endpoint (`output: 'response'`) that
+  reads only the files some entry lists. There is no `public/` folder served at the root.

package/skill/topics/contracts.md

@@ -0,0 +1,36 @@
+# Contracts
+
+A transition that **decides** (a guard, a `navigate`, a `fn()`, a comparison or a computing operator in its values)
+needs a contract; HZ016 prints each missing one, ready to paste:
+`contract(m, { given: { state }, when: [{ send: Event, payload }], expect: { state, changes, effects } })`
+(full example: see --more). Export it from `views.ts`. After a behaviour change, run `hozu check --update-lock`
+and list the accepted `now:` lines in your summary. When a contract fails (HZ015), decide which is intended before
+changing either.
+
+<!-- more -->
+
+- Computing operators: `+ - ?? ?: .length .includes`. Transitions that only copy values need no contract (a contract
+  there is HZ058).
+- `hozu.lock.json` records every transition readably and must equal the computed lock: any difference is HZ057
+  until `hozu check --update-lock` accepts it.
+- A deciding change also needs a contract that fails against the old behaviour (HZ018); renaming or copying a
+  contract does not count.
+- A transition that stops deciding (its guard or `navigate` removed) needs only the lock: `hozu check
+  --update-lock`, then delete the contracts HZ058 names.
+- A transition to `'previous'` needs the state it returns to: `given: { state: 'adding', previous: 'editing' }`.
+- Contracts may be exported from any module the feature lists. When one fails, the choice is between the machine
+  and the contract.
+```ts
+export const addsValid = contract(m, {
+  given: { state: 'idle' },                          // context: initialContext; { touring: true } overrides fields
+  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
+  },
+})
+```

package/skill/topics/data.md

@@ -0,0 +1,75 @@
+# Data: queries, mutations, tags, fn, resolvers
+
+**First: whose data is it?** It decides `runs`, `scope` and where it is stored. When the request does not say, ask.
+
+| The data | `runs` / `scope` | Stored in |
+|---|---|---|
+| the visitor's own, no sign-in (a watchlist, favourites, settings) | `'browser'` / `'user'` | `localStorage`, in `fetch.ts` (`hozu docs recipes`) |
+| a signed-in user's, on every device | `'server'` / `'user'` + `access` | the app's database |
+| everyone's (posts, a shared board) | `'server'` / `'public'` + a deliberate `access` | the app's database |
+| a public third-party API (quotes, weather) | `'either'` / `'public'` | nowhere: read it |
+
+The arrays in Hozu's examples and scaffolds are stand-ins that keep them short: one list for every visitor, gone on
+restart. Never ship one; replace it with the store above.
+
+```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' = the session's data (needs project({ session }))
+  freshness: 'static',              // | 'request' | { revalidate: s } | { swr: s } | 'live' | { poll: s }
+  tags: () => [itemsTag()],          // optional; (input) => [...]
+  runs: 'server',                   // where the implementation lives: 'server' | 'browser' | 'either' (required); hozu docs fetch
+})
+export const getItem = query({ input: Key, output: Item, errors: { NotFound: Key }, scope: 'public',
+  freshness: 'static', tags: (k) => [itemTag(k.id)], runs: 'server' })
+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
+  runs: 'server',
+  access: 'anyone',                 // who may run it (required on the server; user queries too): hozu docs auth
+})
+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),
+})
+```
+```ts
+export default app({ resolvers: resolvers(project, (implement) => [
+  implement(listItems, () => db.items.list()),                     // db: the app's database client
+  implement(getItem, async ({ id }, { fail }) => (await db.items.get(id)) ?? fail('NotFound', { id })),
+  implement(addItem, ({ title }, { fail, session }) => /* … */ ),
+]) })
+```
+- `runs` is required on every query and mutation. `'server'` resolvers live in `app.ts` (or `features/<name>/server.ts`)
+  and get the schema-parsed input; `'browser'` / `'either'` live in `fetch.ts` (`hozu docs fetch`).
+- **Query resolvers only read;** writes happen in mutation and endpoint resolvers (see --more).
+- User data (`scope: 'user'`) is `freshness: 'request'`, `'live'` or `{ poll }` only (HZ049); `'live'` needs tags (HZ050).
+- **Changes on its own** (quotes, a feed): `freshness: { poll: 30 }` reads it again every 30 s (5 to 86400) while a page
+  shows it, also from the browser. `'live'` is for data your own mutations change. A refresh the visitor controls
+  (a button, Pause / Resume) is `refresh: () => [tag()]` on a machine transition (`hozu docs machine`).
+- Call a `fn` from views or machines: `ui.each(visible({ items, show: ctx.show }), 'id', …)`.
+
+<!-- more -->
+
+## Details
+- 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.
+- Freshness describes how the data changes, not where it is read; choose it per query. `'static'` (with tags) is
+  for data only your own declared writers change; `'request'` reads every time it is needed (on the server per
+  request, in the browser on mount and on tags; a public one makes its page uncacheable). `'live'` is only for push
+  updates.
+- `invalidates` drives the refresh: after a mutation or endpoint, cached pages and entries with those tags are
+  dropped and the page's queries with those tags are re-read. `endpoint({ …, invalidates: (input) => [tag()] })`
+  applies when it succeeds (use POST; a GET write is HZ062).
+- Writes from outside (a webhook, a job): `await server.revalidate([itemsTag()])` → `{ entries, pages }`.
+- **Why queries only read:** a query that creates a row on read runs again on every request, on prefetch and after a
+  delete (the account comes back). Keep two helpers: `listOf(user)` returns the stored list or `[]` for queries;
+  `ownListOf(user)` creates it, for mutations only.
+- Resolvers in `features/<name>/server.ts` (from the scaffold) are spread into `app.ts`; the input they get has
+  defaults and transforms applied.
+- Every mutation also has `Invalid` = `{ message, fields }` (input failing its schema, or
+  `fail('Invalid', { message, fields: { title: 'Taken' } })`); never declare `Invalid` or `Unexpected` yourself.