tutuca 0.9.84 → 0.9.85

package/dist/tutuca-cli.js

@@ -15994,7 +15994,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 var describe = "Print a machine-readable schema (commands, flags, exit codes) as JSON.";
-var SCHEMA_VERSION = 2;
+var SCHEMA_VERSION = 3;
 var GLOBAL_FLAGS = [
   {
     name: "json",
@@ -16126,6 +16126,45 @@ var NO_MODULE_COMMANDS_META = {
     ],
     positionals: []
   },
+  storybook: {
+    describe: "Serve a live storybook for the project, auto-discovering co-located *.dev.js modules.",
+    needsModule: false,
+    flags: [
+      {
+        name: "port",
+        type: "string",
+        description: "Preferred port (default 4321; falls back to a free port)."
+      },
+      {
+        name: "out",
+        type: "string",
+        description: "Write a static index.html + bootstrap (CDN import map) instead of serving."
+      },
+      {
+        name: "no-margaui",
+        type: "boolean",
+        description: "Render unstyled (skip margaui)."
+      },
+      {
+        name: "no-check",
+        type: "boolean",
+        description: "Skip the in-browser check(app)."
+      },
+      {
+        name: "no-tests",
+        type: "boolean",
+        description: "Skip running the modules' getTests() before serving."
+      },
+      { name: "help", short: "h", type: "boolean" }
+    ],
+    positionals: [
+      {
+        name: "dir",
+        required: false,
+        description: "Project root to scan and serve (default: cwd)."
+      }
+    ]
+  },
   "agent-context": {
     describe: "Print this schema as JSON.",
     needsModule: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.84",
+  "version": "0.9.85",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",

package/skill/tutuca/cli.md

@@ -40,6 +40,7 @@ Use `--module=<path>` if the path conflicts with positional parsing.
 | `lint <module> [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
 | `render <module> [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
 | `test <module> [name]`   | Run tests defined by `getTests({ describe, test, expect })`. Filter by component name, `--grep <pattern>`, or `--bail`. Exits **4** on any failure |
+| `storybook [dir]`        | Serve a live storybook for the project, auto-discovering co-located `*.dev.js` modules. Flags: `--port`, `--out`, `--no-margaui`, `--no-check`, `--no-tests`. No module path needed |
 | `help [cmd]`             | Show usage. No module path needed                                                                                      |
 | `feedback [message]`     | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl`. No module path needed                      |
 | `install-skill [name]`   | Copy a bundled skill (`tutuca`, `margaui`, `immutable-js`, or `--all`) into `.claude/skills/`. No module path needed   |
@@ -187,6 +188,61 @@ export function getTests({ describe, test, expect }) {
 `tutuca test <module> Counter` picks it up. Untagged `test(...)` at the
 top of a tagged `describe` inherits the tag.
 
+## storybook — live component catalog
+
+`tutuca storybook [dir]` serves a browser storybook for a project with no
+setup. It recursively discovers co-located `*.dev.js` modules (see the
+`.dev.js` convention below), mounts them via the shipped `tutuca/storybook`
+library, and serves an ephemeral page — no config, no HTML to write.
+
+```sh
+tutuca storybook                 # scan + serve the current directory
+tutuca storybook ./packages/ui   # scan + serve another directory
+tutuca storybook --port 4321     # preferred port (falls back to a free one if taken)
+tutuca storybook --out ./_site   # write a static index.html + bootstrap instead of serving
+tutuca storybook --no-tests      # skip the pre-serve getTests() run
+tutuca storybook --no-margaui    # render unstyled (skip margaui)
+tutuca storybook --no-check      # skip the in-browser check(app)
+```
+
+It is **batteries-included by default**: before serving it runs each module's
+`getTests()` in the terminal, the page wires margaui styling, and the browser
+runs `check(app)`. Each is individually disablable with the `--no-*` flags.
+
+How tutuca itself is resolved (convention over configuration): a local
+`node_modules/tutuca` install if present, else the CLI's own `dist`, else the
+version-pinned CDN. All tutuca specifiers resolve to a single runtime, which
+component scope/identity requires. `--out` always pins the CDN so the static
+artifact is portable (host it from the project root so `/*.dev.js` paths resolve).
+
+### The `.dev.js` convention
+
+A `*.dev.js` file is a **dev-only module**: it holds stories
+(`getComponents()` + `getExamples()`), tests (`getTests()`), and any other
+development-time helpers for nearby components, and is **never shipped to
+production or the UI**. The `.dev.js` suffix is the contract — your app imports
+its real components directly and never a `.dev.js`, and a production build glob
+can exclude `**/*.dev.js`. Because they follow the full module convention, the
+same files are valid targets for `tutuca test`/`lint`/`render` too.
+
+```js
+// counter.dev.js — lives next to counter.js
+import { component, html } from "tutuca";
+import { Counter } from "./counter.js";
+
+export function getComponents() {
+  return [Counter];
+}
+export function getExamples() {
+  return { title: "Counter", items: [{ title: "Basic", value: Counter.make({}) }] };
+}
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    test("starts at zero", () => expect(Counter.make({}).count).toBe(0));
+  });
+}
+```
+
 ## Install skill assets
 
 `tutuca install-skill` copies bundled Claude Code skill files into

package/skill/tutuca/core.md

@@ -988,6 +988,12 @@ export, alias it instead of teaching tools a new name:
 export { allMyComponents as getComponents } from "./app.js";
 ```
 
+Put these exports in a co-located **`*.dev.js`** file (a dev-only module
+holding stories + tests, never shipped) and `tutuca storybook` auto-discovers
+and renders them with no setup — see [cli.md](./cli.md). The same shape is
+consumed by the shipped `tutuca/storybook` library (`mountStorybook`,
+`buildStorybook`) if you want to embed a storybook in your own page.
+
 ## See also
 
 - [component-design.md](./component-design.md) — design judgment for shaping a