@valancex/cli 0.12.0 → 0.14.0

package/dist/theme.d.ts

@@ -0,0 +1,35 @@
+import type { Diagnostic } from "./diagnostics.js";
+export declare const THEME_DIR = "theme";
+/** The theme file the project uses: its own `theme/theme.json`, else the default theme's. */
+export declare const themeFileOf: (root: string) => {
+    readonly file: string;
+    readonly custom: boolean;
+};
+export interface ThemeResult {
+    readonly custom: boolean;
+    readonly name: string;
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+    readonly contrast: ReadonlyArray<{
+        readonly mode: string;
+        readonly text: string;
+        readonly on: string;
+        readonly min: number;
+        readonly ratio: number;
+        readonly passes: boolean;
+    }>;
+    /** The stylesheet, when the theme has no problem. */
+    readonly css?: string;
+    /** The theme as the Desktop is told it (resolved values), when the theme has no problem. */
+    readonly desktop?: unknown;
+}
+/** Loads and checks the project's theme. */
+export declare const themeOf: (root: string) => ThemeResult;
+/** What `vlx theme check` says: the theme's problems, the contrast of every pair it declares, and what each target applies of it. */
+export declare const themeReport: (root: string) => {
+    custom: boolean;
+    name: string;
+    modes: string[];
+    diagnostics: Diagnostic[];
+    contrast: readonly import("@valancex/style").ContrastResult[];
+    coverage: import("@valancex/style").Coverage[];
+};

package/dist/theme.js

@@ -0,0 +1,44 @@
+// The project's theme. A project that writes none has the default theme (Tier 1: nothing to do, and every primitive of the portable core is styled); a project that has a `theme/` directory with a
+// `theme.json` (Tier 2) uses it instead, whole: its token documents by mode and its recipes. A recipe's `escape` block (Tier 3) is the marked way to a CSS property outside the contract, for the web.
+// The stylesheet is compiled here, at build time; nothing is computed in the browser.
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { checkTheme, compileWeb, coverageOf, defaultInputs, loadTheme, resolveForDesktop, root as styleRoot } from "@valancex/style";
+import { diagnostic } from "./diagnostics.js";
+export const THEME_DIR = "theme";
+/** The theme file the project uses: its own `theme/theme.json`, else the default theme's. */
+export const themeFileOf = (root) => {
+    const own = join(root, THEME_DIR, "theme.json");
+    return existsSync(own) ? { file: own, custom: true } : { file: join(styleRoot, "themes", "default", "theme.json"), custom: false };
+};
+const asDiagnostic = (each) => diagnostic(each.file, 0, each.code, `${each.path === undefined || each.path === "" ? "" : `${each.path}: `}${each.message}`);
+/** Loads and checks the project's theme. */
+export const themeOf = (root) => {
+    const { file, custom } = themeFileOf(root);
+    const loaded = loadTheme(file, (path) => relative(root, path).split("\\").join("/"));
+    const inputs = defaultInputs();
+    const checked = checkTheme(loaded, inputs);
+    const diagnostics = checked.problems.map(asDiagnostic);
+    return {
+        custom,
+        name: loaded.theme.name,
+        diagnostics,
+        contrast: checked.contrast,
+        ...(diagnostics.length === 0 ? { css: compileWeb(loaded, inputs), desktop: resolveForDesktop(loaded, inputs) } : {}),
+    };
+};
+/** What `vlx theme check` says: the theme's problems, the contrast of every pair it declares, and what each target applies of it. */
+export const themeReport = (root) => {
+    const { file } = themeFileOf(root);
+    const loaded = loadTheme(file, (path) => relative(root, path).split("\\").join("/"));
+    const inputs = defaultInputs();
+    const checked = checkTheme(loaded, inputs);
+    return {
+        custom: themeFileOf(root).custom,
+        name: loaded.theme.name,
+        modes: Object.keys(loaded.modes),
+        diagnostics: checked.problems.map(asDiagnostic),
+        contrast: checked.contrast,
+        coverage: ["web", "desktop"].map((target) => coverageOf(loaded, inputs, target)),
+    };
+};

package/dist/tree.d.ts

@@ -1,5 +1,5 @@
 import type { Schema } from "effect";
