tutuca 0.9.44 → 0.9.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.44",
+  "version": "0.9.45",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -33,7 +33,7 @@
     "fix": "bunx @biomejs/biome check --write src test/*.js",
     "tutuca": "bun tools/tutuca.js",
     "stresstest": "bun scripts/stresstest.js",
-    "smoke-test": "bun tools/tutuca.js ./test/todo.js lint && bun tools/tutuca.js ./test/todo.js render && bun tools/tutuca.js ./test/json.js lint && bun tools/tutuca.js ./test/json.js render"
+    "smoke-test": "bun tools/tutuca.js ./test/todo.js lint && bun tools/tutuca.js ./test/todo.js render && bun tools/tutuca.js ./test/todo.js test && bun tools/tutuca.js ./test/json.js lint && bun tools/tutuca.js ./test/json.js render"
   },
   "sideEffects": false,
   "files": [
@@ -47,6 +47,7 @@
     "skill"
   ],
   "dependencies": {
+    "chai": "^6.2.2",
     "jsdom": "^28.0.0 || ^29.0.0"
   },
   "peerDependencies": {

package/skill/tutuca/advanced.md

@@ -145,7 +145,6 @@ collects the `class=` and `:class=` literals, hands them to a `compile`
 function (any margaui-compatible signature), and returns CSS text. Pair
 with `injectCss(scopeName, css)` to install the result before `start()`.
 
-If a margaui skill is installed in this project (e.g.
-`.claude/skills/margaui/`) load it alongside this one when authoring
-class lists — it lists the available components and their canonical
-class strings, which is what the `compile` step expects.
+If a margaui skill is available, load it alongside this one when
+authoring class lists — it lists the available components and their
+canonical class strings, which is what the `compile` step expects.

package/skill/tutuca/cli.md

@@ -1,11 +1,11 @@
 # Tutuca CLI Reference
 
-The `tutuca` CLI inspects, documents, lints, and renders any module that
-follows the *Conventional Module Exports* shape (see `core.md`). Reach
-this file when you need command/flag/exit-code details, or when reading
-a lint code out of `lint` output. Otherwise the post-edit recipe in
-`core.md` (run `lint`, then `render --title "<your example>"`) is
-enough.
+The `tutuca` CLI inspects, documents, lints, tests, and renders any
+module that follows the *Conventional Module Exports* shape (see
+`core.md`). Reach this file when you need command/flag/exit-code
+details, or when reading a lint code out of `lint` output. Otherwise
+the post-edit recipe in `core.md` (run `lint`, then `test` for
+behavior changes, then `render --title "<your example>"`) is enough.
 
 ## Install / invoke
 
@@ -36,6 +36,7 @@ prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
 | `docs [name]`   | Generate API docs (methods, input handlers, fields with auto-generated accessors) — all or one                         |
 | `lint [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
 | `render [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
+| `test [name]`   | Run tests defined by `getTests({ describe, test, expect })`. Filter by component name, `--grep <pattern>`, or `--bail`. Exits **4** on any failure |
 | `help [cmd]`    | Show usage; the only command that does **not** need a module path                                                      |
 
 ## Global flags
@@ -61,6 +62,7 @@ prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
 | `1`  | usage error (bad args, missing module, bad module shape) |
 | `2`  | lint findings at error level                             |
 | `3`  | render crash                                             |
+| `4`  | one or more tests failed                                 |
 
 ## Examples
 
@@ -77,8 +79,77 @@ tutuca ./src/components.js render Button --title "Disabled state"
 tutuca ./src/components.js lint
 tutuca ./src/components.js render --title "Disabled state"
 tutuca ./src/components.js render --title "Disabled state" --pretty
+
+# Component-behavior verification: run the suite for one component, or
+# narrow further with --grep. Add tests next to the component (the
+# getTests() export) when the change isn't observable from render alone.
+tutuca ./src/components.js test Counter
+tutuca ./src/components.js test Counter --grep "inc()"
+tutuca ./src/components.js test --bail
+```
+
+## `test` — running component tests
+
+Use `test` after edits that change attributes, instance methods, input
+handlers, or static factories — anything observable from JS rather than
+from rendered HTML. The module opts in by exporting
+`getTests({ describe, test, expect })`:
+
+- `describe(Component, fn)` tags the suite with `Component.name` so
+  the positional `[name]` filter can pick it.
+- `describe(title, fn)` is untagged; reachable only via `--grep`.
+- `describe(title, { component }, fn)` tags an explicit title with a
+  custom component name.
+- `test(title, fn)` — `fn` may be async; assertions use the injected
+  chai `expect`.
+
+Filters:
+
+- `[name]` — only tests whose tagged `componentName` equals `<name>`.
+- `--grep <p>` — substring match against the full path
+  (e.g. `"Counter > inc() > works on a negative counter"`).
+- `--bail` — stop on first failure; remaining tests reported as `skip`.
+
+Default format is `cli` (a tree with ✓/✗/○ and per-test durations);
+`-f md` and `-f json` work too.
+
+A worked `getTests()` export covering methods, input handlers (called
+via `Comp.input.x.call(inst)`), and immutability:
+
+```js
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    describe("inc()", () => {                           // method
+      test("returns a Counter with count + 1", () => {
+        const next = Counter.make().inc();
+        expect(next).to.be.instanceOf(Counter.Class);
+        expect(next.count).to.equal(1);
+      });
+      test("does not mutate the original instance", () => {
+        const c = Counter.make({ count: 7 });
+        c.inc();
+        expect(c.count).to.equal(7);                    // immutability
+      });
+    });
+
+    describe("dec()", () => {                           // input handler
+      test("returns a Counter with count - 1", () => {
+        const next = Counter.input.dec.call(Counter.make());
+        expect(next.count).to.equal(-1);
+      });
+    });
+
+    test("inc and dec round-trip", () => {              // untagged path
+      expect(Counter.input.dec.call(Counter.make().inc()).count).to.equal(0);
+    });
+  });
+}
 ```
 
+`describe(Counter, fn)` auto-tags the suite path with `Counter.name`, so
+`tutuca <module> test Counter` picks it up. Untagged `test(...)` at the
+top of a tagged `describe` inherits the tag.
+
 ## Install skill assets
 
 `tutuca install-skill` copies bundled Claude Code skill files into
@@ -100,7 +171,7 @@ tutuca install-skill --all --force     # overwrite existing files
 
 ## Linter Rules
 
-Codes emitted by `lint`. Source: `tools/core/lint-check.js`.
+Codes emitted by `lint`.
 
 ### Field references
 

package/skill/tutuca/core.md

@@ -15,8 +15,8 @@ the `tutuca` CLI.
 
 ## Verifying changes
 
-After editing a Tutuca module, run two checks before declaring the edit
-done:
+After editing a Tutuca module, run these checks before declaring the
+edit done:
 
 1. **Lint the module** — catches undefined fields/handlers/macros/events
    (all the `*_NOT_DEFINED` / `*_NOT_REFERENCED` codes):
@@ -26,7 +26,21 @@ done:
    Exits `2` on any error-level finding. Pass a component name to scope
    it: `tutuca <module-path> lint Button`.
 
-2. **Render the example(s) that exercise the feature you changed** —
+2. **Test component behavior** — when the edit changes attributes,
+   instance methods, input handlers, or static factories (anything
+   observable from JS, not just the rendered HTML), run the test
+   suite. The module opts in by exporting
+   `getTests({ describe, test, expect })`:
+
+        tutuca <module-path> test
+        tutuca <module-path> test Counter           # one component
+        tutuca <module-path> test --grep "inc()"    # one path
+
+   Exits `4` on any failure. Skip this step when the change is purely
+   templates/styling — `render` already covers that. Full reference,
+   including a worked `getTests()` export, in [cli.md](./cli.md).
+
+3. **Render the example(s) that exercise the feature you changed** —
    confirms the component actually mounts in a headless DOM with the new
    behavior. Pick the example whose `title` matches the feature, or
    filter by component:
@@ -775,9 +789,8 @@ import {
 ```
 
 Because every `immutable` export is reachable through `tutuca`, if an
