create-lumiose 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javi Aguilar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// `create-lumiose` entry (owner: Beacon). Runs from source on Node ≥ 24 via native type stripping.
+import { main } from "./main.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/main.d.ts

@@ -0,0 +1,10 @@
+export interface CreateIO {
+    cwd: string;
+    write: (text: string) => void;
+    writeError: (text: string) => void;
+    /** Interactive questions; undefined when stdin is not a terminal. */
+    ask?: (question: string) => Promise<string>;
+    /** `npm_config_user_agent`, for the next-step commands. */
+    userAgent?: string;
+}
+export declare function main(argv: string[], io?: CreateIO): Promise<number>;

package/dist/main.js

@@ -0,0 +1,183 @@
+// `create-lumiose [dir] [--template <name>]` (`pnpm create lumiose`): asks for what is missing when run
+// in a terminal, or takes the defaults with --yes (and in non-interactive runs). Output follows the
+// lumiose CLI contract: exit 0 created, 1 cannot create there, 2 misuse; `--format json` prints
+// `{ command: "create", ok, ... }`.
+import { createInterface } from "node:readline/promises";
+import { relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { mcpCommand, mcpNote } from "@lumiose/cli/agents";
+import pkg from "../package.json" with { type: "json" };
+import { DEFAULT_TEMPLATE, scaffold, ScaffoldError, TEMPLATES, } from "./scaffold.js";
+const USAGE = `Usage: create-lumiose [dir] [options]
+
+Create a Lumiose app in <dir> (asked for when missing in a terminal; default: lumiose-app).
+
+Options:
+  -t, --template <name>  ${TEMPLATES.map((template) => template.name).join(" | ")} (default: ${DEFAULT_TEMPLATE})
+  --name <name>          Package name (default: from the directory name)
+  -y, --yes              Ask nothing: use the defaults
+  --force                Write into a non-empty directory (same-name files are overwritten)
+  --mcp                  Register the Lumiose MCP server for Claude Code (.mcp.json) and Codex
+                         (.codex/config.toml), run with your package manager
+  --format <format>      human (default) or json: { command: "create", ok, ... } on stdout
+  -h, --help             Show this help
+  -v, --version          Show the version
+
+Templates:
+${TEMPLATES.map((template) => `  ${template.name.padEnd(8)} ${template.description} (mode: ${template.mode})`).join("\n")}
+
+Exit codes: 0 created, 1 the directory cannot be used, 2 misuse.
+
+Examples:
+  pnpm create lumiose my-app --template ssr
+  create-lumiose my-site -t static --yes --format json
+  pnpm create lumiose my-app --mcp
+`;
+export async function main(argv, io = processIO()) {
+    const json = argv.some((arg, index) => arg === "--format=json" || (arg === "--format" && argv[index + 1] === "json"));
+    const usageError = (message) => {
+        if (json) {
+            io.write(envelope(false, { failure: { message, help: 'Run "create-lumiose --help".' } }));
+        }
+        else
+            io.writeError(`create-lumiose: ${message}\nRun "create-lumiose --help" for the options.\n`);
+        return 2;
+    };
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                template: { type: "string", short: "t" },
+                name: { type: "string" },
+                yes: { type: "boolean", short: "y" },
+                force: { type: "boolean" },
+                mcp: { type: "boolean" },
+                format: { type: "string" },
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+            },
+        });
+    }
+    catch (error) {
+        return usageError(error.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.format !== undefined && values.format !== "human" && values.format !== "json") {
+        return usageError(`--format must be "human" or "json", not "${values.format}".`);
+    }
+    if (values.help) {
+        io.write(USAGE);
+        return 0;
+    }
+    if (values.version) {
+        io.write(json ? envelope(true, { version: pkg.version }) : `create-lumiose ${pkg.version}\n`);
+        return 0;
+    }
+    if (positionals.length > 1)
+        return usageError(`Unexpected argument "${positionals[1]}".`);
+    if (values.template !== undefined && !isTemplate(values.template)) {
+        return usageError(`Unknown template "${values.template}". Pick one of: ${TEMPLATES.map((t) => t.name).join(", ")}.`);
+    }
+    const ask = values.yes || json ? undefined : io.ask;
+    let dir = positionals[0];
+    if (dir === undefined && ask)
+        dir = (await ask("Project directory (lumiose-app): ")).trim();
+    dir ||= "lumiose-app";
+    let template = values.template;
+    if (template === undefined && ask)
+        template = await askTemplate(ask);
+    template ??= DEFAULT_TEMPLATE;
+    const pm = packageManager(io.userAgent);
+    let result;
+    try {
+        result = await scaffold({
+            dir: resolve(io.cwd, dir),
+            template,
+            ...(values.name === undefined ? {} : { name: values.name }),
+            force: values.force ?? false,
+            ...(values.mcp ? { mcp: pm } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof ScaffoldError))
+            throw error;
+        if (json)
+            io.write(envelope(false, { failure: { message: error.message } }));
+        else
+            io.writeError(`create-lumiose: ${error.message}\n`);
+        return 1;
+    }
+    const fromCwd = relative(io.cwd, result.dir);
+    const cd = fromCwd.startsWith("..") ? result.dir : fromCwd || ".";
+    const next = [
+        ...(cd === "." ? [] : [`cd ${cd.includes(" ") ? JSON.stringify(cd) : cd}`]),
+        `${pm} install`,
+        `${pm} ${pm === "npm" ? "run dev" : "dev"}`,
+    ];
+    if (json) {
+        io.write(envelope(true, {
+            dir: result.dir,
+            name: result.name,
+            template: result.template.name,
+            mode: result.template.mode,
+            files: result.files,
+            next,
+            ...(values.mcp ? { mcp: { ...mcpCommand(pm), note: mcpNote(pm) } } : {}),
+        }));
+    }
+    else {
+        io.write(`\nCreated ${result.name} in ${result.dir} (template: ${result.template.name}, mode: ${result.template.mode}).\n` +
+            `Agent-ready: AGENTS.md, CLAUDE.md and the lumiose skill (.claude/skills/lumiose).\n` +
+            (values.mcp
+                ? `MCP: .mcp.json (Claude Code) and .codex/config.toml (Codex) run the Lumiose MCP server.\n${mcpNote(pm)}\n`
+                : "") +
+            "\n" +
+            `Next:\n${next.map((line) => `  ${line}\n`).join("")}`);
+    }
+    return 0;
+}
+async function askTemplate(ask) {
+    const list = TEMPLATES.map((template, index) => `  ${index + 1}. ${template.name.padEnd(8)} ${template.description}`).join("\n");
+    const defaultIndex = TEMPLATES.findIndex((template) => template.name === DEFAULT_TEMPLATE) + 1;
+    for (;;) {
+        const answer = (await ask(`Template:\n${list}\nPick one (${defaultIndex}): `)).trim();
+        if (answer === "")
+            return DEFAULT_TEMPLATE;
+        const picked = TEMPLATES[Number(answer) - 1]?.name ?? (isTemplate(answer) ? answer : undefined);
+        if (picked)
+            return picked;
+    }
+}
+function isTemplate(name) {
+    return TEMPLATES.some((template) => template.name === name);
+}
+function envelope(ok, payload) {
+    return `${JSON.stringify({ command: "create", ok, ...payload }, null, 2)}\n`;
+}
+/** The package manager that runs us (`pnpm create lumiose`, `npm create lumiose`, …). */
+function packageManager(userAgent) {
+    const name = userAgent?.split("/")[0];
+    return name === "npm" || name === "yarn" || name === "bun" ? name : "pnpm";
+}
+function processIO() {
+    return {
+        cwd: process.cwd(),
+        write: (text) => void process.stdout.write(text),
+        writeError: (text) => void process.stderr.write(text),
+        ...(process.stdin.isTTY ? { ask: askInTerminal } : {}),
+        ...(process.env["npm_config_user_agent"] === undefined
+            ? {}
+            : { userAgent: process.env["npm_config_user_agent"] }),
+    };
+}
+async function askInTerminal(question) {
+    const readline = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await readline.question(question);
+    }
+    finally {
+        readline.close();
+    }
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,41 @@
+import { type AgentFile, type PackageManager } from "@lumiose/cli/agents";
+export type TemplateName = "minimal" | "static" | "ssr" | "spa";
+export interface Template {
+    name: TemplateName;
+    /** The project default route mode, `lumiose({ mode })`. */
+    mode: "static" | "server" | "spa";
+    description: string;
+}
+export declare const TEMPLATES: readonly Template[];
+export declare const DEFAULT_TEMPLATE: TemplateName;
+/** A problem with the target (not empty, invalid name): the CLI exits with 1. */
+export declare class ScaffoldError extends Error {
+    name: string;
+}
+export interface ScaffoldOptions {
+    /** Target directory; created if missing. */
+    dir: string;
+    template: TemplateName;
+    /** Package name. Default: derived from the directory name. */
+    name?: string;
+    /** Write into a non-empty directory, overwriting files with the same names. */
+    force?: boolean;
+    /**
+     * Register `lumiose mcp` for Claude Code (`.mcp.json`) and Codex (`.codex/config.toml`), run with
+     * this package manager.
+     */
+    mcp?: PackageManager;
+}
+export interface ScaffoldResult {
+    /** Absolute target directory. */
+    dir: string;
+    name: string;
+    template: Template;
+    /** Written files, project-relative, sorted. */
+    files: string[];
+    agentFiles: AgentFile[];
+}
+export declare function scaffold(options: ScaffoldOptions): Promise<ScaffoldResult>;
+/** `My App!` → `my-app`. */
+export declare function packageName(text: string): string;
+export declare function isValidPackageName(name: string): boolean;

package/dist/scaffold.js

@@ -0,0 +1,171 @@
+// Writes a new Lumiose project: a template's `src/` (and extras), the generated package.json,
+// tsconfig.json (extending the generated one, decision-25), vite.config.ts with the template's `lumiose({ mode })` (decision-21),
+// .gitignore and README, then the agent files (AGENTS.md, CLAUDE.md, the lumiose skill,
+// .gitattributes) from `@lumiose/cli/agents`, shared with `lumiose agents init`.
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentsInit } from "@lumiose/cli/agents";
+import cliPackage from "@lumiose/cli/package.json" with { type: "json" };
+import lumiosePackage from "lumiose/package.json" with { type: "json" };
+import { formatTsconfig } from "@lumiose/cli/tooling";
+export const TEMPLATES = [
+    { name: "minimal", mode: "static", description: "One static page: the smallest Lumiose app" },
+    {
+        name: "static",
+        mode: "static",
+        description: "A static site: a layout, pages, a blog with staticPaths() and a 404 page",
+    },
+    {
+        name: "ssr",
+        mode: "server",
+        description: "Rendered per request: streaming, a form action, a JSON endpoint and a Node server",
+    },
+    {
+        name: "spa",
+        mode: "spa",
+        description: "A client-rendered app: pages and a persistent layout running in the browser",
+    },
+];
+export const DEFAULT_TEMPLATE = "static";
+const TEMPLATES_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
+/** Tool versions the generated package.json asks for (the Lumiose packages share a version). */
+const VERSIONS = {
+    lumiose: `^${lumiosePackage.version}`,
+    vite: cliPackage.peerDependencies.vite,
+    typescript: "^7.0.2",
+    oxlint: "^1.87.0",
+    oxfmt: "^0.72.0",
+};
+/** A problem with the target (not empty, invalid name): the CLI exits with 1. */
+export class ScaffoldError extends Error {
+    name = "ScaffoldError";
+}
+export async function scaffold(options) {
+    const dir = resolve(options.dir);
+    const template = TEMPLATES.find((candidate) => candidate.name === options.template);
+    if (!template)
+        throw new ScaffoldError(`Unknown template "${options.template}".`);
+    const name = options.name ?? packageName(basename(dir));
+    if (!isValidPackageName(name)) {
+        throw new ScaffoldError(`"${name}" is not a valid package name: use lowercase letters, digits, "-", "." and "_" (pass --name).`);
+    }
+    if (!options.force && existsSync(dir) && (await readdir(dir)).some((entry) => entry !== ".git")) {
+        throw new ScaffoldError(`${dir} is not empty. Pick a new directory, or pass --force.`);
+    }
+    const files = new Map();
+    const templateDir = join(TEMPLATES_DIR, template.name);
+    for (const file of await listFiles(templateDir)) {
+        const text = await readFile(join(templateDir, file), "utf8");
+        files.set(file, text.replaceAll("{{name}}", name));
+    }
+    files.set("package.json", packageJson(name, template));
+    files.set("tsconfig.json", formatTsconfig());
+    files.set("vite.config.ts", viteConfig(template));
+    files.set(".gitignore", "node_modules\ndist\n.lumiose\n");
+    files.set("README.md", readme(name, template));
+    for (const [file, text] of files) {
+        await mkdir(dirname(join(dir, file)), { recursive: true });
+        await writeFile(join(dir, file), text);
+    }
+    const agentFiles = await agentsInit(dir, {
+        name,
+        ...(options.mcp === undefined ? {} : { mcp: options.mcp }),
+    });
+    return {
+        dir,
+        name,
+        template,
+        files: [...files.keys(), ...agentFiles.map((file) => file.file)].toSorted(),
+        agentFiles,
+    };
+}
+/** `My App!` → `my-app`. */
+export function packageName(text) {
+    return (text
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._~-]+/g, "-")
+        .replace(/^[-._]+|-+$/g, "") || "lumiose-app");
+}
+export function isValidPackageName(name) {
+    return /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/.test(name) && name.length <= 214;
+}
+function packageJson(name, template) {
+    const server = template.mode === "server";
+    // The adapter serves `lumiose preview` everywhere and is the production server of `ssr`.
+    const adapter = { "@lumiose/adapter-node": VERSIONS.lumiose };
+    const manifest = {
+        name,
+        version: "0.0.0",
+        private: true,
+        type: "module",
+        scripts: {
+            dev: "lumiose dev",
+            build: "lumiose build",
+            preview: "lumiose preview",
+            ...(server ? { start: "node server.ts" } : {}),
+            check: "lumiose check",
+            lint: "lumiose lint",
+            fmt: "lumiose fmt",
+        },
+        dependencies: { ...(server ? adapter : {}), lumiose: VERSIONS.lumiose },
+        devDependencies: {
+            ...(server ? {} : adapter),
+            "@lumiose/cli": VERSIONS.lumiose,
+            "@lumiose/vite": VERSIONS.lumiose,
+            oxfmt: VERSIONS.oxfmt,
+            oxlint: VERSIONS.oxlint,
+            typescript: VERSIONS.typescript,
+            vite: VERSIONS.vite,
+        },
+        engines: { node: ">=24" },
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+function viteConfig(template) {
+    return `import lumiose from "@lumiose/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  // The default mode of every route: "static" (built HTML), "server" (rendered per request) or
+  // "spa" (rendered in the browser). A route or layout overrides it with \`export const mode\`.
+  plugins: [lumiose({ mode: "${template.mode}" })],
+});
+`;
+}
+function readme(name, template) {
+    const server = template.mode === "server";
+    return `# ${name}
+
+${template.description}. Made with Lumiose (\`create-lumiose --template ${template.name}\`).
+
+## Commands
+
+- \`pnpm dev\`: start the dev server with hot reload.
+- \`pnpm build\`: build into \`dist/\` and prerender the static routes.
+- \`pnpm preview\`: serve the build locally.${server ? "\n- `pnpm start`: serve the build in production (`server.ts`, `@lumiose/adapter-node`)." : ""}
+- \`pnpm check\`: type-check and report Lumiose diagnostics (\`--format json\` for tools).
+- \`pnpm lint\` and \`pnpm fmt\`: lint and format, \`.stsx\` files and \`<style>\` blocks included.
+
+## Layout
+
+- \`src/routes/\`: pages (\`.stsx\`) and endpoints (\`.ts\`); the file path is the URL.
+- \`vite.config.ts\`: \`lumiose({ mode: "${template.mode}" })\` sets the default route mode.
+- \`.lumiose/\`: generated types and shadow files (git-ignored).
+
+\`.stsx\` files are TSX with raw-CSS \`<style>\` blocks. The docs for your Lumiose version are in
+\`node_modules/lumiose/docs\` (\`npx lumiose docs <topic>\`). Coding agents: see \`AGENTS.md\`.
+`;
+}
+async function listFiles(dir, base = dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            return listFiles(path, base);
+        return [relative(base, path).split(sep).join("/")];
+    }));
+    return nested.flat();
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "create-lumiose",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Create a Lumiose app: `pnpm create lumiose my-app --template ssr`. Every project starts agent-ready (AGENTS.md, CLAUDE.md, the lumiose skill).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsjavi/lumiose.git",
+    "directory": "packages/create"
+  },
+  "bin": {
+    "create-lumiose": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@lumiose/cli": "0.2.0",
+    "lumiose": "0.2.0"
+  },
+  "devDependencies": {
+    "@lumiose/adapter-node": "0.2.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "build": "node ../../scripts/build-package.ts"
+  }
 }

