@valancex/cli 0.12.0 → 0.14.0

package/dist/compile.js

@@ -8,16 +8,19 @@ 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 { webVocabulary } from "@valancex/common/internal";
-import { ENTRY_FILE } from "./project.js";
+import { namesOf, webVocabulary, WHOLE } from "@valancex/common/internal";
+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";
 export const BUILT_IN = fileURLToPath(new URL("../views/", import.meta.url));
+/** The desktop target's built-in views: the same components as the web's, written in the desktop vocabulary. */
+export const BUILT_IN_DESKTOP = fileURLToPath(new URL("../views-desktop/", import.meta.url));
 /** The package directory: where its README, which documents the framework's own names, is. */
 export const PACKAGE_DIR = fileURLToPath(new URL("../", import.meta.url));
 const mprxIn = (dir) => existsSync(dir)
@@ -37,11 +40,11 @@ const entryText = (root) => {
  * Built-in templates, then the author's. The author's are exactly the ones `src/main.ts` declares: `layout`, `components` and `override`. A file under `src/` that is not declared is an error, not
  * a guess; a registered component that no template writes is allowed (it is not part of the program until one does). Which components a template uses is read from the template. A name that is a built-in's replaces it only through `override`.
  */
-export const templatesOf = (root, author, vocabulary = webVocabulary) => {
+export const templatesOf = (root, author, vocabulary = webVocabulary, views = BUILT_IN) => {
     const found = new Map();
-    for (const file of mprxIn(BUILT_IN)) {
+    for (const file of mprxIn(views)) {
         const component = basename(file, ".mprx");
-        found.set(component, { component, path: `@valancex/cli/views/${file}`, source: readFileSync(join(BUILT_IN, file), "utf8"), builtIn: true });
+        found.set(component, { component, path: `@valancex/cli/${basename(views)}/${file}`, source: readFileSync(join(views, file), "utf8"), builtIn: true });
     }
     const layout = author?.layout;
     const overrides = author?.override ?? [];
@@ -67,17 +70,30 @@ export const templatesOf = (root, author, vocabulary = webVocabulary) => {
     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 (node.name in vocabulary.tags) {
+        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;
         }
@@ -92,10 +108,17 @@ export const templatesOf = (root, author, vocabulary = webVocabulary) => {
         files.set(node.name, node.file);
         found.set(node.name, { component: node.name, path: node.file, source: readFileSync(join(root, node.file), "utf8"), builtIn: false });
     }
-    // Every template under src/ must be somewhere in the tree.
+    // Every template under src/ must be somewhere in a tree: this target's, or another target's (a project for more than one target keeps each one's templates side by side).
+    const claimed = new Set(files.values());
+    const whole = (author?.[WHOLE] ?? author);
+    for (const parts of [whole, ...Object.values(whole?.targets ?? {})]) {
+        for (const node of declaredOf(parts?.layout, parts?.override ?? [], parts?.components ?? [])) {
+            claimed.add(node.file);
+        }
+    }
     for (const file of mprxIn(join(root, SOURCE_DIR))) {
         const path = `${SOURCE_DIR}/${file}`;
-        if (![...files.values()].includes(path)) {
+        if (!claimed.has(path)) {
             problems.push(diagnostic(path, 0, "template-unused", `${path} is not in the component tree: import it in ${ENTRY_FILE} and ${basename(file) === `${ROOT}.mprx` ? "pass it as `layout`" : "list it in `components`"}`));
         }
     }
@@ -124,11 +147,40 @@ const reachable = (all) => {
     }
     return all.filter((template) => seen.has(template.component));
 };
-export const manifestOf = (author, vocabulary = webVocabulary) => manifest({
-    primitives: vocabulary.tags,
-    scopes: { [ROOT]: scopeSchema(author) },
-    commands: commandTable(author),
-});
+export const manifestOf = (author, vocabulary = webVocabulary) => {
+    const derived = manifest({
+        // A web vocabulary is a table the manifest is derived from; any other is a manifest already, and its components are merged in as they are.
+        primitives: "tags" in vocabulary ? vocabulary.tags : {},
+        scopes: { [ROOT]: scopeSchema(author) },
+        commands: commandTable(author),
+    });
+    if (!("tags" in vocabulary)) {
+        return { ...derived, components: { ...vocabulary.components, ...derived.components } };
+    }
+    // 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) {
+            components[tag] = {
+                ...entry,
+                props: Object.fromEntries(Object.entries(entry.props).map(([name, prop]) => [name, names.includes(name) ? { ...prop, required: false } : prop])),
+            };
+        }
+    }
+    return { ...derived, components };
+};
 const isManifestError = (error) => error instanceof Error && error._tag === "ManifestError";
 /**
  * The model the templates are checked against: the derived one (the tags, the layout's scope, the commands), and an entry for each component that declares its interface. A declared interface is
@@ -161,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;
     }
@@ -171,9 +225,35 @@ 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) => {
-    const { all, tree } = templatesOf(root, author, vocabulary);
+export const compileViews = async (root, author, vocabulary = webVocabulary, views = BUILT_IN) => {
+    const { all, tree } = templatesOf(root, author, vocabulary, views);
     const used = reachable(all);
     const model = modelOf(root, author, tree, vocabulary);
     if (!used.some((template) => template.component === ROOT)) {
@@ -188,12 +268,30 @@ export const compileViews = async (root, author, vocabulary = webVocabulary) =>
         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 {
@@ -205,7 +303,7 @@ export const compileViews = async (root, author, vocabulary = webVocabulary) =>
         templates: used.map((template) => ({
             component: template.component,
             file: template.builtIn
-                ? relative(root, join(BUILT_IN, `${template.component}.mprx`))
+                ? relative(root, join(views, `${template.component}.mprx`))
                     .split(sep)
                     .join("/")
                 : template.path,

package/dist/config.d.ts

@@ -1,10 +1,14 @@
+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";
+export declare const DESKTOP_FILE = "valance.desktop.json";
 /** The only version of both files there is. */
 export declare const CONFIG_VERSION = 1;
 export interface Config {
     readonly name: string;
+    /** The targets the project is built for: each one whose settings file it has (`valance.web.json`, `valance.desktop.json`), else the web alone. One application, one build per target. */
+    readonly targets: ReadonlyArray<"web" | "desktop">;
     /** How the document's title is written from a page's title and the site's name: `{page}` and `{site}`. */
     readonly title: string;
     readonly web: {
@@ -20,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,10 +3,12 @@
 // `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";
 export const WEB_FILE = "valance.web.json";
+export const DESKTOP_FILE = "valance.desktop.json";
 /** The only version of both files there is. */
 export const CONFIG_VERSION = 1;
 const read = (root, file) => {
@@ -90,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);
@@ -97,8 +125,10 @@ export const loadConfig = (root) => {
         throw new AppError([diagnostic(PROJECT_FILE, 0, "config-missing", `there is no ${PROJECT_FILE} in ${root}`)]);
     }
     const web = read(root, WEB_FILE);
+    const desktop = read(root, DESKTOP_FILE);
     const problems = [
-        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title }, ["name"]),
+        ...(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, 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) {
@@ -108,9 +138,12 @@ export const loadConfig = (root) => {
     const named = project.value;
     return {
         name: named.name,
+        targets: desktop === undefined ? ["web"] : web === undefined ? ["desktop"] : ["web", "desktop"],
         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-desktop.d.ts

@@ -0,0 +1,8 @@
+import type { Dev, DevOptions } from "./dev.js";
+/** Whether a changed file (relative to the project) is one the application is made of. */
+export declare const mattersToTheEngine: (file: string) => boolean;
+export interface DesktopDev extends Dev {
+    /** Resolves when the window is closed by the person (not by a rebuild). */
+    readonly closed: Promise<void>;
+}
+export declare const devDesktop: (root: string, options?: DevOptions) => Promise<DesktopDev>;

package/dist/dev-desktop.js

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { watch } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { build } from "./build.js";
+import { AppError, format } from "./diagnostics.js";
+/** How long files must be quiet before a change is built (ms). */
+const QUIET = 150;
+/** Whether a changed file (relative to the project) is one the application is made of. */
+export const mattersToTheEngine = (file) => {
+    const name = file.split("\\").join("/");
+    return /^(content|src|public)\//.test(name) || /^valance(\.\w+)?\.json$/.test(name);
+};
+export const devDesktop = async (root, options = {}) => {
+    const log = options.log ?? ((line) => void console.log(line));
+    const program = process.env["VLX_WINDOW"] ?? "vlx-window";
+    let window;
+    let stopping = false;
+    let working = Promise.resolve();
+    let timer;
+    let leave = () => undefined;
+    const closed = new Promise((resolve) => {
+        leave = resolve;
+    });
+    const reloadDir = mkdtempSync(join(tmpdir(), "vlx-reload-"));
+    const reloadFile = join(reloadDir, "reload");
+    let reloads = 0;
+    writeFileSync(reloadFile, "0");
+    /** Tells a running window the engine was rebuilt: a new modification time on the file it watches. */
+    const touch = () => {
+        reloads += 1;
+        writeFileSync(reloadFile, String(reloads));
+    };
+    const stopWindow = async () => {
+        const running = window;
+        window = undefined;
+        if (running !== undefined && running.exitCode === null) {
+            const exited = new Promise((resolve) => running.once("exit", () => resolve()));
+            running.kill();
+            await exited;
+        }
+    };
+    const openWindow = (engine) => {
+        const child = spawn(program, [], { stdio: "inherit", env: { ...process.env, VLX_ENGINE: `${process.execPath} ${engine}`, VLX_RELOAD: reloadFile } });
+        window = child;
+        child.once("error", (error) => {
+            window = undefined;
+            log(error.code === "ENOENT"
+                ? `vlx: no window program "${program}": install it with \`cargo install --git https://github.com/ValanceX/Port valancex-port-desktop --bin vlx-window\`, or name it in VLX_WINDOW`
+                : `vlx: the window could not start: ${error.message}`);
+        });
+        child.once("exit", () => {
+            if (window === child && !stopping) {
+                window = undefined;
+                log("vlx: the window was closed");
+                leave();
+            }
+        });
+    };
+    const rebuild = async () => {
+        try {
+            const built = await build(root, { targets: ["desktop"] });
+            options.onStatus?.([]);
+            if (stopping) {
+                return;
+            }
+            if (window !== undefined && window.exitCode === null) {
+                touch();
+                log("vlx: built; the window restarts the engine");
+            }
+            else {
+                openWindow(join(built.dir, "desktop", "engine.mjs"));
+                log("vlx: built; the window is open");
+            }
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                options.onStatus?.(error.diagnostics);
+                error.diagnostics.forEach((each) => log(format(each)));
+            }
+            else {
+                log(`vlx: the build failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    };
+    const queue = () => {
+        working = working.then(rebuild);
+    };
+    const watcher = watch(root, { recursive: true }, (_event, file) => {
+        if (file !== null && mattersToTheEngine(file)) {
+            clearTimeout(timer);
+            timer = setTimeout(queue, QUIET);
+        }
+    });
+    queue();
+    await working;
+    return {
+        url: "window",
+        closed,
+        settled: async () => {
+            await working;
+        },
+        close: async () => {
+            stopping = true;
+            clearTimeout(timer);
+            watcher.close();
+            await working;
+            await stopWindow();
+            rmSync(reloadDir, { recursive: true, force: true });
+            leave();
+        },
+    };
+};

package/dist/dev.d.ts

@@ -1,7 +1,15 @@
 import type { Diagnostic } from "./diagnostics.js";
+import type { TargetId } from "./targets.js";
 export interface DevOptions {
+    /** Which target to serve, for a project of more than one. */
+    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. */