@valancex/cli 0.13.0 → 0.14.0

package/dist/compile.js

@@ -8,12 +8,13 @@ import { basename, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { commandTable, scopeSchema } from "@valancex/common/internal";
 import { AppError, diagnostic } from "./diagnostics.js";
-import { declarationsOf, linked, nameOf, treeOf } from "./tree.js";
+import { declarationsOf, declaredOf, linked, nameOf, treeOf } from "./tree.js";
 import { tagsOf } from "./outline.js";
 import { entryOf } from "./contract.js";
 import { locateKey } from "./wiring.js";
 import { namesOf, webVocabulary, WHOLE } from "@valancex/common/internal";
-import { ENTRY_FILE } from "./project.js";
+import { checkReferences, checkTemplate } from "./rules.js";
+import { ENTRY_FILE, GENERATED_DIR } from "./project.js";
 export const SOURCE_DIR = "src";
 /** The component the page is drawn by. */
 export const ROOT = "layout";
@@ -69,16 +70,29 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     for (const each of overrides) {
         const name = nameOf(each.template.mprx);
         if (!builtInNames.has(name) && name !== ROOT) {
-            problem(at(each.template.mprx), "override-unknown", `<${name}> is not a built-in component, so there is nothing to override; list it in the \`uses\` of the component that uses it`);
+            problem(at(each.template.mprx), "override-unknown", `<${name}> is not a built-in component, so there is nothing to override; register it in \`components\` instead`);
+        }
+    }
+    // A name is one component. Two files of one name, from anywhere in the definition (two libraries', or a library's and the application's), are an error: the first listed must not win silently
+    // (decision K14). A component that is not listed in `override` and is named like a built-in is the same collision, with the built-in.
+    // TODO(K14): qualified ids (`acme-ui/disclosure`) will let a library's component be named and overridden without renaming a file; until then the way out of a collision is to rename one.
+    const listed = declaredOf(layout, overrides, author?.components ?? []);
+    const firstOf = new Map();
+    for (const each of listed) {
+        const first = firstOf.get(each.name);
+        if (first === undefined) {
+            firstOf.set(each.name, each.file);
+            if (each.role === "component" && builtInNames.has(each.name) && !listed.some((other) => other.role !== "component" && other.name === each.name)) {
+                problem(at(each.file), "template-builtin", `${each.file} is <${each.name}>, which is also a built-in component: list it in \`override\` to replace the built-in, or rename the file so both can be used`);
+            }
+        }
+        else if (first !== each.file) {
+            problem(at(each.file), "template-duplicate", `${each.file} is also <${each.name}>, like ${first}: a component is named by its file, so the name must be unique; rename one of the files`);
         }
     }
     const files = new Map();
     for (const node of declared) {
         const place = at(node.file);
-        if (files.has(node.name) && files.get(node.name) !== node.file) {
-            problem(place, "template-duplicate", `${files.get(node.name)} is also <${node.name}>: a component is named by its file, so the name must be unique`);
-            continue;
-        }
         if (namesOf(vocabulary).includes(node.name)) {
             problem(place, "template-primitive", `<${node.name}> is already a tag the framework draws as an element; name the file something else`);
             continue;
@@ -98,7 +112,7 @@ export const templatesOf = (root, author, vocabulary = webVocabulary, views = BU
     const claimed = new Set(files.values());
     const whole = (author?.[WHOLE] ?? author);
     for (const parts of [whole, ...Object.values(whole?.targets ?? {})]) {
-        for (const node of treeOf(parts?.layout, parts?.override ?? [], parts?.components ?? [])) {
+        for (const node of declaredOf(parts?.layout, parts?.override ?? [], parts?.components ?? [])) {
             claimed.add(node.file);
         }
     }
@@ -143,8 +157,19 @@ export const manifestOf = (author, vocabulary = webVocabulary) => {
     if (!("tags" in vocabulary)) {
         return { ...derived, components: { ...vocabulary.components, ...derived.components } };
     }
-    // The props the vocabulary says a template may leave out.
+    // What the vocabulary declares of a tag's props and events (the specification's) settles what the table alone derived.
     const components = { ...derived.components };
+    for (const [tag, declared] of Object.entries(vocabulary.declared ?? {})) {
+        const entry = components[tag];
+        if (entry !== undefined) {
+            components[tag] = {
+                ...entry,
+                props: Object.fromEntries(Object.entries(entry.props).map(([name, prop]) => [name, declared.props[name] === undefined ? prop : { ...prop, ...declared.props[name] }])),
+                events: Object.fromEntries(Object.entries(entry.events).map(([name, event]) => [name, declared.events[name] === undefined ? event : { ...event, ...declared.events[name] }])),
+            };
+        }
+    }
+    // The props the vocabulary says a template may leave out.
     for (const [tag, names] of Object.entries(vocabulary.optional ?? {})) {
         const entry = components[tag];
         if (entry !== undefined) {
@@ -188,8 +213,10 @@ const modelOf = (root, author, tree, vocabulary) => {
         const { entry, problems: bad } = entryOf(node.interface);
         const site = declarations.get(node.file);
         for (const each of bad) {
-            const place = site?.member(each.kind, each.name) ?? site?.call ?? site?.imported ?? { file: ENTRY_FILE, line: 1, column: 1 };
-            problems.push(diagnostic(place.file, place.line, "component-schema", `${node.name}'s ${each.kind === "props" ? "prop" : "event"} "${each.name}" has no type the model can hold: ${each.reason}`, place.column));
+            const place = site?.member(each.kind === "unit" ? "props" : each.kind, each.name) ?? site?.call ?? site?.imported ?? { file: ENTRY_FILE, line: 1, column: 1 };
+            problems.push(diagnostic(place.file, place.line, "component-schema", each.message === undefined
+                ? `${node.name}'s ${each.kind === "props" ? "prop" : each.kind === "unit" ? "unit field or command" : "event"} "${each.name}" has no type the model can hold: ${each.reason}`
+                : `${node.name}: ${each.message}`, place.column));
         }
         entries[node.name] = entry;
     }
@@ -198,6 +225,32 @@ const modelOf = (root, author, tree, vocabulary) => {
     }
     return { ...derived, components: { ...derived.components, ...entries } };
 };
+/** The anchors of the content's headings: the ids the built-in views give them (the generated `content.json`, which the content stage wrote before this one). */
+const anchorsOf = (root) => {
+    try {
+        const content = JSON.parse(readFileSync(join(root, GENERATED_DIR, "content.json"), "utf8"));
+        return new Set((content.pages ?? []).flatMap((page) => (page.blocks ?? []).flatMap((block) => (block.anchor === undefined ? [] : [block.anchor]))));
+    }
+    catch {
+        return new Set();
+    }
+};
+/** A tag the web renamed (decision P7: `para` is `paragraph`): said where a template still writes the old one. */
+const renamedHint = (vocabulary, used, at) => {
+    // a prop the web renamed (decision I29: a popover's `kind` is `mode`): the diagnostic names the tag and the prop
+    const prop = /component "([^"]+)" has no prop "([^"]+)"/.exec(at.message ?? "");
+    const renamedProp = prop === null || !("tags" in vocabulary) ? undefined : vocabulary.renamedProps?.[prop[1]]?.[prop[2]];
+    if (renamedProp !== undefined) {
+        return ` (\`${prop[2]}\` on \`${prop[1]}\` is now \`${renamedProp}\`)`;
+    }
+    const renamed = "tags" in vocabulary ? vocabulary.renamed : undefined;
+    const line = used.find((template) => template.path === at.path)?.source.split("\n")[at.span.start.line - 1];
+    if (renamed === undefined || line === undefined) {
+        return "";
+    }
+    const tag = /<\/?([A-Za-z][\w-]*)/.exec(line.slice(Math.max(0, at.span.start.column - 2)))?.[1];
+    return tag !== undefined && Object.hasOwn(renamed, tag) ? ` (\`${tag}\` is now \`${renamed[tag]}\`)` : "";
+};
 /** Compiles the application's templates against a target's vocabulary (the web's by default). Fails with every diagnostic, each pointing into the file it is about. */
 export const compileViews = async (root, author, vocabulary = webVocabulary, views = BUILT_IN) => {
     const { all, tree } = templatesOf(root, author, vocabulary, views);
@@ -215,12 +268,30 @@ export const compileViews = async (root, author, vocabulary = webVocabulary, vie
         const found = [
             ...(result.components ?? []).flatMap((entry) => entry.diagnostics.diagnostics
                 .filter((each) => each.severity === "error")
-                .map((each) => diagnostic(each.path, each.span.start.line, each.code, each.message + (each.suggestions.length > 0 ? ` (did you mean ${each.suggestions.map((suggestion) => `"${suggestion.replacement}"`).join(" or ")}?)` : ""), each.span.start.column))),
+                .map((each) => diagnostic(each.path, each.span.start.line, each.code, each.message +
+                (each.suggestions.length > 0 ? ` (did you mean ${each.suggestions.map((suggestion) => `"${suggestion.replacement}"`).join(" or ")}?)` : "") +
+                renamedHint(vocabulary, used, each), each.span.start.column))),
             ...(result.assembly?.diagnostics ?? []).map((each) => diagnostic(each.path ?? "program", each.span?.start.line ?? 0, each.code, each.message, each.span?.start.column ?? 0)),
         ];
         throw new AppError(found.map((each) => relocate(each, root)));
     }
     const program = result.program;
+    const rules = "tags" in vocabulary ? vocabulary.rules : undefined;
+    if (rules !== undefined) {
+        const texts = program.templates;
+        const known = new Set(namesOf(vocabulary));
+        const broken = used.flatMap((template, index) => checkTemplate(template.path, template.source, JSON.parse(texts[index] ?? "{}"), rules, known, tree.find((node) => node.name === template.component)?.interface?.name));
+        const compiled = used.map((template, index) => ({
+            file: template.path,
+            source: template.source,
+            template: JSON.parse(texts[index] ?? "{}"),
+            builtIn: template.builtIn,
+        }));
+        broken.push(...checkReferences(compiled, anchorsOf(root)));
+        if (broken.length > 0) {
+            throw new AppError(broken.map((each) => relocate(each, root)));
+        }
+    }
     const enriched = program.model;
     const manifestOfProgram = typeof enriched === "string" ? JSON.parse(enriched) : enriched;
     return {

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { Budget } from "./size.js";
 import type { SiteInfo } from "@valancex/common/internal";
 export declare const PROJECT_FILE = "valance.json";
 export declare const WEB_FILE = "valance.web.json";
@@ -23,6 +24,15 @@ export interface Config {
         readonly base: string;
         readonly proxy: string;
     };
+    /** The size budgets a production build is held to (Tier 2): the project's own, or none, in which case the framework's start-up budgets apply (W14). Never checked by `vlx dev`. */
+    readonly budgets: ReadonlyArray<Budget> | undefined;
+    /** What `vlx dev --record` leaves out of a session log (Tier 2; R9, R14): nothing, unless the project says. */
+    readonly record: {
+        readonly redact: {
+            readonly scope: ReadonlyArray<ReadonlyArray<string>>;
+            readonly commands: ReadonlyArray<string>;
+        };
+    };
 }
 /** Reads and validates the project's configuration. Every problem in both files is reported together. */
 export declare const loadConfig: (root: string) => Config;

package/dist/config.js

@@ -3,6 +3,7 @@
 // `schemas/` describe the same files for editors; this is the check the tools make.
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { budgetProblems } from "./size.js";
 import { AppError, diagnostic, lineOf } from "./diagnostics.js";
 import { DEFAULT_TITLE } from "@valancex/common/internal";
 export const PROJECT_FILE = "valance.json";
@@ -91,6 +92,32 @@ const api = (value) => {
     }
     return undefined;
 };
+const record = (value) => {
+    const redact = value?.redact;
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => key !== "redact") ||
+        typeof redact !== "object" ||
+        redact === null ||
+        Array.isArray(redact)) {
+        return 'must be an object such as { "redact": { "scope": [["password"]], "commands": ["login/type"] } }';
+    }
+    const { scope, commands, ...others } = redact;
+    if (Object.keys(others).length > 0) {
+        return `"redact" has unknown settings ${Object.keys(others)
+            .map((key) => `"${key}"`)
+            .join(", ")} (known: scope, commands)`;
+    }
+    if (scope !== undefined &&
+        (!Array.isArray(scope) || scope.some((path) => !Array.isArray(path) || path.length === 0 || path.some((step) => typeof step !== "string" || step === "")))) {
+        return '"redact.scope" must be a list of paths, each a non-empty list of field names ("*" is any list index or field): [["password"], ["people", "*", "pin"]]';
+    }
+    if (commands !== undefined && (!Array.isArray(commands) || commands.some((name) => typeof name !== "string" || !/^[\w-]+\/[\w-]+$/.test(name)))) {
+        return '"redact.commands" must be a list of "component/name" commands whose parameters are not recorded: ["login/type"]';
+    }
+    return undefined;
+};
 /** Reads and validates the project's configuration. Every problem in both files is reported together. */
 export const loadConfig = (root) => {
     const project = read(root, PROJECT_FILE);
@@ -101,7 +128,7 @@ export const loadConfig = (root) => {
     const desktop = read(root, DESKTOP_FILE);
     const problems = [
         ...(desktop === undefined ? [] : check(DESKTOP_FILE, desktop.text, desktop.value, { $schema: schema, version }, [])),
-        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title }, ["name"]),
+        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title, record, budgets: budgetProblems }, ["name"]),
         ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url, headers: flag, announce: flag, api }, [])),
     ];
     if (problems.length > 0) {
@@ -115,6 +142,8 @@ export const loadConfig = (root) => {
         title: named.title ?? DEFAULT_TITLE,
         web: { base: given.base ?? "/", url: given.url ?? "", headers: given.headers ?? true, announce: given.announce ?? true },
         api: { base: given.api?.base ?? "", proxy: given.api?.proxy ?? "" },
+        budgets: named.budgets,
+        record: { redact: { scope: named.record?.redact.scope ?? [], commands: named.record?.redact.commands ?? [] } },
     };
 };
 export const siteInfo = (config) => ({

package/dist/contract.d.ts

@@ -7,6 +7,7 @@ export interface Entry {
     readonly props: Readonly<Record<string, {
         readonly type: MeshType;
         readonly required: boolean;
+        readonly default?: unknown;
     }>>;
     readonly events: Readonly<Record<string, {
         readonly payload?: MeshType;
@@ -14,12 +15,28 @@ export interface Entry {
     readonly commands: Readonly<Record<string, never>>;
     /** Every prop is a name the template reads: the same name and type, absent when the prop may be. */
     readonly scope: Readonly<Record<string, MeshType>>;
+    /** The state and commands of one occurrence, when the component has a unit: their names join the scope and the commands in the model. */
+    readonly unit?: {
+        readonly state: Readonly<Record<string, {
+            readonly type: MeshType;
+            readonly default: unknown;
+            readonly controllable?: boolean;
+        }>>;
+        readonly commands: Readonly<Record<string, {
+            readonly parameters: ReadonlyArray<{
+                readonly name: string;
+                readonly type: MeshType;
+            }>;
+        }>>;
+    };
 }
 /** A schema with no model type, said at the declaration. */
 export interface Problem {
-    readonly kind: "props" | "events";
+    readonly kind: "props" | "events" | "unit";
     readonly name: string;
     readonly reason: string;
+    /** The whole message, for a problem that is not a missing type. */
+    readonly message?: string;
 }
 /** What a schema is in the model: put in a struct, so the rules are state's. A field that may be `undefined` comes back optional. */
 export declare const typeOf: (schema: SchemaOf) => MeshType;

package/dist/contract.js

@@ -1,5 +1,6 @@
 import { manifest } from "@valancex/valance/web/build";
 import { Schema } from "effect";
+import { isField, isSnippet } from "@valancex/common";
 /** What a schema is in the model: put in a struct, so the rules are state's. A field that may be `undefined` comes back optional. */
 export const typeOf = (schema) => {
     const derived = manifest({ primitives: {}, scopes: { contract: Schema.Struct({ value: schema }) }, commands: () => ({}) });
@@ -17,11 +18,39 @@ export const entryOf = (declared) => {
     const props = {};
     const scope = {};
     const events = {};
-    for (const [name, schema] of Object.entries(declared.props)) {
+    for (const [name, declaration] of Object.entries(declared.props)) {
         try {
+            if (isSnippet(declaration)) {
+                // A piece of template: a prop of the component and a name its template reads (`{@render name(…)}`). It is not data, so it has no default and is never absent.
+                if (name === "children" && declaration.params.length > 0) {
+                    throw new Error("`children` is the content between the component's tags, so it takes no parameters: write `snippet()`");
+                }
+                const params = declaration.params.map((schema) => {
+                    const type = typeOf(schema);
+                    return type.kind === "optional" ? type.type : type;
+                });
+                const type = { kind: "snippet", params };
+                // An optional one is `snippet<…>?` in the scope too: the template renders it only where `has(name)` says it is there.
+                props[name] = declaration.isOptional ? { type: { kind: "optional", type }, required: false } : { type, required: true };
+                scope[name] = declaration.isOptional ? { kind: "optional", type } : type;
+                continue;
+            }
+            if (name === "children") {
+                throw new Error("`children` is reserved for the content between the component's tags: declare it `snippet()`");
+            }
+            const schema = isField(declaration) ? declaration.schema : declaration;
             const type = typeOf(schema);
             const optional = type.kind === "optional";
-            props[name] = { type: optional ? type.type : type, required: !optional };
+            if (isField(declaration)) {
+                // A default is for a component that has a template (the model applies it to those only) and is written as the schema encodes it. The prop may then be left out.
+                if (!Schema.is(schema)(declaration.initial)) {
+                    throw new Error("its default is not a value of its type");
+                }
+                props[name] = { type: optional ? type.type : type, required: false, default: Schema.encodeSync(schema)(declaration.initial) };
+            }
+            else {
+                props[name] = { type: optional ? type.type : type, required: !optional };
+            }
             scope[name] = type;
         }
         catch (error) {
@@ -41,5 +70,58 @@ export const entryOf = (declared) => {
             problems.push({ kind: "events", name, reason: reasonOf(error) });
         }
     }
-    return { entry: { props, events, commands: {}, scope }, problems };
+    const unit = declared.unit === undefined ? undefined : unitEntry(declared.unit, props, problems);
+    if (declared.name !== undefined) {
+        const named = props[declared.name];
+        if (named === undefined && !problems.some((each) => each.name === declared.name)) {
+            problems.push({ kind: "props", name: declared.name, reason: "", message: `"${declared.name}" is declared as the component's name (\`name\`) but is not one of its props` });
+        }
+        else if (named !== undefined && (named.type.kind !== "string" || !named.required)) {
+            problems.push({
+                kind: "props",
+                name: declared.name,
+                reason: "",
+                message: `the prop "${declared.name}" is the component's name (\`name\`), so it must be a string every use writes: \`Schema.String\`, with no default and not optional`,
+            });
+        }
+    }
+    return { entry: { props, events, commands: {}, scope, ...(unit === undefined ? {} : { unit }) }, problems };
+};
+/** The model's `unit` of a component: each state field with its type and default, each command with its parameters. A field whose schema has no model type is a problem at the declaration. */
+const unitEntry = (declared, props, problems) => {
+    const state = {};
+    const commands = {};
+    for (const [name, field] of Object.entries(declared.fields)) {
+        try {
+            const type = typeOf(field.schema);
+            const controllable = declared.controllable.includes(name);
+            if (!Schema.is(field.schema)(field.initial)) {
+                throw new Error("its default is not a value of its type");
+            }
+            if (controllable && props[name] === undefined) {
+                throw new Error("it is `controllable`, so the component must declare a prop of the same name (optional, of the same type) for the caller to own it with");
+            }
+            state[name] = {
+                type: type.kind === "optional" ? type.type : type,
+                default: Schema.encodeSync(field.schema)(field.initial),
+                ...(controllable ? { controllable: true } : {}),
+            };
+        }
+        catch (error) {
+            problems.push({ kind: "unit", name, reason: reasonOf(error) });
+        }
+    }
+    for (const [name, command] of Object.entries(declared.commands)) {
+        try {
+            const parameters = Object.entries(command.input?.fields ?? {}).map(([parameter, schema]) => {
+                const type = typeOf(schema);
+                return { name: parameter, type: type.kind === "optional" ? type.type : type };
+            });
+            commands[name] = { parameters };
+        }
+        catch (error) {
+            problems.push({ kind: "unit", name, reason: reasonOf(error) });
+        }
+    }
+    return { state, commands };
 };

package/dist/dev.d.ts

@@ -5,6 +5,11 @@ export interface DevOptions {
     readonly target?: TargetId;
     readonly port?: number;
     readonly host?: string;
+    /**
+     * Record the session (`--record`): the file the page's log is appended to (`@valancex/valance/replay`; read it with `vlx replay`). A development feature, never uploaded: a log holds
+     * what the person typed. The generated page entry that records is rewritten without it by the next run that does not ask for it.
+     */
+    readonly record?: string;
     /** Called with each report (a rebuild, a mistake); defaults to the console. */
     readonly log?: (line: string) => void;
     /** Called with every mistake still open, after the first build and after each rebuild: empty when the project is sound. */

package/dist/dev.js

@@ -1,5 +1,20 @@
+// `vlx dev`: the project served from memory and from disk, rebuilt as its authored files change. Built on a Vite server for what Vite is good at (serving modules, style updates without a
+// reload, the error overlay); everything else is this file's: each page is rendered on the server with the same code a build uses, so development shows what production will.
+//
+// What each change does:
+//
+//   content/**               the content is rebuilt; the browser reloads
+//   src/**/*.mprx, src/main.ts   the templates are recompiled (the manifest derives from main.ts); the browser reloads
+//   src/**/*.css             the style is replaced in the open page, no reload
+//   public/**                the browser reloads
+//   adding or removing a stylesheet or src/main.ts   the entries are rewritten; the browser reloads
+//   valance.json, valance.web.json   the server restarts (the name and the base are fixed when it starts)
+//
+// A mistake in any of them leaves the last good build serving, and is shown in the terminal and as an overlay in the page, naming the file and line. Fixing it reloads the page.
+import { recordingNotice } from "./recording-guard.js";
 import { createServer } from "vite";
-import { relative, sep } from "node:path";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, relative, sep } from "node:path";
 import { loadAuthor } from "./author.js";
 import { loadConfig, PROJECT_FILE, WEB_FILE } from "./config.js";
 import { AppError, format } from "./diagnostics.js";
@@ -51,7 +66,10 @@ const start = async (root, config, options, restart) => {
         });
     const failed = new Map();
     let pending = Promise.resolve();
-    generateEntries(root, config);
+    generateEntries(root, config, { record: options.record !== undefined });
+    if (options.record !== undefined) {
+        recordingNotice(root, options.record, config).forEach(log);
+    }
     const base = baseConfig(root, config);
     const server = await createServer({
         ...base,
@@ -67,29 +85,45 @@ const start = async (root, config, options, restart) => {
             ...(base.plugins ?? []),
             {
                 name: "valance",
-                configureServer: (vite) => () => {
-                    // After Vite's own middleware: modules, styles, public files and the client have had their chance. What is left is a page.
-                    vite.middlewares.use((request, response, next) => {
-                        void (async () => {
-                            // Vite has already removed the base from `request.url`; the application's addresses include it.
-                            const url = new URL(request.originalUrl ?? request.url ?? "/", "http://localhost");
-                            if ((request.method !== "GET" && request.method !== "HEAD") || !url.pathname.startsWith(config.web.base) || /\.[A-Za-z0-9]+$/.test(url.pathname)) {
-                                next();
-                                return;
-                            }
-                            try {
-                                const { render } = (await vite.ssrLoadModule(SERVER_ENTRY));
-                                const { status, html } = await render(url.pathname, { script: `${config.web.base}${GENERATED_DIR}/client.ts`, styles: [] });
-                                response.statusCode = status;
-                                response.setHeader("content-type", "text/html; charset=utf-8");
-                                response.end(await vite.transformIndexHtml(url.pathname, html));
-                            }
-                            catch (error) {
-                                vite.ssrFixStacktrace(error);
-                                next(error);
-                            }
-                        })();
-                    });
+                configureServer: (vite) => {
+                    if (options.record !== undefined) {
+                        const file = options.record;
+                        mkdirSync(dirname(file), { recursive: true });
+                        // the page's recorder posts each line of its log here, in order
+                        vite.middlewares.use("/__vlx/record", (request, response) => {
+                            const chunks = [];
+                            request.on("data", (chunk) => chunks.push(chunk));
+                            request.on("end", () => {
+                                appendFileSync(file, `${Buffer.concat(chunks).toString("utf8")}\n`);
+                                response.statusCode = 204;
+                                response.end();
+                            });
+                        });
+                    }
+                    return () => {
+                        // After Vite's own middleware: modules, styles, public files and the client have had their chance. What is left is a page.
+                        vite.middlewares.use((request, response, next) => {
+                            void (async () => {
+                                // Vite has already removed the base from `request.url`; the application's addresses include it.
+                                const url = new URL(request.originalUrl ?? request.url ?? "/", "http://localhost");
+                                if ((request.method !== "GET" && request.method !== "HEAD") || !url.pathname.startsWith(config.web.base) || /\.[A-Za-z0-9]+$/.test(url.pathname)) {
+                                    next();
+                                    return;
+                                }
+                                try {
+                                    const { render } = (await vite.ssrLoadModule(SERVER_ENTRY));
+                                    const { status, html } = await render(url.pathname, { script: `${config.web.base}${GENERATED_DIR}/client.ts`, styles: [] });
+                                    response.statusCode = status;
+                                    response.setHeader("content-type", "text/html; charset=utf-8");
+                                    response.end(await vite.transformIndexHtml(url.pathname, html));
+                                }
+                                catch (error) {
+                                    vite.ssrFixStacktrace(error);
+                                    next(error);
+                                }
+                            })();
+                        });
+                    };
                 },
             },
         ],
@@ -115,7 +149,7 @@ const start = async (root, config, options, restart) => {
         };
         const wasFailing = failed.size > 0;
         if (stages.includes("entries")) {
-            generateEntries(root, config);
+            generateEntries(root, config, { record: options.record !== undefined });
         }
         if (stages.includes("content")) {
             await run("content", () => generateContent(root, config));

package/dist/emit.d.ts

@@ -13,4 +13,6 @@ export declare const generateProgram: (root: string, author: DefinedApp | undefi
 /** The declaration of one template's type: its props and events as the names TypeScript checks a contract's keys against. */
 export declare const templateType: (props: ReadonlyArray<string>, events: ReadonlyArray<string>) => string;
 /** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. Each target has its own: the web's two (`client.ts`, `server.ts`), the desktop's one (`desktop.ts`). */
-export declare const generateEntries: (root: string, config?: Config) => boolean;
+export declare const generateEntries: (root: string, config?: Config, options?: {
+    readonly record?: boolean;
+}) => boolean;

package/dist/emit.js

@@ -21,22 +21,35 @@ import { targetOf } from "./targets.js";
 import { forTarget } from "@valancex/common/internal";
 import { AppError } from "./diagnostics.js";
 import { ENTRY_FILE, ensureGeneratedDir, GENERATED_DIR, generated, writeIfChanged } from "./project.js";
+import { themeOf } from "./theme.js";
 import { buildWiring } from "./wiring.js";
-/** The layout of the portable core on the web: `column` and `row` are custom elements, and this is what they are (`@valancex/common`'s web vocabulary). It comes first, so a project's own styles win. */
+/** The layout of the portable core on the web: `column` and `row` are custom elements, and this is what they are (`@valancex/common`'s web vocabulary). It is the library's layer, the first of the
+ *  three (library, theme, application): a theme's gap replaces the default here, and a project's own styles, which are in no layer, win over both. */
 const CORE_CSS = `/* Generated by \`valance\`. The web's realization of the portable core's layout components. */
-vlx-column {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
+@layer vlx-library, vlx-theme, vlx-app;
+
+@layer vlx-library {
+  vlx-column {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+
+  vlx-row {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.5rem;
+  }
 
-vlx-row {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  gap: 0.5rem;
+  /* Until the application has started (H5) a control the person can see does not yet do anything: say so, so they do not tap it again. */
+  [data-vlx="starting"] :is(button, input, select, textarea, summary, [role="button"], label) {
+    cursor: progress;
+  }
 }
 `;
+/** The theme's stylesheet. A theme with a problem is reported by \`check\` (and refused by \`build\`); the page gets no theme meanwhile rather than a half of one. */
+const themeStylesheet = (root) => themeOf(root).css ?? "/* The theme has a problem: run `vlx check`. */\n";
 /** The stylesheets the web loads: every one under `src/` except those in another target's directory (`src/desktop/`). */
 const stylesheets = (root) => existsSync(join(root, SOURCE_DIR))
     ? readdirSync(join(root, SOURCE_DIR), { recursive: true, encoding: "utf8" })
@@ -46,20 +59,22 @@ const stylesheets = (root) => existsSync(join(root, SOURCE_DIR))
         .map((file) => `${SOURCE_DIR}/${file}`)
     : [];
 export const hasEntry = (root) => existsSync(join(root, ENTRY_FILE));
-const clientSource = (root, config) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
+const clientSource = (root, config, record = false) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
 // @ts-nocheck
 import { start } from "@valancex/common/client";
 import content from "./content.json";
 import program from "./${programFile(config, "web")}";
+import "./theme.css";
 import "./core.css";
 ${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}${stylesheets(root)
     .map((file) => `import "../${file}";\n`)
     .join("")}
-await start({ content, program, author });
+${record ? `// \`vlx dev --record\`: development only. A build rewrites this entry without it.\nconst { recording } = await import("@valancex/common/record");\nconst record = recording(program, ${JSON.stringify(config?.record.redact ?? { scope: [], commands: [] })});\n` : ""}await start({ content, program, author${record ? ", record" : ""} });
 `;
 const desktopSource = (root, config) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
 // @ts-nocheck
 import { start } from "@valancex/common/desktop";
+import theme from "./theme.desktop.json";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import content from "./content.json";
@@ -69,7 +84,7 @@ ${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author =
 const wasm = new Uint8Array(readFileSync(new URL("./mesh-runtime.wasm", import.meta.url)));
 // (and the project's public/ files, which images are drawn from)
 const assets = fileURLToPath(new URL("./public/", import.meta.url));
-await start({ content, program, author, wasm, assets });
+await start({ content, program, author, wasm, assets, theme: theme ?? undefined });
 // the window is closed: nothing the application left open keeps the engine alive
 process.exit(0);
 `;
@@ -113,6 +128,8 @@ export const generateProgram = async (root, author, config, only) => {
             problems.push(...error.diagnostics);
         }
     }
+    // a theme the project writes is checked with the templates: a mistake in it is as much the project's as one in a layout
+    problems.push(...(themeOf(root).custom ? themeOf(root).diagnostics : []));
     if (problems.length > 0) {
         throw new AppError(problems);
     }
@@ -169,17 +186,23 @@ const writeTemplateTypes = (root, all) => {
     }
 };
 /** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. Each target has its own: the web's two (`client.ts`, `server.ts`), the desktop's one (`desktop.ts`). */
-export const generateEntries = (root, config) => {
+export const generateEntries = (root, config, options) => {
     ensureGeneratedDir(root);
     const targets = config?.targets ?? ["web"];
     return [
         ...(targets.includes("web")
             ? [
                 writeIfChanged(generated(root, "core.css"), CORE_CSS),
-                writeIfChanged(generated(root, "client.ts"), clientSource(root, config)),
+                writeIfChanged(generated(root, "theme.css"), themeStylesheet(root)),
+                writeIfChanged(generated(root, "client.ts"), clientSource(root, config, options?.record === true)),
                 writeIfChanged(generated(root, "server.ts"), serverSource(root, config)),
             ]
             : []),
-        ...(targets.includes("desktop") ? [writeIfChanged(generated(root, "desktop.ts"), desktopSource(root, config))] : []),
+        ...(targets.includes("desktop")
+            ? [
+                writeIfChanged(generated(root, "theme.desktop.json"), `${JSON.stringify(themeOf(root).desktop ?? null)}\n`),
+                writeIfChanged(generated(root, "desktop.ts"), desktopSource(root, config)),
+            ]
+            : []),
     ].some(Boolean);
 };