create-muten 0.0.2 → 0.0.4

package/README.md

@@ -60,10 +60,29 @@ In an interactive terminal it prompts for a few things (defaults in parentheses)
 | Prompt | Options | Default |
 |---|---|---|
 | **Project name** | any valid folder name | `muten-app` |
+| **Template** | `basic` / `routing` / `full` | `basic` |
 | **Stylesheet** | `css` / `scss` | `css` |
+| **Add Tailwind CSS?** | `Y` / `n` (CSS only) | `n` |
+| **Add DaisyUI?** | `Y` / `n` (needs Tailwind) | `n` |
 | **Package manager** | `npm` / `pnpm` / `yarn` / `bun` | the one that launched it |
 | **Install deps and start dev now?** | `Y` / `n` | `Y` |
 
+Tailwind is an optional add-on **on top of** CSS (the look layer; you still style via `class("…")`) — it
+wires `@tailwindcss/vite` + an `@import "tailwindcss"` and notes the setup in the app's `.claude/` guide.
+
+## Templates
+
+| Template | What you get |
+|---|---|
+| **basic** | one page — the minimal starter |
+| **routing** | a persistent shell (navbar + footer) + multiple real-path routes + a static `about` page |
+| **full** | routing + a `.store` + an `api` block + a source-backed products page + Tailwind — a real data app |
+
+When **Tailwind or DaisyUI** is selected, `theme.muten` is centralized to **match Tailwind's scale** (so
+`style()` tokens and Tailwind utilities share one scale, e.g. `style(gap.md)` == `gap-4`); plain CSS/SCSS
+keeps the default scale. **DaisyUI** adds component classes (`btn`, `card`, `modal`) usable in `class("…")` —
+the closest fit to shadcn that works in Muten (pure classes, no React; behavior is Muten state + `on()`).
+
 If you accept the last prompt it runs `<pm> install` followed by `<pm> run dev` — your app is live in a
 single step. Choosing SCSS also adds `sass` and switches the stylesheet to `.scss` automatically.
 
@@ -80,7 +99,10 @@ create-muten my-app --css --no-install    # just scaffold, decide later
 | Flag | Effect |
 |---|---|
 | `<name>` | the project folder (positional argument) |
+| `--template <basic\|routing\|full>` | which starter (default: `basic`; `full` implies Tailwind) |
 | `--css` / `--scss` | pick the stylesheet (default: `css`) |
+| `--tailwind` | add Tailwind CSS v4 on top of CSS (forces `--css`) |
+| `--daisyui` | add DaisyUI component classes (implies `--tailwind`) |
 | `--pm <npm\|pnpm\|yarn\|bun>` | package manager to use (default: detected) |
 | `--no-install` | scaffold only — don't install or start the dev server |
 | `--help` | print usage and exit |

package/index.js

@@ -1,111 +1,167 @@
 #!/usr/bin/env node
-// create-muten — scaffold a new Muten app. Zero runtime deps (Node built-ins only).
+// create-muten — scaffold a new Muten app, with modern interactive prompts (@clack/prompts).
 //
-//   npm create muten@latest [name]              (when published to npm)
-//   npx github:karttofer/create-muten [name]    (from GitHub, not yet public)
-//   create-muten [name] [--css|--scss] [--pm npm|pnpm|yarn|bun] [--no-install]
+//   npm create muten@latest [name]              (or: npx create-muten)
+//   create-muten [name] [--template basic|routing|full] [--css|--scss] [--tailwind] [--daisyui] [--pm npm|pnpm|yarn|bun] [--no-install]
 //