-import type { Component } from "@valancex/common";
+import type { Component, PropDeclaration } from "@valancex/common";
 export interface Place {
     readonly file: string;
     readonly line: number;
@@ -12,8 +12,12 @@ export interface Node {
     readonly file: string;
     /** The interface the component declares: present when it declares one (an omitted side is none), absent when its contract is inferred from the template and where it is used. */
     readonly interface?: {
-        readonly props: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+        readonly props: Readonly<Record<string, PropDeclaration>>;
         readonly events: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+        /** The prop that is the component's accessible name, if it declares one. */
+        readonly name?: string;
+        /** The state and commands of one occurrence of the component, if it has any. */
+        readonly unit?: Component["unit"];
     };
     /** The declared components its template writes. */
     readonly uses: ReadonlyArray<string>;
@@ -22,6 +26,14 @@ export interface Node {
 }
 export declare const APPLICATION = "(application)";
 export declare const nameOf: (file: string) => string;
+/** A component as the definition lists it, before two with one name are told apart: how it was listed, and so whether it may replace a built-in. */
+export interface Declared {
+    readonly name: string;
+    readonly file: string;
+    readonly role: "layout" | "override" | "component";
+}
+/** Every component the definition lists, in order and with repeats, each with the role it was listed in. `treeOf` is these, once each by name. */
+export declare const declaredOf: (layout: Component | undefined, overrides: ReadonlyArray<Component>, components?: ReadonlyArray<Component>) => ReadonlyArray<Declared>;
 /** Every component the definition declares, once each by name: `layout`, each `override`, then each of `components`. Who uses whom is read from the templates (`linked`). */
 export declare const treeOf: (layout: Component | undefined, overrides: ReadonlyArray<Component>, components?: ReadonlyArray<Component>) => ReadonlyArray<Node>;
 /**

package/dist/tree.js

@@ -5,13 +5,28 @@ import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { ENTRY_FILE } from "./project.js";
 export const APPLICATION = "(application)";
 export const nameOf = (file) => basename(file, ".mprx");
+/** Every component the definition lists, in order and with repeats, each with the role it was listed in. `treeOf` is these, once each by name. */
+export const declaredOf = (layout, overrides, components = []) => [
+    ...(layout === undefined ? [] : [{ component: layout, role: "layout" }]),
+    ...overrides.map((component) => ({ component, role: "override" })),
+    ...components.map((component) => ({ component, role: "component" })),
+].map(({ component, role }) => ({ name: nameOf(component.template.mprx), file: component.template.mprx, role }));
 /** Every component the definition declares, once each by name: `layout`, each `override`, then each of `components`. Who uses whom is read from the templates (`linked`). */
 export const treeOf = (layout, overrides, components = []) => {
     const found = new Map();
     for (const declared of [...(layout === undefined ? [] : [layout]), ...overrides, ...components]) {
         const name = nameOf(declared.template.mprx);
         if (!found.has(name)) {
-            const contract = declared.props === undefined && declared.events === undefined ? {} : { interface: { props: declared.props ?? {}, events: declared.events ?? {} } };
+            const contract = declared.props === undefined && declared.events === undefined && declared.unit === undefined
+                ? {}
+                : {
+                    interface: {
+                        props: declared.props ?? {},
+                        events: declared.events ?? {},
+                        ...(declared.name === undefined ? {} : { name: declared.name }),
+                        ...(declared.unit === undefined ? {} : { unit: declared.unit }),
+                    },
+                };
             found.set(name, { name, file: declared.template.mprx, ...contract, uses: [], parents: [] });
         }
     }

package/dist/ui/init.js

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

package/dist/ui/report.js

@@ -26,5 +26,5 @@ export const BuildProgress = ({ current }) => {
     const at = current === undefined ? STAGES.length : STAGES.findIndex((each) => each.stage === current);
     return (_jsx(Box, { flexDirection: "column", children: STAGES.map(({ stage, label }, index) => index > at ? (_jsxs(Text, { dimColor: true, children: ["\u25CB ", label] }, stage)) : index === at ? (_jsxs(Text, { children: [_jsx(Spinner, {}), " ", label] }, stage)) : (_jsxs(Text, { children: [_jsx(Text, { color: "green", children: "\u2714" }), " ", label] }, stage))) }));
 };
-export const BuildResult = ({ built, seconds }) => (_jsxs(Box, { flexDirection: "column", children: [_jsx(BuildProgress, { current: undefined }), _jsxs(Text, { children: [_jsxs(Text, { color: "green", bold: true, children: ["\u2714 Built ", plural(built.pages.length, "page")] }), _jsxs(Text, { dimColor: true, children: [" ", "\u00B7 ", plural(built.files.length, "file"), " \u2192 ", built.dir, " \u00B7 ", seconds.toFixed(1), "s"] })] })] }));
+export const BuildResult = ({ built, seconds }) => (_jsxs(Box, { flexDirection: "column", children: [_jsx(BuildProgress, { current: undefined }), _jsxs(Text, { children: [_jsxs(Text, { color: "green", bold: true, children: ["\u2714 Built ", plural(built.pages.length, "page")] }), _jsxs(Text, { dimColor: true, children: [" ", "\u00B7 ", plural(built.files.length, "file"), " \u2192 ", built.dir, " \u00B7 ", seconds.toFixed(1), "s"] })] }), (built.report ?? []).map((line, index) => (_jsx(Text, { dimColor: !/WARNING|ERROR/.test(line), ...(/WARNING/.test(line) ? { color: "yellow" } : /ERROR/.test(line) ? { color: "red" } : {}), children: line }, index)))] }));
 export const DevScreen = ({ state }) => (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "cyan", children: "vlx dev" }), state.starting ? (_jsxs(Text, { children: ["  ", _jsx(Spinner, {}), " starting"] })) : (_jsxs(Text, { children: ["  ", _jsx(Text, { color: "green", children: "\u25CF" }), " ", state.url] }))] }), state.open.length === 0 ? (state.starting ? null : (_jsx(Text, { color: "green", children: "\u2714 No problems" }))) : (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Diagnostics, { diagnostics: state.open }), _jsxs(Text, { color: "red", children: ["\u2716 ", plural(state.open.length, "problem"), ": fix and save; the last good build keeps serving"] })] })), state.lines.length === 0 ? null : (_jsx(Box, { flexDirection: "column", marginTop: 1, children: state.lines.map((line, index) => (_jsx(Text, { dimColor: true, children: line }, `${index}:${line}`))) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "Ctrl+C to stop" }) })] }));

