tutuca 0.9.97 → 0.9.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.97",
+  "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"
@@ -99,9 +101,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/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

@@ -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
@@ -630,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
 
@@ -714,8 +740,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 +750,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 +759,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 +803,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
@@ -868,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
@@ -1052,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/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).