-// Interactive in a TTY (prompts for name, stylesheet, package manager); flags / non-TTY make it
-// scriptable. The package manager defaults to the one that invoked us. Then it scaffolds and,
-// unless --no-install, runs `<pm> install` + `<pm> run dev`.
+// Stylesheet (CSS or SCSS) is the base; Tailwind is an optional add-on ON TOP of CSS (it's a styling
+// library, not a stylesheet replacement). Interactive in a TTY; flags / non-TTY make it scriptable.
 import { cpSync, existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
+import { intro, outro, text, select, confirm, isCancel, cancel, note } from '@clack/prompts';
+import color from 'picocolors';
 
 const SELF = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(SELF, 'template');
+const OVERLAYS = join(SELF, 'overlays');   // additive layers per template variant (routing, full)
+const TEMPLATES = ['basic', 'routing', 'full'];
 const PKG = JSON.parse(readFileSync(join(SELF, 'package.json'), 'utf8'));
 const PMS = ['npm', 'pnpm', 'yarn', 'bun'];
 
-const BANNER = [
-  '',
-  '                  _',
-  '  _ __ ___  _   _| |_ ___ _ __',
-  " | '_ ` _ \\| | | | __/ _ \\ '_ \\",
-  ' | | | | | | |_| | ||  __/ | | |',
-  ' |_| |_| |_|\\__,_|\\__\\___|_| |_|',
-  '',
-  ' AI-first frontend framework',
-  '',
-].join('\n');
-
-// Which PM launched us? npm/pnpm/yarn/bun all set npm_config_user_agent (e.g. "pnpm/8.6 ...").
-// Detecting it is what create-vue/vite do — the idiomatic default, no guessing.
-const detectPM = () => {
-  const ua = process.env.npm_config_user_agent || '';
-  return PMS.find((p) => ua.startsWith(p + '/')) || 'npm';
+// the starter reset — written by the CLI so the template stays pure .muten (no default styles file).
+const RESET = `/* Your look. Muten ships STRUCTURE + LAYOUT (style() tokens); the LOOK lives here, via class("…"). */
+* { box-sizing: border-box; }
+body { margin: 0; font: 15px/1.55 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; color: #111; }
+h1, h2, h3, h4, h5, h6, p { margin: 0; }
+h1 { font-size: 32px; font-weight: 700; letter-spacing: -.02em; }
+.stack { display: flex; flex-direction: column; }
+img { max-width: 100%; display: block; }
+a { color: inherit; text-decoration: none; }
+`;
+// CSS + Tailwind v4: one @import + the @tailwindcss/vite plugin. Preflight does the reset, so this stays
+// minimal — only `.stack` (a Muten layout primitive Tailwind doesn't know). You style via class("…").
+const tailwindStyles = (daisyui) => `@import "tailwindcss";${daisyui ? '\n@plugin "daisyui";' : ''}
+
+/* Muten layout primitive Tailwind doesn't define */
+.stack { display: flex; flex-direction: column; }
+`;
+const TAILWIND_VITE = `import muten from '@muten/core/vite-plugin-muten.js';
+import tailwindcss from '@tailwindcss/vite';
+
+export default {
+  plugins: [muten(), tailwindcss()],
 };
-
-// Safe folder name: starts alphanumeric, then [A-Za-z0-9._-]. Blocks path traversal / odd input.
+`;
+// When Tailwind/DaisyUI is chosen, the Muten token scale is centralized to MATCH Tailwind's defaults, so
+// style() tokens and Tailwind utilities share one scale (e.g. style(gap.md) == gap-4 == 1rem). Plain
+// css/scss keeps the default theme.muten. (DaisyUI builds on Tailwind's scale; its colors come via @plugin.)
+const TAILWIND_THEME = `# Token SCALE aligned with Tailwind's defaults — style() tokens + Tailwind utilities share one scale.
+theme {
+  space       { xs "0.25rem"  sm "0.5rem"  md "1rem"  lg "1.5rem"  xl "2rem" }
+  font        { sm "0.875rem"  md "1rem"  lg "1.125rem"  xl "1.25rem" }
+  weight      { medium "500"  semibold "600"  bold "700" }
+  leading     { tight "1.25"  normal "1.5"  loose "2" }
+  breakpoints { sm "640px"  md "768px"  lg "1024px"  xl "1280px" }
+}
+`;
+const TAILWIND_NOTE = `
+## Styling: Tailwind CSS v4 (installed)
+This app has Tailwind ON TOP of CSS. Write the LOOK with \`class("…")\` using Tailwind utilities, e.g.
+\`class("flex gap-4 rounded-lg bg-zinc-900 text-white")\`. \`style()\` still owns Muten's layout/
+typography tokens — don't put Tailwind classes in \`style()\`, and don't put layout in \`class()\`.
+You can still add your own rules in \`src/styles.css\` below the \`@import "tailwindcss";\`.
+`;
+// DaisyUI = component CLASSES on top of Tailwind (no React). The "shadcn for Muten": pre-styled components
+// you drop into class("…"); behavior (open/close) you build with Muten state + class(when) + on(…).
+const DAISY_NOTE = `
+## DaisyUI (installed)
+DaisyUI adds **component classes** on top of Tailwind — use them in \`class("…")\`: \`class("btn btn-primary")\`,
+\`class("card bg-base-100 shadow-xl")\`, \`class("badge")\`, \`class("alert")\`. Pure classes, no React.
+\`@plugin "daisyui";\` is already in \`src/styles.css\`. Interactive behavior (toggle a modal/dropdown) you build
+with Muten: \`state\` + \`class(active when isOpen)\` + \`on(click: …)\`.
+`;
+
+// Which PM launched us? npm/pnpm/yarn/bun set npm_config_user_agent — the idiomatic default.
+const detectPM = () => { const ua = process.env.npm_config_user_agent || ''; return PMS.find((p) => ua.startsWith(p + '/')) || 'npm'; };
 const validName = (n) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n);
-const die = (msg) => { console.error(msg); process.exit(1); };
+const keep = (v) => { if (isCancel(v)) { cancel('Cancelled.'); process.exit(0); } return v; };
 
 async function main() {
-  // args: one positional name + optional flags (so the CLI is also scriptable / CI-friendly)
   const argv = process.argv.slice(2);
   const has = (f) => argv.includes(f);
   const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : undefined; };
   if (has('-v') || has('--version')) { console.log(PKG.version); return; }
-  console.log(BANNER);
-  if (has('-h') || has('--help')) { console.log('  Usage: create-muten [name] [--css|--scss] [--pm npm|pnpm|yarn|bun] [--no-install]\n'); return; }
+  if (has('-h') || has('--help')) { console.log('Usage: create-muten [name] [--template basic|routing|full] [--css|--scss] [--tailwind] [--daisyui] [--pm npm|pnpm|yarn|bun] [--no-install]'); return; }
 
-  let name = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--pm')[0];
-  let style = has('--scss') ? 'scss' : has('--css') ? 'css' : undefined;
+  let name = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--pm' && argv[i - 1] !== '--template')[0];
+  let template = val('--template') || (has('--full') ? 'full' : has('--routing') ? 'routing' : has('--basic') ? 'basic' : undefined);
+  let style = has('--scss') ? 'scss' : has('--css') ? 'css' : undefined;     // the base stylesheet
+  let tailwind = has('--tailwind') ? true : undefined;                        // optional add-on (CSS only)
+  let daisyui = has('--daisyui') ? true : undefined;                          // component classes on Tailwind
   let pm = val('--pm');
   let install = has('--no-install') ? false : undefined;
-
-  if (name && !validName(name)) die(`Invalid name: "${name}" (letters, digits, . _ -)`);
-  if (pm && !PMS.includes(pm)) die(`Unknown package manager: "${pm}" (${PMS.join(', ')})`);
-
+  if (name && !validName(name)) { console.error(`Invalid name: "${name}" (letters, digits, . _ -)`); process.exit(1); }
+  if (template && !TEMPLATES.includes(template)) { console.error(`Unknown template: "${template}" (${TEMPLATES.join(', ')})`); process.exit(1); }
+  if (pm && !PMS.includes(pm)) { console.error(`Unknown package manager: "${pm}" (${PMS.join(', ')})`); process.exit(1); }
   const dpm = detectPM();
 
-  // Prompt only with a real TTY — piped/CI input drops lines through readline, so there we use
-  // flags + defaults instead of hanging on a prompt.
+  // Styled prompts only with a real TTY (piped/CI input would hang); otherwise use flags + defaults.
   if (process.stdin.isTTY) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const ask = async (q, def) => (await rl.question(q)).trim() || def;
-    const pick = async (q, opts, def) => {
-      for (;;) {
-        const v = (await ask(q, def)).toLowerCase();
-        if (opts.includes(v)) return v;
-        console.log(`  Choose: ${opts.join(', ')}.`);
-      }
-    };
-    while (!name) {
-      const a = await ask('Project name: (muten-app) ', 'muten-app');
-      if (validName(a)) name = a; else console.log('  Letters, digits, . _ - (start alphanumeric).');
-    }
-    if (!style) style = await pick('Stylesheet? [css/scss] (css) ', ['css', 'scss'], 'css');
-    if (!pm) pm = await pick(`Package manager? [${PMS.join('/')}] (${dpm}) `, PMS, dpm);
-    if (install === undefined) install = (await ask('Install deps and start the dev server now? [Y/n] ', 'y')).toLowerCase() !== 'n';
-    rl.close();
+    intro(color.bgCyan(color.black(' create-muten ')) + color.dim('  the AI-first frontend framework'));
+    if (!name) name = keep(await text({ message: 'Project name', placeholder: 'muten-app', defaultValue: 'muten-app', validate: (v) => (v && !validName(v)) ? 'Use letters, digits, . _ - (start alphanumeric).' : undefined }));
+    if (!template) template = keep(await select({ message: 'Template', options: [
+      { value: 'basic', label: 'Basic', hint: 'one page' },
+      { value: 'routing', label: 'Routing', hint: 'shell + multiple pages' },
+      { value: 'full', label: 'Routing + store + API + Tailwind', hint: 'a real data app' },
+    ] }));
+    if (template === 'full') tailwind = true;   // the full template implies Tailwind
+    // Tailwind is an add-on on top of CSS (Tailwind v4 is CSS-native; Sass isn't recommended).
+    if (!style && !tailwind) style = keep(await select({ message: 'Stylesheet', options: [
+      { value: 'css', label: 'CSS', hint: 'plain, zero deps' },
+      { value: 'scss', label: 'SCSS', hint: 'adds sass' },
+    ] }));
+    if (tailwind === undefined) tailwind = style === 'css' ? keep(await confirm({ message: 'Add Tailwind CSS? (utility classes via class("…"))', initialValue: false })) : false;
+    if (tailwind && daisyui === undefined) daisyui = keep(await confirm({ message: 'Add DaisyUI? (component classes: btn, card, modal…)', initialValue: template === 'full' }));
   }
   name = name || 'muten-app';