package/dist/ui/run.d.ts

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

package/dist/ui/run.js

@@ -1,5 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// Putting the views on the terminal. Ink and React are loaded only here, and only when a command is going to draw: a command that prints plain text never pays for them.
 import { render } from "ink";
 import { build as runBuild } from "../build.js";
 import { check as runCheck } from "../check.js";
@@ -33,14 +32,30 @@ export const drawCheck = async (root) => {
         await shown.waitUntilExit();
     }
 };
-export const drawBuild = async (root) => {
+export const drawBuild = async (root, targets = []) => {
     const started = Date.now();
     const shown = show(_jsx(BuildProgress, { current: "configuration" }));
+    let measured = [];
     try {
-        const built = await runBuild(root, { onStage: ((stage) => shown.rerender(_jsx(BuildProgress, { current: stage }))) });
+        const built = await runBuild(root, {
+            ...(targets.length === 0 ? {} : { targets }),
+            onReport: (report) => {
+                measured = report;
+            },
+            onStage: ((stage) => shown.rerender(_jsx(BuildProgress, { current: stage }))),
+        });
         shown.rerender(_jsx(BuildResult, { built: built, seconds: (Date.now() - started) / 1000 }));
         return built;
     }
+    catch (error) {
+        // A budget error stops the build after the bundle is measured: the report says by how much.
+        if (measured.length > 0) {
+            shown.unmount();
+            await shown.waitUntilExit();
+            measured.forEach((line) => console.error(line));
+        }
+        throw error;
+    }
     finally {
         shown.unmount();
         await shown.waitUntilExit();

package/dist/vite.d.ts

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

package/dist/vite.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/cli",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "vlx, the VALANCE command: make an application (vlx init), serve it as you edit (vlx dev), build it to a static site (vlx build), check it (vlx check). Content, layout, components and styles in, a website out.",
   "keywords": [
     "valance",
@@ -40,6 +40,7 @@
     "dist",
     "bin",
     "views",
+    "views-desktop",
     "schemas",
     "templates"
   ],
@@ -48,25 +49,32 @@
     "provenance": true
   },
   "dependencies": {
-    "@valancex/mesh-compiler": "^0.11.0",
+    "@valancex/mesh-compiler": "^0.15.0 || ^0.16.0 || ^0.17.0",
+    "@valancex/port-desktop-vocabulary": "^0.12.0 || ^0.13.0 || ^0.14.0",
     "effect": "^3.10.0",
     "ink": "7.1.1",
+    "postject": "1.0.0-alpha.6",
     "react": "19.2.8",
     "vite": "7.3.6",
-    "@valancex/common": "^0.12.0",
-    "@valancex/valance": "^0.12.0"
+    "@valancex/style": "^0.14.0",
+    "@valancex/valance": "^0.14.0",
+    "@valancex/common": "^0.14.0"
   },
   "devDependencies": {
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^22.0.0",
     "@types/react": "19.2.18",
-    "@valancex/mesh-runtime": "^0.11.0",
+    "@valancex/mesh-runtime": "^0.17.0",
+    "dom-accessibility-api": "^0.7.0",
     "ink-testing-library": "4.0.0",
+    "jsdom": "^26.0.0",
     "playwright": "1.56.1",
     "typescript": "^5.6.0",
-    "vitest": "^3.2.0"
+    "vitest": "^3.2.0",
+    "vnu-jar": "^26.10.12"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/copy-data.mjs",
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "test": "vitest run"
   }

package/schemas/valance.desktop.schema.json

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

package/schemas/valance.schema.json

@@ -27,6 +27,77 @@
       "pattern": "^[^{}]*(\\{page\\}|\\{site\\})[^{}]*(\\{page\\}|\\{site\\}|[^{}])*$",
       "maxLength": 120,
       "description": "How a document's title is written: \"{page}\" is the page's title and \"{site}\" the name above. Must contain \"{page}\". A page whose title is the site's name is that name alone."
+    },
+    "record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "redact"
+      ],
+      "description": "What `vlx dev --record` leaves out of a session log. A log holds what was typed and seen; a value marked here is never written (its place holds a digest) and the log still replays.",
+      "properties": {
+        "redact": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "scope": {
+              "type": "array",
+              "description": "Paths into the page's scope whose values are replaced by a digest; \"*\" is any list index or field name.",
+              "items": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            "commands": {
+              "type": "array",
+              "description": "Commands (\"component/name\") whose parameters are not recorded.",
+              "items": {
+                "type": "string",
+                "pattern": "^[\\w-]+/[\\w-]+$"
+              }
+            }
+          }
+        }
+      }
+    },
+    "budgets": {
+      "type": "array",
+      "description": "The size budgets `vlx build` holds the production build to (never `vlx dev`). A type, a warning and an error threshold in bytes: 500000, \"500kB\" or \"1MB\" (1 kB is 1,000 bytes). With none, the framework's start-up budgets apply.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "type": {
+            "enum": [
+              "initial",
+              "runtime",
+              "startup",
+              "afterStart",
+              "anyChunk"
+            ],
+            "description": "initial: the start-up JavaScript and CSS; runtime: the WebAssembly runtime; startup: the whole start-up set; afterStart: what loads once the application runs; anyChunk: the largest JavaScript chunk. Brotli bytes."
+          },
+          "warning": {
+            "type": [
+              "string",
+              "number"
+            ]
+          },
+          "error": {
+            "type": [
+              "string",
+              "number"
+            ]
+          }
+        }
+      }
     }
   }
 }

