create-muten 0.0.6 → 0.0.8

package/README.md

@@ -64,6 +64,7 @@ In an interactive terminal it prompts for a few things (defaults in parentheses)
 | **Stylesheet** | `css` / `scss` | `css` |
 | **Add Tailwind CSS?** | `Y` / `n` (CSS only) | `n` |
 | **Add DaisyUI?** | `Y` / `n` (needs Tailwind) | `n` |
+| **Framework islands?** | `none` / `svelte` / `react` / `both` | `none` |
 | **Package manager** | `npm` / `pnpm` / `yarn` / `bun` | the one that launched it |
 | **Install deps and start dev now?** | `Y` / `n` | `Y` |
 
@@ -81,7 +82,12 @@ wires `@tailwindcss/vite` + an `@import "tailwindcss"` and notes the setup in th
 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()`).
+pure classes, no React; behavior is Muten state + `on()`.
+
+**Framework islands** (`svelte` / `react` / `both`) wire `@sveltejs/vite-plugin-svelte` / `@vitejs/plugin-react`
+into `vite.config.mjs` so you can drop a real Svelte/React component (incl. React libs like **shadcn/Radix**)
+into a page as an *island* — `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 the hard widget.
 
 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.
@@ -103,6 +109,7 @@ create-muten my-app --css --no-install    # just scaffold, decide later
 | `--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`) |
+| `--svelte` / `--react` | wire the Svelte / React island plugin (drop in framework components, e.g. shadcn) |
 | `--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 |
@@ -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.
@@ -37,13 +37,30 @@ 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()],
+// 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.)
@@ -83,13 +100,15 @@ async function main() {
   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 basic|routing|full] [--css|--scss] [--tailwind] [--daisyui] [--svelte] [--react] [--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 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 svelte = has('--svelte') ? true : undefined;                            // island: Svelte components
+  let react = has('--react') ? true : undefined;                              // island: React components (shadcn/Radix)
   let pm = val('--pm');
   let install = has('--no-install') ? false : undefined;
   if (name && !validName(name)) { console.error(`Invalid name: "${name}" (letters, digits, . _ -)`); process.exit(1); }
@@ -114,6 +133,16 @@ async function main() {
     ] }));
     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 (svelte === undefined && react === undefined) {
+      const islands = keep(await select({ message: 'Framework islands? (drop in Svelte/React components for hard widgets)', options: [
+        { value: 'none', label: 'None', hint: 'pure Muten' },
+        { value: 'svelte', label: 'Svelte', hint: 'lighter to embed' },
+        { value: 'react', label: 'React', hint: 'shadcn / Radix ecosystem' },
+        { value: 'both', label: 'Both' },
+      ] }));
+      svelte = islands === 'svelte' || islands === 'both';
+      react = islands === 'react' || islands === 'both';
+    }
   }
   name = name || 'muten-app';
   template = template || 'basic';
@@ -122,6 +151,8 @@ async function main() {
   style = style || 'css';
   if (tailwind === undefined) tailwind = false;
   if (daisyui === undefined) daisyui = false;
+  if (svelte === undefined) svelte = false;
+  if (react === undefined) react = false;
   if (tailwind) style = 'css';            // Tailwind implies a CSS base (not SCSS)
   pm = pm || dpm;
   if (install === undefined) install = false;
@@ -139,22 +170,27 @@ 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, '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);
   }
   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' : ''}`;
+  const islandDesc = [svelte && 'Svelte', react && 'React'].filter(Boolean).join('+');
+  const desc = `${template}, ${style}${tailwind ? ' + Tailwind' : ''}${daisyui ? ' + DaisyUI' : ''}${islandDesc ? ' + ' + islandDesc + ' islands' : ''}`;
   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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-muten",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "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.5"
+    "@muten/core": "^0.0.7"
   },
   "devDependencies": {
     "vite": "^8.0.16"