tutuca 0.9.97 → 0.9.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.97",
+  "version": "0.9.98",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -99,9 +99,9 @@
   },
   "homepage": "https://github.com/marianoguerra/tutuca#readme",
   "devDependencies": {
-    "@biomejs/biome": "^2.4.12",
+    "@biomejs/biome": "^2.5.1",
     "chai": "^6.2.2",
-    "fast-check": "^4.7.0",
+    "fast-check": "^4.8.0",
     "htmlparser2": "^12.0.0"
   }
 }

package/skill/tutuca/advanced.md

@@ -124,11 +124,20 @@ in the producer's own view update in lock-step.
 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>`
+unknown tag) as a child of certain elements. Drop `<x render-each>`
 inside one of those and the parser silently strips it.
 
+The parser strips `<x>` only inside the **table family** and **`<select>`**.
+Use pseudo-`@x` when the parent is one of:
+
+`table`, `thead`, `tbody`, `tfoot`, `tr`, `colgroup`, `select`, `optgroup`.
+
+Everywhere else `<x>` is kept and needs no workaround — including `ul`, `ol`,
+`li`, `dl`, `dt`, `dd`, `details`, `summary`, `caption`, `td`, `th`. So
+`<ul><x render-each=".items">…</x></ul>` is fine. (When in doubt, the rule of
+thumb is: any element whose HTML content model only permits *specific* child
+tags — table sections and `<select>` — strips `<x>`.)
+
 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.
@@ -151,8 +160,8 @@ Notes:
   `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>`.
+- Same trick works inside any of the stripping parents listed above
+  (`<table>`/`<tr>`/`<colgroup>`/`<select>`/…).
 
 ## Registering a custom seq type
 

package/skill/tutuca/core.md

@@ -248,8 +248,9 @@ The one exception is **boolean predicates** in conditional slots
 a value, written predicate-first like a handler call —
 `empty?`, `truthy?`, `falsy?`, `null?`, `equals?`. E.g.
 `@hide="empty? .items"`, `@show="truthy? .query"`. A conditional slot
-still accepts a plain field (`@show=".isOpen"`) or no-arg method
-(`@show="$canSubmit"`) name too.
+otherwise accepts the same value forms as `@text` — a plain field
+(`@show=".isOpen"`), a no-arg method (`@show="$canSubmit"`), or a loop/scope
+`@binding` (`@show="@isSelected"`, `@hide="@hasDesc"`) — read as a boolean.
 
 `equals?` takes two args and is the idiomatic way to show/hide by name,
 e.g. `@show="equals? .view 'detail'"`. Predicate args (and handler
@@ -517,13 +518,21 @@ other inline content, or a loop binding). Both take the same value forms
 ```html
 <input :value=".str" @on.input="$setStr value" />
 <a :href=".url" :title="$'Hi {.name}'">link</a>       <!-- string template -->