+  template = template || 'basic';
+  if (template === 'full') tailwind = true;     // full implies Tailwind
+  if (daisyui) tailwind = true;                 // DaisyUI is a Tailwind plugin
   style = style || 'css';
+  if (tailwind === undefined) tailwind = false;
+  if (daisyui === undefined) daisyui = false;
+  if (tailwind) style = 'css';            // Tailwind implies a CSS base (not SCSS)
   pm = pm || dpm;
   if (install === undefined) install = false;
 
   const target = resolve(name);
-  if (existsSync(target)) die(`"${name}" already exists.`);
+  if (existsSync(target)) { (process.stdin.isTTY ? cancel : console.error)(`"${name}" already exists.`); process.exit(1); }
 
-  // scaffold from ./template
+  // scaffold from ./template (the basic base) + layer the chosen variant's overlay + the stylesheet/add-ons
   cpSync(TEMPLATE, target, { recursive: true });
-  const ignore = join(target, '_gitignore');                        // npm strips a real .gitignore on publish
+  if (template !== 'basic') cpSync(join(OVERLAYS, template), target, { recursive: true });  // routing / full overlay
+  const ignore = join(target, '_gitignore');
   if (existsSync(ignore)) renameSync(ignore, join(target, '.gitignore'));
-  if (style === 'scss') renameSync(join(target, 'src', 'styles.css'), join(target, 'src', 'styles.scss')); // plugin auto-detects
 
   const pkgPath = join(target, 'package.json');
   const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   pkg.name = name;
-  if (style === 'scss') pkg.devDependencies = { ...(pkg.devDependencies || {}), sass: '^1.101.0' };
+  const addDev = (deps) => { pkg.devDependencies = { ...(pkg.devDependencies || {}), ...deps }; };
+
+  if (tailwind) {
+    writeFileSync(join(target, 'src', 'styles.css'), tailwindStyles(daisyui));
+    writeFileSync(join(target, 'vite.config.mjs'), TAILWIND_VITE);
+    writeFileSync(join(target, 'theme.muten'), TAILWIND_THEME);          // scale centralized to Tailwind's
+    addDev({ tailwindcss: '^4.0.0', '@tailwindcss/vite': '^4.0.0' });
+    if (daisyui) addDev({ daisyui: '^5.0.0' });
+    const agents = join(target, '.claude', 'AGENTS.md');                 // tell the AI what styling is available
+    if (existsSync(agents)) writeFileSync(agents, readFileSync(agents, 'utf8') + TAILWIND_NOTE + (daisyui ? DAISY_NOTE : ''));
+  } else {
+    writeFileSync(join(target, 'src', style === 'scss' ? 'styles.scss' : 'styles.css'), RESET);
+  }
+  if (style === 'scss') addDev({ sass: '^1.101.0' });
   writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 
-  console.log(`\n  Created ${name}  (${style}, ${pm})\n`);
-
-  if (!install) { console.log(`  cd ${name}\n  ${pm} install\n  ${pm} run dev\n`); return; }
+  const desc = `${template}, ${style}${tailwind ? ' + Tailwind' : ''}${daisyui ? ' + DaisyUI' : ''}`;
+  if (!install) {
+    if (process.stdin.isTTY) { note(`cd ${name}\n${pm} install\n${pm} run dev`, 'Next steps'); outro(color.green(`Created ${name}  (${desc})`)); }
+    else console.log(`\n  Created ${name} (${desc}, ${pm})\n  cd ${name} && ${pm} install && ${pm} run dev\n`);
+    return;
+  }
 
+  if (process.stdin.isTTY) outro(color.green(`Created ${name} (${desc}) — installing with ${pm}…`));
   // PMs are .cmd shims on Windows → spawn needs shell:true to find them.
   const run = (a) => spawnSync(pm, a, { cwd: target, stdio: 'inherit', shell: process.platform === 'win32' });
   if (run(['install']).status === 0) run(['run', 'dev']);

