create-hozu 0.1.0

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

@@ -0,0 +1,129 @@
+import { event, fn, invoke, machine, mutation, on, op, query, tag, ui } from '@hozu/core'
+import { z } from 'zod'
+import { bookmarkPage, Show } from '../../routes.ts'
+
+export const Kind = z.enum(['article', 'video', 'podcast'])
+export const Bookmark = z.object({ id: z.string(), title: z.string(), kind: Kind, read: z.boolean() })
+const Bookmarks = z.array(Bookmark)
+const BookmarkKey = z.object({ id: z.string() })
+const NewBookmark = z.object({
+  title: z.string().min(2, 'Use at least 2 characters').max(80, 'Use at most 80 characters'),
+  kind: Kind,
+})
+
+export const Draft = event({ payload: z.object({ text: z.string() }) })
+export const Add = event({ payload: z.object({ title: z.string(), kind: Kind }) })
+export const ToggleRead = event({ payload: BookmarkKey })
+
+export const bookmarksTag = tag({ param: null })
+
+export const listBookmarks = query({
+  input: z.object({}),
+  output: Bookmarks,
+  scope: 'public',
+  freshness: 'static',
+  tags: () => [bookmarksTag()],
+})
+
+export const getBookmark = query({
+  input: BookmarkKey,
+  output: Bookmark,
+  errors: { NotFound: BookmarkKey },
+  scope: 'public',
+  freshness: 'static',
+  tags: () => [bookmarksTag()],
+})
+
+export const addBookmark = mutation({
+  input: NewBookmark,
+  output: Bookmark,
+  errors: { Duplicate: z.object({ title: z.string() }) },
+  invalidates: () => [bookmarksTag()],
+})
+
+export const toggleRead = mutation({
+  input: BookmarkKey,
+  output: Bookmark,
+  errors: { NotFound: BookmarkKey },
+  invalidates: () => [bookmarksTag()],
+})
+
+const Visible = z.object({ items: Bookmarks, show: Show })
+
+export const visible = fn({
+  input: Visible,
+  output: Bookmarks,
+  impl: ({ items, show }) => items.filter((b) => show === 'all' || !b.read),
+})
+
+export const isEmpty = fn({
+  input: Visible,
+  output: z.boolean(),
+  impl: ({ items, show }) => !items.some((b) => show === 'all' || !b.read),
+})
+
+export const DUPLICATE = 'This bookmark already exists'
+
+export const bookmarksMachine = machine({
+  context: z.object({
+    draft: z.string(),
+    kind: Kind,
+    target: z.string(),
+    error: z.string().nullable(),
+    fields: z.object({ title: z.string().nullable(), kind: z.string().nullable() }),
+  }),
+  initialContext: {
+    draft: '',
+    kind: 'article',
+    target: '',
+    error: null,
+    fields: { title: null, kind: null },
+  },
+  initial: 'idle',
+  states: ({ ctx }) => ({
+    idle: {
+      on: [
+        on(Draft, { target: 'idle', assign: (e) => [op.set(ctx.draft, e.text)] }),
+        on(Add, {
+          target: 'adding',
+          assign: (e) => [
+            op.set(ctx.draft, e.title),
+            op.set(ctx.kind, e.kind),
+            op.set(ctx.error, null),
+            op.set(ctx.fields, { title: null, kind: null }),
+          ],
+        }),
+        on(ToggleRead, { target: 'toggling', assign: (e) => [op.set(ctx.target, e.id)] }),
+      ],
+    },
+    adding: {
+      ignore: [Draft, Add, ToggleRead],
+      invoke: invoke(addBookmark, {
+        input: { title: ctx.draft, kind: ctx.kind },
+        done: [
+          {
+            target: 'idle',
+            assign: () => [op.set(ctx.draft, '')],
+            navigate: (b) => ui.link(bookmarkPage, { id: b.id }),
+          },
+        ],
+        failed: {
+          Duplicate: [{ target: 'idle', assign: () => [op.set(ctx.error, DUPLICATE)] }],
+          Invalid: [{ target: 'idle', assign: (e) => [op.set(ctx.fields, e.fields)] }],
+          Unexpected: [{ target: 'idle', assign: (e) => [op.set(ctx.error, e.message)] }],
+        },
+      }),
+    },
+    toggling: {
+      ignore: [Draft, Add, ToggleRead],
+      invoke: invoke(toggleRead, {
+        input: { id: ctx.target },
+        done: [{ target: 'idle' }],
+        failed: {
+          NotFound: [{ target: 'idle' }],
+          Unexpected: [{ target: 'idle', assign: (e) => [op.set(ctx.error, e.message)] }],
+        },
+      }),
+    },
+  }),
+})

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

