create-zoijs 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to `create-zoijs` are documented here.
 
+## 0.1.2 — 2026-06-26
+
+Dev-server output polish. No CLI API changes; same zero-dependency server on the
+same ports.
+
+- **Cleaner banner:** `npm run dev` now prints a tidy banner with the local URL
+  on its own line, and only mentions fallback ports when one was actually busy:
+
+  ```text
+    Zoijs dev server
+
+    - Local:  http://localhost:7310
+  ```
+
+  (Previously a single `ZoiJS dev server: http://localhost:7310` line plus a
+  static `If busy: …` note.) Plain ASCII so it renders cleanly in every terminal,
+  including the Windows console. Brand casing normalized to **Zoijs**. Still port
+  **7310** with **7311 / 7312 / 7313** fallbacks; still Node built-ins only.
+
+## 0.1.1 — 2026-06-25
+
+Starter polish. No CLI API changes.
+
+- **Dev server:** generated apps now run `npm run dev` on a tiny zero-dependency
+  static server (`dev-server.mjs`, Node built-ins only) that uses port **7310**
+  and falls back to **7311 / 7312 / 7313** if busy — replacing the old default
+  of port 3000. It prints `ZoiJS dev server: http://localhost:<port>`.
+- **Default `app` template redesigned** into a polished "project dashboard":
+  a hero header, a reusable `StatCard` (used ×4), filter chips (All / Active /
+  Done), an empty state, and a developer-hint footer — demonstrating component
+  composition, conditional rendering, and filtering alongside `createState` /
+  `computed` / `each` and parent⇄child communication. Still depends only on
+  `@zoijs/core`; still no build step.
+- **`basic` template** keeps the minimal counter and adopts the same dev server.
+
 ## 0.1.0 — 2026-06-25
 
 Initial release of the Zoijs starter CLI.

package/README.md

@@ -20,6 +20,17 @@ npm install
 npm run dev
 ```
 
+`npm run dev` starts a tiny zero-dependency static server (no `serve`, no
+bundler, no build step):
+
+```text
+  Zoijs dev server
+
+  - Local:  http://localhost:7310
+```
+
+(It falls back to 7311–7313 if the port is busy.)
+
 Or with `npx`:
 
 ```bash
@@ -47,11 +58,12 @@ one.
 ```bash
 npm create zoijs@latest my-app                    # default: the "app" template
 npm create zoijs@latest my-app --template basic   # a minimal counter
-npm create zoijs@latest my-app --template app     # a small task dashboard
+npm create zoijs@latest my-app --template app     # a polished project dashboard
 ```
 
-- **`app`** (default) — a small task dashboard showing `html`, `mount`,
-  `createState`, `computed`, `each`, and parent⇄child component communication.
+- **`app`** (default) — a polished project dashboard (hero, stat cards, filters,
+  empty state) showing `html`, `mount`, `createState`, `computed`, `each`,
+  conditional rendering, and parent⇄child component communication.
 - **`basic`** — a minimal counter, the smallest possible Zoijs app.
 
 ## What it does

package/bin/create-zoijs.js

@@ -75,7 +75,7 @@ export function ensureTargetAvailable(targetDir) {
   }
 }
 
