@valancex/cli 0.12.0 → 0.13.0

package/dist/emit.js

@@ -17,30 +17,67 @@ 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 { buildWiring } from "./wiring.js";
+/** The layout of the portable core on the web: `column` and `row` are custom elements, and this is what they are (`@valancex/common`'s web vocabulary). It comes first, so a project's own styles win. */
+const CORE_CSS = `/* Generated by \`valance\`. The web's realization of the portable core's layout components. */
+vlx-column {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+vlx-row {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 0.5rem;
+}
+`;
+/** 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) => `// 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 "./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 });
 `;
-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 { 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 });
+// 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 +91,50 @@ 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);
+        }
+    }
+    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 +148,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 +168,18 @@ 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) => {
     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, "client.ts"), clientSource(root, config)),
+                writeIfChanged(generated(root, "server.ts"), serverSource(root, config)),
+            ]
+            : []),
+        ...(targets.includes("desktop") ? [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,141 @@
+// `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" },
+        build: {
+            ssr: join(root, GENERATED_DIR, "desktop.sea.ts"),
+            outDir: work,
+            emptyOutDir: false,
+            target: "node22",
+            minify: false,
+            chunkSizeWarningLimit: 4000,
+            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/targets.d.ts

@@ -1,12 +1,17 @@
 import type { Vocabulary } from "@valancex/common/internal";
 export interface Target {
     /** The flag (`--web`) and the name in `valance.<id>.json`. */
-    readonly id: "web";
+    readonly id: "web" | "desktop";
     readonly label: string;
     readonly hint: string;
     /** The tags its templates may write. A project builds against its target's vocabulary. */
     readonly vocabulary: Vocabulary;
+    /** Where the framework's own templates for this target are (the layout and the views that draw a page's blocks): a project's own `layout` and `override`s replace them by name. */
+    readonly views: string;
 }
 export declare const TARGETS: ReadonlyArray<Target>;
+export declare const targetOf: (id: TargetId) => Target;
 export type TargetId = Target["id"];
 export declare const isTarget: (name: string) => name is TargetId;
+/** What `--yes` makes: the web alone is the one that needs nothing else installed. */
+export declare const DEFAULT_TARGETS: ReadonlyArray<TargetId>;

package/dist/targets.js

@@ -1,7 +1,29 @@
-// The targets an application can be developed for. Today there is one, the web; the wizard, `vlx init` and the flags are written against this list, so a target that arrives later is one more entry
-// here (and its template under `templates/`), not a change to them.
-import { webVocabulary } from "@valancex/common/internal";
+// The targets an application can be developed for: the web, and a desktop window. The wizard, `vlx init` and the flags are written against this list, so a target that arrives later is one more
+// entry here (and its template under `templates/`, its built-in views, its vocabulary), not a change to them.
+import { fromManifests, webVocabulary } from "@valancex/common/internal";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { BUILT_IN, BUILT_IN_DESKTOP } from "./compile.js";
+/**
+ * The Desktop PORT's vocabulary: its components as data (`vocabulary.json`: columns, rows, text, a button, a checkbox, a text field; `content.json`: what Markdown produces), read from the
+ * PORT's own package (`@valancex/port-desktop-vocabulary`), not from a copy kept here.
+ */
+const desktopVocabulary = () => {
+    const need = createRequire(import.meta.url);
+    const read = (name) => JSON.parse(readFileSync(need.resolve(`@valancex/port-desktop-vocabulary/${name}`), "utf8"));
+    return fromManifests("desktop", read("vocabulary.json"), read("content.json"));
+};
 export const TARGETS = [
-    { id: "web", label: "Web", hint: "a website: Markdown pages and templates, built to a static site (settings in valance.web.json)", vocabulary: webVocabulary },
+    { id: "web", label: "Web", hint: "a website: Markdown pages and templates, built to a static site (settings in valance.web.json)", vocabulary: webVocabulary, views: BUILT_IN },
+    {
+        id: "desktop",
+        label: "Desktop",
+        hint: "a native window on Linux and Windows: Markdown pages and templates, drawn by the Desktop PORT (settings in valance.desktop.json)",
+        vocabulary: desktopVocabulary(),
+        views: BUILT_IN_DESKTOP,
+    },
 ];
+export const targetOf = (id) => TARGETS.find((each) => each.id === id);
 export const isTarget = (name) => TARGETS.some((each) => each.id === name);
+/** What `--yes` makes: the web alone is the one that needs nothing else installed. */
+export const DEFAULT_TARGETS = ["web"];

package/dist/ui/init.js

