@valancex/cli 0.12.0 → 0.14.0

package/dist/dev.js

@@ -1,8 +1,24 @@
+// `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";
+import { devDesktop } from "./dev-desktop.js";
 import { generateContent, generateEntries, generateProgram } from "./emit.js";
 import { GENERATED_DIR, OUTPUT_DIR } from "./project.js";
 import { baseConfig, SERVER_ENTRY } from "./vite.js";
@@ -50,7 +66,10 @@ const start = async (root, config, options, restart) => {
         });
     const failed = new Map();
     let pending = Promise.resolve();
-    generateEntries(root);
+    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,
@@ -66,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);
+                                }
+                            })();
+                        });
+                    };
                 },
             },
         ],
@@ -114,13 +149,13 @@ const start = async (root, config, options, restart) => {
         };
         const wasFailing = failed.size > 0;
         if (stages.includes("entries")) {
-            generateEntries(root);
+            generateEntries(root, config, { record: options.record !== undefined });
         }
         if (stages.includes("content")) {
             await run("content", () => generateContent(root, config));
         }
         if (stages.includes("program")) {
-            await run("templates", async () => generateProgram(root, await loadAuthor(server, root)));
+            await run("templates", async () => generateProgram(root, await loadAuthor(server, root), config, ["web"]));
         }
         const open = [...failed.values()].flat();
         options.onStatus?.(open);
