tutuca 0.9.85 → 0.9.87

package/dist/tutuca-cli.js

@@ -15722,6 +15722,13 @@ function resolveTutucaBase(projectDir, self, forCdn) {
     return { base: DIST_PREFIX.replace(/\/$/, ""), serveDist: self.distRoot };
   return { base: `https://cdn.jsdelivr.net/npm/tutuca@${self.version}/dist`, serveDist: null };
 }
+function tutucaSource(base) {
+  if (base.startsWith("http"))
+    return "CDN";
+  if (base.startsWith("/node_modules"))
+    return "node_modules";
+  return "local dist";
+}
 function buildImports(base, { margaui }) {
   const dev = `${base}/tutuca-dev.js`;
   const imports = {
@@ -15809,6 +15816,40 @@ async function runDevTests(projectDir, devModuleUrls) {
   }
   return { totalTests, failedTests, withTests, failures, importErrors };
 }
+async function discoverModules(projectDir, devModuleUrls) {
+  await createNodeEnv();
+  const modules = [];
+  for (const url of devModuleUrls) {
+    const abs = resolve4(projectDir, url.slice(1));
+    try {
+      const mod = await import(abs);
+      const { normalized, present } = normalizeModule(mod, { path: abs });
+      modules.push({
+        url,
+        present: [...present],
+        components: normalized.components.map((c) => c.name),
+        sections: normalized.sections.map((s) => ({
+          title: s.title,
+          description: s.description,
+          items: s.items.map((it) => ({
+            title: it.title,
+            view: it.view,
+            componentName: it.componentName
+          }))
+        })),
+        macros: normalized.macros ? Object.keys(normalized.macros) : [],
+        requestHandlers: normalized.requestHandlers ? Object.keys(normalized.requestHandlers) : [],
+        error: null
+      });
+    } catch (e) {
+      modules.push({
+        url,
+        error: { code: e.code ?? null, message: e.message, where: e.where ?? null }
+      });
+    }
+  }
+  return modules;
+}
 function collectFailures(node, acc) {
   if (node.children) {
     for (const child of node.children)
@@ -15844,12 +15885,13 @@ async function run4(argv, opts = {}) {
       "no-margaui": { type: "boolean", default: false },
       "no-check": { type: "boolean", default: false },
       "no-tests": { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
     },
     allowPositionals: true
   });
   if (parsed.values.help) {
-    process.stdout.write(`tutuca storybook [dir] [--port <n>] [--out <dir>]
+    process.stdout.write(`tutuca storybook [dir] [--port <n>] [--out <dir>] [--dry-run]
                  [--no-margaui] [--no-check] [--no-tests]
 
   Auto-discovers co-located *.dev.js modules (recursively, skipping
@@ -15860,6 +15902,9 @@ async function run4(argv, opts = {}) {
   --port <n>     preferred port (default 4321; falls back to a free port)
   --out <dir>    write a static index.html + bootstrap (CDN import map)
                  instead of serving; host it from the project root
+  --dry-run      do all the prep (discover, import and normalize modules,
+                 resolve the runtime, run tests) and print what would be
+                 shown instead of serving; pass --json for structured output
   --no-margaui   skip margaui styling (renders functional but unstyled)
   --no-check     skip the in-browser check(app) dev validation
   --no-tests     skip running the modules' getTests() before serving
@@ -15899,6 +15944,63 @@ async function run4(argv, opts = {}) {
 `);
     return;
   }
+  if (parsed.values["dry-run"]) {
+    const { base: base2 } = resolveTutucaBase(projectDir, self, false);
+    const imports2 = buildImports(base2, { margaui });
+    const modules = await discoverModules(projectDir, devModuleUrls);
+    const tests = parsed.values["no-tests"] ? null : await runDevTests(projectDir, devModuleUrls);
+    const source = tutucaSource(base2);
+    const result = {
+      projectDir,
+      tutuca: { source, base: base2, version: self.version },
+      options: { margaui, check, runTests: !parsed.values["no-tests"] },
+      imports: imports2,
+      modules,
+      tests
+    };
+    if (opts.format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(`tutuca storybook dry run (no server started)
+  project: ${projectDir}
+  tutuca runtime: ${source} (${base2}, version ${self.version})
+  margaui: ${margaui ? "on" : "off"}, in-browser check: ${check ? "on" : "off"}
+  ${modules.length} dev module(s):
+`);
+    for (const m of modules) {
+      if (m.error) {
+        process.stdout.write(`    error ${m.url} — ${m.error.message}
+`);
+        continue;
+      }
+      const sectionItems = m.sections.reduce((n, s) => n + s.items.length, 0);
+      process.stdout.write(`    ok ${m.url} — ${m.components.length} component(s), ${m.sections.length} section(s), ${sectionItems} example(s)
+`);
+    }
+    if (tests) {
+      for (const ie of tests.importErrors) {
+        process.stdout.write(`  ! skipped tests for ${ie.url}: ${ie.message}
+`);
+      }
+      if (tests.withTests === 0) {
+        process.stdout.write(`  tests: no getTests() in any dev module
+`);
+      } else {
+        process.stdout.write(`  tests: ${tests.totalTests - tests.failedTests}/${tests.totalTests} passed across ${tests.withTests} module(s)
+`);
+        for (const f of tests.failures) {
+          process.stdout.write(`    failed ${f.fullPath}: ${f.error?.message ?? "failed"}
+`);
+        }
+      }
+    } else {
+      process.stdout.write(`  tests: skipped (--no-tests)
+`);
+    }
+    return;
+  }
   if (!parsed.values["no-tests"]) {
     const r = await runDevTests(projectDir, devModuleUrls);
     for (const ie of r.importErrors) {
@@ -15949,7 +16051,7 @@ async function run4(argv, opts = {}) {
   });
   server.on("listening", () => {
     const actual = server.address().port;
-    const where = base.startsWith("http") ? "CDN" : base.startsWith("/node_modules") ? "node_modules" : "local dist";
+    const where = tutucaSource(base);
     process.stdout.write(`tutuca storybook: http://localhost:${actual}/  (${devModuleUrls.length} dev modules, tutuca from ${where})
 `);
   });
@@ -16155,6 +16257,11 @@ var NO_MODULE_COMMANDS_META = {
         type: "boolean",
         description: "Skip running the modules' getTests() before serving."
       },
+      {
+        name: "dry-run",
+        type: "boolean",
+        description: "Do all prep (discover + import + normalize modules, resolve runtime, run tests) and print what would be shown instead of serving. Pass --json for structured output."
+      },
       { name: "help", short: "h", type: "boolean" }
     ],
     positionals: [

package/dist/tutuca-storybook.js

@@ -34,20 +34,36 @@ var Storybook = component({
         return this;
       }
       return this.setSectionId(sectionId).setExampleId(exampleId).setFocusExample(example.value);
+    },
+    setSelectedSectionFilter(value) {
+      if (this.sections.size === 0)
+        return this;
+      const i = this.selectedSectionIndex;
+      const sections = this.sections.map((s, idx) => idx === i ? s.setFilter(value ?? "") : s);
+      return this.setSections(sections);
+    },
+    toUrlState(overrides = {}) {
+      const section = this.sections.get(this.selectedSectionIndex);
+      return {
+        section: section?.id ?? "",
+        example: this.exampleId ?? "",
+        sectionFilter: this.filter ?? "",
+        exampleFilter: section?.filter ?? "",
+        ...overrides
+      };
     }
   },
   input: {
     onApplyFilter(value, ctx) {
-      ctx.request("persistState", [{ key: "sectionFilter", value }]);
+      ctx.request("persistState", [this.toUrlState({ sectionFilter: value }), this, false]);
       return this.setFilter(value);
     },
     onClearFilter(ctx) {
-      ctx.request("persistState", [{ key: "sectionFilter", value: "" }]);
+      ctx.request("persistState", [this.toUrlState({ sectionFilter: "" }), this, false]);
       return this.resetFilter();
     },
     onFocusClose(ctx) {
-      ctx.request("persistState", [{ key: "sectionId", value: "" }]);
-      ctx.request("persistState", [{ key: "exampleId", value: "" }]);
+      ctx.request("persistState", [this.toUrlState({ example: "" }), this, true]);
       return this.setSectionId(null).setExampleId(null).setFocusExample(null);
     }
   },
@@ -59,16 +75,38 @@ var Storybook = component({
   bubble: {
     sectionSelected(section, ctx) {
       ctx.stopPropagation();
-      ctx.request("persistState", [{ key: "section", value: section.id }]);
+      ctx.request("persistState", [
+        this.toUrlState({ section: section.id, exampleFilter: section.filter }),
+        this,
+        true
+      ]);
       return this.selectSectionAtIndex(this.sections.indexOf(section));
     },
     exampleFocusRequested(example, ctx) {
       ctx.stopPropagation();
       const section = this.sections.get(this.selectedSectionIndex);
       const sectionId = section?.id ?? null;
-      ctx.request("persistState", [{ key: "sectionId", value: sectionId }]);
-      ctx.request("persistState", [{ key: "exampleId", value: example.id }]);
+      ctx.request("persistState", [this.toUrlState({ example: example.id }), this, true]);
       return this.setSectionId(sectionId).setExampleId(example.id).setFocusExample(example.value);
+    },
+    exampleFilterChanged(value, ctx) {
+      ctx.stopPropagation();
+      ctx.request("persistState", [this.toUrlState({ exampleFilter: value }), this, false]);
+      return this;
+    }
+  },
+  receive: {
+    init(ctx) {
+      ctx.request("loadState", []);
+      return this;
+    }
+  },
+  response: {
+    loadState(state, err) {
+      if (err || !state)
+        return this;
+      const next = this.selectSectionWithId(state.section).setFilter(state.sectionFilter ?? "").setSelectedSectionFilter(state.exampleFilter ?? "");
+      return state.example ? next.focusExampleByIds(state.section, state.example) : next.setSectionId(null).setExampleId(null).setFocusExample(null);
     }
   },
   view: html`<div>
@@ -115,10 +153,13 @@ var Section = component({
     selected: false
   },
   statics: {
-    fromData({ id, title = "???", description = "", items = [] }) {
-      id ??= slugify(title);
+    fromData(raw) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw) || raw.title == null) {
+        throw new Error(`Section.fromData: expected a section object { title, items }, got ${JSON.stringify(raw)}. ` + `getExamples() must return a section object or an array of section objects.`);
+      }
+      const { id, title, description = "", items = [] } = raw;
       return this.make({
-        id,
+        id: id ?? slugify(title),
         title,
         description,
         items: items.map((v) => Example.Class.fromData(v))
@@ -132,11 +173,11 @@ var Section = component({
   },
   input: {
     onApplyFilter(value, ctx) {
-      ctx.request("persistState", [{ key: "exampleFilter", value }]);
+      ctx.bubble("exampleFilterChanged", [value]);
       return this.setFilter(value);
     },
     onClearFilter(ctx) {
-      ctx.request("persistState", [{ key: "exampleFilter", value: "" }]);
+      ctx.bubble("exampleFilterChanged", [""]);
       return this.resetFilter();
     },
     onListItemClick(ctx) {
@@ -235,7 +276,12 @@ function slugify(str) {
   return String(str).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function buildStorybook(modules) {
-  const sections = modules.map((m) => Section.Class.fromData(m.getExamples())).sort((a, b) => a.title.localeCompare(b.title));
+  const sections = modules.flatMap((m) => {
+    const raw = m.getExamples?.();
+    if (raw == null)
+      return [];
+    return Array.isArray(raw) ? raw : [raw];
+  }).map((s) => Section.Class.fromData(s)).sort((a, b) => a.title.localeCompare(b.title));
   const components = new Set([Storybook, Section, Example]);
   const macros = {};
   const requestHandlers = {};
@@ -255,18 +301,46 @@ function buildStorybook(modules) {
     requestHandlers
   };
 }
-async function mountStorybook(selector, modules, { compileCss, root } = {}) {
+async function mountStorybook(selector, modules, { compileCss, root, persistUrl = true } = {}) {
   const app = tutuca(selector);
   const built = buildStorybook(modules);
   app.state.set(root ?? built.root);
   const scope = app.registerComponents(built.components);
   scope.registerMacros(built.macros);
   scope.registerRequestHandlers(built.requestHandlers);
+  if (persistUrl) {
+    scope.registerRequestHandlers({ persistState, loadState });
+  }
   if (compileCss) {
     injectCss("tutuca-storybook", await compileCss(app));
   }
   app.start();
+  if (persistUrl) {
+    app.sendAtRoot("init", []);
+    window.addEventListener("popstate", () => app.sendAtRoot("init", []));
+  }
   return app;
+  function persistState(state, instance, push) {
+    if (instance !== app.state.val)
+      return;
+    const url = new URL(window.location.href);
+    for (const [k, v] of Object.entries(state)) {
+      if (v === "" || v == null)
+        url.searchParams.delete(k);
+      else
+        url.searchParams.set(k, String(v));
+    }
+    window.history[push ? "pushState" : "replaceState"](null, "", url);
+  }
+  function loadState() {
+    const p = new URLSearchParams(window.location.search);
+    return {
+      section: p.get("section"),
+      example: p.get("example"),
+      sectionFilter: p.get("sectionFilter") ?? "",
+      exampleFilter: p.get("exampleFilter") ?? ""
+    };
+  }
 }
 function getComponents() {
   return [Storybook, Section, Example];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.85",
+  "version": "0.9.87",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -22,15 +22,16 @@
     "tutuca": "./dist/tutuca-cli.js"
   },
   "scripts": {
-    "clean": "rm -rf dist",
+    "clean": "rm -rf dist skill",
     "dist": "bun scripts/dist.js",
     "dist-ext": "bun scripts/dist-ext.js",
     "dist-immutable": "bun scripts/dist-immutable.js",
     "dist-all": "bun run dist-immutable && bun run dist && bun run dist-ext && bun run smoke",
     "smoke": "node scripts/smoke.js",
-    "release": "bun run dist-all && bun run build-skill && npm publish --access public",
-    "release-dry": "bun run dist-all && bun run build-skill && npm publish --dry-run",
+    "release": "bun run dist-all && bun run build-skill && (npm publish --access public; bun run clean-skill)",
+    "release-dry": "bun run dist-all && bun run build-skill && (npm publish --dry-run; bun run clean-skill)",
     "build-skill": "bun scripts/build-skill.js",
+    "clean-skill": "rm -rf skill",
     "test": "bun test test/*.test.js",
     "test-watch": "bun test --watch test/*.test.js",
     "format": "bunx @biomejs/biome format --write",
@@ -38,6 +39,7 @@
     "lint-fix": "bunx @biomejs/biome lint --write",
     "fix": "bunx @biomejs/biome check --write",
     "tutuca": "bun tools/tutuca.js",
+    "storybook:examples": "bun scripts/storybook-examples.js",
     "stresstest": "bun scripts/stresstest.js",
     "smoke-test": "bun tools/tutuca.js lint ./test/todo.js && bun tools/tutuca.js render ./test/todo.js && bun tools/tutuca.js test ./test/todo.js && bun tools/tutuca.js lint ./test/json.js && bun tools/tutuca.js render ./test/json.js"
   },

package/skill/tutuca/cli.md

@@ -40,7 +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 |
+| `storybook [dir]`        | Serve a live storybook for the project, auto-discovering co-located `*.dev.js` modules. Flags: `--port`, `--out`, `--dry-run` (prep + print, don't serve), `--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   |
@@ -200,6 +200,8 @@ 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 --dry-run       # do all the prep + print what would be shown, don't serve (smoke test)
+tutuca storybook --dry-run --json # same, machine-readable for agents
 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)

package/skill/tutuca/component-design.md

@@ -28,6 +28,13 @@ Walk these top-down whenever you add or reshape a component:
 
 ## Communication decision ladder
 
+This ladder is about *acting across* a component boundary — reaching up,
+messaging a target, doing async work, or mutating state someone else owns. It is
+**not** about merely *reading* a child's state: an ancestor already holds its
+children as immutable fields and can read them directly in any handler or method
+(`this.items.get(i).done`) — no channel needed. See [core.md](./core.md) "The
+value tree".
+
 Reach for the *narrowest* channel that does the job, and only move further down
 the ladder when the one above can't express it:
 
@@ -72,6 +79,16 @@ A compact worked version of the first four (`method`, `bubble`, `send`/`receive`
   between** (the React "prop drilling" reflex) — let a child render the field it
   needs from its owner. → [patterns/share-state-across-the-tree.md](./patterns/share-state-across-the-tree.md)
 
+- **Do read a child's state directly when an ancestor needs it for an aggregate
+  decision.** A parent holds its children as immutable fields, so a handler or
+  method can read `this.items.get(i).done` straight off — children don't have to
+  `bubble` their state up just to be *read*. **Don't reach for a channel to read
+  downward**; `bubble` / `send` are for reaching *up*, messaging a target, or
+  mutating — not for inspecting state you already own. (And don't reach in to
+  mutate a child around the model — that still goes through the owner returning a
+  new self or `ctx.send`.) → [core.md](./core.md) "The value tree" and
+  [request-response.md](./request-response.md) "When to bubble"
+
 - **Do reach for `provide` / `lookup` (`*name`) last** — only when a deep
   descendant needs a value owned far away and nothing in between should know about
   it. Dynamic bindings couple a consumer to a producer that may not be in scope.

package/skill/tutuca/core.md

@@ -69,6 +69,23 @@ edit done:
    emitted HTML to verify structure (attributes, nesting, text); omit it
    when you only care that the render didn't crash.
 
+4. **Smoke-test the whole project** — when you've touched several
+   `*.dev.js` modules, or are about to launch the storybook, do a
+   project-wide dry run instead of opening a browser:
+
+        tutuca storybook --dry-run
+        tutuca storybook --dry-run --json    # machine-readable for agents
+
+   It does everything the server would do up front — discovers every
+   co-located `*.dev.js`, imports and normalizes each (catching a missing
+   `getComponents()` or a malformed `getExamples()` shape), runs their
+   `getTests()`, and resolves the runtime import map — then prints what
+   it *would* show instead of serving. A broken module is reported in
+   place (an `error` line, or `modules[].error` in `--json`) while the
+   others still report, so one bad module never hides the rest. This is
+   the fast "is the whole catalog wired up correctly?" check; steps 1–3
+   stay the per-module loop.
+
 Full reference: [cli.md](./cli.md).
 
 The Tutuca CLI only catches Tutuca-specific issues. For generic JS
@@ -152,6 +169,23 @@ keys its cache on `===` identity, so unchanged subtrees skip work.
 Every value carries a hidden tag back to its component class, so the
 runtime never needs `instanceof` — it asks the value what it is.
 
+Because children are just immutable Records held in fields, **handlers
+and methods are ordinary JS with full read access to nested child
+state** — `this.child.count`, `this.items.get(i).done`,
+`this.byKey.get(k).label`. Reading *down* the tree is direct and needs
+no channel: an ancestor that owns a list already holds every child's
+state and can read it for an aggregate decision. The single-level
+`.field` restriction (no `.foo.bar`) is a **view-template** rule, not a
+JS one — it's why a derivation like `userName() { return this.user.name; }`
+is written as a method (see *Methods as Predicates & Computed Values*).
+Reading is free; **mutating** a child still flows through the model —
+the owner returns a new self (`setInItemsAt`, …) or messages the child
+with `ctx.send`. Don't reach in to mutate around the handler discipline,
+and prefer letting a child own and render its own state — reach down to
+read only when the ancestor genuinely needs it. See
+[component-design.md](./component-design.md) and "When to bubble" in
+[request-response.md](./request-response.md).
+
 **Stack: frames vs scopes.** As the renderer walks the AST it pushes
 `BindFrame`s. A *frame* is a barrier: name lookups (`@x`) stop at it,
 so a child component view sees a clean namespace. A *scope* is

package/skill/tutuca/request-response.md

@@ -56,7 +56,11 @@ the state needed to respond. Bubble when the action belongs to an
 ancestor (a list item's "remove" must reach the list that owns the
 items), or when an ancestor may want to react to or record something
 that happened (selection, logging, analytics). Don't bubble events
-with no consumer.
+with no consumer — and don't bubble merely so an ancestor can *read* a
+child's state: the ancestor already holds the child as a field and can
+read it directly in its own handler (`this.items.get(i).done`). Bubble
+when the ancestor must **act on** or **record** the event, not to learn
+state it already owns.
 
 ## Send / Receive