@@ -4,7 +4,7 @@ import { Box, Text, useApp } from "ink";
 import { useEffect, useRef, useState } from "react";
 import { relative } from "node:path";
 import { directoryFor, directoryProblem, execute as defaultExecute, nameProblem, PACKAGE_MANAGERS, runCommand, titleOf } from "../init.js";
-import { TARGETS } from "../targets.js";
+import { DEFAULT_TARGETS, TARGETS } from "../targets.js";
 import { Spinner } from "./Spinner.js";
 import { Answered, Confirm, MultiSelect, Select, TextPrompt } from "./prompts.js";
 const ORDER = ["name", "targets", "base", "url", "pm", "install", "git"];
@@ -75,7 +75,7 @@ export const Wizard = ({ args, cwd, detected, version, execute = defaultExecute,
             return;
         }
         finished.current = true;
-        const targets = draft.targets.length === 0 ? TARGETS.map((each) => each.id) : draft.targets;
+        const targets = draft.targets.length === 0 ? DEFAULT_TARGETS : draft.targets;
         const name = draft.name ?? "my-app";
         const answers = {
             name,
@@ -107,10 +107,10 @@ export const Wizard = ({ args, cwd, detected, version, execute = defaultExecute,
         }
     }, [outcome, failure]);
     const question = running ? undefined : ORDER[at];
-    const picked = draft.targets.length === 0 ? TARGETS.map((each) => each.id) : draft.targets;
+    const picked = draft.targets.length === 0 ? DEFAULT_TARGETS : draft.targets;
     return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "cyan", children: "vlx init" }), _jsxs(Text, { dimColor: true, children: [" \u00B7 VALANCE ", version] })] }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [answered.map(([label, value]) => (_jsx(Answered, { label: label, value: value }, label))), question === "name" ? (_jsx(TextPrompt, { label: "What is the application called?", hint: "a name, or a path: it is made in a directory of that name", initial: "my-app", validate: (value) => nameProblem(value) ?? directoryProblem(directoryFor(value, cwd)), onSubmit: (value) => {
                             answer({ name: value.trim() }, "Application", `${titleOf(value)} → ${relative(cwd, directoryFor(value, cwd)) || "."}`);
-                        } })) : null, question === "targets" ? (_jsx(MultiSelect, { label: "Which targets is it for?", choices: TARGETS.map((each) => ({ value: each.id, label: each.label, hint: each.hint })), initial: TARGETS.map((each) => each.id), onSubmit: (values) => {
+                        } })) : null, question === "targets" ? (_jsx(MultiSelect, { label: "Which targets is it for?", hint: "one application, built for each", choices: TARGETS.map((each) => ({ value: each.id, label: each.label, hint: each.hint })), initial: DEFAULT_TARGETS, onSubmit: (values) => {
                             answer({ targets: values }, "Targets", values.map((id) => TARGETS.find((each) => each.id === id)?.label ?? id).join(", "));
                         } })) : null, question === "base" ? (_jsx(TextPrompt, { label: "Web: where is the site served?", hint: "a base path: / or /docs/", initial: "/", validate: (value) => (BASE.test(value) ? undefined : "a path that starts and ends with /, like / or /docs/"), onSubmit: (value) => {
                             answer({ base: value }, "Base path", value);

package/dist/ui/run.d.ts

@@ -1,3 +1,4 @@
+import type { TargetId } from "../targets.js";
 import type { InitArgs } from "../args.js";
 import type { Checked } from "../check.js";
 import type { Diagnostic } from "../diagnostics.js";
@@ -6,10 +7,11 @@ import type { Result } from "./init.js";
 import type { Built } from "../build.js";
 export declare const drawInit: (args: InitArgs, cwd: string, detected: PackageManager, version: string) => Promise<Result>;
 export declare const drawCheck: (root: string) => Promise<Checked>;
-export declare const drawBuild: (root: string) => Promise<Built>;
+export declare const drawBuild: (root: string, targets?: ReadonlyArray<TargetId>) => Promise<Built>;
 /** Mistakes that stopped a command, drawn the way `check` draws them. */
 export declare const drawDiagnostics: (diagnostics: ReadonlyArray<Diagnostic>) => Promise<void>;
 export declare const drawDev: (root: string, options: {
+    readonly target?: TargetId;
     readonly port?: number;
     readonly host?: string;
 }) => Promise<void>;

package/dist/ui/run.js

@@ -1,5 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// Putting the views on the terminal. Ink and React are loaded only here, and only when a command is going to draw: a command that prints plain text never pays for them.
 import { render } from "ink";
 import { build as runBuild } from "../build.js";
 import { check as runCheck } from "../check.js";
@@ -33,11 +32,14 @@ export const drawCheck = async (root) => {
         await shown.waitUntilExit();
     }
 };
-export const drawBuild = async (root) => {
+export const drawBuild = async (root, targets = []) => {
     const started = Date.now();
     const shown = show(_jsx(BuildProgress, { current: "configuration" }));
     try {
-        const built = await runBuild(root, { onStage: ((stage) => shown.rerender(_jsx(BuildProgress, { current: stage }))) });
+        const built = await runBuild(root, {
+            ...(targets.length === 0 ? {} : { targets }),
+            onStage: ((stage) => shown.rerender(_jsx(BuildProgress, { current: stage }))),
+        });
         shown.rerender(_jsx(BuildResult, { built: built, seconds: (Date.now() - started) / 1000 }));
         return built;
     }

package/dist/vite.d.ts

@@ -1,7 +1,8 @@
-import type { InlineConfig, ViteDevServer } from "vite";
+import type { InlineConfig, Plugin, ViteDevServer } from "vite";
 import type { Config } from "./config.js";
 export declare const CLIENT_ENTRY = ".valance/client.ts";
 export declare const SERVER_ENTRY = "/.valance/server.ts";
-export declare const baseConfig: (root: string, config: Config) => InlineConfig;
+export declare const templates: (root: string) => Plugin;
+export declare const baseConfig: (root: string, config: Config, out?: string) => InlineConfig;
 /** A Vite server that serves nothing: it loads the author's TypeScript and the generated server entry in Node. Used by build and check. */
 export declare const createLoader: (root: string, config: Config) => Promise<ViteDevServer>;

package/dist/vite.js

@@ -20,7 +20,7 @@ logger.warnOnce = (message, options) => {
 };
 // `import layout from "./layout.mprx"` in `src/main.ts` is the author naming a template. The import gives the file's address and nothing else: the compiler reads the file itself, and the
 // browser bundle must not carry template text it has already been compiled from.
-const templates = (root) => ({
+export const templates = (root) => ({
     name: "vlx-templates",
     enforce: "pre",
     load(id) {
@@ -30,7 +30,7 @@ const templates = (root) => ({
     // The module is only the file's address, so a change to the template changes nothing the browser holds; the rebuild (dev.ts) recompiles it and reloads once, with the overlay if it fails.
     handleHotUpdate: ({ file }) => (file.endsWith(".mprx") ? [] : undefined),
 });
-export const baseConfig = (root, config) => ({
+export const baseConfig = (root, config, out = OUTPUT_DIR) => ({
     root,
     configFile: false,
     base: config.web.base,
@@ -41,7 +41,7 @@ export const baseConfig = (root, config) => ({
     cacheDir: join(root, GENERATED_DIR, "cache"),
     customLogger: logger,
     clearScreen: false,
-    build: { outDir: join(root, OUTPUT_DIR), emptyOutDir: true, target: "esnext", manifest: true, chunkSizeWarningLimit: 1500, rollupOptions: { input: join(root, CLIENT_ENTRY) } },
+    build: { outDir: join(root, out), emptyOutDir: true, target: "esnext", manifest: true, chunkSizeWarningLimit: 1500, rollupOptions: { input: join(root, CLIENT_ENTRY) } },
     // The MESH runtime refers to node:fs/promises on a path the browser never takes.
     optimizeDeps: { exclude: ["@valancex/mesh-runtime", "@valancex/cli", "@valancex/common"] },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "vlx, the VALANCE command: make an application (vlx init), serve it as you edit (vlx dev), build it to a static site (vlx build), check it (vlx check). Content, layout, components and styles in, a website out.",
   "keywords": [
     "valance",
@@ -40,6 +40,7 @@
     "dist",
     "bin",
     "views",
+    "views-desktop",
     "schemas",
     "templates"
   ],
@@ -49,12 +50,14 @@
   },
   "dependencies": {
     "@valancex/mesh-compiler": "^0.11.0",
+    "@valancex/port-desktop-vocabulary": "^0.6.0",
     "effect": "^3.10.0",
     "ink": "7.1.1",
+    "postject": "1.0.0-alpha.6",
     "react": "19.2.8",
     "vite": "7.3.6",
-    "@valancex/common": "^0.12.0",
-    "@valancex/valance": "^0.12.0"
+    "@valancex/valance": "^0.13.0",
+    "@valancex/common": "^0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/schemas/valance.desktop.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://valancex.dev/schemas/valance.desktop.schema.json",
+  "title": "valance.desktop.json",
+  "description": "Marks the project as a desktop one: it is built to an engine that a native window runs. It has no settings yet.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "The version of this file's format."
+    }
+  }
+}