-const TEXT_EXT = new Set([".js", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
+const TEXT_EXT = new Set([".js", ".mjs", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
 const isText = (file) => file === "_gitignore" || TEXT_EXT.has(path.extname(file));
 
 function applyTokens(content, tokens) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zoijs",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Create a new Zoijs app with one command. Plain HTML, CSS, and JavaScript — no build step.",
   "type": "module",
   "bin": {

package/templates/app/README.md

@@ -1,7 +1,7 @@
 # {{APP_TITLE}}
 
-A small task dashboard built with [Zoijs](https://zoijs.dev) — plain HTML, CSS,
-and JavaScript. **No build step.**
+A small **project dashboard** built with [Zoijs](https://zoijs.dev) — plain HTML,
+CSS, and JavaScript. **No build step.**
 
 ## Develop
 
@@ -10,27 +10,37 @@ npm install
 npm run dev
 ```
 
-Then open the printed URL.
+```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 the task list; renders the page
-    style.css             plain CSS
+    app.js                owns all state; composes the dashboard
+    style.css             plain CSS (light/dark, responsive)
     components/
-      Header.js           parent → child: receives title + count
+      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 and the input draft.
-- **`computed`** — the "tasks left" count, derived from the list.
-- **`each`** — keyed rendering of the task list.
-- **Parent → child** — `App` passes data down to `Header` as arguments.
+- **`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.
 

package/templates/app/dev-server.mjs

@@ -0,0 +1,74 @@
+// dev-server.mjs — a tiny static file server for this Zoijs app.
+//
+// Zero dependencies (Node built-ins only), no build step, no bundler. It serves
+// the project files so the import map in index.html can load @zoijs/core from
+// node_modules. Tries port 7310, then 7311 / 7312 / 7313 if one is busy.
+//
+//   node dev-server.mjs      (this is what `npm run dev` runs)
+
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { extname, join, normalize } from "node:path";
+
+const PORTS = [7310, 7311, 7312, 7313];
+const ROOT = process.cwd();
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+};
+
+const server = createServer(async (req, res) => {
+  let pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+  if (pathname === "/") pathname = "/index.html";
+
+  // Resolve inside ROOT and refuse anything that climbs out of it.
+  const filePath = join(ROOT, normalize(pathname));
+  if (!filePath.startsWith(ROOT)) {
+    res.writeHead(403).end("Forbidden");
+    return;
+  }
+  try {
+    const body = await readFile(filePath);
+    res.writeHead(200, { "Content-Type": TYPES[extname(filePath)] || "application/octet-stream" });
+    res.end(body);
+  } catch {
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }).end("Not found");
+  }
+});
+
+function start(i = 0) {
+  if (i >= PORTS.length) {
+    console.error(`\nAll dev ports are busy (${PORTS.join(", ")}). Free one and try again.\n`);
+    process.exit(1);
+  }
+  // Paired once-listeners: each attempt removes its sibling so a failed bind
+  // can't leave a stale "listening" handler that prints the wrong port later.
+  const onError = (err) => {
+    server.removeListener("listening", onListening);
+    if (err.code === "EADDRINUSE") start(i + 1);
+    else {
+      console.error(err);
+      process.exit(1);
+    }
+  };
+  const onListening = () => {
+    server.removeListener("error", onError);
+    const lines = ["", "  Zoijs dev server", "", `  - Local:  http://localhost:${PORTS[i]}`];
+    if (i > 0) lines.push(`  (ports ${PORTS.slice(0, i).join(", ")} were busy)`);
+    lines.push("");
+    console.log(lines.join("\n"));
+  };
+  server.once("error", onError);
+  server.once("listening", onListening);
+  server.listen(PORTS[i]);
+}
+
+start();

package/templates/app/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "npx serve ."
+    "dev": "node dev-server.mjs"
   },
   "dependencies": {
     "@zoijs/core": "^1.1.0"

package/templates/app/src/app.js

@@ -1,54 +1,97 @@
 import { html, mount, createState, computed, each } from "@zoijs/core";
 import { Header } from "./components/Header.js";
+import { StatCard } from "./components/StatCard.js";
 import { TaskItem } from "./components/TaskItem.js";
 
-// The App owns the task list. Children receive data as arguments (parent → child)
-// and report events back through callbacks (child → parent). No store, no context.
+// The App owns all the state. Child components receive data as arguments
+// (parent -> child) and report events back through callbacks (child -> parent).
+// No store, no context, no providers — just functions and reactive values.
 function App() {
+  // --- state -----------------------------------------------------------------
   const tasks = createState([
-    { id: 1, text: "Read the Zoijs docs", done: true },
-    { id: 2, text: "Build something small", done: false },
-    { id: 3, text: "Share it", done: false },
+    { id: 1, text: "Read the Zoijs guide", done: true },
+    { id: 2, text: "Scaffold a project", done: true },
+    { id: 3, text: "Design the dashboard", done: false },
+    { id: 4, text: "Ship something small", done: false },
   ]);
-  let nextId = 4;
-
-  // computed: derived, cached, reactive.
-  const remaining = computed(() => tasks.get().filter((t) => !t.done).length);
+  const filter = createState("all"); // "all" | "active" | "done"
+  const draft = createState("");
+  let nextId = 5;
 
-  const addTask = (text) => tasks.set([...tasks.get(), { id: nextId++, text, done: false }]);
-  const toggle = (id) => tasks.set(tasks.get().map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
-  const remove = (id) => tasks.set(tasks.get().filter((t) => t.id !== id));
+  // --- derived values (computed: cached + reactive) --------------------------
+  const total = computed(() => tasks.get().length);
+  const completed = computed(() => tasks.get().filter((t) => t.done).length);
+  const active = computed(() => total.get() - completed.get());
+  const visible = computed(() => {
+    const f = filter.get();
+    return tasks.get().filter((t) => (f === "all" ? true : f === "done" ? t.done : !t.done));
+  });
 
-  const draft = createState("");
-  const onSubmit = (e) => {
+  // --- actions ---------------------------------------------------------------
+  const addTask = (e) => {
     e.preventDefault();
     const text = draft.get().trim();
     if (!text) return;
-    addTask(text);
+    tasks.set([...tasks.get(), { id: nextId++, text, done: false }]);
     draft.set("");
   };
+  const toggle = (id) => tasks.set(tasks.get().map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
+  const remove = (id) => tasks.set(tasks.get().filter((t) => t.id !== id));
+
+  const filterChip = (value, label) => html`
+    <button
+      class=${() => "chip" + (filter.get() === value ? " chip-on" : "")}
+      onclick=${() => filter.set(value)}>
+      ${label}
+    </button>
+  `;
 
   return html`
-    <main>
-      ${/* parent → child: pass plain data (title) and a reader (remaining) down */ ""}
-      ${Header({ title: "{{APP_TITLE}}", remaining: () => remaining.get() })}
-
-      <form onsubmit=${onSubmit}>
-        <input
-          placeholder="Add a task…"
-          value=${() => draft.get()}
-          oninput=${(e) => draft.set(e.target.value)} />
-        <button type="submit">Add</button>
-      </form>
-
-      <ul class="tasks">
-        ${each(
-          () => tasks.get(),
-          (t) => t.id,
-          (t) => TaskItem({ task: t, onToggle: toggle, onDelete: remove })
-        )}
-      </ul>
-    </main>
+    <div class="app">
+      ${Header({ completed: () => completed.get(), total: () => total.get() })}
+
+      <section class="stats">
+        ${StatCard({ label: "Total", value: () => total.get(), accent: "indigo" })}
+        ${StatCard({ label: "Completed", value: () => completed.get(), accent: "green" })}
+        ${StatCard({ label: "Active", value: () => active.get(), accent: "amber" })}
+        ${StatCard({ label: "Filter", value: () => filter.get(), accent: "slate" })}
+      </section>
+
+      <section class="panel">
+        <form class="add" onsubmit=${addTask}>
+          <input
+            aria-label="Add a task"
+            placeholder="Add a task…"
+            value=${() => draft.get()}
+            oninput=${(e) => draft.set(e.target.value)} />
+          <button type="submit">Add</button>
+        </form>
+
+        <div class="filters" role="group" aria-label="Filter tasks">
+          ${filterChip("all", "All")}
+          ${filterChip("active", "Active")}
+          ${filterChip("done", "Done")}
+        </div>
+
+        <ul class="tasks">
+          ${each(
+            () => visible.get(),
+            (t) => t.id,
+            (t) => TaskItem({ task: t, onToggle: toggle, onDelete: remove })
+          )}
+        </ul>
+
+        ${() =>
+          visible.get().length === 0
+            ? html`<p class="empty">Nothing here yet — add a task above. ✨</p>`
+            : null}
+      </section>
+
+      <footer class="hint">
+        <p>This starter uses <code>html()</code>, <code>createState()</code>, <code>computed()</code>, and <code>each()</code>.</p>
+        <p>Open <code>src/app.js</code> to start editing.</p>
+      </footer>
+    </div>
   `;
 }
 

package/templates/app/src/components/Header.js

@@ -1,13 +1,15 @@
 import { html } from "@zoijs/core";
 
-// Parent → child communication: Header receives plain data (`title`) and a
-// reader function (`remaining`) as arguments. It owns no state of its own.
-export function Header({ title, remaining }) {
+// Parent -> child: the Header receives derived stats as reader functions and
+// renders the hero. It holds no state of its own.
+export function Header({ completed, total }) {
   return html`
-    <header>
-      <h1>${title}</h1>
-      <p class="count">
-        ${() => remaining()} task${() => (remaining() === 1 ? "" : "s")} left
+    <header class="hero">
+      <span class="badge">Built with Zoijs</span>
+      <h1>{{APP_TITLE}}</h1>
+      <p class="tagline">A tiny project dashboard — plain HTML, CSS, and JavaScript. No build step.</p>
+      <p class="summary">
+        <strong>${() => completed()}</strong> of <strong>${() => total()}</strong> tasks done
       </p>
     </header>
   `;

package/templates/app/src/components/StatCard.js

@@ -0,0 +1,13 @@
+import { html } from "@zoijs/core";
+
+// A small, reusable presentational component used four times in the stats grid.
+// Parent -> child: it simply renders the label, value, and accent it is given —
+// composition without any shared state.
+export function StatCard({ label, value, accent }) {
+  return html`
+    <div class="card stat stat-${accent}">
+      <div class="stat-value">${() => value()}</div>
+      <div class="stat-label">${label}</div>
+    </div>
+  `;
+}

package/templates/app/src/components/TaskItem.js

@@ -1,10 +1,10 @@
 import { html } from "@zoijs/core";
 
-// Child → parent communication: TaskItem owns no state. It reports toggle and
-// delete events upward by calling the callbacks the parent passed in.
+// Child -> parent: TaskItem owns no state. It reports toggle and delete events
+// upward by calling the callbacks the parent passed in.
 export function TaskItem({ task, onToggle, onDelete }) {
   return html`
-    <li class=${() => (task.done ? "done" : "")}>
+    <li class=${() => "task" + (task.done ? " done" : "")}>
       <label>
         <input
           type="checkbox"
@@ -12,7 +12,7 @@ export function TaskItem({ task, onToggle, onDelete }) {
           onchange=${() => onToggle(task.id)} />
         <span>${() => task.text}</span>
       </label>
-      <button class="delete" title="Delete" onclick=${() => onDelete(task.id)}>✕</button>
+      <button class="delete" title="Delete task" onclick=${() => onDelete(task.id)}>✕</button>
     </li>
   `;
 }

package/templates/app/src/style.css

@@ -1,53 +1,168 @@
+/* A small, polished dashboard theme — plain CSS, no framework.
+   Adapts to light/dark automatically and stays readable on mobile. */
+
 :root {
   color-scheme: light dark;
-  font-family: system-ui, sans-serif;
-  line-height: 1.5;
+  --bg: #f6f7fb;
+  --panel: #ffffff;
+  --text: #1e2230;
+  --muted: #6b7280;
+  --border: #e6e8ef;
+  --accent: #6366f1;
+  --accent-2: #8b5cf6;
+  --radius: 14px;
+  --shadow: 0 1px 2px rgba(20, 22, 40, 0.04), 0 8px 24px rgba(20, 22, 40, 0.06);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0e1016;
+    --panel: #171a22;
+    --text: #e7e9f0;
+    --muted: #9aa1b1;
+    --border: #262a36;
+    --shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 10px 30px rgba(0, 0, 0, 0.35);
+  }
+}
+
+* {
+  box-sizing: border-box;
 }
 
 body {
   margin: 0;
-  display: grid;
-  place-items: start center;
   min-height: 100vh;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  line-height: 1.5;
+  color: var(--text);
+  background:
+    radial-gradient(1200px 500px at 50% -200px, rgba(99, 102, 241, 0.18), transparent 70%),
+    var(--bg);
 }
 
-main {
-  width: min(34rem, 92vw);
-  padding: 2rem 1rem;
+.app {
+  width: min(56rem, 92vw);
+  margin: 0 auto;
+  padding: clamp(1.5rem, 4vw, 3rem) 0 3rem;
 }
 
-header h1 {
-  margin: 0 0 0.25rem;
+/* --- hero ------------------------------------------------------------------ */
+.hero {
+  text-align: center;
+  margin-bottom: 1.75rem;
+}
+.badge {
+  display: inline-block;
+  font-size: 0.72rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: #fff;
+  background: linear-gradient(135deg, var(--accent), var(--accent-2));
+  padding: 0.3rem 0.7rem;
+  border-radius: 999px;
+}
+.hero h1 {
+  margin: 0.7rem 0 0.25rem;
+  font-size: clamp(1.8rem, 5vw, 2.6rem);
+  letter-spacing: -0.02em;
+}
+.tagline {
+  margin: 0 auto;
+  max-width: 34rem;
+  color: var(--muted);
+}
+.summary {
+  margin: 0.6rem 0 0;
+  color: var(--muted);
 }
 
-.count {
-  margin: 0 0 1rem;
-  color: gray;
+/* --- cards & stats --------------------------------------------------------- */
+.card {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
 }
 
-form {
+.stats {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(8.5rem, 1fr));
+  gap: 0.9rem;
+  margin-bottom: 1.25rem;
+}
+.stat {
+  padding: 1rem 1.1rem;
+  border-left: 3px solid var(--accent);
+}
+.stat-indigo { border-left-color: #6366f1; }
+.stat-green  { border-left-color: #10b981; }
+.stat-amber  { border-left-color: #f59e0b; }
+.stat-slate  { border-left-color: #64748b; }
+.stat-value {
+  font-size: 1.7rem;
+  font-weight: 700;
+  text-transform: capitalize;
+}
+.stat-label {
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+/* --- task panel ------------------------------------------------------------ */
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  padding: 1.25rem;
+}
+
+.add {
   display: flex;
   gap: 0.5rem;
-  margin-bottom: 1rem;
+  margin-bottom: 0.9rem;
 }
-
-input[type="text"],
-form input {
+.add input {
   flex: 1;
   font: inherit;
-  padding: 0.5rem 0.7rem;
-  border: 1px solid rgba(127, 127, 127, 0.5);
-  border-radius: 8px;
+  padding: 0.6rem 0.8rem;
+  color: var(--text);
   background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+}
+.add input:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
 }
-
 button {
   font: inherit;
-  padding: 0.5rem 0.9rem;
-  border: 1px solid currentColor;
-  border-radius: 8px;
-  background: transparent;
   cursor: pointer;
+  border-radius: 10px;
+  border: 1px solid transparent;
+}
+.add button {
+  padding: 0.6rem 1.1rem;
+  color: #fff;
+  background: linear-gradient(135deg, var(--accent), var(--accent-2));
+}
+
+.filters {
+  display: flex;
+  gap: 0.4rem;
+  margin-bottom: 0.9rem;
+}
+.chip {
+  padding: 0.35rem 0.85rem;
+  color: var(--muted);
+  background: transparent;
+  border: 1px solid var(--border);
+}
+.chip-on {
+  color: var(--text);
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
 }
 
 .tasks {
@@ -55,37 +170,72 @@ button {
   margin: 0;
   padding: 0;
   display: grid;
-  gap: 0.4rem;
+  gap: 0.45rem;
 }
-
-.tasks li {
+.task {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 0.5rem;
-  padding: 0.5rem 0.7rem;
-  border: 1px solid rgba(127, 127, 127, 0.25);
-  border-radius: 8px;
-}
-
-.tasks li.done span {
-  text-decoration: line-through;
-  opacity: 0.6;
+  gap: 0.6rem;
+  padding: 0.6rem 0.75rem;
+  border: 1px solid var(--border);
+  border-radius: 10px;
 }
-
-.tasks label {
+.task label {
   display: flex;
   align-items: center;
-  gap: 0.5rem;
+  gap: 0.6rem;
   cursor: pointer;
 }
-
+.task input[type="checkbox"] {
+  width: 1.1rem;
+  height: 1.1rem;
+  accent-color: var(--accent);
+}
+.task.done span {
+  text-decoration: line-through;
+  color: var(--muted);
+}
 .delete {
   border: none;
+  background: transparent;
+  color: var(--muted);
   padding: 0.2rem 0.5rem;
-  opacity: 0.6;
+  font-size: 1rem;
 }
-
 .delete:hover {
-  opacity: 1;
+  color: #ef4444;
+}
+
+.empty {
+  text-align: center;
+  color: var(--muted);
+  padding: 1.5rem 0 0.5rem;
+}
+
+/* --- dev hint -------------------------------------------------------------- */
+.hint {
+  text-align: center;
+  color: var(--muted);
+  font-size: 0.9rem;
+  margin-top: 1.5rem;
+}
+.hint p {
+  margin: 0.2rem 0;
+}
+code {
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.85em;
+  padding: 0.1rem 0.35rem;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+}
+
+@media (max-width: 30rem) {
+  .add {
+    flex-direction: column;
+  }
+  .add button {
+    width: 100%;
+  }
 }

package/templates/basic/README.md

@@ -9,11 +9,18 @@ npm install
 npm run dev
 ```
 
-Then open the printed URL.
+```text
+  Zoijs dev server
+
+  - Local:  http://localhost:7310
+```
+
+Open the printed URL (it falls back to 7311–7313 if the port is busy).
 
 ## How it works
 
 - **`index.html`** — an import map points `@zoijs/core` at `node_modules`, then loads `src/app.js`.
+- **`dev-server.mjs`** — a tiny zero-dependency static server (Node built-ins only) that `npm run dev` runs.
 - **`src/app.js`** — your app: `createState` for state, `html` for markup, `mount` to render.
 - **`src/style.css`** — plain CSS.
 

package/templates/basic/dev-server.mjs

@@ -0,0 +1,74 @@
+// dev-server.mjs — a tiny static file server for this Zoijs app.
+//
+// Zero dependencies (Node built-ins only), no build step, no bundler. It serves
+// the project files so the import map in index.html can load @zoijs/core from
+// node_modules. Tries port 7310, then 7311 / 7312 / 7313 if one is busy.
+//
+//   node dev-server.mjs      (this is what `npm run dev` runs)
+
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { extname, join, normalize } from "node:path";
+
+const PORTS = [7310, 7311, 7312, 7313];
+const ROOT = process.cwd();
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+};
+
+const server = createServer(async (req, res) => {
+  let pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+  if (pathname === "/") pathname = "/index.html";
+
+  // Resolve inside ROOT and refuse anything that climbs out of it.
+  const filePath = join(ROOT, normalize(pathname));
+  if (!filePath.startsWith(ROOT)) {
+    res.writeHead(403).end("Forbidden");
+    return;
+  }
+  try {
+    const body = await readFile(filePath);
+    res.writeHead(200, { "Content-Type": TYPES[extname(filePath)] || "application/octet-stream" });
+    res.end(body);
+  } catch {
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }).end("Not found");
+  }
+});
+
+function start(i = 0) {
+  if (i >= PORTS.length) {
+    console.error(`\nAll dev ports are busy (${PORTS.join(", ")}). Free one and try again.\n`);
+    process.exit(1);
+  }
+  // Paired once-listeners: each attempt removes its sibling so a failed bind
+  // can't leave a stale "listening" handler that prints the wrong port later.
+  const onError = (err) => {
+    server.removeListener("listening", onListening);
+    if (err.code === "EADDRINUSE") start(i + 1);
+    else {
+      console.error(err);
+      process.exit(1);
+    }
+  };
+  const onListening = () => {
+    server.removeListener("error", onError);
+    const lines = ["", "  Zoijs dev server", "", `  - Local:  http://localhost:${PORTS[i]}`];
+    if (i > 0) lines.push(`  (ports ${PORTS.slice(0, i).join(", ")} were busy)`);
+    lines.push("");
+    console.log(lines.join("\n"));
+  };
+  server.once("error", onError);
+  server.once("listening", onListening);
+  server.listen(PORTS[i]);
+}
+
+start();

package/templates/basic/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "npx serve ."
+    "dev": "node dev-server.mjs"
   },
   "dependencies": {
     "@zoijs/core": "^1.1.0"