create-muten 0.0.7 → 0.0.9

package/README.md

@@ -60,8 +60,8 @@ 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` |
+| **Template** | `muten` / `muten + React` / `muten + Svelte` | `muten` |
+| **Styling** | `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 |
@@ -70,18 +70,25 @@ In an interactive terminal it prompts for a few things (defaults in parentheses)
 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
+## Templates (flavors)
+
+Every flavor scaffolds the **same** welcome page and the same `.muten` workflow — the only difference is
+whether a framework's island plugin is pre-wired:
 
 | 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 |
+| **muten** | pure muten — the AI-first DSL, zero framework runtime |
+| **muten + React** | same, plus `@vitejs/plugin-react` + React, so you can drop in a **React island** (shadcn/Radix, any React lib) |
+| **muten + Svelte** | same, plus `@sveltejs/vite-plugin-svelte` + Svelte, for **Svelte islands** (a lighter runtime) |
+
+An *island* is a real framework component used as a node — `use X from "react:./X.jsx"` →
+`X(value: @s, onChange: act) client:visible` (props ↓ + events ↑, lazy + code-split). Default to `.muten`;
+reach for an island only for a widget muten can't express.
 
-When **Tailwind or DaisyUI** is selected, `theme.muten` is centralized to **match Tailwind's scale** (so
+When **Tailwind or DaisyUI** is added, `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()`).
+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.
@@ -99,7 +106,7 @@ 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) |
+| `--template <muten\|react\|svelte>` | flavor (default: `muten`); `--react` / `--svelte` are shortcuts |
 | `--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`) |
@@ -128,6 +135,23 @@ my-app/
 There is **no hand-written `main.js`**: the Vite plugin compiles `src/app.muten` into the app's entry,
 so the whole app is `.muten` from the first line.
 
