@valancex/cli 0.13.0 → 0.14.0

package/README.md

@@ -153,7 +153,7 @@ Templates are MPRX. Conditional and repeated parts are blocks: `{#if cond}…{:e
 | `prev`, `next` | `{ href, label }`, empty `href` when there is none |
 | `viewport` | How much room the page has: `"compact"` (under 600 px), `"medium"` (600 to 839) or `"expanded"` (840 and up), kept current as the window changes. `{#if viewport == "compact"}` chooses markup for a phone. The server renders `expanded`; the browser corrects it as soon as it starts. |
 
-Tags you may use: `shell` (`class`, `theme`), `div`, `header`, `footer`, `nav` (`class`, `label`), `aside`, `section`, `article`, `main` (`id`, `tabindex`), `h1`–`h3` (`id`), `para`, `quote`, `list`, `olist`, `item`, `pre`, `code`, `strong`, `em`, `span`, `image`, `a` (`href`), `link` (`href`, `class`, `current`), `button` (`class`, `pressed`, `on.click`), plus your components and the built-ins (`blocks`, `block`, `heading`, `list-block`, `list-items`, `runs`, `inline`). A prop a tag declares must be written wherever the tag is used; that is why there are many narrow tags rather than a few wide ones. The attribute each prop becomes is in [`src/primitives.ts`](src/primitives.ts).
+Tags you may use: `shell` (`class`, `theme`), `div`, `header`, `footer`, `nav` (`class`, `label`), `aside`, `section`, `article`, `main` (`id`, `tabindex`), `h1`–`h3` (`id`), `paragraph`, `blockquote`, `list`, `olist`, `listitem`, `pre`, `code`, `strong`, `em`, `span`, `image`, `a` (`href`), `link` (`href`, `class`, `current`), `button` (`class`, `pressed`, `on.click`), `toggle`, `checkbox`, `textfield`, `radiogroup`, `radio`, `label`, `status`, `alert` (the full list, with roles and names, is [the primitives](../../docs/use/primitives.md)), plus your components and the built-ins (`blocks`, `block`, `heading`, `list-block`, `list-items`, `runs`, `inline`). The tags `para`, `item` and `quote` are now `paragraph`, `listitem` and `blockquote` (the ARIA names, which the Desktop already used); a template that writes the old one is told the new one. A prop a tag declares must be written wherever the tag is used; that is why there are many narrow tags rather than a few wide ones. The attribute each prop becomes is in [`src/primitives.ts`](src/primitives.ts).
 
 ## The components
 
@@ -173,20 +173,22 @@ export default defineApp({
 
 ```ts
 // src/theme-toggle.ts: the component states its own interface, where it is defined
-import { component } from "@valancex/common";
+import { component, field } from "@valancex/common";
 import { Schema } from "effect";
 import template from "./theme-toggle.mprx";
 
 export default component(template, {
-  props: { theme: Schema.Literal("light", "dark") },
+  props: { theme: field(Schema.Literal("light", "dark"), "light") },
   events: { toggle: Schema.Void },
 });
 ```
 
 - `import x from "./x.mprx"` names a template file; `component(x, …)` defines it. The tag is the file's name (`theme-toggle.mprx` is `<theme-toggle>`). Register it once, in `components`.
 - **Which components a template uses is read from the template.** Write `<theme-toggle … />` in the layout (or in another component) and it is used; there is no list of uses to keep in step. A registered component no template writes yet is not part of the program, and is not an error. A file under `src/` that is not registered is an error (`template-unused`).
-- **The contract.** `props` maps a prop name to its Effect Schema and `events` an event name to its payload Schema (`Schema.Void` is no payload). Declare either and the contract is exactly what you wrote (an omitted side is none), overriding inference; declare neither and MESH infers it from the template and where it is used. Schemas are converted by the same rules as state; a prop is optional when its schema admits `undefined`, and props have no defaults. A schema with no MESH type is a diagnostic at the declaration (`component-schema`). MESH reports an undeclared or missing prop, a prop of the wrong type and a handler for an undeclared event at the use. The layout takes no contract (`layout-contract`). That declared interface is where an editor takes you from `on.toggle=` or `theme=` at a use, and where *Find All References* starts.
+- **The contract.** `props` maps a prop name to its Effect Schema and `events` an event name to its payload Schema (`Schema.Void` is no payload). Declare either and the contract is exactly what you wrote (an omitted side is none), overriding inference; declare neither and MESH infers it from the template and where it is used. Schemas are converted by the same rules as state; a prop is optional when its schema admits `undefined`. A **string-literal union is a closed set**: `Schema.Literal("info", "danger")` becomes the MESH type `"info" | "danger"`, and MESH reports any other literal written for the prop at the use (`unknown-variant`, with a did-you-mean when one is close); a number or boolean literal keeps its primitive type. A prop gets a **default** with `field(schema, value)` (`props: { tone: field(Schema.Literal("info", "danger"), "info") }`): a use of the component that leaves the prop out gets the value, the prop may then be left out, and TypeScript refuses a default that is not a member. A default is for a component with a template; on a primitive it is ignored. A schema with no MESH type, for example a union of a string literal and a number, or a default that is not a value of the prop's type, is a diagnostic at the declaration (`component-schema`). Both need MESH 0.14 or later (`@valancex/mesh-compiler` `^0.14.0`, which the packages depend on). MESH reports an undeclared or missing prop, a prop of the wrong type and a handler for an undeclared event at the use. The layout takes no contract (`layout-contract`). That declared interface is where an editor takes you from `on.toggle=` or `theme=` at a use, and where *Find All References* starts.
 - `override: [component(runs, { props: { spans: … } })]` replaces a built-in (`runs`, `heading-block`, …) with your template of the same name.
+- **One MESH runtime.** `vlx build` (never `vlx dev`) stops with `runtime-duplicate` when the packages resolve more than one copy of `@valancex/mesh-runtime`: each copy is a 765 KB WebAssembly module (171 KB of brotli) that the site would ship and the browser fetch. The message names each copy, its version and who uses it, and says to add an `overrides` entry (npm; `pnpm.overrides`, or `resolutions` with yarn) so there is one. `@valancex/common`, `@valancex/valance` and `@valancex/nexus` accept the same range (`^0.12.0`) so a plain install has one.
+- **One name is one component.** Two registered files with the same name (for example `a/disclosure.mprx` and `b/disclosure.mprx`, whether yours or from two libraries) are `template-duplicate`, and a registered component named like a built-in is `template-builtin` unless it is in `override`: neither silently replaces the other, and the first one listed does not win. Rename one of the files; qualified ids for a library's components (`acme-ui/disclosure`, decision K14) are not built yet. `override` is only for built-ins: for any other name it is `override-unknown`, and the component belongs in `components`.
 - `layout` is optional; without it the built-in layout draws the page. Its template must be named `layout.mprx`.
 
 ### Children and slots
@@ -202,13 +204,38 @@ A component places the content its caller writes inside it with `<mesh-slot />`,
 
 <!-- where it is used -->
 <card>
-  <mesh-fill slot="head"><para class="title">Title</para></mesh-fill>
-  <para class="body">The body goes to the unnamed slot.</para>
+  <mesh-fill slot="head"><paragraph class="title">Title</paragraph></mesh-fill>
+  <paragraph class="body">The body goes to the unnamed slot.</paragraph>
 </card>
 ```
 
 The children are the caller's: `{x}` in them is the caller's `x`, never the card's. `vlx generate component` writes the single, unnamed slot for you. The rules (where a slot may be, what a fill is, the errors) are in MESH's [templates manual](https://github.com/ValanceX/Mesh/blob/main/docs/manual/templates.md#children-and-the-slot).
 
+### Snippets as props
+
+A prop can be a piece of template (MESH 0.14). Declare it with `snippet(…)`, the types of its parameters in order, and read it in the component's template with `{@render name(args)}`:
+
+```
+// src/panel.ts and src/item-list.ts
+component(panel, { props: { title: Schema.String, children: snippet() } });
+component(itemList, { props: { items: Schema.Array(Item), row: snippet(Item, Schema.String) } });
+```
+
+```
+<!-- src/panel.mprx -->
+<section><strong>{title}</strong>{@render children()}</section>
+
+<!-- where they are used: loose content is `children`; a {#snippet} that is a direct child is the prop of its name -->
+<panel title="Totals"><span class="count">{count}</span></panel>
+<item-list items={items} label="row">{#snippet row(item, tag)}<span class="row">{tag}:{item.name}</span>{/snippet}</item-list>
+```
+
+- `children` is reserved for the content between the tags: it must be `snippet()` (no parameters), and `children={…}` with content is `children-conflict`. A snippet is not data: it has no `field` default, is never optional, and is not a record field or an event's payload.
+- A snippet reads the scope of the template that **wrote** it (`count` above is the layout's, not the panel's), so a node that renders one is redrawn when that scope changes though its own props did not.
+- The arity and the types are checked: `snippet-arity-mismatch` in the composite's template when `{@render row(item)}` passes too few, and a member the parameter does not have is reported where the snippet is written.
+- **Optional.** `snippet(…).optional()` (and `children: snippet().optional()`) is one an occurrence may leave out: it is `snippet<…>?` in the model, and an absent one draws nothing. Rendering it is `possibly-absent-snippet` unless it is inside the first branch of an `{#if has(name)}` (`&&` allowed), so `{#if has(header)}{@render header()}{/if}` is how a template uses one.
+- Slots (`mesh-slot`, `mesh-fill`) keep working for a component that does not declare `children`.
+
 ### Typed template imports
 
 `vlx sync` (and `check`, `dev` and `build`) write `.valance/types/<template>.d.mprx.ts`, so a component's declaration is checked against the names its template uses: `component(template, { props: { thme: … } })` is a compile-time error. This needs two options in your `tsconfig.json`:

package/dist/budgets.json

@@ -0,0 +1,175 @@
+{
+  "version": 1,
+  "about": "The ecosystem's budgets, as data (Bet 3; decisions W1 to W24). `project` is what `vlx build` holds an application to when its valance.json sets none (W14). `framework` is what the release check holds the reference applications and the runtime to (scripts/check-budgets.mjs, over the output of scripts/measure-footprint.mjs). Brotli bytes, because that is what travels (W2).",
+  "rule": "A ceiling is the baseline plus 5 percent, rounded up to the next 100 bytes (the next 10 under 1,000), then ratcheted down (W3). A ceiling above that needs `analysis`: the path of a size analysis that says why (W23a), and a decision row. The check refuses a raised ceiling without one.",
+  "project": {
+    "budgets": [
+      {
+        "type": "initial",
+        "warning": 105200,
+        "error": 210400
+      },
+      {
+        "type": "runtime",
+        "error": 192900
+      }
+    ],
+    "note": "W14: the framework's own start-up ceilings. `initial` warns above the largest reference application's JavaScript and CSS ceiling (docs-app) and fails at twice that; `runtime` is the WebAssembly runtime, the same for every application, so a growth of it fails the build of whoever upgrades."
+  },
+  "framework": {
+    "baseline": "docs/direction/baselines/2026-10-24-wp8-before.md",
+    "ceilings": [
+      {
+        "id": "counter.javascript",
+        "what": "Counter application, JavaScript, brotli",
+        "path": "counter.deduped.js.brotli",
+        "unit": "bytes",
+        "baseline": 93722,
+        "ceiling": 98500,
+        "previousCeiling": 92400,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "counter.css",
+        "what": "Counter application, CSS, brotli",
+        "path": "counter.deduped.css.brotli",
+        "unit": "bytes",
+        "baseline": 1053,
+        "ceiling": 1200
+      },
+      {
+        "id": "runtime.wasm",
+        "what": "The WebAssembly runtime, brotli",
+        "path": "counter.deduped.wasm.brotli",
+        "unit": "bytes",
+        "baseline": 183629,
+        "ceiling": 192900,
+        "previousCeiling": 179400,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "counter.transferred",
+        "what": "Counter application, everything the browser transfers, brotli",
+        "path": "browser.deduped.noThrottling.bytesTransferredBrotli",
+        "unit": "bytes",
+        "baseline": 279594,
+        "ceiling": 293600,
+        "previousCeiling": 274100,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "docsApp.javascript",
+        "what": "docs-app, JavaScript, brotli",
+        "path": "docsApp.js.brotli",
+        "unit": "bytes",
+        "baseline": 98520,
+        "ceiling": 103500,
+        "previousCeiling": 97400,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "docsApp.css",
+        "what": "docs-app, CSS, brotli",
+        "path": "docsApp.css.brotli",
+        "unit": "bytes",
+        "baseline": 1542,
+        "ceiling": 1700
+      },
+      {
+        "id": "docsApp.perPage",
+        "what": "Client JavaScript each added page costs, raw",
+        "path": "docsApp.perAddedPage.jsRawPerPage",
+        "unit": "bytes",
+        "baseline": 2471.5,
+        "ceiling": 2600,
+        "previousCeiling": 2600
+      },
+      {
+        "id": "counter.heap",
+        "what": "Counter, JavaScript heap after 200 updates",
+        "path": "browser.deduped.noThrottling.afterUpdates.jsHeapUsedBytes",
+        "unit": "bytes",
+        "baseline": 4575160,
+        "ceiling": 4630800,
+        "previousCeiling": 4630800,
+        "note": "W24: the 1,000-update heap gate stays off"
+      },
+      {
+        "id": "counter.wasmMemory",
+        "what": "Counter, WebAssembly memory after 200 updates",
+        "path": "browser.deduped.noThrottling.afterUpdates.wasmMemoryBytes",
+        "unit": "bytes",
+        "baseline": 1310720,
+        "ceiling": 1376300,
+        "previousCeiling": 4885800,
+        "note": "ratcheted down: W21 fixed the growth, the memory is flat"
+      },
+      {
+        "id": "docsApp.wasmMemory",
+        "what": "docs-app, WebAssembly memory after 200 updates",
+        "path": "browser.docsApp.noThrottling.afterUpdates.wasmMemoryBytes",
+        "unit": "bytes",
+        "baseline": 2293760,
+        "ceiling": 2408500
+      }
+    ],
+    "exact": [
+      {
+        "id": "wire.patch",
+        "what": "Bytes a PORT is sent for one changed item of 1,000 rows, as patches",
+        "path": "wire.1000.patchBytes",
+        "unit": "bytes",
+        "max": 202
+      }
+    ],
+    "ratios": [
+      {
+        "id": "counter.interactiveAt",
+        "what": "Counter, time until a click is handled, unthrottled",
+        "path": "browser.deduped.noThrottling.interactiveAtMs",
+        "max": 2
+      },
+      {
+        "id": "counter.interactiveAt4x",
+        "what": "Counter, time until a click is handled, 4x CPU",
+        "path": "browser.deduped.cpu4x.interactiveAtMs",
+        "max": 2
+      },
+      {
+        "id": "counter.firstPaint",
+        "what": "Counter, first paint, unthrottled",
+        "path": "browser.deduped.noThrottling.firstPaintMs",
+        "max": 2
+      },
+      {
+        "id": "update.10000",
+        "what": "`update`, 10,000 items, one changed",
+        "path": "update.10000.updateMs",
+        "max": 1.5
+      },
+      {
+        "id": "updateFromChanges.10000",
+        "what": "`update` from changes, 10,000 items",
+        "path": "update.10000.updateFromChangesMs",
+        "max": 1.5
+      }
+    ],
+    "known": [
+      {
+        "id": "wire.wholeTree",
+        "what": "Bytes a PORT is sent for one changed item of 1,000 rows, whole tree",
+        "path": "wire.1000.wholeTreeBytes",
+        "reason": "the Desktop protocol sends the whole tree on every update; patches are Bet 3's own work item, not WP8",
+        "owner": "unassigned"
+      },
+      {
+        "id": "installability",
+        "what": "The newest published @valancex set, with the release being measured, installs together",
+        "path": "newestInstallsTogether.installs",
+        "expect": true,
+        "reason": "Was red from MESH 0.16 until VALANCE 0.14: NEXUS 0.14 and PORT 0.12 stopped their MESH peer range at 0.15. With --tree the release candidate's own tarballs stand in for the published VALANCE packages, so a release is held to installing beside the newest of the others before it is published (a published VALANCE, the previous release, would gate a release on its predecessor)",
+        "owner": "WP8"
+      }
+    ]
+  }
+}

package/dist/build.d.ts

@@ -1,8 +1,14 @@
 import type { TargetId } from "./targets.js";
+import type { BudgetResult, SizeReport } from "./size.js";
 export interface Built {
     readonly dir: string;
     readonly files: ReadonlyArray<string>;
     readonly pages: ReadonlyArray<string>;
+    /** The web build's start-up and after-start sets, measured, and each budget it was held to (a production build only). */
+    readonly size?: SizeReport;
+    readonly budgets?: ReadonlyArray<BudgetResult>;
+    /** The size report as the lines a terminal prints. */
+    readonly report?: ReadonlyArray<string>;
 }
 /** The file a pathname is written to in the site: `/` → `index.html`, `/guide/x` → `guide/x/index.html`, relative to the base. */
 export declare const fileOf: (pathname: string, base: string) => string;
@@ -13,5 +19,7 @@ export interface BuildOptions {
     readonly onStage?: (stage: BuildStage) => void;
     /** Which of the project's targets to build; all of them by default. */
     readonly targets?: ReadonlyArray<TargetId>;
+    /** Called with the size report as soon as the bundle is measured, before a budget error stops the build (a terminal prints it). */
+    readonly onReport?: (lines: ReadonlyArray<string>) => void;
 }
 export declare const build: (root: string, options?: BuildOptions) => Promise<Built>;

package/dist/build.js

@@ -10,6 +10,8 @@ import { headersFile } from "./security.js";
 import { AppError } from "./diagnostics.js";
 import { generateContent, generateEntries, generateProgram } from "./emit.js";
 import { OUTPUT_DIR } from "./project.js";
+import { check, DEFAULT_BUDGETS, failure, lines, measure } from "./size.js";
+import { assertOneRuntime } from "./runtime-guard.js";
 import { baseConfig, createLoader, SERVER_ENTRY, templates } from "./vite.js";
 import { GENERATED_DIR } from "./project.js";
 /** The file a pathname is written to in the site: `/` → `index.html`, `/guide/x` → `guide/x/index.html`, relative to the base. */
@@ -36,13 +38,14 @@ const buildDesktop = async (root) => {
         plugins: [templates(root)],
         cacheDir: join(root, GENERATED_DIR, "cache"),
         ssr: { noExternal: true, target: "node" },
+        esbuild: { keepNames: true },
         build: {
             ssr: join(root, GENERATED_DIR, "desktop.ts"),
             outDir: out,
             emptyOutDir: true,
             target: "node22",
-            minify: false,
-            chunkSizeWarningLimit: 4000,
+            // W10: the engine is minified (half the bytes; start-up measured no worse, 2026-10-24). Names are kept: errors and their `_tag` are read by name.
+            minify: "esbuild",
             rollupOptions: {
                 output: {
                     format: "es",
@@ -61,7 +64,7 @@ const buildDesktop = async (root) => {
     return { dir: out, files: ["desktop/engine.mjs", "desktop/mesh-runtime.wasm"], pages: [] };
 };
 /** The web build: the browser bundle into `out`, then one document per page. The loader is the one the templates were compiled with. */
-const buildWeb = async (root, config, loader, content, out, prefix, stage) => {
+const buildWeb = async (root, config, loader, content, out, prefix, stage, onReport) => {
     // The browser bundle first: it empties its directory, and the documents are written into it after.
     stage("bundle");
     await bundle({ ...baseConfig(root, config, out), mode: "production" });
@@ -74,7 +77,22 @@ const buildWeb = async (root, config, loader, content, out, prefix, stage) => {
             throw new AppError([{ file: out, line: 0, column: 0, code: "build-entry", message: "the bundle has no entry chunk" }]);
         }
         rmSync(join(dist, ".vite"), { recursive: true, force: true }); // the bundler's bookkeeping is not part of the site
-        const built = { script: `${config.web.base}${entry.file}`, styles: (entry.css ?? []).map((file) => `${config.web.base}${file}`) };
+        // The WebAssembly runtime is in the start-up set (H7): the head starts compiling it while the page's script downloads (W11).
+        const wasm = Object.values(manifest).find((chunk) => chunk.file.endsWith(".wasm"))?.file;
+        const built = {
+            script: `${config.web.base}${entry.file}`,
+            styles: (entry.css ?? []).map((file) => `${config.web.base}${file}`),
+            ...(wasm === undefined ? {} : { wasm: `${config.web.base}${wasm}` }),
+        };
+        // The size report: the start-up set and the after-start set, held to the project's budgets or the framework's (W9, W14). Production only.
+        const size = measure(dist, manifest, wasm);
+        const budgets = check(size, config.budgets ?? DEFAULT_BUDGETS);
+        const report = lines(size, budgets);
+        onReport(report);
+        const over = failure(budgets);
+        if (over !== undefined) {
+            throw over;
+        }
         const files = [];
         const write = (relative, text) => {
             mkdirSync(dirname(join(dist, relative)), { recursive: true });
@@ -95,7 +113,7 @@ const buildWeb = async (root, config, loader, content, out, prefix, stage) => {
         if (config.web.headers) {
             write("_headers", headersFile(config));
         }
-        return { dir: dist, files: files.map((file) => `${prefix}${file}`), pages };
+        return { dir: dist, files: files.map((file) => `${prefix}${file}`), pages, size, budgets, report };
     }
 };
 export const build = async (root, options = {}) => {
@@ -115,6 +133,8 @@ export const build = async (root, options = {}) => {
             },
         ]);
     }
+    // Production only (`vlx dev` does not build through here): one copy of the MESH runtime, or the site ships its WebAssembly module more than once (W20).
+    assertOneRuntime(root);
     generateEntries(root, config);
     stage("content");
     const content = generateContent(root, config);
@@ -125,7 +145,7 @@ export const build = async (root, options = {}) => {
         await generateProgram(root, await loadAuthor(loader, root), config, selected);
         // Each target writes to a directory of its own, whatever else the project has: dist/web/ and dist/desktop/.
         if (selected.includes("web")) {
-            built.push(await buildWeb(root, config, loader, content, `${OUTPUT_DIR}/web`, "web/", stage));
+            built.push(await buildWeb(root, config, loader, content, `${OUTPUT_DIR}/web`, "web/", stage, options.onReport ?? (() => undefined)));
         }
         if (selected.includes("desktop")) {
             stage("bundle");
@@ -135,5 +155,11 @@ export const build = async (root, options = {}) => {
     finally {
         await loader.close();
     }
-    return { dir: join(root, OUTPUT_DIR), files: built.flatMap((each) => each.files), pages: built.flatMap((each) => each.pages) };
+    const web = built.find((each) => each.size !== undefined);
+    return {
+        dir: join(root, OUTPUT_DIR),
+        files: built.flatMap((each) => each.files),
+        pages: built.flatMap((each) => each.pages),
+        ...(web?.size === undefined ? {} : { size: web.size, budgets: web.budgets, report: web.report }),
+    };
 };

package/dist/cli.js

@@ -4,11 +4,13 @@
 //   vlx dev [--port N] [--host H]   serve the project and rebuild it as it changes
 //   vlx build                       write the site to dist/web/
 //   vlx check [--json]              find mistakes in authored files without building
+//   vlx theme check [--json]        the theme: its tokens, recipes, contrast and what each target applies
 //   vlx generate page|component <name>   add a page, or a component registered in src/main.ts (alias: g)
 //   vlx sync                        bring .valance/ (generated types, manifest, entries) up to date; runs by itself after install and generate
 //   vlx help [command]              what a command does
 //
 // In a terminal, `init`, `dev`, `build` and `check` draw an interface (Ink, `ui/`). Anywhere else (a pipe, CI, `--json`, `--plain`) they print the plain text they always have.
+import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { INIT_HELP, parseInit } from "./args.js";
@@ -16,9 +18,11 @@ import { build } from "./build.js";
 import { packageDesktop } from "./package.js";
 import { generateComponent, generatePage, generateTarget, GenerateError, KINDS } from "./add.js";
 import { check } from "./check.js";
+import { themeReport } from "./theme.js";
 import { findRoot } from "./config.js";
 import { localCli } from "./delegate.js";
 import { dev } from "./dev.js";
+import { defaultRecording, replayFile } from "./replay.js";
 import { AppError, format } from "./diagnostics.js";
 import { detectPackageManager, directoryFor, directoryProblem, execute, nameProblem, runCommand, titleOf } from "./init.js";
 import { DEFAULT_TARGETS, TARGETS } from "./targets.js";
@@ -26,9 +30,11 @@ import { canAsk, canDraw } from "./tty.js";
 const HELP = `vlx <command>
 
   init [name] [--web]              make a new application
-  dev [--port N] [--host H]        serve it and rebuild as it changes
+  dev [--port N] [--host H]        serve it and rebuild as it changes (--record [file]: write a session log)
+  replay <log> [--route R] [--allow-user-data]  play a session log against this project and find where it differs
   build                            write the site to dist/web/
   check [--json]                   find mistakes in your files without building
+  theme check [--json]             check the theme: tokens, recipes, contrast, and what each target applies
   generate page|component <name>  add a page, or a component (alias: g)
   generate target web|desktop      add a target to the project
   package --desktop                the desktop target as one executable beside its window (unsigned)
@@ -55,10 +61,12 @@ const COMMAND_HELP = {
     init: INIT_HELP,
     generate: GENERATE_HELP,
     g: GENERATE_HELP,
-    dev: "vlx dev [--web|--desktop] [--port N] [--host H]\n\nServe the project (the web is served, a desktop project opens its window; a project of more than one target does both, or the one named) and rebuild it as files change. A mistake leaves the last good build serving and shows in the terminal and in the page.\n",
+    replay: "vlx replay <log> [--route changes,update,render] [--json] [--allow-user-data]\n\nPlay a session log (written by vlx dev --record, or one of MESH's conformance logs) against this project's templates by the three routes of the equivalence law, and find the first line where one differs from the log: a tree, an event's outcome, a program or manifest that is not the one recorded. It runs no command and reads no clock. Exits 0 when every route gave what the log recorded, 1 when one did not, 2 when the log cannot be read. A log that holds user data (every recording does: its header says containsUserData) is refused unless you pass --allow-user-data: a divergence prints what was typed and shown.\n",
+    dev: "vlx dev [--web|--desktop] [--port N] [--host H] [--record [file]]\n\nServe the project (the web is served, a desktop project opens its window; a project of more than one target does both, or the one named) and rebuild it as files change. A mistake leaves the last good build serving and shows in the terminal and in the page. --record writes the web page's session as a log (default .valance/sessions/<time>.jsonl) for vlx replay: development only, never uploaded, and it holds what the person typed.\n",
     build: "vlx build [--web] [--desktop]\n\nBuild every target the project has (or the ones named). The web: the site, in dist/web/; any host that serves files can serve it. The desktop: the engine, in dist/desktop/.\n",
     sync: "vlx sync\n\nBring .valance/ up to date: the generated types for your templates (so your editor and tsc agree with them), the manifest and the entries. You rarely run it: a new project does it after install (the `prepare` script), `vlx generate` does it after it writes, and dev, build and check do it as they run. It never fails: mistakes in your files are reported by vlx check.\n",
     package: "vlx package --desktop [--platform linux-x64|win32-x64] [--window <path>] [--node <path>] [--archive]\n\nBuild the desktop target and package it: the engine as one executable (Node's single executable application, with the MESH runtime inside) beside the Desktop PORT's window program, in dist/package/<platform>/. --window is the window program for that platform (default: VLX_WINDOW, else vlx-window on the PATH; build it from the PORT repository). For another platform, --node is a node binary of this version for it. --archive also writes the package as one file, a .tar.gz (Linux) or a .zip (Windows), with its SHA-256 beside it. The result is unsigned.\n",
+    theme: "vlx theme check [--json]\n\nCheck the theme: the project's `theme/theme.json` (its tokens by mode, in the Design Tokens format, and its recipes), or the default theme when it has none. Reports a token that does not resolve, a recipe that names a part, state, variant, property or token that does not exist, a removed focus ring, the contrast of every pair the theme declares (WCAG 2.2), and what the web and the desktop apply of it. --json prints the diagnostics, the contrast and the coverage.\n",
     check: "vlx check [--json]\n\nFind mistakes in your files without building. --json prints them as { file, line, column, code, message } for editors and CI.\n",
 };
 /** Refreshes `.valance/` and says so in a line. Best effort: a mistake in the project is `check`'s to report, and a project with no `valance.json` (the install ran before init finished) is left alone. */
@@ -79,6 +87,16 @@ const option = (args, name) => {
     const at = args.indexOf(name);
     return at < 0 ? undefined : args[at + 1];
 };
+/** `--record` alone, `--record file` or `--record=file`: the file, `""` for the default, nothing when it is not there. A word after it that is another flag is not its file. */
+const recordOption = (args) => {
+    const joined = args.find((each) => each.startsWith("--record="));
+    if (joined !== undefined) {
+        return joined.slice("--record=".length);
+    }
+    const at = args.indexOf("--record");
+    const next = at < 0 ? undefined : args[at + 1];
+    return at < 0 ? undefined : next === undefined || next.startsWith("-") ? "" : next;
+};
 const version = () => JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const runInit = async (args, cwd) => {
     if (args.name !== undefined) {
@@ -137,7 +155,15 @@ export const main = async (args, cwd = process.cwd()) => {
         return 0;
     }
     // A global `vlx` runs the project's own (see `delegate.ts`).
-    if (command === "dev" || command === "build" || command === "package" || command === "check" || command === "sync" || command === "generate" || command === "g") {
+    if (command === "dev" ||
+        command === "replay" ||
+        command === "build" ||
+        command === "package" ||
+        command === "check" ||
+        command === "theme" ||
+        command === "sync" ||
+        command === "generate" ||
+        command === "g") {
         const local = localCli(cwd);
         if (local !== undefined) {
             const theirs = (await import(pathToFileURL(local).href));
@@ -168,9 +194,12 @@ export const main = async (args, cwd = process.cwd()) => {
                     return 2;
                 }
                 const target = picked[0];
+                const asked = recordOption(rest);
+                const record = asked === undefined ? undefined : asked === "" ? defaultRecording(findRoot(cwd)) : resolve(cwd, asked);
                 if (draws) {
                     const { drawDev } = await import("./ui/run.js");
                     await drawDev(findRoot(cwd), {
+                        ...(record === undefined ? {} : { record }),
                         ...(target === undefined ? {} : { target }),
                         ...(port === undefined ? {} : { port: Number(port) }),
                         ...(host === undefined ? {} : { host }),
@@ -178,6 +207,7 @@ export const main = async (args, cwd = process.cwd()) => {
                     return 0;
                 }
                 const running = await dev(findRoot(cwd), {
+                    ...(record === undefined ? {} : { record }),
                     ...(target === undefined ? {} : { target }),
                     ...(port === undefined ? {} : { port: Number(port) }),
                     ...(host === undefined ? {} : { host }),
@@ -192,6 +222,21 @@ export const main = async (args, cwd = process.cwd()) => {
                 await running.close();
                 return 0;
             }
+            case "replay": {
+                const file = rest.find((each, index) => !each.startsWith("-") && rest[index - 1] !== "--route");
+                if (file === undefined) {
+                    console.error("vlx replay: name a log: vlx replay <log> [--route changes,update,render] [--json]");
+                    return 2;
+                }
+                const routes = option(rest, "--route");
+                const replayed = await replayFile(findRoot(cwd), resolve(cwd, file), {
+                    ...(routes === undefined ? {} : { routes: routes.split(",") }),
+                    json: rest.includes("--json"),
+                    allowUserData: rest.includes("--allow-user-data"),
+                });
+                (replayed.code === 0 ? console.log : console.error)(replayed.output);
+                return replayed.code;
+            }
             case "build": {
                 if (draws) {
                     const { drawBuild } = await import("./ui/run.js");
@@ -200,7 +245,7 @@ export const main = async (args, cwd = process.cwd()) => {
                 }
                 const started = Date.now();
                 const flagged = targetFlags(rest);
-                const built = await build(findRoot(cwd), flagged.length === 0 ? {} : { targets: flagged });
+                const built = await build(findRoot(cwd), { ...(flagged.length === 0 ? {} : { targets: flagged }), onReport: (report) => report.forEach((line) => console.log(line)) });
                 console.log(`vlx build: ${built.pages.length} pages, ${built.files.length} files → ${built.dir} (${((Date.now() - started) / 1000).toFixed(1)}s)`);
                 return 0;
             }
@@ -242,6 +287,32 @@ export const main = async (args, cwd = process.cwd()) => {
                 }
                 return result.diagnostics.length === 0 ? 0 : 1;
             }
+            case "theme": {
+                if (rest[0] !== "check") {
+                    console.error("vlx theme: say what: vlx theme check [--json]");
+                    return 2;
+                }
+                const report = themeReport(findRoot(cwd));
+                if (rest.includes("--json")) {
+                    console.log(JSON.stringify({ theme: report.name, custom: report.custom, diagnostics: report.diagnostics, contrast: report.contrast, coverage: report.coverage }, null, 2));
+                    return report.diagnostics.length === 0 ? 0 : 1;
+                }
+                console.log(`vlx theme check: ${report.custom ? "the project's theme" : "the default theme"} "${report.name}" (modes: ${report.modes.join(", ")})`);
+                for (const each of report.contrast) {
+                    console.log(`  contrast  ${each.mode.padEnd(9)} ${each.text} on ${each.on}  ${each.ratio.toFixed(2)}:1  (min ${each.min})  ${each.passes ? "ok" : "BELOW"}`);
+                }
+                for (const each of report.coverage) {
+                    console.log(`  ${each.target}: ${each.styled.length} of ${each.styled.length + each.unstyled.length} primitives of the portable core styled${each.unstyled.length === 0 ? "" : ` (not styled: ${each.unstyled.join(", ")})`}`);
+                    for (const note of each.notApplied) {
+                        console.log(`    not applied: ${note.primitive} ${note.kind} ${note.name} (${note.support})`);
+                    }
+                }
+                report.diagnostics.forEach((each) => {
+                    console.error(format(each));
+                });
+                console.log(report.diagnostics.length === 0 ? "vlx theme check: no problems" : `vlx theme check: ${report.diagnostics.length} problem${report.diagnostics.length === 1 ? "" : "s"}`);
+                return report.diagnostics.length === 0 ? 0 : 1;
+            }
             case "sync": {
                 const synced = await sync(cwd);
                 console.log(synced);