@valancex/cli 0.11.0 → 0.13.0

package/dist/package.js

@@ -0,0 +1,141 @@
+// `vlx package`: the desktop target as something to hand to a person. The engine becomes one executable (Node's single executable application: the engine bundled to one file, with the MESH
+// runtime's module inside as an asset, injected into a `node` binary), set beside the Desktop PORT's window program. Unsigned: signing and notarizing are not done here (the artifacts say so).
+import { build as bundle } from "vite";
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, join } from "node:path";
+import { checksums, tarGz, zip } from "./archive.js";
+import { loadAuthor } from "./author.js";
+import { build } from "./build.js";
+import { loadConfig } from "./config.js";
+import { AppError } from "./diagnostics.js";
+import { hasEntry } from "./emit.js";
+import { ENTRY_FILE, GENERATED_DIR, OUTPUT_DIR } from "./project.js";
+import { programFile } from "./emit.js";
+import { createLoader, templates } from "./vite.js";
+export const PLATFORMS = ["linux-x64", "win32-x64"];
+const hostPlatform = () => `${process.platform}-${process.arch}`;
+const fail = (message) => {
+    throw new AppError([{ file: "valance.desktop.json", line: 0, column: 0, code: "package", message }]);
+};
+/** A program on the PATH, as the shell would find it. */
+const onPath = (name) => (process.env["PATH"] ?? "")
+    .split(delimiter)
+    .map((dir) => join(dir, name))
+    .find((candidate) => existsSync(candidate));
+/** The entry of the packaged engine: the generated desktop entry, with the MESH runtime's module read from the executable's own assets (a single file has nothing beside it). */
+const seaSource = (root, config) => `// Generated by \`vlx package\`. Do not edit.
+// @ts-nocheck
+import { getRawAsset } from "node:sea";
+import { dirname, join } from "node:path";
+import { start } from "@valancex/common/desktop";
+import content from "./content.json";
+import program from "./${programFile(config, "desktop")}";
+${hasEntry(root) ? `import author from "../${ENTRY_FILE}";\n` : "const author = undefined;\n"}
+const wasm = new Uint8Array(getRawAsset("mesh-runtime.wasm"));
+
+// the project's public/ files sit beside the executable
+const assets = join(dirname(process.execPath), "public");
+
+start({ content, program, author, wasm, assets }).then(
+  () => process.exit(0),
+  (error) => {
+    console.error("the engine stopped:", error);
+    process.exit(1);
+  },
+);
+`;
+/** Every file under `dir` as an archive entry inside `top/`, in a stable order (a program keeps its executable bit). */
+const entriesOf = (dir, top, at = "") => readdirSync(join(dir, at))
+    .sort()
+    .flatMap((name) => {
+    const relative = at === "" ? name : `${at}/${name}`;
+    const file = join(dir, relative);
+    return statSync(file).isDirectory()
+        ? entriesOf(dir, top, relative)
+        : [{ path: `${top}/${relative}`, data: readFileSync(file), mode: statSync(file).mode & 0o111 ? 0o755 : 0o644 }];
+});
+export const packageDesktop = async (root, options = {}) => {
+    const config = loadConfig(root);
+    if (!config.targets.includes("desktop")) {
+        return fail("this project has no desktop target (vlx generate target desktop)");
+    }
+    const platform = options.platform ?? hostPlatform();
+    if (!PLATFORMS.includes(platform)) {
+        return fail(`cannot package for ${platform}: the platforms are ${PLATFORMS.join(", ")}`);
+    }
+    const windows = platform.startsWith("win32");
+    const node = options.node ?? (platform === hostPlatform() ? process.execPath : undefined);
+    const window = options.window ?? process.env["VLX_WINDOW"] ?? onPath(windows ? "vlx-window.exe" : "vlx-window");
+    if (node === undefined) {
+        return fail(`packaging for ${platform} from ${hostPlatform()} needs a node binary of this version for ${platform}: --node <path>`);
+    }
+    if (window === undefined || !existsSync(window)) {
+        return fail(`no window program: build it from the PORT repository (cargo build --release --bin vlx-window) and give its path with --window <path> (or set VLX_WINDOW)`);
+    }
+    // The engine, built first: the content, the program and the entries are the project's as they are now.
+    await build(root, { targets: ["desktop"] });
+    const work = join(root, GENERATED_DIR, "package");
+    rmSync(work, { recursive: true, force: true });
+    mkdirSync(work, { recursive: true });
+    writeFileSync(join(root, GENERATED_DIR, "desktop.sea.ts"), seaSource(root, config));
+    // Loading the author's definition once checks it still loads; the bundle below is the one that ships.
+    const loader = await createLoader(root, config);
+    try {
+        await loadAuthor(loader, root);
+    }
+    finally {
+        await loader.close();
+    }
+    await bundle({
+        root,
+        configFile: false,
+        publicDir: false,
+        logLevel: "warn",
+        plugins: [templates(root)],
+        cacheDir: join(root, GENERATED_DIR, "cache"),
+        ssr: { noExternal: true, target: "node" },
+        build: {
+            ssr: join(root, GENERATED_DIR, "desktop.sea.ts"),
+            outDir: work,
+            emptyOutDir: false,
+            target: "node22",
+            minify: false,
+            chunkSizeWarningLimit: 4000,
+            rollupOptions: { output: { format: "cjs", entryFileNames: "engine.cjs" } },
+        },
+    });
+    const wasm = createRequire(createRequire(join(root, "package.json")).resolve("@valancex/common/package.json")).resolve("@valancex/mesh-runtime/mesh-runtime.wasm");
+    writeFileSync(join(work, "sea-config.json"), JSON.stringify({ main: join(work, "engine.cjs"), output: join(work, "engine.blob"), disableExperimentalSEAWarning: true, assets: { "mesh-runtime.wasm": wasm } }));
+    execFileSync(process.execPath, ["--experimental-sea-config", join(work, "sea-config.json")], { stdio: "pipe" });
+    const out = join(root, OUTPUT_DIR, "package", platform);
+    rmSync(out, { recursive: true, force: true });
+    mkdirSync(out, { recursive: true });
+    const engine = join(out, windows ? "vlx-engine.exe" : "vlx-engine");
+    const app = join(out, `${config.name.replace(/[^\w.-]+/g, "-")}${windows ? ".exe" : ""}`);
+    copyFileSync(node, engine);
+    chmodSync(engine, 0o755);
+    const injector = "postject"; // (no type declarations of its own)
+    const { inject } = (await import(injector));
+    await inject(engine, "NODE_SEA_BLOB", readFileSync(join(work, "engine.blob")), { sentinelFuse: "NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2" });
+    copyFileSync(window, app);
+    chmodSync(app, 0o755);
+    // The files images are drawn from, beside the engine.
+    const publicDir = join(root, "public");
+    if (existsSync(publicDir)) {
+        cpSync(publicDir, join(out, "public"), { recursive: true });
+    }
+    const files = [engine, app].map((file) => file.slice(out.length + 1));
+    const notes = ["unsigned: macOS notarization and Windows signing are not done here; an unsigned program draws a warning on first run"];
+    if (options.archive === true) {
+        const stem = `${config.name.replace(/[^\w.-]+/g, "-")}-${platform}`;
+        const archive = `${stem}.${windows ? "zip" : "tar.gz"}`;
+        const data = (windows ? zip : tarGz)(entriesOf(out, stem));
+        writeFileSync(join(root, OUTPUT_DIR, "package", archive), data);
+        writeFileSync(join(root, OUTPUT_DIR, "package", `${archive}.sha256`), checksums([{ name: archive, data }]));
+        files.push(`../${archive}`, `../${archive}.sha256`);
+        notes.push(`${archive} is the package as one file, with its SHA-256 beside it; the checksum says the file is the one that was made, not who made it (that is what signing is for)`);
+    }
+    return { dir: out, files, notes };
+};

