tutuca 0.9.89 → 0.9.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.89",
+  "version": "0.9.91",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",

package/skill/tutuca/SKILL.md

@@ -30,6 +30,7 @@ When authoring tutuca code, also load these if available:
 | Authoring `component({...})`, `html`...`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
 | Designing components — responsibilities, state ownership, channel choice, do's & don'ts | [component-design.md](./component-design.md) |
 | CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.md)             |
+| Authoring `*.dev.js` story modules, `getExamples()` sections, per-example request mocking, running `tutuca storybook` | [storybook.md](./storybook.md) |
 | `bubble` / `send`-`receive` / async `request`-`response` channels, `$unknown`, request-handler registration | [request-response.md](./request-response.md) |
 | Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
 | Runtime semantics — path steps, transaction lifecycle, dyn-var teleporting, async key pinning (`livePath`) | [semantics.md](./semantics.md) |

package/skill/tutuca/cli.md

@@ -217,33 +217,11 @@ 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
+### Authoring `.dev.js` story modules
 
-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));
-  });
-}
-```
+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).
 
 ## Install skill assets
 

package/skill/tutuca/core.md

@@ -1005,12 +1005,31 @@ export function getExamples()         {
   return {
     title: "...",
     description: "...",
-    items: [{ title, description, value, view }],         // value = Comp.make(...)
+    // value = Comp.make(...); requestHandlers (optional) mocks this example's requests
+    items: [{ title, description, value, view, requestHandlers }],
   };
 }
 export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
 ```
 
+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
+]
+```
+
 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

package/skill/tutuca/patterns/README.md

@@ -41,3 +41,7 @@ task.
 ## Component communication
 
 - [Coordinate components](coordinate-components.md) — `bubble`, `send`/`receive`, async `request`/`response`.
+
+## Stories & catalog
+
+- [Add a story for a component](add-a-story.md) — a `*.dev.js` with `getComponents()` + `getExamples()`, optional per-example request mocks.

package/skill/tutuca/patterns/add-a-story.md

@@ -0,0 +1,26 @@
+# Add a story for a component
+
+**Problem:** show a component (and its states) in the storybook.
+
+Create `foo.dev.js` next to `foo.js`:
+
+```js
+import { Foo } from "./foo.js";
+
+export function getComponents() {
+  return [Foo];
+}
+export function getExamples() {
+  return { title: "Foo", items: [
+    { title: "Empty", value: Foo.make({}) },
+    { title: "Loaded", value: Foo.make({ isLoading: true }),
+      requestHandlers: { async load() { return [{ id: 1 }]; } } },
+  ] };
+}
+```
+
+`value` must be a real `Foo.make(...)` instance, not a plain object. Add a
+`requestHandlers` map to an item to mock that example's requests
+(fixture / `throw` / never-resolve) — these are storybook-only. Run
+`tutuca storybook` to view, or `--dry-run --json` to smoke-test. See
+[storybook.md](../storybook.md).

package/skill/tutuca/request-response.md

@@ -274,7 +274,7 @@ You can also fire several in one handler
 ### The request-handler contract
 
 Registered request handlers run with **no `this`** (they're invoked as
-`fn.apply(null, args)`), so they can't read component state — pass
+`fn.apply(null, [...args, ctx])`), so they can't read component state — pass
 everything they need through `args`
 (`ctx.request("persistState", [{ key, value }])`). They're plain async
 functions or closures. Aggregate handlers from sub-modules with spread:
