npm - tutuca - Versions diffs - 0.9.83 → 0.9.85 - Mend

tutuca 0.9.83 → 0.9.85

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +2 -0
package/dist/tutuca-cli.js +424 -53
package/dist/tutuca-storybook.js +283 -0
package/package.json +3 -1
package/skill/tutuca/cli.md +56 -0
package/skill/tutuca/core.md +17 -0

package/README.md CHANGED Viewed

@@ -68,6 +68,8 @@ Tutuca ships a single-file CLI (`dist/tutuca-cli.js`) for inspecting, linting,
 documenting, and rendering components defined in an ES module. The module just
 needs to export `getComponents()` and, for render-time commands, `getExamples()`
 in the storybook shape `{ title, description?, items: [{ title, description?, value, view? }] }` (a single section, or an array of sections).
+Expose **all** of your app's components through `getComponents()` — components
+left out are invisible to `lint`/`render`/`test` and silently lose coverage.
 ### Setup

package/dist/tutuca-cli.js CHANGED Viewed

@@ -15629,6 +15629,356 @@ var init_install_skill = __esm(() => {
   ];
 });
+// tools/cli/env.js
+import { JSDOM, VirtualConsole } from "jsdom";
+async function createNodeEnv() {
+  const virtualConsole = new VirtualConsole;
+  virtualConsole.forwardTo(console, { jsdomErrors: "none" });
+  virtualConsole.on("jsdomError", (err) => {
+    if (err?.message?.includes("Could not parse CSS stylesheet"))
+      return;
+    console.error(err.message);
+  });
+  const dom = new JSDOM("<!DOCTYPE html><html><head></head><body></body></html>", {
+    virtualConsole
+  });
+  const { document: document2, Text, Comment } = dom.window;
+  globalThis.document = document2;
+  class HeadlessParseContext extends ParseContext {
+    constructor() {
+      super(document2, Text, Comment);
+    }
+  }
+  class HeadlessLintParseContext extends LintParseContext {
+    constructor() {
+      super(document2, Text, Comment);
+    }
+  }
+  return {
+    document: dom.window.document,
+    ParseContext: HeadlessParseContext,
+    LintParseContext: HeadlessLintParseContext
+  };
+}
+var init_env2 = __esm(() => {
+  init_anode();
+  init_lint_check();
+});
+// tools/cli/commands/storybook.js
+var exports_storybook = {};
+__export(exports_storybook, {
+  run: () => run4,
+  describe: () => describe4
+});
+import {
+  createReadStream,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync3,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { createServer } from "node:http";
+import { dirname as dirname4, join, normalize, relative as relative2, resolve as resolve4, sep } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { parseArgs as parseArgs3 } from "node:util";
+function findDevModules(root, dir, acc) {
+  for (const e of readdirSync2(dir, { withFileTypes: true })) {
+    if (e.name.startsWith(".") || e.name === "node_modules")
+      continue;
+    const full = resolve4(dir, e.name);
+    if (e.isDirectory()) {
+      findDevModules(root, full, acc);
+    } else if (e.isFile() && e.name.endsWith(".dev.js")) {
+      acc.push(`/${relative2(root, full).split(sep).join("/")}`);
+    }
+  }
+  return acc;
+}
+function findSelf() {
+  const here = dirname4(fileURLToPath4(import.meta.url));
+  const pkgCandidates = [
+    resolve4(here, "..", "..", "..", "package.json"),
+    resolve4(here, "..", "package.json")
+  ];
+  const pkgPath = pkgCandidates.find(existsSync4);
+  const version = pkgPath ? JSON.parse(readFileSync3(pkgPath, "utf8")).version : "latest";
+  const distCandidates = [resolve4(here, "..", "..", "..", "dist"), resolve4(here, ".")];
+  const distRoot = distCandidates.find((d) => existsSync4(resolve4(d, "tutuca-storybook.js"))) ?? null;
+  return { version, distRoot };
+}
+function resolveTutucaBase(projectDir, self, forCdn) {
+  if (forCdn)
+    return { base: `https://cdn.jsdelivr.net/npm/tutuca@${self.version}/dist`, serveDist: null };
+  const nm = resolve4(projectDir, "node_modules", "tutuca", "dist");
+  if (existsSync4(resolve4(nm, "tutuca-dev.js"))) {
+    return { base: "/node_modules/tutuca/dist", serveDist: null };
+  }
+  if (self.distRoot)
+    return { base: DIST_PREFIX.replace(/\/$/, ""), serveDist: self.distRoot };
+  return { base: `https://cdn.jsdelivr.net/npm/tutuca@${self.version}/dist`, serveDist: null };
+}
+function buildImports(base, { margaui }) {
+  const dev = `${base}/tutuca-dev.js`;
+  const imports = {
+    tutuca: dev,
+    "tutuca/extra": dev,
+    "tutuca/dev": dev,
+    "tutuca/storybook": `${base}/tutuca-storybook.js`
+  };
+  if (margaui)
+    imports.margaui = MARGAUI_CDN;
+  return imports;
+}
+function renderIndexHtml(imports, { margaui, bootstrapUrl }) {
+  const theme = margaui ? `
+    <link rel="stylesheet" href="${MARGAUI_THEME}" />` : "";
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Storybook</title>${theme}
+    <script type="importmap">
+${JSON.stringify({ imports }, null, 6)}
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="${bootstrapUrl}"></script>
+  </body>
+</html>
+`;
+}
+function renderBootstrap(devModuleUrls, { margaui, check }) {
+  const lines = ['import { mountStorybook } from "tutuca/storybook";'];
+  if (margaui) {
+    lines.push('import { compileClassesToStyleText } from "tutuca/extra";');
+    lines.push('import { compile } from "margaui";');
+  }
+  if (check)
+    lines.push('import { check } from "tutuca/dev";');
+  devModuleUrls.forEach((url, i) => {
+    lines.push(`import * as m${i} from ${JSON.stringify(url)};`);
+  });
+  const modules = devModuleUrls.map((_, i) => `m${i}`).join(", ");
+  const opts = margaui ? "{ compileCss: (app) => compileClassesToStyleText(app, compile) }" : "{}";
+  lines.push("");
+  lines.push(`const app = await mountStorybook("#app", [${modules}], ${opts});`);
+  if (check)
+    lines.push("check(app);");
+  lines.push("");
+  return lines.join(`
+`);
+}
+async function runDevTests(projectDir, devModuleUrls) {
+  await createNodeEnv();
+  let totalTests = 0;
+  let failedTests = 0;
+  let withTests = 0;
+  const failures = [];
+  const importErrors = [];
+  for (const url of devModuleUrls) {
+    const abs = resolve4(projectDir, url.slice(1));
+    let mod;
+    try {
+      mod = await import(abs);
+    } catch (e) {
+      importErrors.push({ url, message: e.message });
+      continue;
+    }
+    if (typeof mod.getTests !== "function")
+      continue;
+    withTests++;
+    const { normalized } = normalizeModule(mod, { path: abs });
+    const report = await runTests({
+      getTests: mod.getTests,
+      components: normalized.components,
+      path: abs,
+      expect
+    });
+    const m = report.modules[0];
+    totalTests += m.counts.total;
+    failedTests += m.counts.fail;
+    for (const suite of m.suites)
+      collectFailures(suite, failures);
+  }
+  return { totalTests, failedTests, withTests, failures, importErrors };
+}
+function collectFailures(node, acc) {
+  if (node.children) {
+    for (const child of node.children)
+      collectFailures(child, acc);
+  } else if (node.status === "fail") {
+    acc.push(node);
+  }
+}
+function safeJoin(rootDir, urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0]);
+  const p = normalize(join(rootDir, decoded));
+  if (p !== rootDir && !p.startsWith(rootDir + sep))
+    return null;
+  return p;
+}
+function serveFile(res, filePath) {
+  if (!filePath || !existsSync4(filePath) || statSync(filePath).isDirectory()) {
+    res.writeHead(404);
+    res.end("Not found");
+    return;
+  }
+  const dot = filePath.lastIndexOf(".");
+  const ext = dot >= 0 ? filePath.slice(dot) : "";
+  res.setHeader("Content-Type", MIME[ext] ?? "application/octet-stream");
+  createReadStream(filePath).pipe(res);
+}
+async function run4(argv, opts = {}) {
+  const parsed = parseArgs3({
+    args: argv,
+    options: {
+      port: { type: "string" },
+      out: { type: "string" },
+      "no-margaui": { type: "boolean", default: false },
+      "no-check": { type: "boolean", default: false },
+      "no-tests": { 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>]
+                 [--no-margaui] [--no-check] [--no-tests]
+  Auto-discovers co-located *.dev.js modules (recursively, skipping
+  node_modules/dotdirs) and serves a live storybook that mounts them via
+  the tutuca/storybook library. Zero setup.
+  [dir]          project root to scan and serve (default: cwd)
+  --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
+  --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
+`);
+    return;
+  }
+  const projectDir = resolve4(parsed.positionals[0] ?? process.cwd());
+  if (!existsSync4(projectDir) || !statSync(projectDir).isDirectory()) {
+    emitError(opts, {
+      code: CODES.USAGE_MISSING_ARGUMENT,
+      message: `not a directory: ${projectDir}`,
+      hint: "Pass a project directory to scan, or omit it to use the current directory."
+    });
+  }
+  const devModuleUrls = findDevModules(projectDir, projectDir, []);
+  if (devModuleUrls.length === 0) {
+    emitError(opts, {
+      code: CODES.USAGE_MISSING_ARGUMENT,
+      message: `no *.dev.js modules found under ${projectDir}`,
+      hint: "Create a co-located <name>.dev.js exporting getComponents() and getExamples()."
+    });
+  }
+  const margaui = !parsed.values["no-margaui"];
+  const check = !parsed.values["no-check"];
+  const self = findSelf();
+  if (parsed.values.out) {
+    const outDir = resolve4(parsed.values.out);
+    mkdirSync3(outDir, { recursive: true });
+    const { base: base2 } = resolveTutucaBase(projectDir, self, true);
+    const imports2 = buildImports(base2, { margaui });
+    const bootstrapName = "tutuca-storybook.bootstrap.js";
+    writeFileSync(resolve4(outDir, "index.html"), renderIndexHtml(imports2, { margaui, bootstrapUrl: `./${bootstrapName}` }));
+    writeFileSync(resolve4(outDir, bootstrapName), renderBootstrap(devModuleUrls, { margaui, check }));
+    process.stdout.write(`wrote static storybook → ${relative2(process.cwd(), outDir) || "."}/
+  index.html + ${bootstrapName} (${devModuleUrls.length} dev modules, CDN import map)
+  Host it from the project root so /*.dev.js paths resolve.
+`);
+    return;
+  }
+  if (!parsed.values["no-tests"]) {
+    const r = await runDevTests(projectDir, devModuleUrls);
+    for (const ie of r.importErrors) {
+      process.stdout.write(`  ! skipped tests for ${ie.url}: ${ie.message}
+`);
+    }
+    if (r.withTests === 0) {
+      process.stdout.write(`tests: no getTests() in any dev module
+`);
+    } else {
+      process.stdout.write(`tests: ${r.totalTests - r.failedTests}/${r.totalTests} passed across ${r.withTests} module(s)
+`);
+      for (const f of r.failures) {
+        process.stdout.write(`  ✗ ${f.fullPath}: ${f.error?.message ?? "failed"}
+`);
+      }
+    }
+  }
+  const { base, serveDist } = resolveTutucaBase(projectDir, self, false);
+  const imports = buildImports(base, { margaui });
+  const indexHtml = renderIndexHtml(imports, { margaui, bootstrapUrl: BOOTSTRAP_URL });
+  const bootstrapJs = renderBootstrap(devModuleUrls, { margaui, check });
+  const server = createServer((req, res) => {
+    const path = req.url.split("?")[0];
+    if (path === "/" || path === "/index.html") {
+      res.setHeader("Content-Type", MIME[".html"]);
+      res.end(indexHtml);
+      return;
+    }
+    if (path === BOOTSTRAP_URL) {
+      res.setHeader("Content-Type", MIME[".js"]);
+      res.end(bootstrapJs);
+      return;
+    }
+    if (serveDist && path.startsWith(DIST_PREFIX)) {
+      serveFile(res, safeJoin(serveDist, `/${path.slice(DIST_PREFIX.length)}`));
+      return;
+    }
+    serveFile(res, safeJoin(projectDir, path));
+  });
+  const preferred = Number.parseInt(parsed.values.port ?? "4321", 10);
+  server.on("error", (e) => {
+    if (e.code === "EADDRINUSE") {
+      server.listen(0);
+    } else {
+      throw e;
+    }
+  });
+  server.on("listening", () => {
+    const actual = server.address().port;
+    const where = base.startsWith("http") ? "CDN" : base.startsWith("/node_modules") ? "node_modules" : "local dist";
+    process.stdout.write(`tutuca storybook: http://localhost:${actual}/  (${devModuleUrls.length} dev modules, tutuca from ${where})
+`);
+  });
+  server.listen(preferred);
+}
+var describe4 = "Serve a storybook for the project's co-located *.dev.js modules (auto-discovered).", BOOTSTRAP_URL = "/__tutuca_storybook__.js", DIST_PREFIX = "/__tutuca__/", MIME, MARGAUI_CDN = "https://cdn.jsdelivr.net/npm/margaui/+esm", MARGAUI_THEME = "https://marianoguerra.github.io/margaui/themes/theme.css";
+var init_storybook = __esm(() => {
+  init_chai2();
+  init_test();
+  init_env2();
+  init_errors();
+  MIME = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".css": "text/css",
+    ".html": "text/html; charset=utf-8",
+    ".json": "application/json",
+    ".wasm": "application/wasm",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".map": "application/json"
+  };
+});
 // tools/tutuca.js
 init__registry();
