@valancex/cli 0.0.0-stage → 0.11.0

package/dist/vite.d.ts

@@ -0,0 +1,7 @@
+import type { InlineConfig, 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;
+/** 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

@@ -0,0 +1,49 @@
+import { createLogger, createServer } from "vite";
+import { join, relative, sep } from "node:path";
+import { GENERATED_DIR, OUTPUT_DIR } from "./project.js";
+export const CLIENT_ENTRY = `${GENERATED_DIR}/client.ts`;
+export const SERVER_ENTRY = `/${GENERATED_DIR}/server.ts`;
+// Published packages ship source maps whose sources they do not ship; Vite warns about each, in every project, and the author can do nothing about it. Every other warning is kept.
+const logger = createLogger("warn");
+// oxlint-disable-next-line no-control-regex -- ESC introduces an ANSI colour sequence
+const noise = (message) => /^Sourcemap for .* points to missing source files/.test(message.replace(/\u001b\[[0-9;]*m/g, ""));
+const { warn, warnOnce } = logger;
+logger.warn = (message, options) => {
+    if (!noise(message)) {
+        warn(message, options);
+    }
+};
+logger.warnOnce = (message, options) => {
+    if (!noise(message)) {
+        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) => ({
+    name: "vlx-templates",
+    enforce: "pre",
+    load(id) {
+        const file = id.split("?")[0];
+        return file.endsWith(".mprx") ? `export default ${JSON.stringify({ mprx: relative(root, file).split(sep).join("/") })};` : null;
+    },
+    // 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) => ({
+    root,
+    configFile: false,
+    base: config.web.base,
+    appType: "custom",
+    plugins: [templates(root)],
+    publicDir: join(root, "public"),
+    // The bundler's cache is an intermediate like any other.
+    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) } },
+    // The MESH runtime refers to node:fs/promises on a path the browser never takes.
+    optimizeDeps: { exclude: ["@valancex/mesh-runtime", "@valancex/cli", "@valancex/common"] },
+});
+/** 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 const createLoader = async (root, config) => createServer({ ...baseConfig(root, config), optimizeDeps: { noDiscovery: true, include: [] }, server: { middlewareMode: true, hmr: false, watch: null, ws: false } });

package/dist/wiring.d.ts

@@ -0,0 +1,108 @@
+import type { Compiled } from "./compile.js";
+import type { DefinedApp } from "@valancex/common";
+import type { Place } from "./tree.js";
+export type { Place };
+export interface Use {
+    /** The tag in a template. */
+    readonly at: Place;
+    readonly tag: string;
+    /** The template that defines it. */
+    readonly target: Place;
+    /** What the caller passes: the attribute (where it is written), and the expression or string it is given. */
+    readonly props: ReadonlyArray<{
+        readonly name: string;
+        readonly from: string;
+        readonly at: Place;
+    }>;
+    /** What the caller does when the component raises an event: `on.toggle={toggleTheme()}`. */
+    readonly events: ReadonlyArray<{
+        readonly name: string;
+        readonly to: string;
+        readonly at: Place;
+    }>;
+}
+/** A component as seen from inside: what it takes and raises, where each is first used in its template, and who passes or handles it. */
+export interface Component {
+    readonly name: string;
+    readonly file: string;
+    /** `at` is where the template first reads the prop; `declared` where `src/main.ts` lists it. */
+    readonly props: ReadonlyArray<{
+        readonly name: string;
+        readonly at: Place;
+        readonly declared?: Place;
+        readonly passedBy: ReadonlyArray<{
+            readonly at: Place;
+            readonly from: string;
+        }>;
+    }>;
+    /** `at` is where the template first raises the event; `declared` where `src/main.ts` lists it. */
+    readonly events: ReadonlyArray<{
+        readonly name: string;
+        readonly at: Place;
+        readonly declared?: Place;
+        readonly handledBy: ReadonlyArray<{
+            readonly at: Place;
+            readonly to: string;
+        }>;
+    }>;
+}
+/** A component as `src/main.ts` declares it: the application's component tree, one entry per component, from `layout` down. */
+export interface Declaration {
+    readonly name: string;
+    readonly file: string;
+    /** Where it is declared in `src/main.ts` (its `component(…)` call, or its import). */
+    readonly declared?: Place;
+    /** The components that list it in `uses`; `(application)` for the layout and an override. */
+    readonly parents: ReadonlyArray<string>;
+    readonly uses: ReadonlyArray<string>;
+}
+export interface Wiring {
+    readonly version: 1;
+    /** A path into manifest.json (`components/theme-toggle/props/theme`) → the authored place it is declared. The framework's own names point into its README. */
+    readonly definitions: Readonly<Record<string, Place>>;
+    /** The same path → where the caller writes it: the attribute that passes a prop, the `on.x` that handles an event. What a click goes to from inside the component. */
+    readonly bindings: Readonly<Record<string, ReadonlyArray<Place>>>;
+    readonly uses: ReadonlyArray<Use>;
+    readonly components: ReadonlyArray<Component>;
+    /** The component tree, as declared. */
+    readonly tree: ReadonlyArray<Declaration>;
+    readonly state: ReadonlyArray<{
+        readonly name: string;
+        readonly source: Place;
+        readonly readBy: ReadonlyArray<Place>;
+    }>;
+    readonly commands: ReadonlyArray<{
+        readonly name: string;
+        readonly source: Place;
+        readonly runBy: ReadonlyArray<Place>;
+    }>;
+}
+interface Read {
+    readonly name: string;
+    readonly call: boolean;
+    readonly at: number;
+}
+interface Element {
+    readonly tag: string;
+    readonly at: number;
+    readonly attributes: ReadonlyArray<{
+        readonly name: string;
+        readonly string: boolean;
+        readonly text: string;
+        readonly at: number;
+    }>;
+}
+interface Scanned {
+    readonly reads: ReadonlyArray<Read>;
+    readonly elements: ReadonlyArray<Element>;
+}
+/** A forgiving scan of MPRX: the elements with their attributes, and every identifier read inside `{ … }`. It reads a template the compiler has accepted, so it does not validate. */
+export declare const scan: (text: string) => Scanned;
+/** The first place a key `name:` is written in `src/main.ts`: where a state field or a command is declared. A text search, not a parse: it is for pointing, and falls back to the top of the file. */
+export declare const locateKey: (text: string, name: string) => Place;
+/** Where the framework documents a name an author did not write: a line of its README, which ships with the package. `undefined` when there is none to point at. */
+export interface Docs {
+    readonly file: string;
+    readonly lines: ReadonlyArray<string>;
+}
+export declare const buildWiring: (root: string, author: DefinedApp | undefined, compiled: Compiled, docs?: Docs) => Wiring;

