@valancex/cli 0.12.0 → 0.13.0

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

@@ -6,6 +6,8 @@ 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 {
@@ -24,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, vocabulary?: Vocabulary) => Templates;
-export declare const manifestOf: (author: DefinedApp | undefined, vocabulary?: Vocabulary) => 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;
     /**
@@ -48,5 +56,5 @@ export interface 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) => Promise<Compiled>;
+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 { webVocabulary } 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, 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 ?? [];
@@ -77,7 +79,7 @@ export const templatesOf = (root, author, vocabulary = webVocabulary) => {
             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 +94,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 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, 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 } };
+    }
+    // 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
@@ -172,8 +199,8 @@ const modelOf = (root, author, tree, vocabulary) => {
     return { ...derived, components: { ...derived.components, ...entries } };
 };
 /** 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)) {
@@ -205,7 +232,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,13 @@
 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: {

package/dist/config.js

@@ -7,6 +7,7 @@ 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) => {
@@ -97,7 +98,9 @@ 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 = [
+        ...(desktop === undefined ? [] : check(DESKTOP_FILE, desktop.text, desktop.value, { $schema: schema, version }, [])),
         ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title }, ["name"]),
         ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url, headers: flag, announce: flag, api }, [])),
     ];
@@ -108,6 +111,7 @@ 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 ?? "" },

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,5 +1,8 @@
 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;
     /** Called with each report (a rebuild, a mistake); defaults to the console. */

package/dist/dev.js

@@ -3,6 +3,7 @@ import { 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 +51,7 @@ const start = async (root, config, options, restart) => {
         });
     const failed = new Map();
     let pending = Promise.resolve();
-    generateEntries(root);
+    generateEntries(root, config);
     const base = baseConfig(root, config);
     const server = await createServer({
         ...base,
@@ -114,13 +115,13 @@ const start = async (root, config, options, restart) => {
         };
         const wasFailing = failed.size > 0;
         if (stages.includes("entries")) {
-            generateEntries(root);
+            generateEntries(root, config);
         }
         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 +177,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 +207,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 +272,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,16 @@
 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) => boolean;