@valancex/cli 0.11.0 → 0.12.0

package/README.md

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

package/dist/build.js

@@ -5,6 +5,7 @@ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { loadAuthor } from "./author.js";
 import { loadConfig } from "./config.js";
+import { headersFile } from "./security.js";
 import { AppError } from "./diagnostics.js";
 import { generateContent, generateEntries, generateProgram } from "./emit.js";
 import { OUTPUT_DIR } from "./project.js";
@@ -62,6 +63,10 @@ export const build = async (root, options = {}) => {
         if (config.web.url !== "") {
             write("sitemap.xml", sitemap(content));
         }
+        // The headers to serve it with: the page is only as safe as the host makes it (src/security.ts).
+        if (config.web.headers) {
+            write("_headers", headersFile(config));
+        }
         return { dir: dist, files, pages };
     }
     finally {

package/dist/compile.d.ts

@@ -1,6 +1,7 @@
 import type * as Valance from "@valancex/valance";
 import type { DefinedApp } from "@valancex/common";
 import type { Node } from "./tree.js";
+import type { Vocabulary } from "@valancex/common/internal";
 export declare const SOURCE_DIR = "src";
 /** The component the page is drawn by. */
 export declare const ROOT = "layout";
@@ -23,8 +24,8 @@ export interface Templates {
  * Built-in templates, then the author's. The author's are exactly the ones `src/main.ts` declares: `layout`, `components` and `override`. A file under `src/` that is not declared is an error, not
  * a guess; a registered component that no template writes is allowed (it is not part of the program until one does). Which components a template uses is read from the template. A name that is a built-in's replaces it only through `override`.
  */
-export declare const templatesOf: (root: string, author: DefinedApp | undefined) => Templates;
-export declare const manifestOf: (author: DefinedApp | undefined) => import("@valancex/valance/web/build").Manifest;
+export declare const templatesOf: (root: string, author: DefinedApp | undefined, vocabulary?: Vocabulary) => Templates;
+export declare const manifestOf: (author: DefinedApp | undefined, vocabulary?: Vocabulary) => import("@valancex/valance/web/build").Manifest;
 export interface Compiled {
     readonly program: Valance.Program;
     /**
@@ -46,6 +47,6 @@ export interface Compiled {
         readonly builtIn: boolean;
     }>;
 }
-/** Compiles the application's templates. Fails with every diagnostic, each pointing into the file it is about. */
-export declare const compileViews: (root: string, author: DefinedApp | undefined) => Promise<Compiled>;
+/** Compiles the application's templates against a target's vocabulary (the web's by default). Fails with every diagnostic, each pointing into the file it is about. */
+export declare const compileViews: (root: string, author: DefinedApp | undefined, vocabulary?: Vocabulary) => Promise<Compiled>;
 export {};

package/dist/compile.js

@@ -12,7 +12,7 @@ import { declarationsOf, linked, nameOf, treeOf } from "./tree.js";
 import { tagsOf } from "./outline.js";
 import { entryOf } from "./contract.js";
 import { locateKey } from "./wiring.js";
-import { primitives } from "@valancex/common/internal";
+import { webVocabulary } from "@valancex/common/internal";
 import { ENTRY_FILE } from "./project.js";
 export const SOURCE_DIR = "src";
 /** The component the page is drawn by. */
@@ -37,7 +37,7 @@ const entryText = (root) => {
  * Built-in templates, then the author's. The author's are exactly the ones `src/main.ts` declares: `layout`, `components` and `override`. A file under `src/` that is not declared is an error, not
  * a guess; a registered component that no template writes is allowed (it is not part of the program until one does). Which components a template uses is read from the template. A name that is a built-in's replaces it only through `override`.
  */
-export const templatesOf = (root, author) => {
+export const templatesOf = (root, author, vocabulary = webVocabulary) => {
     const found = new Map();
     for (const file of mprxIn(BUILT_IN)) {
         const component = basename(file, ".mprx");
@@ -77,7 +77,7 @@ export const templatesOf = (root, author) => {
             problem(place, "template-duplicate", `${files.get(node.name)} is also <${node.name}>: a component is named by its file, so the name must be unique`);
             continue;
         }
-        if (node.name in primitives) {
+        if (node.name in vocabulary.tags) {
             problem(place, "template-primitive", `<${node.name}> is already a tag the framework draws as an element; name the file something else`);
             continue;
         }
@@ -124,8 +124,8 @@ const reachable = (all) => {
     }
     return all.filter((template) => seen.has(template.component));
 };
-export const manifestOf = (author) => manifest({
-    primitives,
+export const manifestOf = (author, vocabulary = webVocabulary) => manifest({
+    primitives: vocabulary.tags,
     scopes: { [ROOT]: scopeSchema(author) },
     commands: commandTable(author),
 });
@@ -136,12 +136,12 @@ const isManifestError = (error) => error instanceof Error && error._tag === "Man
  * uses. MESH checks every use against it (an undeclared prop, a missing one, a wrong type, an undeclared event in a handler), at the use or in the template. A schema with no model type is a
  * diagnostic at the declaration, not a crash.
  */
-const modelOf = (root, author, tree) => {
+const modelOf = (root, author, tree, vocabulary) => {
     const problems = [];
     const mainText = entryText(root);
     let derived;
     try {
-        derived = manifestOf(author);
+        derived = manifestOf(author, vocabulary);
     }
     catch (error) {
         if (!isManifestError(error)) {
@@ -171,11 +171,11 @@ const modelOf = (root, author, tree) => {
     }
     return { ...derived, components: { ...derived.components, ...entries } };
 };
-/** Compiles the application's templates. Fails with every diagnostic, each pointing into the file it is about. */
-export const compileViews = async (root, author) => {
-    const { all, tree } = templatesOf(root, author);
+/** Compiles the application's templates against a target's vocabulary (the web's by default). Fails with every diagnostic, each pointing into the file it is about. */
+export const compileViews = async (root, author, vocabulary = webVocabulary) => {
+    const { all, tree } = templatesOf(root, author, vocabulary);
     const used = reachable(all);
-    const model = modelOf(root, author, tree);
+    const model = modelOf(root, author, tree, vocabulary);
     if (!used.some((template) => template.component === ROOT)) {
         throw new AppError([diagnostic(`${SOURCE_DIR}/${ROOT}.mprx`, 0, "layout-missing", "there is no layout")]);
     }

package/dist/config.d.ts

@@ -5,9 +5,20 @@ export declare const WEB_FILE = "valance.web.json";
 export declare const CONFIG_VERSION = 1;
 export interface Config {
     readonly name: string;
+    /** How the document's title is written from a page's title and the site's name: `{page}` and `{site}`. */
+    readonly title: string;
     readonly web: {
         readonly base: string;
         readonly url: string;
+        /** Write the security headers file beside the built site. */
+        readonly headers: boolean;
+        /** Announce a page change made in place to assistive technology. */
+        readonly announce: boolean;
+    };
+    /** The application's backend: the address its requests are made to (a path on the site's own origin, or an absolute https address), and, for `vlx dev`, where a path is proxied to. */
+    readonly api: {
+        readonly base: string;
+        readonly proxy: string;
     };
 }
 /** Reads and validates the project's configuration. Every problem in both files is reported together. */

package/dist/config.js

@@ -4,6 +4,7 @@
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { AppError, diagnostic, lineOf } from "./diagnostics.js";
+import { DEFAULT_TITLE } from "@valancex/common/internal";
 export const PROJECT_FILE = "valance.json";
 export const WEB_FILE = "valance.web.json";
 /** The only version of both files there is. */
@@ -60,6 +61,35 @@ const url = (value) => {
         return "must be an absolute address such as https://example.com";
     }
 };
+const title = (value) => typeof value === "string" && value.includes("{page}") && value.length <= 120 && !/[{}]/.test(value.replaceAll("{page}", "").replaceAll("{site}", ""))
+    ? undefined
+    : 'must contain "{page}" and may use "{site}", for example "{page} · {site}" (at most 120 characters)';
+const flag = (value) => (typeof value === "boolean" ? undefined : "must be true or false");
+const api = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return 'must be an object such as { "base": "/api" }';
+    }
+    const given = value;
+    const unknown = Object.keys(given).filter((key) => key !== "base" && key !== "proxy");
+    if (unknown.length > 0) {
+        return `has unknown settings ${unknown.map((key) => `"${key}"`).join(", ")} (known: base, proxy)`;
+    }
+    if (typeof given["base"] !== "string" || !/^(\/([\w.~-]+\/?)*|https:\/\/[^\s/]+(\/[^\s]*)?)$/.test(given["base"]) || given["base"].endsWith("//")) {
+        return '"base" must be a path on the site ("/api") or an absolute https address ("https://api.example.com")';
+    }
+    if (given["proxy"] !== undefined) {
+        try {
+            const target = new URL(String(given["proxy"]));
+            if (!target.protocol.startsWith("http") || !given["base"].startsWith("/")) {
+                return '"proxy" is an http(s) address that a path "base" is forwarded to while you run vlx dev';
+            }
+        }
+        catch {
+            return '"proxy" must be an absolute address such as http://localhost:3000';
+        }
+    }
+    return undefined;
+};
 /** Reads and validates the project's configuration. Every problem in both files is reported together. */
 export const loadConfig = (root) => {
     const project = read(root, PROJECT_FILE);
@@ -68,16 +98,29 @@ export const loadConfig = (root) => {
     }
     const web = read(root, WEB_FILE);
     const problems = [
-        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text }, ["name"]),
-        ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url }, [])),
+        ...check(PROJECT_FILE, project.text, project.value, { $schema: schema, version, name: text, title }, ["name"]),
+        ...(web === undefined ? [] : check(WEB_FILE, web.text, web.value, { $schema: schema, version, base, url, headers: flag, announce: flag, api }, [])),
     ];
     if (problems.length > 0) {
         throw new AppError(problems);
     }
     const given = (web?.value ?? {});
-    return { name: project.value.name, web: { base: given.base ?? "/", url: given.url ?? "" } };
+    const named = project.value;
+    return {
+        name: named.name,
+        title: named.title ?? DEFAULT_TITLE,
+        web: { base: given.base ?? "/", url: given.url ?? "", headers: given.headers ?? true, announce: given.announce ?? true },
+        api: { base: given.api?.base ?? "", proxy: given.api?.proxy ?? "" },
+    };
 };
-export const siteInfo = (config) => ({ name: config.name, base: config.web.base, url: config.web.url });
+export const siteInfo = (config) => ({
+    name: config.name,
+    base: config.web.base,
+    url: config.web.url,
+    title: config.title,
+    api: config.api.base,
+    announce: config.web.announce,
+});
 /**
  * The nearest directory at or above `from` that holds a `valance.json`, as its real path. The bundler names a file by its real path, so a project reached through a symlink, or by a short
  * Windows name (`RUNNER~1`), must be called the same thing here or a file is not the file the bundler means.

package/dist/content.js

@@ -2,6 +2,7 @@
 // discovery, front matter, Markdown, navigation order, and a check of every link and image against the pages and `public/` that exist.
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, posix } from "node:path";
+import { siteInfo } from "./config.js";
 import { AppError, diagnostic } from "./diagnostics.js";
 import { parseMarkdown, plain } from "./markdown.js";
 export const CONTENT_DIR = "content";
@@ -188,6 +189,6 @@ export const readContent = (root, config) => {
         throw new AppError(problems);
     }
     const ordered = [...pages].sort((a, b) => (a.section === "" ? 0 : 1) - (b.section === "" ? 0 : 1) || a.section.localeCompare(b.section) || a.order - b.order || a.path.localeCompare(b.path));
-    return { site: { name: config.name, base: config.web.base, url: config.web.url }, pages: ordered, ...(fallback === undefined ? {} : { notFound: fallback }) };
+    return { site: siteInfo(config), pages: ordered, ...(fallback === undefined ? {} : { notFound: fallback }) };
 };
 export const sectionTitle = titleCase;

package/dist/dev.js

@@ -54,7 +54,14 @@ const start = async (root, config, options, restart) => {
     const base = baseConfig(root, config);
     const server = await createServer({
         ...base,
-        server: { port: options.port ?? 5173, host: options.host ?? "127.0.0.1", strictPort: false, fs: { allow: [root] } },
+        server: {
+            port: options.port ?? 5173,
+            host: options.host ?? "127.0.0.1",
+            strictPort: false,
+            fs: { allow: [root] },
+            // The backend, reached through the page's own origin: no CORS settings to write (valance.web.json `api`).
+            ...(config.api.proxy === "" || !config.api.base.startsWith("/") ? {} : { proxy: { [config.api.base.replace(/\/$/, "")]: { target: config.api.proxy, changeOrigin: true } } }),
+        },
         plugins: [
             ...(base.plugins ?? []),
             {

package/dist/markdown.js

@@ -5,7 +5,8 @@ export const slug = (text) => text
     .replace(/[̀-ͯ]/g, "")
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
-const MARKS = /\*\*([^*]+)\*\*|`([^`]+)`|!\[[^\]]*\]\([^)\s]*\)|\[([^\]]+)\]\(([^)\s]+)\)|\*([^*\s][^*]*)\*|(?<![\w])_([^_\s][^_]*)_(?![\w])/g;
+// A link's address may hold one level of balanced parentheses (`/a_(b)`, `javascript:alert(1)`), so it is read whole: a check that names it quotes all of it.
+const MARKS = /\*\*([^*]+)\*\*|`([^`]+)`|!\[[^\]]*\]\((?:[^()\s]|\([^()\s]*\))*\)|\[([^\]]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\)|\*([^*\s][^*]*)\*|(?<![\w])_([^_\s][^_]*)_(?![\w])/g;
 const empty = { level: 0, anchor: "", spans: [], items: [], ordered: false, lang: "", text: "", src: "", alt: "" };
 export const plain = (spans) => spans.map((span) => span.text).join("");
 /**

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,8 +1,11 @@
+import type { Vocabulary } from "@valancex/common/internal";
 export interface Target {
     /** The flag (`--web`) and the name in `valance.<id>.json`. */
     readonly id: "web";
     readonly label: string;
     readonly hint: string;
+    /** The tags its templates may write. A project builds against its target's vocabulary. */
+    readonly vocabulary: Vocabulary;
 }
 export declare const TARGETS: ReadonlyArray<Target>;
 export type TargetId = Target["id"];

package/dist/targets.js

@@ -1,2 +1,7 @@
-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. Today there is one, the web; 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/`), not a change to them.
+import { webVocabulary } from "@valancex/common/internal";
+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 },
+];
 export const isTarget = (name) => TARGETS.some((each) => each.id === name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valancex/cli",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -53,12 +53,13 @@
     "ink": "7.1.1",
     "react": "19.2.8",
     "vite": "7.3.6",
-    "@valancex/common": "^0.11.0",
-    "@valancex/valance": "^0.11.0"
+    "@valancex/common": "^0.12.0",
+    "@valancex/valance": "^0.12.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.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."
+        }
+      }
+    }
   }
 }