odoro 1.0.9 → 2.0.0

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-export { startPreviewServer } from './chunk-ZVL7EXJO.js';
-export { defineConfig, loadConfig } from './chunk-DL3NPC4H.js';
+export { startPreviewServer } from './chunk-PRWVZ2SM.js';
+export { clientEnv, defineConfig, loadConfig, loadEnv } from './chunk-QOVBLN7A.js';
 import './chunk-T6RLHSCW.js';
-export { buildProject, reportBuild } from './chunk-22KJTV2R.js';
-export { ModuleGraph, detectSelfAccepting, optimizeDeps, scanDependencies, startDevServer } from './chunk-LHZGX5ML.js';
-export { depFileName } from './chunk-TQUJ3MFS.js';
-import './chunk-JMEHF3KN.js';
+export { buildManifest, buildProject, chunksFor, prerender, reportBuild } from './chunk-Q2KCMTB5.js';
+export { ModuleGraph, detectSelfAccepting, optimizeDeps, scanDependencies, startDevServer } from './chunk-OMHEQVIW.js';
+export { depFileName, hasGlob, transformGlob } from './chunk-WWTDEV4Y.js';
+import './chunk-7ZB5MAM6.js';

package/dist/{package-EIDLKAA6.js → package-T4Z7OBOH.js}