@@ -0,0 +1,248 @@
+import { contract, feature, op, ui } from '@hozu/core'
+import { bookmarkPage, home } from '../../routes.ts'
+import {
+  Add,
+  addBookmark,
+  bookmarksMachine,
+  bookmarksTag,
+  Draft,
+  DUPLICATE,
+  getBookmark,
+  isEmpty,
+  listBookmarks,
+  ToggleRead,
+  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 gap-2',
+          on: { submit: ui.send(Add, { title: ui.dom.form('title'), kind: ui.dom.form('kind') }) },
+        },
+        [
+          ui.label({ for: 'title', class: 'sr-only' }, ['Title']),
+          ui.input({
+            id: 'title',
+            name: 'title',
+            required: true,
+            minlength: 2,
+            maxlength: 80,
+            value: ctx.draft,
+            'aria-invalid': op.neq(ctx.fields.title, null),
+            'aria-describedby': 'title-error',
+            class: 'flex-1 rounded border px-3 py-2',
+            on: { input: ui.send(Draft, { text: ui.dom.value }) },
+          }),
+          ui.select(
+            { name: 'kind', 'aria-label': 'Kind', class: 'rounded border px-2' },
+            kinds.map((k) => ui.option({ value: k, selected: op.eq(ctx.kind, k) }, [k])),
+          ),
+          ui.button({ type: 'submit', class: 'rounded bg-indigo-600 px-4 py-2 text-white' }, ['Add']),
+        ],
+      ),
+      ui.p({ id: 'title-error', class: 'text-sm text-rose-600' }, [ctx.fields.title]),
+      ui.if(op.neq(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': op.eq(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) =>
+            ui.if(
+              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.span({ class: 'text-xs text-slate-500' }, [b.kind]),
+                      ui.button(
+                        {
+                          type: 'button',
+                          class: 'text-sm',
+                          on: { click: ui.send(ToggleRead, { id: b.id }) },
+                        },
+                        [ui.if(op.eq(b.read, true), ['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.p({}, [ui.if(op.eq(b.read, true), ['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, null), class: 'underline' }, ['Back']),
+    ]),
+})
+
+export const typesDraft = contract(bookmarksMachine, {
+  given: { state: 'idle' },
+  when: [{ send: Draft, payload: { text: 'Hozu' } }],
+  expect: { state: 'idle', changes: { draft: 'Hozu' } },
+})
+
+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' },
+    ],
+  },
+})
+
+export const rejectsDuplicate = contract(bookmarksMachine, {
+  given: { state: 'adding' },
+  when: [{ failed: addBookmark, error: 'Duplicate', data: { title: 'Hozu talk' } }],
+  expect: { state: 'idle', changes: { error: DUPLICATE } },
+})
+
+export const rejectsInvalidTitle = contract(bookmarksMachine, {
+  given: { state: 'adding' },
+  when: [
+    {
+      failed: addBookmark,
+      error: 'Invalid',
+      data: {
+        message: 'title: Use at least 2 characters',
+        fields: { title: 'Use at least 2 characters', kind: null },
+      },
+    },
+  ],
+  expect: { state: 'idle', changes: { fields: { title: 'Use at least 2 characters' } } },
+})
+
+export const addFails = contract(bookmarksMachine, {
+  given: { state: 'adding' },
+  when: [{ failed: addBookmark, error: 'Unexpected', data: { message: 'offline' } }],
+  expect: { state: 'idle', changes: { error: 'offline' } },
+})
+
+export const togglesRead = contract(bookmarksMachine, {
+  given: { state: 'idle' },
+  when: [
+    { send: ToggleRead, payload: { id: 'b1' } },
+    { done: toggleRead, result: { id: 'b1', title: 'A', kind: 'article', read: true } },
+  ],
+  expect: {
+    state: 'idle',
+    changes: { target: 'b1' },
+    effects: [{ effect: toggleRead, input: { id: 'b1' } }],
+  },
+})
+
+export const toggleMissing = contract(bookmarksMachine, {
+  given: { state: 'toggling' },
+  when: [{ failed: toggleRead, error: 'NotFound', data: { id: 'b9' } }],
+  expect: { state: 'idle' },
+})
+
+export const toggleFails = contract(bookmarksMachine, {
+  given: { state: 'toggling' },
+  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

@@ -0,0 +1,28 @@
+import { project, ui } from '@hozu/core'
+import { zodAdapter } from '@hozu/schema-zod'
+import { getBookmark, listBookmarks } from './features/bookmarks/model.ts'
+import { Board, bookmarks, Detail } from './features/bookmarks/views.ts'
+import { bookmarkPage, home } from './routes.ts'
+
+export default project({
+  schema: zodAdapter,
+  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 }),
+        render: (b) => ({ title: b.title, description: b.title, type: 'article' }),
+      },
+      entries: { query: listBookmarks, input: {}, params: (b) => ({ id: b.id }) },
+    }),
+  ],
+  features: [bookmarks],
+})

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/serve.ts

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