@@ -15644,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",
@@ -15776,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,
@@ -15854,10 +16243,10 @@ init_feedback();
 init_chai_jest();
 var exports_help = {};
 __export(exports_help, {
-  run: () => run4,
-  describe: () => describe4
+  run: () => run5,
+  describe: () => describe5
 });
-var describe4 = "Show usage. `help <command>` for per-command detail.";
+var describe5 = "Show usage. `help <command>` for per-command detail.";
 var OVERVIEW = `tutuca — CLI for inspecting, documenting, linting and rendering tutuca
 components defined in an ES module.
@@ -15874,8 +16263,8 @@ INVOCATION SHAPE
     components; pass it to operate on exactly one (e.g. \`show Button\`).
   - Per-command flags follow the module path; global flags can appear
     anywhere. Unknown flags are rejected by the subcommand's parser.
-  - \`help\`, \`feedback\`, \`install-skill\`, \`agent-context\` do NOT take a
-    module path.
+  - \`help\`, \`feedback\`, \`install-skill\`, \`storybook\`, \`agent-context\` do NOT
+    take a module path.
 MODULE CONVENTION
   A module passed to tutuca must export one or more of:
@@ -15962,6 +16351,20 @@ COMMANDS (no module required)
       or suggestions about the CLI, skills, docs, or the library.
       Message comes from the positional arg or piped stdin.
+  storybook [dir] [--port <n>] [--out <dir>] [--no-margaui] [--no-check] [--no-tests]
+      Serve a live storybook for the project. Recursively auto-discovers
+      co-located *.dev.js modules (dev-only modules holding stories + tests
+      + helpers, never shipped) and mounts them via the tutuca/storybook
+      library — zero setup. By default also runs their getTests() in the
+      terminal and wires margaui styling + an in-browser check(app).
+        [dir]         project root to scan/serve (default: cwd)
+        --port <n>    preferred port (default 4321; else a free port)
+        --out <dir>   write a static index.html + bootstrap (CDN import map)
+                      instead of serving; host from the project root
+        --no-margaui  render unstyled (skip margaui)
+        --no-check    skip the in-browser check(app)
+        --no-tests    skip the pre-serve getTests() run
   agent-context
       Print a machine-readable schema of every command, flag, exit code,
       and error code as JSON on stdout. Use this once to teach an agent the
@@ -16027,21 +16430,22 @@ EXAMPLES
   tutuca lint ./src/components.js
   tutuca render ./src/components.js --title "Disabled state"
 `;
