tutuca 0.9.97 → 0.9.99

package/README.md

@@ -7,7 +7,7 @@ Zero-dependency batteries included SPA framework.
 - **Fits in your head** (and the context window)
 - **View source friendly** — step through the whole stack
 - **As much HTML as possible, as little JS as needed**
-- ~177KB minified, ~40KB brotli compressed
+- ~182KB minified, ~41KB brotli compressed
 
 ## Quick Start
 
@@ -95,6 +95,7 @@ tutuca help [command]
 | `lint <module> [name]` | Run lint checks — all, or one by name (exit 2 on errors) |
 | `render <module> [name] [--title t] [--view v]` | Render examples to HTML |
 | `test <module> [name] [--grep p] [--bail]` | Run `getTests()` (exit 4 on failures) |
+| `storybook [dir]` | Serve a live storybook, auto-discovering co-located `*.dev.js` modules (`--port`, `--out`, `--dry-run`, `--no-margaui`, `--no-check`, `--no-tests`; no module path needed) |
 | `feedback [message]` | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl` (no module path needed) |
 | `install-skill [--user\|--project] [--margaui-skill\|--immutable-skill\|--all] [--dot-agents] [--dry-run] [--force]` | Install bundled Claude Code skills (no module path needed) |
 | `agent-context` | Print a versioned JSON schema of the entire CLI surface (no module path needed) |
@@ -146,8 +147,9 @@ The invocation stays short even without wrapping, but common patterns:
 
 ## Use with Claude Code
 
-Tutuca ships an LLM-facing reference (`SKILL.md` + `core.md` / `cli.md` /
-`advanced.md` / `testing.md`) packaged as a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills).
+Tutuca ships an LLM-facing reference (`SKILL.md` plus topic files such as
+`core.md`, `cli.md`, `advanced.md`, `testing.md`, `storybook.md`, and more)
+packaged as a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills).
 Once installed, Claude auto-loads it whenever a session touches tutuca
 components, views, macros, or the CLI.
 

package/dist/tutuca-cli.js

@@ -9799,37 +9799,47 @@ class Renderer {
   renderEach(stack, iterInfo, node, viewName) {
     const { seq, filter, loopWith } = iterInfo.eval(stack);
     const r = [];
-    const { iterData, start, end } = unpackLoopResult(loopWith.call(stack.it, seq), seq);
-    getSeqInfo(seq)(seq, (key, value, attrName) => {
-      if (filter.call(stack.it, key, value, iterData)) {
-        const dom = this.renderIt(stack.enter(value, { key }, true), node, key, viewName);
-        this.pushEachEntry(r, node.nodeId, attrName, key, dom);
-      }
-    }, start, end);
+    const { iterData, start, end, keys } = unpackLoopResult(loopWith.call(stack.it, seq, makeLoopCtx(stack, filter)), seq);
+    const renderOne = (key, value, attrName) => {
+      const dom = this.renderIt(stack.enter(value, { key }, true), node, key, viewName);
+      this.pushEachEntry(r, node.nodeId, attrName, key, dom);
+    };
+    if (keys)
+      imKeysIter(seq, renderOne, keys);
+    else
+      getSeqInfo(seq)(seq, (key, value, attrName) => {
+        if (filter.call(stack.it, key, value, iterData))
+          renderOne(key, value, attrName);
+      }, start, end);
     return r;
   }
   renderEachWhen(stack, iterInfo, view, nid) {
     const { seq, filter, loopWith, enricher } = iterInfo.eval(stack);
     const r = [];
     const it = stack.it;
-    const { iterData, start, end } = unpackLoopResult(loopWith.call(it, seq), seq);
-    getSeqInfo(seq)(seq, (key, value, attrName) => {
-      if (filter.call(it, key, value, iterData)) {
-        const cachePath = enricher ? [view, it, value] : [view, value];
-        const binds = { key, value };
-        const cacheKey = `${nid}-${key}`;
-        if (enricher)
-          enricher.call(it, binds, key, value, iterData);
-        const cachedNode = this.cache.get(cachePath, cacheKey);
-        if (cachedNode)
-          this.pushEachEntry(r, nid, attrName, key, cachedNode);
-        else {
-          const dom = this.renderView(view, stack.enter(value, binds, false));
-          this.pushEachEntry(r, nid, attrName, key, dom);
-          this.cache.set(cachePath, cacheKey, dom);
-        }
+    const { iterData, start, end, keys } = unpackLoopResult(loopWith.call(it, seq, makeLoopCtx(stack, filter)), seq);
+    const renderOne = (key, value, attrName) => {
+      const cachePath = enricher ? [view, it, value] : [view, value];
+      const binds = { key, value };
+      const cacheKey = `${nid}-${key}`;
+      if (enricher)
+        enricher.call(it, binds, key, value, iterData);
+      const cachedNode = this.cache.get(cachePath, cacheKey);
+      if (cachedNode)
+        this.pushEachEntry(r, nid, attrName, key, cachedNode);
+      else {
+        const dom = this.renderView(view, stack.enter(value, binds, false));
+        this.pushEachEntry(r, nid, attrName, key, dom);
+        this.cache.set(cachePath, cacheKey, dom);
       }
-    }, start, end);
+    };
+    if (keys)
+      imKeysIter(seq, renderOne, keys);
+    else
+      getSeqInfo(seq)(seq, (key, value, attrName) => {
+        if (filter.call(it, key, value, iterData))
+          renderOne(key, value, attrName);
+      }, start, end);
     return r;
   }
   renderView(view, stack) {
@@ -9861,8 +9871,15 @@ var DATASET_ATTRS, getSeqInfo = (seq) => isIndexed(seq) ? imIndexedIter : isKeye
   return [s, e < s ? s : e];
 }, filterAlwaysTrue = (_v, _k, _seq) => true, nullLoopWith = (seq) => ({ iterData: { seq } }), unpackLoopResult = (result, seq) => {
   const r = result ?? {};
-  return { iterData: r.iterData ?? { seq }, start: r.start, end: r.end };
-}, imIndexedIter = (seq, visit, start, end) => {
+  return { iterData: r.iterData ?? { seq }, start: r.start, end: r.end, keys: r.keys };
+}, imKeysIter = (seq, visit, keys) => {
+  const attrName = isIndexed(seq) ? "si" : "sk";
+  for (const key of keys)
+    visit(key, seq.get(key), attrName);
+}, makeLoopCtx = (stack, filter) => ({
+  lookup: (name) => stack.lookupBind(name),
+  filter: (key, value, iterData) => filter.call(stack.it, key, value, iterData)
+}), imIndexedIter = (seq, visit, start, end) => {
   const [s, e] = normalizeRange(start, end, seq.size);
   for (let i = s;i < e; i++)
     visit(i, seq.get(i), "si");
@@ -10049,11 +10066,11 @@ class IterInfo {
     return { seq, filter, loopWith, enricher };
   }
   enrichBinds(stack, key) {
-    const { seq, loopWith, enricher } = this.eval(stack);
+    const { seq, filter, loopWith, enricher } = this.eval(stack);
     const value = seq?.get ? seq.get(key, null) : null;
     const binds = { key, value };
     if (enricher) {
-      const { iterData } = unpackLoopResult(loopWith.call(stack.it, seq), seq);
+      const { iterData } = unpackLoopResult(loopWith.call(stack.it, seq, makeLoopCtx(stack, filter)), seq);
       enricher.call(stack.it, binds, key, value, iterData);
     }
     return binds;
@@ -11377,7 +11394,7 @@ var init_html_tokenizer = __esm(() => {
 });
 
 // tools/core/htmllinter-tables.js
-var VOID_ELEMENTS, RAW_TEXT_ELEMENTS, RCDATA_ELEMENTS, SPECIAL_ELEMENTS, FORMATTING_ELEMENTS, DEFAULT_SCOPE_BOUNDARIES, MATHML_TEXT_INTEGRATION_POINT_NAMES, SVG_HTML_INTEGRATION_POINT_NAMES, SCOPE_LIST_ITEM, SCOPE_BUTTON, SCOPE_DEFAULT, SCOPE_TABLE, SCOPE_SELECT, STANDARD_SVG_CAMEL_ELEMENTS, STANDARD_SVG_CAMEL_ATTRS, MATHML_CAMEL_ATTRS, SVG_ATTR_LOWERCASE_TO_CAMEL, MATHML_ATTR_LOWERCASE_TO_CAMEL, FOREIGN_BREAKOUT_TAGS, MATHML_TEXT_INTEGRATION_POINTS, BLOCK_LEVEL_AUTO_CLOSE_P, SELECT_VALID_CHILDREN, SELECT_BREAKOUT_TAGS, MODES, NS, FRAGMENT_CONTEXT_MODES;
+var VOID_ELEMENTS, RAW_TEXT_ELEMENTS, SPECIAL_ELEMENTS, FORMATTING_ELEMENTS, DEFAULT_SCOPE_BOUNDARIES, MATHML_TEXT_INTEGRATION_POINT_NAMES, SVG_HTML_INTEGRATION_POINT_NAMES, SCOPE_LIST_ITEM, SCOPE_BUTTON, SCOPE_DEFAULT, SCOPE_TABLE, STANDARD_SVG_CAMEL_ELEMENTS, STANDARD_SVG_CAMEL_ATTRS, MATHML_CAMEL_ATTRS, SVG_ATTR_LOWERCASE_TO_CAMEL, MATHML_ATTR_LOWERCASE_TO_CAMEL, FOREIGN_BREAKOUT_TAGS, BLOCK_LEVEL_AUTO_CLOSE_P, SELECT_BREAKOUT_TAGS, MODES, NS, FRAGMENT_CONTEXT_MODES;
 var init_htmllinter_tables = __esm(() => {
   VOID_ELEMENTS = new Set([
     "area",
@@ -11404,7 +11421,6 @@ var init_htmllinter_tables = __esm(() => {
     "xmp",
     "plaintext"
   ]);
-  RCDATA_ELEMENTS = new Set(["textarea", "title"]);
   SPECIAL_ELEMENTS = new Set([
     "address",
     "applet",
@@ -11519,7 +11535,6 @@ var init_htmllinter_tables = __esm(() => {
   SCOPE_BUTTON = new Set([...DEFAULT_SCOPE_BOUNDARIES, "button"]);
   SCOPE_DEFAULT = DEFAULT_SCOPE_BOUNDARIES;
   SCOPE_TABLE = new Set(["html", "table", "template"]);
-  SCOPE_SELECT = new Set;
   STANDARD_SVG_CAMEL_ELEMENTS = new Set([
     "altGlyph",
     "altGlyphDef",
@@ -11671,7 +11686,6 @@ var init_htmllinter_tables = __esm(() => {
     "ul",
     "var"
   ]);
-  MATHML_TEXT_INTEGRATION_POINTS = new Set(["mi", "mo", "mn", "ms", "mtext"]);
   BLOCK_LEVEL_AUTO_CLOSE_P = new Set([
     "address",
     "article",
@@ -11714,7 +11728,6 @@ var init_htmllinter_tables = __esm(() => {
     "dd",
     "dt"
   ]);
-  SELECT_VALID_CHILDREN = new Set(["option", "optgroup", "hr", "script", "template"]);
   SELECT_BREAKOUT_TAGS = new Set(["input", "keygen", "textarea", "select"]);
   MODES = Object.freeze({
     inBody: "inBody",
@@ -14760,6 +14773,13 @@ function phaseOps(phase) {
 function resolveArgs(args, self) {
   return typeof args === "function" ? args(self) ?? [] : args ?? [];
 }
+function phaseHasBubble(phase) {
+  if (!phase)
+    return false;
+  if (phase.bubble?.length)
+    return true;
+  return (phase.do ?? []).some((op) => op.type === "bubble");
+}
 function dispatchPhase(dispatcher, targetPath, phase, self) {
   if (!phase)
     return;
@@ -14938,6 +14958,8 @@ async function driveStack(stack, value, phase, opts = {}) {
       const t = info?.transaction;
       opts.onMessage({ kind: t?.handlerProp ?? "input", name: t?.name, args: t?.args, path: t?.path }, old, val);
     });
+  if (phaseHasBubble(phase))
+    console.warn("drive(): a `bubble` action is a no-op here — drive originates at the root and bubbles travel child→parent, so there is no ancestor to receive it (and the root's own bubble handler is skipped). To exercise a bubble handler, call it directly.");
   dispatchPhase(rootDispatcher(transactor), new Path([]), phase, value);
   await transactor.settle();
   return transactor.state.val;
@@ -15113,13 +15135,17 @@ var init__registry = __esm(() => {
       exitOn: (result) => result.hasErrors ? 3 : 0
     },
     test: {
-      describe: "Run tests defined by getTests() (optional <name> to filter by component).",
+      describe: "Run tests defined by getTests() (optional <name> to filter by component). Pass a directory to run every *.test.js / *.dev.js under it.",
       defaultFormat: "cli",
       needsEnv: true,
       parseOptions: {
         grep: { type: "string" },
         bail: { type: "boolean" }
       },
+      acceptsDir: true,
+      dirMatch: (name) => name.endsWith(".test.js") || name.endsWith(".dev.js"),
+      dirFilter: (normalized) => typeof normalized.mod.getTests === "function",
+      mergeResults: (reports) => new TestReport({ modules: reports.flatMap((r) => r.modules) }),
       run: (normalized, { values, positionals }) => runTests({
         getTests: normalized.mod.getTests,
         components: normalized.components,
@@ -16011,6 +16037,23 @@ var init_env2 = __esm(() => {
   init_lint_check();
 });
 
+// tools/cli/walk.js
+import { readdirSync as readdirSync2 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
+function walkFiles(dir, { match }, 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())
+      walkFiles(full, { match }, acc);
+    else if (e.isFile() && match(e.name))
+      acc.push(full);
+  }
+  return acc;
+}
+var init_walk = () => {};
+
 // tools/cli/commands/storybook.js
 var exports_storybook = {};
 __export(exports_storybook, {
@@ -16021,45 +16064,34 @@ 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 { dirname as dirname4, join, normalize, relative as relative2, resolve as resolve5, 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 findDevModules(root) {
+  return walkFiles(root, { match: (name) => name.endsWith(".dev.js") }).map((full) => `/${relative2(root, full).split(sep).join("/")}`);
 }
 function findSelf() {
   const here = dirname4(fileURLToPath4(import.meta.url));
   const pkgCandidates = [
-    resolve4(here, "..", "..", "..", "package.json"),
-    resolve4(here, "..", "package.json")
+    resolve5(here, "..", "..", "..", "package.json"),
+    resolve5(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;
+  const distCandidates = [resolve5(here, "..", "..", "..", "dist"), resolve5(here, ".")];
+  const distRoot = distCandidates.find((d) => existsSync4(resolve5(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"))) {
+  const nm = resolve5(projectDir, "node_modules", "tutuca", "dist");
+  if (existsSync4(resolve5(nm, "tutuca-dev.js"))) {
     return { base: "/node_modules/tutuca/dist", serveDist: null };
   }
   if (self.distRoot)
@@ -16079,7 +16111,8 @@ function buildImports(base, { margaui }) {
     tutuca: dev,
     "tutuca/extra": dev,
     "tutuca/dev": dev,
-    "tutuca/storybook": `${base}/tutuca-storybook.js`
+    "tutuca/storybook": `${base}/tutuca-storybook.js`,
+    "tutuca/components": `${base}/tutuca-components.js`
   };
   if (margaui)
     imports.margaui = MARGAUI_CDN;
@@ -16105,19 +16138,27 @@ ${JSON.stringify({ imports }, null, 6)}
 </html>
 `;
 }
