ferrovue 0.5.0 → 0.6.0

package/README.md

@@ -56,10 +56,10 @@ crate that includes it needs **edition 2024**.
 |---|---|---|
 | `components` | yes | Directory of `.vue` files to compile |
 | `out` | yes | Directory the Rust modules are written to. **Everything in it is replaced.** |
-| `routes` | no | JSON file listing the app's routes: each a vue-router path, or `{ "path", "name", "children" }`. Needed for `<RouterLink>`, `<RouterView>` and `useRoute()` |
+| `routes` | no | JSON file listing the app's routes: each a vue-router path, or `{ "path", "name", "children" }`. Or `{ "pages": "client/pages" }`: a folder of pages, whose file names give the routes as vue-router's file-based routing reads them (`index.vue`, `[id].vue`, `[[id]].vue`, `[...path].vue`, `(group)` folders, a `name.vue` beside `name/` as its layout), each page compiled as a component. Needed for `<RouterLink>`, `<RouterView>` and `useRoute()` |
 | `router` | no | Instead of `routes`: `{ routes, base?, linkActiveClass?, linkExactActiveClass? }`, matching `createWebHistory(base)` and `createRouter`'s options |
 | `stores` | no | Directory of Pinia option stores whose state components may read |
-| `trustedHtml` | no | Rust type of a `TrustedHtml` prop, e.g. `crate::html::Sanitised` (needed for `v-html`) |
+| `trustedHtml` | no | Rust type of a `TrustedHtml` prop (needed for `v-html`): `ferrovue::BasicHtml` (text with a few formatting tags, built in), `ferrovue::InlineHtml` (inline formatting tags only, built in, which makes every `TrustedHtml` prop inline HTML), `ferrovue::Sanitised` (HTML cleaned by ammonia, the `ammonia` feature), or a type of your own such as `crate::html::CleanHtml` |
 | `helpers` | no | `{ module, functions }`: functions a template may call, each mapped to a Rust twin |
 | `twins` | no | Components ferrovue does not compile, each rendered by a Rust function of yours: `{ "VBtn": { "rust": "crate::ui::v_btn", "props": { "label": "string" }, "slots": ["default"] } }`. See [Escape hatches](#escape-hatches) |
 | `i18n` | no | vue-i18n: `{ messages, locale?, fallbackLocale? }`, the directory of locale files (`en.json`, `nl.json`), the default locale and the fallbacks |
@@ -84,12 +84,12 @@ defineProps<{ name: string; unread: number; note?: string }>();
 ### 4. Generate and render
 
 ```sh
-npx ferrovue init       # a starter ferrovue.config.json and components/Hello.vue
-npx ferrovue            # writes src/generated/{greeting.rs, mod.rs}
-npx ferrovue --check    # in CI: exits 1 if the committed modules are stale
-npx ferrovue --check --diff   # …and shows what differs, as `diff -u` does
-npx ferrovue --check --format json   # errors as JSON, for an editor or CI annotations
-npx ferrovue --watch    # regenerates when components or configs change
+pnpm ferrovue init      # a starter ferrovue.config.json and components/Hello.vue
+pnpm ferrovue           # writes src/generated/{greeting.rs, mod.rs}
+pnpm ferrovue --check   # in CI: exits 1 if the committed modules are stale
+pnpm ferrovue --check --diff  # …and shows what differs, as `diff -u` does
+pnpm ferrovue --check --format json  # errors as JSON, for an editor or CI annotations
+pnpm ferrovue --watch   # regenerates when components or configs change
 ```
 
 Every error carries a stable code, as `error[FV0602]: components/Card.vue:4:17: …`, documented in
@@ -115,8 +115,8 @@ let html: String = greeting::html(&props).into_string();
 let island = greeting::island(&props).into_string();
 
 // (`island()` exists for a component that renders from its props alone: the client rebuilds it from
-// `data-props`. One that also takes slots, the route, stores, translations or teleports has `html()`,
-// and the page's own app mounts it; see examples/fullstack.)
+// `data-props`. One that also takes slots, the route, stores, translations, teleports, provided
+// values or the page head has `html()`, and the page's own app mounts it; see examples/fullstack.)
 
 // …or straight into a buffer you already hold:
 let mut page = String::from("<!doctype html><body>");
@@ -129,11 +129,22 @@ route.
 
 The router and vue-i18n are features of the crate, `router` and `i18n`, both on by default. An
 application with neither routes nor translations can leave them out, and build neither
-`ferrovue-router` nor `ferrovue-i18n`: `ferrovue = { version = "0.5", default-features = false }`.
+`ferrovue-router` nor `ferrovue-i18n`: `ferrovue = { version = "0.6", default-features = false }`.
 
 With the `maud` feature, `ferrovue::Html` implements `maud::Render`, so `(greeting::html(&props))` can go
 straight into a `maud::html!` page.
 
+For `v-html`, `ferrovue::BasicHtml` is built in: `BasicHtml::new(untrusted)` escapes everything but
+`<b>`, `<i>`, `<em>`, `<strong>`, `<code>`, `<br>`, `<p>`, `<ul>`, `<ol>` and `<li>` written with no
+attributes, and balances them; `BasicHtml::from_text(text)` turns plain text into paragraphs.
+`ferrovue::InlineHtml` does the same with `<b>`, `<i>`, `<em>`, `<strong>`, `<code>` and `<br>`
+only: it is what a prop typed `InlineHtml` from `ferrovue/types` is on the server, and the HTML
+`v-html` may write inside a `<p>`.
+With the `ammonia` feature, `ferrovue::Sanitised` is HTML cleaned by [ammonia](https://docs.rs/ammonia):
+name it as `trustedHtml` and build a `v-html` prop with `Sanitised::new(untrusted)`, or
+`Sanitised::with(&builder, untrusted)` for a policy of your own. The server renders the cleaned
+string, and the island's `data-props` carries that same string to the client.
+
 With the `axum` feature, `Html` is an `IntoResponse`, and with `actix-web` a `Responder`: a handler
 responds with the component, as `text/html; charset=utf-8`. `into_html(props)` and
 `into_island(props)` take the props by value, so a handler that builds them returns the page:
@@ -147,7 +158,7 @@ async fn hello(Path(name): Path<String>) -> impl IntoResponse {
 With the `dioxus` feature, a component goes into a Dioxus 0.7 page (`dioxus-ssr` or fullstack):
 `{greeting::island(&props)}` in `rsx!` is the island element itself, with exactly the markup Vue
 hydrates inside it. See `examples/dioxus` and the crate guide's
-[Dioxus page](crates/ferrovue/docs/guide/dioxus.md).
+[Dioxus page](https://github.com/Kinsmir/ferrovue/blob/main/crates/ferrovue/docs/guide/dioxus.md).
 
 ## What a component may use
 
@@ -157,11 +168,12 @@ ferrovue compiles `<script setup lang="ts">` components, and components with no
 
 | Area | Supported |
 |---|---|
-| Prop types | `string`, `number` (integers, `i64`, written and computed as JavaScript does, exact within ±2⁵³), `Float` from `ferrovue/types` (fractions, `f64`), `boolean`, string-literal unions (`"sm" \| "md"`), `T \| undefined`, `T \| null` (an `Option` written as `null`), arrays (`T[]`, `Array<T>`, `readonly T[]`), interfaces and object type aliases (recursive ones too), dictionaries (`Record<string, T>`, `{ [key: string]: T }`, `ferrovue::Record` in Rust, which keeps JavaScript's order of keys), another component's exported `Props`, `TrustedHtml` |
+| Prop types | `string`, `number` (integers, `i64`, written and computed as JavaScript does, exact within ±2⁵³), `Float` from `ferrovue/types` (fractions, `f64`), `boolean`, string-literal unions (`"sm" \| "md"`), `T \| undefined`, `T \| null` (an `Option` written as `null`), arrays (`T[]`, `Array<T>`, `readonly T[]`), interfaces and object type aliases (recursive ones too), dictionaries (`Record<string, T>`, `{ [key: string]: T }`, `ferrovue::Record` in Rust, which keeps JavaScript's order of keys), another component's exported `Props`, `TrustedHtml`, `InlineHtml` |
 | Shared types | Interfaces and type aliases imported from `.ts` files (generated once, into `types.rs`), from a store's file, or from another component's `.vue` file; objects of a shared type can be passed between components. A TypeScript `enum` whose members are literals is the type of its values: a string, or a number |
 | Constants | Constants imported from `.ts` files and `enum`s (imported, or declared in the component), evaluated when the component is compiled: strings, numbers, booleans, `null`, lists of them, objects of them read field by field (`LABELS.save`, `Tone.Loud`, `Rank[5]`), and lists of objects of them, which become a `const` in `types.rs` (`{ value, label }` items get a type named after the constant, `OptionsItem`, unless the constant is typed with an interface: `OPTIONS: Option[]`; a field that is `null` in some items is `T | null`). See [Constants](#constants) |
 | Props | `withDefaults`, destructured props with defaults (`const { size = "md" } = defineProps<…>()`), the props object (`const props = defineProps<…>()`, then `props.label` in the template or in script code), optional booleans (Vue casts an absent one to `false`), `defineModel` (named, required, with defaults), components with no props. A generic component (`<script setup generic="T extends Item">`) renders each type parameter as its constraint, which is all the template can rely on |
-| Setup | `ref`/`shallowRef`, `computed` (an expression or a single `return`), refs that start empty, typed by their type argument (`ref<Row[]>([])`, `ref<Row>()`, `ref<string \| undefined>(undefined)`), plain `const`/`let`, `.value` in script code, helpers with Rust twins, a plain `<script>` block beside setup. Lifecycle hooks, `watch` (not `immediate`), `defineEmits`, `defineSlots`, `defineOptions`, `defineExpose`, `provide`, template refs (`ref(null)`, `useTemplateRef`) and functions are client-only. The template may name them only from event handlers, which the server drops |
+| Setup | `ref`/`shallowRef`, `computed` (an expression or a single `return`), refs that start empty, typed by their type argument (`ref<Row[]>([])`, `ref<Row>()`, `ref<string \| undefined>(undefined)`), plain `const`/`let`, `.value` in script code, helpers with Rust twins, a plain `<script>` block beside setup. Lifecycle hooks, `watch` (not `immediate`), `defineEmits`, `defineSlots`, `defineOptions`, `defineExpose`, template refs (`ref(null)`, `useTemplateRef`) and functions are client-only. The template may name them only from event handlers, which the server drops |
+| Provide and inject | `provide` and `inject` resolved through the component tree, slot content seeing the providers of the component that renders it, as Vue does: keys that are string literals or `InjectionKey` symbols exported from `.ts` files; values that are props, refs, `computed`s, constants or objects of them (an interface's fields, `reactive()` unwrapping refs); defaults, factory defaults (`inject(k, () => …, true)`), object defaults built as the key's interface (`inject(k, { size: "md" })`), and keys holding functions, which only event handlers may call. A page rendered from Rust passes the generated `Provides`, empty or holding what the client app gives `app.provide`. See the crate's [`provide_inject`](https://docs.rs/ferrovue/latest/ferrovue/guide/provide_inject/index.html) guide |
 | Text | `{{ }}` of strings, integers and booleans; `+`, `-`, `*`, `/`, `%`, with integers and fractions as JavaScript computes them; `<`, `>`, `<=`, `>=` (between numbers, or between strings by UTF-16 code unit), `===`, `!==`; unary `-`, `!`; `??`, `\|\|`, `&&`, `?:`; template literals; optional chaining `a?.b`; `.length`; `String()`, `.toString()`, `.toFixed()`, `Math.max`/`min`/`abs`/`round`/`floor`/`ceil`/`trunc`; `Number()`, `parseInt()` (no radix, 10 or 16), `parseFloat()`; `JSON.stringify()` of strings, numbers, booleans and lists of those; array literals |
 | Strings | `.trim()`, `.trimStart()`, `.trimEnd()`, `.toUpperCase()`, `.toLowerCase()`, `.includes()`, `.startsWith()`, `.endsWith()`, `.indexOf()`, `.lastIndexOf()`, `.slice()`, `.substring()`, `.at()`, `.charAt()`, `.split()`, `.replace()` and `.replaceAll()` with string patterns (`$&`, `` $` ``, `$'`, `$$` read as JavaScript reads them), `.padStart()`, `.padEnd()`, `.repeat()`; indices and lengths count UTF-16 code units, as JavaScript's do (see [Strings](#strings)) |
 | Conditions | `v-if` / `v-else-if` / `v-else`, `?:`, `&&` and `||`, with optional and nullable values narrowed as TypeScript narrows them: `v-if="user"`, `user !== undefined`, `user !== null`, `user != null`, and `!user`, `user === undefined` or `user === null` for the `v-else` |
@@ -172,15 +184,17 @@ ferrovue compiles `<script setup lang="ts">` components, and components with no
 | `style` | objects (camelCase or kebab-case keys, `--custom` properties), arrays of objects, strings, merged with a static `style`, and `v-show`; later values override earlier ones as in Vue. A global `<style>` block is allowed |
 | Scoped styles | `<style scoped>`: the id on every element, on child components' roots (a root that is itself a component, fragments, recursion and `inheritAttrs: false` as Vue renders them) and, from a component with `:slotted()` rules, on the slot content it is given, forwarded slots included; inside `<Transition>`, `<KeepAlive>`, `<Teleport>` and `v-if`; on `<RouterLink>` and what it holds, as vue-router renders them |
 | Components | imported child components, `v-bind` of a child's own `Props`, `v-model` on a child's `defineModel`, recursion; props named in `kebab-case` or `camelCase`; `defineAsyncComponent(() => import("./X.vue"))` (or `{ loader: … }`), rendered as the component it loads, which Vue's server renderer waits for |
+| `<component :is>` | over a closed set of choices, compiled to a `match`: an imported component (`:is="Card"`), an HTML element's name (`is="h2"`), a `computed` or `?:` choosing among them, a prop typed as a union of string literals (`as: "h1" \| "h2"`), and an object of imported components (or element names) declared in setup or imported from a `.ts` file, read by such a prop (`ICONS[name]`); props, fallthrough attributes, slots and scope ids reach each choice as they reach a static child; also inside `<KeepAlive>` and `<Transition>`. See the crate's [`generated_code`](https://docs.rs/ferrovue/latest/ferrovue/guide/generated_code/index.html#component-is) guide |
 | Escape hatches | `<ClientOnly>` from `ferrovue/client`, whose default slot the server never renders, so anything may go in it; components listed in `twins`, rendered by Rust functions of yours. See [Escape hatches](#escape-hatches) |
 | Fallthrough attributes | what a parent passes a child beyond its props (static and bound attributes, `class`, `style`, `data-*`, `aria-*`, booleans, `undefined`): onto its single root, merged with the root's own class and style and replacing its other attributes where they stand, as Vue's `mergeProps` merges them; none for two roots; on through a root that is a component, or a `<RouterLink>`; with `inheritAttrs: false`, onto the elements or components that bind `v-bind="$attrs"` or a `useAttrs()` binding, before or after their own; beside scope ids. Listeners are dropped, as Vue's server drops them. See the crate's [`generated_code`](https://docs.rs/ferrovue/latest/ferrovue/guide/generated_code/index.html#fallthrough-attributes) guide |
 | Slots | default and named slots, fallbacks, `$slots.name` tests and the same through `useSlots()`, scoped slots (`<slot :item="x">` and `#item="{ item }"` or `v-slot="props"`), whose props a parent can hand to its own children |
 | Forms | `v-model` on text inputs, checkboxes, radios, `<select>` and `<textarea>` (renders the initial state) |
 | Built-ins | `<Transition>`, `<TransitionGroup>`, `<KeepAlive>`, `<Suspense>` (synchronous content), `<Teleport>` (to any target, nested, disabled: see below), `v-text`, `v-once`, `v-pre`, `v-memo`, custom directives listed in `clientDirectives` |
-| Vue Router | `<RouterLink>` (resolved by name or imported) with a string `to` or `{ name, params, query, hash }` / `{ path, query, hash }`, `active-class`, `exact-active-class`, `aria-current-value`, `replace`; vue-router's own encoding and active-link matching, nested routes included (a parent link is active on its children's pages, exact only on its own); a history base. `useRoute()` and `$route`: `path`, `fullPath`, `hash`, `name`, `params`, and `query` (a value written once, without `=`, or repeated, exactly as vue-router parses it; `typeof route.query.q === "string"` narrows one to a single string). `<RouterView>`, at the top and in nested route components: each takes the page it shows as a slot |
+| Vue Router | `<RouterLink>` (resolved by name or imported) with a string `to` or `{ name, params, query, hash }` / `{ path, query, hash }`, `active-class`, `exact-active-class`, `aria-current-value`, `replace`; vue-router's own encoding and active-link matching, nested routes included (a parent link is active on its children's pages, exact only on its own); a history base; optional parameters (`:id?`); routes built from a folder of pages, which the Vite plugin also gives the client as `ferrovue/routes`. `useRoute()` and `$route`: `path`, `fullPath`, `hash`, `name`, `params`, and `query` (a value written once, without `=`, or repeated, exactly as vue-router parses it; `typeof route.query.q === "string"` narrows one to a single string). `<RouterView>`, at the top and in nested route components: each takes the page it shows as a slot |
 | Pinia | option stores with a typed `state`, and setup stores (`defineStore(id, () => { … })`) whose returned refs are typed by `ref<T>()` or their initial literal; read through `useX()` or `storeToRefs`, in the template or in `computed`; getters that are an expression of the state, and a setup store's computeds, which may read each other |
 | vue-i18n | `$t` and `useI18n()`'s `t` and `locale`: named and list values, plurals by vue-i18n's rule, literals, linked messages with `upper`/`lower`/`capitalize`, nested and flat keys, fallback locales, a missing key shown as itself. Messages are parsed at build time by vue-i18n's own compiler |
-| `v-html` | only on a `TrustedHtml` prop (`import type { TrustedHtml } from "ferrovue/types"`) |
+| `v-html` | only on a `TrustedHtml` prop (`import type { TrustedHtml } from "ferrovue/types"`), or an `InlineHtml` one (inline tags only, `ferrovue::InlineHtml` on the server, with no `trustedHtml` needed), the only HTML it may write inside a `<p>`; never on a table's structure, a `<select>` or `<optgroup>`, or an SVG or MathML element that holds no HTML. See the crate's [`escaping`](https://docs.rs/ferrovue/latest/ferrovue/guide/escaping/index.html#where-v-html-may-go) guide |
+| Page head | `useHead` (and `useServerHead`) from `@unhead/vue` 3: `title`, `titleTemplate`, `base`, `meta`, `link`, `script`, `style`, `noscript`, `htmlAttrs` and `bodyAttrs`, with values the server computes (props, setup bindings, getters such as `() => props.title`, `list.map(x => ({ … }))` for a list of tags), `key`, `tagPosition`, `tagPriority` and `tagDuplicateStrategy`; `useSeoMeta` (and `useServerSeoMeta`) of string, number, boolean and `null` values. Collected into a `ferrovue::Head` in the order Vue's server runs them, and written as unhead's `renderSSRHead` writes them: its tag order, deduplication, title template and escaping. See [Page head](#page-head) |
 
 Refused at compile time, each with an error that names the construct:
 
@@ -188,7 +202,20 @@ Refused at compile time, each with an error that names the construct:
 - `<RouterView>` in a component with `<style scoped>`, which would give the page that component's
   id; and, since vue-router renders a link from virtual nodes, a `<slot>` inside a `<RouterLink>`
   that takes scope ids, or an element inside one in slot content given a `:slotted()` id
-- `<component :is>`
+- `<component :is>` over an open set (a `string`, a `Component`, a key that is not a literal union),
+  over a prop that may be absent, or naming a key its object lacks or a tag that is not an HTML
+  element; `v-html` or `v-text` on it; and, inside an element it chooses (which Vue renders from
+  virtual nodes), a `<slot>` with fallback content, `v-show`, and `v-model` on a `<select>`
+- in provide and inject: a key that is neither a string literal nor an `InjectionKey` symbol exported
+  from a `.ts` file, `inject(key)!`, a value that may be `null` or `undefined`, values of different
+  types (or a ref and a plain value) under one key, setup that assigns to an injected value,
+  `provide` in a component holding `<RouterView>`, a string key injected inside a Rust twin's slot,
+  and `provide(…)` not imported from `vue`
+- `v-show`, and `v-model` on a `<select>`, in the content of a `<RouterLink>` or of a Rust twin's
+  slot, which Vue renders from virtual nodes
+- in the page head: options given to `useHead`, `useHeadSafe`, `templateParams`, a `titleTemplate`
+  function, event handlers (`onload`), a `class` or `style` that may be `null` (on which unhead's
+  renderer throws), and an object or array given to a `useSeoMeta` key
 - the Options API (a `<script>` without `setup`), and a type parameter of a generic component with
   no constraint (`generic="T"`)
 - constants that are not literals (`Date.now()`, a function), an object constant read whole or by a
@@ -197,6 +224,9 @@ Refused at compile time, each with an error that names the construct:
 - custom directives not listed in `clientDirectives`
 - `watchEffect`, `watch` with `immediate`, `onServerPrefetch`, top-level `await`, and statements in setup that change state
 - `route.meta` and `route.matched`
+- in a folder of pages: a parameter beside text in one part of a path (`prefix-[id].vue`), repeatable
+  and optional catch-all parameters, parameter parsers (`[id=int]`), named views (`index@aside.vue`),
+  `definePage()`, a `<route>` block, and two pages, or a page and a component, with one component name
 - Pinia getters that read `this` or return a function
 - ordering comparisons between a string and a number, which JavaScript makes numeric
 - regular expressions (`.replace(/x/g, …)`, `.split(/,/)`), replacement functions, a search's
@@ -251,7 +281,7 @@ are, and `v-for="s in SIZES"` walks an array literal. A list of objects becomes
 the shared types, with a type for its items (here `SortsItem`, or the interface the constant is
 declared with):
 
-```rust,ignore
+```rust
 pub const SORTS: &[SortsItem<'static>] = &[
     SortsItem { key: Cow::Borrowed("name"), label: Cow::Borrowed("By name") },
     SortsItem { key: Cow::Borrowed("price"), label: Cow::Borrowed("By price") },
@@ -284,7 +314,7 @@ The default is the plugin's production behaviour because the production build is
 get: with every option left alone, its styles apply. But plugin-vue hashes the path alone in its dev
 server, so with the default a page rendered during development carries other ids than the dev
 client and shows unstyled. The recommended setup is `componentIdGenerator: "filepath"` with
-`"scopeId": "filepath"`, as [`examples/fullstack`](examples/fullstack) does: the ids are then the
+`"scopeId": "filepath"`, as [`examples/fullstack`](https://github.com/Kinsmir/ferrovue/tree/main/examples/fullstack) does: the ids are then the
 same in development and production, and do not change, nor change the generated Rust, whenever a
 component's source does.
 
@@ -347,8 +377,8 @@ page::render(&mut out, &props, &i18n);
 
 ### Escape hatches
 
-Some components will never compile: a component library's render functions, `inject` chains, code
-that measures the page in `onMounted`. Two ways keep one of them from blocking the page around it.
+Some components will never compile: a component library's render functions, code that measures the
+page in `onMounted`. Two ways keep one of them from blocking the page around it.
 
 **`<ClientOnly>`**: the server writes its `#fallback` slot (or a comment, without one), and the
 browser hydrates that same fallback, then swaps in the default slot once mounted. Both sides render
@@ -397,13 +427,11 @@ have. Prop types are those of helpers (`string`, `int?`, …); an absent `bool`
 bare `block` is `true`, as Vue casts them.
 
 **Exactness is your responsibility.** ferrovue cannot check that `v_btn` writes the bytes Vue's
-server renderer writes for `VBtn`: its guarantee rests on your code here, as it does for helpers. Prove it with fixtures: render the components that use the twin with Vue through
-`ferrovue/testing`'s `fixtureApp` and `attachSsrRender`, and with Rust through the generated
-`render_json`, and compare. Slot content reaches the twin as a component's render function sees it
+server renderer writes for `VBtn`: its guarantee rests on your code here, as it does for helpers. Prove it with fixtures of the components that use the twin, held to Vue by the
+conformance suite (see [Testing against Vue](#testing-against-vue)). Slot content reaches the twin as a component's render function sees it
 (`<!--v-if-->` for an absent `v-if`, as Vue writes virtual nodes). The twin decides where it goes and
 whether fragment markers surround it, as the component does. `examples/fullstack` has a
-twin (`src/ui.rs`), its fixtures (`fixtures/`), the Vue half (`test/fixtures.test.ts`) and the Rust
-half (`src/fixtures.rs`).
+twin (`src/ui.rs`) and its fixtures (`fixtures/`).
 
 ### Teleports
 
@@ -419,6 +447,25 @@ let modals = teleports.get("#modals").unwrap_or_default(); // inside <div id="mo
 As Vue recommends, teleport to a dedicated element such as `#modals`: the browser hydrates
 a target from its first node, and `body` also holds the app.
 
+### Page head
+
+A component that calls `useHead` or `useSeoMeta` from `@unhead/vue` takes a `ferrovue::Head`, which
+collects the calls of the whole tree in the order Vue's server runs them. After rendering the body,
+write the head as unhead's server renderer writes it:
+
+```rust
+let head = ferrovue::Head::new(); // createHead(): lang="en", charset and viewport; or Head::without_defaults()
+book_page::render(&mut body, &props, &head);
+let tags = head.render(); // head_tags, body_tags_open, body_tags, html_attrs, body_attrs
+let page = format!("<html{}><head>{}</head><body{}>{}{}{}</body></html>",
+    tags.html_attrs, tags.head_tags, tags.body_attrs, tags.body_tags_open, body, tags.body_tags);
+```
+
+On the client the head is unhead's: give the page's app its client head,
+`mountPage(layout, islands, { plugins: [createHead()] })` with `createHead` from
+`@unhead/vue/client`, and it takes over the tags the server wrote. The crate's
+[`head`](https://docs.rs/ferrovue/latest/ferrovue/guide/head/index.html) guide has the details.
+
 ### Scoped slots from Rust
 
 A scoped slot's `Slots` field takes a closure that receives the props its outlet passes, as a
@@ -459,6 +506,25 @@ components alike, so a hand-written island can join them: `mountIslands({ ...isl
 An island whose name is not among them is left as the server rendered it, with a warning naming it
 (`onError` to handle it otherwise), as is one whose component fails to load.
 
+An island can wait to hydrate, and to fetch its code, until it is needed. `hydrate` on the
+server's `island()` writes a `data-hydrate` attribute on the wrapper, which `mountIslands` honours
+with Vue's lazy hydration strategies:
+
+```rust
+use ferrovue::Hydrate;
+
+reviews::island(&props).hydrate(Hydrate::Visible);               // scrolled into view
+footer::island(&props).hydrate(Hydrate::visible_with("200px"));  // within 200px of the view
+chart::island(&props).hydrate(Hydrate::Idle);                    // the browser is idle
+counter::island(&props).hydrate(Hydrate::Interaction);           // pointerenter, click or focus
+menu::island(&props).hydrate(Hydrate::InteractionOn(&["keydown"]));
+sidebar::island(&props).hydrate(Hydrate::media("(min-width: 60rem)"));
+```
+
+The island's markup is unchanged, so nothing about exactness changes. An event that woke an island
+waiting for interaction is dispatched again once it has hydrated, so the first click is not lost.
+An island without `data-hydrate` hydrates at once, as before.
+
 An island's `<style>` goes into its chunk too, and Vite links it only once the island's script has
 loaded, after the server's markup is on screen. Link those stylesheets from the page up front: a
 server reading Vite's manifest takes the `css` of the entry's `dynamicImports` as well as its own
@@ -466,7 +532,8 @@ server reading Vite's manifest takes the `css` of the entry's `dynamicImports` a
 
 An application whose own navigation layer leaves the page can keep `<RouterLink>` for its `href`s
 and active classes with `linkRouter(routes, { navigate })` from `ferrovue/link-router`: a router
-over the routes file whose every navigation after the first goes to `navigate`. The routing guide
+over the routes file (or the default export of `ferrovue/routes`, with a folder of pages) whose
+every navigation after the first goes to `navigate`. The routing guide
 (`ferrovue::guide::routing`) explains each part of it.
 
 ### Hydrating a whole page
@@ -509,17 +576,82 @@ import { hydrateState } from "ferrovue";
 hydrateState(pinia); // before app.mount(): every store starts from what the server rendered
 ```
 
+### Fixtures in an application's vitest run
+
+`fixtureApp` from `ferrovue/testing` installs Pinia for a fixture's `$stores`, vue-router for its
+routes and vue-i18n for its `i18n` option, importing each itself. A component's `useBasket()`,
+`useRoute()` or `useI18n()` reads the instance its own import of the package gives it, so the two
+must be one module instance. vitest loads `ferrovue/testing` from `node_modules` with Node, and
+runs the application's code through Vite; where a peer goes through Vite too (listed in
+`server.deps.inline`, aliased, linked from elsewhere, or installed twice), the fixture installs a
+different instance from the one the component reads, and the render fails with Pinia's "there was
+no active Pinia" or an undefined route. Pass the application's own modules in the options:
+
+```ts
+const app = await fixtureApp(component, readFixture(json), routes, {
+  pinia: await import("pinia"),
+  vueRouter: await import("vue-router"),
+  vueI18n: await import("vue-i18n"),
+});
+```
+
+Without them, `fixtureApp` imports the peers itself, as before. Another way is to have vitest run
+ferrovue through Vite as well, which puts it on the application's module graph; this also covers
+`vue` itself, which `fixtureApp` always imports:
+
+```ts
+// vitest.config.ts
+export default defineConfig({ test: { server: { deps: { inline: ["ferrovue"] } } } });
+```
+
 ### Streaming with holes
 
 `ferrovue::hole()` is a slot whose content you write later. Render a layout with holes,
 `split_holes` the output, and stream the pieces with each hole's content between them, in whatever
-order the content is ready. With the `axum` or `actix-web` feature, `ferrovue::HtmlStream` is that
-streamed response, from the render and a future for each hole's content:
+order the content is ready. With the `stream` feature (which `axum` and `actix-web` turn on),
+`ferrovue::HtmlStream` is that streamed body, from the render and a future for each hole's content:
 
 ```rust
 let body = ferrovue::HtmlStream::new(page).hole(async move { reviews_of(&id).await });
 ```
 
+### Testing against Vue
+
+An application holds its own components to Vue as ferrovue's suite does, with a fixtures directory
+and two calls. A fixture is a component's props as JSON (plus `$slots`, `$route`, `$stores` and
+`$locale` where it takes them) beside the HTML Vue rendered for them:
+
+```text
+fixtures/Reviews/three.json   {"reviews":[{"reader":"Ada","stars":5,"text":"The spice must flow."}]}
+fixtures/Reviews/three.html   recorded from Vue with FERROVUE_FIXTURES_WRITE=1
+```
+
+```ts
+// test/conformance.test.ts, run by vitest with environment: "happy-dom"
+import { join } from "node:path";
+import type { Component } from "vue";
+import { conformanceSuite } from "ferrovue/testing";
+
+await conformanceSuite({
+  config: join(import.meta.dirname, "../ferrovue.config.json"),
+  components: import.meta.glob<Component>("../client/components/*.vue", { eager: true, import: "default" }),
+  pinia: await import("pinia"),
+  vueRouter: await import("vue-router"),
+});
+```
+
+```rust
+ferrovue::conformance!("fixtures", generated::render_json, at_least = 24);
+```
+
+The Vue half fails on a component with no fixtures, a fixture naming no component, a project with
+no components, generated Rust that differs from what `ferrovue` writes now, a fixture Vue renders
+differently from its `.html`, and a recorded `.html` that hydrates with any warning;
+`FERROVUE_FIXTURES_WRITE=1` records the `.html` files instead. The Rust half renders every fixture through the generated `render_json`,
+compares the bytes, and fails when fewer than `at_least` fixtures are found. The crate's
+[`testing`](https://docs.rs/ferrovue/latest/ferrovue/guide/testing/index.html) guide has the
+details; `examples/fullstack` uses both.
+
 ## Performance
 
 Time to render one component to an HTML string. On the left is Vue's `renderToString` on Node, and
@@ -529,10 +661,10 @@ and both write the same bytes: each side checks its output against
 
 | Scenario | What renders | Output | Vue `renderToString` | ferrovue | Speed-up |
 |---|---|---|---|---|---|
-| `small` | `Nav`: two `<RouterLink>`s resolved against the current route | 206 B | 41.39 µs | 0.962 µs | 43.0× |
-| `list` | `Lists`: 1,000 words, 1,000 numbers, 100 groups of 10 members | 102 KiB | 363.9 µs | 49.00 µs | 7.4× |
-| `tree` | `Tree`: a recursive component, binary tree 8 levels deep (255 nodes) | 9.5 KiB | 539.5 µs | 3.89 µs | 138.5× |
-| `page` | `Dashboard`: 22 `Panel`s with named slots, a `Text`, 20 `Frame`s holding loops | 8.0 KiB | 192.4 µs | 4.84 µs | 39.7× |
+| `small` | `Nav`: two `<RouterLink>`s resolved against the current route | 206 B | 36.41 µs | 0.989 µs | 36.8× |
+| `list` | `Lists`: 1,000 words, 1,000 numbers, 100 groups of 10 members | 102 KiB | 355.8 µs | 46.16 µs | 7.7× |
+| `tree` | `Tree`: a recursive component, binary tree 8 levels deep (255 nodes) | 9.5 KiB | 522.2 µs | 3.86 µs | 135.2× |
+| `page` | `Dashboard`: 22 `Panel`s with named slots, a `Text`, 20 `Frame`s holding loops | 8.0 KiB | 181.3 µs | 5.06 µs | 35.8× |
 
 These are mean times per render. The Vue column is tinybench's mean, with 5 s per scenario after
 a 1 s warm-up. The ferrovue column is criterion's mean point estimate, using its defaults of a 3 s
@@ -580,6 +712,7 @@ of Vue and of each integration. Your project may use any later patch of the same
 | `vue-router` (optional) | `~5.3.1` | 5.3.1 |
 | `pinia` (optional) | `~4.0.3` | 4.0.3 |
 | `vue-i18n` (optional) | `~11.4.13` | 11.4.13 |
+| `@unhead/vue` (optional) | `~3.4.2` | 3.4.2 |
 
 A new minor of any of them (Vue 3.6, vue-router 5.4, …) needs a ferrovue release that re-records
 the fixtures from it. A weekly CI job re-records them from the newest patch each range allows and
@@ -591,10 +724,15 @@ before it reaches you; a ferrovue patch follows when one does.
 ```text
 crates/ferrovue/             the Rust runtime crate, which generated code calls
   src/                       a module per part (`Html`, slots, class and style, the state script,
-                             strings, teleports, fallthrough attributes), each module's unit tests
-                             beside it in <module>/tests.rs; lib.rs re-exports them all, and the
-                             three crates below
+                             strings, teleports, the page head, fallthrough attributes, `BasicHtml`
+                             and `InlineHtml`,
+                             `Sanitised`, the fixture check `conformance!` writes), each module's
+                             unit tests beside it in <module>/tests.rs; lib.rs re-exports them all,
+                             and the three crates below
+  docs/guide/                the crate guide, `ferrovue::guide` on docs.rs
   tests/conformance/         components, fixtures, recorded HTML, generated Rust
+  tests/literal_props/       components compiled with `"builders": false`
+  tests/sanitised/           a component whose `TrustedHtml` is `ferrovue::Sanitised`
   tests/vectors/             vectors recorded from JavaScript and Vue
   tests/properties.rs        property-based tests of the runtime
   benches/                   criterion benchmarks of generated renderers (see Performance)
@@ -606,36 +744,49 @@ crates/ferrovue-i18n/        vue-i18n's t() (the `i18n` feature)
 packages/ferrovue/           the compiler (npm package)
   src/index.ts               `ferrovue`: the browser API, `mountIslands`, `mountPage`, `hydrateState` and the types
   src/compiler.ts            `ferrovue/compiler`: `generate`, `write`
+  src/context.ts, model.ts   `ferrovue.config.json`, and the types and values the compiler passes around
   src/component.ts, script.ts, typescript.ts, constants.ts
                              a `.vue` file read, <script setup>, TypeScript types, constants and enums
-  src/template.ts, children.ts, slots.ts, loops.ts
-                             the compiled template: statements, child components, slots, v-for
-  src/expr.ts, strings.ts, numbers.ts, narrowing.ts, calls.ts, lists.ts
-                             expressions: operators, strings, numbers, narrowing, calls, lists
+  src/template.ts, children.ts, slots.ts, loops.ts, vhtml.ts
+                             the compiled template: statements, child components, slots, v-for,
+                             where `v-html` may go
+  src/expr.ts, strings.ts, numbers.ts, narrowing.ts, calls.ts, lists.ts, parens.ts
+                             expressions: operators, strings, numbers, narrowing, calls, lists,
+                             the parentheses Rust needs
   src/attrs.ts, classes.ts, styles.ts, fallthrough.ts
                              attributes, class and style, attributes a parent passes on
+  src/dynamic.ts             `<component :is>` over a closed set of choices
   src/plugin.ts              the plugin interface (see CONTRIBUTING.md)
   src/plugins/               vue-router, Pinia, vue-i18n, scoped styles, <Teleport>, shared types,
-                             <ClientOnly>, Rust twins
+                             <ClientOnly>, Rust twins, provide and inject, the page head
   src/rust.ts, emitter.ts    the Rust source written out
   src/cli.ts, vite.ts        the `ferrovue` command and the Vite plugin
+  src/diff.ts                the diff `ferrovue --check --diff` prints for a stale file
   src/errors.ts, diagnostics.ts
                              every error code with its title, and errors as the CLI, JSON and Vite show them
   src/client.ts              browser-side helpers: `mountIslands`, `mountPage`, `hydrateState`, `<ClientOnly>`
   src/islands.ts             `ferrovue/islands`, which the Vite plugin writes: every island, loaded lazily
   src/link-router.ts         `ferrovue/link-router`: `<RouterLink>` while the application navigates on its own
   src/routes.ts              a routes file as vue-router's route records
-  src/testing.ts             utilities for a project's own conformance suite
+  src/file-routes.ts         the routes vue-router's file-based routing builds from a folder of pages
+  src/page-routes.ts         `ferrovue/routes`, which the Vite plugin writes from the pages
+  src/testing.ts             `ferrovue/testing`: utilities for a project's own conformance suite
+  src/fixture.ts, settle.ts  `fixtureApp` and `readFixture`, and waiting for async components to settle
+  src/conformance.ts         `conformanceSuite`, which `ferrovue/testing` exports
+  src/ssr.ts                 `attachSsrRender`, which `ferrovue/testing` exports
   src/hydration.ts           `hydrateRecordedPage`, which `ferrovue/testing` exports
-  src/types.ts               `ferrovue/types`: `TrustedHtml`, `Float`
+  src/types.ts               `ferrovue/types`: `TrustedHtml`, `InlineHtml`, `Float`
   test/                      compiler, CLI, router, vector, island, Vite and conformance tests
   browser/                   conformance fixtures and recorded pages hydrated in real browsers (`pnpm test:browser`)
   bench/                     Vue renderToString benchmarks, the other half of Performance
   fuzz/                      the randomised differential tester (`pnpm fuzz`)
 examples/greeting/           the smallest setup: one component rendered from Rust
-examples/fullstack/          axum + Vite: islands, a page hydrated whole, Pinia state, routes and
-                             streaming, <ClientOnly>, a Rust twin and its fixtures
+examples/fullstack/          axum + Vite: islands (some hydrating later), a page hydrated whole,
+                             Pinia state, routes from a folder of pages, the page head, streaming,
+                             <ClientOnly>, a Rust twin, and a conformance suite
 examples/dioxus/             a Dioxus page, rendered with dioxus-ssr, with an island in it
+scripts/ferrovue-in.ts       the `ferrovue` command run in a project of this repository (`pnpm conformance:check`, CI)
+scripts/inspect.ts           Vue's SSR code and render of a component beside the Rust ferrovue generates for it
 scripts/release.ts           the release version bump (see RELEASING.md)
 ```
 
@@ -648,15 +799,15 @@ pnpm typecheck
 cargo test --all-features
 ```
 
-[TESTING.md](TESTING.md) explains how the suite fits together and how to add a case,
-[CONTRIBUTING.md](CONTRIBUTING.md) how to add support for a Vue construct, and
-[RELEASING.md](RELEASING.md) how a release is cut.
+[TESTING.md](https://github.com/Kinsmir/ferrovue/blob/main/TESTING.md) explains how the suite fits together and how to add a case,
+[CONTRIBUTING.md](https://github.com/Kinsmir/ferrovue/blob/main/CONTRIBUTING.md) how to add support for a Vue construct, and
+[RELEASING.md](https://github.com/Kinsmir/ferrovue/blob/main/RELEASING.md) how a release is cut.
 
-[`examples/fullstack`](examples/fullstack/README.md) is a complete app to copy: an axum server, a Vite client, islands, Pinia, vue-router and streaming, with a test that it hydrates.
+[`examples/fullstack`](https://github.com/Kinsmir/ferrovue/blob/main/examples/fullstack/README.md) is a complete app to copy: an axum server, a Vite client, islands, Pinia, vue-router and streaming, with a test that it hydrates.
 
 ## Licence
 
-Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT licence](LICENSE-MIT),
+Licensed under either of [Apache License, Version 2.0](https://github.com/Kinsmir/ferrovue/blob/main/LICENSE-APACHE) or [MIT licence](https://github.com/Kinsmir/ferrovue/blob/main/LICENSE-MIT),
 at your option. Unless you explicitly state otherwise, any contribution you intentionally submit for
 inclusion in this work, as defined in the Apache-2.0 licence, is dual-licensed as above, without any
 additional terms or conditions.

package/dist/attrs.d.ts

@@ -4,7 +4,8 @@ export declare function display(e: Emitter, v: Val): boolean;
 export declare function interpolate(s: Scope, e: Emitter, v: Val, n: N): void;
 export declare function attrValue(e: Emitter, v: Val): void;
 export declare function renderAttr(s: Scope, e: Emitter, key: string, v: Val, n: N): void;
-export declare function renderDynamicAttr(s: Scope, e: Emitter, key: string, v: Val, n: N): void;
+export declare function keepsAttrCase(tag: string): boolean;
+export declare function renderDynamicAttr(s: Scope, e: Emitter, key: string, v: Val, n: N, tag?: string | null): void;
 export declare const IGNORED_PROPS: Set<string>;
 export declare function directiveProps(s: Scope, n: N): boolean;
 export declare function isAttrs(n: N): boolean;

package/dist/attrs.js

@@ -1,4 +1,4 @@
-import { escapeHtml, hyphenate, isBooleanAttr, isSSRSafeAttrName, propsToAttrMap } from "@vue/shared";
+import { escapeHtml, hyphenate, isBooleanAttr, isSSRSafeAttrName, isSVGTag, propsToAttrMap } from "@vue/shared";
 import { fail, nothing, GenError, rustStr } from "./model.js";
 import { CONFIG_FILE, ctx } from "./context.js";
 import { describeTy, expr } from "./expr.js";
@@ -75,8 +75,11 @@ export function renderAttr(s, e, key, v, n) {
     attrValue(e, v);
     e.lit(`"`);
 }
-export function renderDynamicAttr(s, e, key, v, n) {
-    const name = propsToAttrMap[key] ?? key.toLowerCase();
+export function keepsAttrCase(tag) {
+    return tag.indexOf("-") > 0 || isSVGTag(tag);
+}
+export function renderDynamicAttr(s, e, key, v, n, tag = null) {
+    const name = tag !== null && keepsAttrCase(tag) ? key : (propsToAttrMap[key] ?? key.toLowerCase());
     if (!isSSRSafeAttrName(name))
         fail(s.comp, "FV0404", `unsafe attribute name \`${name}\``, n);
     renderable(s, key, v, n);
@@ -91,7 +94,7 @@ export function renderDynamicAttr(s, e, key, v, n) {
     }
     if (v.ty.k === "opt") {
         e.open(`if let Some(v) = ${v.code}`);
-        renderDynamicAttr(s, e, key, { code: "v", ty: v.ty.of }, n);
+        renderDynamicAttr(s, e, key, { code: "v", ty: v.ty.of }, n, tag);
         e.close();
         return;
     }

package/dist/children.d.ts

@@ -10,7 +10,7 @@ export declare function renderChild(s: Scope, e: Emitter, n: N, twin?: TwinCall)
 export declare function array(key: string): boolean;
 export declare function fieldInit(name: string, value: string): string;
 export declare function takesSlots(c: Component): boolean;
-export declare function extraParams(c: Component): string;
-export declare function callChild(s: Scope, e: Emitter, child: Component, propsCode: string, slots: N, attrs: string | null): void;
+export declare function extraParams(c: Component, unread?: (name: string) => boolean): string;
+export declare function callChild(s: Scope, e: Emitter, child: Component, propsCode: string, slots: N, attrs: string | null, later?: boolean): void;
 export declare function callWith(s: Scope, e: Emitter, child: Component, m: string, head: string, slotsTy: string, trailing: string, slots: N, vnode?: boolean): void;
 export declare function ownInto(comp: Component, v: Val, want: Ty, node: N): string;