package/overlays/full/src/app.muten

@@ -0,0 +1,21 @@
+# The app ROOT. `api` is the backend config (one place: base URL + default headers) — every `sources`
+# inherits it. The shell's navbar reads the cart store (global) and shows a live count.
+api {
+  base: "https://fakestoreapi.com"
+}
+
+shell {
+  Header style(row, between, center) class("p-4 shadow bg-white") {
+    Link "Shop" -> / class("text-xl font-bold")
+    Nav "Main" style(row, gap.md, center) {
+      Link "Products" -> /products
+      Span "🛒 {cart.count}" class("font-medium")
+    }
+  }
+  slot
+}
+
+routes {
+  /         -> home
+  /products -> products
+}

package/overlays/full/src/cart.store

@@ -0,0 +1,9 @@
+# An app-global store (any `*.store` under src/). State is shared across pages + the shell, no imports.
+# `get` is a derived value; `action`s are the only way to mutate.
+store { items = [] : list<text> }
+
+get count = items.length
+
+action add mutates items <- id {
+  items.push(id)
+}

package/overlays/full/src/pages/products/products.muten

@@ -0,0 +1,26 @@
+# A real data page: `query` state backed by a `sources` URL (relative → joined to the app's `api.base`).
+# `muten build` fetches it at build and bakes the rows into the HTML (SSG); the runtime then takes over.
+# Clicking "Add" calls the cart store action — the navbar count updates reactively.
+screen products
+
+meta { title "Products" }
+
+entity Product { title text  price text }
+
+state { products = query products : list<Product> }
+
+sources { products: "/products" }
+
+Page style(padding.lg, gap.md) {
+  Title "Products" class("text-2xl font-bold")
+  when products.loading { Text "Loading…" class("opacity-60") }
+  each products as p {
+    Stack style(gap.sm) class("p-4 rounded-lg shadow bg-white") {
+      Text "{p.title}" class("font-semibold")
+      Stack style(row, between, center) {
+        Span "$ {p.price}" class("text-lg")
+        Button "Add to cart" -> cart.add(p.id) class("px-3 py-1 rounded bg-black text-white")
+      }
+    }
+  }
+}

package/overlays/routing/src/app.muten

@@ -0,0 +1,19 @@
+# The app ROOT. A persistent `shell { … slot … }` wraps every page (navbar here); `slot` is where the
+# active page mounts. `routes` maps a real-path URL to a page (the folder under src/pages/).
+shell {
+  Header style(row, between, center) class("nav") {
+    Link "Home" -> /
+    Nav "Main" {
+      Link "About" -> /about
+    }
+  }
+  slot
+  Footer style(padding.md) {
+    Text "Built with Muten"
+  }
+}
+
+routes {
+  /      -> home
+  /about -> about
+}

package/overlays/routing/src/pages/about/about.muten

@@ -0,0 +1,15 @@
+# A second page. `meta { … }` sets the <head> title/description (og:* auto-derived) — applied on
+# navigation and baked into the static HTML at build. This page has no reactivity, so `muten build`
+# pre-renders it to zero-JS HTML (crawlable).
+screen about
+
+meta {
+  title "About"
+  description "About this Muten app."
+}
+
+Page style(padding.lg, gap.md) {
+  Title "About"
+  Text "Static pages compile to zero-JS HTML at build — crawlable and instant."
+  Link "← Home" -> /
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-muten",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Scaffold a new Muten app.",
   "repository": {
     "type": "git",
@@ -14,6 +14,10 @@
   "bin": {
     "create-muten": "index.js"
   },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.1"
+  },
   "keywords": ["muten", "create-muten", "scaffold", "starter", "cli", "frontend"],
-  "files": ["index.js", "template"]
+  "files": ["index.js", "template", "overlays"]
 }

package/template/.claude/AGENTS.md