package/templates/minimal/src/routes/index.stsx

@@ -0,0 +1,23 @@
+import { Title } from "lumiose";
+
+export default function Home() {
+  return (
+    <main>
+      <Title>{{name}}</Title>
+      <h1>{{name}}</h1>
+      <p>
+        Edit <code>src/routes/index.stsx</code>: pages are files in <code>src/routes</code>.
+      </p>
+    </main>
+  );
+}
+
+// One <style> block at the end of the file styles every component in this file.
+<style>
+  main {
+    max-width: 40rem;
+    margin: 4rem auto;
+    padding: 0 1rem;
+    font-family: system-ui, sans-serif;
+  }
+</style>

package/templates/spa/src/components/Counter.stsx

@@ -0,0 +1,21 @@
+import { signal } from "lumiose";
+
+export function Counter(props: { start?: number }) {
+  const count = signal(props.start ?? 0);
+
+  return (
+    <button class={{ counter: true, hot: count() >= 5 }} onClick={() => count.update((n) => n + 1)}>
+      Clicked {count()} times
+    </button>
+  );
+}
+
+<style>
+  .counter {
+    font: inherit;
+    padding: 0.5rem 1rem;
+  }
+  .hot {
+    color: crimson;
+  }
+</style>

package/templates/spa/src/routes/_layout.stsx