-async function run4(argv, opts = {}) {
+async function run5(argv, opts = {}) {
   const target = argv?.[0];
   if (!target) {
     process.stdout.write(OVERVIEW);
     return;
   }
   if (target === "help") {
-    process.stdout.write(`help: ${describe4}
+    process.stdout.write(`help: ${describe5}
 `);
     return;
   }
   const { COMMANDS: COMMANDS2 } = await Promise.resolve().then(() => (init__registry(), exports__registry));
   const noModule = {
     feedback: await Promise.resolve().then(() => (init_feedback(), exports_feedback)),
-    "install-skill": await Promise.resolve().then(() => (init_install_skill(), exports_install_skill))
+    "install-skill": await Promise.resolve().then(() => (init_install_skill(), exports_install_skill)),
+    storybook: await Promise.resolve().then(() => (init_storybook(), exports_storybook))
   };
   const cmd = COMMANDS2[target] ?? noModule[target];
   if (!cmd) {
@@ -16084,58 +16488,24 @@ ${group}
 // tools/tutuca.js
 init_install_skill();
+init_storybook();
 init_errors();
 // tools/cli/with-module.js
-import { parseArgs as parseArgs3 } from "node:util";
-// tools/cli/env.js
-init_anode();
-init_lint_check();
-import { JSDOM, VirtualConsole } from "jsdom";
-async function createNodeEnv() {
-  const virtualConsole = new VirtualConsole;
-  virtualConsole.forwardTo(console, { jsdomErrors: "none" });
-  virtualConsole.on("jsdomError", (err) => {
-    if (err?.message?.includes("Could not parse CSS stylesheet"))
-      return;
-    console.error(err.message);
-  });
-  const dom = new JSDOM("<!DOCTYPE html><html><head></head><body></body></html>", {
-    virtualConsole
-  });
-  const { document: document2, Text, Comment } = dom.window;
-  globalThis.document = document2;
-  class HeadlessParseContext extends ParseContext {
-    constructor() {
-      super(document2, Text, Comment);
-    }
-  }
-  class HeadlessLintParseContext extends LintParseContext {
-    constructor() {
-      super(document2, Text, Comment);
-    }
-  }
-  return {
-    document: dom.window.document,
-    ParseContext: HeadlessParseContext,
-    LintParseContext: HeadlessLintParseContext
-  };
-}
+init_env2();
+import { parseArgs as parseArgs4 } from "node:util";
 // tools/cli/load.js
-import { resolve as resolve4 } from "node:path";
+import { resolve as resolve5 } from "node:path";
 async function loadAndNormalize(modulePath) {
-  const abs = resolve4(modulePath);
+  const abs = resolve5(modulePath);
   const mod = await import(abs);
   const { normalized } = normalizeModule(mod, { path: abs });
   return normalized;
 }
 // tools/cli/output.js
-import { writeFileSync } from "node:fs";
+import { writeFileSync as writeFileSync2 } from "node:fs";
 // tools/format/cli.js
 var exports_cli = {};
@@ -16621,7 +16991,7 @@ async function formatResult(formatName, result, options = {}) {
 async function emit(result, { format: format5, pretty, output }) {
   const text = await formatResult(format5, result, { pretty });
   if (output) {
-    writeFileSync(output, text);
+    writeFileSync2(output, text);
   } else {
     process.stdout.write(text);
     if (!text.endsWith(`
@@ -16633,7 +17003,7 @@ async function emit(result, { format: format5, pretty, output }) {
 // tools/cli/with-module.js
 async function runCommand(cmd, argv, globalOpts) {
-  const parsed = parseArgs3({
+  const parsed = parseArgs4({
     args: argv,
     options: cmd.parseOptions ?? {},
     allowPositionals: true
@@ -16658,6 +17028,7 @@ var NO_MODULE_COMMANDS = {
   help: exports_help,
   feedback: exports_feedback,
   "install-skill": exports_install_skill,
+  storybook: exports_storybook,
   "agent-context": exports_agent_context
 };
 var VALID_FORMATS = ["cli", "md", "json", "html"];
@@ -16711,7 +17082,7 @@ function dispatchKnownCommands() {
 async function main() {
   const { opts, rest } = extractGlobals(process.argv.slice(2));
   if (rest.length === 0) {
-    await run4([], opts);
+    await run5([], opts);
     return;
   }
   const command = rest[0];
@@ -16722,7 +17093,7 @@ async function main() {
     return;
   }
   if (opts.help) {
-    await run4([command], opts);
+    await run5([command], opts);
     return;
   }
   const cmd = COMMANDS[command];

package/dist/tutuca-storybook.js ADDED Viewed

@@ -0,0 +1,283 @@
+// src/storybook.js
+import { component, html, injectCss, tutuca } from "tutuca";
+var Storybook = component({
+  name: "Storybook",
+  fields: {
+    selectedSectionIndex: 0,
+    sections: [],
+    filter: "",
+    sectionId: null,
+    exampleId: null,
+    focusExample: null
+  },
+  methods: {
+    selectSectionAtIndex(index) {
+      if (this.sections.size === 0)
+        return this;
+      const safeIndex = index >= 0 && index < this.sections.size ? index : 0;
+      const sections = this.sections.map((s, i) => s.setSelected(i === safeIndex));
+      return this.setSelectedSectionIndex(safeIndex).setSections(sections);
+    },
+    selectSectionWithId(id) {
+      if (!id)
+        return this.selectSectionAtIndex(this.selectedSectionIndex);
+      const index = this.sections.findIndex((s) => s.id === id);
+      return this.selectSectionAtIndex(index);
+    },
+    focusExampleByIds(sectionId, exampleId) {
+      if (!sectionId || !exampleId) {
+        return this;
+      }
+      const section = this.sections.find((s) => s.id === sectionId);
+      const example = section?.items.find((e) => e.id === exampleId);
+      if (!example) {
+        return this;
+      }
+      return this.setSectionId(sectionId).setExampleId(exampleId).setFocusExample(example.value);
+    }
+  },
+  input: {
+    onApplyFilter(value, ctx) {
+      ctx.request("persistState", [{ key: "sectionFilter", value }]);
+      return this.setFilter(value);
+    },
+    onClearFilter(ctx) {
+      ctx.request("persistState", [{ key: "sectionFilter", value: "" }]);
+      return this.resetFilter();
+    },
+    onFocusClose(ctx) {
+      ctx.request("persistState", [{ key: "sectionId", value: "" }]);
+      ctx.request("persistState", [{ key: "exampleId", value: "" }]);
+      return this.setSectionId(null).setExampleId(null).setFocusExample(null);
+    }
+  },
+  alter: {
+    filterSection(_key, section) {
+      return this.filter === "" || fuzzyMatch(this.filter, `${section.title} ${section.description}`);
+    }
+  },
+  bubble: {
+    sectionSelected(section, ctx) {
+      ctx.stopPropagation();
+      ctx.request("persistState", [{ key: "section", value: section.id }]);
+      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 }]);
+      return this.setSectionId(sectionId).setExampleId(example.id).setFocusExample(example.value);
+    }
+  },
+  view: html`<div>
+    <div class="flex flex-col gap-3 p-3 h-screen" @show="truthy? .focusExample">
+      <div class="flex justify-end">
+        <button class="btn btn-ghost btn-sm" @on.click="onFocusClose">
+          close
+        </button>
+      </div>
+      <div class="flex-1 overflow-y-auto">
+        <x render=".focusExample"></x>
+      </div>
+    </div>
+    <div class="flex gap-3 p-3 h-screen" @hide="truthy? .focusExample">
+      <div
+        class="w-1/4 flex flex-col gap-3 bg-base-100 shadow-md h-full overflow-hidden"
+      >
+        <input
+          class="input w-full outline-0 focus:bg-base-200"
+          type="search"
+          placeholder="Filter sections"
+          :value=".filter"
+          @on.input="onApplyFilter value"
+          @on.keydown.cancel="onClearFilter"
+        />
+        <div class="list h-full flex-1 overflow-y-auto">
+          <x render-each=".sections" as="listEntry" when="filterSection"></x>
+        </div>
+      </div>
+      <div class="w-full h-full overflow-y-auto">
+        <x render=".sections[.selectedSectionIndex]"></x>
+      </div>
+    </div>
+  </div>`
+});
+var Section = component({
+  name: "Section",
+  fields: {
+    id: "?",
+    title: "No Title Section",
+    description: "",
+    items: [],
+    filter: "",
+    selected: false
+  },
+  statics: {
+    fromData({ id, title = "???", description = "", items = [] }) {
+      id ??= slugify(title);
+      return this.make({
+        id,
+        title,
+        description,
+        items: items.map((v) => Example.Class.fromData(v))
+      });
+    }
+  },
+  alter: {
+    filterItem(_key, item) {
+      return this.filter === "" || fuzzyMatch(this.filter, `${item.title} ${item.description}`);
+    }
+  },
+  input: {
+    onApplyFilter(value, ctx) {
+      ctx.request("persistState", [{ key: "exampleFilter", value }]);
+      return this.setFilter(value);
+    },
+    onClearFilter(ctx) {
+      ctx.request("persistState", [{ key: "exampleFilter", value: "" }]);
+      return this.resetFilter();
+    },
+    onListItemClick(ctx) {
+      ctx.bubble("sectionSelected", [this]);
+      return this;
+    }
+  },
+  view: html`<section class="flex flex-col gap-3">
+    <div class="sticky top-0 z-10 bg-base-100 pt-1 pb-2 shadow-sm">
+      <h2 class="text-lg font-bold" @text=".title"></h2>
+      <p class="text-md italic opacity-60" @text=".description"></p>
+    </div>
+    <input
+      class="input w-full outline-0 focus:bg-base-200"
+      type="search"
+      placeholder="Filter examples"
+      :value=".filter"
+      @on.input="onApplyFilter value"
+      @on.keydown.cancel="onClearFilter"
+    />
+    <div class="flex flex-col gap-3">
+      <x render-each=".items" when="filterItem"></x>
+    </div>
+  </section>`,
+  views: {
+    listEntry: html`<div
+      @if.class=".selected"
+      @then="'list-row cursor-pointer text-blue-400 hover:text-blue-500 font-semibold'"
+      @else="'list-row cursor-pointer hover:bg-base-200'"
+      :title=".description"
+      @on.click="onListItemClick"
+    >
+      <div @text=".title" class="list-col-grow"></div>
+      <p
+        class="text-xs opacity-60 list-col-wrap truncate"
+        @text=".description"
+      ></p>
+    </div> `
+  }
+});
+var Example = component({
+  name: "Example",
+  fields: { id: "?", title: "?", description: "", value: null, view: "main" },
+  statics: {
+    fromData({ id, title = "No Title Example", description = "", value = null, view = "main" }) {
+      id ??= slugify(title);
+      return this.make({
+        id,
+        title,
+        description,
+        value,
+        view
+      });
+    }
+  },
+  input: {
+    onLogSelected() {
+      console.log(this.value);
+      return this;
+    },
+    onFocusSelected(ctx) {
+      ctx.bubble("exampleFocusRequested", [this]);
+      return this;
+    }
+  },
+  view: html`<div class="card card-border bg-base-100 shadow-md">
+    <div class="card-body">
+      <h2 class="card-title flex justify-between">
+        <a :href="$'#example-{.id}'" :id="$'example-{.id}'" @text=".title"></a>
+        <div class="flex gap-2">
+          <button class="btn btn-ghost btn-sm" @on.click="onFocusSelected">
+            focus
+          </button>
+          <button class="btn btn-ghost btn-sm" @on.click="onLogSelected">
+            log
+          </button>
+        </div>
+      </h2>
+      <p class="text-md italic opacity-60" @text=".description"></p>
+      <div class="bg-base-100 p-3" @push-view=".view">
+        <x render=".value"></x>
+      </div>
+    </div>
+  </div>`
+});
+function fuzzyMatch(query, target) {
+  const q = query.toLowerCase(), t = target.toLowerCase();
+  let qi = 0;
+  for (let ti = 0;ti < t.length && qi < q.length; ti++) {
+    if (t[ti] === q[qi])
+      qi++;
+  }
+  return qi === q.length;
+}
+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 components = new Set([Storybook, Section, Example]);
+  const macros = {};
+  const requestHandlers = {};
+  for (const m of modules) {
+    for (const c of m.getComponents?.() ?? []) {
+      components.add(c);
+    }
+    if (m.getMacros)
+      Object.assign(macros, m.getMacros());
+    if (m.getRequestHandlers)
+      Object.assign(requestHandlers, m.getRequestHandlers());
+  }
+  return {
+    root: Storybook.make({ sections }),
+    components: [...components],
+    macros,
+    requestHandlers
+  };
+}
+async function mountStorybook(selector, modules, { compileCss, root } = {}) {
+  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 (compileCss) {
+    injectCss("tutuca-storybook", await compileCss(app));
+  }
+  app.start();
+  return app;
+}
+function getComponents() {
+  return [Storybook, Section, Example];
+}
+export {
+  slugify,
+  mountStorybook,
+  getComponents,
+  fuzzyMatch,
+  buildStorybook,
+  Storybook,
+  Section,
+  Example
+};

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.83",
+  "version": "0.9.85",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -13,6 +13,7 @@
     "./ext": "./dist/tutuca.ext.js",
     "./extra-ext": "./dist/tutuca-extra.ext.js",
     "./dev-ext": "./dist/tutuca-dev.ext.js",
+    "./storybook": "./dist/tutuca-storybook.js",
     "./immutable": "./dist/immutable.js",
     "./chai": "./dist/chai.js",
     "./package.json": "./package.json"
@@ -54,6 +55,7 @@
     "dist/tutuca.ext.js",
     "dist/tutuca-extra.ext.js",
     "dist/tutuca-dev.ext.js",
+    "dist/tutuca-storybook.js",
     "dist/immutable.js",
     "dist/chai.js",
     "skill"

package/skill/tutuca/cli.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -977,6 +977,23 @@ export function getExamples()         {
 export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
 ```
+Best practice: have `getComponents()` return **every** component the module
+defines — child and helper components included — and give each one at least
+one item in `getExamples()`. A component left out of `getComponents()` is
+invisible to `tutuca lint`/`render`/`test`, so it silently loses linting and
+render coverage. If your components already live behind a differently named
+export, alias it instead of teaching tools a new name:
+```js
+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