tutuca 0.9.98 → 0.9.99

package/dist/tutuca-storybook.js

@@ -1,5 +1,48 @@
-// src/storybook.js
+// src/storybook/index.js
 import { component, dispatchPhase, html, injectCss, phaseHasBubble, tutuca } from "tutuca";
+import { getComponents as getInspectorComponents } from "tutuca/components";
+
+// src/storybook/inspect.js
+import { buildInspectorViews, isComponentInstance } from "tutuca/components";
+function buildTestIndex(modules) {
+  const index = new Map;
+  for (const m of modules) {
+    if (typeof m.getTests !== "function")
+      continue;
+    const components = m.getComponents?.() ?? [];
+    for (const c of components) {
+      if (!index.has(c.name))
+        index.set(c.name, { getTests: m.getTests, components });
+    }
+  }
+  return index;
+}
+async function buildExampleInspectors(example, scope, testIndex, dev) {
+  const value = example.value;
+  const comp = isComponentInstance(value) ? scope.getCompFor(value) : null;
+  const entry = comp ? testIndex.get(comp.name) : null;
+  const views = await buildInspectorViews(value, scope, {
+    getTests: entry?.getTests ?? null,
+    components: entry?.components ?? [],
+    dev
+  });
+  return example.setInstanceView(views.instanceView).setComponentView(views.componentView).setLintView(views.lintView).setTestView(views.testView).setHasInspect(views.hasInspect).setHasComponent(views.hasComponent).setHasLint(views.hasLint).setHasTest(views.hasTest);
+}
+async function attachInspectorViews(root, scope, modules, dev = null) {
+  const testIndex = buildTestIndex(modules);
+  let sections = root.sections;
+  for (let si = 0;si < sections.size; si++) {
+    const section = sections.get(si);
+    let items = section.items;
+    for (let ii = 0;ii < items.size; ii++) {
+      items = items.set(ii, await buildExampleInspectors(items.get(ii), scope, testIndex, dev));
+    }
+    sections = sections.set(si, section.setItems(items));
+  }
+  return root.setSections(sections);
+}
+
+// src/storybook/index.js
 var Storybook = component({
   name: "Storybook",
   fields: {
@@ -247,7 +290,16 @@ var Example = component({
     value: null,
     view: "main",
     requestHandlers: null,
-    on: null
+    on: null,
+    activeTab: "preview",
+    hasInspect: false,
+    hasComponent: false,
+    hasLint: false,
+    hasTest: false,
+    componentView: null,
+    instanceView: null,
+    lintView: null,
+    testView: null
   },
   requestOverridesField: "requestHandlers",
   statics: {
@@ -317,8 +369,72 @@ var Example = component({
         </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 role="tablist" class="tabs tabs-border" @show=".hasInspect">
+        <a
+          role="tab"
+          @if.class="equals? .activeTab 'preview'"
+          @then="'tab tab-active'"
+          @else="'tab'"
+          @on.click="$setActiveTab 'preview'"
+        >
+          Preview
+        </a>
+        <a
+          role="tab"
+          @show=".hasComponent"
+          @if.class="equals? .activeTab 'component'"
+          @then="'tab tab-active'"
+          @else="'tab'"
+          @on.click="$setActiveTab 'component'"
+        >
+          Component
+        </a>
+        <a
+          role="tab"
+          @if.class="equals? .activeTab 'instance'"
+          @then="'tab tab-active'"
+          @else="'tab'"
+          @on.click="$setActiveTab 'instance'"
+        >
+          Instance
+        </a>
+        <a
+          role="tab"
+          @show=".hasLint"
+          @if.class="equals? .activeTab 'lint'"
+          @then="'tab tab-active'"
+          @else="'tab'"
+          @on.click="$setActiveTab 'lint'"
+        >
+          Lint
+        </a>
+        <a
+          role="tab"
+          @show=".hasTest"
+          @if.class="equals? .activeTab 'test'"
+          @then="'tab tab-active'"
+          @else="'tab'"
+          @on.click="$setActiveTab 'test'"
+        >
+          Test
+        </a>
+      </div>
+      <div @show="equals? .activeTab 'preview'">
+        <div class="bg-base-100 p-3" @push-view=".view">
+          <x render=".value"></x>
+        </div>
+      </div>
+      <div class="p-3" @show="equals? .activeTab 'component'">
+        <x render=".componentView"></x>
+      </div>
+      <div class="p-3" @show="equals? .activeTab 'instance'">
+        <x render=".instanceView"></x>
+      </div>
+      <div class="p-3" @show="equals? .activeTab 'lint'">
+        <x render=".lintView"></x>
+      </div>
+      <div class="p-3" @show="equals? .activeTab 'test'">
+        <x render=".testView"></x>
       </div>
     </div>
   </div>`
@@ -360,7 +476,7 @@ function buildStorybook(modules) {
     return Array.isArray(raw) ? raw : [raw];
   });
   const sections = rawSections.map((s) => Section.Class.fromData(s)).sort((a, b) => a.title.localeCompare(b.title));
-  const components = new Set([Storybook, Section, Example]);
+  const components = new Set([Storybook, Section, Example, ...getInspectorComponents()]);
   const macros = {};
   const requestHandlers = {};
   const overrideNames = new Set;
@@ -413,7 +529,7 @@ function buildExampleRequestHandlers({ requestHandlers: reals, overrideNames })
     handlers[name] = makeMeta(name);
   return handlers;
 }
-async function mountStorybook(selector, modules, { compileCss, root, persistUrl = true } = {}) {
+async function mountStorybook(selector, modules, { compileCss, root, persistUrl = true, dev = null } = {}) {
   const app = tutuca(selector);
   const built = buildStorybook(modules);
   app.state.set(root ?? built.root);
@@ -424,6 +540,9 @@ async function mountStorybook(selector, modules, { compileCss, root, persistUrl
   if (persistUrl) {
     scope.registerRequestHandlers({ persistState });
   }
+  if (dev && app.state.val?.sections) {
+    app.state.set(await attachInspectorViews(app.state.val, scope, modules, dev));
+  }
   if (compileCss) {
     injectCss("tutuca-storybook", await compileCss(app));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.98",
+  "version": "0.9.99",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -14,6 +14,7 @@
     "./extra-ext": "./dist/tutuca-extra.ext.js",
     "./dev-ext": "./dist/tutuca-dev.ext.js",
     "./storybook": "./dist/tutuca-storybook.js",
+    "./components": "./dist/tutuca-components.js",
     "./immutable": "./dist/immutable.js",
     "./chai": "./dist/chai.js",
     "./package.json": "./package.json"
@@ -59,6 +60,7 @@
     "dist/tutuca-extra.ext.js",
     "dist/tutuca-dev.ext.js",
     "dist/tutuca-storybook.js",
+    "dist/tutuca-components.js",
     "dist/immutable.js",
     "dist/chai.js",
     "skill"

package/skill/tutuca/cli.md

@@ -151,77 +151,19 @@ Filters:
 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).toBeInstanceOf(Counter.Class);
-        expect(next.count).toBe(1);
-      });
-      test("does not mutate the original instance", () => {
-        const c = Counter.make({ count: 7 });
-        c.inc();
-        expect(c.count).toBe(7);                    // immutability
-      });
-    });
-
-    describe("dec()", () => {                           // input handler
-      test("returns a Counter with count - 1", () => {
-        const next = Counter.input.dec.call(Counter.make());
-        expect(next.count).toBe(-1);
-      });
-    });
-
-    test("inc and dec round-trip", () => {              // untagged path
-      expect(Counter.input.dec.call(Counter.make().inc()).count).toBe(0);
-    });
-  });
-}
-```
-
-`describe(Counter, fn)` auto-tags the suite path with `Counter.name`, so
-`tutuca test <module> Counter` picks it up. Untagged `test(...)` at the
-top of a tagged `describe` inherits the tag.
+The `getTests` shape and the handler calling conventions (`Comp.method()`,
+`Comp.input.x.call(inst, …)`, the `drive` cascade helper, iteration
+handlers) are in [testing.md](./testing.md).
 
 ## 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 --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)
-```
-
-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).
-
-### Authoring `.dev.js` story modules
-
-The `*.dev.js` convention (a dev-only module holding `getComponents()` +
-`getExamples()` + `getTests()`, never shipped), the example/section shape, and
-per-example request mocking are covered in [storybook.md](./storybook.md).
+`tutuca storybook [dir]` serves a browser storybook with no setup — it
+discovers co-located `*.dev.js` modules, runs their `getTests()`, wires
+margaui, and serves an ephemeral page. Its flags (`--port`, `--out`,
+`--dry-run`, `--no-margaui`, `--no-check`, `--no-tests`) are in the
+Commands table above. Authoring `.dev.js` modules, the example/section shape,
+per-example request mocking, and runtime resolution are all in
+[storybook.md](./storybook.md).
 
 ## Install skill assets
 

package/skill/tutuca/core.md

@@ -657,12 +657,11 @@ inbound sources (WebSocket, `postMessage`, timers) have no element to bind
 — route those through `app.sendAtRoot` instead (see
 [request-response.md](./request-response.md)).
 
-Pitfall: binding camelCase JS properties on a custom element silently
-fails. `:mapId=".id"` does *not* invoke a `set mapId` setter
-— the HTML parser lowercased the attribute name, so the framework assigns
-to `node.mapid` instead, creating an own property and bypassing the
-setter. Use kebab-case attributes / lowercased setters when authoring
-custom elements for use with Tutuca. See *Attribute Binding* above.
+Pitfall: binding a camelCase JS property on a custom element silently
+fails — `:mapId=".id"` assigns to `node.mapid`, never invoking
+`set mapId`. Author custom elements with kebab-case attributes /
+lowercased setters and bind via `:kebab-name`. See *Attribute Binding*
+above for the full explanation.
 
 ## Conditional Display
 
@@ -931,66 +930,29 @@ CSS via the extra build), see [margaui.md](./margaui.md).
 
 ## Triggers and Handlers
 
-Tutuca has four orchestration channels. Each one pairs a trigger with
-a same-shape handler block:
+Tutuca has four orchestration channels. Each pairs a trigger with a
+same-shape handler block:
 
-| Triggered by                                | Handler block       |
-| ------------------------------------------- | ------------------- |
-| DOM event (`click`, `input`, …)             | `input:    { ... }` |
-| `ctx.send(name)` — message to a target path | `receive:  { ... }` |
-| `ctx.request(name)` — async request         | `response: { ... }` |
-| `ctx.bubble(name)` — event up the tree      | `bubble:   { ... }` |
+| Triggered by                                | Handler block       | Use for                                             |
+| ------------------------------------------- | ------------------- | --------------------------------------------------- |
+| DOM event (`click`, `input`, …)             | `input:    { ... }` | the component handling its own events               |
+| `ctx.bubble(name)` — event up the tree      | `bubble:   { ... }` | aggregate state an ancestor owns (logs, selections) |
+| `ctx.send(name)` — message to a target path | `receive:  { ... }` | addressing one known component (or self)            |
+| `ctx.request(name)` — async request         | `response: { ... }` | fetch / timer / IndexedDB, result routed back       |
 
 Every handler is called as `handler(...args, ctx)` and returns a
-(possibly updated) instance of `this`; the framework swaps the
-returned value into the dispatch path. The three event-driven channels
-beyond `input` — `bubble`, `send`/`receive`, async `request`/`response`
-— plus the shared `$unknown` fallback and request-handler registration
-are documented in [request-response.md](./request-response.md); the
-brief anchors below cover the essentials.
+(possibly updated) instance of `this`, which the framework swaps into
+the dispatch path; `ctx` is always the trailing argument. The three
+channels beyond `input` — plus `ctx.at`, the `$unknown` fallback,
+per-call handler-name overrides, error handling, and request-handler
+registration — are in [request-response.md](./request-response.md);
+worked snippets in
+[patterns/coordinate-components.md](./patterns/coordinate-components.md).
 
 `alter` is a fifth handler block, but unlike the four above it isn't
 event-triggered — the renderer invokes alter handlers to produce
 binds, not to update state. See *Mental model* and *Scope Enrichment*.
 
-## Orchestration channels (bubble / send-receive / request-response)
-
-Beyond local `input` handlers, three channels move state between
-components. Full mechanics — when-to-use guidance, the `ctx.at`
-`PathBuilder`, error handling, per-call handler-name overrides, the
-`$unknown` fallback, and request-handler registration — are in
-[request-response.md](./request-response.md). The essentials:
-
-- **`bubble`** — `ctx.bubble("name", args)` walks the dispatch path
-  toward the root; each ancestor with `bubble.<name>(...args, ctx)`
-  runs (after descendants transact); `ctx.stopPropagation()` halts it.
-  Use for aggregate state owned by an ancestor (logs, selections).
-
-  ```js
-  input:  { onClick(ctx) { ctx.bubble("itemSelected", [this]); return this; } },
-  bubble: { itemSelected(item, ctx) { return this.insertInLogAt(0, item.label); } },
-  ```
-
-- **`send` / `receive`** — `ctx.send("name", args)` delivers a message
-  to one target (self by default, or `ctx.at.field("x").send(...)` /
-  `.index(name, i)` / `.key(name, k)` for another); the target's
-  `receive.<name>(...args, ctx)` runs. `receive.init` is a convention,
-  not a lifecycle hook — dispatch it via `app.sendAtRoot("init")`.
-
-- **`request` / `response`** — `ctx.request("name", args)` runs a
-  host-registered async handler (registered with
-  `scope.registerRequestHandlers({...})`) and routes the result to
-  `response.<name>(res, err, ctx)` — `res` set on success, `err` on
-  failure. Use for fetch / timer / IndexedDB work.
-
-  ```js
-  receive:  { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } },
-  response: { loadData(res, err, ctx) { return this.setIsLoading(false).setItems(res); } },
-  ```
-
-`ctx` is always the last argument of every `bubble` / `receive` /
-`response` handler.
-
 ## Macros
 
 Pure template expansion — no state, no methods. Calls inside a macro
@@ -1115,22 +1077,11 @@ export function getTests({ describe, test, expect }) { /*...*/ }      // optiona
 ```
 
 An example item may carry an optional **`requestHandlers`** map — per-example
-mocks for the request handlers its component triggers, used by the storybook
-only. Each is a plain async function keyed by request name; it overrides the
-module's real `getRequestHandlers()` handler **for that example instance only**,
-so two examples of the same component can show different responses side by side.
-Return a fixture, `throw` to exercise the error path, or never resolve to hold a
-loading state:
-
-```js
-items: [
-  { title: "Loaded", value: Widget.make(),
-    requestHandlers: { async load() { return [{ id: 1, name: "Ada" }]; } } },
-  { title: "Error", value: Widget.make(),
-    requestHandlers: { async load() { throw new Error("boom"); } } },
-  { title: "Default", value: Widget.make() },   // no mock → real handler / 404
-]
-```
+mocks (keyed by request name) that override the module's real
+`getRequestHandlers()` for that one instance, so two examples of the same
+component show different responses side by side. Return a fixture, `throw` for
+the error path, or never resolve to hold a loading state. Full treatment, plus
+the `on` lifecycle hooks, in [storybook.md](./storybook.md).
 
 Best practice: have `getComponents()` return **every** component the module
 defines — child and helper components included — and give each one at least

package/skill/tutuca/semantics.md

@@ -83,9 +83,10 @@ return curLeaf !== newLeaf ? txnPath.setValue(curRoot, newLeaf) : curRoot;
 ```
 
 The root swap is atomic and identity-cheap: unchanged subtrees keep their
-references, so re-render is incremental. Cross-transaction ordering and
-fan-out completion are tracked by `Task` (a transaction's `task` resolves
-once its dependency tasks do).
+references, so re-render is incremental. Per-dispatch completion is tracked
+by `Completion` (counter-based): `whenSettled()` resolves once a
+transaction's own work finishes, `whenSubtreeSettled()` once the subtree it
+spawned (requests, follow-on sends) settles too.
 
 ## Dispatch channels, semantically
 

package/skill/tutuca/testing.md

@@ -269,12 +269,9 @@ The "bad" forms force every test to construct
 `{ target: { value: "42" } }` (or a fuller stub when more fields are
 read), which is brittle and obscures intent.
 
-Built-in named args (full list in [core.md](./core.md) *Event
-Handling*): `value`, `valueAsInt`, `valueAsFloat`, `target`, `event`,
-`isAlt`, `isShift`, `isCtrl` / `isCmd`, `key`, `keyCode`, `isUpKey`,
-`isDownKey`, `isSend`, `isCancel`, `isTabKey`, `ctx`, `dragInfo`.
-`ctx` is auto-appended last. Reach for `event` only when no narrower
-arg fits.
+The built-in named args are listed in [core.md](./core.md) *Event
+Handling*; `ctx` is auto-appended last. Reach for `event` only when no
+narrower arg fits.
 
 ## Worked example