create-zoijs 0.1.3 → 0.2.0

package/bin/create-zoijs.js

@@ -1,169 +1,197 @@
-#!/usr/bin/env node
-// create-zoijs — a tiny scaffolder for new Zoijs apps. No build step, no
-// dependencies. It copies a template, fills in the app name, and prints the
-// three commands to get going. That's the whole tool — read it top to bottom.
-//
-// Usage:
-//   npm create zoijs@latest my-app          (npm maps this to create-zoijs)
-//   npx create-zoijs my-app --template basic
-//
-// The pure functions below are exported so they can be unit-tested; main() only
-// runs when this file is executed directly (not when imported).
-
-import fs from "node:fs";
-import path from "node:path";
-import readline from "node:readline";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-export const TEMPLATES = ["basic", "app", "typescript", "minimal", "library"];
-export const DEFAULT_TEMPLATE = "app";
-const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
-
-// ---- argument parsing --------------------------------------------------------
-
-/** Parse argv into { name, template }. The first non-flag arg is the app name. */
-export function parseArgs(argv) {
-  let name;
-  let template = DEFAULT_TEMPLATE;
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--template" || a === "-t") template = argv[++i];
-    else if (a.startsWith("--template=")) template = a.slice("--template=".length);
-    else if (!a.startsWith("-") && name === undefined) name = a;
-  }
-  return { name, template };
-}
-
-// ---- naming ------------------------------------------------------------------
-
-/** A readable Title Case form of a project name: "task-manager" → "Task Manager". */
-export function toTitle(name) {
-  return String(name)
-    .replace(/[-_]+/g, " ")
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .trim()
-    .split(/\s+/)
-    .filter(Boolean)
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-    .join(" ");
-}
-
-/** Validate a project name. Returns { valid, problems[] }. Keeps it npm-safe. */
-export function validateName(name) {
-  const problems = [];
-  if (!name || !name.trim()) {
-    problems.push("Project name cannot be empty.");
-    return { valid: false, problems };
-  }
-  if (name.trim() !== name) problems.push("Project name cannot have leading or trailing spaces.");
-  if (name.length > 214) problems.push("Project name must be 214 characters or fewer.");
-  if (/^[._]/.test(name)) problems.push("Project name cannot start with a dot or underscore.");
-  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
-    problems.push("Project name may only contain letters, numbers, dashes, dots, and underscores.");
-  }
-  return { valid: problems.length === 0, problems };
-}
-
-// ---- filesystem --------------------------------------------------------------
-
-/** Throw if the target directory exists and already has files in it. */
-export function ensureTargetAvailable(targetDir) {
-  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
-    throw new Error(`Directory "${path.basename(targetDir)}" already exists and is not empty.`);
-  }
-}
-
-const TEXT_EXT = new Set([".js", ".ts", ".mjs", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
-const isText = (file) => file === "_gitignore" || TEXT_EXT.has(path.extname(file));
-
-function applyTokens(content, tokens) {
-  return content.replaceAll("{{APP_NAME}}", tokens.APP_NAME).replaceAll("{{APP_TITLE}}", tokens.APP_TITLE);
-}
-
-function copyDir(srcDir, destDir, tokens, written) {
-  fs.mkdirSync(destDir, { recursive: true });
-  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    const srcPath = path.join(srcDir, entry.name);
-    // npm strips a literal ".gitignore" from published packages, so templates
-    // ship it as "_gitignore" and we rename it on copy.
-    const destName = entry.name === "_gitignore" ? ".gitignore" : entry.name;
-    const destPath = path.join(destDir, destName);
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, tokens, written);
-    } else if (isText(entry.name)) {
-      fs.writeFileSync(destPath, applyTokens(fs.readFileSync(srcPath, "utf8"), tokens));
-      written.push(destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-      written.push(destPath);
-    }
-  }
-}
-
-/**
- * Copy a template into targetDir, substituting the app name. Pure FS work — the
- * caller decides the name/template/dirs, which makes this easy to test.
- */
-export function scaffold({ name, template = DEFAULT_TEMPLATE, targetDir, templatesDir = TEMPLATES_DIR }) {
-  const tplDir = path.join(templatesDir, template);
-  if (!TEMPLATES.includes(template) || !fs.existsSync(tplDir)) {
-    throw new Error(`Unknown template "${template}". Available templates: ${TEMPLATES.join(", ")}.`);
-  }
-  const tokens = { APP_NAME: name.toLowerCase(), APP_TITLE: toTitle(name) };
-  const written = [];
-  copyDir(tplDir, targetDir, tokens, written);
-  return { written, tokens };
-}
-
-// ---- the CLI -----------------------------------------------------------------
-
-function ask(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
-}
-
-const fail = (message) => { console.error(`\n✖ ${message}\n`); process.exit(1); };
-
-async function main(argv) {
-  const { name: argName, template } = parseArgs(argv);
-
-  let name = argName;
-  if (!name) name = await ask("Project name: ");
-
-  const { valid, problems } = validateName(name);
-  if (!valid) fail(problems.join("\n  "));
-
-  const targetDir = path.resolve(process.cwd(), name);
-  try {
-    ensureTargetAvailable(targetDir);
-  } catch (err) {
-    fail(err.message);
-  }
-
-  let result;
-  try {
-    result = scaffold({ name, template, targetDir });
-  } catch (err) {
-    fail(err.message);
-  }
-
-  console.log(`\n✔ Created ${name} (${template} template) — ${result.written.length} files\n`);
-  console.log("Next steps:");
-  console.log(`  cd ${name}`);
-  console.log("  npm install");
-  console.log("  npm run dev\n");
-  console.log("Zoijs works without this tool, too — it's only a convenience. See https://zoijs.dev/start\n");
-}
-
-// Run only when executed directly (resolve symlinks so the npm bin shim works).
-function invokedDirectly() {
-  try {
-    return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
-  } catch {
-    return process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
-  }
-}
-
-if (invokedDirectly()) main(process.argv.slice(2));
+#!/usr/bin/env node
+// create-zoijs — a tiny scaffolder for new Zoijs apps. No build step, no
+// dependencies. It copies a template, fills in the app name, and prints the
+// three commands to get going. That's the whole tool — read it top to bottom.
+//
+// Usage:
+//   npm create zoijs@latest my-app          (npm maps this to create-zoijs)
+//   npx create-zoijs my-app --template basic
+//
+// The pure functions below are exported so they can be unit-tested; main() only
+// runs when this file is executed directly (not when imported).
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const TEMPLATES = ["basic", "app", "typescript", "minimal", "library"];
+export const DEFAULT_TEMPLATE = "app";
+const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+
+// The one exact @zoijs/core version generated apps target, plus an integrity-protected
+// jsDelivr import map for it (generated by scripts/cdn-importmap.mjs, verified at release).
+// Templates never hard-code a Zoijs version: they use the tokens below.
+const CORE_CDN = path.join(__dirname, "..", "core-cdn.json");
+export function loadCore(file = CORE_CDN) {
+  const cdn = JSON.parse(fs.readFileSync(file, "utf8"));
+  return { version: cdn.packages["@zoijs/core"].version, imports: cdn.imports, integrity: cdn.integrity };
+}
+
+// ---- argument parsing --------------------------------------------------------
+
+/** Parse argv into { name, template }. The first non-flag arg is the app name. */
+export function parseArgs(argv) {
+  let name;
+  let template = DEFAULT_TEMPLATE;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--template" || a === "-t") template = argv[++i];
+    else if (a.startsWith("--template=")) template = a.slice("--template=".length);
+    else if (!a.startsWith("-") && name === undefined) name = a;
+  }
+  return { name, template };
+}
+
+// ---- naming ------------------------------------------------------------------
+
+/** A readable Title Case form of a project name: "task-manager" → "Task Manager". */
+export function toTitle(name) {
+  return String(name)
+    .replace(/[-_]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+/** Validate a project name. Returns { valid, problems[] }. Keeps it npm-safe. */
+export function validateName(name) {
+  const problems = [];
+  if (!name || !name.trim()) {
+    problems.push("Project name cannot be empty.");
+    return { valid: false, problems };
+  }
+  if (name.trim() !== name) problems.push("Project name cannot have leading or trailing spaces.");
+  if (name.length > 214) problems.push("Project name must be 214 characters or fewer.");
+  if (/^[._]/.test(name)) problems.push("Project name cannot start with a dot or underscore.");
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    problems.push("Project name may only contain letters, numbers, dashes, dots, and underscores.");
+  }
+  return { valid: problems.length === 0, problems };
+}
+
+// ---- filesystem --------------------------------------------------------------
+
+/** Throw if the target directory exists and already has files in it. */
+export function ensureTargetAvailable(targetDir) {
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    throw new Error(`Directory "${path.basename(targetDir)}" already exists and is not empty.`);
+  }
+}
+
+const TEXT_EXT = new Set([".js", ".ts", ".mjs", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
+const isText = (file) => file === "_gitignore" || TEXT_EXT.has(path.extname(file));
+
+// npm strips/renames files and dirs that start with a dot from a published package,
+// so templates ship them with a "_" prefix and we restore the dot name on copy.
+const RENAME = { _gitignore: ".gitignore", _vscode: ".vscode" };
+
+function applyTokens(content, tokens) {
+  return content.replace(/\{\{(APP_NAME|APP_TITLE|ZOIJS_CORE_VERSION|ZOIJS_CORE_CDN|ZOIJS_CORE_IMPORTMAP)\}\}/g, (_, key) => tokens[key]);
+}
+
+// The import map for an HTML template, indented to sit inside <script type="importmap">.
+function importMapJson(core) {
+  return JSON.stringify({ imports: core.imports, integrity: core.integrity }, null, 2).replace(/\n/g, "\n      ");
+}
+
+function copyDir(srcDir, destDir, tokens, written) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destName = RENAME[entry.name] ?? entry.name; // restore dot-prefixed names
+    const destPath = path.join(destDir, destName);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, tokens, written);
+    } else if (isText(entry.name)) {
+      fs.writeFileSync(destPath, applyTokens(fs.readFileSync(srcPath, "utf8"), tokens));
+      written.push(destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      written.push(destPath);
+    }
+  }
+}
+
+/**
+ * Copy a template into targetDir, substituting the app name. Pure FS work — the
+ * caller decides the name/template/dirs, which makes this easy to test.
+ */
+export function scaffold({ name, template = DEFAULT_TEMPLATE, targetDir, templatesDir = TEMPLATES_DIR, core = loadCore() }) {
+  const tplDir = path.join(templatesDir, template);
+  if (!TEMPLATES.includes(template) || !fs.existsSync(tplDir)) {
+    throw new Error(`Unknown template "${template}". Available templates: ${TEMPLATES.join(", ")}.`);
+  }
+  const tokens = {
+    APP_NAME: name.toLowerCase(),
+    APP_TITLE: toTitle(name),
+    ZOIJS_CORE_VERSION: core.version,
+    ZOIJS_CORE_CDN: `https://cdn.jsdelivr.net/npm/@zoijs/core@${core.version}/src/`,
+    ZOIJS_CORE_IMPORTMAP: importMapJson(core),
+  };
+  const written = [];
+  copyDir(tplDir, targetDir, tokens, written);
+  return { written, tokens };
+}
+
+/** The commands to print after scaffolding (minimal has nothing to install; library has no app to serve). */
+export function nextSteps(name, template = DEFAULT_TEMPLATE) {
+  if (template === "minimal") return [`cd ${name}`, "npm run dev"];
+  if (template === "library") return [`cd ${name}`, "npm install", "npm test"];
+  return [`cd ${name}`, "npm install", "npm run dev"];
+}
+
+// ---- the CLI -----------------------------------------------------------------
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
+}
+
+const fail = (message) => { console.error(`\n✖ ${message}\n`); process.exit(1); };
+
+async function main(argv) {
+  const { name: argName, template } = parseArgs(argv);
+
+  let name = argName;
+  if (!name) name = await ask("Project name: ");
+
+  const { valid, problems } = validateName(name);
+  if (!valid) fail(problems.join("\n  "));
+
+  const targetDir = path.resolve(process.cwd(), name);
+  try {
+    ensureTargetAvailable(targetDir);
+  } catch (err) {
+    fail(err.message);
+  }
+
+  let result;
+  try {
+    result = scaffold({ name, template, targetDir });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  console.log(`\n✔ Created ${name} (${template} template) — ${result.written.length} files\n`);
+  console.log("Next steps:");
+  for (const step of nextSteps(name, template)) console.log(`  ${step}`);
+  console.log("");
+  console.log("Zoijs works without this tool, too — it's only a convenience. See https://zoijs.dev/start\n");
+}
+
+// Run only when executed directly (resolve symlinks so the npm bin shim works).
+function invokedDirectly() {
+  try {
+    return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+  }
+}
+
+if (invokedDirectly()) main(process.argv.slice(2));

package/core-cdn.json

@@ -0,0 +1,36 @@
+{
+  "prod": false,
+  "imports": {
+    "@zoijs/core": "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/index.js"
+  },
+  "integrity": {
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/core/boundary.js": "sha384-sgP+7Uk+gh1Gk39OqMxZEo9Mox6uM6upgCbk9n4HKa8L3LywliSiXjQPQrjj/OG/",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/core/brand.js": "sha384-SQKAavcGif93XT58P5unWneM/VMR1rPsGM/wF63kNN4YaR2RdK2mu2IwULo9VYix",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/core/each.js": "sha384-ple5ogdJi5exkzQbgaQ8jnLLOymkmnG8dG/B8L36QkDbmIOiuRL+IdNVNNLYh+3N",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/core/html.js": "sha384-5sS5ABTdRpfXmhwZuIyhqcSO7fCY1VFVlYcolWRfLsRVzytc9JnUkjfX2Adfy8WI",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/core/mount.js": "sha384-eAm8c9K1SY4j66NnZ4pc4exzlek7iG67di9hU5U9S3PnaZnElkqRGpzOy2z4Uz2h",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/core/renderer.js": "sha384-H2K6FI3+kv2iPxyLb8V9e9Ux4X95PcPQGYu/h7Gq9rk4brE1nLHKFvI4iG5vt7Uz",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/index.js": "sha384-dDKK+RVA9Pj7X7aJvv0zgepWNZQi9W20zZ1JgACZ4EbIQ9LjvLsss8gsQGiyvcRb",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/prod.js": "sha384-2Wg5h5XW9gULwwZPet1azoni63tKm9iTs9FrAoLV0vGUa77h5WPgqsG/F3TFPuBy",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/computed.js": "sha384-nlAK86Jy1IR3yFSePE38l6cjZqcu5SdnYRVQxJh/+2YQL3WhTHdZ18yCKeKL4ffm",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/core.js": "sha384-dBKT0ohkuylmZHrv0HAjRtTxrMNyo6FZTk8Fqf6LH+aAi3moXikSLGdlPaeZi5IV",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/devtools.js": "sha384-KyEdZp4AcE9RdgocIKg0Q3NKTIyCUPnMi8LLPGrDDhRCJ55DA/JcqSZRFjoHHR5X",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/effect.js": "sha384-EMCI2Kpw6k0EUn5QPC6tJLoON+nUgQ7L25AXgIrWLmhMCLKJq/jP+C6Bk/P6gGDY",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/env.js": "sha384-41791FgWw6cq/pCRB6up+hZExngmUr1tAVxQG58SdvonImEcU6jK7g14jzZAPBFL",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/owner.js": "sha384-r8/NbofI3PXPfKvjxBuhWcRZGMJQn+Ldbne0ghFkjELu6SjvpaWIHnxF8FuScUAp",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/runtime.js": "sha384-5CQnBBrMFUfcq+ahlgE4DX/nG0ua+Bo0l70VtRkXVPWQyvGtXoSScup7FHsQqbA2",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/reactivity/state.js": "sha384-w2HVkiWmSdb8h7qqr4OViqHJrDqlD/oInr+5Lal+lSvXWu3SPuZv35WWDPsEOgUq",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/utils/dom.js": "sha384-XsdCmmxzHfpBmOdz1648tCRrAMMHbWKIzvm4Aj2VIEpWJDIIaKmihqEARvxN6d+2",
+    "https://cdn.jsdelivr.net/npm/@zoijs/core@1.9.0/src/utils/security.js": "sha384-7UafFG7FtgE/ZSVl+gEOKHc7qewaF0V6hKLEqgI9yj9mGTxz62GTzkrUPfbOXOtT"
+  },
+  "packages": {
+    "@zoijs/core": {
+      "version": "1.9.0",
+      "entries": [
+        "src/index.js",
+        "src/prod.js"
+      ],
+      "files": 18
+    }
+  }
+}

package/package.json

@@ -1,43 +1,44 @@
-{
-  "name": "create-zoijs",
-  "version": "0.1.3",
-  "description": "Create a new Zoijs app with one command. Plain HTML, CSS, and JavaScript — no build step.",
-  "type": "module",
-  "bin": {
-    "create-zoijs": "bin/create-zoijs.js"
-  },
-  "files": [
-    "bin",
-    "templates",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "author": "Zoijs contributors (https://zoijs.dev)",
-  "license": "MIT",
-  "homepage": "https://zoijs.dev",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Zoijs/zoijs.git",
-    "directory": "create"
-  },
-  "bugs": {
-    "url": "https://github.com/Zoijs/zoijs/issues"
-  },
-  "keywords": [
-    "zoijs",
-    "create",
-    "create-zoijs",
-    "scaffold",
-    "starter",
-    "cli",
-    "no-build",
-    "no-jsx"
-  ],
-  "scripts": {
-    "test": "node --test tests/create.test.js"
-  }
-}
+{
+  "name": "create-zoijs",
+  "version": "0.2.0",
+  "description": "Create a new Zoijs app with one command. Plain HTML, CSS, and JavaScript — no build step.",
+  "type": "module",
+  "bin": {
+    "create-zoijs": "bin/create-zoijs.js"
+  },
+  "files": [
+    "bin",
+    "core-cdn.json",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Zoijs contributors (https://zoijs.dev)",
+  "license": "MIT",
+  "homepage": "https://zoijs.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zoijs/zoijs.git",
+    "directory": "create"
+  },
+  "bugs": {
+    "url": "https://github.com/Zoijs/zoijs/issues"
+  },
+  "keywords": [
+    "zoijs",
+    "create",
+    "create-zoijs",
+    "scaffold",
+    "starter",
+    "cli",
+    "no-build",
+    "no-jsx"
+  ],
+  "scripts": {
+    "test": "node --test tests/create.test.js tests/dev-server.test.js tests/versions.test.js"
+  }
+}

package/templates/app/README.md

@@ -1,48 +1,68 @@
-# {{APP_TITLE}}
-
-A small **project dashboard** built with [Zoijs](https://zoijs.dev) — plain HTML,
-CSS, and JavaScript. **No build step.**
-
-## Develop
-
-```bash
-npm install
-npm run dev
-```
-
-```text
-  Zoijs dev server
-
-  - Local:  http://localhost:7310
-```
-
-Open the printed URL (it falls back to 7311–7313 if the port is busy).
-
-## Project layout
-
-```
-{{APP_NAME}}/
-  index.html              import map + #app mount point
-  dev-server.mjs          tiny zero-dependency static server (npm run dev)
-  src/
-    app.js                owns all state; composes the dashboard
-    style.css             plain CSS (light/dark, responsive)
-    components/
-      Header.js           parent → child: hero + summary stats
-      StatCard.js         parent → child: a reusable stat card (used ×4)
-      TaskItem.js         child → parent: reports toggle/delete via callbacks
-```
-
-## What it shows
-
-- **`createState`** — the task list, the active filter, and the input draft.
-- **`computed`** — total / completed / active counts and the filtered list.
-- **`each`** — keyed rendering of the visible tasks.
-- **Conditional rendering** — the empty state and the active-filter highlight.
-- **Component composition** — `Header`, `StatCard` (×4), and `TaskItem`.
-- **Parent → child** — `App` passes data down to its components as arguments.
-- **Child → parent** — `TaskItem` reports events up through callbacks; `App`
-  owns the state and performs the changes.
-
-No bundler, no build step. Open the files and read them. Learn more at
-[zoijs.dev](https://zoijs.dev).
+# {{APP_TITLE}}
+
+A small **project dashboard** built with [Zoijs](https://zoijs.dev) — plain HTML,
+CSS, and JavaScript. **No build step.**
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+```text
+  Zoijs dev server
+
+  - Local:  http://localhost:7310
+```
+
+Open the printed URL (it falls back to 7311–7313 if the port is busy).
+
+The dev server is for **development only**: it listens on `127.0.0.1` (this machine),
+never serves dotfiles (`.env`, `.git/`, …) or anything outside the project folder, and is
+not meant for hosting. To try the app from a phone on your network, opt in explicitly with
+`ZOIJS_HOST=0.0.0.0 npm run dev` — while it runs, anyone on that network can read the
+project's files.
+
+## Deploy
+
+This page loads the **development** entry of `@zoijs/core` (helpful warnings, devtools).
+When you deploy, change the import map in `index.html` to the **production** entry —
+same API, warnings and the devtools hook off:
+
+```html
+"@zoijs/core": "./node_modules/@zoijs/core/src/prod.js"
+```
+
+Then deploy the files to a static host (not the dev server) and go through the
+[production security checklist](https://zoijs.dev/production-security) — security headers,
+a Content-Security-Policy with your import map's hash, CSRF, and more.
+
+## Project layout
+
+```
+{{APP_NAME}}/
+  index.html              import map + #app mount point
+  dev-server.mjs          tiny zero-dependency static server (npm run dev)
+  src/
+    app.js                owns all state; composes the dashboard
+    style.css             plain CSS (light/dark, responsive)
+    components/
+      Header.js           parent → child: hero + summary stats
+      StatCard.js         parent → child: a reusable stat card (used ×4)
+      TaskItem.js         child → parent: reports toggle/delete via callbacks
+```
+
+## What it shows
+
+- **`createState`** — the task list, the active filter, and the input draft.
+- **`computed`** — total / completed / active counts and the filtered list.
+- **`each`** — keyed rendering of the visible tasks.
+- **Conditional rendering** — the empty state and the active-filter highlight.
+- **Component composition** — `Header`, `StatCard` (×4), and `TaskItem`.
+- **Parent → child** — `App` passes data down to its components as arguments.
+- **Child → parent** — `TaskItem` reports events up through callbacks; `App`
+  owns the state and performs the changes.
+
+No bundler, no build step. Open the files and read them. Learn more at
+[zoijs.dev](https://zoijs.dev).

package/templates/app/_gitignore

@@ -1 +1 @@
-node_modules
+node_modules

package/templates/app/_vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "bierner.lit-html",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode"
+  ]
+}