-<button class="btn" :class="$'btn {.color}'">x</button>
+<button :class="$'btn {.color}'">x</button>
 ```
 
 Plain attrs are static. `:attr="..."` is a dynamic expression. Boolean
 HTML attributes (`disabled`, `checked`, `hidden`, …) are auto-recognized;
 pass a boolean field.
 
+A static `class="…"` and a dynamic `:class`/`@if.class` **cannot coexist on the
+same element** — setting one attribute two ways is a lint error
+(`DUPLICATE_ATTR_DEFINITION`), and at runtime the dynamic value wins and the
+static class is dropped. Fold any structural classes into the bound expression,
+e.g. `:class="$'btn {.color}'"` (note `btn` is part of the template, not a
+separate `class="btn"`). The same applies to other attributes — see the
+duplicate-attribute note below.
+
 The HTML parser lowercases attribute names before Tutuca sees them, so
 `:mapId` arrives as `:mapid` and `<x:Card>` becomes `<x:card>`. Three
 consequences:
@@ -549,6 +558,24 @@ via `is="..."` (e.g. `<button is="x-fancy">`); `is` is applied when the
 element is created, so it must be a static attribute — setting it later
 does not upgrade the element.
 
+### When nothing renders (or renders unstyled)
+
+A few mistakes fail quietly — no error, just a blank or unstyled result, which
+is the slowest kind to debug. **Run `tutuca lint <module>` first**: it catches
+several of these. The usual suspects:
+
+- **Unparseable attribute value** → the attribute is silently dropped. A bare
+  multi-word value isn't a string — quote it (`:label="'two words'"`) or make it
+  a template (`:label="$'{.a} {.b}'"`). Lint flags this as `BAD_VALUE`.
+- **camelCase attribute on a custom element** → setter no-op (see the lowercasing
+  note above). Use kebab-case attributes. Not lintable — the HTML parser
+  lowercases the name before either Tutuca or the linter sees it.
+- **Forgotten margaui `_palette`/decoy view** → classes assembled in methods or
+  interpolations render unstyled. See [margaui.md](./margaui.md). Not lintable.
+- **A whitespace-only `html\`\``** → blank render. A *leading* newline before the
+  root element is fine (the parser trims it); a template with no element at all
+  is not.
+
 ## Event Handling
 
 ```html
@@ -714,8 +741,8 @@ share the handler-name resolution rules below.
 alter: {
   filterItem(_key, item, iterData) { return item.includes(iterData.q); },
   enrichItem(binds, _key, item, iterData) { binds.count = item.length; },
-  // `@loop-with` returns { iterData?, start?, end? } — all optional.
-  getIterData(seq) {
+  // `@loop-with` is `(seq, ctx)` and returns { iterData?, start?, end?, keys? }.
+  getIterData(seq, ctx) {
     const start = this.page * this.pageSize;
     return { iterData: { q: this.query.toLowerCase() }, start, end: start + this.pageSize };
   },
@@ -724,7 +751,7 @@ alter: {
 
 #### `@loop-with` return shape — `iterData` + slicing
 
-A `@loop-with` handler returns an object with up to three optional keys:
+A `@loop-with` handler returns an object with up to four optional keys:
 
 - **`iterData`** — the shared per-loop value handed to `@when` /
   `@enrich-with`. Defaults to `{ seq }` when omitted.
@@ -733,11 +760,43 @@ A `@loop-with` handler returns an object with up to three optional keys:
   from the end (`end: -3` drops the last 3), `undefined` means the
   natural bound. Use this to **paginate** — skip a prefix and/or suffix
   without iterating or rendering it.
+- **`keys`** — an explicit, ordered array of **original keys** to visit,
+  for **filter-then-paginate**. The handler filters/sorts/slices the full
+  sequence itself and returns the current page's slice of original keys;
+  the renderer visits exactly those (`seq.get(key)`), in order. Takes
+  precedence over `start`/`end` when both are present.
 
 Slicing is positional but **preserves each item's original key**: a List
 sliced to `start: 2` still binds `@key` to `2, 3, …`, so events, drag,
-and two-way binding keep their identity. `@when` then filters *within*
-the window, so a page may yield fewer than `end - start` items.
+and two-way binding keep their identity. With `start`/`end`, `@when` then
+filters *within* the window, so a page may yield fewer than `end - start`
+items — to filter *before* paging (so the page count reflects the filtered
+total), return `keys` instead. `keys` are original keys, so identity is
+preserved there too: editing or deleting a row on page 2 of a filtered view
+hits the right item. A `keys` return is **authoritative** — the renderer
+visits exactly those keys and does **not** re-apply `@when` (the handler has
+already decided what renders).
+
+#### `@loop-with` handler context — `(seq, ctx)`
+
+The handler's second argument is `ctx = { lookup, filter }` (an object so it
+can grow):
+
+- **`ctx.lookup(name)`** — reads a scope `@`-binding, e.g. one published by an
+  ancestor scope `@enrich-with`. Lets the handler **reuse a value the enrich
+  already computed** instead of recomputing it.
+- **`ctx.filter(key, value, iterData)`** — wraps the declared `@when` predicate
+  (always callable; a no-op that returns `true` when there is no `@when`). Lets
+  the handler apply the *declared* filter while building its `keys` slice,
+  rather than re-implementing the match test.
+
+This is the **filter-then-paginate, minimal-work** pattern: a scope
+`@enrich-with` on an ancestor does **one** counting scan and publishes the
+clamped page + pager labels (which the page controls, sitting outside the loop,
+read as `@`-bindings); the `@loop-with` handler then reads the clamped page via
+`ctx.lookup`, reuses the predicate via `ctx.filter`, and collects only the
+current page's keys — early-exiting once the page is full. See
+[patterns/filter-and-paginate.md](patterns/filter-and-paginate.md).
 
 ### Lifecycle of `@each`
 
@@ -745,14 +804,18 @@ For each render of an element with `@each=".items"`:
 
 1. **Resolve sequence** — evaluate `.items`. Lists, IMaps, OMaps, ISets,
    and any class declaring a `SEQ_INFO` walker are recognized.
-2. **`@loop-with`** (once per render) — `getIterData.call(this, seq)` is
-   called with the full sequence; its `iterData` becomes the shared
-   per-loop value and its `start`/`end` slice the iteration. Skipped if
-   no `@loop-with`; then `iterData` is `{ seq }` and the whole sequence
-   is iterated.
-3. For each `(key, value)` pair in the sliced sequence:
+2. **`@loop-with`** (once per render) — `getIterData.call(this, seq, ctx)`
+   is called with the full sequence and the `{ lookup, filter }` context;
+   its `iterData` becomes the shared per-loop value and its `start`/`end`
+   slice the iteration. Skipped if no `@loop-with`; then `iterData` is
+   `{ seq }` and the whole sequence is iterated. If it returns `keys`,
+   those exact keys are visited in order (filter-then-paginate) and
+   `start`/`end` are ignored.
+3. For each `(key, value)` pair in the sliced sequence (or each `key` in
+   `keys`):
    1. **`@when`** — `filterItem.call(this, key, value, iterData)`; if it
-      returns `false`, the item is skipped.
+      returns `false`, the item is skipped. **Not applied** when the
+      handler returned `keys` (those are authoritative).
    2. **`@enrich-with`** — `enrichItem.call(this, binds, key, value, iterData)`.
       `binds` is a **mutable object** seeded with `{ key, value }`;
       mutating it (`binds.count = ...`) creates `@`-prefixed bindings

package/skill/tutuca/margaui.md

@@ -95,24 +95,36 @@ available (`npx tutuca install-skill --margaui-skill`) — it lists the
 available components and their canonical class strings, which is what the
 `compile` step expects.
 
-## Pitfall: @if.class is invisible to the scanner
+## Pitfall: assembled class names are invisible to the scanner
 
-Classes inside `@then` / `@else` (e.g.
-`@if.class=".active" @then="'btn-success'" @else="'btn-ghost'"`) are not
-literals in `class=` / `:class=`, so `compileClassesToStyleText` skips
-them and the margaui CSS for those classes is never emitted — the
-conditional class renders unstyled. Workaround: add a hidden "decoy" view
-on the component that lists every conditional class as a real literal, so
-the walker picks them up:
+The scanner only reads **constant** class literals out of parsed templates. It
+cannot see a class name that is assembled rather than written out verbatim, so
+the margaui CSS for that class is never emitted and it renders unstyled. Two
+cases:
+
+- **Interpolated templates** — `:class="$'bg-{.color}'"` contributes only the
+  constant prefix `bg-`, never `bg-red` / `bg-blue`. Same for any `${…}` segment.
+- **Classes built in a method** — anything a method returns (e.g. a `headerClass()`
+  that builds `` `progress-${this.color}` ``) is never scanned at all; the walker
+  only reads view templates, not JS bodies.
+
+(Literal `@then` / `@else` strings on `@if.class` — e.g.
+`@if.class=".active" @then="'btn-success'" @else="'btn-ghost'"` — **are** now
+collected, so those don't need the workaround.)
+
+Workaround: add a hidden "decoy"/palette view on the component that lists every
+possible assembled class as a real literal, so the walker picks them up:
 
 ```js