@@ -0,0 +1,34 @@
+// The root layout: in an `spa` app it stays mounted while the pages change.
+import { href, type LayoutProps } from "lumiose";
+
+export default function Layout(props: LayoutProps<"/">) {
+  return (
+    <div class="app">
+      <nav>
+        <a href={href("/")}>Home</a>
+        <a href={href("/about")}>About</a>
+      </nav>
+      {props.children}
+    </div>
+  );
+}
+
+<style>
+  .app {
+    max-width: 42rem;
+    margin: 0 auto;
+    padding: 1.5rem 1rem;
+  }
+  nav {
+    display: flex;
+    gap: 1rem;
+    margin-bottom: 2rem;
+  }
+</style>
+
+<style global>
+  body {
+    margin: 0;
+    font-family: system-ui, sans-serif;
+  }
+</style>

package/templates/spa/src/routes/about.stsx

@@ -0,0 +1,11 @@
+import { Title } from "lumiose";
+
+export default function About() {
+  return (
+    <main>
+      <Title>About · {{name}}</Title>
+      <h1>About</h1>
+      <p>Pages are files in src/routes; the layout in src/routes/_layout.stsx wraps them.</p>
+    </main>
+  );
+}

package/templates/spa/src/routes/index.stsx

@@ -0,0 +1,16 @@
+import { Title } from "lumiose";
+import { Counter } from "../components/Counter.stsx";
+
+export default function Home() {
+  return (
+    <main>
+      <Title>{{name}}</Title>
+      <h1>{{name}}</h1>
+      <p>
+        An <code>spa</code> app: the whole page runs in the browser, so components need no
+        <code> client:</code> directive.
+      </p>
+      <Counter start={1} />
+    </main>
+  );
+}