package/templates/desktop/README.md

@@ -0,0 +1,14 @@
+# {{name}}
+
+A VALANCE application for the desktop, made with `vlx init --desktop`.
+
+```console
+$ {{run}} dev      # open the window, and update it as you edit
+$ {{run}} build    # write the engine to dist/desktop/
+$ {{run}} check    # find mistakes in your files without building
+```
+
+- `content/` is Markdown: a page's path is its address.
+- `src/layout.mprx` is the window around a page; `src/main.ts` declares it, the state and the commands.
+- `valance.desktop.json` marks the project as a desktop one; `valance.json` names the application.
+- The window is the Desktop PORT's (`valancex-port-desktop`); `vlx build` writes the engine it runs, `dist/desktop/engine.mjs`.

package/templates/desktop/content/404.md

@@ -0,0 +1,7 @@
+---
+title: Not found
+---
+
+# Not found
+
+There is no page at that address. Go back to the [first page](/).

package/templates/desktop/content/guide/getting-started.md

@@ -0,0 +1,15 @@
+---
+title: Getting started
+description: Create the project, run it, change a page.
+order: 1
+---
+
+# Getting started
+
+Edit `content/index.md` and save: the window shows it.
+
+> A link is an address. In a window, following one is the application's own navigation, the same command the web uses.
+
+1. Add a page: a Markdown file under `content/`.
+2. Change the window: `src/layout.mprx`, with the components `column`, `row`, `heading`, `text`, `button`, `checkbox` and `textfield`.
+3. Add state or a command: `src/main.ts`.

package/templates/desktop/content/index.md

@@ -0,0 +1,14 @@
+---
+title: {{name}}
+description: A desktop application, written the way a VALANCE application is written.
+---
+
+# {{name}}
+
+This is a **VALANCE application** in a window. Everything you are reading is a Markdown file in `content/`; the window around it is `src/layout.mprx`.
+
+- Pages are Markdown files. Their path is their address.
+- The layout is a template, drawn with the Desktop PORT's components.
+- `vlx dev` opens the window and updates it as you edit.
+
+Start with [Getting started](/guide/getting-started).