@@ -176,7 +211,7 @@ const start = async (root, config, options, restart) => {
     // First build: a mistake here is reported like any other and the server still starts, so the overlay can show it.
     for (const [name, work] of [
         ["content", () => generateContent(root, config)],
-        ["templates", async () => generateProgram(root, await loadAuthor(server, root))],
+        ["templates", async () => generateProgram(root, await loadAuthor(server, root), config, ["web"])],
     ]) {
         try {
             await work();
@@ -206,6 +241,33 @@ const start = async (root, config, options, restart) => {
 };
 /** Starts the development server for the project at `root`. */
 export const dev = async (root, options = {}) => {
+    const config = loadConfig(root);
+    const target = options.target ?? (config.targets.length === 1 ? config.targets[0] : undefined);
+    if (target !== undefined && !config.targets.includes(target)) {
+        throw new AppError([
+            { file: "valance.json", line: 0, column: 0, code: "dev-target", message: `this project is not built for ${target} (its targets: ${config.targets.join(", ")})` },
+        ]);
+    }
+    // A project of more than one target, and none named: serve the web and open the desktop's window, each as it would be alone.
+    if (target === undefined) {
+        const web = await dev(root, { ...options, target: "web" });
+        const desktop = await devDesktop(root, options);
+        return {
+            url: web.url,
+            closed: desktop.closed,
+            settled: async () => {
+                await web.settled();
+                await desktop.settled();
+            },
+            close: async () => {
+                await desktop.close();
+                await web.close();
+            },
+        };
+    }
+    if (target === "desktop") {
+        return devDesktop(root, options);
+    }
     let current;
     const log = options.log ??
         ((line) => {
@@ -244,7 +306,7 @@ export const dev = async (root, options = {}) => {
         }, 500);
         timer.unref();
     };
-    const config = loadConfig(root);
+    // (the configuration is read above)
     current = await start(root, config, options, restart);
     return {
         get url() {

package/dist/emit.d.ts

@@ -1,13 +1,18 @@
 import type { Config } from "./config.js";
+import type { TargetId } from "./targets.js";
 import type { DefinedApp } from "@valancex/common";
 import type { Content } from "@valancex/common/internal";
 export declare const hasEntry: (root: string) => boolean;
 export declare const writeContent: (root: string, content: Content) => boolean;
 /** The content stage alone: it does not need the author's code. */
 export declare const generateContent: (root: string, config: Config) => Content;
-/** The templates stage: needs the author's definition (the manifest derives from its state and commands). */
-export declare const generateProgram: (root: string, author: DefinedApp | undefined) => Promise<ReadonlyArray<string>>;
+/** The file a target's compiled program is in: `program.json` for a project of one target (as it always was), `program.<target>.json` for one of several. */
+export declare const programFile: (config: Config | undefined, id: TargetId) => string;
+/** The templates stage: needs the author's definition (the manifest derives from its state and commands). One program per target; the state, the commands and the content are shared. */
+export declare const generateProgram: (root: string, author: DefinedApp | undefined, config?: Config, only?: ReadonlyArray<TargetId>) => Promise<ReadonlyArray<string>>;
 /** 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. */
-export declare const generateEntries: (root: string) => boolean;
+/** 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, options?: {
+    readonly record?: boolean;
+}) => boolean;

package/dist/emit.js

@@ -17,30 +17,82 @@ import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { compileViews, PACKAGE_DIR, SOURCE_DIR } from "./compile.js";
 import { readContent } from "./content.js";
+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 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. */
+@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;
+  }
+
+  /* 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" })
-        .filter((file) => file.endsWith(".css"))
+        .map((file) => file.split(sep).join("/"))
+        .filter((file) => file.endsWith(".css") && !file.startsWith("desktop/"))
         .sort()
         .map((file) => `${SOURCE_DIR}/${file}`)
     : [];
 export const hasEntry = (root) => existsSync(join(root, ENTRY_FILE));
-const clientSource = (root) => `// 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 "./program.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 serverSource = (root) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
+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";
+import program from "./${programFile(config, "desktop")}";
+${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}
+// the MESH runtime's module sits beside the built engine (vlx build copies it there)
+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, theme: theme ?? undefined });
+// the window is closed: nothing the application left open keeps the engine alive
+process.exit(0);
+`;
+const serverSource = (root, config) => `// Generated by \`valance\`. Do not edit: it is rewritten whenever the project changes.
 // @ts-nocheck
 import { createRenderer, pathsOf } from "@valancex/common/server";
 import content from "./content.json";
-import program from "./program.json";
+import program from "./${programFile(config, "web")}";
 ${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}
 export const render = createRenderer({ content, program, author });
 export const paths = () => pathsOf(content);
@@ -54,20 +106,52 @@ export const generateContent = (root, config) => {
     writeContent(root, content);
     return content;
 };
-/** The templates stage: needs the author's definition (the manifest derives from its state and commands). */
-export const generateProgram = async (root, author) => {
+/** The file a target's compiled program is in: `program.json` for a project of one target (as it always was), `program.<target>.json` for one of several. */
+export const programFile = (config, id) => ((config?.targets.length ?? 1) > 1 ? `program.${id}.json` : "program.json");
+const manifestFile = (config, id) => ((config?.targets.length ?? 1) > 1 ? `manifest.${id}.json` : "manifest.json");
+const wiringFile = (config, id) => ((config?.targets.length ?? 1) > 1 ? `wiring.${id}.json` : "wiring.json");
+/** The templates stage: needs the author's definition (the manifest derives from its state and commands). One program per target; the state, the commands and the content are shared. */
+export const generateProgram = async (root, author, config, only) => {
     ensureGeneratedDir(root);
-    const compiled = await compileViews(root, author);
-    writeIfChanged(generated(root, "program.json"), `${JSON.stringify(compiled.program)}\n`);
-    writeIfChanged(generated(root, "manifest.json"), `${JSON.stringify(compiled.manifest, null, 2)}\n`);
-    // The one file an editor reads to know the project: where the manifest is, and which file is the template of which component. The conventions stay here, not copied into every editor.
-    writeIfChanged(generated(root, "editor.json"), `${JSON.stringify({ version: 1, model: `${GENERATED_DIR}/manifest.json`, components: compiled.files, wiring: `${GENERATED_DIR}/wiring.json` }, null, 2)}\n`);
-    writeTemplateTypes(root, compiled);
-    // Where every name came from and what uses it, at both ends, for the editor. The framework's own names point into the README that ships with the package.
+    const targets = (config?.targets ?? ["web"]).filter((id) => only === undefined || only.includes(id));
+    const compiledAll = [];
+    const problems = [];
+    for (const id of targets) {
+        const target = targetOf(id);
+        try {
+            compiledAll.push({ id, compiled: await compileViews(root, forTarget(author, id), target.vocabulary, target.views) });
+        }
+        catch (error) {
+            if (!(error instanceof AppError)) {
+                throw error;
+            }
+            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);
+    }
     const readme = join(PACKAGE_DIR, "README.md");
     const docs = existsSync(readme) ? { file: relative(root, readme).split(sep).join("/"), lines: readFileSync(readme, "utf8").split("\n") } : undefined;
-    writeIfChanged(generated(root, "wiring.json"), `${JSON.stringify(buildWiring(root, author, compiled, docs), null, 2)}\n`);
-    return compiled.components;
+    const editor = [];
+    for (const { id, compiled } of compiledAll) {
+        writeIfChanged(generated(root, programFile(config, id)), `${JSON.stringify(compiled.program)}\n`);
+        writeIfChanged(generated(root, manifestFile(config, id)), `${JSON.stringify(compiled.manifest, null, 2)}\n`);
+        // Where every name came from and what uses it, at both ends, for the editor. The framework's own names point into the README that ships with the package.
+        writeIfChanged(generated(root, wiringFile(config, id)), `${JSON.stringify(buildWiring(root, forTarget(author, id), compiled, docs), null, 2)}\n`);
+        editor.push({ id, model: `${GENERATED_DIR}/${manifestFile(config, id)}`, wiring: `${GENERATED_DIR}/${wiringFile(config, id)}`, components: compiled.files });
+    }
+    // The one file an editor reads to know the project: where the manifest is, and which file is the template of which component. The conventions stay here, not copied into every editor. For a project
+    // of several targets the first one is what the editor reads (`model`, `wiring`), and `targets` lists each.
+    const first = editor[0];
+    // Only a pass over every target writes it (a pass over one, as `vlx dev --web` is, would leave the others out of it).
+    if (first !== undefined && editor.length === (config?.targets ?? ["web"]).length) {
+        writeIfChanged(generated(root, "editor.json"), `${JSON.stringify({ version: 1, model: first.model, components: first.components, wiring: first.wiring, ...(editor.length > 1 ? { targets: Object.fromEntries(editor.map((each) => [each.id, { model: each.model, wiring: each.wiring, components: each.components }])) } : {}) }, null, 2)}\n`);
+    }
+    writeTemplateTypes(root, compiledAll.map((each) => each.compiled));
+    return [...new Set(compiledAll.flatMap((each) => each.compiled.components))];
 };
 const union = (names) => (names.length === 0 ? "never" : names.map((name) => JSON.stringify(name)).join(" | "));
 /** The declaration of one template's type: its props and events as the names TypeScript checks a contract's keys against. */
@@ -81,15 +165,16 @@ export default template;
  */
 const typePath = (file) => `types/${file.replace(new RegExp(`^${SOURCE_DIR}/`), "").replace(/\.mprx$/, ".d.mprx.ts")}`;
 /** Writes the type of each of the author's templates, and removes the type of one that is gone. */
-const writeTemplateTypes = (root, compiled) => {
-    const components = compiled.manifest
-        .components;
+const writeTemplateTypes = (root, all) => {
     const written = new Set();
-    for (const template of compiled.templates.filter((each) => !each.builtIn)) {
-        const entry = components[template.component];
-        const path = typePath(template.file);
-        written.add(path);
-        writeIfChanged(generated(root, path), templateType(Object.keys(entry?.props ?? {}), Object.keys(entry?.events ?? {})));
+    for (const compiled of all) {
+        const components = compiled.manifest.components;
+        for (const template of compiled.templates.filter((each) => !each.builtIn)) {
+            const entry = components[template.component];
+            const path = typePath(template.file);
+            written.add(path);
+            writeIfChanged(generated(root, path), templateType(Object.keys(entry?.props ?? {}), Object.keys(entry?.events ?? {})));
+        }
     }
     const dir = generated(root, "types");
     if (existsSync(dir)) {
@@ -100,8 +185,24 @@ const writeTemplateTypes = (root, compiled) => {
         }
     }
 };
-/** The entries; rewritten when `src/main.ts` or a stylesheet is added or removed. */
-export const generateEntries = (root) => {
+/** 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, options) => {
     ensureGeneratedDir(root);
-    return [writeIfChanged(generated(root, "client.ts"), clientSource(root)), writeIfChanged(generated(root, "server.ts"), serverSource(root))].some(Boolean);
+    const targets = config?.targets ?? ["web"];
+    return [
+        ...(targets.includes("web")
+            ? [
+                writeIfChanged(generated(root, "core.css"), CORE_CSS),
+                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, "theme.desktop.json"), `${JSON.stringify(themeOf(root).desktop ?? null)}\n`),
+                writeIfChanged(generated(root, "desktop.ts"), desktopSource(root, config)),
+            ]
+            : []),
+    ].some(Boolean);
 };

package/dist/init.js

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { PROJECT_FILE, WEB_FILE } from "./config.js";
+import { DESKTOP_FILE, PROJECT_FILE, WEB_FILE } from "./config.js";
 export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
 const PACKAGE = new URL("../", import.meta.url);
 const TEMPLATES = new URL("../templates/", import.meta.url);
@@ -84,6 +84,7 @@ export const plan = (answers) => {
     const out = new Map();
     const title = titleOf(answers.name);
     const web = answers.targets.includes("web");
+    const desktop = answers.targets.includes("desktop");
     const hasBase = answers.web.base !== "" && answers.web.base !== "/";
     const settings = [hasBase ? `base ${answers.web.base}` : "", answers.web.url !== "" ? `url ${answers.web.url}` : ""].filter((each) => each !== "");
     const tokens = {
@@ -92,14 +93,20 @@ export const plan = (answers) => {
         web_note: web && settings.length > 0 ? `, and \`${WEB_FILE}\` says where the web site is served (${settings.join(", ")})` : "",
     };
     const fill = (text) => text.replace(/\{\{(\w+)\}\}/g, (match, key) => tokens[key] ?? match);
-    if (web) {
-        const root = new URL("web/", TEMPLATES);
+    // A project for more than one target keeps what they share (the content, the state and the commands) and gives each its own templates (`src/web/`, `src/desktop/`): the "multi" template, on
+    // top of the web's files that are not templates.
+    const layers = web && desktop ? ["web", "multi"] : web ? ["web"] : desktop ? ["desktop"] : [];
+    for (const target of layers) {
+        const root = new URL(`${target}/`, TEMPLATES);
         for (const file of files(root)) {
+            if (target === "web" && layers.includes("multi") && (file.startsWith("src/") || file.startsWith("content/") || file === "README.md")) {
+                continue;
+            }
             out.set(written(file), fill(readFileSync(new URL(file, root), "utf8")));
         }
     }
     out.set(PROJECT_FILE, json({ $schema: "./node_modules/@valancex/cli/schemas/valance.schema.json", version: 1, name: title }));
-    if (web && (hasBase || answers.web.url !== "")) {
+    if (web && (hasBase || answers.web.url !== "" || desktop)) {
         out.set(WEB_FILE, json({
             $schema: "./node_modules/@valancex/cli/schemas/valance.web.schema.json",
             version: 1,
@@ -107,6 +114,9 @@ export const plan = (answers) => {
             ...(answers.web.url !== "" ? { url: answers.web.url } : {}),
         }));
     }
+    if (desktop) {
+        out.set(DESKTOP_FILE, json({ $schema: "./node_modules/@valancex/cli/schemas/valance.desktop.schema.json", version: 1 }));
+    }
     out.set("package.json", json({
         name: packageName(basename(answers.dir)),
         version: "0.0.0",

package/dist/package.d.ts

@@ -0,0 +1,18 @@
+export declare const PLATFORMS: readonly ["linux-x64", "win32-x64"];
+export type Platform = (typeof PLATFORMS)[number];
+export interface PackageOptions {
+    /** The platform the package is for; by default the one this runs on. */
+    readonly platform?: string;
+    /** The Desktop PORT's window program for that platform (`vlx-window`); by default `VLX_WINDOW`, else `vlx-window` on the PATH. */
+    readonly window?: string;
+    /** A `node` binary of the same version for that platform; by default the one running this, which is only right for the platform this runs on. */
+    readonly node?: string;
+    /** Also write the package as one file: a `.tar.gz` for Linux, a `.zip` for Windows, with its SHA-256 beside it. */
+    readonly archive?: boolean;
+}
+export interface Packaged {
+    readonly dir: string;
+    readonly files: ReadonlyArray<string>;
+    readonly notes: ReadonlyArray<string>;
+}
+export declare const packageDesktop: (root: string, options?: PackageOptions) => Promise<Packaged>;

package/dist/package.js

@@ -0,0 +1,142 @@
+// `vlx package`: the desktop target as something to hand to a person. The engine becomes one executable (Node's single executable application: the engine bundled to one file, with the MESH
+// runtime's module inside as an asset, injected into a `node` binary), set beside the Desktop PORT's window program. Unsigned: signing and notarizing are not done here (the artifacts say so).
+import { build as bundle } from "vite";
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, join } from "node:path";
+import { checksums, tarGz, zip } from "./archive.js";
+import { loadAuthor } from "./author.js";
+import { build } from "./build.js";
+import { loadConfig } from "./config.js";
+import { AppError } from "./diagnostics.js";
+import { hasEntry } from "./emit.js";
+import { ENTRY_FILE, GENERATED_DIR, OUTPUT_DIR } from "./project.js";
+import { programFile } from "./emit.js";
+import { createLoader, templates } from "./vite.js";
+export const PLATFORMS = ["linux-x64", "win32-x64"];
+const hostPlatform = () => `${process.platform}-${process.arch}`;
+const fail = (message) => {
+    throw new AppError([{ file: "valance.desktop.json", line: 0, column: 0, code: "package", message }]);
+};
+/** A program on the PATH, as the shell would find it. */
+const onPath = (name) => (process.env["PATH"] ?? "")
+    .split(delimiter)
+    .map((dir) => join(dir, name))
+    .find((candidate) => existsSync(candidate));
+/** The entry of the packaged engine: the generated desktop entry, with the MESH runtime's module read from the executable's own assets (a single file has nothing beside it). */
+const seaSource = (root, config) => `// Generated by \`vlx package\`. Do not edit.
+// @ts-nocheck
+import { getRawAsset } from "node:sea";
+import { dirname, join } from "node:path";
+import { start } from "@valancex/common/desktop";
+import content from "./content.json";
+import program from "./${programFile(config, "desktop")}";
+${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}
+const wasm = new Uint8Array(getRawAsset("mesh-runtime.wasm"));
+
+// the project's public/ files sit beside the executable
+const assets = join(dirname(process.execPath), "public");
+
+start({ content, program, author, wasm, assets }).then(
+  () => process.exit(0),
+  (error) => {
+    console.error("the engine stopped:", error);
+    process.exit(1);
+  },
+);
+`;
+/** Every file under `dir` as an archive entry inside `top/`, in a stable order (a program keeps its executable bit). */
+const entriesOf = (dir, top, at = "") => readdirSync(join(dir, at))
+    .sort()
+    .flatMap((name) => {
+    const relative = at === "" ? name : `${at}/${name}`;
+    const file = join(dir, relative);
+    return statSync(file).isDirectory()
+        ? entriesOf(dir, top, relative)
+        : [{ path: `${top}/${relative}`, data: readFileSync(file), mode: statSync(file).mode & 0o111 ? 0o755 : 0o644 }];
+});
+export const packageDesktop = async (root, options = {}) => {
+    const config = loadConfig(root);
+    if (!config.targets.includes("desktop")) {
+        return fail("this project has no desktop target (vlx generate target desktop)");
+    }
+    const platform = options.platform ?? hostPlatform();
+    if (!PLATFORMS.includes(platform)) {
+        return fail(`cannot package for ${platform}: the platforms are ${PLATFORMS.join(", ")}`);
+    }
+    const windows = platform.startsWith("win32");
+    const node = options.node ?? (platform === hostPlatform() ? process.execPath : undefined);
+    const window = options.window ?? process.env["VLX_WINDOW"] ?? onPath(windows ? "vlx-window.exe" : "vlx-window");
+    if (node === undefined) {
+        return fail(`packaging for ${platform} from ${hostPlatform()} needs a node binary of this version for ${platform}: --node <path>`);
+    }
+    if (window === undefined || !existsSync(window)) {
+        return fail(`no window program: build it from the PORT repository (cargo build --release --bin vlx-window) and give its path with --window <path> (or set VLX_WINDOW)`);
+    }
+    // The engine, built first: the content, the program and the entries are the project's as they are now.
+    await build(root, { targets: ["desktop"] });
+    const work = join(root, GENERATED_DIR, "package");
+    rmSync(work, { recursive: true, force: true });
+    mkdirSync(work, { recursive: true });
+    writeFileSync(join(root, GENERATED_DIR, "desktop.sea.ts"), seaSource(root, config));
+    // Loading the author's definition once checks it still loads; the bundle below is the one that ships.
+    const loader = await createLoader(root, config);
+    try {
+        await loadAuthor(loader, root);
+    }
+    finally {
+        await loader.close();
+    }
+    await bundle({
+        root,
+        configFile: false,
+        publicDir: false,
+        logLevel: "warn",
+        plugins: [templates(root)],
+        cacheDir: join(root, GENERATED_DIR, "cache"),
+        ssr: { noExternal: true, target: "node" },
+        esbuild: { keepNames: true },
+        build: {
+            ssr: join(root, GENERATED_DIR, "desktop.sea.ts"),
+            outDir: work,
+            emptyOutDir: false,
+            target: "node22",
+            // W10: the engine is minified (half the bytes; start-up measured no worse, 2026-10-24). Names are kept: errors and their `_tag` are read by name.
+            minify: "esbuild",
+            rollupOptions: { output: { format: "cjs", entryFileNames: "engine.cjs" } },
+        },
+    });
+    const wasm = createRequire(createRequire(join(root, "package.json")).resolve("@valancex/common/package.json")).resolve("@valancex/mesh-runtime/mesh-runtime.wasm");
+    writeFileSync(join(work, "sea-config.json"), JSON.stringify({ main: join(work, "engine.cjs"), output: join(work, "engine.blob"), disableExperimentalSEAWarning: true, assets: { "mesh-runtime.wasm": wasm } }));
+    execFileSync(process.execPath, ["--experimental-sea-config", join(work, "sea-config.json")], { stdio: "pipe" });
+    const out = join(root, OUTPUT_DIR, "package", platform);
+    rmSync(out, { recursive: true, force: true });
+    mkdirSync(out, { recursive: true });
+    const engine = join(out, windows ? "vlx-engine.exe" : "vlx-engine");
+    const app = join(out, `${config.name.replace(/[^\w.-]+/g, "-")}${windows ? ".exe" : ""}`);
+    copyFileSync(node, engine);
+    chmodSync(engine, 0o755);
+    const injector = "postject"; // (no type declarations of its own)
+    const { inject } = (await import(injector));
+    await inject(engine, "NODE_SEA_BLOB", readFileSync(join(work, "engine.blob")), { sentinelFuse: "NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2" });
+    copyFileSync(window, app);
+    chmodSync(app, 0o755);
+    // The files images are drawn from, beside the engine.
+    const publicDir = join(root, "public");
+    if (existsSync(publicDir)) {
+        cpSync(publicDir, join(out, "public"), { recursive: true });
+    }
+    const files = [engine, app].map((file) => file.slice(out.length + 1));
+    const notes = ["unsigned: macOS notarization and Windows signing are not done here; an unsigned program draws a warning on first run"];
+    if (options.archive === true) {
+        const stem = `${config.name.replace(/[^\w.-]+/g, "-")}-${platform}`;
+        const archive = `${stem}.${windows ? "zip" : "tar.gz"}`;
+        const data = (windows ? zip : tarGz)(entriesOf(out, stem));
+        writeFileSync(join(root, OUTPUT_DIR, "package", archive), data);
+        writeFileSync(join(root, OUTPUT_DIR, "package", `${archive}.sha256`), checksums([{ name: archive, data }]));
+        files.push(`../${archive}`, `../${archive}.sha256`);
+        notes.push(`${archive} is the package as one file, with its SHA-256 beside it; the checksum says the file is the one that was made, not who made it (that is what signing is for)`);
+    }
+    return { dir: out, files, notes };
+};

package/dist/project.js

@@ -1,4 +1,4 @@
-// Where things are in a project. Authored: `valance.json`, `valance.web.json`, `content/`, `public/`, `src/`. Generated and never edited or committed: `.valance/`. The final site: `dist/`.
+// Where things are in a project. Authored: `valance.json`, `valance.web.json`, `content/`, `public/`, `src/`. Generated and never edited or committed: `.valance/`. The final site: `dist/web/`.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 export const GENERATED_DIR = ".valance";

package/dist/recording-guard.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from "./config.js";
+/** The lines `vlx dev --record` prints before it records: where, what the log holds, what is redacted, and whether git would commit it. */
+export declare const recordingNotice: (root: string, file: string, config: Config) => ReadonlyArray<string>;
+/** What `vlx replay` says when it is given a log that holds user data without being told it may read it. */
+export declare const userDataRefusal: (file: string) => string;