package/dist/wiring.js

@@ -0,0 +1,330 @@
+// Where every name came from, and what uses it: the connections between main.ts, the layout and the components, recorded at both ends. MESH knows the manifest, not the files it was derived from;
+// VALANCE knows both. Written as `.valance/wiring.json` for the editor, which uses it so that ctrl+click lands on YOUR file instead of the generated manifest, and so that both ends of a
+// connection (an event and its handler, a prop and what is passed) point at each other.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ownNames } from "@valancex/common/internal";
+import { ENTRY_FILE } from "./project.js";
+import { declarationsOf, placeIn } from "./tree.js";
+const KEYWORDS = new Set(["true", "false", "null"]);
+/** What a block's braces start with: its keyword. */
+const BLOCK = /^\s*(#if|#each|:else if|:else|\/if|\/each)(?![\w-])/;
+/** The `as item (key)` of an `{#each}`: the name it binds and, if written, its key. */
+const EACH = /\s+as\s+([A-Za-z_]\w*)\s*(?:\(([\s\S]*)\))?\s*$/;
+/** The identifiers an expression reads (and the commands it calls), with their offsets; strings and member names are not reads. */
+const identifiers = (expression, base) => {
+    const plain = expression.replace(/"([^"\\]|\\.)*"/g, (found) => " ".repeat(found.length));
+    const found = [];
+    for (const match of plain.matchAll(/(?<![.\w$])(\$?[A-Za-z_]\w*)(\s*\()?/g)) {
+        const name = match[1];
+        const after = plain.slice(match.index + name.length).trimStart();
+        const before = plain.slice(0, match.index).trimEnd().slice(-1);
+        if (KEYWORDS.has(name) || name.startsWith("$")) {
+            continue;
+        }
+        if (after.startsWith(":") && (before === "{" || before === ",")) {
+            continue;
+        } // an object key
+        found.push({ name, call: match[2] !== undefined, at: base + match.index });
+    }
+    return found;
+};
+/** The text of a balanced `{ … }` starting at `from`, strings respected. */
+const balanced = (text, from) => {
+    let depth = 0;
+    for (let at = from; at < text.length; at += 1) {
+        const char = text[at];
+        if (char === '"') {
+            at += 1;
+            while (at < text.length && text[at] !== '"') {
+                at += text[at] === "\\" ? 2 : 1;
+            }
+        }
+        else if (char === "{") {
+            depth += 1;
+        }
+        else if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return at;
+            }
+        }
+    }
+    return text.length - 1;
+};
+/** A forgiving scan of MPRX: the elements with their attributes, and every identifier read inside `{ … }`. It reads a template the compiler has accepted, so it does not validate. */
+export const scan = (text) => {
+    const reads = [];
+    const elements = [];
+    /** The names the enclosing `{#each}` blocks bind, innermost last, and the kind of each open block. */
+    const bound = [];
+    const kinds = [];
+    const read = (expression, base) => {
+        reads.push(...identifiers(expression, base).filter((each) => !bound.includes(each.name)));
+    };
+    let at = 0;
+    while (at < text.length) {
+        const char = text[at];
+        if (char === "{") {
+            const end = balanced(text, at);
+            const inner = text.slice(at + 1, end);
+            const block = BLOCK.exec(inner);
+            if (block === null) {
+                read(inner, at + 1);
+            }
+            else if (block[1] === "#each") {
+                // `{#each items as item (key)}`: the list is read where the block is; the key and the body see the name it binds, which is a binding, not a read of state.
+                const head = EACH.exec(inner);
+                if (head !== null) {
+                    const items = inner.slice(block[0].length, head.index);
+                    read(items, at + 1 + block[0].length);
+                    bound.push(head[1]);
+                    kinds.push("each");
+                    if (head[2] !== undefined) {
+                        read(head[2], at + 1 + head.index + head[0].indexOf("(") + 1);
+                    }
+                }
+                else {
+                    kinds.push("each");
+                }
+            }
+            else if (block[1] === "#if") {
+                kinds.push("if");
+                read(inner.slice(block[0].length), at + 1 + block[0].length);
+            }
+            else if (block[1] === ":else if") {
+                read(inner.slice(block[0].length), at + 1 + block[0].length);
+            }
+            else if (block[1] === "/each" || block[1] === "/if") {
+                if (kinds.pop() === "each") {
+                    bound.pop();
+                }
+            }
+            at = end + 1;
+        }
+        else if (char === "<" && text[at + 1] === "/") {
+            at = text.indexOf(">", at) + 1 || text.length;
+        }
+        else if (char === "<" && /[a-z]/.test(text[at + 1] ?? "")) {
+            const name = /^[a-z][a-z0-9-]*/.exec(text.slice(at + 1))[0];
+            const attributes = [];
+            let cursor = at + 1 + name.length;
+            for (;;) {
+                while (/\s/.test(text[cursor] ?? "")) {
+                    cursor += 1;
+                }
+                if (cursor >= text.length) {
+                    break;
+                }
+                if (text.startsWith("/>", cursor)) {
+                    cursor += 2;
+                    break;
+                }
+                if (text[cursor] === ">") {
+                    cursor += 1;
+                    break;
+                }
+                const attribute = /^[A-Za-z_][\w.:-]*/.exec(text.slice(cursor));
+                if (attribute === null) {
+                    cursor += 1;
+                    continue;
+                }
+                const attributeAt = cursor;
+                cursor += attribute[0].length;
+                while (/\s/.test(text[cursor] ?? "")) {
+                    cursor += 1;
+                }
+                if (text[cursor] !== "=") {
+                    attributes.push({ name: attribute[0], string: true, text: "", at: attributeAt });
+                    continue;
+                }
+                cursor += 1;
+                while (/\s/.test(text[cursor] ?? "")) {
+                    cursor += 1;
+                }
+                if (text[cursor] === '"') {
+                    let end = cursor + 1;
+                    while (end < text.length && text[end] !== '"') {
+                        end += text[end] === "\\" ? 2 : 1;
+                    }
+                    attributes.push({ name: attribute[0], string: true, text: text.slice(cursor + 1, end), at: attributeAt });
+                    cursor = end + 1;
+                }
+                else if (text[cursor] === "{") {
+                    const end = balanced(text, cursor);
+                    read(text.slice(cursor + 1, end), cursor + 1);
+                    attributes.push({ name: attribute[0], string: false, text: text.slice(cursor + 1, end).trim(), at: attributeAt });
+                    cursor = end + 1;
+                }
+            }
+            elements.push({ tag: name, at, attributes });
+            at = cursor;
+        }
+        else {
+            at += 1;
+        }
+    }
+    return { reads, elements };
+};
+/** The first place a key `name:` is written in `src/main.ts`: where a state field or a command is declared. A text search, not a parse: it is for pointing, and falls back to the top of the file. */
+export const locateKey = (text, name) => {
+    // The keys of a component's `props: { … }` and `events: { … }` are not state fields or commands: blank them out, keeping every offset.
+    let masked = text;
+    for (const contract of text.matchAll(/\b(?:props|events)\s*:\s*\{/g)) {
+        const open = contract.index + contract[0].length - 1;
+        let depth = 0;
+        let end = open;
+        for (; end < text.length; end += 1) {
+            if (text[end] === "{") {
+                depth += 1;
+            }
+            else if (text[end] === "}") {
+                depth -= 1;
+                if (depth === 0) {
+                    break;
+                }
+            }
+        }
+        masked = masked.slice(0, open) + text.slice(open, end).replace(/[^\n]/g, " ") + masked.slice(end);
+    }
+    const found = new RegExp(`(^|[\\s{,(])(${name})\\s*:`, "m").exec(masked);
+    return found === null ? { file: ENTRY_FILE, line: 1, column: 1 } : placeIn(text, found.index + found[1].length, ENTRY_FILE);
+};
+const docLine = (docs, find) => {
+    const at = docs?.lines.findIndex(find) ?? -1;
+    return docs === undefined || at < 0 ? undefined : { file: docs.file, line: at + 1, column: 1 };
+};
+export const buildWiring = (root, author, compiled, docs) => {
+    const manifest = compiled.manifest;
+    const own = ownNames(author);
+    const mainText = (() => {
+        try {
+            return readFileSync(join(root, ENTRY_FILE), "utf8");
+        }
+        catch {
+            return "";
+        }
+    })();
+    const scanned = new Map(compiled.templates.map((template) => [template.component, { template, ...scan(template.source) }]));
+    const builtInFiles = new Set(compiled.templates.filter((template) => template.builtIn).map((template) => template.file));
+    const definitions = {};
+    const bindings = {};
+    const define = (path, place) => {
+        if (place !== undefined) {
+            definitions[path.join("/")] = place;
+        }
+    };
+    const placeOf = (component, offset) => {
+        const found = scanned.get(component);
+        return placeIn(found.template.source, offset, found.template.file);
+    };
+    const declarations = declarationsOf(root);
+    const sites = new Map(compiled.tree.map((node) => [node.name, declarations.get(node.file)]));
+    const declaredAt = (name) => {
+        const site = sites.get(name);
+        return site?.call ?? site?.imported;
+    };
+    const top = (component) => ({ file: scanned.get(component).template.file, line: 1, column: 1 });
+    // Where each component is used, and what is passed and handled.
+    const uses = [];
+    for (const [component, found] of scanned) {
+        for (const element of found.elements.filter((each) => scanned.has(each.tag))) {
+            uses.push({
+                at: placeOf(component, element.at),
+                tag: element.tag,
+                target: top(element.tag),
+                props: element.attributes
+                    .filter((attribute) => !attribute.name.startsWith("on."))
+                    .map((attribute) => ({ name: attribute.name, from: attribute.string ? JSON.stringify(attribute.text) : `{${attribute.text}}`, at: placeOf(component, attribute.at) })),
+                events: element.attributes
+                    .filter((attribute) => attribute.name.startsWith("on."))
+                    .map((attribute) => ({ name: attribute.name.slice(3), to: attribute.text, at: placeOf(component, attribute.at) })),
+            });
+        }
+    }
+    // What the layout reads or runs: only the layout's own template. A component's `theme` is its prop, a different name that happens to be spelt alike.
+    const readsOf = (name, call) => {
+        const seen = new Set();
+        return scanned
+            .get("layout")
+            .reads.filter((read) => read.name === name && read.call === call)
+            .map((read) => placeOf("layout", read.at))
+            .filter((place) => !seen.has(place.line) && seen.add(place.line));
+    };
+    // The layout: its names are your state, your commands, or the framework's.
+    define(["components", "layout"], top("layout"));
+    for (const name of Object.keys(manifest.components["layout"].scope)) {
+        define(["components", "layout", "scope", name], own.state.includes(name)
+            ? locateKey(mainText, name)
+            : docLine(docs, (line) => line.startsWith("|") && (line.split("|")[1] ?? "").includes(`\`${name}\``)));
+    }
+    for (const name of Object.keys(manifest.components["layout"].commands)) {
+        define(["components", "layout", "commands", name], own.commands.includes(name)
+            ? locateKey(mainText, name)
+            : docLine(docs, (line) => line.includes(`\`${name}\` is the framework`)));
+    }
+    // Components: declared where the template first uses the prop or raises the event, and bound where a caller writes it.
+    const components = [];
+    for (const { template } of scanned.values()) {
+        const name = template.component;
+        if (name === "layout") {
+            continue;
+        }
+        define(["components", name], top(name));
+        const entry = manifest.components[name];
+        const callers = uses.filter((use) => use.tag === name && !builtInFiles.has(use.at.file));
+        const reads = scanned.get(name).reads;
+        const props = Object.keys(entry?.props ?? {}).map((prop) => {
+            const first = reads.find((read) => read.name === prop && !read.call);
+            const at = first === undefined ? top(name) : placeOf(name, first.at);
+            const passedBy = callers.flatMap((use) => use.props.filter((passed) => passed.name === prop).map((passed) => ({ at: passed.at, from: passed.from })));
+            const declared = sites.get(name)?.member("props", prop) ?? declaredAt(name);
+            const everywhere = [...(first === undefined ? [] : [at]), ...passedBy.map((each) => each.at)];
+            define(["components", name, "props", prop], declared ?? at);
+            define(["components", name, "scope", prop], declared ?? at);
+            bindings[["components", name, "props", prop].join("/")] = everywhere;
+            bindings[["components", name, "scope", prop].join("/")] = everywhere;
+            return { name: prop, at, ...(declared === undefined ? {} : { declared }), passedBy };
+        });
+        const events = Object.keys(entry?.events ?? {}).map((event) => {
+            const first = reads.find((read) => read.name === event && read.call);
+            const at = first === undefined ? top(name) : placeOf(name, first.at);
+            const handledBy = callers.flatMap((use) => use.events.filter((handled) => handled.name === event).map((handled) => ({ at: handled.at, to: handled.to })));
+            const declared = sites.get(name)?.member("events", event) ?? declaredAt(name);
+            const everywhere = [...(first === undefined ? [] : [at]), ...handledBy.map((each) => each.at)];
+            define(["components", name, "events", event], declared ?? at);
+            define(["components", name, "commands", event], declared ?? at);
+            bindings[["components", name, "events", event].join("/")] = everywhere;
+            bindings[["components", name, "commands", event].join("/")] = everywhere;
+            return { name: event, at, ...(declared === undefined ? {} : { declared }), handledBy };
+        });
+        components.push({ name, file: template.file, props, events });
+    }
+    // The elements the framework draws: documented in its README, as one list.
+    const tags = docLine(docs, (line) => line.startsWith("Tags you may use:"));
+    for (const [tag, entry] of Object.entries(manifest.components)) {
+        if (scanned.has(tag) || tag.startsWith("mesh-")) {
+            continue;
+        }
+        define(["components", tag], tags);
+        for (const prop of Object.keys(entry.props)) {
+            define(["components", tag, "props", prop], tags);
+        }
+        for (const event of Object.keys(entry.events)) {
+            define(["components", tag, "events", event], tags);
+        }
+    }
+    return {
+        version: 1,
+        definitions,
+        bindings,
+        uses,
+        components,
+        tree: compiled.tree.map((node) => {
+            const declared = declaredAt(node.name);
+            return { name: node.name, file: node.file, ...(declared === undefined ? {} : { declared }), parents: node.parents, uses: node.uses };
+        }),
+        state: own.state.map((name) => ({ name, source: locateKey(mainText, name), readBy: readsOf(name, false) })),
+        commands: own.commands.map((name) => ({ name, source: locateKey(mainText, name), runBy: readsOf(name, true) })),
+    };
+};

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@valancex/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.11.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",
+    "cli",
+    "vlx",
+    "static-site",
+    "scaffold"
+  ],
+  "homepage": "https://github.com/ValanceX/Valance/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/ValanceX/Valance/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ValanceX/Valance.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "Jack Miller <jackmiller0899@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "vlx": "./bin/vlx.js"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "views",
+    "schemas",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@valancex/mesh-compiler": "^0.11.0",
+    "effect": "^3.10.0",
+    "ink": "7.1.1",
+    "react": "19.2.8",
+    "vite": "7.3.6",
+    "@valancex/common": "^0.11.0",
+    "@valancex/valance": "^0.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "19.2.18",
+    "ink-testing-library": "4.0.0",
+    "playwright": "1.56.1",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run"
+  }
 }