package/skill/example/server.ts

@@ -0,0 +1,34 @@
+import { resolvers } from '@hozu/data'
+import { addBookmark, getBookmark, listBookmarks, toggleRead } from './features/bookmarks/model.ts'
+import project from './hozu.config.ts'
+
+type Kind = 'article' | 'video' | 'podcast'
+
+export function createResolvers() {
+  const items = [
+    { id: 'b1', title: 'Closed-world UI', kind: 'article' as Kind, read: false },
+    { id: 'b2', title: 'Islands explained', kind: 'video' as Kind, read: true },
+  ]
+  let seq = items.length
+  return resolvers(project, (implement) => [
+    implement(listBookmarks, () => items.map((b) => ({ ...b }))),
+    implement(getBookmark, ({ id }, { fail }) => {
+      const b = items.find((x) => x.id === id)
+      return b ? { ...b } : fail('NotFound', { id })
+    }),
+    implement(addBookmark, ({ title, kind }, { fail }) => {
+      const clean = title.trim()
+      if (items.some((b) => b.title.toLowerCase() === clean.toLowerCase()))
+        return fail('Duplicate', { title: clean })
+      const b = { id: `b${++seq}`, title: clean, kind, read: false }
+      items.unshift(b)
+      return { ...b }
+    }),
+    implement(toggleRead, ({ id }, { fail }) => {
+      const b = items.find((x) => x.id === id)
+      if (!b) return fail('NotFound', { id })
+      b.read = !b.read
+      return { ...b }
+    }),
+  ])
+}

package/skill/patterns.md

@@ -0,0 +1,56 @@
+# Hozu patterns
+
+Patterns marked *(example)* are used in `example/`, next to this file.
+
+- **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

@@ -0,0 +1,139 @@
+# 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 (`ui.widget` / `ui.use`) for
+  third-party DOM libraries.
+
+## 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`).
+
+## Sessions
+- `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`.
+- **Fonts:** a local `@font-face` gets a size-matched `"<Family> Fallback"` automatically.
+
+## 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.
+
+## 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.
+```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 }
+```

package/templates/app/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";