@@ -0,0 +1,64 @@
+# Working in a Muten app — guide for AI agents
+
+This project uses **Muten**, an AI-first frontend framework. The UI is written in **`.muten` files**
+(a small declarative DSL) — **not** React, JSX, Vue, Svelte or hand-written HTML/JS. No model is
+trained on Muten yet, so **follow this guide instead of guessing**: never import React/Vue, never write
+`.jsx`/`.vue`, never add a JS bootstrap.
+
+> Full language reference (every primitive, prop, token, pattern): the **`muten` skill** at
+> [`skills/muten/SKILL.md`](skills/muten/SKILL.md).
+
+## Golden rules
+- UI → `.muten` files. App-global state → `.store` files. Both compile via the `@muten/core` Vite plugin.
+- **No `main.js`.** `src/app.muten` IS the entry (loaded by `index.html`). Never add a JS entry/bootstrap.
+- Primitives are **PascalCase** (`Stack`, `Text`, `Button`); control flow is lowercase (`when`, `each`).
+- **`style(...)`** = layout/typography tokens (Muten builds STRUCTURE). **`class("...")`** = your look
+  (your CSS / Tailwind). Muten ships no skin — appearance is yours.
+- State references use `@name`; interpolate in any string with `{expr}`: `Text "Hi, {user.name}"`.
+
+## File map
+```
+src/
+  app.muten                    ROOT — routes { /url -> page }  (+ optional shell { … slot … })
+  pages/<route>/<route>.muten  a page; the folder name IS the route
+  parts/<name>.muten           reusable component (composition, inlined at build)
+  components/<Name>.js          escape hatch (host JS) used via the `Custom` primitive
+theme.muten                    design tokens: space, font, weight, breakpoints
+src/styles.css                 your look (.scss if you picked SCSS)
+```
+
+## A page looks like this
+```
+screen home
+
+Page style(padding.lg, gap.md) {
+  Title "Hello"
+  Text "Body copy with reactive state: {user.name}"
+  Button "Save" -> save
+}
+```
+
+## Cheat-sheet
+- **Layout:** `Stack` (vertical), `Page` (`<main>`), `Header`/`Nav`/`Sidebar`/`Footer` (landmarks). Horizontal = `style(row)`.
+- **Content:** `Text`, `Title "x" h2`, `Span`, `Image "{src}" alt "…"` (alt required), `Link "x" -> /route`, `Button "x" -> action(arg)`.
+- **Data:** `DataTable @list columns(a, b)`, `Form bind @draft submit create`, `SearchField bind @q`.
+- **Control:** `when <expr> { … }`, `each <list> as item { … }`.
+- **Interactivity:** reactive class `class(active when isOpen)`; events on any element `on(keydown: act, mouseenter: act)`; a `/404` route catches unmatched paths.
+- **State:** `state { q = "" : text  users = query listUsers : list<User> }` — query states expose `.loading/.error/.data`.
+- **Backend:** `sources { x: { url, method?, headers?, body?, at? } }` feeds a `query`. Shared base+auth go in `api { base, headers }` (app.muten, named clients via `{ api: "shop" }`) — relative source urls join to `base`. GET sources pre-render at build (SSG).
+- **Writes:** a source-backed list gets `create`/`update`/`delete` in an action (`orders.create(draft)` → POST/PUT/DELETE the resource, optimistic + updates the list). The action is async with reactive `name.pending`/`name.error` for UX. Local-only mutations stay `push`/`set`/`reset`/`remove`.
+- **Refetch:** re-run a query with N params (search / paginate / filter): `products.refetch(q: term, page: n)` in an action → builds `?q=&page=` and reloads the list.
+- **Escape hatch:** non-RESTful API? `post`/`put`/`delete` a `"client:/path"` (interpolated) with optional `body` in an action: `post "shop:/orders" body item`. Uses the client's base+headers; `mutates` is optional for pure commands.
+- **Actions:** `action add mutates users <- item { users.push(item) }` — ops: `push/set/reset/remove`; branch with `if/else`.
+- **Tokens:** `gap.md padding.lg cols.3 text.lg row center between` — responsive prefix: `md:cols.2`.
+
+## Dependencies & limits
+- **CSS / Tailwind / SCSS: YES** — it's a Vite app; install them and use `class("…")` + your CSS.
+- **React / Vue / Svelte UI libraries: NO** — the UI is `.muten` (vanilla DOM, no JS framework runtime).
+  Need a JS widget? Wrap it in a `Custom` host component (`src/components/<Name>.js`).
+- Routing uses **real paths** (`/path`, History API; deploy serves `index.html` for any path); route params work (`/product/:id` → `param id`). SEO: `meta { title "…" description "…" }` per page → `<head>` tags (og auto-derived). Shell has no local state → use a
+  `.store`. No `toggle` op → `set(not x)`. `style()` is layout tokens only; visuals go in `class()`.
+- The full reference (stores, routing, theme, every primitive) is in [`skills/muten/SKILL.md`](skills/muten/SKILL.md).
+
+## Commands
+`npm run dev` (dev server + HMR) · `npm run build` (production) · `npm run lint` (validate `.muten`).