package/templates/ssr/server.ts

@@ -0,0 +1,9 @@
+// Production server: serves the `lumiose build` output (dist/) with @lumiose/adapter-node. Static
+// files come from dist/client; every other request goes to the app in dist/server/entry.js.
+// Set PORT, HOST and ORIGIN as needed.
+//
+//   pnpm build && pnpm start
+import { createServer } from "@lumiose/adapter-node";
+
+const { url } = await createServer({ dir: new URL("dist", import.meta.url) });
+console.log(`Listening on ${url}`);

package/templates/ssr/src/routes/_404.stsx

@@ -0,0 +1,13 @@
+import { href, Title } from "lumiose";
+
+export default function NotFound() {
+  return (
+    <main>
+      <Title>Not found · {{name}}</Title>
+      <h1>Page not found</h1>
+      <p>
+        <a href={href("/")}>Home</a>
+      </p>
+    </main>
+  );
+}

package/templates/ssr/src/routes/_layout.stsx

@@ -0,0 +1,42 @@
+// The root layout: wraps every page.
+import { href, type LayoutProps } from "lumiose";
+
+export default function Layout(props: LayoutProps<"/">) {
+  return (
+    <div class="app">
+      <header>
+        <a class="brand" href={href("/")}>
+          {{name}}
+        </a>
+        <nav>
+          <a href={href("/guestbook")}>Guestbook</a>
+        </nav>
+      </header>
+      {props.children}
+    </div>
+  );
+}
+
+<style>
+  .app {
+    max-width: 42rem;
+    margin: 0 auto;
+    padding: 1.5rem 1rem;
+  }
+  header {
+    display: flex;
+    justify-content: space-between;
+    margin-bottom: 2rem;
+  }
+  .brand {
+    font-weight: 700;
+  }
+</style>
+
+<style global>
+  body {
+    margin: 0;
+    font-family: system-ui, sans-serif;
+    line-height: 1.6;
+  }
+</style>