-function renderBootstrap(devModuleUrls, { margaui, check }) {
+function renderBootstrap(devModuleUrls, { margaui, check, inspect: inspect3 }) {
   const lines = ['import { mountStorybook } from "tutuca/storybook";'];
   if (margaui) {
     lines.push('import { compileClassesToStyleText } from "tutuca/extra";');
     lines.push('import { compile } from "margaui";');
   }
+  if (inspect3) {
+    lines.push('import { shadowCheckComponent, runTests, expect } from "tutuca/dev";');
+  }
   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) }" : "{}";
+  const optParts = [];
+  if (margaui)
+    optParts.push("compileCss: (app) => compileClassesToStyleText(app, compile)");
+  if (inspect3)
+    optParts.push("dev: { shadowCheckComponent, runTests, expect }");
+  const opts = optParts.length ? `{ ${optParts.join(", ")} }` : "{}";
   lines.push("");
   lines.push(`const app = await mountStorybook("#app", [${modules}], ${opts});`);
   if (check)
@@ -16134,7 +16175,7 @@ async function runDevTests(projectDir, devModuleUrls) {
   const failures = [];
   const importErrors = [];
   for (const url of devModuleUrls) {
-    const abs = resolve4(projectDir, url.slice(1));
+    const abs = resolve5(projectDir, url.slice(1));
     let mod;
     try {
       mod = await import(abs);
@@ -16166,7 +16207,7 @@ async function discoverModules(projectDir, devModuleUrls) {
   await createNodeEnv();
   const modules = [];
   for (const url of devModuleUrls) {
-    const abs = resolve4(projectDir, url.slice(1));
+    const abs = resolve5(projectDir, url.slice(1));
     try {
       const mod = await import(abs);
       const { normalized, present } = normalizeModule(mod, { path: abs });
@@ -16231,6 +16272,7 @@ async function run4(argv, opts = {}) {
       out: { type: "string" },
       "no-margaui": { type: "boolean", default: false },
       "no-check": { type: "boolean", default: false },
+      "no-inspect": { type: "boolean", default: false },
       "no-tests": { type: "boolean", default: false },
       "dry-run": { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
@@ -16239,7 +16281,7 @@ async function run4(argv, opts = {}) {
   });
   if (parsed.values.help) {
     process.stdout.write(`tutuca storybook [dir] [--port <n>] [--out <dir>] [--dry-run]
-                 [--no-margaui] [--no-check] [--no-tests]
+                 [--no-margaui] [--no-check] [--no-inspect] [--no-tests]
 
   Auto-discovers co-located *.dev.js modules (recursively, skipping
   node_modules/dotdirs) and serves a live storybook that mounts them via
@@ -16254,11 +16296,12 @@ async function run4(argv, opts = {}) {
                  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-inspect   skip the per-example Component/Instance/Data/Lint/Test tabs
   --no-tests     skip running the modules' getTests() before serving
 `);
     return;
   }
-  const projectDir = resolve4(parsed.positionals[0] ?? process.cwd());
+  const projectDir = resolve5(parsed.positionals[0] ?? process.cwd());
   if (!existsSync4(projectDir) || !statSync(projectDir).isDirectory()) {
     emitError(opts, {
       code: CODES.USAGE_MISSING_ARGUMENT,
@@ -16266,7 +16309,7 @@ async function run4(argv, opts = {}) {
       hint: "Pass a project directory to scan, or omit it to use the current directory."
     });
   }
-  const devModuleUrls = findDevModules(projectDir, projectDir, []);
+  const devModuleUrls = findDevModules(projectDir);
   if (devModuleUrls.length === 0) {
     emitError(opts, {
       code: CODES.USAGE_MISSING_ARGUMENT,
@@ -16276,15 +16319,16 @@ async function run4(argv, opts = {}) {
   }
   const margaui = !parsed.values["no-margaui"];
   const check = !parsed.values["no-check"];
+  const inspect3 = !parsed.values["no-inspect"];
   const self = findSelf();
   if (parsed.values.out) {
-    const outDir = resolve4(parsed.values.out);
+    const outDir = resolve5(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 }));
+    writeFileSync(resolve5(outDir, "index.html"), renderIndexHtml(imports2, { margaui, bootstrapUrl: `./${bootstrapName}` }));
+    writeFileSync(resolve5(outDir, bootstrapName), renderBootstrap(devModuleUrls, { margaui, check, inspect: inspect3 }));
     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.
@@ -16369,7 +16413,7 @@ async function run4(argv, opts = {}) {
   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 bootstrapJs = renderBootstrap(devModuleUrls, { margaui, check, inspect: inspect3 });
   const server = createServer((req, res) => {
     const path = req.url.split("?")[0];
     if (path === "/" || path === "/index.html") {
@@ -16410,6 +16454,7 @@ var init_storybook = __esm(() => {
   init_test();
   init_env2();
   init_errors();
+  init_walk();
   MIME = {
     ".js": "text/javascript",
     ".mjs": "text/javascript",
@@ -16943,17 +16988,60 @@ ${group}
 // tools/tutuca.js
 init_install_skill();
 init_storybook();
+
+// tools/cli/dev-build-hook.js
+import { register } from "node:module";
+function installDevBuildResolveHook() {
+  let devUrl;
+  try {
+    devUrl = import.meta.resolve("tutuca/dev");
+  } catch {
+    return false;
+  }
+  const hookSource = `
+let devUrl;
+export async function initialize(data) { devUrl = data.devUrl; }
+export async function resolve(specifier, context, nextResolve) {
+  return specifier === "tutuca"
+    ? { url: devUrl, shortCircuit: true }
+    : nextResolve(specifier, context);
+}`;
+  try {
+    register(`data:text/javascript,${encodeURIComponent(hookSource)}`, import.meta.url, {
+      data: { devUrl }
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// tools/tutuca.js
 init_errors();
 
 // tools/cli/with-module.js
 init_env2();
+init_errors();
+import { statSync as statSync2 } from "node:fs";
 import { parseArgs as parseArgs4 } from "node:util";
 
 // tools/cli/load.js
-import { resolve as resolve5 } from "node:path";
+import { existsSync as existsSync5 } from "node:fs";
+import { resolve as resolve6 } from "node:path";
 async function loadAndNormalize(modulePath) {
-  const abs = resolve5(modulePath);
-  const mod = await import(abs);
+  const abs = resolve6(modulePath);
+  let mod;
+  try {
+    mod = await import(abs);
+  } catch (e) {
+    const entryProblem = e?.code === "ERR_UNSUPPORTED_DIR_IMPORT" || e?.code === "ERR_MODULE_NOT_FOUND" && !existsSync5(abs);
+    if (entryProblem) {
+      const err = new Error(e.code === "ERR_UNSUPPORTED_DIR_IMPORT" ? `expected a module file, got a directory: ${modulePath}` : `module not found: ${modulePath}`);
+      err.code = "ERR_MODULE_LOAD_FAILED";
+      throw err;
+    }
+    throw e;
+  }
   const { normalized } = normalizeModule(mod, { path: abs });
   return normalized;
 }
@@ -17456,15 +17544,57 @@ async function emit(result, { format: format5, pretty, output }) {
 }
 
 // tools/cli/with-module.js
+init_walk();
 async function runCommand(cmd, argv, globalOpts) {
   const parsed = parseArgs4({
     args: argv,
     options: cmd.parseOptions ?? {},
     allowPositionals: true
   });
+  let stat = null;
+  try {
+    stat = statSync2(globalOpts.module);
+  } catch {}
+  if (stat?.isDirectory()) {
+    await runOnDir(cmd, parsed, globalOpts);
+    return;
+  }
   const normalized = await loadAndNormalize(globalOpts.module);
   const env = cmd.needsEnv ? await createNodeEnv() : null;
   const result = await cmd.run(normalized, parsed, env);
+  await emitResult(cmd, result, globalOpts);
+}
+async function runOnDir(cmd, parsed, globalOpts) {
+  if (!cmd.acceptsDir) {
+    emitError(globalOpts, {
+      code: CODES.MODULE_LOAD_FAILED,
+      message: `expected a module file, got a directory: ${globalOpts.module}`,
+      hint: "This command takes a single module file (.js). Pass a file path."
+    });
+    return;
+  }
+  const files = walkFiles(globalOpts.module, { match: cmd.dirMatch });
+  const normalizedAll = [];
+  for (const file of files) {
+    const normalized = await loadAndNormalize(file);
+    if (!cmd.dirFilter || cmd.dirFilter(normalized))
+      normalizedAll.push(normalized);
+  }
+  if (normalizedAll.length === 0) {
+    emitError(globalOpts, {
+      code: CODES.MODULE_LOAD_FAILED,
+      message: `no test modules found under ${globalOpts.module}`,
+      hint: "Test modules are *.test.js / *.dev.js files that export getTests()."
+    });
+    return;
+  }
+  const env = cmd.needsEnv ? await createNodeEnv() : null;
+  const results = [];
+  for (const normalized of normalizedAll)
+    results.push(await cmd.run(normalized, parsed, env));
+  await emitResult(cmd, cmd.mergeResults(results), globalOpts);
+}
+async function emitResult(cmd, result, globalOpts) {
   await emit(result, {
     format: globalOpts.format ?? cmd.defaultFormat,
     pretty: globalOpts.pretty,
@@ -17573,6 +17703,8 @@ async function main() {
     opts.module = rest[1];
     commandArgs = rest.slice(2);
   }
+  if (command === "test")
+    installDevBuildResolveHook();
   try {
     await runCommand(cmd, commandArgs, opts);
   } catch (e) {
@@ -17610,6 +17742,13 @@ async function main() {
         hint: shape.hint ?? `Run \`tutuca help ${command}\` for valid flags.`
       });
     }
+    if (e?.code === "ERR_MODULE_LOAD_FAILED") {
+      emitError(opts, {
+        code: CODES.MODULE_LOAD_FAILED,
+        message: e.message,
+        hint: "Pass a module file path. `tutuca test` also accepts a directory to run every test module under it."
+      });
+    }
     throw e;
   }
 }