package/dist/project.js

@@ -1,4 +1,4 @@
-// Where things are in a project. Authored: `valance.json`, `valance.web.json`, `content/`, `public/`, `src/`. Generated and never edited or committed: `.valance/`. The final site: `dist/`.
+// Where things are in a project. Authored: `valance.json`, `valance.web.json`, `content/`, `public/`, `src/`. Generated and never edited or committed: `.valance/`. The final site: `dist/web/`.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 export const GENERATED_DIR = ".valance";

package/dist/security.d.ts

@@ -0,0 +1,4 @@
+import type { Config } from "./config.js";
+export declare const contentSecurityPolicy: (config: Config) => string;
+/** The header lines, for every path under the site's base. */
+export declare const headersFile: (config: Config) => string;

package/dist/security.js

@@ -0,0 +1,35 @@
+/** The origin of the backend when `api.base` is an absolute address (the page may connect to it), else nothing: a path is the page's own origin. */
+const apiOrigin = (config) => {
+    try {
+        return new URL(config.api.base).origin;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const contentSecurityPolicy = (config) => {
+    const origin = apiOrigin(config);
+    return [
+        "default-src 'self'",
+        "script-src 'self' 'wasm-unsafe-eval'",
+        "style-src 'self'",
+        "img-src 'self' data:",
+        `connect-src 'self'${origin === undefined ? "" : ` ${origin}`}`,
+        "font-src 'self'",
+        "base-uri 'none'",
+        "form-action 'self'",
+        "frame-ancestors 'none'",
+        "object-src 'none'",
+    ].join("; ");
+};
+/** The header lines, for every path under the site's base. */
+export const headersFile = (config) => {
+    const lines = [
+        `Content-Security-Policy: ${contentSecurityPolicy(config)}`,
+        "X-Content-Type-Options: nosniff",
+        "Referrer-Policy: strict-origin-when-cross-origin",
+        "Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()",
+        "Cross-Origin-Opener-Policy: same-origin",
+    ];
+    return `# Written by vlx build. Serve these headers with the site (Netlify and Cloudflare Pages read this file; copy the lines to any other host's configuration).\n# Turn it off with "headers": false in valance.web.json.\n${config.web.base}*\n${lines.map((line) => `  ${line}`).join("\n")}\n`;
+};

package/dist/targets.d.ts

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

package/dist/targets.js

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

package/dist/ui/init.js

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

package/dist/ui/run.d.ts

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

package/dist/ui/run.js

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

package/dist/vite.d.ts

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

package/dist/vite.js

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

package/package.json

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

package/schemas/valance.desktop.schema.json

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

package/schemas/valance.schema.json

@@ -5,10 +5,28 @@
   "description": "The project: what the application is called. Settings for a target are in valance.<target>.json (valance.web.json for the web).",
   "type": "object",
   "additionalProperties": false,
-  "required": ["name"],
+  "required": [
+    "name"
+  ],
   "properties": {
-    "$schema": { "type": "string" },
-    "version": { "const": 1, "description": "The version of this file's format." },
-    "name": { "type": "string", "minLength": 1, "description": "The application's name: the site's title in navigation and in every page's <title>." }
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "The version of this file's format."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The application's name: the site's title in navigation and in every page's <title>."
+    },
+    "title": {
+      "type": "string",
+      "default": "{page} \u00b7 {site}",
+      "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."
+    }
   }
 }