package/templates/desktop/gitignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.valance
+# session recordings (vlx dev --record) hold what was typed: never commit them
+.valance/sessions/
+*.session.jsonl
+.work*

package/templates/desktop/src/layout.mprx

@@ -0,0 +1,23 @@
+<column>
+  <row>
+    <button disabled={!canGoBack} on.click={back()}>Back</button>
+    <button disabled={!canGoForward} on.click={forward()}>Forward</button>
+    <link href={home}>{site}</link>
+    <button on.click={toggleNavigation()}>{#if navigation}Hide pages{:else}Show pages{/if}</button>
+  </row>
+  {#if navigation}
+    {#each sections as s (s.id)}
+      <column>
+        {#if s.title != ""}<text>{s.title}</text>{/if}
+        <list ordered={false}>
+          {#each s.items as n (n.id)}<listitem><link href={n.href}>{n.label}</link></listitem>{/each}
+        </list>
+      </column>
+    {/each}
+  {/if}
+  <blocks items={blocks} />
+  <row>
+    {#if prev.href != ""}<link href={prev.href}>{prev.label}</link>{/if}
+    {#if next.href != ""}<link href={next.href}>{next.label}</link>{/if}
+  </row>
+</column>

package/templates/desktop/src/main.ts

@@ -0,0 +1,15 @@
+import { component, defineApp, field } from "@valancex/common";
+import { Schema } from "effect";
+import layout from "./layout.mprx";
+
+// The application, from the top. `layout` is the window's content around a page; the Markdown in content/ is what goes in `<blocks>`. The state is the application's own, beyond "which page is
+// shown": each field is its type and its default, together. A field is a name the layout can read (`navigation`), and the commands below are names it can run (`toggleNavigation()`).
+export default defineApp({
+  layout: component(layout),
+  state: {
+    navigation: field(Schema.Boolean, true),
+  },
+  commands: (command) => ({
+    toggleNavigation: command((state) => ({ ...state, navigation: !state.navigation })),
+  }),
+});

package/templates/desktop/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "allowArbitraryExtensions": true,
+    "rootDirs": ["src", ".valance/types"]
+  },
+  "include": ["src"]
+}

package/templates/multi/README.md

@@ -0,0 +1,13 @@
+# {{name}}
+
+A VALANCE application for the web and the desktop, made with `vlx init --web --desktop`.
+
+```console
+$ {{run}} dev -- --web       # serve the site (--desktop opens the window instead)
+$ {{run}} build              # build every target: dist/web/ and dist/desktop/
+$ {{run}} check              # find mistakes in your files, for every target
+```
+
+- `content/` is Markdown, and the state and commands in `src/main.ts` are the application's: the same on every target.
+- Each target has its own templates, because each draws with its own vocabulary: `src/web/` and `src/desktop/`. `src/main.ts` says which is whose (`targets`).
+- `valance.web.json` and `valance.desktop.json` say which targets the project has; `valance.json` names the application.

package/templates/multi/content/404.md

@@ -0,0 +1,7 @@
+---
+title: Not found
+---
+
+# Not found
+
+There is no page at that address. Go back to the [first page](/).

package/templates/multi/content/guide/getting-started.md

@@ -0,0 +1,15 @@
+---
+title: Getting started
+description: Create the project, run it, change a page.
+order: 1
+---
+
+# Getting started
+
+Edit `content/index.md` and save: the window shows it.
+
+> A link is an address. In a window, following one is the application's own navigation, the same command the web uses.
+
+1. Add a page: a Markdown file under `content/`.
+2. Change the window: `src/layout.mprx`, with the components `column`, `row`, `heading`, `text`, `button`, `checkbox` and `textfield`.
+3. Add state or a command: `src/main.ts`.

package/templates/multi/content/index.md

@@ -0,0 +1,14 @@
+---
+title: {{name}}
+description: A desktop application, written the way a VALANCE application is written.
+---
+
+# {{name}}
+
+This is a **VALANCE application** in a window. Everything you are reading is a Markdown file in `content/`; the window around it is `src/layout.mprx`.
+
+- Pages are Markdown files. Their path is their address.
+- The layout is a template, drawn with the Desktop PORT's components.
+- `vlx dev --desktop` opens the window and updates it as you edit.
+
+Start with [Getting started](/guide/getting-started).