-_margauiClasses: html`<p class="btn-success btn-ghost on off"></p>`,
+// enumerate color × utility so each full class name appears verbatim
+_margauiClasses: html`<p class="bg-red bg-blue progress-red progress-blue"></p>`,
 ```
 
-The view does not need to be rendered anywhere — registration is enough
-for the template walker to find it. (This is the same rule
-[component-design.md](./component-design.md) gives for runtime-assembled
-margaui classes.)
+The view does not need to be rendered anywhere — registration is enough for the
+template walker to find it. (This is the same rule
+[component-design.md](./component-design.md) gives for runtime-assembled margaui
+classes.) The cost is that the palette and the methods can drift apart with no
+check catching it; keep them adjacent and update both together.
 
 ## See also
 

package/skill/tutuca/patterns/README.md

@@ -14,6 +14,7 @@ task.
 - [Filter a list](filter-a-list.md) — keep only matching items with `@when`.
 - [Enrich each item](enrich-each-item.md) — expose derived per-item values as `@`-bindings.
 - [Paginate a list](paginate-a-list.md) — slice the iteration with `@loop-with` `start`/`end`.
+- [Filter and paginate a list](filter-and-paginate.md) — do both with `@loop-with` `keys` (filter-then-slice, identity preserved).
 
 ## Conditional content & attributes
 

package/skill/tutuca/patterns/filter-a-list.md

@@ -20,4 +20,6 @@ alter: {
 `@when` names an `alter` handler called per item as `(key, value, iterData)`;
 return `false` to skip. It filters *after* any `@loop-with` slice, so a page
 can yield fewer than its window. Filtering reads other fields off `this`
-directly (`this.query`) — there are no paths in the template.
+directly (`this.query`) — there are no paths in the template. To filter
+*before* paging, return `keys` from `@loop-with` instead — see
+[filter-and-paginate.md](filter-and-paginate.md).

package/skill/tutuca/patterns/filter-and-paginate.md

@@ -0,0 +1,116 @@
+# Filter and paginate a list
+
+**Problem:** show one page of the items that match a query — filtering
+*before* paging, so page counts reflect the filtered total and a row's
+identity survives editing or deleting across pages — without scanning the
+list more than necessary.
+
+```html
+<section @enrich-with="pageInfo">          <!-- COUNT pass: runs once -->
+  <input :value=".query" @on.input="search value" />
+  <li @each=".items" @when="onlyMatches" @loop-with="page">  <!-- COLLECT pass -->
+    <span @text="@key"></span> <x render-it></x>
+    <button @on.click="$removeInItemsAt @key">✕</button>
+  </li>
+  <button :disabled="@isFirst" @on.click="prev">‹</button>
+  <button @text="@pageLabel"></button>
+  <button :disabled="@isLast" @on.click="next">›</button>
+</section>
+```
+
+```js
+methods: { matchCount() { /* one scan: how many match this.query */ } },
+alter: {
+  onlyMatches(_key, p) { return matches(p, this.query); },   // the predicate
+  pageInfo() {                                  // scope enrich: the COUNT scan
+    const total = this.matchCount();
+    const { pageCount, currentPage } = clamp(this.page, total, this.pageSize);
+    return { currentPage, isFirst: currentPage <= 0, isLast: currentPage >= pageCount - 1,
+             pageLabel: `Page ${currentPage + 1} of ${pageCount} · ${total}` };
+  },
+  page(seq, { lookup, filter }) {               // @loop-with: the COLLECT scan
+    const start = lookup("currentPage") * this.pageSize, end = start + this.pageSize;
+    const keys = [];
+    let m = 0;
+    for (let i = 0; i < seq.size && m < end; i++)   // early-exit: stops at page end
+      if (filter(i, seq.get(i))) { if (m >= start) keys.push(i); m++; }
+    return { keys };
+  },
+},
+```
+
+Returning **`keys`** (ordered *original* keys) is what makes this work: the
+renderer visits exactly those and does **not** re-apply `@when`, and because
+`@key` stays the original index, deleting row `@key` on page 2 of a filtered
+view hits the right item. The page controls live *outside* the loop, so they
+can't read its `iterData`; instead a scope `@enrich-with` does the one counting
+scan and publishes the clamped page + labels as `@`-bindings. The `@loop-with`
+handler's `ctx` lets it avoid repeating that work: `ctx.lookup` reads the
+clamped page the enrich already computed, and `ctx.filter` reuses the declared
+`@when` predicate — so the collect pass scans just far enough to fill the page.
+Reset `page` to 0 when the query changes.
+
+## Three ways to wire it
+
+The block above is the **shared** strategy. There are three, trading simplicity
+for scans-per-render (all return `keys`, so all keep identity):
+
+**1. Naive — two independent scans.** The loop scans + slices the whole list
+itself; a separate `@enrich-with` scans again for the labels. Simplest, nothing
+shared:
+
+```js
+naiveTablePage(seq, { filter }) {            // builds the WHOLE matching list…
+  const all = [];
+  for (let i = 0; i < seq.size; i++) if (filter(i, seq.get(i))) all.push(i);
+  const start = clamp(this.page, all.length, this.pageSize).currentPage * this.pageSize;
+  return { keys: all.slice(start, start + this.pageSize) };   // …just to slice it
+},
+```
+
+**2. Shared — one count + one partial collect** (the block above). The enrich
+counts and publishes `@currentPage`; the loop reuses it via `lookup` and stops
+once the page is full.
+
+**3. Coupled — one scan.** The enrich does *everything*, including the page keys,
+and stashes them in a binding only the loop reads. Fastest, but the two handlers
+are welded together — name them so it shows:
+
+```js
+enrichBuildsKeysForTheLoopBelow() {          // the only scan: count + labels + keys
+  const all = []; /* …collect matching indices… */
+  const { pageCount, currentPage } = clamp(this.page, all.length, this.pageSize);
+  const start = currentPage * this.pageSize;
+  return { __keys__: all.slice(start, start + this.pageSize), /* …labels… */ };
+},
+loopJustForwardsTheEnrichsKeys(_seq, { lookup }) {  // useless without the enrich
+  return { keys: lookup("__keys__") };
+},
+```
+
+## Testing each strategy
+
+`collectIterBindings(Comp, instance, seq, opts)` drives a loop exactly like the
+renderer and returns the `{ key, value }` binds it would render. Map the
+template's directives to `opts` — `when` → `@when`, `loopWith` → `@loop-with`,
+`scopeEnrich` → the ancestor scope `@enrich-with` whose result the loop reads via
+`ctx.lookup`:
+
+```js
+import { collectIterBindings } from "tutuca";
+const keys = (Comp, c, opts) => collectIterBindings(Comp, c, c.items, opts).map((b) => b.key);
+
+// each strategy wires the directives differently, yet renders the same page:
+keys(Naive,   c, { when: "onlyMatches", loopWith: "naiveTablePage" });
+keys(Shared,  c, { when: "onlyMatches", loopWith: "page", scopeEnrich: "pageInfo" });
+keys(Coupled, c, { loopWith: "loopJustForwardsTheEnrichsKeys",
+                   scopeEnrich: "enrichBuildsKeysForTheLoopBelow" });
+```
+
+A `keys` return is honored as-is (no `@when` re-applied), and `scopeEnrich` runs
+the named scope handler so a `lookup("currentPage")` / `lookup("__keys__")`
+resolves in the test. `collectIterBindings` lives in the **dev build**; both the
+playground's Test tab (via its import map) and `tutuca test` (which redirects the
+`"tutuca"` import to the dev build under Node) resolve it to the real
+implementation. See [filter-a-list.md](filter-a-list.md) and
+[paginate-a-list.md](paginate-a-list.md) for each half on its own.

package/skill/tutuca/patterns/paginate-a-list.md

@@ -24,4 +24,6 @@ slice with `Array.prototype.slice` semantics (`end` exclusive, negatives count
 from the end). Slicing is positional but **preserves each item's original
 key** — `@key` is the index in the full list, so events and two-way binding
 keep their identity across pages. `iterData` is the shared per-loop value
-handed to `@when` / `@enrich-with`.
+handed to `@when` / `@enrich-with`. To paginate a *filtered* list, return
+`keys` instead of `start`/`end` — see
+[filter-and-paginate.md](filter-and-paginate.md).

package/skill/tutuca/storybook.md

@@ -27,7 +27,7 @@ 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 |
+| `getComponents()` | `[Comp, ...]` | stories — return **every** component the module defines, children and helpers included. Components dedup by identity, so re-listing a leaf that another module also lists is safe (a composition module can re-list every leaf it uses). |
 | `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) |
