@valancex/cli 0.12.0 → 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -66,6 +66,16 @@ Then it writes the project (the same files as `examples/docs-app`: a layout, a c
 
 Without a terminal (a pipe, CI) it cannot ask, so it needs a name and a target: `vlx init my-app --web`.
 
+## A desktop application: `vlx init --desktop`
+
+A project has the targets whose settings file it has; `vlx init my-app --web --desktop` makes both, and `defineApp`'s `targets` gives each its templates (how it was designed and what it found: `docs/application-model/MULTI-TARGET.md` and `MULTI-TARGET-PLAN.md`). `vlx init my-app --desktop` makes the same project as for the web (Markdown in `content/`, a layout, state and commands in `src/main.ts`) with `valance.desktop.json` in place of `valance.web.json`. Its templates are written against the Desktop PORT's vocabulary (`column`, `row`, `heading`, `text`, `button`, `checkbox`, `textfield`, and the content layer: `paragraph`, `list`, `listitem`, `blockquote`, `emphasis`, …), not the web's tags: `<div>` in a desktop project is an error from `vlx check`.
+
+`vlx build` writes the engine to `dist/desktop/`: `engine.mjs` (everything bundled; run it with Node) and `mesh-runtime.wasm` beside it. The engine speaks the host protocol on stdin and stdout; the window that runs it is the Desktop PORT's (`valancex-port-desktop`). `vlx package --desktop` packs the engine into one executable (Node's single executable application, with the MESH runtime inside) and sets it beside the window program (`--window <path>`, or `VLX_WINDOW`, or `vlx-window` on the PATH) in `dist/package/<platform>/`. `--archive` also writes the package as one reproducible file, a `.tar.gz` (Linux) or a `.zip` (Windows), with its SHA-256 beside it. **Unsigned**: signing and notarization are not done by `vlx`. For another platform, `--platform win32-x64 --node <that platform's node> --window <that platform's window>`. `vlx dev` builds the engine, opens the Desktop PORT's window on it (the `vlx-window` program, installed with `cargo install --git https://github.com/ValanceX/Port valancex-port-desktop --bin vlx-window`, found on the PATH or at `VLX_WINDOW`), and when a file changes it builds again and tells the running window to start the engine again in place (the window keeps its position and size). Closing the window ends `vlx dev`.
+
+## Adding a target: `vlx generate target desktop`
+
+A web project becomes a project of two targets without moving anything: `vlx generate target desktop` writes `valance.desktop.json` (and `valance.web.json`, which a project needs once it has another target's), a layout of its own in `src/desktop/`, and registers it in `targets` in `src/main.ts`. The layout the project has stays the default for a target with none of its own. **The site moves**: a project of one web target builds to `dist/`, one of several to `dist/<target>/` (`dist/web/`, `dist/desktop/`), so a deploy step that serves `dist/` is pointed at `dist/web/` when the second target is added (the command says so). See `docs/application-model/MULTI-TARGET.md`.
+
 ## Adding to an application: `vlx generate`
 
 ```console
@@ -90,7 +100,7 @@ Try it locally: [`docs/application-model/TRY-IT.md`](../../docs/application-mode
    and a `package.json` that depends on `@valancex/cli` and has `"dev": "vlx dev"`, `"build": "vlx build"`.
 2. Add pages: **`content/index.md`** is the first page (`# Notes` and some text). Every other `.md` file under `content/` is a page.
 3. `pnpm dev`. Open the address it prints. Edit a Markdown file and save: the page reloads with your change.
-4. `pnpm build`. The site is in `dist/`; any host that serves files can serve it.
+4. `pnpm build`. The site is in `dist/web/`; any host that serves files can serve it.
 
 That is a complete application. It uses a built-in layout. Everything below is how you take over a part of it.
 
@@ -107,7 +117,7 @@ That is a complete application. It uses a built-in layout. Everything below is h
 | `src/**/*.css` | Styles. Every stylesheet is loaded. | you |
 | `src/main.ts` | Optional until you own a template. `defineApp`: the `layout`, your `components`, state of your own and the commands that change it. | you |
 | `.valance/` | Generated: content, compiled templates, the entries, and for editors `manifest.json` (what a template may use) and `editor.json` (which file is which component). Git-ignored by a `.gitignore` inside it. | the tools |
-| `dist/` | The built site. | the tools |
+| `dist/web/` | The built site. | the tools |
 
 Settings are validated, unknown keys are errors, and editors can use the JSON Schemas in `schemas/` (`"$schema": "./node_modules/@valancex/cli/schemas/valance.schema.json"`).
 
@@ -176,7 +186,7 @@ export default component(template, {
 - `import x from "./x.mprx"` names a template file; `component(x, …)` defines it. The tag is the file's name (`theme-toggle.mprx` is `<theme-toggle>`). Register it once, in `components`.
 - **Which components a template uses is read from the template.** Write `<theme-toggle … />` in the layout (or in another component) and it is used; there is no list of uses to keep in step. A registered component no template writes yet is not part of the program, and is not an error. A file under `src/` that is not registered is an error (`template-unused`).
 - **The contract.** `props` maps a prop name to its Effect Schema and `events` an event name to its payload Schema (`Schema.Void` is no payload). Declare either and the contract is exactly what you wrote (an omitted side is none), overriding inference; declare neither and MESH infers it from the template and where it is used. Schemas are converted by the same rules as state; a prop is optional when its schema admits `undefined`, and props have no defaults. A schema with no MESH type is a diagnostic at the declaration (`component-schema`). MESH reports an undeclared or missing prop, a prop of the wrong type and a handler for an undeclared event at the use. The layout takes no contract (`layout-contract`). That declared interface is where an editor takes you from `on.toggle=` or `theme=` at a use, and where *Find All References* starts.
-- `override: [component(runs, { props: { spans: … } })]` replaces a built-in (`runs`, `heading`, …) with your template of the same name.
+- `override: [component(runs, { props: { spans: … } })]` replaces a built-in (`runs`, `heading-block`, …) with your template of the same name.
 - `layout` is optional; without it the built-in layout draws the page. Its template must be named `layout.mprx`.
 
 ### Children and slots
@@ -229,6 +239,27 @@ export default defineApp({
 
 A state field is its type and its default in one declaration. Hand-building `state: { schema, initial }` is still accepted; giving both forms is the same definition error as a clash. `theme` is now a name the layout reads (`<shell theme={theme}>`) and `toggleTheme()` a command it runs (`on.click={toggleTheme()}`). A component raises an event (`on.click={toggle()}`, declared in `events`) and its user binds it (`<theme-toggle on.toggle={toggleTheme()} />`). A state field may not reuse a framework name (`site`, `title`, `blocks`…), and `go` is the framework's command. Both are errors that say so.
 
+### Values worked out, kept, and moved between
+
+`defineApp` has more than state and commands. All of it is the same on every target:
+
+```ts
+export default defineApp({
+  state: { items: field(Schema.Array(Item), []), theme: field(Schema.Literal("system", "light", "dark"), "system") },
+  // Worked out from the state, with their types, for a template to read: `{summary}`.
+  derived: (derive) => ({ summary: derive(Schema.String, (state) => `${state.items.length} items`) }),
+  // Kept between runs through the platform's `Store` (the page's storage; a file in the user's data directory on the desktop).
+  // "navigation" keeps the pages visited, where the engine keeps them (a window; a page's list is the browser's).
+  persist: ["items", "theme", "navigation"],
+  // What the window asks to look like (`"light"`, `"dark"` or `"system"`); the layout reads `colorScheme`, the system's.
+  appearance: (state) => state.theme,
+  // Asked before `go`, `back` and `forward` (the router's `Guard`): `false` stops the move, `redirect(page)` sends it elsewhere.
+  guard: ({ to, kind }) => to.name !== "/private",
+});
+```
+
+The framework's own names are `page`, `trail`, `cursor`, `viewport`, `colorScheme`, `canGoBack` and `canGoForward` (state a layout reads) and the commands `go`, `back`, `forward`, `resize`, `colorScheme` and `persist`; an application's own state and commands cannot take them. A text field reports `change`, `submit` (Enter) and `cancel` (Escape). `Store` and `Open` (send a person to an address outside the application: a new tab, or the system's opener) are capabilities in `@valancex/common`. How navigation is modelled across a page, a window and a phone: `docs/application-model/NAVIGATION.md`.
+
 ## The document's title
 
 A page's title is its front-matter `title` (else its first heading), written with the project's format in `valance.json`:
@@ -320,7 +351,7 @@ A mistake leaves the last good build serving and appears in the terminal and as
 $ pnpm add -D @valancex/mesh-lsp
 ```
 
-The VS Code extension in [`editors/vscode`](../../editors/vscode) (not published yet) starts it, highlights `.mprx`, and shows `vlx check` mistakes in Markdown, config and `main.ts`. Neovim and Helix can use the same two files ([MESH's editor guide](https://github.com/ValanceX/Mesh/blob/main/docs/guides/editor-setup.md)).
+The VS Code extension (**VALANCE**, in [`editors/vscode`](../../editors/vscode)) starts it, highlights `.mprx`, and shows `vlx check` mistakes in Markdown, config and `main.ts`. Neovim and Helix can use the same two files ([MESH's editor guide](https://github.com/ValanceX/Mesh/blob/main/docs/guides/editor-setup.md)).
 
 ## Diagnostics
 
@@ -331,5 +362,5 @@ Every mistake the tools can attribute to a file has one shape: `{ file, line, co
 - The whole content model ships in the page bundle. Fine for tens of pages; a per-page payload is the known answer for hundreds (the documentation verifier does it).
 - The Markdown dialect is a subset; no syntax highlighting, tables, callouts, tabs, search, versions or languages (the verifier has these as stand-ins).
 - The tag table is fixed, and it is the web's: `class`, `theme`, `tabindex`, `label`, `current`, `pressed`, `id` and `loading` are web hooks (a build against a vocabulary without them rejects the built-in views). An application cannot declare new primitives.
-- Only the web target exists, delivered as a static site. No server rendering command, no `preview` command.
+- The web target is delivered as a static site, with no server rendering command and no `preview` command; the desktop target needs the Desktop PORT's window built from its source (it is not yet published). A third target (a phone) does not exist.
 - Updates are reloads, not hot swaps (except styles).

package/dist/add.d.ts

@@ -1,4 +1,5 @@
-export declare const KINDS: readonly ["page", "component"];
+import type { TargetId } from "./targets.js";
+export declare const KINDS: readonly ["page", "component", "target"];
 export type Kind = (typeof KINDS)[number];
 export interface Generated {
     /** Files written, relative to the project. */
@@ -18,3 +19,10 @@ export declare const componentProblem: (name: string, root?: string) => string |
 /** `main.ts` with `ident` added to `components`, or `undefined` when its definition is not written in the plain form this can edit. */
 export declare const register: (text: string, ident: string, name: string) => string | undefined;
 export declare const generateComponent: (root: string, name: string) => Generated;
+/**
+ * `main.ts` with a `targets` entry for `id`: its layout, from `src/<id>/layout.mprx`. `undefined` when the definition is not written in the plain form this can edit (or already has `targets`).
+ * The layout the project already has stays the default for every target that has none of its own, so nothing is moved.
+ */
+export declare const registerTarget: (text: string, id: TargetId) => string | undefined;
+/** Adds a target to the project: its settings file, and a starting layout of its own in `src/<id>/`, registered in `src/main.ts`. Nothing the project has is moved or changed but `src/main.ts`. */
+export declare const generateTarget: (root: string, given: string) => Generated;

package/dist/add.js

@@ -2,10 +2,12 @@
 // Nothing here overwrites a file: a name that is taken is refused.
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { BUILT_IN, ROOT, SOURCE_DIR } from "./compile.js";
+import { BUILT_IN, BUILT_IN_DESKTOP, ROOT, SOURCE_DIR } from "./compile.js";
+import { DESKTOP_FILE, loadConfig, WEB_FILE } from "./config.js";
+import { isTarget } from "./targets.js";
 import { ENTRY_FILE } from "./project.js";
 import { primitives } from "@valancex/common/internal";
-export const KINDS = ["page", "component"];
+export const KINDS = ["page", "component", "target"];
 export class GenerateError extends Error {
 }
 const words = (name) => name.replace(/[-_]+/g, " ").replace(/^./, (first) => first.toUpperCase());
@@ -40,9 +42,7 @@ export const generatePage = (root, given, title) => {
     return { created: [file], changed: [], notes: [] };
 };
 // ---- a component -------------------------------------------------------------------------------------------------------------------------------------------
-const builtIns = () => new Set(readdirSync(BUILT_IN)
-    .filter((file) => file.endsWith(".mprx"))
-    .map((file) => file.slice(0, -".mprx".length)));
+const builtIns = () => new Set([...readdirSync(BUILT_IN), ...readdirSync(BUILT_IN_DESKTOP)].filter((file) => file.endsWith(".mprx")).map((file) => file.slice(0, -".mprx".length)));
 export const componentProblem = (name, root) => {
     if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name)) {
         return `"${name}" cannot be a tag: use lowercase words joined by - (callout, post-card)`;
@@ -141,3 +141,66 @@ export const generateComponent = (root, name) => {
     notes.push(`use it by writing <${name}></${name}> in a template`);
     return { created, changed, notes };
 };
+// ---- a target ----------------------------------------------------------------------------------------------------------------------------------------------
+/**
+ * `main.ts` with a `targets` entry for `id`: its layout, from `src/<id>/layout.mprx`. `undefined` when the definition is not written in the plain form this can edit (or already has `targets`).
+ * The layout the project already has stays the default for every target that has none of its own, so nothing is moved.
+ */
+export const registerTarget = (text, id) => {
+    const define = /defineApp\(\s*\{/.exec(text);
+    if (define === null || /\btargets\s*:/.test(text)) {
+        return undefined;
+    }
+    const ident = `${id}Layout`;
+    const at = define.index + define[0].length;
+    let edited = `${text.slice(0, at)}\n  targets: { ${id}: { layout: component(${ident}) } },${text.slice(at)}`;
+    edited = withImport(edited, `import ${ident} from "./${id}/layout.mprx";`);
+    return /import\s*\{[^}]*\bcomponent\b[^}]*\}\s*from\s*"@valancex\/common"/.test(edited) ? edited : withImport(edited, 'import { component } from "@valancex/common";');
+};
+/** Adds a target to the project: its settings file, and a starting layout of its own in `src/<id>/`, registered in `src/main.ts`. Nothing the project has is moved or changed but `src/main.ts`. */
+export const generateTarget = (root, given) => {
+    if (!isTarget(given)) {
+        throw new GenerateError(`"${given}" is not a target: the targets are web and desktop (vlx generate target desktop)`);
+    }
+    const id = given;
+    const config = loadConfig(root);
+    if (config.targets.includes(id)) {
+        throw new GenerateError(`this project already has the ${id} target`);
+    }
+    const settings = id === "web" ? WEB_FILE : DESKTOP_FILE;
+    const layout = `${SOURCE_DIR}/${id}/layout.mprx`;
+    const entry = join(root, ENTRY_FILE);
+    if (existsSync(join(root, layout))) {
+        throw new GenerateError(`${layout} already exists`);
+    }
+    const marker = (target) => `${JSON.stringify({ $schema: `./node_modules/@valancex/cli/schemas/valance.${target}.schema.json`, version: 1 }, null, 2)}\n`;
+    const created = [];
+    // A project is for the web when it has no settings file at all; once it has another target's, the web needs its own to stay a target.
+    if (id === "desktop" && !existsSync(join(root, WEB_FILE))) {
+        write(root, WEB_FILE, marker("web"));
+        created.push(WEB_FILE);
+    }
+    write(root, settings, marker(id));
+    created.push(settings);
+    // The framework's own layout for the target is the starting point: the page's shell, the sections and the previous and next pages.
+    write(root, layout, readFileSync(join(id === "web" ? BUILT_IN : BUILT_IN_DESKTOP, "layout.mprx"), "utf8"));
+    created.push(layout);
+    const changed = [];
+    const notes = [];
+    if (!existsSync(entry)) {
+        write(root, ENTRY_FILE, `import { component, defineApp } from "@valancex/common";\nimport ${id}Layout from "./${id}/layout.mprx";\n\nexport default defineApp({\n  targets: { ${id}: { layout: component(${id}Layout) } },\n});\n`);
+        created.push(ENTRY_FILE);
+    }
+    else {
+        const edited = registerTarget(readFileSync(entry, "utf8"), id);
+        if (edited === undefined) {
+            notes.push(`add it to ${ENTRY_FILE} yourself: import ${id}Layout from "./${id}/layout.mprx"; and give defineApp \`targets: { ${id}: { layout: component(${id}Layout) } }\``);
+        }
+        else {
+            writeFileSync(entry, edited);
+            changed.push(ENTRY_FILE);
+        }
+    }
+    notes.push(`the ${id} target is drawn with its own vocabulary: write its templates in ${SOURCE_DIR}/${id}/, and the state, the commands and the content are shared`);
+    return { created, changed, notes };
+};

package/dist/archive.d.ts

@@ -0,0 +1,17 @@
+export interface Entry {
+    /** Path inside the archive, `/` separated, no leading slash. */
+    readonly path: string;
+    readonly data: Buffer;
+    /** Unix permission bits (0o755 for a program, 0o644 for data). */
+    readonly mode: number;
+}
+export declare const crc32: (data: Uint8Array) => number;
+/** A gzipped tar of `entries`, in the order given. */
+export declare const tarGz: (entries: ReadonlyArray<Entry>) => Buffer;
+/** A zip of `entries` (deflated), with each entry's Unix mode kept so a program stays executable where the unzipper honors it. */
+export declare const zip: (entries: ReadonlyArray<Entry>) => Buffer;
+/** `sha256sum`'s format: the hex digest, two spaces, the file name; one line per file. */
+export declare const checksums: (files: ReadonlyArray<{
+    readonly name: string;
+    readonly data: Buffer;
+}>) => string;

package/dist/archive.js

@@ -0,0 +1,111 @@
+// Archives for `vlx package --archive`: a .tar.gz (Linux) and a .zip (Windows), written here with Node's own zlib so nothing has to be installed, and written the same every time (no clock, no owner)
+// so the same files make the same bytes and a checksum means something.
+import { createHash } from "node:crypto";
+import { deflateRawSync, gzipSync } from "node:zlib";
+/** CRC-32 (the zip checksum), here and not `zlib.crc32`: that is Node 22.2 and later, and `vlx` also runs under the Node an editor ships (VS Code 1.90 has 20.9). */
+const TABLE = Uint32Array.from({ length: 256 }, (_, n) => {
+    let value = n;
+    for (let bit = 0; bit < 8; bit += 1) {
+        value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    return value >>> 0;
+});
+export const crc32 = (data) => {
+    let crc = 0xffffffff;
+    for (const byte of data) {
+        crc = TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+};
+const octal = (value, width) => value.toString(8).padStart(width - 1, "0") + "\0";
+/** One ustar header (512 bytes). A path longer than 100 bytes is split at a `/` into prefix and name, as ustar does. */
+const tarHeader = (path, size, mode) => {
+    const bytes = Buffer.byteLength(path);
+    let name = path;
+    let prefix = "";
+    if (bytes > 100) {
+        const cut = path.lastIndexOf("/", path.length - 1);
+        const split = path.slice(0, cut);
+        const rest = path.slice(cut + 1);
+        if (cut < 0 || Buffer.byteLength(rest) > 100 || Buffer.byteLength(split) > 155) {
+            throw new Error(`the path is too long for an archive: ${path}`);
+        }
+        prefix = split;
+        name = rest;
+    }
+    const header = Buffer.alloc(512);
+    header.write(name, 0, "utf8");
+    header.write(octal(mode & 0o777, 8), 100, "ascii");
+    header.write(octal(0, 8), 108, "ascii"); // uid
+    header.write(octal(0, 8), 116, "ascii"); // gid
+    header.write(octal(size, 12), 124, "ascii");
+    header.write(octal(0, 12), 136, "ascii"); // mtime: the epoch, so the same files are the same bytes
+    header.write("        ", 148, "ascii"); // the checksum is summed over this field as spaces
+    header.write("0", 156, "ascii"); // a regular file
+    header.write("ustar\0" + "00", 257, "ascii");
+    header.write(prefix, 345, "utf8");
+    const sum = header.reduce((total, byte) => total + byte, 0);
+    header.write(octal(sum, 7) + " ", 148, "ascii");
+    return header;
+};
+/** A gzipped tar of `entries`, in the order given. */
+export const tarGz = (entries) => {
+    const parts = [];
+    for (const entry of entries) {
+        parts.push(tarHeader(entry.path, entry.data.length, entry.mode), entry.data, Buffer.alloc((512 - (entry.data.length % 512)) % 512));
+    }
+    parts.push(Buffer.alloc(1024)); // two empty blocks end an archive
+    return gzipSync(Buffer.concat(parts), { level: 9, mtime: 0 });
+};
+const DOS_TIME = 0; // 00:00:00
+const DOS_DATE = (1 << 5) | 1; // 1980-01-01, the earliest a zip can say
+/** A zip of `entries` (deflated), with each entry's Unix mode kept so a program stays executable where the unzipper honors it. */
+export const zip = (entries) => {
+    const local = [];
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.path, "utf8");
+        const packed = deflateRawSync(entry.data, { level: 9 });
+        const crc = crc32(entry.data);
+        const head = Buffer.alloc(30);
+        head.writeUInt32LE(0x04034b50, 0);
+        head.writeUInt16LE(20, 4); // version needed
+        head.writeUInt16LE(0x0800, 6); // names are UTF-8
+        head.writeUInt16LE(8, 8); // deflate
+        head.writeUInt16LE(DOS_TIME, 10);
+        head.writeUInt16LE(DOS_DATE, 12);
+        head.writeUInt32LE(crc, 14);
+        head.writeUInt32LE(packed.length, 18);
+        head.writeUInt32LE(entry.data.length, 22);
+        head.writeUInt16LE(name.length, 26);
+        head.writeUInt16LE(0, 28);
+        local.push(head, name, packed);
+        const entryCentral = Buffer.alloc(46);
+        entryCentral.writeUInt32LE(0x02014b50, 0);
+        entryCentral.writeUInt16LE((3 << 8) | 20, 4); // made by Unix, version 2.0
+        entryCentral.writeUInt16LE(20, 6);
+        entryCentral.writeUInt16LE(0x0800, 8);
+        entryCentral.writeUInt16LE(8, 10);
+        entryCentral.writeUInt16LE(DOS_TIME, 12);
+        entryCentral.writeUInt16LE(DOS_DATE, 14);
+        entryCentral.writeUInt32LE(crc, 16);
+        entryCentral.writeUInt32LE(packed.length, 20);
+        entryCentral.writeUInt32LE(entry.data.length, 24);
+        entryCentral.writeUInt16LE(name.length, 28);
+        entryCentral.writeUInt32LE(((0o100000 | (entry.mode & 0o777)) << 16) >>> 0, 38); // external attributes: a Unix regular file and its mode
+        entryCentral.writeUInt32LE(offset, 42);
+        central.push(entryCentral, name);
+        offset += head.length + name.length + packed.length;
+    }
+    const directory = Buffer.concat(central);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...local, directory, end]);
+};
+/** `sha256sum`'s format: the hex digest, two spaces, the file name; one line per file. */
+export const checksums = (files) => files.map((file) => `${createHash("sha256").update(file.data).digest("hex")}  ${file.name}\n`).join("");

package/dist/args.js

@@ -4,8 +4,8 @@ export const INIT_HELP = `vlx init [app-name] [options]
 
 Make a new application. Without options it asks what it needs to know.
 
-  --web                      develop for the web (a flag per target: ${TARGETS.map((each) => `--${each.id}`).join(", ")})
-  -y, --yes                  answer every question with its default (all targets)
+  --web, --desktop           the targets: the web, a desktop window, or both (a flag per target: ${TARGETS.map((each) => `--${each.id}`).join(", ")})
+  -y, --yes                  answer every question with its default (the web)
   --pm <npm|pnpm|yarn|bun>   the package manager (default: the one that ran this, else npm)
   --no-install               do not install the dependencies
   --no-git                   do not run git init

package/dist/build.d.ts

@@ -1,3 +1,4 @@
+import type { TargetId } from "./targets.js";
 export interface Built {
     readonly dir: string;
     readonly files: ReadonlyArray<string>;
@@ -10,5 +11,7 @@ export type BuildStage = "configuration" | "content" | "templates" | "bundle" |
 export interface BuildOptions {
     /** Called as each stage begins. */
     readonly onStage?: (stage: BuildStage) => void;
+    /** Which of the project's targets to build; all of them by default. */
+    readonly targets?: ReadonlyArray<TargetId>;
 }
 export declare const build: (root: string, options?: BuildOptions) => Promise<Built>;

package/dist/build.js

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

package/dist/check.js

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