package/schemas/valance.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://valancex.dev/schemas/valance.schema.json",
+  "title": "valance.json",
+  "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"],
+  "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>." }
+  }
+}

package/schemas/valance.web.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://valancex.dev/schemas/valance.web.schema.json",
+  "title": "valance.web.json",
+  "description": "Settings for the web target: where the built site is served.",
+  "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." }
+  }
+}

package/templates/web/README.md

@@ -0,0 +1,14 @@
+# {{name}}
+
+A VALANCE application for the web, made with `vlx init`.
+
+```console
+$ {{run}} dev      # serve it, and rebuild as you edit
+$ {{run}} build    # write the site to dist/
+$ {{run}} check    # find mistakes in your files without building
+```
+
+- `content/` is Markdown: a page's path is its address.
+- `src/layout.mprx` is the page around it; `src/main.ts` declares the components it uses (start reading there).
+- `src/styles.css` is the look. `public/` is served as it is.
+- `valance.json` names the application{{web_note}}.

package/templates/web/content/404.md

@@ -0,0 +1,7 @@
+---
+title: Not found
+---
+
+# Not found
+
+There is no page at this address. [Back to the start](/).

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

@@ -0,0 +1,33 @@
+---
+title: Getting started
+description: Create the project, run it, change a page.
+order: 1
+---
+
+# Getting started
+
+## Run it
+
+```
+pnpm install
+pnpm dev
+```
+
+Open the address `vlx dev` prints. Edit this file and save: the page reloads with your change.
+
+## Build it
+
+```
+pnpm build
+```
+
+The finished site is in `dist/`. Anything that serves files can host it.
+
+## Where things are
+
+1. `content/` holds the pages.
+2. `src/layout.mprx` is the shell around every page.
+3. `src/styles.css` is the look.
+4. `public/` holds files that are served as they are, like the logo.
+
+Next: [writing pages](./writing-pages.md).