package/templates/ssr/src/routes/api/entries.ts

@@ -0,0 +1,5 @@
+// GET /api/entries: the guestbook as JSON.
+import type { Endpoint } from "lumiose";
+import { listEntries } from "../../server/guestbook.server.ts";
+
+export const GET: Endpoint<"/api/entries"> = () => Response.json(listEntries());

package/templates/ssr/src/routes/guestbook.stsx

@@ -0,0 +1,71 @@
+// A form that works without JavaScript: it posts to the `sign` action, which validates the input
+// and redirects back (or returns the errors, which the page reads with actionData()).
+import { actionData, fail, redirect, Title, type ActionContext } from "lumiose";
+import { addEntry, listEntries } from "../server/guestbook.server.ts";
+
+interface Errors {
+  name?: string;
+  message?: string;
+}
+
+export const actions = {
+  async sign(ctx: ActionContext<"/guestbook">) {
+    const form = await ctx.formData();
+    const name = String(form.get("name") ?? "").trim();
+    const message = String(form.get("message") ?? "").trim();
+    const errors: Errors = {};
+    if (name === "") errors.name = "Your name is required.";
+    if (message === "") errors.message = "Write a message.";
+    if (errors.name || errors.message) return fail(400, errors);
+    addEntry(name, message);
+    redirect("/guestbook");
+  },
+};
+
+export default function Guestbook() {
+  const errors = actionData<typeof actions>();
+
+  return (
+    <main>
+      <Title>Guestbook · {{name}}</Title>
+      <h1>Guestbook</h1>
+      <form method="post" action="?/sign">
+        <label>
+          Name <input name="name" />
+        </label>
+        <p class="error">{errors?.name}</p>
+        <label>
+          Message <textarea name="message" />
+        </label>
+        <p class="error">{errors?.message}</p>
+        <button>Sign</button>
+      </form>
+      <ul class="entries">
+        {listEntries().map((entry) => (
+          <li key={entry.id}>
+            <strong>{entry.name}</strong>: {entry.message}
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+
+<style>
+  form {
+    display: grid;
+    gap: 0.25rem;
+    max-width: 24rem;
+  }
+  label {
+    display: grid;
+  }
+  .error {
+    margin: 0;
+    color: crimson;
+  }
+  .entries {
+    padding: 0;
+    list-style: none;
+  }
+</style>

package/templates/ssr/src/routes/index.stsx

@@ -0,0 +1,27 @@
+import { Suspense, Title } from "lumiose";
+import { listEntries } from "../server/guestbook.server.ts";
+
+/** Slow data: the page is sent first and this part streams in when it resolves. */
+async function GuestCount() {
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  return <p class="count">{listEntries().length} guestbook entries so far.</p>;
+}
+
+export default function Home() {
+  return (
+    <main>
+      <Title>{{name}}</Title>
+      <h1>{{name}}</h1>
+      <p>Rendered on the server at {new Date().toLocaleTimeString("en")}, on every request.</p>
+      <Suspense fallback={<p class="count">Counting entries…</p>}>
+        <GuestCount />
+      </Suspense>
+    </main>
+  );
+}
+
+<style>
+  .count {
+    color: #555;
+  }
+</style>

package/templates/ssr/src/server/guestbook.server.ts

@@ -0,0 +1,23 @@
+// A demo store: entries live in memory and are lost when the server restarts. Swap it for a
+// database (node:sqlite, Postgres, …). `*.server.ts` modules never reach the browser:
+// `lumiose dev` and `lumiose build` fail if client code imports one (LUM4003).
+
+export interface Entry {
+  id: number;
+  name: string;
+  message: string;
+  createdAt: string;
+}
+
+const entries: Entry[] = [];
+
+/** Newest first. */
+export function listEntries(): Entry[] {
+  return entries.toReversed();
+}
+
+export function addEntry(name: string, message: string): Entry {
+  const entry = { id: entries.length + 1, name, message, createdAt: new Date().toISOString() };
+  entries.push(entry);
+  return entry;
+}

package/templates/static/src/lib/posts.ts

@@ -0,0 +1,28 @@
+// The blog's content. Replace it with Markdown files (`import.meta.glob("./posts/*.md", { query:
+// "?raw" })`), a CMS or a database: pages read it at build time.
+
+export interface Post {
+  slug: string;
+  title: string;
+  date: string;
+  body: string;
+}
+
+export const posts: Post[] = [
+  {
+    slug: "hello-lumiose",
+    title: "Hello, Lumiose",
+    date: "2026-10-01",
+    body: "This site is static: every page is HTML built by `lumiose build`, with no JavaScript.",
+  },
+  {
+    slug: "adding-pages",
+    title: "Adding pages",
+    date: "2026-10-02",
+    body: "Add a file under src/routes. Pages with params list their paths in staticPaths().",
+  },
+];
+
+export function findPost(slug: string): Post | undefined {
+  return posts.find((post) => post.slug === slug);
+}

package/templates/static/src/routes/_404.stsx

@@ -0,0 +1,13 @@
+import { href, Title } from "lumiose";
+
+export default function NotFound() {
+  return (
+    <main>
+      <Title>Not found · {{name}}</Title>
+      <h1>Page not found</h1>
+      <p>
+        <a href={href("/")}>Back to the posts</a>
+      </p>
+    </main>
+  );
+}

package/templates/static/src/routes/_layout.stsx

@@ -0,0 +1,50 @@
+// The root layout: wraps every page.
+import { href, type LayoutProps } from "lumiose";
+
+export default function Layout(props: LayoutProps<"/">) {
+  return (
+    <div class="site">
+      <header>
+        <a class="brand" href={href("/")}>
+          {{name}}
+        </a>
+        <nav>
+          <a href={href("/about")}>About</a>
+        </nav>
+      </header>
+      {props.children}
+      <footer>Built with Lumiose.</footer>
+    </div>
+  );
+}
+
+<style>
+  .site {
+    max-width: 42rem;
+    margin: 0 auto;
+    padding: 1.5rem 1rem;
+  }
+  header {
+    display: flex;
+    justify-content: space-between;
+    margin-bottom: 2rem;
+  }
+  .brand {
+    font-weight: 700;
+  }
+  footer {
+    margin-top: 3rem;
+    color: #666;
+  }
+</style>
+
+<style global>
+  body {
+    margin: 0;
+    font-family: system-ui, sans-serif;
+    line-height: 1.6;
+  }
+  a {
+    color: #4338ca;
+  }
+</style>

package/templates/static/src/routes/about.stsx

@@ -0,0 +1,14 @@
+import { Title } from "lumiose";
+
+export default function About() {
+  return (
+    <main>
+      <Title>About · {{name}}</Title>
+      <h1>About</h1>
+      <p>
+        A static site made with Lumiose. <code>lumiose build</code> prerenders every page to HTML in
+        <code> dist/client</code>, ready for any static host.
+      </p>
+    </main>
+  );
+}

package/templates/static/src/routes/blog/[slug].stsx

@@ -0,0 +1,27 @@
+import { notFound, params, Title } from "lumiose";
+import { findPost, posts } from "../../lib/posts.ts";
+
+/** The paths `lumiose build` prerenders for this route. */
+export async function staticPaths() {
+  return posts.map((post) => ({ params: { slug: post.slug } }));
+}
+
+export default function BlogPost() {
+  const post = findPost(params<"/blog/[slug]">().slug);
+  if (!post) notFound();
+
+  return (
+    <article>
+      <Title>{post.title} · {{name}}</Title>
+      <h1>{post.title}</h1>
+      <time>{post.date}</time>
+      <p>{post.body}</p>
+    </article>
+  );
+}
+
+<style>
+  time {
+    color: #666;
+  }
+</style>

package/templates/static/src/routes/index.stsx

@@ -0,0 +1,30 @@
+import { href, Title } from "lumiose";
+import { posts } from "../lib/posts.ts";
+
+export default function Home() {
+  return (
+    <main>
+      <Title>{{name}}</Title>
+      <h1>Posts</h1>
+      <ul class="posts">
+        {posts.map((post) => (
+          <li key={post.slug}>
+            <a href={href("/blog/[slug]", { slug: post.slug })}>{post.title}</a>
+            <time>{post.date}</time>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+
+<style>
+  .posts {
+    padding: 0;
+    list-style: none;
+  }
+  time {
+    margin-left: 0.5rem;
+    color: #666;
+  }
+</style>

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.