tungsten 0.7.1 → 0.8.0

package/AGENTS.md

@@ -0,0 +1,1385 @@
+# Tungsten — guide for coding agents
+
+A working guide to building applications with [Tungsten](https://robertsandiford.co.uk/tungsten),
+written for AI coding agents. It covers the parts of the framework you need to write correct code,
+and the places where Tungsten differs from React/Next in ways that silently produce broken output.
+
+Read the section for the work you are about to do. The **Things to avoid** list at the end is a
+summary, not a substitute.
+
+## Authority
+
+Prefer these sources in order:
+
+1. The installed source and TypeScript declarations — `node_modules/tungsten/dist/**/*.d.ts`, and
+   `src/` if you have the framework repo. This is definitive.
+2. Existing code in the application you are working on. Follow its established patterns rather
+   than introducing a second way of doing the same thing.
+3. This document.
+4. The [published documentation](https://robertsandiford.co.uk/tungsten). Good for concepts and
+   background, but it is a work in progress and some examples use older API names.
+
+If this document and the installed declarations disagree, the declarations win — say so rather
+than working around it.
+
+## What Tungsten is
+
+A TypeScript, class-component frontend framework whose rendering and updating algorithm is
+deliberately close to React's, wrapped in a scope closer to Next: it supplies routing, scoped
+styling, a reactive store, SSR + hydration, environment handling, dev/prod servers, and a build
+pipeline.
+
+What it is **not**:
+
+- Not React. Do not add React, React DOM, or hooks-based code to a Tungsten app. Some
+  function-component compatibility exists (`src/hooks/`, `src/compat/`) but it is deprioritized —
+  function-component stand-ins are not persistent. Class components are the model.
+- Not file-system routed. Routes are defined in code, deliberately.
+- Not a full-stack data framework. It has no server components and no opinion about your API or
+  database. tRPC and Prisma appear in the author's own applications by preference; they are not
+  part of Tungsten.
+
+## Related packages
+
+Two sibling repositories, in `framework/` next to this work folder, ship with Tungsten and track
+its conventions:
+
+- **`create-tungsten-app`** — the project generator, with the starter templates under `templates/`.
+  A change to an app-facing protocol here (config, env, routing, the JSX runtime) usually has to
+  reach the templates too.
+- **`eslint-config-tungsten-flat`** — the lint configuration the generated apps use.
+
+Neither is touched from this repo; each has its own working tree and history.
+
+## Runtime model
+
+On an initial request the server matches a route, runs that route's `data` function, renders the
+root component and matched page to HTML, and sends it. The browser hydrates that markup.
+Subsequent navigation through `<Link>` is client-side: the destination route's `data` function is
+fetched first, then its content renders.
+
+```
+request -> match route -> route data -> root + page render -> HTML -> hydrate
+```
+
+Two consequences that cause real bugs:
+
+- **The server render and the hydration render must produce identical output.** Anything
+  environment-dependent — `toLocaleString`, local timezone, `Math.random`, `Date.now` — will
+  differ between server and browser and corrupt hydration. Build such strings from fixed parts
+  (UTC getters, explicit locales), and coerce defensively: a `Date` in route data may arrive at
+  the client as an ISO string.
+- **Clicks before hydration completes are lost.** This is the standard SSR caveat; do not add
+  application code to work around it.
+
+## Project layout and configuration
+
+`tungsten.config.js` at the project root configures the framework. Defaults are in
+`src/defaultConfig.ts`; the type is `FrameworkConfig` (usable via JSDoc in a `.js` config).
+
+| Key | Meaning |
+| --- | --- |
+| `codeDir` | Folder of compiled application code Tungsten consumes, e.g. `'dist'`. |
+| `sourceDir` | Source folder — needed to locate `.sass`/`.css` files if the TS build does not copy them. |
+| `rootComponent` | Entry component, relative to `codeDir`, e.g. `'client/Root.jsx'`. |
+| `routesLocation` | `[file, exportName]`, relative to `codeDir`. Defaults to `['routes.jsx', 'routes']`; set it only when the routes live elsewhere or under another name, e.g. `['client/routes.jsx', 'getRoutes']`. |
+| `envSchemasLocation` | Module that registers the env schemas (see [Environment](#environment)). Defaults to `'env.js'`, e.g. `'common/env.js'`. |
+| `clientDirs` / `clientPatterns` | Sources the browser pipeline compiles. Unset, everything. |
+| `rawDirs` / `rawPatterns` | Sources the node pipeline compiles (types stripped, imports untouched) — server middleware and the like. Unset, nothing. |
+| `ignoreDirs` / `ignorePatterns` | Sources neither pipeline compiles. No default. Each pipeline compiles its selection **and not** these, so an ignored folder cannot be selected back in. `ignoreDirs: ['server']` suits an app whose own build emits its server code; to have Tungsten compile the server, narrow `clientDirs` and select it in `rawDirs` instead. |
+| `serverMiddleware` | `[file, exportName, mountPath]` — Express handlers mounted on Tungsten's own server, so a frontend and an API can share one process. Loaded from the raw pipeline's output when the file is in `rawDirs`, otherwise from `codeDir`. In dev (unreleased) it is loaded once and reloaded when a `.js` file under `codeDir` changes, not on every request — so module-level state lasts until the next edit, as in prod. |
+| `serverIgnoreDirs` / `serverIgnorePatterns` | Dev: files under `codeDir` whose changes don't reload `serverMiddleware`, in the shapes of `ignoreDirs` / `ignorePatterns`. Test files never do. No default; e.g. `serverIgnoreDirs: ['client']`. |
+| `defaultCacheControl` | The `Cache-Control` of prod pages that set none themselves (see [Page caching](#page-caching)). Unset, pages are sent without one. |
+| `serverSideRouting` | 0.7.1+. Unset is `true`. `false`: the server runs none of the app's code for a page. It does no routing and fetches no data, and sends the same stub for every URL (status 200): the root component's `<html>`, `<head>` and `<body>` with nothing in them. The client then fetches the global data (or the pipeline's all-routes data) beside its first routing, with the route data, and builds the head and body. A pipeline app runs, in order: `clientInit`/`init`, then the all-routes data beside routing, then `clientPost`/`post`, then `clientAfterRouting`. A route data redirect is followed on the client before anything is built. Turns `csr` on, and needs a root component. The root's own `content` still runs on the server, and registered stores are built there with an empty context, so neither may depend on the data. Static generation writes the stub for each listed route; routes found only by following links are not found. |
+
+### The two-stage build, and why imports end in `.jsx`
+
+The application `tsconfig.json` uses `jsx: "preserve"` with an `outDir`, so **tsc emits `.jsx`
+files**; Tungsten then Babel-processes those (its own JSX runtime plus transforms for component
+state, bindings, styles, css imports, and package handling).
+
+Under NodeNext resolution that means source files import the *emitted* extension:
+
+```ts
+import { Home } from './pages/Home.jsx'   // even though the file is Home.tsx
+import { formatDate } from './lib/date.js' // even though the file is date.ts
+```
+
+This is correct and intentional. Do not "fix" it to `.tsx`/`.ts` or extensionless.
+
+Typical scripts: `dev` = `tsc --watch` alongside `tungsten dev`; `build` = `tsc && tungsten build`;
+`start` = `tungsten start`.
+
+### TightScript declarations (unreleased)
+
+Tungsten also ships declarations written for TightScript, the TypeScript fork with permission
+modifiers (`rw`, `exact`, `owned`, …). The runtime code is the same either way; only the types
+differ. An app compiled with the fork opts in through an export condition in its `tsconfig.json`:
+
+```jsonc
+"compilerOptions": {
+    "customConditions": ["tightscript"],
+    "permissionModifiers": true,
+    "permissionDefaults": "read" // the default; tungsten's declarations are written for it
+}
+```
+
+Without the condition, an app gets the stock TypeScript declarations, which is what stock `tsc`
+needs: it can't parse TightScript's modifiers. TightScript's global declarations are
+`tungsten/types-ti/*`, used alongside `tungsten/types/*`.
+
+Under these declarations tungsten asks for write permission where it writes. For example, an object
+bound to an input must be writable (`rw`), so a form object declared read-only is refused at the
+`bind`.
+
+## Components
+
+Base classes, exported from `tungsten` with both a long and a short name
+(`src/Components.tsx`, `src/indexInner.ts`):
+
+| Use | Class | Alias |
+| --- | --- | --- |
+| No local state | `TungstenSimpleComponent<Props, RouteData?>` | `SimpleComponent` |
+| Local state | `TungstenStatefulComponent<Props, State, RouteData?>` | `StatefulComponent` |
+| Optional state | `TungstenComponent<Props, State?, RouteData?>` | — |
+| Store access, stateless | `TungstenBaseSimpleStoreComponent<Props, RouteData, Schema>` | `BaseSimpleStoreComponent` |
+| Store access, stateful | `TungstenBaseStatefulStoreComponent<Props, State, RouteData, Schema>` | `BaseStatefulStoreComponent` |
+
+Applications normally subclass the two store base classes once with their own schema and use those
+wrappers everywhere (see **Store**). Pick the smallest class that fits: no state where none is
+needed, no store where the component only needs props.
+
+Everything is a class field, usually an arrow function:
+
+```tsx
+import { StatefulComponent, BindableInput } from 'tungsten'
+
+type Props = { initialName: string }
+type State = { name: string }
+
+export class Greeting extends StatefulComponent<Props, State> {
+    state: State = { name: this.props.initialName }
+
+    title = `Hello, ${this.props.initialName}`   // sets document title
+
+    reset = () => { this.state.name = this.props.initialName }
+
+    content = () => (
+        <section>
+            <BindableInput name="name" bind={[this.state, 'name']} />
+            <p>{this.state.name}</p>
+            <button onClick={this.reset}>Reset</button>
+        </section>
+    )
+
+    style = Sass`
+        section
+            padding: 1rem
+    `
+}
+```
+
+- **`content` is the render method.** It is called as `content(props, state)` and **may be
+  async** — the framework awaits it. (`render` is accepted as a React-compat alternative; if both
+  exist, `content` wins.)
+- Use arrow-function class fields for handlers so `this` is bound.
+- `title` sets the document title and may be `(props, state) => string`. **Only set `title` on
+  page components** — the last call wins, so a nested component setting it will fight the page.
+- `this.tungsten` holds framework helpers bound to the component (0.7.1+):
+  `this.tungsten.getRoutes()` gives the app's routes as this request resolved them (the function
+  form called for you), for rendering nav. Name their type to read their fields:
+  `getRoutes<typeof routes>()` (unreleased; unchecked beyond being routes, so name the app's own,
+  with `import type`). `this.tungsten.fileUrl('/logo.png')` gives a site
+  file's URL with its cache-busting version (see **Styling**). `this.tungsten.instance` is this
+  component's instance — the same object as `this.__instance`, under a name that is part of the
+  API rather than a convention.
+
+### Lifecycle
+
+Each hook has a React-style name and a short alias:
+
+| Hook | Alias | Notes |
+| --- | --- | --- |
+| `init(props)` / `init(props, state)` | — | On construction, both server and client. May be async. A `TungstenSimpleComponent` is passed props only; the stateful bases pass state too. |
+| `serverInit` / `clientInit` | — | Side-specific initialization. Same arguments as `init`. |
+| `componentDidMount` | `_mounted` | |
+| `componentDidHydrate` | `_hydrated` | Client only, after hydration attaches. |
+| `componentDidUpdate` | `_updated` | |
+| `componentDidRender` | `_rendered` | |
+| `componentWillUnmount` | `_deleting` | |
+| `componentDidUnmount` | `_deleted` | |
+
+Put browser-only work (`window`, `location`, `localStorage`) in `clientInit` or a later client
+hook — never unguarded in `init`, route code, or `content`. A browser-only value the *first render*
+needs (a stored theme) goes through `DocInit()` instead — see **Inline scripts and styles**.
+
+Other instance members worth knowing: `this.props`, `this.routeParams`, `this.routeData`,
+`this.globalData`, `this.triggerUpdate()` (manual re-render),
+`this.pickProps(...)` / `this.pickState(...)`, and `this.using(disposable)` for something that
+should be disposed on unmount. `this.setTimeout(fn, ms)` / `this.setInterval(fn, ms)` (with
+`this.clearTimeout` / `this.clearInterval`) work like the window timers but are cleared when the
+component is deleted; on the server they do nothing and return `undefined`.
+
+### State is mutable and proxied — this is the biggest difference from React
+
+`this.state`, and any plain objects, arrays, `Map`s and `Set`s inside it, are wrapped in proxies
+on the client (`src/componentProxyHandlers.ts`). Writes are detected and queue a re-render.
+
+```ts
+this.state.count++
+this.state.items.push(item)
+this.state.form.email = value
+delete this.state.items[index]
+```
+
+All of that is correct Tungsten code. Rules that follow from it:
+
+- **Do not use `setState`.** It exists only as a React-compat shim and is not needed.
+- **Do not write immutable-update code** — no `{ ...this.state, count: n }` ceremony, no
+  reducers. Deep state structures are fine and are not discouraged.
+- **State updates apply immediately; re-renders are batched.** You read your own writes at once,
+  but the DOM catches up on the next tick. An `await` is a batching boundary — a queued update can
+  run while you are suspended.
+- **Never mutate state inside `content`** or anything it calls. That risks a torn render. Mutate
+  in init hooks and event handlers only.
+- An object already owned by another component's state is **adopted by copy** when you store it,
+  so the two components' states stay independent. Do not rely on sharing a mutable object between
+  components as a communication channel — use the store, or props plus a callback.
+- **An `async content` widens every one of these rules.** Nothing locks a component while it is
+  suspended: a state write starts a second, overlapping update, and a parent re-render replaces
+  `this.props` under the render in flight — so code before the first `await` and code after it can
+  see different props. Prefer a synchronous `content` with the loading done in a lifecycle hook.
+
+#### Framework internals: the render baseline is stamped *before* the render
+
+`markRendered(element)` records the tick a component last rendered at, and `propsAreEqual()` skips
+a child whose props carry no write newer than it. Both call sites in `integrateUpdateVdom.ts` must
+therefore stamp **before** building content, as `__initialContent` already does at mount. Stamping
+afterwards buries any write that landed while an async content was suspended: its tick is then
+`<=` the baseline, and the child is skipped **for good**, since nothing will stamp that object
+again. Regression test: `src/update/asyncRenderBaseline.dom.sxyt.tsx`.
+
+## Routing and data loading
+
+Routes are an object keyed by path, exported from the module named by `routesLocation` — by
+default an export named `routes` from `routes.jsx` in `codeDir`, which is what
+`create-tungsten-app` generates and needs no config:
+
+```tsx
+export const routes = {
+    '/': { content: <Home /> },
+    '404': { content: <NotFound /> },
+} as const satisfies CustomRoutes<Endpoint<any, any>>
+```
+
+The export may instead be a function of the request, `(reqRes: ReqRes | null) => Routes`, when
+building the routes needs it — below, to create an API client for that request. A different
+export name must be set in `routesLocation`; a missing export throws an error naming the setting.
+
+```tsx
+import { type Params, type Endpoint, type CustomRoutes } from 'tungsten'
+
+// tungsten.config.js: routesLocation: ['routes.jsx', 'getRoutes']
+export const getRoutes = (reqRes: ReqResOrNull) => {
+    const api = getApiClient(reqRes)
+
+    return {
+        '/': { content: <Home /> },
+
+        '/things/:id<1+>': {
+            data: ({ id }: Params<'id'>) => api.thing.get(Number(id)),
+            content: (data, params: Params<'id'>) => <ThingDetail thing={data} />,
+        } satisfies Endpoint<Params<'id'>, ThingResponse>,
+
+        '404': { content: <NotFound /> },
+    } as const satisfies CustomRoutes<Endpoint<any, any>>
+}
+
+export type AppRoutes = ReturnType<typeof getRoutes>
+```
+
+- `content` is JSX, or `(data, params) => JSX` when the route has a `data` function.
+- `data` is async and runs **before** the content renders — on the server during SSR, over the
+  network on client-side navigation. The component then receives resolved data, so there is no
+  loading flash on first paint. Route loaders are the right place for a page's initial read.
+- Annotate each entry with `satisfies Endpoint<Params, Data>`. `Data` should be the actual response
+  type of the endpoint, not a locally duplicated shape. `satisfies` preserves the literal path key
+  while still checking the loader and the content callback.
+- A **`'404'` key** supplies not-found content. Every application needs one. It answers with status
+  404, or with its own **`code`** when it gives one (0.7.1+), e.g. `'404': { content: <Gone />,
+  code: 410 }`. An object typed with `CustomRoutes` accepts `code` from unreleased; in 0.7.1 only
+  `Routes` and the array form do.
+- Route definitions may carry **arbitrary extra fields** (`name`, `nav`, `requireAuth`, …) by
+  extending `Endpoint<Params, Data>` — a navigation component can then read them off the routes
+  object.
+
+### The array form (0.7.1+)
+
+Routes may instead be an array, each entry naming its path — anywhere the object is accepted, and
+as a routes function's return:
+
+```tsx
+import { route } from 'tungsten'
+
+export const getRoutes = (reqRes: ReqResOrNull) => [
+    route({ path: '/', content: <Home /> }),
+    route({ path: '/things/:id<1+>', content: <Thing /> }),
+    route({ path: '404', content: <NotFound /> }),
+]
+```
+
+- `route()` keeps the path literal, so `RoutesType` and `PathsType` read the array as they read
+  the object.
+- A **path given twice** is a type error when the routes are registered through the app builder's
+  `.routes()`: the message names the path. It needs the array written out in the call (or in the
+  function it returns from); an array built elsewhere is checked when the routes are read instead,
+  which throws in dev. Outside dev, the last entry for a path wins, as a repeated object key does.
+- The array cannot carry the object's `[$cacheControl]`; each entry's own `cacheControl` still
+  applies.
+- **`routesWithList<Rule>()`** (0.7.1+) requires fields of every path route, leaving `'default'`,
+  `'404'` and `'error'` free of them. It returns the array as given, typed as a tuple:
+
+  ```tsx
+  export const routes = routesWithList<{ name: string }>()([
+      route({ path: '/', name: 'Home', content: <Home /> }),
+      route({ path: '404', content: <NotFound /> }),
+  ])
+  ```
+
+  `routesWith<Rule>()` takes the routes as separate arguments and returns them keyed by path; its
+  rule applies to every route, `'404'` included.
+- **`makeRouteWith<Rule>()`** (unreleased) returns a `route()` that requires the rule's fields, so
+  a route missing one is flagged by itself instead of marking the whole list:
+
+  ```tsx
+  const appRoute = makeRouteWith<{ name: string }>()
+  appRoute({ path: '/', name: 'Home', content: <Home /> })
+  ```
+
+### Path parameters
+
+Express-like `:name` segments. Bare `:name` matches `[^/]+`; a trailing slash is always optional.
+Two constraint syntaxes, both supported (`src/routing/patternToRegex.ts`):
+
+- **Raw regex:** `:id(\d+)`.
+- **Named types:** `:id<uint>`. Available: `digits`/`uint`/`unsigned-integer`;
+  `int`/`integer`/`sint`/`signed-integer`; `int-ge1`/`1+`; `num`/`number`; `alpha`;
+  `alpha-lower`; `alpha-num`/`alpha-numeric`; `alpha-lower-num`/`alpha-lower-numeric`.
+
+Note `1+` means **an integer ≥ 1**, not "one or more digits". A route that does not match its
+constraint falls through to the next candidate, so put literal paths before overlapping
+parametric ones — `/things/new` must precede `/things/:id<1+>`.
+
+Type params with `Params<'id'>` or `ParamsFromPath<'/things/:id'>`.
+
+### Navigation and redirects
+
+- `<Link to="/things/1">` for internal navigation — it keeps routing client-side. Use a plain
+  `<a>` only for external URLs or paths deliberately served by something else. Since 0.6.2 a click
+  with a modifier key (ctrl, meta, shift, alt) or a non-primary button is left to the browser, so
+  open-in-new-tab works.
+- **Typed links (0.7.1+):** `RoutePaths<typeof routes>` is the union of the app's paths,
+  parameters as template holes: `'/leads/:id<1+>'` gives `` `/leads/${number}` ``. The routes may be
+  an object or a routes function (every table it can return counts). Make a `Link` typed by it in
+  an app file:
+
+  ```ts
+  import { makeTypedLink } from 'tungsten'
+  import type { routes } from '../routes.jsx'
+
+  export const { Link } = makeTypedLink('Link')<typeof routes>()
+  ```
+
+  The string names the component for stylesheets (`Link` as a selector), and it is the only key
+  returned, so destructuring any other name is a type error. The type argument is the routes
+  (object or function), not `RoutePaths`: leaving it out, or passing anything with no paths, fails
+  at this call. Import the routes' type with
+  `import type`: a value import of the routes file from a component risks an import cycle. A plain
+  subclass does the same, its class name being the selector:
+  `export class Link extends _Link<RoutePaths<typeof routes>> {}`.
+- `this.__instance.goto(path)` navigates from code; `<GoTo to="/path" />` does it when rendered.
+  Since 0.6.2, with `clientSideNav: false` it is a full page load, and during a server render it
+  answers the request with a redirect immediately (the first one wins if the render asks twice).
+- Back/Forward keep the query (0.7.1+): a route's `data()` gets the query of the entry moved
+  to, and `internalStore.location` is the route path plus query after hydration as on the server.
+  Moving back from a same-page `#anchor` no longer re-runs the route or reloads.
+- From a `data` function, **return** `new RoutingRedirect(path)` (in-app) or
+  `new WebRedirect(url)` (full browser redirect) instead of data. `RedirectCode` sets the status.
+- As content, render `<RouteRedirectComponent to="/path" />`.
+- Both in-app forms redirect under `siteBasePath` on the server, as `goto()` does (unreleased;
+  before, the server sent the bare route path).
+- Global data — classic `globalData` and the pipeline's all-routes data, on either side of a split
+  pipeline — may return the same redirects (unreleased). It wins over the route's redirect, and Post
+  does not run. It is handed the location (route path plus query) as its last argument, since no
+  route has matched yet: check it, or a redirect to `/login` redirects `/login` again.
+- `<MatchedRoute />` renders the active route; it belongs in the root component's `<body>`.
+- **A pipeline recovers to its `'error'` route** (unreleased): the route renders in the root,
+  with status 500 and `Cache-Control: no-store`, and the app keeps running. `.routes()` requires
+  one, as routing can always fail (a type error, for a returned tuple or object):
+
+  | Fails | Then |
+  | --- | --- |
+  | routing or route data | Post, then the `'error'` route |
+  | the all-routes data, with a fallback | the fallback is the data, Post, then the `'error'` route |
+  | Init; the all-routes data with no fallback; Post; the fallback; the render | the error page |
+
+  The fallback is the all-routes data function's second argument (also `serverAllRoutesData`,
+  `clientAllRoutesData`): a whole value of its type, or a function of the same arguments plus the
+  error, which may return a redirect. A static value is shared by every request, so never mutate
+  it. A redirect from the all-routes data wins over a route data throw. The route's data is
+  `{ error, message }`; in prod `message` is `'server error'`. In prod the page carries the
+  message only to the browser, as does a classic `'error'` route's; in dev it carries the error
+  too, with its stack. A client navigation recovers in place; past recovery it loads the page
+  from the server.
+
+  ```tsx
+  .allRoutesData(loadUser, (reqRes, init, location, error) =>
+      isUnauthorized(error) ? new WebRedirect(logInUrl(location)) : guestUser)
+  ...
+  .routes(() => [
+      ...,
+      { path: 'error', content: (info: TungstenErrorInfo) => <ErrorPanel message={info.message} /> },
+  ])
+  ```
+- **A pipeline's error page** (unreleased) is `.errorPage(Page)` before `.routes()`, for what
+  recovery cannot reach. `Page` extends the stage's
+  `ErrorComponent` and renders the whole document, `<html>` included: no root is around it. When a
+  request fails past recovery, after Init, the server sends it with status 500, with props
+  `{ error, message }`, Init's context and networked data (Post never ran), and
+  `this.tungsten.allRoutesData` that may be `undefined` (it may be what threw). On the prod server
+  `message` is `'server error'`, not the error's own; `error` is the thrown value either way,
+  server-side only. In prod the page carries only the message to the browser (in dev, the error
+  too), which hydrates it the same way, with client navigation off. Optional: without one, or when Init or the page itself throws,
+  the framework's error page is sent.
+
+  ```tsx
+  const withData = pipeline.server('express').init(...).allRoutesData(...)
+  class ErrorPage extends withData.ErrorComponent {
+      content = () => <html><head>…</head><body><p>{this.props.message}</p></body></html>
+  }
+  export const app = withData.post(...).errorPage(ErrorPage).routes(() => [...])
+  ```
+
+### Page caching
+
+The prod server sends each page with a `Cache-Control` chosen from named policies (0.7.1+):
+
+| Value | Header | Use for |
+| --- | --- | --- |
+| `'no-store'` | `no-store` | pages that must never be kept |
+| `'private-check'` | `private, no-cache` | per-user pages: only the user's browser keeps them, and checks back each time (a cheap 304 when unchanged) |
+| `'public-check'` | `public, no-cache` | pages the same for everyone: CDNs may keep them too, still checking back each time |
+| `{ privacy, maxAge, staleWhileRevalidate? }` | e.g. `public, max-age=300` | reused without checking for `maxAge` seconds; `privacy` is `'private'` or `'public'` |
+
+`public` lets a CDN serve one user's copy to another, so never use it on a page that shows
+per-user data. A `maxAge` page can be up to that many seconds out of date, including after a
+deploy.
+
+The most specific setting wins:
+
+```ts
+import { $cacheControl } from 'tungsten'
+
+export const routes = {
+    [$cacheControl]: 'private-check',                 // every route that sets none
+    '/docs': { content: <Docs />, cacheControl: 'public-check' },
+    '/feed': {
+        content: <Feed />,
+        cacheControl: ({ req }) => (req.query.live !== undefined ? 'no-store' : 'public-check'),
+    },
+    // ...
+}
+```
+
+A route's `cacheControl` (a value, or a function of
+`{ req, res }`) beats the routes object's `[$cacheControl]`, which beats config
+`defaultCacheControl`. With none of them set no header is
+sent, and a `Cache-Control` set by `serverMiddleware` is never overwritten. The error page and
+redirects are not affected. Static sites take their headers from their host.
+
+### The root component
+
+The root component replaces `index.html` — it renders `<html>`, `<head>` and `<body>` itself.
+
+**`<head>` content is not hydrated.** Event handlers placed there are never attached. The
+framework inserts its own scripts and stylesheets into the head.
+
+## Store and global data
+
+`registerStore(SchemaClass)` creates a typed reactive store. The schema is a **class**,
+constructed per app instance with the request context, which is what makes it safe under SSR —
+one store per request on the server, not a module-level singleton.
+
+```ts
+// Store.ts
+export class StoreSchema {
+    apiClient: ApiClient
+    authed: boolean = false
+    constructor(reqRes: ReqRes | null) { this.apiClient = getApiClient(reqRes) }
+}
+export const { getComponentStore } = registerStore(StoreSchema)
+
+// StoreComponents.ts — subclass once, use everywhere
+export abstract class SimpleStoreComponent<P, RD>
+    extends BaseSimpleStoreComponent<P, RD, StoreSchema> {
+    store = getComponentStore(this)
+}
+export abstract class StatefulStoreComponent<P, S, RD = unknown>
+    extends BaseStatefulStoreComponent<P, S, RD, StoreSchema> {
+    store = getComponentStore(this)
+}
+```
+
+Each store value exposes `.get()`, `.set(v)`, `.subscribe()`, `.unsubscribe()`, `.sync()`, and —
+since 0.6.1 — `.notify(fn)` and `.stopNotify(fn)`.
+
+**`sync()` = get + subscribe this component.** Use `sync()` when reading from `content` and the
+component should re-render on change; use `get()` for a one-off read, such as pulling a client out
+to make a call. Subscriptions are cleaned up when the component is deleted.
+
+```tsx
+const client = this.store.apiClient.get()      // just need the object
+const authed = this.store.authed.sync()        // re-render when this changes
+this.store.authed.set(true)
+```
+
+**`notify(fn)` runs a callback on every write, instead of re-rendering.** Use it for a side effect
+a value should trigger — closing a menu, starting a timer, calling out — where `sync()` would be
+wrong because nothing in the markup depends on the value. The callback receives the new value, and
+`notify` returns the function so it can be kept for `stopNotify(fn)`.
+
+```tsx
+init = () => {
+    this.store.authed.notify(authed => { if (!authed) this.closeMenu() })
+}
+```
+
+Callbacks registered from a component are released when that component is deleted, like
+subscriptions — there is no need to call `stopNotify` in a teardown hook. `notify` runs on writes
+only; it does not fire with the current value on registration.
+
+The framework's own store is reached through `this.__instance.internalStore`. Its values are not
+bound to a component, so pass it — from a store component, since that is the type they take:
+`.sync(this)`, `.notify(fn, this)`. Two of them are read-only
+(0.6.2+): `navigating` (a client navigation is in progress) and `navigationIndex` (counts
+navigations) have no `.set()` — `goto()` writes them, and a test harness can't supply them.
+
+```tsx
+content = () => this.__instance.internalStore.navigating.sync(this) ? <Spinner /> : null
+```
+
+The store is for genuine cross-component state. Keep form and page state in `this.state`. Do not
+push fetched page records into the store merely to avoid passing props — that is what route data
+and props are for. The store may hold non-serializable services as well as data.
+
+For request-scoped values available to every component, `registerGlobalData(async reqRes => ({…}))`
+plus a declaration-merged `interface GlobalData` gives you `this.globalData`. The function runs
+before any route renders: before SSR, with the request, and (0.7.1+) again before each
+client-side navigation, with `reqRes` null, in parallel with the route's data. Its result replaces
+the global data as the new route renders. The server's result is serialized into the page for
+hydration, so it must be serializable.
+
+**Context (0.7.1+).** `registerContext` supplies an object made fresh for each server request,
+and once per page on the client (it survives client-side navigation):
+
+```ts
+registerContext({ client: ClientContext, server: ServerContext }) // new ServerContext(reqRes), new ClientContext()
+registerContext(Context)                                          // one class: new Context(reqRes | null)
+```
+
+Register it in code the routes file loads. The context is the routes function's second argument,
+each store schema's fourth constructor argument (after `reqRes, globalData, matchedRouteInfo`), and
+`this.__instance.context`. It is untyped (`unknown`) for now: annotate the parameter with your own
+classes, e.g. `(reqRes, context: ClientContext | ServerContext) => routes`. Test harnesses take a
+`context` option.
+
+## Styling
+
+Component styles are a class field set to a tagged template. **`Css`, `Sass` and `Scss` are
+ambient globals** — declared in `tungsten/types/index.d.ts`, so there is no import. (Less is not
+implemented.)
+
+```tsx
+style = Sass`
+    .panel
+        display: grid
+        gap: 0.6rem
+`
+```
+
+Sass `@use` and imports of `.sass`/`.scss` files work inside the tag. For genuinely global
+styles, import a `.sass` file — the import yields an href string — and render it as
+`<Stylesheet>{baseStyles}</Stylesheet>` in the root's `<head>`, which emits a `<link>` and lets
+the browser cache it. An inline `css="…"` attribute is also available on elements.
+
+In a production build (0.7.1+) URLs to the site's own files get a `?v=<content hash>` query, and
+those URLs are served with a one-year `immutable` cache. A new deploy changes the hash, so browsers
+fetch the new file. It covers the framework's bundle and component CSS, and every file in `public/`,
+the compiled stylesheets and `assets/`. For these it is automatic: any element's `src`, `href`,
+`poster` or `srcset` naming one of those files exactly is versioned when rendered, so
+`<Stylesheet>{baseStyles}</Stylesheet>` and a hand-written `<img src="/logo.png" />` both get it.
+A URL built in code (a `fetch`, an inline style) gets it through
+`this.tungsten.fileUrl('/logo.png')`, which also adds the site base path. Not covered: URLs that
+already carry a `?` or `#`, and `url(...)` inside CSS. Dev URLs carry no version.
+
+### How scoping works — and the mistake to avoid
+
+Every selector in a component's `style` is rewritten to a class private to that component, and
+that class is stamped onto the elements **the component itself renders**.
+`dist/postcssPlugins/TransformCssNames.js` is the authority: a class selector `.panel` becomes
+`Thing_panel`; a bare tag selector `div` becomes `Thing_#_div`.
+
+Two things follow.
+
+**First, tag selectors become class selectors, so a tag and a class have equal specificity** —
+unlike ordinary CSS. Order and explicitness matter more than you expect.
+
+**Second — the common error — a component cannot style markup rendered by a child component.**
+This is deliberate encapsulation. React CSS Modules leak here; Tungsten does not.
+
+```tsx
+<nav className="user-links">
+    <Link to={`/users/${user.id}`}>Profile</Link>
+</nav>
+```
+
+renders as `<nav class="user-links User_user-links"><a href="/users/3">Profile</a></nav>`. The
+anchor belongs to `Link` and carries none of this component's classes, so:
+
+```sass
+// ❌ compiles to a selector that can never match — the links stay unstyled
+.user-links
+    a
+        font-weight: 600
+```
+
+The rule is not an error, produces no warning, and simply does nothing. It is easy to write and
+easy to miss in review, so check it deliberately whenever you style something that turns out to be
+a component: `Link`, `BindableInput`, `BindableSelect`, `BindableTextarea`, and any component of
+your own.
+
+**The fix: name the component as the selector.** A capitalised name is transformed the same way a
+tag is; Tungsten generates the scoped class and passes it to that component as `className`
+automatically. There is no prop to write and no class name to invent.
+
+```sass
+// ✅
+.user-links
+    Link
+        font-weight: 600
+```
+
+Passing a class explicitly — `<Link className="user-link">` — uses the same mechanism by hand.
+Reserve it for cases the component selector cannot express: different styling for different
+instances of the same component, or a child that also needs a global class.
+
+Either way, **the child must accept a `className` prop and apply it**. Tungsten's own components
+do. When you write a component, accept `className` and put it on your root element (or merge it
+with `combineClassNames`) — that is what makes it styleable by a parent:
+
+```tsx
+type Props = { className?: string, label: string }
+
+export class Badge extends SimpleComponent<Props> {
+    content = ({ className, label }: Props) =>
+        <span className={combineClassNames(className, 'badge')}>{label}</span>
+}
+```
+
+Parent rules that land this way still beat the child's own: component styles are emitted with
+4× stacked class selectors (`.C.C.C.C`), so a parent overrides a child's internals. `!important`
+is a last resort.
+
+**Escape hatch:** `:i(<selector>)` — or its long form `:ignore(<selector>)` — pierces scoping:
+`button :i(span)` reaches spans inside child components. Reserve it for third-party or legacy components that do not accept a `className`.
+Reaching for it on a component you control means that component should have taken a `className`
+instead.
+
+### Class attribute
+
+Both `class` and `className` work in JSX, but **`className` is the canonical internal prop** —
+scoped styling reads and rewrites it, and the renderer converts it to the HTML `class` attribute.
+Prefer `className` consistently, for native elements and components alike, so behaviour does not
+change when an element becomes a component or a prop is forwarded. Build dynamic lists with
+`combineClassNames`.
+
+## Rendering a string of HTML
+
+Use **`<ParseHtml>`** (the same component is also exported as `<RawHtml>`; prefer the `ParseHtml`
+name, which says what it does). It parses the markup into an ordinary content tree, so the result
+renders, hydrates and reconciles like anything else:
+
+```tsx
+<div className="tip-text"><ParseHtml html={tip.text} safe /></div>
+```
+
+| Prop | Effect |
+| --- | --- |
+| `html` | the markup. Anything unparseable is kept as text; it never throws |
+| `safe` | applies `safeHtmlAllowList` — formatting, lists, tables, links, images |
+| `allowList` | your own `HtmlAllowList`. Wins over `safe`. Disallowed elements are *unwrapped*, so no text is lost |
+| `sanitize` | defaults to on: drops `<script>`, `javascript:`/`vbscript:` URLs, and `data:` URLs in navigation attributes. `on*` attributes are always dropped |
+
+`parseHtml()`, `safeHtmlAllowList` and the `HtmlAllowList` type are exported for use outside a
+component.
+
+**The parsed elements are not part of any component's scoped CSS**, because no component rendered
+them. Component styles reach them only through `:i()` / `:ignore()`:
+
+```sass
+.tip-text
+    :i(p)
+        margin: 0 0 0.5rem
+```
+
+**Choosing a host element matters.** Authored HTML is usually block level — paragraphs, tables —
+and a `<p>` host cannot contain it: the parser closes the host at the first inner block tag,
+leaving it empty. That breaks hydration outright. Use a `div`.
+
+`dangerouslySetInnerHTML={{ __html }}` also works, and hands the markup to the browser as the
+element's inner content. Tungsten never reconciles inside it, so reach for it only when the markup
+must not be touched — `<ParseHtml>` is the default choice.
+
+### Markup that will be managed by hand: `<Protected>`
+
+For an element whose contents a library or your own code will mutate directly (an editor, a chart,
+a widget that owns its DOM), wrap the markup in **`<Protected>`**. It renders its children once and
+Tungsten never updates them again: a parent re-render skips the subtree, so the reconciler does not
+undo the manual changes. It does not stop the component's own updates, and it is a plain component,
+so the initial markup still renders server-side and hydrates. Its `children` is a `ContentNode`, so
+any JSX goes in without a cast — and markup you hold as a string goes in the same way through
+`<ParseHtml>` or the `parseHtml()` function, which parse an HTML string into a content tree, the
+same structure JSX compiles to:
+
+```tsx
+<Protected><ParseHtml html={widgetMarkup} /></Protected>
+```
+
+Prefer it over the older `<NativeHtml>`, whose children type is `ContentNodeHtml` and therefore
+needs a cast on any JSX child. The name is not final.
+
+**Avoid `__noEscape`.** It is an older switch that turns off escaping for an element's children.
+It inherits down the entire subtree, so nested Tungsten text also renders unescaped; it only ever
+worked server-side, so a client render escapes the markup into visible text; and it leaks into the
+markup as a literal `__noescape` attribute.
+
+### Inline scripts and styles
+
+The text children of `<script>` and `<style>` are emitted **verbatim** by the server renderer
+(`renderingTreeToHtml.ts`; test `src/render/rawTextElements.sxyt.ts`). So inline code is just a
+child string:
+
+```tsx
+<script>{themeBoot}</script>
+<style>{criticalCss}</style>
+```
+
+The React idiom `<script dangerouslySetInnerHTML={{ __html: code }} />` exists because React
+HTML-escapes script children; Tungsten does not, so the idiom is unnecessary — do not carry it
+over. As with any framework, the string itself must not contain `</script>`.
+
+A hand-written boot script that sets an attribute on `<html>` or `<body>` (theme, colour scheme)
+does not survive hydration. **Hydration reconciles attributes to what the component rendered and
+removes any it did not** (`reconcileHydratedAttributes.ts`), so the attribute is stripped the moment
+that element hydrates — reported in dev as a mismatch banner (`data-theme: rendered null, server
+sent …`), silently in prod. Deriving the value in `clientInit` does not help either: the first
+client render then differs from the server's markup. Two ways to make the renders agree:
+
+- **The server knows the value** — keep the preference in a cookie or the database, read it
+  server-side (`reqRes` / global data) and render the attribute from the root component. No script
+  needed.
+- **Only the browser knows it** (`localStorage`, `prefers-color-scheme`) — use
+  [`DocInit()`](#docinit--code-that-runs-before-body), which runs the script for you and hands the
+  same value to the client render.
+
+### `DocInit()` — code that runs before `<body>`
+
+`DocInit` is an ambient global, like `Sass` — no import. Its function is inlined into the document
+head as a synchronous script, so it runs on every full page load before `<body>` exists, before
+first paint and before the app bundle. The call evaluates to that function's return value on the
+client, and to the second argument on the server:
+
+```tsx
+export class Root extends SimpleStoreComponent {
+    theme = DocInit(() => {
+        const theme = localStorage.getItem('theme') ?? 'light'
+        document.documentElement.dataset.theme = theme
+        return theme
+    }, 'light')   // what the server sees; DocInit(() => { … }) alone is the void form
+
+    content = () =>
+        <html data-theme={this.theme}>…</html>
+}
+```
+
+**Render whatever the script changed from the value it returned**, as above. Hydration compares the
+client render with the live DOM, so the attribute the head script set and the attribute the client
+render produces agree, and nothing is stripped. Markup rendered from the server value that the
+script did *not* also change is still a mismatch.
+
+The rules, enforced at build by `BabelTransformDocInit` with a code frame:
+
+- **The function must be self-contained.** Only browser globals (`document`, `localStorage`, …)
+  exist in the head. A module import, an outer variable, `this` from the class, a named function
+  passed by reference, parameters, `async` and generators are all build errors. Write helpers
+  inline in the function.
+- **Only a direct call of the global is recognised.** An alias (`const D = DocInit`) or a wrapper is
+  not rewritten, and reaches a stand-in global that throws naming the cause. A local binding named
+  `DocInit` is left alone.
+- **A throw halts the page — there is no fallback** to the server value. The error appears in the
+  console where it happened, a read of the value throws, and in dev a red banner names the call
+  site. Guard what can fail (`localStorage` throws when site data is blocked) inside the function.
+- **The value is fixed for the page load.** It is not reactive; copy it into state or the store in
+  `init` if it can change later, and update the DOM yourself when it does.
+- **An HMR edit to a module using `DocInit` falls back to a full reload**, since the head script
+  only runs on a full load.
+
+Tests run compiled output without the build transform, so the global is the throwing stand-in.
+Call `installTestDocInit()` from `tungsten/testing/installTestDocInit.js` in the test setup: it runs
+the function where a `document` exists and returns the server value where it does not.
+
+## Form binding
+
+The bindable components give two-way binding to any object property:
+
+```tsx
+<BindableInput name="email" bind={[this.state.form, 'email']} />
+<BindableSelect name="role" bind={[this.state.form, 'role']} options={roleOptions} />
+<BindableCheckbox name="active" bindChecked={[this.state.form, 'active']} />
+```
+
+The family is `BindableInput`, `BindableInputTyped`, `BindableCheckbox`, `BindableRadio`,
+`BindableSelect`, `BindableTextarea`. `bind={[object, 'key']}` accepts state, a nested state
+object, or a plain instance property. Binds take an optional `filter` to transform or validate
+incoming values before they reach the property — the usual use is converting an input string to
+the field's real type.
+
+`BindableSelect` takes either an `options` array of `{ value, text }` structs or ordinary JSX
+children (`<option>`, `<optgroup>`, conditionals). Prefer `options` when the values form a literal
+union: `value` is how option values reach the type system, and with children they degrade to
+`string`. As with a plain `<select>`, `placeholder` does nothing — supply a leading empty-valued
+option instead. See `src/components/bindable/BindableSelect.md` before changing that component.
+
+A common and reasonable application pattern is to hold form values as strings in state and convert
+to the domain type on submit, since browser inputs produce strings.
+
+## Environment
+
+Applications register Standard Schema schemas (zod, valibot, arktype…) from the module named by
+`envSchemasLocation`: `registerPrivateEnvSchema(schema)` (server only) and
+`registerPublicEnvSchema(schema)` (shipped to the client), both imported from `tungsten`; either
+may be omitted. Tungsten imports that module for its side effect, loads `.env` files, validates
+them at startup, and injects the public values into the client bundle. The old protocol of two
+named exports, `privateEnvSchema` / `publicEnvSchema`, is no longer read and fails loudly.
+
+Access is through **ambient globals**, no import: `tungstenPrivateEnv` and `tungstenPublicEnv`.
+Type them by declaration-merging `TungstenPrivateEnv` / `TungstenPublicEnv` in `declare global`.
+
+- Never expose a private value to client code, and never copy one into the public schema or file.
+- Add every new variable to the appropriate schema and to the sample env file.
+- Code that runs outside Tungsten startup (standalone scripts, some test setups) must bootstrap
+  the globals itself before importing modules that read them.
+
+Tungsten reads four variables of its own, which your schemas must declare like any other:
+`TUNGSTEN_SERVER_PORT` (private) and `FRONTEND_PROTO` / `FRONTEND_HOSTNAME` / `FRONTEND_PORT`
+(public). Both ports are validated as numbers `>= 0`.
+
+- `TUNGSTEN_SERVER_PORT` is the port the server binds; unset means 3000. **`0` asks the OS for a
+  free port** (0.6.0) and `tungsten dev` reports the one it took. `tungsten start`
+  rejects `0` — production needs a fixed address.
+- The `FRONTEND_*` trio describes the address the **browser** uses, which is not the server's own
+  whenever a proxy sits in front. `FRONTEND_PORT` unset or `0` means "whatever port the server
+  bound", so a dev server on a random port still reports a usable URL. A default port is left out
+  of the URL: `https://site.example`, not `https://site.example:443`.
+- **`FRONTEND_HOSTNAME` was `FRONTEND_HOST`** (0.6.0). Rename it in your env files
+  and schema — under the old name the public address silently falls back to `localhost`.
+
+## Testing
+
+**Write the failing test before the fix, and watch it fail.** Then fix, and watch it pass. A test
+never seen red proves nothing — it may assert something that was already true, or never reach the
+code at all. If you have already written the fix, revert it, run the test, confirm it fails for
+the reason you expect, then restore it.
+
+Two things bite here in particular. The runner executes compiled JS, not your source — an app's
+test compile tree (`.tungsten/test` below), this repo's `dist/` — and a watch build may have
+rebuilt your change already: check that the red run really is testing the unfixed code. And put the test at the layer the bug lives at: `createTestApp()` renders on the client
+only, so a server-render or hydration bug can sit underneath a fully green suite.
+
+Test APIs live at `tungsten/testing`, not the main entry point. The test project supplies its own
+DOM implementation (happy-dom, jsdom):
+
+```tsx
+import { Window } from 'happy-dom'
+import { createTestApp } from 'tungsten/testing'
+
+const window = new Window()
+const testApp = await createTestApp(RootComponent, {
+    document: window.document as unknown as Document,
+    props: { initialName: 'Robert' },
+    location: '/',
+})
+
+try {
+    const button = testApp.container.querySelector('button')
+    button!.dispatchEvent(new window.Event('click') as unknown as Event)
+    await testApp.resolved()
+    expect(testApp.container.textContent).toContain('Robert')
+} finally {
+    await testApp.unmount()
+}
+```
+
+`createTestApp()` completes the initial client render before returning. `resolved()` then waits
+for Tungsten updates, DOM reconciliation, lifecycle-triggered updates, and promises returned by
+registered event handlers — but not unrelated timers or network requests. Casts are only needed
+when the DOM package's types are not structurally compatible with the TypeScript DOM library.
+An automatically created container is appended to the supplied document's body and removed by
+`unmount()`; a caller-supplied container must be empty, and is emptied but kept. Both
+`createTestApp()` and `hydrateTestApp()` are async-disposable (0.6.2+), so
+`await using testApp = await createTestApp(...)` unmounts at the end of the scope instead of a
+`try`/`finally`. Pass `routes` (an object, or a routes function — called with `null`, as on the
+client) to let components `goto()` for real (0.6.2+); without it the app has no routes and a
+navigation goes nowhere. Unlike an app's routes, these need no `'404'` or `'default'` route: a miss
+lands on the built-in "404 page not found", which the test's own assertions will catch. Tests
+containing Tungsten JSX must be compiled through `tungsten compile` so they use Tungsten's JSX runtime and
+transforms.
+
+`hydrateTestApp()` and `hydrateTestPipelineApp()` (0.7.1+) throw at once unless `isClient` is
+true: run them in a DOM suite whose `setup` puts happy-dom's `window` on the global before the tests
+are imported, since tungsten reads `isClient` when it loads.
+
+An app built with `pipeline()` or `splitPipeline()` (0.7.1+) has its own pair, imported from
+`tungsten/testing/pipeline` rather than `tungsten/testing`, taking the app (the routes module's `.routes()`
+export, or a smaller set built off the same stage) first:
+`createTestPipelineApp(app, Root, options)` runs the app's client stages and routes `location`
+against its routes; `hydrateTestPipelineApp(app, Root, options)` runs the server stages (with a
+stand-in request unless `reqRes` is given), renders, carries the all-routes and networked data as the
+page does, then runs the client stages and hydrates. A component whose store or markup comes from
+the pipeline's context needs these: `createTestApp()` and `hydrateTestApp()` run no pipeline, so its
+context is empty.
+
+`routesOf(app, reqRes | null)` (unreleased, same import) gives a pipeline app's routes as `host()`'s
+`routes` option takes them, for a component that reads the route table (a nav): it runs the app's
+Init for the side `isServer` says this is - the server's needs a request, and throws on `null` -
+and calls the routes function with its result. `routesOf(app, initResult)` skips Init and uses the
+result given, typed as the routes function's `init` parameter:
+`host(Nav, {}, { location: '/', routes: routesOf(app, { context }) })`.
+
+Stores are created independently per test app; initialize one with `testStore()` before the root
+component starts. Component tests that need the application's env globals opt in by calling
+`loadEnv({ buildLocation })` once from the test runner `setup` hook, where `buildLocation` is the
+test compile's output (`tungsten compile --output .tungsten/test` → `'.tungsten/test'`): the env
+schemas module is imported from that compiled tree, not the dev build's. `loadEnv()` loads env once
+per process and a missing/invalid env schema module is a hard error. `TUNGSTEN_TEST_ENV` (the
+variable name is exported as `testEnvVariableName`) only chooses which files: set it to prefer
+`.env.test*` over the base ones. The harness itself only waits for a load `setup` started
+(`waitForEnvIfLoading`), so a package that never calls `loadEnv()` loads nothing.
+
+### `host()` — a component without a DOM
+
+`createTestApp()` is the harness for anything that needs a document. When the question is only
+"what does this component render, and what do its handlers do", `host()` is the smaller tool: it
+constructs the component with a mock construct package, awaits `init`, runs the mount lifecycles,
+and hands back a wrapper.
+
+```ts
+import { host } from 'tungsten/testing'
+
+const hosted = await host(DataTable, { head, rows: [], columns: 2, emptyText: 'Nothing found' })
+
+hosted.content()                                  // content(props) or content(props, state)
+await hosted.updateProps({ ...props, rows })      // re-renders, runs the update lifecycles
+await hosted.updateState(state => { state.open = true })
+hosted.toggleRow(3)                               // the component's own methods, bound
+```
+
+- **`content()` takes no arguments.** It calls the content function with what that component's
+  flavour takes — `(props)` for a `TungstenSimpleComponent`, `(props, state)` for the rest — so
+  tests stop writing `component.content(component.props, component.state)` and stop casting when a
+  component's signature differs.
+- **`content()` gives the whole tree, not one component's output** (the default since
+  0.7.1; before, `resolve: true` asked for it). Every component in the tree is constructed and
+  asked for its content, down to html and text, and `content()`, `updateProps()` and
+  `updateState()` all hand back that tree. Resolution is async, so they are promises whatever the
+  component's own `content` returns — await them — and the wrapper's type is
+  `HostedResolved<Component>`. **`resolve: false`** hands back what the hosted component itself
+  returned, its child components unexpanded (`one.component('UserCard')` is there, the html it
+  renders is not); that `content()` is not awaited — an async `content` returns a promise, a sync
+  one the node, and the type (`Hosted<Component>`) says which:
+
+  ```ts
+  const full = await host(Page, { id: 7 })
+  ensure(await full.content(), [
+      ensure.one.component('UserCard').with.one.prop('name').is('Bob'),  // node and props kept
+      ensure.one.html('em'), ensure.one.text('Bob'),                     // what it rendered
+  ])
+  ```
+
+  A component node stays in the tree as written — its type, key and props — holding what it
+  rendered in place of the children it was passed, so a fact reads it by name, by prop, and by what
+  it put on the page. A component that ignores its children shows none of them. Child components
+  run their real `init` and mount lifecycles against the same store, internal store and recorded
+  navigations — so pass the store the *children* need, even where the hosted component has none.
+  With a partial store, a key a child reads that the options did not supply names itself, as it
+  does for the hosted component, except in the child's own `init`, which has run by then. A
+  component the app renders on the client alone (`render`) resolves to its placeholder, its content
+  never run.
+- **`contentToString(tree)` shows a tree as JSX** (0.7.1+, from `tungsten/testing`), to read
+  what a component rendered: `console.log(contentToString(await hosted.content()))`. A resolved
+  component's output sits under it, marked `⤵`; the children it was passed show as
+  `children={...}`, in full with `{ children: true }`. One unresolved nests its children as written.
+  A tree that renders nothing shows what it was (`{null}`, `{false}`, `{[]}`); inside a tree such
+  values are left out, as the page leaves them. Text with spaces at an edge is quoted (`{'Save '}`).
+  Fragments are hidden, their text running on as the page and `ensure()` text facts join it;
+  `{ fragments: true }` shows them:
+
+  ```
+  <div id='page'>
+      <Middle name='Bob'> ⤵
+          <p>Hi, Bob.</p>
+      </Middle>
+  </div>
+  ```
+- **Nothing re-renders on its own.** The construct package is marked `hosted`, so state is not
+  proxied on either side; `updateProps` and `updateState` are the renders. `updateState` takes
+  `(state) => newState | void`, so mutate it or return a replacement.
+- **No starting state and no app state.** The component inits and renders as it really would.
+  The internal store gets `location` (the option, else `/`) and empty `popMessages`, and a matched
+  route only if the options give one. Reading a key nothing
+  supplied throws, naming the key. If the component needs a real app, it needs `createTestApp()`.
+- **The side is the process's.** `host()` has no client/server option: `isClient`/`isServer` are
+  what the framework and your components both read, so a plain node run is the server
+  (`serverInit`). To test the client, install a window and DOM (happy-dom, jsdom) in the test
+  runner's setup, before anything imports tungsten.
+- `hosted.title` and `hosted.navigations` record what the component tried to do to the document
+  title and the router; both are recorded rather than carried out. A lifecycle failure is thrown
+  rather than logged, so a test cannot pass over one.
+- **Literal props are typed by the component** (0.5.4+, also `createTestApp()`), so
+  `{ type: 'success' }` or `bind: [form, 'value']` needs no `as const`. Before 0.5.4 they widen to
+  `string` and arrays and fail against the component's props — annotate them. For a *generic*
+  component a bare tuple still widens in any version: annotate it
+  (`const bind: TypedBindVariable<Form, 'value'> = [form, 'value']`).
+- **The third argument is the options** (`HostOptions<Component>`), required for a store
+  component. A component without a store of its own takes the store forms too (0.7.1+) — it
+  may hold children that have one, which resolving constructs against the same instance —
+  but with the schema unchecked, there being no class of its own to check it against. A store
+  component is given its store one of four ways: `store` (a real `makeStore` store, its cells
+  keeping state, so one can be shared between
+  hosts), `storeData` (a value per key, each wrapped in a cell of its own), or the partial opt-ins
+  `partialStore` / `partialStoreData`, where a key left out throws, naming itself, when read.
+  Routing: `location` (a `/path`), `routes`, and either `matchedRoute: { key, params?, data? }`
+  stated by the test, or `routing: true` to have `host()` match `location` against `routes`
+  itself. The location defaults to `/` (0.7.1+; before, it had none). There is no default
+  route: a component that reads one the test did not give throws, naming it. An internal-store component takes those routing options, not a store.
+  `HostOptions`, `HostStoreOptions`, `makeStore` and `TrueStore` are all exported from
+  `tungsten/testing`, so a test file needs no second import for them. For a wrapper that fixes
+  `resolve`, `HostResolveOptions` / `HostDontResolveOptions` (per component) and
+  `HostStoreResolveOptions` / `HostStoreDontResolveOptions` (per store schema) are the same
+  options with `resolve` settled (0.7.1+), so no distributive `Omit` is needed.
+- **A real store for tests** is `makeStore(schema, new Map())`. The second argument is the
+  subscribed-elements map the store's cells share; a fresh `Map` is right for a test. Cells are
+  branded, so a hand-rolled `{ get, set, … }` object is not a `TrueStore` and will not type-check:
+  make one with `makeStore`, or give `host()` values through `storeData`. Stub what the schema
+  holds before handing it over, an API client above all:
+
+  ```ts
+  const schema = new StoreSchema()
+  schema.apiClient = stubClient           // a stub, not a real client
+  const store = makeStore(schema, new Map())
+  ```
+- **`serverInit` runs under `host()`.** A plain node run is the server, so a store component whose
+  `serverInit` calls the API reaches whatever client its store holds. Stub the client through the
+  store, as above.
+- **Class components only.** `host()` takes a component class. A function component is a
+  function: call it.
+- **`hostJsx()` takes the element instead** (0.7.1+), for a test that reads as the page does:
+
+  ```ts
+  const hosted = await hostJsx(<DataTable head={head} rows={rows} columns={2} />)
+  ensure(await hosted.content(), [ensure.one.html('table')])
+  ```
+
+  It is `host()` underneath, with the same options and the same lifecycles, given the class and
+  props off the element. The cost is types: TypeScript types every JSX expression as `JSX.Element`,
+  so the element does not carry the component it names, and the wrapper comes back as the base
+  component — `props` and `state` are `any`, the component's own methods are not on it, and
+  `content()` is `ContentNode | Promise<ContentNode>`, so `await` it. Naming the component in the
+  call restores all of that: `await hostJsx<DataTable>(<DataTable … />)`. Reach for `hostJsx()`
+  when the test asserts the content, and `host()` when it drives the component through the
+  wrapper's api. An element that is not a class component — an html tag, a fragment, a function
+  component — throws, naming what it was given. Also on `host.jsx()` (0.7.1+).
+- **`host.generic()` for a component class that is generic** (0.7.1+). It takes the class in a
+  call of its own, then the props:
+
+  ```ts
+  const hosted = await host.generic(BoundValue)({ bind: [form, 'value'] })
+  const own = await host.generic(BoundValue, { resolve: false })({ bind: [form, 'value'] })
+  ```
+
+  Plain `host()` cannot infer such a class's type arguments: passed as an argument, its own type
+  parameters are erased to their constraints before the props are looked at, so a tuple prop like
+  `bind: [form, 'value']` widens to an array and the class stops fitting — `Target requires 2
+  element(s) but source may have fewer`. Annotating the prop (`const bind: TypedBindVariable<Form,
+  'value'> = [form, 'value']`) is the way round it with `host()`; `host.generic()` needs no
+  annotation and checks the props against the component the way JSX does. Options go on the first
+  call, not the second — that is what keeps the inference working.
+- **A generic helper can wrap it without a cast.** Store components resolve to an
+  overload whose schema is its own type parameter, inferred from the class, so a project helper
+  such as `<C extends TungstenBaseComponent<any, any> & { store: ComponentStore<Schema> }>(Type,
+  props, store) => host(Type, props, { store })` type-checks while `C` is still generic. The
+  store options are checked as before, and a wrong schema or a store-less component is rejected
+  at the `host()` call inside the helper. `HostStoreOptions<Schema>` is the options type for a
+  schema, for a helper that builds on it, say making `store` optional with a mock default. It is
+  a union (the four store forms times the two routing forms), so `Omit` it through a conditional,
+  which distributes; a plain `Omit<HostStoreOptions<S>, 'store'>` merges the routing variants,
+  `routing` widens to `boolean`, and `host()` rejects the result:
+
+  ```ts
+  type OptionalStore<V> = V extends unknown ? Omit<V, 'store'> & { store?: TrueStore<S> } : never
+  type Options = OptionalStore<Extract<HostStoreOptions<S>, { store: unknown }>>
+  ```
+
+  Before this, `host()`'s argument tuple was conditional on the component, which a still-generic
+  component cannot satisfy, so such helpers cast.
+
+### `ensure()` — facts about a content tree
+
+`ensure()` states what a content tree holds, with no DOM and no string of HTML in between
+(0.7.1+). It takes the tree and a list of facts: a passing call is its own assertion, and a
+failure throws `EnsureError`, naming the fact and what it saw, with the `actual` / `expected` /
+`showDiff` fields a runner reads for a diff and a stack that starts at the `ensure()` call.
+
+```ts
+import { ensure } from 'tungsten/testing'
+
+ensure(hosted.content(), [
+    ensure.one.html('form'),
+    ensure.two.html('input').with.one.prop('name'),
+    ensure.count(2).text('Bob'),
+    ensure.no.html('video'),
+])
+```
+
+**The model is sightings, one flat list, a kind each.** The tree is flattened in document order into
+sightings: text, html elements by tag, components by the name stylesheets match, fragments, an
+element's classes one at a time, its id, and every prop but `children`. A fact meets only sightings
+of its own kind, and its quantifier counts the ones that *match* — so
+`no.html('a').with.one.prop('href')` says "no `a` with an href", not "no `a`". Depth does not
+matter: the walk goes through html elements, fragments and a component's children as written, so a
+fact at the top finds an element at any level.
+Text is joined as the page shows it — `Hi, {name}.` is one sighting, a number is text, a fragment
+does not break a run, an element either side of one does.
+
+**Two things the walk does not enter.** A prop other than `children`: an element in
+`rows={[<tr/>]}` is a `prop:rows` sighting and nothing more until a fact opts in with `.content()`.
+And a component's rendered output where the tree does not hold it — the tree is the one given, so
+in a tree as written a component is read by name and by prop, not by what it renders. `host()`'s
+`content()` resolves by default, holding both (with `{ resolve: false }`, the tree as written); the
+facts are the same either way.
+
+**Quantifiers**: `no` / `none`, `one` (`a` and `an` read the same), `two`, `three`, `count(n)`,
+`some` (one or more), `all` (every sighting of the kind matches, and there is at least one — all
+of none proves nothing). Each is on `ensure`, as `ensure.one`; the bare forms, for facts written
+inside a scope, come from the deep import:
+`import { one, two, children } from 'tungsten/testing/ensure.js'`.
+
+**Ends** — what a sighting has to be:
+
+- `text('Bob')`, `text.contains('ob')`, `text.matches(/^B/)`, and `textCi` for the same three
+  ignoring case. `g` and `y` flags are dropped, so one regex is safe across sightings.
+- `interruptedText('BobAlice')` — an element's whole text with the markup between the words
+  ignored, as `textContent` reads it; `.contains` and `.matches` too.
+- `html('button')`, `component('Badge')`, `fragment()`.
+- `select('nav > a.active')` — the elements a CSS selector matches (0.7.1+), counted by any
+  quantifier and scoped like `html()`: `all.select('.bar').with.one.prop('data-t')`. Names are
+  case-sensitive, and a capitalised one is a component, by the name `component()` matches, and it
+  is the parent of what it holds: `select('Link > a')`, not `select('nav > a')`. Attributes are
+  the props: `class` reads `className`, `for` reads `htmlFor`, `true` is present, `false`, `null`
+  and `undefined` absent; a component's `className` and `id` are no class or id. `:has()`,
+  `:not()` and the rest work. A scope is a tree of its own, so inside `.with.children` a selector
+  sees no ancestor outside it. `select` is not taken by `with`: a match's own tag, classes and
+  attributes go in its selector (`select('nav.main:has(a)')`).
+- `className('card')`, `id('page')` — one class at a time; with no argument, that it has one.
+- `prop('href')` — the prop is there, whatever its value, `undefined` included. Then `.is(value)`
+  (`===`, so a handler or ref matches by reference), `.contains(text)`, `.matches(regex)`,
+  `.exact(value)` (deep equal), `.subset(shape)` (extra keys and array elements pass, each shape
+  element matching some element in any order), `.duck(shape)` (extra keys pass, but an array is a
+  tuple: same length, in place), and `.content()` (the value is content; given facts, its tree).
+
+**Scopes tie facts to one element.** Two facts in the list are independent —
+`one.html('button').with.one.prop('disabled')` and
+`one.html('button').with.children.one.text('Save')` can be met by two different buttons. To say one
+button is both, put both facts in the same scope:
+
+- `.with([…])`, or chained as `.with.one.prop('name')` — properties of the match itself: `prop`,
+  `className`, `id`, `interruptedText`, and `children` facts. `html`, `component`, `select`,
+  `fragment`, `text` and `textCi` are not properties, so `with` does not take them (a type error;
+  0.7.1+) — what the element holds is `.with.children`.
+  `.with(props => boolean)` is the escape hatch for what facts cannot say, and the function's name
+  is what the failure shows.
+- `.with.children([…])`, or `.with.children.one.text('Save')` — facts on the content it holds.
+- `children([…])` and `children.one.html('li')` — the same children facts, written for a `with`
+  list, so they mix with the element's own facts and all of them apply to that one element:
+
+  ```ts
+  ensure(tree, [
+      ensure.one.html('button').with([
+          one.prop('disabled').is(true),
+          children.one.text('Save'),
+      ]),
+  ])
+  ```
+
+A failure states the fact as prose, with the fact as written on a `rule:` line, and lists the
+sightings of its kind with the reason each one missed, down through the scopes. A reason names
+every inner fact the sighting missed, then those it met (`met: …`), and the nearest misses are
+listed first, ahead of the cap of 10. Where stdout has colour, sightings are white, misses red and
+facts met green; `{ color: false }` turns it off (0.7.1+):
+
+```
+ensure: expected one <a> with one href="/y", saw 0
+  rule: one.html('a').with.one.prop('href').is('/y')
+  ·
+  <a> seen:
+    <a href='/x'> (one href="/y": saw 0)
+```
+
+`ensure(tree, facts, { readable: false })` states it only as the fact was written:
+
+```
+ensure: expected one.html('a').with.one.prop('href').is('/y'), saw 0
+  html:a seen:
+    <a href='/x'> (one.prop('href').is('/y'): saw 0)
+```
+
+### `tungsten compile` — preparing code for tests
+
+A one-shot dev compilation without a server. By default it compiles JavaScript (JSX and the Babel
+transforms), stylesheets, client support files, assets and public files into `.tungsten/dev`,
+cleaning each selected target's existing output first (`--no-clean` keeps it). `--output <root>`
+selects an independent output root with the same layout (`code`, `.client`, `.static`, `.assets`,
+`.public`, `.componentCss`, `.packages`); cleaning and the package cache are scoped to it. Limit
+the work with `--js`, `--css`, `--client`, `--assets`, `--public` (`--all` is the explicit
+default). `--watch` keeps the js, css, asset and public compilers running; client support files
+are generated once. For orchestration, `--ready-file <file>` writes a small JSON file only after
+the initial compilation succeeds (removed by a failed watch cycle, recreated by the next success),
+and `--quiet` drops per-file messages but keeps errors and cycle status:
+
+```sh
+tungsten compile --watch --output .tungsten/test --ready-file .tungsten/test.ready --quiet
+```
+
+Test files are left out of every compile unless `--tests` is passed: mark them in config with
+`testDirs` / `testPatterns` (the same two shapes as `ignoreDirs` / `ignorePatterns`, which drop
+files from every pipeline; `--ignore-dirs` / `--ignore-patterns` override those two from the
+command line). **On upgrade, add `--tests` to the test compile**, or it emits no test files and
+the runner finds nothing to run. Whether that fails CI is the runner's call: sxy-test-runner 2.4.12
+exits 3 for "no test files", earlier versions used other codes, and a runner that treats it as a
+pass goes green having run nothing, so check for the "no tests" case rather than assume. `--packages` also compiles imported packages into the build's `.packages` tree for
+the dev server to serve; it is off by default, and a use for it outside the dev server has not
+come up, since compiled code left to node's own resolution needs none of it. Which sources each
+pipeline compiles is set by `clientDirs` / `clientPatterns` (compiled for the browser with every
+plugin, into `.tungsten/<mode>/code`) and `rawDirs` / `rawPatterns` (compiled for node with types
+stripped and imports untouched, into `.tungsten/<mode>-raw`, for server middleware and the like).
+Each pipeline compiles **its selection and not the ignores**: client and not ignore, raw and not
+ignore. Unset, the client selection is everything and the raw selection is nothing; a file may be
+in both. Because the ignores win, ignoring server code also removes it from the raw pipeline: that
+is fine when the app's own build emits the server into `codeDir` (e.g. `ignoreDirs: ['server']`),
+but to have Tungsten compile it, narrow `clientDirs` and put it in `rawDirs` instead (e.g.
+`clientDirs: ['client', 'common'], rawDirs: ['server', 'common']`). Keep node-only modules out
+of the client set: the client pipeline does not tolerate imports of node built-ins when it
+compiles packages, which the dev server does. `--fresh` ignores the packages and styles caches.
+`sourceMaps: true` in `tungsten.config.js` appends an inline source map to each
+compiled app file in both pipelines, for `tungsten compile` and the dev server alike, chained
+through any map the source already references (e.g. tsc's `.js.map`), so debuggers (and node run
+with `--enable-source-maps`) point at the original source. Packages in `.packages` and the
+production bundle are not mapped. `tungsten compile --source-maps` / `--no-source-maps` override
+the config entry for one compile.
+
+`skipPackageCompilation` in `tungsten.config.js` (one glob or an array, matched against the
+JavaScript files Tungsten receives, extensions untranslated) names files to transform and emit
+without traversing or copying their package dependencies; bare package imports in them are left as
+they are. Example: `'**/*.domTest.js'`.
+
+## Dev server behaviour
+
+Things that look like application bugs but are not:
+
+- **HMR is on by default.** A source edit hot-swaps the changed component in place, keeping its
+  position, props and state, and swaps CSS without a reload; anything it cannot handle falls back
+  to a full page reload. The `hmr` config option picks the branch: `true` (default), `'reload'` for
+  a plain full reload on every change, `false` for no live reload at all. Design and limits are in
+  `docs/hmr.md`.
+- **Server modules are re-imported per request.** The dev server busts Node's ESM cache with an
+  incrementing query string so server changes are picked up without a restart. Two consequences:
+  - **Module-scope singletons are not singletons.** A database client or connection pool created
+    at module scope in your server code is rebuilt on nearly every request, and old pools are not
+    released — under load this exhausts the pool. The framework-sanctioned fix is the
+    **`._cached_` filename convention**: the loader (`dist/moduleReloader.js`) exempts any module
+    matching `*._cached_.{js,ts,jsx,tsx,…}` **and its dependency graph** from reloading. Put the
+    client construction in e.g. `server/db/client._cached_.ts` and re-export it.
+  - **A flat per-request latency** before any endpoint code runs, which grows with the number of
+    first-party server modules, because the entry module's whole import graph is re-imported. It
+    is the same for a database-free endpoint and for a 404. Do not chase it in application code;
+    it does not exist in a production build.
+- Tungsten's own env globals *do* reload per page request, but a plain static import inside a
+  middleware module resolves to the cached instance — so app-level env read at module scope by
+  your own middleware still needs a restart.
+- **Startup fails loudly if the port is not fully yours** (0.6.0). Both servers
+  reject on a bind error, and after binding fetch their own boot id from `/__tungsten_boot_probe__`
+  over `127.0.0.1` and `::1`; if another process answers on either, or accepts and never answers,
+  `tungsten dev`/`start` exits non-zero naming the address and the reason, instead of printing
+  "ready" while a stale server takes the traffic. Stop the other server and start again.
+- **`TUNGSTEN_SERVER_PORT=0` starts dev on a free port** (0.6.0). The ready line
+  names the port taken, and the browser opens on it. Pairing a random port with a fixed
+  `FRONTEND_PORT` warns at startup: a proxy cannot be pointed at a port that changes every boot.
+- **The origin-mismatch warning compares hosts, not whole origins** (0.6.0). It
+  fires when a request carries an `Origin` matching your configured frontend but arrives at a
+  different host — the case where cookies silently do not travel. The scheme is ignored on purpose:
+  Tungsten always serves http, so behind a TLS-terminating proxy every request would otherwise look
+  like a mismatch, which is what earlier versions reported. `suppressOriginMismatchWarning: true`
+  turns it off; the production server repeats it at most once a day per host.
+
+## Everyday workflow
+
+1. Add or adjust the API endpoint and its tests.
+2. Add the route and its `data` loader for the page's initial read.
+3. Build the page as a typed class component; use the store wrapper only if it needs shared state.
+4. Bind ordinary form fields; call the API from event handlers for mutations.
+5. Handle every result status the endpoint can return, then refresh local or route data.
+6. Type-check, then run the test suite.
+
+## Things to avoid
+
+The principle behind most of these: **do not deviate between the server render and the client
+render.** In the normal flow the two are identical, and hydration depends on it. The only sanctioned
+deviations are updates after the first render, `DocInit()` mutations made before hydration, and
+client-only rendering — `csr: true` in config (the body ships empty and the client mounts fresh),
+`serverSideRouting: false` (the head's children too, and the client fetches the data), or a
+component's `static render = 'client'` / `static render = { location: 'client', placeholder }`
+(the server emits the placeholder, the client renders the component). Anything else that makes
+the first client render differ from the server's markup is a bug, not a technique.
+
+- Do not use `setState`, immutable state updates, or React hooks. Mutate state directly.
+- Do not mutate state inside `content` or anything it calls.
+- Do not write a descendant selector for markup a **child component** renders — name the
+  component as the selector instead. Check this every time you style what turns out to be a
+  component.
+- Do not rely on tag-vs-class specificity in scoped styles; they are equal.
+- Do not fetch a page's initial data only in `clientInit` — it loses SSR and the first render.
+- Do not touch browser globals in `init`, route code, or `content` without a guard; use
+  `clientInit`.
+- Do not produce environment-dependent output during render — it breaks hydration.
+- Do not bypass `<Link>` for a path that should stay client-side.
+- Do not put page-local state, or fetched records, in the global store to avoid passing props.
+- Do not set `title` on anything but a page component.
+- Do not create module-scope connections or caches in server code without the `._cached_`
+  convention.
+- Do not put event handlers in `<head>` — it is not hydrated.
+- Do not use `dangerouslySetInnerHTML` for inline `<script>`/`<style>` code — their children are
+  not escaped; write `<script>{code}</script>`. And do not expect an attribute a boot script sets on
+  `<html>`/`<body>` to survive hydration unless the root component renders it too.
+- Do not "correct" `.jsx`/`.js` import extensions in `.tsx` source.
+- Do not treat the published documentation's names and examples as definitive over the installed
+  declarations.