@@ -37,7 +37,12 @@ same file is a valid target for `tutuca lint` / `test` / `render` too.
 ## Authoring stories (`getExamples`)
 
 Return one section, or an array of sections to group examples under multiple
-headings. A section is `{ title, description?, items: [...] }`:
+headings. A section is `{ title, description?, items: [...] }`. An array of one
+section behaves exactly like returning that section directly — both go through
+the same `Section.fromData`, which **throws** on a malformed section (missing
+`title`, not an object) rather than rendering a placeholder title. (If you saw
+broken titles from a one-element array in an older build, that predates array
+support — it has shipped since well before 0.9.88.)
 
 ```js
 import { component, html } from "tutuca";

package/skill/tutuca/testing.md

@@ -114,10 +114,21 @@ export function getTests({ describe, test, expect, drive }) {
 - `drive(value, phase, opts?)` builds a transactor over `value`, dispatches the
   phase's actions at the root, awaits the whole cascade (including async
   requests), and returns the **settled** instance.
+- `drive` **always originates at the root** — there is no `at:`/path option. To
+  exercise a handler on a nested child, call it directly with `.call(child, …)`.
 - `phase` is the same shape as an example's `on.init`
   (`{ send, bubble, request, input, do }`; see
   [storybook.md](./storybook.md#lifecycle-hooks-on)). `args` may be a function
   `(self) => [...]`.
+- A `bubble` action is a **no-op under `drive`**: bubbles travel child→parent, and
+  at the root there is no ancestor to receive it (the root's own `bubble` handler
+  is skipped too). To test a `bubble` handler, call it directly. (`drive` warns
+  when a phase contains a `bubble`.)
+- These are *action kinds*, not methods. `$`-prefixed **methods** (auto setters/
+  togglers, `$foo`) are not an action kind — `on`/`drive` can only reach state
+  through `input`/`receive`/`response` handlers. To put a component into a method-
+  driven state for a test, call the method directly or route it through an `input`
+  handler.
 - `request` actions resolve against the module's `getRequestHandlers()`.
 - `opts.onMessage(message, before, after)` observes every committed transaction —
   `message` is `{ kind, name, args, path }`, `before`/`after` are the root values

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

@@ -1744,37 +1744,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) {
@@ -1810,8 +1820,17 @@ var filterAlwaysTrue = (_v, _k, _seq) => true;
 var nullLoopWith = (seq) => ({ iterData: { seq } });
 var unpackLoopResult = (result, seq) => {
   const r = result ?? {};
-  return { iterData: r.iterData ?? { seq }, start: r.start, end: r.end };
+  return { iterData: r.iterData ?? { seq }, start: r.start, end: r.end, keys: r.keys };
+};
+var imKeysIter = (seq, visit, keys) => {
+  const attrName = isIndexed(seq) ? "si" : "sk";
+  for (const key of keys)
+    visit(key, seq.get(key), attrName);
 };
+var makeLoopCtx = (stack, filter) => ({
+  lookup: (name) => stack.lookupBind(name),
+  filter: (key, value, iterData) => filter.call(stack.it, key, value, iterData)
+});
 var imIndexedIter = (seq, visit, start, end) => {
   const [s, e] = normalizeRange(start, end, seq.size);
   for (let i = s;i < e; i++)
@@ -2359,11 +2378,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;
@@ -3714,6 +3733,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;
@@ -4007,7 +4033,8 @@ class FieldSet extends Field {
 }
 function mkCompField(field, scope, args) {
   const Comp = scope?.lookupComponent(field.type) ?? null;
-  console.assert(!scope || Comp !== null, "component not found", { field });
+  if (Comp === null)
+    console.warn(scope ? `component field "${field.name}": component "${field.type}" not found in scope` : `component field "${field.name}": cannot resolve component "${field.type}" — built without a registered scope (use ${field.type}.make({}) as the default, or build via a registered component)`);
   return Comp?.make({ ...field.args, ...args }, { scope }) ?? null;
 }
 
@@ -4156,6 +4183,7 @@ export {
   removeIn,
   remove,
   phaseOps,
+  phaseHasBubble,
   mergeWith,
   mergeDeepWith,
   mergeDeep,