@valancex/cli 0.11.0 → 0.13.0

package/dist/build.js

@@ -1,48 +1,77 @@
-// `vlx build`: the project → a static site in `dist/`. The stages, in order: configuration, content, templates, the browser bundle, then one document per page (and a 404 page, a sitemap
-// when the site has a published address). Everything is generated under `.valance/` first; `dist/` holds only the site.
+// `vlx build`: the project → a static site in `dist/web/`. The stages, in order: configuration, content, templates, the browser bundle, then one document per page (and a 404 page, a sitemap
+// when the site has a published address). Everything is generated under `.valance/` first; `dist/` holds only what is built.
 import { build as bundle } from "vite";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { loadAuthor } from "./author.js";
 import { loadConfig } from "./config.js";
+import { headersFile } from "./security.js";
 import { AppError } from "./diagnostics.js";
 import { generateContent, generateEntries, generateProgram } from "./emit.js";
 import { OUTPUT_DIR } from "./project.js";
-import { baseConfig, createLoader, SERVER_ENTRY } from "./vite.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. */
 export const fileOf = (pathname, base) => {
     const inside = pathname.slice(base.length).replace(/\/+$/, "");
     return inside === "" ? "index.html" : `${inside}/index.html`;
 };
 const sitemap = (content) => `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${content.pages.map((page) => `  <url><loc>${content.site.url}${content.site.base}${page.path.replace(/^\//, "")}</loc></url>`).join("\n")}\n</urlset>\n`;
-export const build = async (root, options = {}) => {
-    const stage = options.onStage ?? (() => undefined);
-    stage("configuration");
-    const config = loadConfig(root);
-    generateEntries(root);
-    stage("content");
-    const content = generateContent(root, config);
-    const loader = await createLoader(root, config);
-    let rendered;
-    try {
-        stage("templates");
-        const author = await loadAuthor(loader, root);
-        await generateProgram(root, author);
-        // The browser bundle first: it empties dist/, and the documents are written into it after.
-        stage("bundle");
-        await bundle({ ...baseConfig(root, config), mode: "production" });
-        rendered = (await loader.ssrLoadModule(SERVER_ENTRY));
-    }
-    catch (error) {
-        await loader.close();
-        throw error;
+/** The MESH runtime's module, found the way the project's own dependency would be: through `@valancex/common`, which depends on it. */
+const wasmOf = (root) => {
+    const fromRoot = createRequire(join(root, "package.json"));
+    const fromCommon = createRequire(fromRoot.resolve("@valancex/common/package.json"));
+    return fromCommon.resolve("@valancex/mesh-runtime/mesh-runtime.wasm");
+};
+/** The desktop build: the engine, one ES module with everything it needs bundled in, and the MESH runtime's module beside it, in `dist/desktop/`. The window is the Desktop PORT's. */
+const buildDesktop = async (root) => {
+    const out = join(root, OUTPUT_DIR, "desktop");
+    rmSync(out, { recursive: true, force: true });
+    await bundle({
+        root,
+        configFile: false,
+        publicDir: false, // the site's public files are the web's
+        logLevel: "warn",
+        plugins: [templates(root)],
+        cacheDir: join(root, GENERATED_DIR, "cache"),
+        ssr: { noExternal: true, target: "node" },
+        build: {
+            ssr: join(root, GENERATED_DIR, "desktop.ts"),
+            outDir: out,
+            emptyOutDir: true,
+            target: "node22",
+            minify: false,
+            chunkSizeWarningLimit: 4000,
+            rollupOptions: {
+                output: {
+                    format: "es",
+                    entryFileNames: "engine.mjs",
+                    banner: 'import { createRequire as __vlxRequire } from "node:module"; const require = __vlxRequire(import.meta.url);',
+                },
+            },
+        },
+    });
+    copyFileSync(wasmOf(root), join(out, "mesh-runtime.wasm"));
+    // The files images are drawn from, beside the engine (the site's `public/`, which the desktop's content refers to the same way).
+    const publicDir = join(root, "public");
+    if (existsSync(publicDir)) {
+        cpSync(publicDir, join(out, "public"), { recursive: true });
     }
-    try {
-        const dist = join(root, OUTPUT_DIR);
+    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) => {
+    // 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" });
+    const rendered = (await loader.ssrLoadModule(SERVER_ENTRY));
+    {
+        const dist = join(root, out);
         const manifest = JSON.parse(readFileSync(join(dist, ".vite", "manifest.json"), "utf8"));
         const entry = Object.values(manifest).find((chunk) => chunk.isEntry === true);
         if (entry === undefined) {
-            throw new AppError([{ file: OUTPUT_DIR, line: 0, column: 0, code: "build-entry", message: "the bundle has no entry chunk" }]);
+            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}`) };
@@ -62,9 +91,49 @@ export const build = async (root, options = {}) => {
         if (config.web.url !== "") {
             write("sitemap.xml", sitemap(content));
         }
-        return { dir: dist, files, pages };
+        // The headers to serve it with: the page is only as safe as the host makes it (src/security.ts).
+        if (config.web.headers) {
+            write("_headers", headersFile(config));
+        }
+        return { dir: dist, files: files.map((file) => `${prefix}${file}`), pages };
+    }
+};
+export const build = async (root, options = {}) => {
+    const stage = options.onStage ?? (() => undefined);
+    stage("configuration");
+    const config = loadConfig(root);
+    const selected = options.targets ?? config.targets;
+    const unknown = selected.filter((id) => !config.targets.includes(id));
+    if (unknown.length > 0) {
+        throw new AppError([
+            {
+                file: "valance.json",
+                line: 0,
+                column: 0,
+                code: "build-target",
+                message: `this project is not built for ${unknown.join(", ")} (its targets: ${config.targets.join(", ")}): add valance.${unknown[0]}.json`,
+            },
+        ]);
+    }
+    generateEntries(root, config);
+    stage("content");
+    const content = generateContent(root, config);
+    const loader = await createLoader(root, config);
+    const built = [];
+    try {
+        stage("templates");
+        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));
+        }
+        if (selected.includes("desktop")) {
+            stage("bundle");
+            built.push(await buildDesktop(root));
+        }
     }
     finally {
         await loader.close();
     }
+    return { dir: join(root, OUTPUT_DIR), files: built.flatMap((each) => each.files), pages: built.flatMap((each) => each.pages) };
 };

package/dist/check.js

@@ -22,13 +22,13 @@ export const check = async (root) => {
     if (config === undefined) {
         return { diagnostics: problems, pages: 0, components: [] };
     }
-    generateEntries(root);
+    generateEntries(root, config);
     const content = await collect(problems, () => generateContent(root, config));
     const server = await createLoader(root, config);
     try {
         const author = await collect(problems, () => loadAuthor(server, root));
         const failedAuthor = problems.some((each) => each.file === "src/main.ts");
-        const components = failedAuthor ? undefined : await collect(problems, () => generateProgram(root, author));
+        const components = failedAuthor ? undefined : await collect(problems, () => generateProgram(root, author, config));
         return { diagnostics: problems, pages: content?.pages.length ?? 0, components: components ?? [] };
     }
     finally {

package/dist/cli.js

@@ -2,7 +2,7 @@
 //
 //   vlx init [name] [--web ...]     make a new application (asks what the flags do not say)
 //   vlx dev [--port N] [--host H]   serve the project and rebuild it as it changes
-//   vlx build                       write the site to dist/
+//   vlx build                       write the site to dist/web/
 //   vlx check [--json]              find mistakes in authored files without building
 //   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
@@ -13,35 +13,41 @@ import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { INIT_HELP, parseInit } from "./args.js";
 import { build } from "./build.js";
-import { generateComponent, generatePage, GenerateError, KINDS } from "./add.js";
+import { packageDesktop } from "./package.js";
+import { generateComponent, generatePage, generateTarget, GenerateError, KINDS } from "./add.js";
 import { check } from "./check.js";
 import { findRoot } from "./config.js";
 import { localCli } from "./delegate.js";
 import { dev } from "./dev.js";
 import { AppError, format } from "./diagnostics.js";
 import { detectPackageManager, directoryFor, directoryProblem, execute, nameProblem, runCommand, titleOf } from "./init.js";
-import { TARGETS } from "./targets.js";
+import { DEFAULT_TARGETS, TARGETS } from "./targets.js";
 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
-  build                            write the site to dist/
+  build                            write the site to dist/web/
   check [--json]                   find mistakes in your files without building
   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)
   sync                             refresh the generated files (this runs by itself; see vlx help sync)
   help [command]                   say more about one command
 
 Run it in a project (a directory with a valance.json), or any directory inside one.
 In a terminal the commands draw an interface; --plain (or a pipe, or CI) prints plain text.
 `;
-const GENERATE_HELP = `vlx generate <page|component> <name>   (alias: vlx g)
+const GENERATE_HELP = `vlx generate <page|component|target> <name>   (alias: vlx g)
 
   vlx generate page guide/getting-started   content/guide/getting-started.md, with its front matter
                                             (--title "Getting started" to say the title)
   vlx generate component post-card          src/post-card.mprx and src/post-card.ts, imported in
                                             src/main.ts and listed in its \`components\`. Write
                                             <post-card></post-card> in a template to use it.
+  vlx generate target desktop               valance.desktop.json and a layout of its own in src/desktop/,
+                                            registered in \`targets\` of src/main.ts; the content, the state and
+                                            the commands are shared. Nothing the project has is moved.
 
 Nothing is overwritten: a name that is taken is refused.
 `;
@@ -49,9 +55,10 @@ const COMMAND_HELP = {
     init: INIT_HELP,
     generate: GENERATE_HELP,
     g: GENERATE_HELP,
-    dev: "vlx dev [--port N] [--host H]\n\nServe the project and rebuild it as files change. A mistake leaves the last good build serving and shows in the terminal and in the page.\n",
-    build: "vlx build\n\nWrite the site to dist/. Any host that serves files can serve it.\n",
+    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",
+    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",
     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. */
@@ -66,6 +73,8 @@ const sync = async (from) => {
         return `skipped (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`;
     }
 };
+/** The targets named by flags (`--web`, `--desktop`), in the order given. */
+const targetFlags = (args) => TARGETS.map((each) => each.id).filter((id) => args.includes(`--${id}`));
 const option = (args, name) => {
     const at = args.indexOf(name);
     return at < 0 ? undefined : args[at + 1];
@@ -90,13 +99,13 @@ const runInit = async (args, cwd) => {
         return 2;
     }
     if (args.targets.length === 0 && !args.yes) {
-        console.error(`vlx init: choose a target (${TARGETS.map((each) => `--${each.id}`).join(", ")}), or --yes for all of them`);
+        console.error(`vlx init: choose a target (${TARGETS.map((each) => `--${each.id}`).join(", ")}), or --yes for the web`);
         return 2;
     }
     const answers = {
         name: args.name,
         dir: directoryFor(args.name, cwd),
-        targets: args.targets.length === 0 ? TARGETS.map((each) => each.id) : args.targets,
+        targets: args.targets.length === 0 ? DEFAULT_TARGETS : args.targets,
         web: { base: args.base ?? "", url: args.url ?? "" },
         packageManager: args.packageManager ?? detectPackageManager(),
         install: args.install ?? true,
@@ -128,7 +137,7 @@ 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 === "check" || command === "sync" || command === "generate" || command === "g") {
+    if (command === "dev" || command === "build" || command === "package" || command === "check" || command === "sync" || command === "generate" || command === "g") {
         const local = localCli(cwd);
         if (local !== undefined) {
             const theirs = (await import(pathToFileURL(local).href));
@@ -153,17 +162,32 @@ export const main = async (args, cwd = process.cwd()) => {
             case "dev": {
                 const port = option(rest, "--port");
                 const host = option(rest, "--host");
+                const picked = targetFlags(rest);
+                if (picked.length > 1) {
+                    console.error("vlx dev: name one target, or none for all of them: vlx dev --web or vlx dev --desktop");
+                    return 2;
+                }
+                const target = picked[0];
                 if (draws) {
                     const { drawDev } = await import("./ui/run.js");
-                    await drawDev(findRoot(cwd), { ...(port === undefined ? {} : { port: Number(port) }), ...(host === undefined ? {} : { host }) });
+                    await drawDev(findRoot(cwd), {
+                        ...(target === undefined ? {} : { target }),
+                        ...(port === undefined ? {} : { port: Number(port) }),
+                        ...(host === undefined ? {} : { host }),
+                    });
                     return 0;
                 }
-                const running = await dev(findRoot(cwd), { ...(port === undefined ? {} : { port: Number(port) }), ...(host === undefined ? {} : { host }) });
+                const running = await dev(findRoot(cwd), {
+                    ...(target === undefined ? {} : { target }),
+                    ...(port === undefined ? {} : { port: Number(port) }),
+                    ...(host === undefined ? {} : { host }),
+                });
                 console.log(`vlx dev: ${running.url}`);
-                // Until interrupted.
+                // Until interrupted (or, for a desktop project, until the window is closed).
                 await new Promise((resolve) => {
                     process.once("SIGINT", resolve);
                     process.once("SIGTERM", resolve);
+                    void running.closed?.then(resolve);
                 });
                 await running.close();
                 return 0;
@@ -171,14 +195,33 @@ export const main = async (args, cwd = process.cwd()) => {
             case "build": {
                 if (draws) {
                     const { drawBuild } = await import("./ui/run.js");
-                    await drawBuild(findRoot(cwd));
+                    await drawBuild(findRoot(cwd), targetFlags(rest));
                     return 0;
                 }
                 const started = Date.now();
-                const built = await build(findRoot(cwd));
+                const flagged = targetFlags(rest);
+                const built = await build(findRoot(cwd), flagged.length === 0 ? {} : { targets: flagged });
                 console.log(`vlx build: ${built.pages.length} pages, ${built.files.length} files → ${built.dir} (${((Date.now() - started) / 1000).toFixed(1)}s)`);
                 return 0;
             }
+            case "package": {
+                if (!rest.includes("--desktop")) {
+                    console.error("vlx package: say what: vlx package --desktop [--platform linux-x64|win32-x64] [--window <path>] [--node <path>] [--archive]");
+                    return 2;
+                }
+                const platform = option(rest, "--platform");
+                const window = option(rest, "--window");
+                const node = option(rest, "--node");
+                const packaged = await packageDesktop(findRoot(cwd), {
+                    ...(platform === undefined ? {} : { platform }),
+                    ...(window === undefined ? {} : { window }),
+                    ...(node === undefined ? {} : { node }),
+                    ...(rest.includes("--archive") ? { archive: true } : {}),
+                });
+                console.log(`vlx package: ${packaged.files.join(", ")} → ${packaged.dir}`);
+                packaged.notes.forEach((note) => console.log(`vlx package: ${note}`));
+                return 0;
+            }
             case "check": {
                 if (draws && !rest.includes("--json")) {
                     const { drawCheck } = await import("./ui/run.js");
@@ -219,7 +262,7 @@ export const main = async (args, cwd = process.cwd()) => {
                 }
                 const root = findRoot(cwd);
                 try {
-                    const made = kind === "page" ? generatePage(root, positional[1], title) : generateComponent(root, positional[1]);
+                    const made = kind === "page" ? generatePage(root, positional[1], title) : kind === "target" ? generateTarget(root, positional[1]) : generateComponent(root, positional[1]);
                     made.created.forEach((file) => console.log(`vlx generate: created ${file}`));
                     made.changed.forEach((file) => console.log(`vlx generate: changed ${file}`));
                     console.log(`vlx generate: ${await sync(root)}`);

package/dist/compile.d.ts

@@ -1,10 +1,13 @@
 import type * as Valance from "@valancex/valance";
 import type { DefinedApp } from "@valancex/common";
 import type { Node } from "./tree.js";
+import type { Vocabulary } from "@valancex/common/internal";
 export declare const SOURCE_DIR = "src";
 /** The component the page is drawn by. */
 export declare const ROOT = "layout";
 export declare const BUILT_IN: string;
+/** The desktop target's built-in views: the same components as the web's, written in the desktop vocabulary. */
+export declare const BUILT_IN_DESKTOP: string;
 /** The package directory: where its README, which documents the framework's own names, is. */
 export declare const PACKAGE_DIR: string;
 interface Template {
@@ -23,8 +26,14 @@ export interface Templates {
  * 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 declare const templatesOf: (root: string, author: DefinedApp | undefined) => Templates;
-export declare const manifestOf: (author: DefinedApp | undefined) => import("@valancex/valance/web/build").Manifest;
+export declare const templatesOf: (root: string, author: DefinedApp | undefined, vocabulary?: Vocabulary, views?: string) => Templates;
+export declare const manifestOf: (author: DefinedApp | undefined, vocabulary?: Vocabulary) => {
+    components: {
+        [x: string]: unknown;
+    };
+    version: 1;
+    types: Readonly<Record<string, never>>;
+};
 export interface Compiled {
     readonly program: Valance.Program;
     /**
@@ -46,6 +55,6 @@ export interface Compiled {
         readonly builtIn: boolean;
     }>;
 }
-/** Compiles the application's templates. Fails with every diagnostic, each pointing into the file it is about. */
-export declare const compileViews: (root: string, author: DefinedApp | undefined) => Promise<Compiled>;
+/** 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 declare const compileViews: (root: string, author: DefinedApp | undefined, vocabulary?: Vocabulary, views?: string) => Promise<Compiled>;
 export {};

package/dist/compile.js

@@ -12,12 +12,14 @@ import { declarationsOf, linked, nameOf, treeOf } from "./tree.js";
 import { tagsOf } from "./outline.js";
 import { entryOf } from "./contract.js";
 import { locateKey } from "./wiring.js";
-import { primitives } from "@valancex/common/internal";
+import { namesOf, webVocabulary, WHOLE } from "@valancex/common/internal";
 import { ENTRY_FILE } 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 +39,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) => {
+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 ?? [];
@@ -77,7 +79,7 @@ export const templatesOf = (root, author) => {
             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 primitives) {
+        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 +94,17 @@ export const templatesOf = (root, author) => {
         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 treeOf(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 +133,29 @@ const reachable = (all) => {
     }
     return all.filter((template) => seen.has(template.component));
 };
-export const manifestOf = (author) => manifest({
-    primitives,
-    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 } };
+    }
+    // The props the vocabulary says a template may leave out.
+    const components = { ...derived.components };
+    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
@@ -136,12 +163,12 @@ const isManifestError = (error) => error instanceof Error && error._tag === "Man
  * uses. MESH checks every use against it (an undeclared prop, a missing one, a wrong type, an undeclared event in a handler), at the use or in the template. A schema with no model type is a
  * diagnostic at the declaration, not a crash.
  */
-const modelOf = (root, author, tree) => {
+const modelOf = (root, author, tree, vocabulary) => {
     const problems = [];
     const mainText = entryText(root);
     let derived;
     try {
-        derived = manifestOf(author);
+        derived = manifestOf(author, vocabulary);
     }
     catch (error) {
         if (!isManifestError(error)) {
@@ -171,11 +198,11 @@ const modelOf = (root, author, tree) => {
     }
     return { ...derived, components: { ...derived.components, ...entries } };
 };
-/** Compiles the application's templates. Fails with every diagnostic, each pointing into the file it is about. */
-export const compileViews = async (root, author) => {
-    const { all, tree } = templatesOf(root, author);
+/** 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);
     const used = reachable(all);
-    const model = modelOf(root, author, tree);
+    const model = modelOf(root, author, tree, vocabulary);
     if (!used.some((template) => template.component === ROOT)) {
         throw new AppError([diagnostic(`${SOURCE_DIR}/${ROOT}.mprx`, 0, "layout-missing", "there is no layout")]);
     }
@@ -205,7 +232,7 @@ export const compileViews = async (root, author) => {
         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,13 +1,27 @@
 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: {
         readonly base: string;
         readonly url: string;
+        /** Write the security headers file beside the built site. */
+        readonly headers: boolean;
+        /** Announce a page change made in place to assistive technology. */
+        readonly announce: boolean;
+    };
+    /** The application's backend: the address its requests are made to (a path on the site's own origin, or an absolute https address), and, for `vlx dev`, where a path is proxied to. */
+    readonly api: {
+        readonly base: string;
+        readonly proxy: string;
     };
 }
 /** Reads and validates the project's configuration. Every problem in both files is reported together. */