-`immutable-js` skill is installed in this project (e.g.
-`.claude/skills/immutable-js/`) load it alongside this one — its guidance
-applies directly to the values you'll be reading and writing.
+`immutable-js` skill is available, load it alongside this one — its
+guidance applies directly to the values you'll be reading and writing.
 
 ## Conventional Module Exports
 

package/skill/SKILL.md

@@ -1,46 +0,0 @@
----
-name: tutuca
-description: Authoring or reviewing tutuca components, html`` views, macros, or running the `tutuca` CLI. Covers field types, @-directives, bubble/receive/response handlers, and the post-edit `tutuca <module> lint` + `tutuca <module> render --title …` verification recipe.
----
-
-# Tutuca
-
-Tutuca is an immutable-state SPA framework: components have typed
-`fields`, auto-generated mutators (`setX`, `pushInX`, …), HTML-template
-`view`s with `@`-prefixed directives, and `bubble` / `receive` /
-`response` handlers for orchestration.
-
-## Verifying changes
-
-After editing a tutuca module, run two checks before declaring the edit
-done:
-
-1. **Lint** — catches undefined fields/handlers/macros/events. Exits
-   `2` on any error-level finding.
-
-   ```sh
-   tutuca <module-path> lint
-   ```
-
-2. **Render the example that exercises the feature you changed** —
-   confirms the component mounts in a headless DOM with the new
-   behavior. Exits `3` on render crash.
-
-   ```sh
-   tutuca <module-path> render --title "<example title>"
-   ```
-
-   If no example covers the feature, add one to `getExamples()` first —
-   that's how the feature becomes verifiable.
-
-## Routing
-
-| Task                                                                                           | File                            |
-| ---------------------------------------------------------------------------------------------- | ------------------------------- |
-| Authoring `component({...})`, `html\`...\`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
-| CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.md)             |
-| Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
-
-Read `core.md` first. Reach for `cli.md` or `advanced.md` only when the
-task touches them — both files are referenced inline from `core.md` so
-you'll be pointed there when relevant.

package/skill/advanced.md

@@ -1,146 +0,0 @@
-# Tutuca — Advanced Topics
-
-Reach this file only when the task touches drag & drop, context-style
-"dynamic bindings", pseudo-`x` (the `<x>`-stripping workaround inside
-`<select>`/`<table>`/`<tr>`), registering a custom seq type, or
-compiling Tailwind / MargaUI classes. For everything else, `core.md`
-is the right place.
-
-## Drag and Drop
-
-```html
-<div
-  @each=".items"
-  draggable="true"
-  data-dragtype="my-item"
-  data-droptarget="my-item"
-  @on.drop="onDrop @key dragInfo event"
-></div>
-```
-
-```js
-input: {
-  onDrop(targetKey, dragInfo, e) {
-    const sourceKey = dragInfo.lookupBind("key");   // any bind from source render
-    return this.setItems(this.items.moveKeyBeforeKey(sourceKey, targetKey));
-  },
-}
-```
-
-Tutuca auto-manages two attrs during a drag — style them with CSS:
-
-```css
-[data-dragging="1"] {
-  opacity: 0.5;
-}
-[data-draggingover="my-item"] {
-  outline: 1px dashed;
-}
-```
-
-Touch is wired up too (drag fires after a small move threshold).
-
-## Dynamic Bindings
-
-For passing values "context-style" through nested components without prop
-drilling. Define on the producer; alias on consumers; resolve as `*name`.
-
-```js
-const Theme = component({
-  name: "Theme",
-  fields: { color: "blue" },
-  dynamic: { color: ".color" },
-  on: {
-    stackEnter() {
-      return ["color"];
-    },
-  },
-});
-const Child = component({
-  dynamic: { color: { for: "Theme.color", default: "'gray'" } },
-  view: html`<p :style="color: {*color}"></p>`,
-});
-```
-
-`on.stackEnter()` is required only on the **producer** (the component
-declaring `dynamic: { name: ".field" }` to expose a value). It returns
-the list of dynamic-binding names this component pushes onto the stack
-when entering its render. Consumers (which only alias via
-`{ for: "Producer.name", default: ... }`) don't need it.
-
-## Pseudo-`x` (`@x`)
-
-Tutuca's special operations (`render`, `render-it`, `render-each`, `text`,
-`show`, `hide`, `slot`) live on the `<x>` tag. That works almost
-everywhere, but the browser's HTML parser refuses to keep `<x>` (or any
-unknown tag) as a child of certain elements: `<select>` only allows
-`<option>` / `<optgroup>`, `<table>` only allows `<thead>` / `<tbody>` /
-`<tr>`, `<tr>` only allows `<th>` / `<td>`, etc. Drop `<x render-each>`
-inside one of those and the parser silently strips it.
-
-The escape hatch: prefix the **first** attribute on a *legal* tag with
-`@x`. Tutuca treats that tag as if it were `<x>` and reads the next
-attribute as the special op.
-
-```html
-<!-- ❌ <x> stripped by the HTML parser inside <select> -->
-<select>
-  <x render-each=".items" as="option"></x>
-</select>
-
-<!-- ✅ pseudo-x: <option @x render-each=".items" as="option"> -->
-<select>
-  <option @x render-each=".items" as="option"></option>
-</select>
-```
-
-Notes:
-
-- `@x` must be the **first** attribute; the special op (`render-each`,
-  `render`, `text`, `show`, ...) is the second.
-- The host tag (here `<option>`) is otherwise ignored — only the special
-  op runs. Tutuca produces the rendered children directly.
-- Same trick works inside `<tr>`, `<table>`, `<colgroup>`, `<dl>`,
-  `<details>`, or anywhere else the parser would discard `<x>`.
-
-## Registering a custom seq type
-
-To make `@each` recognize your own collection class, install a
-`SEQ_INFO` walker on its prototype:
-
-```js
-import { SEQ_INFO } from "tutuca";
-
-class MyClass {
-  // ...
-}
-MyClass.prototype[SEQ_INFO] = (seq, visit) => {
-  for (const [k, v] of seq.entries()) visit(k, v, "data-sk");
-};
-```
-
-`SEQ_INFO` is `Symbol.for("tutuca.seqInfo")`, so the same identity
-is shared across module graphs (source vs. bundled tutuca). The
-renderer reads `seq[SEQ_INFO]` directly (no `.constructor` lookup),
-which is why the walker goes on the prototype, not as a static.
-
-The third arg to `visit` is the data attribute used for stable-key
-diffing (typically `"data-sk"` for "sequence key").
-
-## Tailwind / MargaUI Class Compilation (extra build)
-
-```js
-import { compileClassesToStyleText, injectCss, tutuca } from "tutuca/extra";
-import { compile } from "https://esm.sh/margaui";
-
-const app = tutuca("#app");
-app.registerComponents([Comp]);
-const css = await compileClassesToStyleText(app, compile);
-injectCss("myapp", css);
-app.start();
-```
-
-`compileClassesToStyleText` walks every registered component's templates,
-collects the `class=` and `:class=` literals, hands them to a `compile`
-function (any margaui-compatible signature), and returns CSS text. Pair
-with `injectCss(scopeName, css)` to install the result before `start()`.

package/skill/cli.md

@@ -1,117 +0,0 @@
-# Tutuca CLI Reference
-
-The `tutuca` CLI inspects, documents, lints, and renders any module that
-follows the *Conventional Module Exports* shape (see `core.md`). Reach
-this file when you need command/flag/exit-code details, or when reading
-a lint code out of `lint` output. Otherwise the post-edit recipe in
-`core.md` (run `lint`, then `render --title "<your example>"`) is
-enough.
-
-## Install / invoke
-
-```sh
-# project local
-npm i --save-dev tutuca
-npx tutuca <module-path> <command> [name] [flags]
-
-# global
-npm i -g tutuca
-tutuca <module-path> <command> [name] [flags]
-
-# from a checkout of this repo
-bun tools/tutuca.js <module-path> <command> [name] [flags]
-```
-
-The module path comes **first**, the command second, an optional component
-name third. `tutuca help` prints the full reference; `tutuca help <command>`
-prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
-
-## Commands
-
-| Command         | Purpose                                                                                                                |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `info`          | Summarize which `getX()` exports are present and counts                                                                |
-| `list`          | List components with their views and fields (name + type)                                                              |
-| `examples`      | Print `getExamples()` content (title, items, per section)                                                              |
-| `docs [name]`   | Generate API docs (methods, input handlers, fields with auto-generated accessors) — all or one                         |
-| `lint [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
-| `render [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
-| `help [cmd]`    | Show usage; the only command that does **not** need a module path                                                      |
-
-## Global flags
-
-```
--f, --format <cli|md|json|html>  output format
-                                 defaults: info/list/examples/lint → cli
-                                           docs/render             → md
-                                 html only valid for render
-                                 json works for every command
--o, --output <file>              write to file instead of stdout
-    --pretty                     pretty-print HTML (md/html) via prettier;
-                                 JSON formatter uses indent 2
-    --module <path>              alternative to first-positional module path
--h, --help                       show help (overview, or for one command)
-```
-
-## Exit codes
-
-| Code | Meaning                                                  |
-| ---- | -------------------------------------------------------- |
-| `0`  | success                                                  |
-| `1`  | usage error (bad args, missing module, bad module shape) |
-| `2`  | lint findings at error level                             |
-| `3`  | render crash                                             |
-
-## Examples
-
-```sh
-tutuca ./src/components.js info                       # quick overview
-tutuca ./src/components.js list                       # components, views, fields
-tutuca ./src/components.js docs Button -f json        # one component, JSON
-tutuca ./src/components.js render -f html --pretty -o out/examples.html
-tutuca ./src/components.js render Button --title "Disabled state"
-
-# Post-edit verification: lint, then render the example for the feature
-# you just changed (add the example first if none covers it). Add
-# --pretty when you need to read the HTML to verify structure.
-tutuca ./src/components.js lint
-tutuca ./src/components.js render --title "Disabled state"
-tutuca ./src/components.js render --title "Disabled state" --pretty
-```
-
-## Linter Rules
-
-Codes emitted by `lint`. Source: `tools/core/lint-check.js`.
-
-### Field references
-
-- `FIELD_VAL_NOT_DEFINED` — `.field` not declared in `fields`.
-
-### Input-handler / method confusion
-
-- `INPUT_HANDLER_NOT_IMPLEMENTED` — bare handler name not in `input`.
-- `INPUT_HANDLER_NOT_REFERENCED` — `input` entry never used.
-- `INPUT_HANDLER_METHOD_NOT_IMPLEMENTED` — `.handler` not in `methods`.
-- `INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD` — bare name resolves to `methods` (use `.name`).
-- `INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER` — `.name` resolves to `input` (drop the dot).
-
-### Iteration helpers (`alter`)
-
-- `ALT_HANDLER_NOT_DEFINED` — `@when` / `@enrich-with` / `@loop-with` name not in `alter`.
-- `ALT_HANDLER_NOT_REFERENCED` — `alter` entry never used.
-
-### Templates / events
-
-- `RENDER_IT_OUTSIDE_OF_LOOP` — `<x render-it>` outside `@each` / `render-each`.
-- `UNKNOWN_EVENT_MODIFIER` — `+mod` not in the recognized modifier set.
-- `UNKNOWN_HANDLER_ARG_NAME` — handler arg name not a built-in / declared component.
-- `DUPLICATE_ATTR_DEFINITION` — same attr set by literal + `:attr` + `@if.attr` on one element.
-- `UNKNOWN_DIRECTIVE` — `@name` directive not recognized (typo or unsupported).
-- `UNKNOWN_X_OP` — first attribute on `<x>` (or pseudo-`@x`) is not a known op.
-- `UNKNOWN_X_ATTR` — extra attribute on `<x op>` not consumed by the op and not a known wrapper (`show`/`hide`).
-
-### Names registered with the app
-
-- `UNKNOWN_REQUEST_NAME` — `!name` not registered.
-- `UNKNOWN_COMPONENT_NAME` — component type not registered.
-- `UNKNOWN_MACRO_ARG` — macro attr not declared in defaults.