+## What you can build
+
+A muten app reaches the whole web platform through bounded escapes — reach for the **lowest tier that works**:
+
+- **Pure muten** — CRUD / SaaS / catalog / dashboard / content: pages, routing, `state`/`store`, `query` over
+  REST, `Form` + validation, `DataTable`, `when`/`each`, SSG + SEO. The declarative 80%, zero extra deps.
+- **muten + the platform** *(no framework runtime)* — native HTML (`<input type="date">`, `<dialog>`) + `class()`,
+  CSS libs (Tailwind / DaisyUI), **vanilla JS via `Custom`** (charts, maps, date-pickers, rich-text, grids),
+  `use fmt from "./lib.ts"` for any JS logic. Almost every "hard widget" lands here, *without React*.
+- **Svelte / React island** (`--svelte` / `--react`) — only when the component *is* a framework component
+  (shadcn/ui, a React-only lib). Ships that runtime, lazy + code-split. The narrow last resort.
+
+Full reference (every primitive, the three tiers, the roadmap): [`@muten/core`](https://www.npmjs.com/package/@muten/core).
+
+> **Status: pre-1.0.** The core (language, compiler, CLI, Vite plugin, extension, islands) is solid; the
+> ecosystem is young and full island SSR is experimental. Great for real apps, not yet for critical production.
+
 ## Requirements
 
 - **Node.js 18+**

package/index.js

@@ -2,7 +2,7 @@
 // create-muten — scaffold a new Muten app, with modern interactive prompts (@clack/prompts).
 //
 //   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]
+//   create-muten [name] [--template basic|routing|full] [--css|--scss] [--tailwind] [--daisyui] [--svelte] [--react] [--pm npm|pnpm|yarn|bun] [--no-install]
 //
 // 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.
@@ -15,8 +15,7 @@ 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 TEMPLATES = ['muten', 'react', 'svelte']; // the "template" IS the flavor: pure muten, or muten + a framework for islands
 const PKG = JSON.parse(readFileSync(join(SELF, 'package.json'), 'utf8'));
 const PMS = ['npm', 'pnpm', 'yarn', 'bun'];
 
@@ -37,13 +36,55 @@ const tailwindStyles = (daisyui) => `@import "tailwindcss";${daisyui ? '\n@plugi
 /* 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()],
+// Starter welcome page styles (used by the scaffolded home.muten). Self-contained plain CSS — looks good
+// with or without Tailwind; delete it (and the page) when you build your own.
+const WELCOME_CSS = `
+/* — starter welcome page (src/pages/home/home.muten) — delete when you build your own — */
+.welcome { background: #fafafa; color: #18181b; padding: 64px 24px; }
+.wrap { max-width: 720px; margin: 0 auto; display: flex; flex-direction: column; gap: 52px; }
+.hero { text-align: center; }
+.logo { width: 64px; height: 64px; border-radius: 16px; margin: 0 auto; box-shadow: 0 6px 20px rgba(255,94,0,.28); }
+.brand { font-size: clamp(40px, 8vw, 58px); font-weight: 800; letter-spacing: -.04em; line-height: 1; margin-top: 22px; background: linear-gradient(135deg, #ff5e00, #ff9a00); -webkit-background-clip: text; background-clip: text; color: transparent; }
+.tagline { font-size: 18px; font-weight: 600; color: #27272a; margin-top: 10px; }
+.lead { max-width: 580px; margin: 14px auto 0; color: #52525b; font-size: 16px; line-height: 1.65; }
+.stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; }
+.stat { border: 1px solid #e4e4e7; border-radius: 14px; padding: 22px 16px; text-align: center; background: #fff; }
+.stat-n { font-size: 26px; font-weight: 800; letter-spacing: -.02em; color: #ff5e00; }
+.stat-l { color: #71717a; font-size: 12px; line-height: 1.45; margin-top: 6px; }
+.section { display: flex; flex-direction: column; gap: 14px; }
+.h2 { font-size: 22px; font-weight: 700; letter-spacing: -.02em; }
+.snippet { background: #18181b; color: #e4e4e7; border-radius: 14px; padding: 20px 22px; margin: 0; overflow-x: auto; white-space: pre; font: 13px/1.7 ui-monospace, 'SF Mono', Menlo, Consolas, monospace; }
+.note { color: #71717a; font-size: 13px; line-height: 1.55; }
+.cards { display: grid; grid-template-columns: repeat(2, 1fr); gap: 14px; }
+.card { border: 1px solid #e4e4e7; border-radius: 14px; padding: 18px; background: #fff; }
+.card-title { font-size: 14px; font-weight: 600; margin-bottom: 5px; }
+.card-text { color: #71717a; font-size: 13px; line-height: 1.5; }
+@media (max-width: 560px) { .stats, .cards { grid-template-columns: 1fr; } }
+`;
+// vite.config composed from the chosen options — muten always; svelte/react add island plugins; tailwind last.
+const viteConfig = ({ tailwind, svelte, react }) => {
+  const imports = [`import muten from '@muten/core/vite-plugin-muten.js';`];
+  const plugins = ['muten()'];
+  if (svelte) { imports.push(`import { svelte } from '@sveltejs/vite-plugin-svelte';`); plugins.push('svelte()'); }
+  if (react) { imports.push(`import react from '@vitejs/plugin-react';`); plugins.push('react()'); }
+  if (tailwind) { imports.push(`import tailwindcss from '@tailwindcss/vite';`); plugins.push('tailwindcss()'); }
+  return `${imports.join('\n')}\n\nexport default {\n  plugins: [${plugins.join(', ')}],\n};\n`;
 };
+// Tell the AI the island plugin is wired so it can drop in a real Svelte/React component (incl. shadcn/Radix).
+const ISLANDS_NOTE = ({ svelte, react }) => {
+  const techs = [svelte && 'Svelte', react && 'React'].filter(Boolean).join(' + ');
+  const ex = react
+    ? `use Widget from "react:./Widget.jsx"` + '  →  ' + `Widget(value: @sel, onChange: pick) client:visible`
+    : `use Widget from "svelte:./Widget.svelte"` + '  →  ' + `Widget(value: @sel, onChange: pick) client:visible`;
+  return `
+## Framework islands (${techs} — wired)
+The ${techs} Vite plugin is installed. For a genuinely-interactive widget Muten can't express (date-picker,
+combobox, command palette, rich editor — including React/Svelte libs like shadcn/Radix), write the component
+in its own \`.${react ? 'jsx' : 'svelte'}\` file and mount it as a node: \`${ex}\`. props ↓ (\`@state\`) + events ↑
+(an \`onX: action\` calls a Muten action), lazy + code-split. Default to \`.muten\` for the UI; reach for an
+island only for the foreign piece. Full details: SKILL §14.
 `;
+};
 // 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.)
@@ -78,15 +119,23 @@ const detectPM = () => { const ua = process.env.npm_config_user_agent || ''; ret
 const validName = (n) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n);
 const keep = (v) => { if (isCancel(v)) { cancel('Cancelled.'); process.exit(0); } return v; };
 
+// The muten mark + wordmark, in the brand orange (#FF5E00) — shown before the prompts. Truecolor ANSI
+// (modern terminals); degrades to plain text where unsupported.
+const logo = () => {
+  const o = '\x1b[38;2;255;94;0m', tile = '\x1b[48;2;255;94;0m\x1b[1m\x1b[97m', b = '\x1b[1m', d = '\x1b[2m', r = '\x1b[0m';
+  console.log(`\n  ${tile} M ${r}  ${b}${o}muten${r}`);
+  console.log(`  ${d}     the AI-first frontend framework${r}\n`);
+};
+
 async function main() {
   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; }
-  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; }
+  if (has('-h') || has('--help')) { console.log('Usage: create-muten [name] [--template muten|react|svelte] [--css|--scss] [--tailwind] [--daisyui] [--pm npm|pnpm|yarn|bun] [--no-install]'); return; }
 
   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 template = val('--template') || (has('--react') ? 'react' : has('--svelte') ? 'svelte' : has('--muten') ? 'muten' : undefined); // flavor: muten | react | svelte
   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
@@ -99,39 +148,39 @@ async function main() {
 
   // Styled prompts only with a real TTY (piped/CI input would hang); otherwise use flags + defaults.
   if (process.stdin.isTTY) {
-    intro(color.bgCyan(color.black(' create-muten ')) + color.dim('  the AI-first frontend framework'));
+    logo();
+    intro(color.dim(`create-muten v${PKG.version}`));
     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' },
+      { value: 'muten', label: 'muten', hint: 'pure — the AI-first DSL, zero framework runtime' },
+      { value: 'react', label: 'muten + React', hint: 'React islands: shadcn, Radix, any React lib' },
+      { value: 'svelte', label: 'muten + Svelte', hint: 'Svelte islands: a lighter runtime' },
     ] }));
-    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: [
+    if (!style) style = keep(await select({ message: 'Styling', 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' }));
+    if (tailwind === undefined) tailwind = style === 'css' ? keep(await confirm({ message: 'Add Tailwind CSS?', initialValue: false })) : false;
+    if (tailwind && daisyui === undefined) daisyui = keep(await confirm({ message: 'Add DaisyUI? (component classes: btn, card, modal…)', initialValue: false }));
   }
   name = name || 'muten-app';
-  template = template || 'basic';
-  if (template === 'full') tailwind = true;     // full implies Tailwind
-  if (daisyui) tailwind = true;                 // DaisyUI is a Tailwind plugin
+  template = template || 'muten';
   style = style || 'css';
+  if (daisyui) tailwind = true;                 // DaisyUI is a Tailwind plugin
   if (tailwind === undefined) tailwind = false;
   if (daisyui === undefined) daisyui = false;
-  if (tailwind) style = 'css';            // Tailwind implies a CSS base (not SCSS)
+  if (tailwind) style = 'css';                  // Tailwind v4 is CSS-native (not SCSS)
+  const svelte = template === 'svelte';         // the flavor IS the islands choice
+  const react = template === 'react';
   pm = pm || dpm;
   if (install === undefined) install = false;
 
   const target = resolve(name);
   if (existsSync(target)) { (process.stdin.isTTY ? cancel : console.error)(`"${name}" already exists.`); process.exit(1); }
 
-  // scaffold from ./template (the basic base) + layer the chosen variant's overlay + the stylesheet/add-ons
+  // EVERY flavor scaffolds the SAME base template (identical welcome page); react/svelte only add the
+  // island plugin + deps below, and tailwind/daisyui only swap the stylesheet.
   cpSync(TEMPLATE, target, { recursive: true });
-  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'));
 
@@ -139,19 +188,23 @@ async function main() {
   const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
   pkg.name = name;
   const addDev = (deps) => { pkg.devDependencies = { ...(pkg.devDependencies || {}), ...deps }; };
+  const addDep = (deps) => { pkg.dependencies = { ...(pkg.dependencies || {}), ...deps }; };
+  const appendAgents = (text) => { const f = join(target, '.claude', 'AGENTS.md'); if (existsSync(f)) writeFileSync(f, readFileSync(f, 'utf8') + text); };
 
   if (tailwind) {
-    writeFileSync(join(target, 'src', 'styles.css'), tailwindStyles(daisyui));
-    writeFileSync(join(target, 'vite.config.mjs'), TAILWIND_VITE);
+    writeFileSync(join(target, 'src', 'styles.css'), tailwindStyles(daisyui) + WELCOME_CSS);
     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 : ''));
+    appendAgents(TAILWIND_NOTE + (daisyui ? DAISY_NOTE : ''));           // tell the AI what styling is available
   } else {
-    writeFileSync(join(target, 'src', style === 'scss' ? 'styles.scss' : 'styles.css'), RESET);
+    writeFileSync(join(target, 'src', style === 'scss' ? 'styles.scss' : 'styles.css'), RESET + WELCOME_CSS);
   }
   if (style === 'scss') addDev({ sass: '^1.101.0' });
+  if (svelte) { addDep({ svelte: '^5.0.0' }); addDev({ '@sveltejs/vite-plugin-svelte': '^7.0.0' }); }
+  if (react) { addDep({ react: '^19.0.0', 'react-dom': '^19.0.0' }); addDev({ '@vitejs/plugin-react': '^6.0.0' }); }
+  if (svelte || react) appendAgents(ISLANDS_NOTE({ svelte, react }));
+  writeFileSync(join(target, 'vite.config.mjs'), viteConfig({ tailwind, svelte, react })); // composed: muten + chosen plugins
   writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 
   const desc = `${template}, ${style}${tailwind ? ' + Tailwind' : ''}${daisyui ? ' + DaisyUI' : ''}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-muten",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Scaffold a new Muten app.",
   "repository": {
     "type": "git",

package/template/.claude/AGENTS.md

@@ -2,8 +2,8 @@
 
 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.
+trained on Muten yet, so **follow this guide instead of guessing**. Foreign code enters ONLY through explicit
+escapes — `use` for JS functions, **islands** for a Svelte/React widget — never as the page UI itself; 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).
@@ -49,13 +49,15 @@ Page style(padding.lg, gap.md) {
 - **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.
+- **JS & framework escapes (`use`):** call JS functions — `use fmt from "./lib.ts"` → `Text "{fmt(x)}"`. Mount a Svelte/React widget as an **island** — `use Box from "react:./Box.jsx"` → `Box(value: @s, onPick: act) client:visible` (props↓ + events↑, lazy, code-split). Add the framework's Vite plugin. Full details: SKILL §14.
 - **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`).
+- **React / Vue / Svelte as the page UI: NO** — pages are `.muten` (vanilla DOM, no framework runtime). But a
+  single interactive widget or framework lib CAN enter as an **island** (`use X from "react:…"`, SKILL §14) or a
+  vanilla `Custom` component — for the foreign piece, not the whole UI.
 - 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).

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

@@ -6,7 +6,8 @@ description: Read and write Muten — the AI-first frontend DSL this app is buil
 # 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.
+Vite plugin does the compiling. You write a small declarative DSL for the UI — **not** React/JSX/Vue/Svelte/HTML;
+foreign code comes in only through explicit escapes (`use` for JS functions, **islands** for Svelte/React widgets — §14).
 A page with no reactivity compiles to plain zero-runtime HTML; a reactive one ships ~1KB of signals.
 
 ## Mental model & golden rules
@@ -24,16 +25,21 @@ This is a normal **Vite** project, so the whole Vite/npm ecosystem for **styling
   `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.).
+- **Data / utility npm packages** — usable inside `.store` logic, inside `Custom` host components, and via
+  **`use` logic imports** (date libs, fetch wrappers, zod, etc.).
+- **JS logic via `use … from "./lib.ts"` — YES.** Import named functions and call them in any expression
+  (`use fmt from "./lib.ts"` → `Text "{fmt(x)}"`). The `.ts` is a facade over any npm. See §14.
+- **Svelte / React components via ISLANDS — YES.** A genuinely-interactive widget or a framework UI lib
+  Muten can't express → mount a real `.svelte`/`.jsx` with `use X from "svelte:…"`. See §14.
 - **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.
+- **Don't build the page UI out of React / Vue / Svelte.** Pages are `.muten` → vanilla DOM, no framework
+  runtime; you don't compose the app from MUI/Chakra/shadcn. BUT a *specific* interactive widget or framework
+  lib CAN enter as an **island** (`use X from "react:…"`, §14) or a vanilla-JS `Custom` — for the foreign piece,
+  not the whole UI. Default to `.muten`; reach for an island only when Muten genuinely can't express it.
+- **No JSX / hooks / `className` inside `.muten`.** Those live in the island's own `.svelte`/`.jsx` file, never in a page.
 - **No arbitrary inline CSS via `style()`** — `style()` only takes the layout/typography tokens below.
   Visual styling (colors, borders, shadows) goes through `class("…")` + your CSS.
 
@@ -325,15 +331,45 @@ 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`.
+## 14. `use` — JS logic functions & framework islands
+Two escapes that pull in real JS/npm behind a typed border. Both reuse `use … from`; the prefix decides which.
+
+**Logic functions** — `use` named exports from a `.ts`/`.js` file and call them in any expression:
+```
+use fmt, slug from "./lib/format.ts"        # named exports ONLY (the .ts is a facade over any npm)
+Text "{fmt(order.total)}"                    # called like any expression
+Link "{slug(post.title)}" -> /blog/{post.id}
+```
+Import zod/date-fns/nanoid/whatever *inside* `format.ts` and expose tidy named functions; Muten sees only the
+names, so the oracle still checks your calls. Keep the border **synchronous** (no async functions).
+
+**Islands** — mount a real **Svelte or React** component for an interactive widget or framework UI lib Muten
+can't express (a date-picker, rich editor, a React charting component):
+```
+use Counter from "svelte:./Counter.svelte"   # `svelte:` / `react:` prefix = an ISLAND (not a logic fn)
+use Likes   from "react:./Likes.jsx"
+Page {
+  Counter(start: @total, onChange: setTotal)               # props ↓ (@state) + events ↑ (a muten action)
+  Likes(start: @total, onLike: setTotal) client:visible    # lazy: hydrate when scrolled into view
+}
+```
+- `prop: @state` sends a value **down** (snapshot; a React island re-renders when the signal changes). `onX: action`
+  sends a callback that fires a **muten action** — that's how the island writes **back** to muten state.
+- `client:visible` / `client:idle` = **lazy** hydration (load the island's JS only when visible / idle). No
+  directive = on load. Every island is code-split, so it never bloats the main bundle.
+- **Install the framework's Vite plugin** (`@sveltejs/vite-plugin-svelte` or `@vitejs/plugin-react`) next to
+  `muten()` in `vite.config.mjs`. The component file is normal Svelte/React — it owns its own tooling; Muten
+  only validates the node + its args. This is how a **React/Svelte component lib** comes in: wrap it in an island.
+
+## 15. Gotchas
+- It's NOT React: PascalCase primitives + `{ }` children; no JSX/hooks/`className` (those live in island files, §14).
 - 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.
+- Want a library? CSS → `class()`. JS function → `use` (§14). A widget → `Custom`. A React/Svelte component → an **island** (§14).
 
-## 15. Minimal full app
+## 16. Minimal full app
 ```
 # src/app.muten
 routes { / -> home }

package/template/package.json

@@ -8,7 +8,7 @@
     "lint": "muten lint"
   },
   "dependencies": {
-    "@muten/core": "^0.0.6"
+    "@muten/core": "^0.0.8"
   },
   "devDependencies": {
     "vite": "^8.0.16"

package/template/public/muten.svg

@@ -0,0 +1,4 @@
+<svg width="157" height="157" viewBox="0 0 157 157" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 12C0 5.37258 5.37258 0 12 0H145C151.627 0 157 5.37258 157 12V145C157 151.627 151.627 157 145 157H12C5.37258 157 0 151.627 0 145V12Z" fill="#FF5E00"/>
+<path d="M73.2841 144V91.6364H89.1364V101.25H89.7159C90.8068 98.0682 92.6477 95.5568 95.2386 93.7159C97.8295 91.875 100.92 90.9545 104.511 90.9545C108.148 90.9545 111.261 91.8864 113.852 93.75C116.443 95.6136 118.091 98.1136 118.795 101.25H119.341C120.318 98.1364 122.227 95.6477 125.068 93.7841C127.909 91.8977 131.261 90.9545 135.125 90.9545C140.08 90.9545 144.102 92.5455 147.193 95.7273C150.284 98.8864 151.83 103.227 151.83 108.75V144H135.159V112.568C135.159 109.955 134.489 107.966 133.148 106.602C131.807 105.216 130.068 104.523 127.932 104.523C125.636 104.523 123.83 105.273 122.511 106.773C121.216 108.25 120.568 110.239 120.568 112.739V144H104.545V112.398C104.545 109.966 103.886 108.045 102.568 106.636C101.25 105.227 99.5114 104.523 97.3523 104.523C95.8977 104.523 94.6136 104.875 93.5 105.58C92.3864 106.261 91.5114 107.239 90.875 108.511C90.2614 109.784 89.9545 111.284 89.9545 113.011V144H73.2841Z" fill="white"/>
+</svg>

package/template/src/components/Snippet.js

@@ -0,0 +1,19 @@
+// Welcome-page code block (a `Custom` host component — the escape hatch for anything muten can't express).
+// The snippet lives here in JS so it can contain quotes and { } that a .muten string can't. Delete with
+// the welcome page. Used from home.muten as: Custom Snippet
+const CODE = `screen home
+
+state { count = 0 : number }
+action inc mutates count { count.set(count + 1) }
+
+Page style(padding.lg, gap.md) {
+  Title "Count: {count}"
+  Button "+1" -> inc
+}`;
+
+function mount(el) {
+  const pre = document.createElement('pre');
+  pre.className = 'snippet';
+  pre.textContent = CODE;
+  el.appendChild(pre);
+}

package/template/src/pages/home/home.muten

@@ -1,9 +1,45 @@
-# A page = one .muten file; its folder name (home) is the route target from app.muten.
-# `Page` is the <main> landmark; lay it out with style() tokens, skin it with class("…").
+# The starter welcome page. Skin with class(…) + src/styles.css. Delete it and build your own — or just
+# ask your AI assistant; it has the full muten reference in .claude/. The code sample is a Custom component
+# (src/components/Snippet.js) because a .muten string can't hold the quotes/braces of muten source.
 screen home
 
-Page style(padding.xl, gap.md) {
-  Title "Hello, Muten"
-  Text "Edit src/pages/home/home.muten to build your first page."
-  Text "Add routes in src/app.muten; define your token scale in theme.muten."
+Page class("welcome") {
+  Stack class("wrap") {
+
+    Stack class("hero") {
+      Image "/muten.svg" alt "muten logo" class("logo")
+      Title "muten" class("brand")
+      Text "An AI-first frontend framework." class("tagline")
+      Text "You write small .muten files. muten compiles them to vanilla JS plus fine-grained signals — no virtual DOM, no runtime to ship. The language stays small and analyzable, so an AI can locate and mutate your app cheaply." class("lead")
+    }
+
+    Stack class("stats") {
+      Stack class("stat") { Title "2.8 KB" h3 class("stat-n")  Text "muten ships, gzipped" class("stat-l") }
+      Stack class("stat") { Title "5 to 21x" h3 class("stat-n")  Text "less JS than React, Vue, Svelte" class("stat-l") }
+      Stack class("stat") { Title "0 KB" h3 class("stat-n")  Text "on a static page" class("stat-l") }
+    }
+
+    Stack class("section") {
+      Title "A whole page, in muten" h2 class("h2")
+      Custom Snippet
+      Text "Reactivity is automatic — read a state and only that spot re-renders. No hooks, no effects to wire." class("note")
+    }
+
+    Stack class("section") {
+      Title "Where to go next" h2 class("h2")
+      Stack class("cards") {
+        Stack class("card") { Title "Edit this page" h3 class("card-title")  Text "src/pages/home/home.muten" class("card-text") }
+        Stack class("card") { Title "Add a route" h3 class("card-title")  Text "Map URLs to pages in src/app.muten" class("card-text") }
+        Stack class("card") { Title "Style it" h3 class("card-title")  Text "class(…) plus your CSS in src/styles.css — Tailwind optional" class("card-text") }
+        Stack class("card") { Title "Need React or Svelte?" h3 class("card-title")  Text "Drop a real component in as an island, lazy and code-split" class("card-text") }
+      }
+    }
+
+    Stack class("section") {
+      Title "Your AI already knows muten" h2 class("h2")
+      Text "The full language reference ships in this project under .claude — an AGENTS guide plus a Claude skill. Ask your assistant to build a page; it reads that instead of guessing." class("lead")
+      Text "More Claude skills: docs.claude.com — Claude Code, Skills." class("note")
+    }
+
+  }
 }