package/schemas/valance.web.schema.json

@@ -6,9 +6,51 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "$schema": { "type": "string" },
-    "version": { "const": 1, "description": "The version of this file's format." },
-    "base": { "type": "string", "pattern": "^/([\\w.~-]+/)*$", "default": "/", "description": "The path the site is served under: \"/\" or \"/docs/\". Every address the build writes is under it." },
-    "url": { "type": "string", "pattern": "^https?://.*[^/]$", "description": "Where the site is published, without a trailing slash. With it, pages get canonical links and the build writes sitemap.xml." }
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "The version of this file's format."
+    },
+    "base": {
+      "type": "string",
+      "pattern": "^/([\\w.~-]+/)*$",
+      "default": "/",
+      "description": "The path the site is served under: \"/\" or \"/docs/\". Every address the build writes is under it."
+    },
+    "url": {
+      "type": "string",
+      "pattern": "^https?://.*[^/]$",
+      "description": "Where the site is published, without a trailing slash. With it, pages get canonical links and the build writes sitemap.xml."
+    },
+    "headers": {
+      "type": "boolean",
+      "default": true,
+      "description": "Write the recommended security headers (a strict Content-Security-Policy and others) as _headers beside the built site."
+    },
+    "announce": {
+      "type": "boolean",
+      "default": true,
+      "description": "After the application changes page in place, tell assistive technology: say the new title in a live region and focus the main content."
+    },
+    "api": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "base"
+      ],
+      "description": "The application's backend.",
+      "properties": {
+        "base": {
+          "type": "string",
+          "description": "Where its requests go: a path on the site's own origin (\"/api\") or an absolute https address (\"https://api.example.com\", which the Content-Security-Policy then allows)."
+        },
+        "proxy": {
+          "type": "string",
+          "description": "For vlx dev: forward requests under a path \"base\" to this address (\"http://localhost:3000\"), so the browser sees one origin and no CORS settings are needed."
+        }
+      }
+    }
   }
 }

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,4 @@
+node_modules
+dist
+.valance
+.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"]
+}