@@ -285,6 +285,15 @@ export function getRequestHandlers() {
 }
 ```
 
+The handler also receives a request context as its **final argument**
+(consistent with `receive`/`input`/`response`, where `ctx` is last) — usually
+ignored, but available when needed. Like every ctx it exposes
+`ctx.walkPath(callback)`, which walks the component instances on the issuing
+path **leaf→root**, calling `callback(Component, instance)` (return `false` to
+stop early). It captures the immutable dispatch root/path, so it may be called
+before or after an `await`. (The storybook uses this to let an example mock the
+request handlers its component triggers — per example, in isolation.)
+
 ### Chaining from a response handler
 
 A `response` handler gets the full `ctx`, so it can issue further

package/skill/tutuca/storybook.md

@@ -0,0 +1,151 @@
+# Storybook
+
+Reach this file when authoring `*.dev.js` story modules or running
+`tutuca storybook` — defining `getExamples()` sections, mocking requests per
+example, or rendering a live component catalog. For the framework primer see
+[core.md](./core.md); for the full CLI flag/exit-code table see
+[cli.md](./cli.md); for the `getTests` shape see [testing.md](./testing.md).
+
+## Mental model
+
+`tutuca storybook [dir]` recursively discovers co-located `*.dev.js` modules,
+mounts them via the shipped `tutuca/storybook` library, and serves an ephemeral
+page — no config, no HTML to write. 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 a `--no-*` flag. All tutuca specifiers resolve to **one
+runtime** — component scope and identity require it.
+
+## The `.dev.js` module
+
+A `*.dev.js` file is a **dev-only module**: it holds stories, tests, and
+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 it follows the full module convention, the
+same file is a valid target for `tutuca lint` / `test` / `render` too.
+
+| Export | Returns | Used for |
+| ------ | ------- | -------- |
+| `getComponents()` | `[Comp, ...]` | stories — return **every** component the module defines, children and helpers included |
+| `getExamples()` | one section, or an array of sections | the catalog cards |
+| `getTests({ describe, test, expect })` | tests | the pre-serve test run (optional) |
+| `getMacros()` | `{ name: macro }` | macros referenced in views (optional) |
+| `getRequestHandlers()` | `{ name: async fn }` | the module's **real** request handlers (optional) |
+| `getRoot()` | `Root.make({...})` | root state when examples need it (optional) |
+
+## Authoring stories (`getExamples`)
+
+Return one section, or an array of sections to group examples under multiple
+headings. A section is `{ title, description?, items: [...] }`:
+
+```js
+import { component, html } from "tutuca";
+import { Counter } from "./counter.js";
+
+export function getComponents() {
+  return [Counter];
+}
+export function getExamples() {
+  return {                                    // one section, or an array of these
+    title: "Counter",
+    description: "A button that counts clicks.", // optional
+    items: [
+      { title: "Basic", description: "starts at zero", value: Counter.make({ count: 0 }) },
+      { title: "Pre-filled", value: Counter.make({ count: 5 }) },
+    ],
+  };
+}
+```
+
+Item fields:
+
+- `title` — required.
+- `description?` — shown under the card title.
+- `value` — required, the instance to render, usually `Comp.make({...})`.
+- `view?` — selects a pushed named view, rendered via `@push-view` in the card.
+- `requestHandlers?` — per-example request mocks (next section).
+
+The storybook sorts sections by title and renders a sidebar with a filter, so
+one example item per meaningful state reads as a state matrix.
+
+## Mocking requests per example
+
+An item's optional `requestHandlers` map holds async functions keyed by request
+name that override the module's real `getRequestHandlers()` handler **for that
+one example instance only** — so two examples of the same component show
+different responses side by side. The three idioms:
+
+```js
+items: [
+  { title: "Loaded", value: Widget.make({ isLoading: true }),
+    requestHandlers: { async load() { return [{ id: 1, name: "Ada" }]; } } },   // fixture
+  { title: "Error", value: Widget.make({ isLoading: true }),
+    requestHandlers: { async load() { throw new Error("boom"); } } },           // error path
+  { title: "Loading", value: Widget.make({ isLoading: true }),
+    requestHandlers: { load() { return new Promise(() => {}); } } },            // never resolves
+  { title: "Default", value: Widget.make() },         // no mock → real handler / "Request not found"
+]
+```
+
+How it resolves: the storybook registers one meta-handler per request name. On
+dispatch it walks the issuing component's path leaf→root to find the nearest
+example carrying a mock for that name (**nearest example wins**), else falls
+back to the module's real handler, else surfaces `Request not found: <name>`.
+This is **storybook-only** — at runtime your real `getRequestHandlers()` apply.
+See [request-response.md](./request-response.md) for the handler contract (the
+`ctx` is the handler's final argument). `tutuca storybook --dry-run --json`
+lists each example's mocked names.
+
+## Stories as tests (`getTests`)
+
+`getTests` runs through the same machinery as `tutuca test`; the storybook runs
+it in the terminal before serving (skip with `--no-tests`). `describe(Comp, fn)`
+auto-tags the suite by `Comp.name`:
+
+```js
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    test("starts at zero", () => expect(Counter.make({}).count).toBe(0));
+  });
+}
+```
+
+See [testing.md](./testing.md) for the full `getTests` shape and how to call
+methods / input / receive / bubble / response / alter handlers.
+
+## Running it
+
+```sh
+tutuca storybook                  # scan + serve the current directory
+tutuca storybook ./packages/ui    # scan + serve another directory
+tutuca storybook --dry-run        # prep + print what would be shown, don't serve (smoke test)
+tutuca storybook --dry-run --json # same, machine-readable for agents
+tutuca storybook --out ./_site    # write a static index.html + bootstrap instead of serving
+tutuca storybook --no-tests       # skip the pre-serve getTests() run
+```
+
+Runtime resolution (convention over configuration): a local
+`node_modules/tutuca` install if present, else the CLI's own `dist`, else the
+version-pinned CDN. `--out` always pins the CDN so the artifact is portable —
+host it from the project root so `/*.dev.js` paths resolve. See [cli.md](./cli.md)
+for the exhaustive flag list and exit codes.
+
+## Footguns
+
+- ⚠️ `value` must be a real instance (`Comp.make(...)`), not a plain object or
+  the class itself — examples need an addressable instance for event dispatch.
+- ⚠️ `requestHandlers` mocks are **storybook-only** and per-instance; don't rely
+  on them in `getTests` or production code.
+- ⚠️ Never import a `.dev.js` from app/production code — the suffix is the
+  ship / no-ship boundary.
+- ⚠️ An example whose component triggers a request with no real handler and no
+  per-example mock surfaces `Request not found: <name>`.
+- ⚠️ Keep one tutuca runtime — mixed specifiers or installs break scope identity.
+
+## Verify
+
+After editing a `*.dev.js`: `tutuca lint <module>.dev.js` →
+`tutuca test <module>.dev.js` → `tutuca storybook --dry-run --json <dir>`
+(smoke-test discovery, counts, and mocked names without serving), then
+`tutuca storybook <dir>` to view it live.

package/skill/tutuca-source/tutuca.ext.js

@@ -250,6 +250,17 @@ class Path {
     }
     return curVal;
   }
+  resolveChain(root) {
+    const out = [root];
+    let curVal = root;
+    for (const step of this.steps) {
+      curVal = step.lookup(curVal, NONE);
+      if (curVal === NONE)
+        break;
+      out.push(curVal);
+    }
+    return out;
+  }
   setValue(root, v) {
     const intermediates = new Array(this.steps.length);
     let curVal = root;
@@ -2926,6 +2937,7 @@ class Transactor {
     const txnPath = path.toTransactionPath();
     const curLeaf = txnPath.lookup(curRoot);
     const handler = this.comps.getRequestFor(curLeaf, name) ?? mkReq404(name);
+    const reqCtx = new RequestContext(path, this, parent, curRoot);
     const resHandlerName = opts?.onResName ?? name;
     const resPath = opts?.livePath ? null : txnPath.pinKeys(curRoot);
     const push = (specificName, baseName, singleArg, result, error) => {
@@ -2934,7 +2946,7 @@ class Transactor {
       this.pushTransaction(t);
     };
     try {
-      const result = await handler.fn.apply(null, args);
+      const result = await handler.fn.apply(null, [...args, reqCtx]);
       push(opts?.onOkName, resHandlerName, result, result, null);
     } catch (error) {
       push(opts?.onErrorName, resHandlerName, error, null, error);
@@ -3177,10 +3189,20 @@ class Task {
 }
 
 class Dispatcher {
-  constructor(path, transactor, parentTransaction) {
+  constructor(path, transactor, parentTransaction, root = transactor.state.val) {
     this.path = path;
     this.transactor = transactor;
     this.parent = parentTransaction;
+    this.root = root;
+  }
+  walkPath(callback) {
+    const comps = this.transactor.comps;
+    const chain = this.path.toTransactionPath().resolveChain(this.root);
+    for (let i = chain.length - 1;i >= 0; i--) {
+      const comp = comps.getCompFor(chain[i]);
+      if (comp && callback(comp, chain[i]) === false)
+        return;
+    }
   }
   get at() {
     return new PathChanges(this);
@@ -3217,6 +3239,9 @@ class EventContext extends Dispatcher {
   }
 }
 
+class RequestContext extends Dispatcher {
+}
+
 class PathChanges extends PathBuilder {
   constructor(dispatcher) {
     super();