@valancex/cli 0.12.0 → 0.14.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"`).
 
@@ -143,7 +153,7 @@ Templates are MPRX. Conditional and repeated parts are blocks: `{#if cond}…{:e
 | `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).
+Tags you may use: `shell` (`class`, `theme`), `div`, `header`, `footer`, `nav` (`class`, `label`), `aside`, `section`, `article`, `main` (`id`, `tabindex`), `h1`–`h3` (`id`), `paragraph`, `blockquote`, `list`, `olist`, `listitem`, `pre`, `code`, `strong`, `em`, `span`, `image`, `a` (`href`), `link` (`href`, `class`, `current`), `button` (`class`, `pressed`, `on.click`), `toggle`, `checkbox`, `textfield`, `radiogroup`, `radio`, `label`, `status`, `alert` (the full list, with roles and names, is [the primitives](../../docs/use/primitives.md)), plus your components and the built-ins (`blocks`, `block`, `heading`, `list-block`, `list-items`, `runs`, `inline`). The tags `para`, `item` and `quote` are now `paragraph`, `listitem` and `blockquote` (the ARIA names, which the Desktop already used); a template that writes the old one is told the new one. 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).
 
 ## The components
 
@@ -163,20 +173,22 @@ export default defineApp({
 
 ```ts
 // src/theme-toggle.ts: the component states its own interface, where it is defined
-import { component } from "@valancex/common";
+import { component, field } from "@valancex/common";
 import { Schema } from "effect";
 import template from "./theme-toggle.mprx";
 
 export default component(template, {
-  props: { theme: Schema.Literal("light", "dark") },
+  props: { theme: field(Schema.Literal("light", "dark"), "light") },
   events: { toggle: Schema.Void },
 });
 ```
 
 - `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.
+- **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`. A **string-literal union is a closed set**: `Schema.Literal("info", "danger")` becomes the MESH type `"info" | "danger"`, and MESH reports any other literal written for the prop at the use (`unknown-variant`, with a did-you-mean when one is close); a number or boolean literal keeps its primitive type. A prop gets a **default** with `field(schema, value)` (`props: { tone: field(Schema.Literal("info", "danger"), "info") }`): a use of the component that leaves the prop out gets the value, the prop may then be left out, and TypeScript refuses a default that is not a member. A default is for a component with a template; on a primitive it is ignored. A schema with no MESH type, for example a union of a string literal and a number, or a default that is not a value of the prop's type, is a diagnostic at the declaration (`component-schema`). Both need MESH 0.14 or later (`@valancex/mesh-compiler` `^0.14.0`, which the packages depend on). 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-block`, …) with your template of the same name.
+- **One MESH runtime.** `vlx build` (never `vlx dev`) stops with `runtime-duplicate` when the packages resolve more than one copy of `@valancex/mesh-runtime`: each copy is a 765 KB WebAssembly module (171 KB of brotli) that the site would ship and the browser fetch. The message names each copy, its version and who uses it, and says to add an `overrides` entry (npm; `pnpm.overrides`, or `resolutions` with yarn) so there is one. `@valancex/common`, `@valancex/valance` and `@valancex/nexus` accept the same range (`^0.12.0`) so a plain install has one.
+- **One name is one component.** Two registered files with the same name (for example `a/disclosure.mprx` and `b/disclosure.mprx`, whether yours or from two libraries) are `template-duplicate`, and a registered component named like a built-in is `template-builtin` unless it is in `override`: neither silently replaces the other, and the first one listed does not win. Rename one of the files; qualified ids for a library's components (`acme-ui/disclosure`, decision K14) are not built yet. `override` is only for built-ins: for any other name it is `override-unknown`, and the component belongs in `components`.
 - `layout` is optional; without it the built-in layout draws the page. Its template must be named `layout.mprx`.
 
 ### Children and slots
@@ -192,13 +204,38 @@ A component places the content its caller writes inside it with `<mesh-slot />`,
 
 <!-- where it is used -->
 <card>
-  <mesh-fill slot="head"><para class="title">Title</para></mesh-fill>
-  <para class="body">The body goes to the unnamed slot.</para>
+  <mesh-fill slot="head"><paragraph class="title">Title</paragraph></mesh-fill>
+  <paragraph class="body">The body goes to the unnamed slot.</paragraph>
 </card>
 ```
 
 The children are the caller's: `{x}` in them is the caller's `x`, never the card's. `vlx generate component` writes the single, unnamed slot for you. The rules (where a slot may be, what a fill is, the errors) are in MESH's [templates manual](https://github.com/ValanceX/Mesh/blob/main/docs/manual/templates.md#children-and-the-slot).
 
+### Snippets as props
+
+A prop can be a piece of template (MESH 0.14). Declare it with `snippet(…)`, the types of its parameters in order, and read it in the component's template with `{@render name(args)}`:
+
+```
+// src/panel.ts and src/item-list.ts
+component(panel, { props: { title: Schema.String, children: snippet() } });
+component(itemList, { props: { items: Schema.Array(Item), row: snippet(Item, Schema.String) } });
+```
+
+```
+<!-- src/panel.mprx -->
+<section><strong>{title}</strong>{@render children()}</section>
+
+<!-- where they are used: loose content is `children`; a {#snippet} that is a direct child is the prop of its name -->
+<panel title="Totals"><span class="count">{count}</span></panel>
+<item-list items={items} label="row">{#snippet row(item, tag)}<span class="row">{tag}:{item.name}</span>{/snippet}</item-list>
+```
+
+- `children` is reserved for the content between the tags: it must be `snippet()` (no parameters), and `children={…}` with content is `children-conflict`. A snippet is not data: it has no `field` default, is never optional, and is not a record field or an event's payload.
+- A snippet reads the scope of the template that **wrote** it (`count` above is the layout's, not the panel's), so a node that renders one is redrawn when that scope changes though its own props did not.
+- The arity and the types are checked: `snippet-arity-mismatch` in the composite's template when `{@render row(item)}` passes too few, and a member the parameter does not have is reported where the snippet is written.
+- **Optional.** `snippet(…).optional()` (and `children: snippet().optional()`) is one an occurrence may leave out: it is `snippet<…>?` in the model, and an absent one draws nothing. Rendering it is `possibly-absent-snippet` unless it is inside the first branch of an `{#if has(name)}` (`&&` allowed), so `{#if has(header)}{@render header()}{/if}` is how a template uses one.
+- Slots (`mesh-slot`, `mesh-fill`) keep working for a component that does not declare `children`.
+
 ### Typed template imports
 
 `vlx sync` (and `check`, `dev` and `build`) write `.valance/types/<template>.d.mprx.ts`, so a component's declaration is checked against the names its template uses: `component(template, { props: { thme: … } })` is a compile-time error. This needs two options in your `tsconfig.json`:
@@ -229,6 +266,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 +378,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 +389,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/budgets.json

@@ -0,0 +1,175 @@
+{
+  "version": 1,
+  "about": "The ecosystem's budgets, as data (Bet 3; decisions W1 to W24). `project` is what `vlx build` holds an application to when its valance.json sets none (W14). `framework` is what the release check holds the reference applications and the runtime to (scripts/check-budgets.mjs, over the output of scripts/measure-footprint.mjs). Brotli bytes, because that is what travels (W2).",
+  "rule": "A ceiling is the baseline plus 5 percent, rounded up to the next 100 bytes (the next 10 under 1,000), then ratcheted down (W3). A ceiling above that needs `analysis`: the path of a size analysis that says why (W23a), and a decision row. The check refuses a raised ceiling without one.",
+  "project": {
+    "budgets": [
+      {
+        "type": "initial",
+        "warning": 105200,
+        "error": 210400
+      },
+      {
+        "type": "runtime",
+        "error": 192900
+      }
+    ],
+    "note": "W14: the framework's own start-up ceilings. `initial` warns above the largest reference application's JavaScript and CSS ceiling (docs-app) and fails at twice that; `runtime` is the WebAssembly runtime, the same for every application, so a growth of it fails the build of whoever upgrades."
+  },
+  "framework": {
+    "baseline": "docs/direction/baselines/2026-10-24-wp8-before.md",
+    "ceilings": [
+      {
+        "id": "counter.javascript",
+        "what": "Counter application, JavaScript, brotli",
+        "path": "counter.deduped.js.brotli",
+        "unit": "bytes",
+        "baseline": 93722,
+        "ceiling": 98500,
+        "previousCeiling": 92400,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "counter.css",
+        "what": "Counter application, CSS, brotli",
+        "path": "counter.deduped.css.brotli",
+        "unit": "bytes",
+        "baseline": 1053,
+        "ceiling": 1200
+      },
+      {
+        "id": "runtime.wasm",
+        "what": "The WebAssembly runtime, brotli",
+        "path": "counter.deduped.wasm.brotli",
+        "unit": "bytes",
+        "baseline": 183629,
+        "ceiling": 192900,
+        "previousCeiling": 179400,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "counter.transferred",
+        "what": "Counter application, everything the browser transfers, brotli",
+        "path": "browser.deduped.noThrottling.bytesTransferredBrotli",
+        "unit": "bytes",
+        "baseline": 279594,
+        "ceiling": 293600,
+        "previousCeiling": 274100,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "docsApp.javascript",
+        "what": "docs-app, JavaScript, brotli",
+        "path": "docsApp.js.brotli",
+        "unit": "bytes",
+        "baseline": 98520,
+        "ceiling": 103500,
+        "previousCeiling": 97400,
+        "analysis": "docs/direction/evidence/measurement/size-2026-10-24.md"
+      },
+      {
+        "id": "docsApp.css",
+        "what": "docs-app, CSS, brotli",
+        "path": "docsApp.css.brotli",
+        "unit": "bytes",
+        "baseline": 1542,
+        "ceiling": 1700
+      },
+      {
+        "id": "docsApp.perPage",
+        "what": "Client JavaScript each added page costs, raw",
+        "path": "docsApp.perAddedPage.jsRawPerPage",
+        "unit": "bytes",
+        "baseline": 2471.5,
+        "ceiling": 2600,
+        "previousCeiling": 2600
+      },
+      {
+        "id": "counter.heap",
+        "what": "Counter, JavaScript heap after 200 updates",
+        "path": "browser.deduped.noThrottling.afterUpdates.jsHeapUsedBytes",
+        "unit": "bytes",
+        "baseline": 4575160,
+        "ceiling": 4630800,
+        "previousCeiling": 4630800,
+        "note": "W24: the 1,000-update heap gate stays off"
+      },
+      {
+        "id": "counter.wasmMemory",
+        "what": "Counter, WebAssembly memory after 200 updates",
+        "path": "browser.deduped.noThrottling.afterUpdates.wasmMemoryBytes",
+        "unit": "bytes",
+        "baseline": 1310720,
+        "ceiling": 1376300,
+        "previousCeiling": 4885800,
+        "note": "ratcheted down: W21 fixed the growth, the memory is flat"
+      },
+      {
+        "id": "docsApp.wasmMemory",
+        "what": "docs-app, WebAssembly memory after 200 updates",
+        "path": "browser.docsApp.noThrottling.afterUpdates.wasmMemoryBytes",
+        "unit": "bytes",
+        "baseline": 2293760,
+        "ceiling": 2408500
+      }
+    ],
+    "exact": [
+      {
+        "id": "wire.patch",
+        "what": "Bytes a PORT is sent for one changed item of 1,000 rows, as patches",
+        "path": "wire.1000.patchBytes",
+        "unit": "bytes",
+        "max": 202
+      }
+    ],
+    "ratios": [
+      {
+        "id": "counter.interactiveAt",
+        "what": "Counter, time until a click is handled, unthrottled",
+        "path": "browser.deduped.noThrottling.interactiveAtMs",
+        "max": 2
+      },
+      {
+        "id": "counter.interactiveAt4x",
+        "what": "Counter, time until a click is handled, 4x CPU",
+        "path": "browser.deduped.cpu4x.interactiveAtMs",
+        "max": 2
+      },
+      {
+        "id": "counter.firstPaint",
+        "what": "Counter, first paint, unthrottled",
+        "path": "browser.deduped.noThrottling.firstPaintMs",
+        "max": 2
+      },
+      {
+        "id": "update.10000",
+        "what": "`update`, 10,000 items, one changed",
+        "path": "update.10000.updateMs",
+        "max": 1.5
+      },
+      {
+        "id": "updateFromChanges.10000",
+        "what": "`update` from changes, 10,000 items",
+        "path": "update.10000.updateFromChangesMs",
+        "max": 1.5
+      }
+    ],
+    "known": [
+      {
+        "id": "wire.wholeTree",
+        "what": "Bytes a PORT is sent for one changed item of 1,000 rows, whole tree",
+        "path": "wire.1000.wholeTreeBytes",
+        "reason": "the Desktop protocol sends the whole tree on every update; patches are Bet 3's own work item, not WP8",
+        "owner": "unassigned"
+      },
+      {
+        "id": "installability",
+        "what": "The newest published @valancex set, with the release being measured, installs together",
+        "path": "newestInstallsTogether.installs",
+        "expect": true,
+        "reason": "Was red from MESH 0.16 until VALANCE 0.14: NEXUS 0.14 and PORT 0.12 stopped their MESH peer range at 0.15. With --tree the release candidate's own tarballs stand in for the published VALANCE packages, so a release is held to installing beside the newest of the others before it is published (a published VALANCE, the previous release, would gate a release on its predecessor)",
+        "owner": "WP8"
+      }
+    ]
+  }
+}