@@ -2,11 +2,11 @@
 // package.json
 var package_default = {
   name: "odoro",
-  version: "1.0.9",
+  version: "2.0.0",
   type: "module",
   license: "UNLICENSED",
   author: "BouBouw",
-  description: "Moteur de developpement et echafaudage Odoro : odoro create, dev, build, preview.",
+  description: "Odoro development engine and scaffolder: odoro create, dev, build, preview.",
   engines: {
     node: ">=20"
   },
@@ -37,12 +37,12 @@ var package_default = {
     }
   },
   scripts: {
-    build: "node scripts/versions-famille.mjs && tsup",
+    build: "node scripts/family-versions.mjs && tsup",
     dev: "tsup --watch",
     test: "vitest run",
-    typecheck: "node scripts/versions-famille.mjs && tsc --noEmit",
+    typecheck: "node scripts/family-versions.mjs && tsc --noEmit",
     prepublishOnly: "pnpm run build",
-    "versions:famille": "node scripts/versions-famille.mjs"
+    "versions:family": "node scripts/family-versions.mjs"
   },
   dependencies: {
     "@babel/core": "^7.29.7",

package/dist/preview-P4WY5GEY.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export { startPreviewServer } from './chunk-PRWVZ2SM.js';
+import './chunk-WWTDEV4Y.js';
+import './chunk-7ZB5MAM6.js';

package/dist/registry/index.d.ts

@@ -1,46 +1,45 @@
 import * as z from 'zod/mini';
 
 /**
- * Format d'une entree de registre.
+ * Format of a registry entry.
  *
- * ## Pourquoi le schema vit ici
+ * ## Why the schema lives here
  *
- * Le format est un **contrat** entre le registre qui publie et le client qui
- * telecharge. Le placer du cote client n'est pas arbitraire : c'est la ou la
- * validation compte le plus. Le registre valide ce qu'il produit avant de le
- * publier ; le client, lui, valide ce qu'il recoit d'un serveur qu'il ne
- * controle pas, juste avant d'ecrire des fichiers dans le projet de
- * l'utilisateur.
+ * The format is a **contract** between the registry that publishes and the
+ * client that downloads. Putting it on the client side is not arbitrary: that
+ * is where the validation matters most. The registry validates what it produces
+ * before publishing it; the client validates what it receives from a server it
+ * does not control, just before writing files into the user project.
  *
- * Une seule definition, donc, employee aux deux bouts.
+ * A single definition, therefore, used at both ends.
  *
- * ## Le poids de la validation
+ * ## The weight of the validation
  *
- * Deux decisions, mesurees plutot que supposees.
+ * Two decisions, measured rather than assumed.
  *
- * La bibliotheque est **integree a la compilation** plutot que declaree en
- * dependance : installee, elle pese pres de six megaoctets, alors que la
- * surface reellement employee en represente une fraction.
+ * The library is **inlined at build time** rather than declared as a
+ * dependency: installed, it weighs close to six megabytes, while the surface
+ * actually used is a fraction of that.
  *
- * Et c'est sa variante concue pour le decoupage qui est employee, non son API
- * usuelle : la premiere produit treize kilo-octets minifies, la seconde quatre
- * cent vingt-sept. Un facteur trente-trois pour la meme validation. L'ecriture
- * y est plus verbeuse — les controles sont des fonctions plutot que des
- * methodes chainees — mais plaider le poids pour le moteur graphique et
- * l'ignorer ici serait incoherent.
+ * And it is its variant designed for splitting that is used, not its usual API:
+ * the first produces thirteen minified kilobytes, the second four hundred and
+ * twenty-seven. A factor of thirty-three for the same validation. Writing it is
+ * more verbose there — the checks are functions rather than chained methods —
+ * but pleading weight for the graphics engine and ignoring it here would be
+ * inconsistent.
  *
  * @module
  */
 
-/** Categories de composants du registre. */
+/** Component categories of the registry. */
 declare const CATEGORIES: readonly ["text", "background", "effect", "hero", "image", "ui", "section", "loader", "hooks"];
-/** Niveaux de cout d'un composant. */
+/** Cost levels of a component. */
 declare const PERF_TIERS: readonly ["light", "medium", "heavy"];
-/** Backends graphiques declarables. */
+/** Declarable graphics backends. */
 declare const GL_BACKENDS: readonly ["ogl", "three"];
-/** Nature du repli visuel d'un composant. */
+/** Nature of the visual fallback of a component. */
 declare const FALLBACKS: readonly ["poster", "gradient", "static", "none"];
-/** Forme d'une entree, avant les regles qui croisent plusieurs champs. */
+/** Shape of an entry, before the rules that cross several fields. */
 declare const baseSchema: z.ZodMiniObject<{
     name: z.ZodMiniString<string>;
     category: z.ZodMiniEnum<{
@@ -101,16 +100,16 @@ declare const baseSchema: z.ZodMiniObject<{
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
-/** Une entree telle qu'elle sort de la validation. */
+/** An entry as it comes out of the validation. */
 type RegistryMeta = z.infer<typeof baseSchema>;
-/** Entree telle qu'elle est ecrite dans un `meta.json`, avant valeurs par defaut. */
+/** Entry as it is written in a `meta.json`, before default values. */
 type RegistryMetaInput = z.input<typeof baseSchema>;
 /**
- * Description complete d'une entree de registre.
+ * Complete description of a registry entry.
  *
- * Les regles qui croisent plusieurs champs sont verifiees ici plutot que dans
- * le script de validation : elles font partie du format, et un registre tiers
- * qui reutiliserait ce schema doit les subir aussi.
+ * The rules that cross several fields are checked here rather than in the
+ * validation script: they are part of the format, and a third-party registry
+ * reusing this schema must be subject to them too.
  */
 declare const metaSchema: z.ZodMiniObject<{
     name: z.ZodMiniString<string>;
@@ -172,16 +171,16 @@ declare const metaSchema: z.ZodMiniObject<{
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
-/** Identifiant complet d'une entree, sous la forme `categorie/nom`. */
+/** Full identifier of an entry, in the form `category/name`. */
 declare function entryId(meta: Pick<RegistryMeta, 'category' | 'name'>): string;
-/** Une entree publiee, code source inline. */
+/** A published entry, source code inlined. */
 interface PublishedEntry extends RegistryMeta {
-    /** Identifiant complet. */
+    /** Full identifier. */
     readonly id: string;
-    /** Contenu des fichiers, indexe par leur chemin dans le composant. */
+    /** Content of the files, indexed by their path inside the component. */
     readonly sources: Readonly<Record<string, string>>;
 }
-/** Resume d'une entree, tel qu'il figure dans l'index. */
+/** Summary of an entry, as it appears in the index. */
 interface IndexEntry {
     readonly id: string;
     readonly name: string;
@@ -192,21 +191,21 @@ interface IndexEntry {
     readonly backend: false | (typeof GL_BACKENDS)[number];
     readonly registryDependencies: readonly string[];
 }
-/** Index du registre, servi a la racine. */
+/** Index of the registry, served at the root. */
 interface RegistryIndex {
-    /** Version du format, pour que le client sache s'il sait lire. */
+    /** Version of the format, so that the client knows whether it can read it. */
     readonly version: 1;
-    /** Date de generation, en ISO 8601. */
+    /** Generation date, in ISO 8601. */
     readonly generatedAt: string;
-    /** Resume de chaque entree, sans le code source. */
+    /** Summary of each entry, without the source code. */
     readonly entries: readonly IndexEntry[];
 }
 /**
- * Valide une entree et rend des messages lisibles en cas d'echec.
+ * Validates an entry and returns readable messages on failure.
  *
- * Les messages bruts sont exacts mais arides : ils sont reformates en chemin
- * plus explication, pour qu'un auteur de composant sache quoi corriger sans
- * avoir a lire le schema.
+ * The raw messages are exact but dry: they are reformatted as path plus
+ * explanation, so that a component author knows what to fix without having to
+ * read the schema.
  *
  * @example
  * const result = parseMeta(JSON.parse(raw), 'text/split-reveal')
@@ -221,53 +220,53 @@ declare function parseMeta(value: unknown, origin: string): {
 };
 
 /**
- * Resolution du graphe de dependances du registre.
+ * Resolution of the dependency graph of the registry.
  *
- * Une entree peut en reclamer d'autres — un hook partage, un utilitaire. Il
- * faut donc, avant d'ecrire quoi que ce soit chez l'utilisateur, savoir
- * exactement quelles entrees installer et dans quel ordre.
+ * An entry may require others — a shared hook, a utility. Before writing
+ * anything into the user project, we therefore have to know exactly which
+ * entries to install and in what order.
  *
- * ## Les cycles
+ * ## The cycles
  *
- * Rien n'interdit structurellement a deux entrees de se reclamer l'une
- * l'autre, et un parcours naif s'y perdrait indefiniment. Le cycle est donc
- * detecte, et **signale avec le chemin qui le compose** : une erreur qui dit
- * seulement « cycle detecte » oblige a le chercher a la main.
+ * Nothing structurally forbids two entries from requiring each other, and a
+ * naive walk would get lost in them forever. The cycle is therefore detected,
+ * and **reported with the path that makes it up**: an error that says only
+ * "cycle detected" forces you to look for it by hand.
  *
- * ## L'ordre
+ * ## The order
  *
- * Les dependances sont installees avant ce qui les reclame. Cela n'a pas
- * d'importance pour l'ecriture de fichiers, qui est independante, mais cela en
- * a pour ce que l'utilisateur voit defiler : une liste ou les dependances
- * apparaissent apres leur consommateur se lit comme une erreur.
+ * The dependencies are installed before what requires them. That does not
+ * matter for writing files, which is independent, but it does matter for what
+ * the user sees scrolling by: a list where the dependencies appear after their
+ * consumer reads like an error.
  *
  * @module
  */
 
-/** Ce qu'il faut savoir d'une entree pour resoudre le graphe. */
+/** What has to be known about an entry to resolve the graph. */
 interface ResolvableEntry {
-    /** Identifiant complet, sous la forme `categorie/nom`. */
+    /** Full identifier, in the form `category/name`. */
     readonly id: string;
-    /** Entrees reclamees par celle-ci. */
+    /** Entries required by this one. */
     readonly registryDependencies: readonly string[];
 }
-/** Resultat d'une resolution reussie. */
+/** Result of a successful resolution. */
 interface ResolvedGraph {
-    /** Entrees a installer, dependances d'abord. */
+    /** Entries to install, dependencies first. */
     readonly order: readonly string[];
-    /** Entrees ajoutees qui n'avaient pas ete demandees. */
+    /** Entries added that had not been asked for. */
     readonly implied: readonly string[];
 }
-/** Ce qui a empeche la resolution. */
+/** What prevented the resolution. */
 type ResolutionProblem = {
-    readonly kind: 'introuvable';
+    readonly kind: 'missing';
     readonly id: string;
     readonly requiredBy: string | null;
 } | {
     readonly kind: 'cycle';
     readonly path: readonly string[];
 };
-/** Resultat d'une resolution. */
+/** Result of a resolution. */
 type ResolutionResult = {
     readonly ok: true;
     readonly graph: ResolvedGraph;
@@ -276,18 +275,18 @@ type ResolutionResult = {
     readonly problems: readonly ResolutionProblem[];
 };
 /**
- * Met un probleme de resolution en phrase lisible.
+ * Turns a resolution problem into a readable sentence.
  *
  * @example
  * describeProblem({ kind: 'cycle', path: ['a', 'b', 'a'] })
- * // 'Cycle de dependances : a → b → a'
+ * // 'Dependency cycle: a → b → a'
  */
 declare function describeProblem(problem: ResolutionProblem): string;
 /**
- * Resout les dependances d'un ensemble d'entrees demandees.
+ * Resolves the dependencies of a set of requested entries.
  *
- * @param requested Identifiants demandes par l'utilisateur.
- * @param available Toutes les entrees connues, indexees par identifiant.
+ * @param requested Identifiers requested by the user.
+ * @param available Every known entry, indexed by identifier.
  *
  * @example
  * const result = resolveGraph(['hero/canopy'], catalogue)
@@ -295,10 +294,10 @@ declare function describeProblem(problem: ResolutionProblem): string;
  */
 declare function resolveGraph(requested: readonly string[], available: ReadonlyMap<string, ResolvableEntry>): ResolutionResult;
 /**
- * Verifie l'integrite d'un catalogue entier.
+ * Checks the integrity of a whole catalogue.
  *
- * Emploi typique : la validation du registre avant publication, ou toutes les
- * entrees sont resolues d'un coup plutot qu'une par une.
+ * Typical use: the validation of the registry before publication, where every
+ * entry is resolved at once rather than one by one.
  *
  * @example
  * const problems = validateCatalogue(catalogue)
@@ -306,7 +305,7 @@ declare function resolveGraph(requested: readonly string[], available: ReadonlyM
  */
 declare function validateCatalogue(available: ReadonlyMap<string, ResolvableEntry>): readonly ResolutionProblem[];
 /**
- * Construit un catalogue a partir d'entrees completes.
+ * Builds a catalogue from complete entries.
  *
  * @example
  * const catalogue = toCatalogue(metas)

package/dist/registry/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export { CATEGORIES, FALLBACKS, GL_BACKENDS, PERF_TIERS, describeProblem, entryId, metaSchema, parseMeta, resolveGraph, toCatalogue, validateCatalogue } from '../chunk-34RGOZFA.js';
+export { CATEGORIES, FALLBACKS, GL_BACKENDS, PERF_TIERS, describeProblem, entryId, metaSchema, parseMeta, resolveGraph, toCatalogue, validateCatalogue } from '../chunk-4D56Z7G3.js';

package/dist/{server-4UGN3SFS.js → server-2WP562EV.js}

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-export { extractEntries, injectClient, startDevServer } from './chunk-LHZGX5ML.js';
-import './chunk-TQUJ3MFS.js';
-import './chunk-JMEHF3KN.js';
+export { extractEntries, injectClient, startDevServer } from './chunk-OMHEQVIW.js';
+import './chunk-WWTDEV4Y.js';
+import './chunk-7ZB5MAM6.js';

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "odoro",
-  "version": "1.0.9",
+  "version": "2.0.0",
   "type": "module",
   "license": "UNLICENSED",
   "author": "BouBouw",
-  "description": "Moteur de developpement et echafaudage Odoro : odoro create, dev, build, preview.",
+  "description": "Odoro development engine and scaffolder: odoro create, dev, build, preview.",
   "engines": {
     "node": ">=20"
   },
@@ -59,10 +59,10 @@
     "url": "https://github.com/ODORO-CLI/OdoroKit/issues"
   },
   "scripts": {
-    "build": "node scripts/versions-famille.mjs && tsup",
+    "build": "node scripts/family-versions.mjs && tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "typecheck": "node scripts/versions-famille.mjs && tsc --noEmit",
-    "versions:famille": "node scripts/versions-famille.mjs"
+    "typecheck": "node scripts/family-versions.mjs && tsc --noEmit",
+    "versions:family": "node scripts/family-versions.mjs"
   }
 }

package/templates/react-ts/README.md

@@ -1,52 +1,88 @@
-# Odoro — application monopage
+# Odoro — single-page application
 
-Projet genere par `odoro create`. Le routeur, le moteur d'animation, le systeme
-de style et les composants d'interface viennent tous de `@odoro-cli/libs` ; le
-serveur de developpement et la compilation viennent du moteur `odoro`.
+Project generated by `odoro create`. The router, the motion engine, the style
+system and the interface components all come from `@odoro-cli/libs`; the
+development server and the build come from the `odoro` engine.
 
 ## Structure
 
 ```
-index.html          Document et point d'entree : la balise <script type="module">
-                    designe le fichier a compiler.
-odoro.config.ts     Configuration du moteur : alias, port, proxy, build.
-public/             Fichiers copies tels quels a la racine du site.
+index.html          Document and entry point: the <script type="module"> tag
+                    names the file to build.
+odoro.config.ts     Engine configuration: aliases, port, proxy, build.
+.env.example        The expected variables. Copy to `.env`, never committed.
+public/             Files copied as-is to the root of the site.
 src/
-  main.tsx          Montage de React et imports de feuilles de style.
-  App.tsx           Declaration des routes et enveloppe commune.
-  routes/           Une page par route.
-  styles.css        Styles propres au projet et surcharges de tokens.
-  odoro-env.d.ts    Types ambiants (import.meta.env, imports de ressources).
+  main.tsx          React mounting and stylesheet imports.
+  App.tsx           The whole page: nav, sections, footer.
+  router.tsx        The route table — the only file that names the router.
+  entry-server.tsx  Prerendering: which routes, and what they put in the head.
+  background.tsx    The decorative background — the only piece tied to the
+                    graphics engine.
+  styles.css        Project styles and token overrides.
+  odoro-env.d.ts    Ambient types (import.meta.env, asset imports).
 ```
 
 ## Scripts
 
-| Commande    | Effet                                               |
-| ----------- | --------------------------------------------------- |
-| `dev`       | Serveur de developpement avec rechargement a chaud. |
-| `build`     | Compilation de production dans `dist/`.             |
-| `preview`   | Sert `dist/` comme le ferait un hebergeur statique. |
-| `typecheck` | Verification des types, sans emission.              |
+| Command     | Effect                                          |
+| ----------- | ----------------------------------------------- |
+| `dev`       | Development server with hot reloading.          |
+| `build`     | Production build into `dist/`.                  |
+| `preview`   | Serves `dist/` the way a static host would.     |
+| `typecheck` | Type checking, without emitting.                |
 
-## Personnalisation
+## Environment variables
 
-Toutes les valeurs visuelles passent par des variables CSS. Surcharger
-`--o-palette-brand-600` dans `src/styles.css` retheme l'application **et** les
-composants de la librairie, sans toucher a leur code.
+Copy `.env.example` to `.env`. The files are read from the least specific to
+the most specific — `.env`, `.env.local`, `.env.<mode>`, `.env.<mode>.local` —
+and a variable already set in the environment is never overwritten by a file:
+whatever your host injects wins.
 
-Une seule feuille de style : `@odoro-cli/libs/styles.css`, a importer une fois
-a la racine de l'application.
+**Only variables prefixed with `ODORO_` reach the browser**, through
+`import.meta.env`. Anyone who opens the site can then read them. Everything
+else stays on the machine.
 
-Elle ne contient que le socle — variables, preflight, animations. Les
-utilitaires sont produits a la compilation, pour les seules classes que votre
-code emploie : quelques dizaines de kilooctets en pratique, et toute la palette
-disponible sans que rien ne pese.
+```ts
+const api = import.meta.env.ODORO_API
+```
+
+`odoro build --mode staging` reads `.env.staging` and fills in
+`import.meta.env.MODE`.
+
+## Prerendering
+
+`build.prerender` is on: `odoro build` renders every route of
+`src/entry-server.tsx` as a complete HTML document, and `main.tsx` hydrates it
+on load rather than rebuilding everything.
+
+That is what lets a search engine, a link preview or a screen reader find text
+in the very first response. `/about` becomes `dist/about/index.html`, which any
+static host serves with no configuration — nothing runs in production.
+
+Adding a route: one line in `routes`, and the matching entry in
+`src/router.tsx`. Doing without: remove `prerender` from `odoro.config.ts`,
+then delete `src/entry-server.tsx`.
+
+## Customising
+
+Every visual value goes through a CSS variable. Overriding
+`--o-palette-brand-600` in `src/styles.css` rethemes the application **and**
+the library components, without touching their code.
+
+A single stylesheet: `@odoro-cli/libs/styles.css`, imported once at the root of
+the application.
+
+It carries only the base — variables, preflight, animations. The utilities are
+produced at build time, for the classes your code actually uses: a few tens of
+kilobytes in practice, with the whole palette available and nothing weighing it
+down.
 
-## Rechargement a chaud
+## Hot reloading
 
-Modifier un composant remplace son code sans demonter l'arbre : la valeur d'un
-compteur, le texte saisi dans un champ, l'onglet ouvert survivent a l'edition.
-Une feuille de style est echangee sans rechargement.
+Editing a component swaps its code without unmounting the tree: the value of a
+counter, the text typed into a field, the open tab all survive the edit. A
+stylesheet is swapped with no reload at all.
 
-Un module qui n'exporte pas que des composants recharge la page, et c'est
-correct : rien ne permettrait d'en propager le changement sans risque.
+A module that exports more than components reloads the page, and that is
+correct: nothing would let its change propagate safely.

package/templates/react-ts/_env.example

@@ -0,0 +1,9 @@
+# Variables prefixed with ODORO_ go into the published bundle: anyone who opens
+# the site can read them. Everything else — tokens, server-side API keys — stays
+# on the machine, readable by the commands and by the back end.
+#
+# Copy this file to `.env` (ignored by git) and fill in what you need.
+# `.env.production` only applies to `odoro build`, `.env.development` only to
+# `odoro dev`.
+
+ODORO_API=http://localhost:3001

package/templates/react-ts/_variants/with-engine/src/background.tsx

@@ -0,0 +1,118 @@
+/**
+ * The decorative background, as a WebGL surface.
+ *
+ * This version replaces the static gradient because the engine was picked at
+ * creation. The rest of the page is unchanged: it places `<Background />` and
+ * does not know what is behind it.
+ *
+ * ## What the engine brings that a gradient cannot
+ *
+ * **An arbiter.** The surface is asked of the engine manager, which refuses it
+ * if the browser has no WebGL, if too many contexts are already open, or if
+ * the device would not keep up. The refusal is a value, not an exception: the
+ * gradient is shown instead, and the page holds.
+ *
+ * **Reduced motion.** Under that preference nothing is mounted: the background
+ * brought only its motion, and the graphics card has no business waking up for
+ * a visitor who asked for calm.
+ *
+ * **The theme colours.** The hues are read from the tokens, not written into
+ * the shader. A light / dark switch re-reads them, and changing
+ * `--o-palette-brand-500` repaints the background without touching this file.
+ *
+ * ## Why inline styles
+ *
+ * This file is laid down whatever the rest: a project that unticked the
+ * libraries has no `o-*` classes, and a missing class paints nothing — the
+ * background would then be zero pixels tall, with nothing to report it. So the
+ * few placement rules are written where they are safe.
+ *
+ * @module
+ */
+
+import {
+  AURORA_FRAGMENT,
+  readTokenColour,
+  useMotionState,
+  useShaderSurface,
+  type ShaderColour,
+} from '@odoro-cli/engine'
+import { useEffect, useMemo, useState, type ReactElement } from 'react'
+
+/** The tokens read to tint the glow. */
+const HUES = ['--o-palette-brand-500', '--o-palette-brand-300', '--o-theme-bg'] as const
+
+/** The gradient served while the surface is not there — or forever. */
+function Gradient(): ReactElement {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        opacity: 0.28,
+        filter: 'blur(64px)',
+        background:
+          'radial-gradient(60% 60% at 50% 0%, var(--o-palette-brand-500, #3b82f6), transparent)',
+      }}
+    />
+  )
+}
+
+/** An animated glow behind the top of the page. */
+export function Background(): ReactElement {
+  const { quality, reduced } = useMotionState()
+  const [host, setHost] = useState<HTMLElement | null>(null)
+  const [hues, setHues] = useState<readonly ShaderColour[]>([])
+
+  // Re-read when the host appears and when the theme switches — the latter
+  // goes through the motion policy, which is renewed on every state.
+  useEffect(() => {
+    if (host === null) return
+    setHues(HUES.map((token) => readTokenColour(token, host)))
+  }, [host, reduced, quality])
+
+  const uniforms = useMemo(() => {
+    const [a, b, c] = hues
+    if (a === undefined || b === undefined || c === undefined) return undefined
+    // The theme background dominates, the brand is only a reflection: these
+    // three colours go into a mix, and two brand hues out of three would give
+    // a full-page glow rather than a halo.
+    return { uColorA: c, uColorB: c, uColorC: a, uSpeed: 0.1, uScale: 1.4, uOctaves: 3 }
+  }, [hues])
+
+  const { ref, ready, refused } = useShaderSurface<HTMLDivElement>({
+    fragment: AURORA_FRAGMENT,
+    uniforms: uniforms ?? {},
+    name: 'home-background',
+  })
+
+  const fallback = !ready || refused !== undefined || uniforms === undefined
+
+  return (
+    <div
+      aria-hidden="true"
+      ref={(element) => {
+        setHost(element)
+        ref.current = element
+      }}
+      style={{
+        position: 'absolute',
+        insetInline: 0,
+        top: 0,
+        height: '42rem',
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        // A decorative background is noticed when you look for it, not before.
+        // At full strength the glow comes in front of the title it is supposed
+        // to carry; at a fifth, it underlines it.
+        opacity: 0.2,
+        // The bottom dissolves into the page: a surface that stops dead draws
+        // a horizontal line that nothing justifies.
+        maskImage: 'linear-gradient(to bottom, black 45%, transparent)',
+        WebkitMaskImage: 'linear-gradient(to bottom, black 45%, transparent)',
+      }}
+    >
+      {fallback ? <Gradient /> : null}
+    </div>
+  )
+}