package/template/.claude/skills/muten/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: muten
+description: Read and write Muten — the AI-first frontend DSL this app is built in (.muten and .store files), NOT React/Vue/HTML. Use whenever creating or editing any .muten or .store file, app.muten routes, theme.muten, parts, components, stores, or deciding what can be installed. No model is trained on Muten, so consult this before writing any Muten code or adding a dependency. Assume the human will NOT read the code — you do everything.
+---
+
+# Muten — complete language reference
+
+Muten compiles `.muten` files to vanilla JS + fine-grained signals (no virtual DOM). The `@muten/core`
+Vite plugin does the compiling. You write a small declarative DSL — **never** React/JSX/Vue/Svelte/HTML.
+A page with no reactivity compiles to plain zero-runtime HTML; a reactive one ships ~1KB of signals.
+
+## Mental model & golden rules
+- **UI** → `.muten` files (pages, parts, the app root, the theme). **App-global state** → `.store` files.
+- **`src/app.muten` is the entry.** `index.html` loads it; the plugin boots it. **Never create `main.js`** or a `<script>` bootstrap.
+- Primitives are **PascalCase** (`Stack`, `Text`); keywords/control flow are **lowercase** (`when`, `each`, `state`).
+- `style(...)` = layout/typography **tokens** (Muten builds STRUCTURE). `class("...")` = **look** (your CSS / Tailwind); toggle reactively with `class(active when isOpen)`. Muten ships no skin.
+- `@name` = a state reference. `{expr}` = interpolation inside any string: `Text "Hi, {user.name}"`.
+- Each page has **one root node**. Reactivity is automatic: reading a state in interpolation / `when` / `each` re-renders just that spot.
+
+## 1. What you CAN install / use
+This is a normal **Vite** project, so the whole Vite/npm ecosystem for **styling, build, and data** works:
+- **Tailwind CSS — YES.** Install it (`tailwindcss`, `postcss`, `autoprefixer`), add the config + the
+  `@tailwind` directives to `src/styles.css`, and use utilities via `class("flex gap-4 rounded")`.
+  `class()` emits raw class names, so any CSS framework (Tailwind, UnoCSS, Bootstrap CSS, your own CSS) works.
+- **Sass/SCSS** — supported out of the box if you scaffolded with SCSS (or add `sass`); use `src/styles.scss`.
+- **Any Vite plugin / PostCSS plugin** — add it to `vite.config.mjs` alongside `muten()`.
+- **Data / utility npm packages** — usable inside `.store` logic and inside `Custom` host components
+  (date libs, fetch wrappers, zod, etc.).
+- **Host UI via the `Custom` primitive** — write vanilla JS in `src/components/<Name>.js` (charts,
+  maps, a third-party widget) and mount it with `Custom`. See §Custom.
+
+## 2. What you CANNOT do
+- **No React / Vue / Svelte component libraries as UI.** There is no React/Vue runtime — the UI is
+  `.muten` compiled to vanilla DOM. You cannot drop in MUI, Chakra, Ant, shadcn, a React table, etc.
+  If you truly need a JS widget, wrap it yourself in a `Custom` component (vanilla JS).
+- **No JSX / `.jsx` / `.vue` / hand-written DOM in pages.** No `className`, no hooks, no lifecycle.
+- **No arbitrary inline CSS via `style()`** — `style()` only takes the layout/typography tokens below.
+  Visual styling (colors, borders, shadows) goes through `class("…")` + your CSS.
+
+## 3. Limitations (current)
+- **Routing uses real paths** (`/path`, History API). Route params ARE supported: `/product/:id` → declare `param id`
+  in the page (see §10). `muten build` pre-renders pages to real HTML (SSG) so content is crawlable —
+  static pages ship zero JS; reactive pages get their content (lists, `each`, interpolation from mock data)
+  baked into the HTML, then the runtime boots for interactivity. No special syntax needed.
+- **Shell has no local state** — put shell/cross-page state in a `.store` (see the mobile-menu pattern).
+- **No `toggle` op** — flip a bool with `set(not x)`.
+- **Forms**: `Form` (auto-generated from an entity) and `SearchField` (single text input) are the
+  built-ins; richer custom inputs need a `Custom` component for now.
+- **Pages are single-root** (one top node per page).
+
+## 4. Files
+```
+src/app.muten                    routes (+ optional shell) — the ROOT; read it first
+src/pages/<route>/<route>.muten  one page; the folder name IS the route
+src/parts/<name>.muten           reusable component (inlined at build time)
+src/components/<Name>.js          host-JS escape hatch, mounted via Custom
+src/<domain>.store               app-global state slice (domain = file name)
+theme.muten                      token scale (space/font/weight/leading/breakpoints)
+src/styles.css                   reset + look (or styles.scss)
+index.html / vite.config.mjs     wired to @muten/core; don't hand-edit the boot
+```
+
+## 5. Declarations
+```
+screen <name>                    # page identity (first line of a page)
+
+entity User {                    # data shape + validation (implicit `id uuid`)
+  name  text  required           # constraints: required | min:N | max:N
+  email email required
+  role  admin | member           # `a | b | c` = enum
+}
+
+state {                          # page-LOCAL reactive state
+  q     = ""              : text
+  users = query listUsers : list<User>   # query → async; exposes @users.loading/.error/.data
+}
+
+const TAX = 0.21                 # compile-time immutable scalar (inlined, never reactive)
+
+action add mutates users <- item {   # mutation; `mutates` lists what it may change (enforced)
+  users.push(item)               # ops: push | set | reset | remove
+  if item.vip { rating.set(5) } else { rating.set(1) }   # if/else = the only branching in actions
+}
+
+mock    { listUsers: [ { name: "Ana", role: admin } ] }          # mock data for a query
+sources { listUsers: { url: "https://api…", at: "results" } }    # real data source for a query
+```
+
+A `sources` entry is a complete HTTP request — a bare URL, or `{ url, method?, headers?, body?, at? }`:
+```
+sources {
+  products: "https://api.shop.com/products"                              # GET, response is the array
+  orders:   { url: "https://api…/orders", headers: { Authorization: "Bearer KEY" }, at: "data" }
+  search:   { url: "https://api…/graphql", method: "POST", body: { query: "…" }, at: "data" }
+}
+```
+- `at` reads the array out of `json[at]` — dotted for nested envelopes (`"data.posts"`). Else the response IS the array. `body` is JSON-encoded (sets `content-type`).
+- At build (`muten build`), **GET** sources are fetched and baked into the HTML (SSG); non-GET run only client-side (no build side-effects).
+- **Headers ship to the client** like any browser fetch — use public keys or a per-user token, never a server secret.
+
+**Don't repeat the backend — `api { }` in `src/app.muten`** sets the base URL + default headers for ALL sources:
+```
+# src/app.muten
+api { base: "https://api.shop.com/v1"  headers: { Authorization: "Bearer KEY" } }
+```
+```
+# any page — only what differs
+sources {
+  products: { url: "/products", at: "data" }     # → https://api.shop.com/v1/products, with the Authorization header
+  orders:   { url: "/orders",   at: "data" }
+}
+```
+A **relative** source url is joined to `base`; an **absolute** one (`https://…`) ignores it (other host). Source headers override the api defaults. Define the backend once.
+
+**Multiple backends** — name the clients, pick one per source with `{ api: "name" }`:
+```
+# src/app.muten
+api {
+  shop: { base: "https://api.shop.com/v1", headers: { Authorization: "Bearer KEY" } }
+  cms:  { base: "https://cms.io/api" }
+}
+```
+```
+sources {
+  products: { api: "shop", url: "/products", at: "data" }
+  posts:    { api: "cms",  url: "/posts",    at: "data.posts" }
+}
+```
+No `api` field → the client named `default`. The flat `api { base, headers }` form is just a single default client.
+
+**Writing to the backend (POST/PUT/DELETE)** — a source-backed list gets `create`/`update`/`delete` in an action, fired by an event; each hits the resource endpoint (reusing the source's `api` base + headers) and updates the list reactively:
+```
+state { orders = query orders : list<Order> }
+sources { orders: { api: "shop", url: "/orders", at: "data" } }
+
+action buy  mutates orders <- item { orders.create(item) }   # POST   /orders       → append the result
+action edit mutates orders <- item { orders.update(item) }   # PUT    /orders/{id}  → replace by id
+action drop mutates orders <- item { orders.delete(item) }   # DELETE /orders/{id}  → remove by id
+
+Button "Buy" -> buy(product)
+```
+The write action is **async** and exposes reactive **`buy.pending`** (true while in flight) and **`buy.error`** — use them for UX:
+```
+when buy.pending { Text "Saving…" }
+when buy.error { Text "Could not save: {buy.error}" }
+```
+`create`/`update`/`delete` are **optimistic** — the list changes instantly, reconciles with the server response, and **reverts** if the request fails (with `.error` set). REST convention: create = POST to the collection, update/delete target `/{item.id}`. Local-only mutations stay `push`/`set`/`reset`/`remove`; `create/update/delete` talk to the server.
+
+**Re-running a query — `refetch` (search / pagination / filters)** — call it in an action with **N named params**; they become the query string (`?q=…&page=…`, url-encoded) and the list reloads. Works for any web-app, not just lists:
+```
+state { q = "" : text  page = 1 : number  products = query products : list<Product> }
+sources { products: { url: "/products", at: "data" } }
+
+action search mutates products <- term { products.refetch(q: term, page: 1) }
+action next   mutates products         { page.set(page + 1)  products.refetch(q: q, page: page) }
+
+SearchField bind q
+Button "Search" -> search(q)
+Button "Next"   -> next
+```
+Pass as many params as you need (`q`, `page`, `sort`, `category`, …). The query's `.loading`/`.error` reflect the refetch.
+
+**Escape hatch — explicit request** (when the API isn't RESTful): `post`/`put`/`delete` a `"client:/path"` (interpolated) with an optional `body`, in an action:
+```
+action buy    <- item { post "shop:/orders" body item }        # any method, any path
+action cancel <- o    { delete "shop:/orders/{o.id}/cancel" }   # custom path, interpolated
+action ping           { post "shop:/health" }                   # no body, no `mutates` needed
+```
+It uses the named client's base + headers; the action is async with `.pending`/`.error`. Prefer `create`/`update`/`delete` when the API is RESTful (those also update the list); reach for `post`/`put`/`delete` only when the convention doesn't fit.
+
+## 6. Primitives
+A bare string is the node's main prop. `{ }` = children. Lay out with `style()`, skin with `class()`.
+
+| Primitive | Use | Example |
+|---|---|---|
+| `Stack` | vertical stack (flex column) | `Stack style(gap.md) { … }` |
+| `Page` | page root `<main>` (one per route) | `Page style(padding.lg) { … }` |
+| `Header`/`Nav`/`Sidebar`/`Footer` | landmarks | `Header style(row, between, center) { … }` |
+| `Text` | paragraph, interpolates | `Text "Hi, {user.name}"` |
+| `Title` | heading; level keyword | `Title "Dashboard" h2` |
+| `Span` | inline text | `Span "{cart.total}"` |
+| `Image` | `<img>`, **alt required** | `Image "{p.image}" alt "{p.title}"` |
+| `Link` | client-side nav | `Link "Catalog" -> /catalog` |
+| `Button` | runs an action | `Button "Save" -> save(draft)` |
+| `SearchField` | text input bound to state | `SearchField bind @q "Search…"` |
+| `Form` | auto-form from an entity draft | `Form bind @draft submit create "Save"` |
+| `DataTable` | reactive table over a list/query | `DataTable @users columns(name, email)` |
+| `RowAction` | a button inside each table row | `RowAction "Delete" -> remove(row.id)` |
+| `slot` | outlet inside `shell` | `slot` |
+| `Custom` | host-JS escape hatch | `Custom Chart inputs(data: @sales) on(pick: select)` |
+
+Horizontal layout = a region with `style(row)` (there is no `Row` primitive). Clickable card =
+`Button { … }` or `Link "" -> /x { … }` with children instead of a label.
+
+Modifiers (after a primitive): `style(tokens)` · `class("css")` · `bind @state` · `submit action` ·
+`where(clauses)` · `columns(a, b)` · `alt "…"` · `inputs(k: v)` · `on(event: action)`.
+`class()` also toggles reactively (`class(active when isOpen)`); `on(event: action)` works on **any** element
+(keydown, mouseenter, change, blur, …) and calls the action — use `Button -> action(arg)` when you need an arg.
+
+## 7. Theme — how it works
+`theme.muten` supplies the **scale** (values); the engine owns only the **vocabulary** (token names).
+```
+theme {
+  space       { xs "4px"  sm "8px"  md "16px"  lg "24px"  xl "32px" }
+  font        { sm "13px"  md "15px"  lg "20px"  xl "28px" }
+  weight      { medium "500"  bold "700" }
+  leading     { tight "1.2"  normal "1.5" }
+  breakpoints { sm "640px"  md "768px"  lg "1024px" }
+}
+```
+A token like `gap.md` resolves to `gap: 16px` via `space.md`; `text.lg` → `font.lg`; `md:cols.2` uses
+`breakpoints.md`. **No CSS/reset goes in `theme.muten`** — the reset and the look live in `src/styles.css`.
+
+### Style tokens (`style(...)`)
+```
+row column wrap grid grow center between
+gap.sm|md|lg   padding.md|lg   padding.x.md   padding.y.md   margin.md
+cols.2|3|auto  rows.2
+text.sm|md|lg|xl   weight.medium|bold   leading.normal   italic   bold
+align.left|center|right   justify.center|between   items.center|start
+width.full   height.full
+```
+Responsive: prefix any token with a breakpoint → `md:cols.2`, `lg:cols.4` (`sm/md/lg/xl`).
+
+## 8. State, actions & reactivity
+- `state` cells are signals; reading them in interpolation / `when` / `each` auto-updates that spot.
+- `query` state is async → render with `when @x.loading { … }`, then use `@x.data`.
+- Mutate **only** through `action`s, and only the state in `mutates` (the linter enforces it):
+  - `list.push(x)` (append; auto-fills uuid fields) · `s.set(v)` · `s.reset()` · `list.remove(x => x.id == id)`
+  - There is no `toggle`: `flag.set(not flag)`.
+- Control flow in the tree: `when <expr> { … }` (mount/unmount), `each <list> as item { … }` (item is a scope var).
+- Expressions: `== != < > <= >=`, `and or not`, `contains` (case-insensitive substring / list membership),
+  `+ - * /`, ternary `c ? a : b`, parentheses, refs (`user.name`, `cart.total`, `$item.x`).
+
+## 9. Stores — app-global state
+A `.store` file = state shared across pages, **no prop drilling**. The file name is the domain.
+```
+# src/ui.store   → referenced everywhere as ui.<member>
+state  { menuOpen = false : bool }
+get    isOpen = menuOpen                 # derived/memoized value (read as ui.isOpen)
+action toggleMenu mutates menuOpen <- x { menuOpen.set(not menuOpen) }
+effect { /* runs whenever the store state it reads changes */ }
+```
+Use it from any page/shell by name: `when ui.menuOpen { … }`, `Button "☰" -> ui.toggleMenu`. The Vite
+plugin auto-detects every `.store` file. `get` = memoized; `effect` = reactive side-effect (Angular-style).
+
+## 10. Routing — how it works
+`src/app.muten` maps URLs to pages. It uses **real paths** (`/about`, History API — client-side nav, no
+reload); the **first route is the default**. The folder under `src/pages/` must match the page name.
+*(Deploy: the host must serve `index.html` for any path — standard SPA fallback.)*
+```
+routes {
+  /         -> home               # src/pages/home/home.muten
+  /about    -> about              # static page → compiles to zero-runtime HTML
+  /cart     -> cart guard auth.loggedIn else /login    # guard: a store boolean; redirect if false
+  /login    -> login guard not auth.loggedIn else /     # guest-only page
+}
+```
+Guards read a **store boolean**; when it flips (login/logout) the active route re-renders automatically.
+A route named `/404` catches any unmatched path (otherwise the first route is shown).
+Navigate with `Link "x" -> /path` (client-side, no reload).
+
+**Route params:** a `:seg` in the route captures a URL value. The page declares it with `param <name>`,
+then uses it as a read-only string in interpolation / `when` / expressions (it can't be mutated):
+```
+# app.muten
+routes { /product/:id -> product }
+# src/pages/product/product.muten
+screen product
+param id
+Page { Title "Product {id}" }
+```
+Navigating `/product/1` → `/product/2` re-mounts the page with the new `id` (re-fetch the new item).
+
+**`<head>` meta (SEO):** a page declares `meta { title "…" description "…" }` → `<title>` + `<meta>` tags
+(`og:title`/`og:description` auto-derived). Applied on navigation and baked into the SSG HTML at build.
+
+### Shell (persistent chrome)
+Wrap routes in a `shell { … slot … }` for a nav/footer around every page. `slot` is where the active
+page mounts. The shell has **no local state** → use a store for things like a mobile menu:
+```
+shell {
+  Header style(row, between, center) class("nav") {
+    Link "Home" -> /
+    Button "☰" -> ui.toggleMenu class("burger")
+  }
+  when ui.menuOpen { Stack class("mobile-menu") { Link "About" -> /about } }
+  slot
+  Footer { Span "© 2026" }
+}
+routes { / -> home }
+```
+
+## 11. Entities, forms & validation
+`entity` defines a shape + constraints. `Form bind @draft submit create` auto-renders one input per
+field and validates on submit (per-field `.field-error`), blocking the action if invalid.
+```
+entity Task { title text required  notes text  done bool }
+state  { draft = {} : Task  tasks = [] : list<Task> }
+action create mutates tasks, draft <- t { tasks.push(draft)  draft.reset() }
+# in the page:  Form bind @draft submit create "Add task"
+```
+
+## 12. Parts — reusable composition
+`part` = a reusable fragment, **inlined at build** (not a runtime component). Pass OBJECTS (`$x.field`)
+and ACTION callbacks (`-> $onPick(...)`).
+```
+# src/parts/feature.muten
+part Feature(item: Feature, onPick: action) {
+  Stack style(column, gap.sm) class("card") {
+    Title "{$item.title}" h3
+    Text  "{$item.body}"
+    Button "Choose" -> $onPick($item.id)
+  }
+}
+# use it:  Feature(item: f, onPick: select)
+```
+
+## 13. Custom — the host-JS escape hatch
+For anything Muten can't express (a chart, a 3rd-party widget), write vanilla JS in
+`src/components/<Name>.js` and mount it with `Custom`. It receives `inputs` (values/state) and wires
+DOM events to your actions via `on`. This is the ONLY way to use non-Muten UI code.
+```
+Custom Chart inputs(data: @sales) on(pointSelect: select)
+# → src/components/Chart.js exports a mount(el, { inputs, on }) that builds vanilla DOM.
+```
+
+## 14. Gotchas
+- It's NOT React: PascalCase primitives + `{ }` children; no JSX/hooks/`className`.
+- No `main.js`/`<script>` — `app.muten` is the entry.
+- `style()` (layout tokens) ≠ `class()` (look). No colors/borders in `style()`.
+- `Image` without `alt` fails validation (`alt ""` for decorative).
+- Actions may only touch their declared `mutates`.
+- Want a library? If it's CSS → `class()`. If it's a JS widget → `Custom`. If it's React/Vue UI → not possible.
+
+## 15. Minimal full app
+```
+# src/app.muten
+routes { / -> home }
+
+# src/pages/home/home.muten
+screen home
+state  { name = "" : text }
+action greet mutates name <- v { name.set(v) }
+
+Page style(padding.lg, gap.md) {
+  Title "Hello"
+  SearchField bind @name "Your name"
+  when name { Text "Hi, {name}!" }
+}
+```
+Validate anytime: `npm run lint`.

package/template/package.json

@@ -8,7 +8,7 @@
     "lint": "muten lint"
   },
   "dependencies": {
-    "@muten/core": "^0.0.2",
+    "@muten/core": "^0.0.3",
     "vite": "^8.0.16"
   }
 }

package/template/theme.muten

@@ -4,5 +4,6 @@ theme {
   space       { xs "4px"  sm "8px"  md "16px"  lg "24px"  xl "32px" }
   font        { sm "13px"  md "15px"  lg "20px"  xl "28px" }
   weight      { medium "500"  bold "700" }
+  leading     { tight "1.2"  normal "1.5"  loose "1.8" }
   breakpoints { sm "640px"  md "768px"  lg "1024px" }
 }

package/template/src/styles.css

@@ -1,9 +0,0 @@
-/* Your look. Muten ships STRUCTURE (semantic tags) + LAYOUT (style tokens); the LOOK lives here,
-   referenced from .muten via class("…"). This base reset is all a fresh app needs to start. */
-* { box-sizing: border-box; }
-body { margin: 0; font: 15px/1.55 system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; color: #111; }
-h1, h2, h3, h4, h5, h6, p { margin: 0; }
-h1 { font-size: 32px; font-weight: 700; letter-spacing: -.02em; }
-.stack { display: flex; flex-direction: column; } /* the class Stack and column layouts emit */
-img { max-width: 100%; display: block; }
-a { color: inherit; text-decoration: none; }