create-hozu 0.3.0 → 0.4.1

package/package.json

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

package/skill/reference.md

@@ -21,9 +21,30 @@ export const docs = route({ path: '/docs/:path+', params: z.object({ path: z.arr
   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
+  `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. Serve with
+`widgets: await bundleWidgets(build)` from `@hozu/bundle` (and pass it to `exportStatic`); `hozu build` bundles
+them itself (HZ029 for a client module that does not bundle).
+
 ## 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
@@ -112,8 +133,12 @@ There are no rewrites: one URL has one owner.
   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`.
+  `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
@@ -136,6 +161,9 @@ Cloudflare Workers or Vercel the server is `createHandler({ build, manifest, res
 `@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'