@valancex/cli 0.11.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.
 
@@ -98,8 +108,8 @@ That is a complete application. It uses a built-in layout. Everything below is h
 
 | Path | What it is | Edited by |
 |---|---|---|
-| `valance.json` | The project: its `name`. | you |
-| `valance.web.json` | The web target: `base` (where it is served, default `/`) and `url` (where it is published; adds canonical links and `sitemap.xml`). Optional. | you |
+| `valance.json` | The project: its `name`, and optionally the `title` format (see [The document's title](#the-documents-title)). | you |
+| `valance.web.json` | The web target: `base` (where it is served, default `/`), `url` (where it is published; adds canonical links and `sitemap.xml`), `api` (the backend: [below](#talking-to-a-backend)), `headers` (write the [security headers](#security-headers), default on) and `announce` (tell assistive technology about page changes, default on). Optional. | you |
 | `content/**/*.md` | The pages. A file's path is its address. | you |
 | `public/**` | Files served as they are (`public/logo.svg` is `/logo.svg`). | you |
 | `src/layout.mprx` | The shell around every page. Optional: without a `layout` in `src/main.ts` a default ships. | you |
@@ -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"`).
 
@@ -141,6 +151,7 @@ Templates are MPRX. Conditional and repeated parts are blocks: `{#if cond}…{:e
 | `hasToc`, `toc` | The `##`/`###` headings of this page: `[{ id, href, label, level }]` |
 | `blocks` | The page body. `<blocks items={blocks} />` draws it |
 | `prev`, `next` | `{ href, label }`, empty `href` when there is none |
+| `viewport` | How much room the page has: `"compact"` (under 600 px), `"medium"` (600 to 839) or `"expanded"` (840 and up), kept current as the window changes. `{#if viewport == "compact"}` chooses markup for a phone. The server renders `expanded`; the browser corrects it as soon as it starts. |
 
 Tags you may use: `shell` (`class`, `theme`), `div`, `header`, `footer`, `nav` (`class`, `label`), `aside`, `section`, `article`, `main` (`id`, `tabindex`), `h1`–`h3` (`id`), `para`, `quote`, `list`, `olist`, `item`, `pre`, `code`, `strong`, `em`, `span`, `image`, `a` (`href`), `link` (`href`, `class`, `current`), `button` (`class`, `pressed`, `on.click`), plus your components and the built-ins (`blocks`, `block`, `heading`, `list-block`, `list-items`, `runs`, `inline`). A prop a tag declares must be written wherever the tag is used; that is why there are many narrow tags rather than a few wide ones. The attribute each prop becomes is in [`src/primitives.ts`](src/primitives.ts).
 
@@ -175,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
@@ -228,6 +239,97 @@ 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`:
+
+```json
+{ "name": "Notes", "title": "{page} · {site}" }
+```
+
+`{page}` is the page's part and `{site}` the name; the format must contain `{page}`, and a page whose title is the site's name is that name alone. The application can say its own parts from its state:
+
+```ts
+export default defineApp({
+  state: { unread: field(Schema.Number, 0) },
+  title: (state, page) => ({ status: state.unread > 0 ? String(state.unread) : undefined }),   // "(3) Inbox · Notes"
+});
+```
+
+`title` returns `{ page?, app?, status? }` (a string is the page part). `status` is what is going on right now and belongs to no page (an unread count, "Saving…"); it is written first, in parentheses. A target that is not a web page uses the same three parts for its own surfaces (a window title, a navigation bar, a badge). The function runs for every committed state, on the server for the one it renders and in the browser after each; if it throws, the default title is used and the failure is logged by name.
+
+Every title and meta is **plain text** by the time it reaches the document: control characters and the bidirectional override and isolate characters (U+202A to U+202E, U+2066 to U+2069) are removed (they let a string reorder or hide what is around it in a tab or a history list), whitespace is collapsed, and a title is cut at 200 characters. A title is written only when it changed. After a page changes in place, a polite live region says the new title and focus moves to `#content` (when your layout's `<main id="content" tabindex="-1">` is focusable, as the scaffold's is), as a page load would; a link to a `#heading` is left to the browser. Turn it off with `"announce": false` in `valance.web.json`.
+
+## Talking to a backend
+
+NEXUS and VALANCE hold no HTTP: what an application needs from where it runs is a **capability**, which the platform supplies. `@valancex/common/http` is that contract for HTTP, and the web page supplies it with `fetch`.
+
+```ts
+import { defineApp, field } from "@valancex/common";
+import { request } from "@valancex/common/http";
+import { Schema } from "effect";
+
+const Inbox = Schema.Struct({ unread: Schema.Number });
+
+export default defineApp({
+  state: { unread: field(Schema.Number, 0), failed: field(Schema.String, "") },
+  commands: (command) => ({
+    refresh: command.waiting(Schema.Struct({}), {
+      work: () => request({ path: "/inbox", response: Inbox }),
+      wanted: () => true,
+      settle: (outcome, _input, state) => (outcome.ok ? { ...state, unread: outcome.value.unread, failed: "" } : { ...state, failed: "could not load" }),
+    }),
+  }),
+});
+```
+
+Where the requests go is `api` in `valance.web.json`:
+
+```json
+{ "api": { "base": "/api", "proxy": "http://localhost:3000" } }
+```
+
+`base` is a path on the site's own origin (the default is the origin's root) or an absolute `https` address; `proxy` is for `vlx dev`: requests under a path `base` are forwarded to it, so the browser sees one origin and the backend needs no CORS settings.
+
+What the client does, so a command does not have to: the path must start with a single `/` (a path built from data cannot send the request elsewhere: `//host`, a scheme, a backslash or `..` is `Unsafe`); it sends and accepts JSON and refuses any other answer type (an HTML error page is `Decode`, never state); the answer is **decoded by the Schema you give** before it reaches the command; it is bounded in time (15 s, `Timeout`) and size (`TooLarge`); it is cancelled when the application ends (`Aborted`); same-origin credentials only, and an `api.base` on another origin gets none unless the application asks; unsafe methods carry `x-requested-with: valance`, which a plain cross-site form cannot send. A failure is one of `Offline`, `Status(code)`, `Decode`, `Timeout`, `Aborted`, `TooLarge` or `Unsafe` and **never carries the answer, the address or a header**, which can hold a secret.
+
+A static site cannot keep a secret: nothing in `src/` or `valance.web.json` should be one. For sign-in on the web, prefer a same-origin session cookie (`HttpOnly`, `Secure`, `SameSite=Lax` or `Strict`, set by the backend) to a token in `localStorage`, which any script that gets past the policy can read. A desktop or mobile target supplies the same `Http` capability with the platform's own client and a keychain-backed token; no command changes. Data fetched while building (`vlx build`) is not part of the model, and server rendering of a command that waits is not either.
+
+## Security headers
+
+`vlx build` writes `_headers` beside the site (the file Netlify and Cloudflare Pages read; other hosts take the same lines):
+
+```
+Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; object-src 'none'
+X-Content-Type-Options: nosniff
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()
+Cross-Origin-Opener-Policy: same-origin
+```
+
+The page's runtime is WebAssembly, so a strict policy needs **`'wasm-unsafe-eval'`** in `script-src` and nothing more permissive: no `'unsafe-inline'`, no `'unsafe-eval'`. Without it the server's HTML stays and the application never starts (`data-valance="failed"`). `connect-src` adds the origin of an absolute `api.base`. The site's own test runs under this exact policy with no violation. If you serve the site with your own policy, start from this one. Turn the file off with `"headers": false`. `vlx dev` does not send it (the bundler's development client needs inline scripts).
+
 ## What `vlx dev` does when you save
 
 | You change | It does |
@@ -237,7 +339,7 @@ A state field is its type and its default in one declaration. Hand-building `sta
 | `src/**/*.css` | updates the style in the open page, no reload |
 | `public/**` | reloads |
 | a new or removed stylesheet or `src/main.ts` | rewrites the entry, reloads |
-| `valance.json`, `valance.web.json` | restarts the server (the name and the base are fixed at startup) |
+| `valance.json`, `valance.web.json` | restarts the server (the name, the base and the proxy are fixed at startup) |
 
 A mistake leaves the last good build serving and appears in the terminal and as an overlay in the page, as `file:line:column code: message`. Fixing it reloads the page. There is no hot swap of the compiled templates yet: a reload is the correct, reliable update, and the browser keeps its address.
 
@@ -249,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
 
@@ -259,6 +361,6 @@ 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. An application cannot declare new primitives.
-- Only the web target exists, delivered as a static site. No server rendering command, no `preview` command.
+- 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.
+- 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>;