micra.js 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,231 @@
+# Changelog
+
+All notable changes to Micra.js will be documented in this file. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning follows
+[SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [2.2.0] — 2026-05-27
+
+### Performance — single-pass DOM scan
+
+- **Mount cost cut roughly in half.** Internal `applyDirectives`,
+  `bindDataOn`, `bindAtEvents`, `bindModels`, `collectRefs`, and
+  `renderList` used to walk the DOM 10+ times per render via separate
+  `querySelectorAll` calls. They now consume a single pre-computed
+  `ScanIndex` built by one `TreeWalker` traversal. The walker
+  `FILTER_REJECT`s subtrees rooted at nested `[data-component]` — those
+  subtrees aren't even visited.
+- Cross-library benchmark numbers on Firefox 150 / Mac (median of 7 runs):
+
+  | Scenario                  | Before  | After     | Vs Alpine.js  | Vs petite-vue |
+  | ------------------------- | ------: | --------: | ------------: | ------------: |
+  | Mount 100 components      | 10.8 ms | **5.6 ms**| × 4.9 faster  | × 3.6 faster  |
+  | Mount 1000 components     |128.3 ms |**65.4 ms**| × 7.0 faster  | × 2.4 faster  |
+  | Update 5 of 1000 rows     |    —    | **1 ms**  | × 886 faster  | × 1002 faster |
+  | 10,000 state writes       |    —    | **1 ms**  | × 980 faster  | × 983 faster  |
+  | First render 1000 keyed   |    —    | **12 ms** | × 79 faster   | × 82 faster   |
+  | Swap first ↔ last of 1000 |    —    | **7 ms**  | × 131 faster  | × 143 faster  |
+
+  Bundle stays at **5.0 KB gzip** — the rewrite removed code, not added it.
+
+### TypeScript — full inference from your component literal
+
+- **Method-level type inference.** Both `S` (state shape) and `M`
+  (method set) are now inferred from the object literal passed to
+  `Micra.define` / `Micra.mount`. Inside method bodies and lifecycle
+  hooks **both** `this.state.X` and `this.someMethod()` are fully typed:
+
+  ```ts
+  Micra.define('counter', {
+    state: { count: 0 },
+    inc() {
+      this.state.count++   // ✓ number
+      this.dec()           // ✓ inferred sibling method
+      // this.foo()        // ❌ Property 'foo' does not exist
+    },
+    dec() { this.state.count-- },
+  })
+  ```
+
+- Public `ComponentInstance<S, M>` and `ComponentDefinition<S, M>` now
+  take a second generic parameter for methods. `mount()` returns a fully
+  typed instance — `inst.inc()` and `inst.state.count` are both checked
+  at the call site.
+- New `ComponentMethods` and `ComponentBuiltins` types exported for
+  advanced typing.
+
+### Breaking — internal only
+
+- The internal directive scan format changed (`DirectiveCache` →
+  `ScanIndex`). Internal-only — no public-API change. If you reached
+  into internals via deep imports, switch to consuming
+  `el.__micraScan` instead of `el.__micraCache`.
+
+## [2.1.0] — 2026-05-25
+
+### Added
+
+- **`this.fetch(url, { signal })` now forwards `AbortSignal` to the native
+  `fetch()`.** Previously the `signal` option was treated as any other
+  GET-option and serialized into the URL as `&signal=[object AbortSignal]`,
+  while never reaching the underlying request — so abort silently did
+  nothing. After this release:
+  - `signal` passes through verbatim to native `fetch()`.
+  - `signal` is excluded from the GET-querystring serialization loop.
+  - `AbortController#abort()` rejects the in-flight request with an
+    `AbortError`, matching native semantics.
+  - Enables the canonical search-debounce pattern (drop a stale request when
+    a fresher query arrives) without dropping to native `fetch` manually.
+  - Migration: none — purely additive, the previous URL-serialization
+    behaviour was a bug.
+
+### Tests
+
+- 76 new tests for the components and recipes shipped on the docs site
+  (14 components + 6 recipes). Total suite: 235 tests across 13 files.
+
+## [2.0.0] — 2026-05-24
+
+### Breaking
+
+- **`data-if` now truly unmounts the element from the DOM.** Previously
+  `data-if` and `data-show` were aliases — both toggled `style.display`.
+  Now `data-if` detaches the element (replacing it with a Comment placeholder)
+  when falsy and re-inserts it when truthy. `data-show` keeps the old
+  `style.display` behaviour and is the way to express cheap visibility
+  toggling.
+  - Side effect: `this.refs.X` is `undefined` while the element is detached.
+  - DOM listeners on the detached node survive — re-insert preserves identity.
+  - `<template data-each>` inside a `data-if=false` subtree is suspended and
+    re-renders cleanly when the ancestor returns.
+  - **Migration:** if you relied on `data-if` keeping the element in the DOM
+    (e.g. you were reading `this.refs.X` while hidden, or animating
+    `display` transitions), replace those `data-if` attributes with
+    `data-show`.
+
+### Fixed
+
+- **`@event` shorthand no longer crosses nested `data-component` boundaries.**
+  `bindAtEvents` previously walked all descendants via `queryAll('*')`,
+  attaching parent-component handlers to elements owned by a nested child
+  component. It now uses `queryOwnAll` like `data-on`/`data-model` already do.
+- **`this.fetch(url, { method: 'POST' })` without a `body` no longer sends
+  the options object as the body.** Previously `body` was set to
+  `JSON.stringify(options)` (which serialized `{"method":"POST"}` to the
+  server). Now the body is omitted unless `options.body` is provided.
+
+### Added
+
+- **`queryOwnAll(root, selector)`** in `src/dom/query.ts` — selector variant
+  of `queryOwn` for cases where there is no attribute to query by (e.g.
+  scanning `*` for `@`-prefixed attribute names).
+- **Recipe: `docs/recipes/sse.md`** — server-sent events pattern using
+  `onCreate` + native `EventSource` + `onDestroy` cleanup. No new library
+  surface; just the canonical pattern for live data on top of Micra.
+
+### Docs
+
+- `docs/directives.md` — full split between `data-if` (unmount) and
+  `data-show` (display).
+- `docs/llm-guide.md`, `PROMPT.md`, `llms.txt`, `llms-full.txt` — updated
+  the directive table and added a "when to pick which" rule for AI agents.
+
+---
+
+## [1.1.0] — 2026-05-24
+
+### Security
+
+- **Directive expressions now shadow non-whitelisted globals.** Identifiers in
+  `data-text`, `data-if`, `data-bind`, etc. resolve to state keys, instance
+  methods, or one of the whitelisted globals: `Math`, `JSON`, `Date`, `String`,
+  `Number`, `Boolean`, `Array`, `Object`, `parseInt`, `parseFloat`, `isNaN`,
+  `isFinite`, `NaN`, `Infinity`, `undefined`. Everything else (`window`,
+  `document`, `fetch`, `eval`, `setTimeout`, `constructor`, `__proto__`, ...)
+  resolves to `undefined`. This blocks the common
+  `constructor.constructor("...")()` chain and accidental access to browser
+  globals from directive markup. See `docs/directives.md → Security model` for
+  the full contract.
+- **`data-html` is now explicitly documented as XSS-prone.** Inline JSDoc
+  warning + Security model section in the docs. Sanitize untrusted input on
+  the server before binding.
+
+### Fixed
+
+- **`destroy()` actually unmounts.** Every DOM listener attached by
+  `data-on` / `@event` / `data-model` is now tracked on the instance and
+  removed in `destroy()`. Scheduled re-renders after destroy are no-ops.
+  Per-element bookkeeping flags are cleared so re-mounting the same DOM
+  rebinds cleanly.
+- **Instance methods called from directive expressions now have `this`
+  bound to the component.** `data-text="doneCount() + ' done'"` where
+  `doneCount` reads `this.state.items` now works as written (previously
+  silently returned `undefined` due to `with()` semantics).
+- **`data-model` on focused inputs syncs programmatic state changes.**
+  `this.state.q = ''` while the input has focus now clears the field.
+  Live typing remains a no-op (state already matches value after the input
+  event, so no write happens).
+- **`data-model` on `<input type="number">` / `<input type="range">`
+  writes a `number`, not a string.** Empty inputs write `null`. Checkbox
+  inputs continue to write booleans.
+- **Duplicate `data-each` keys produce a warning.** Previously rows
+  silently collided.
+- **`null` / `undefined` `data-each` keys warn once per render**
+  instead of once per item.
+- **`@event` shorthand re-scans the subtree on every render.**
+  Replaces the root-level `__micraAtScanned` flag with per-element
+  `__micraAtBound`, so `@click` attributes inside markup injected via
+  `data-html` get bound on the next render.
+- **`data-bind="class:..."` + `data-class` on the same element now warns**
+  via `validateDirectives` — the two directives fight on every render.
+- **`bus.off()` cleans up empty event Sets** instead of leaving them in
+  the map.
+
+### Added
+
+- **Dev warnings (deduped):**
+  - re-entrant `render()` call (typically: a directive expression that
+    mutated state) — warns once per instance.
+  - runtime errors in directive expressions — warns once per unique
+    expression string.
+
+### Changed
+
+- **Internal:** `data-bind` and `data-class` specs are pre-parsed once
+  into `CachedPairBinding.pairs` in `DirectiveCache` — re-renders skip
+  the comma+colon split.
+- **Internal:** `Object.prototype` key membership is pre-computed once
+  at module load and cached in a `Set` (faster `safeStateHas`).
+- **Internal:** `data-each` no-key warning is deduped per template
+  via `__micraNoKeyWarned`.
+
+### Docs
+
+- `docs/directives.md` — new "Security model" section.
+- `docs/llm-guide.md` — Security model, `Micra.off` reference,
+  "Things Micra does NOT support" (key modifiers, nested `data-model`,
+  `data-if` keeps element in DOM).
+- `docs/examples.md` — inline-edit example now has `data-ref="input"`
+  and uses `e.key === 'Enter'` instead of unsupported `@keydown.enter`.
+
+### Bundle size
+
+- ~3.7 KB → 4.8 KB gzip. Cost of the security hardening + listener
+  cleanup tracking.
+
+### Migration notes
+
+- If any directive expression relied on `constructor`, `window`, `fetch`,
+  or other non-whitelisted globals, it now resolves to `undefined`. Move
+  the access into a component method.
+- If you held onto an instance after calling `destroy()`, you can now
+  safely re-mount the same DOM with a new definition.
+
+---
+
+## [1.0.0] — initial release
+
+Reactive shallow `Proxy` state, batched microtask rendering, DOM directives
+(`data-text`, `data-html`, `data-if`, `data-show`, `data-bind`, `data-model`,
+`data-class`, `data-on`, `@event`), keyed `data-each` list rendering, event
+bus, SSR `prop()`, `fetch()` helper, idempotent `start()`.

package/README.md

@@ -2,21 +2,31 @@
 
 Micra.js is a lightweight reactive TypeScript framework for small sites and SaaS apps. It gives you reactive state, DOM directives, keyed list rendering, an event bus, SSR-friendly props, and auto-mounting in about 5 KB gzip.
 
-## What is Micra.js?
+## When to use Micra.js
 
-Micra.js is designed for server-rendered apps and small frontends that need a little reactivity without a large framework.
+Built for **server-rendered apps** (Rails, Laravel, Django, Phoenix, ASP.NET) and small SaaS frontends that need a sprinkle of reactivity without a build step.
 
-Use it when you want:
+Reach for Micra.js instead of React/Vue when:
 
-- JS expressions in directives like `data-if="count > 0"`
-- keyed list diffing with `data-each` + `data-key`
-- auto-mounting with `data-component`, `Micra.define()`, and `Micra.start()`
+- ~5 KB gzip matters (full bundle, not "core")
+- you want to drop a `<script>` tag on an existing page and go — no toolchain
+- you have HTML rendered by your server template engine that needs reactive directives
+- you don't need client-side routing or a full SPA
+- you want **htmx + reactive client state** in the same page
+
+Compared to Alpine.js: smaller surface, no `x-*` shorthand soup, AST-validated expressions (no global `window` / `fetch` access from markup), cleaner LLM ergonomics — fewer anti-patterns to fall into.
+
+What you get:
+
+- reactive `state` via a shallow `Proxy` (top-level writes only)
+- JS expressions in directives: `data-if="count > 0"`
+- keyed list diffing: `data-each` + `data-key`
+- auto-mounting via `data-component` + `Micra.start()`
 - SSR props from `data-*` attributes via `this.prop()`
-- a built-in `this.fetch()` helper
-- a small global event bus with `Micra.on()` and `Micra.emit()`
-- DOM refs via `data-ref`
-- additive class toggling with `data-class`
-- simple lifecycle hooks: `onCreate`, `onDestroy`
+- built-in `this.fetch()` helper with `AbortSignal` support
+- global event bus: `Micra.on()` / `Micra.emit()`
+- DOM refs via `data-ref`, additive class toggling via `data-class`
+- lifecycle hooks: `onCreate`, `onDestroy`
 
 ## Quick Start
 
@@ -102,8 +112,8 @@ Micra.start();
 | ------------ | ---------------------------------------- | ------------------------- |
 | `data-text`  | `data-text="name"`                       | Set `textContent`         |
 | `data-html`  | `data-html="content"`                    | Set `innerHTML`           |
-| `data-if`    | `data-if="count > 0"`                    | Toggle display            |
-| `data-show`  | `data-show="loaded"`                     | Alias of `data-if`        |
+| `data-if`    | `data-if="count > 0"`                    | Mount / unmount from DOM  |
+| `data-show`  | `data-show="loaded"`                     | Toggle `style.display`    |
 | `data-bind`  | `data-bind="href:url, disabled:loading"` | Bind attributes           |
 | `data-model` | `data-model="search"`                    | Two-way input binding     |
 | `data-each`  | `data-each="items" data-key="id"`        | List rendering            |
@@ -153,13 +163,14 @@ this.refs
 this.render()
 this.destroy()
 this.prop(name, default?)
-this.fetch(url, options?)
+this.fetch(url, options?)   // supports AbortSignal in options.signal
 this.emit(event, payload?)
 this.on(event, handler)
 ```
 
 ## Documentation
 
+- **AI / LLM code generation:** [`llms.txt`](./llms.txt) (overview) · [`llms-full.txt`](./llms-full.txt) (10 inline recipes + anti-pattern reference) · [`docs/llm-guide.md`](./docs/llm-guide.md) (full guide)
 - [Getting started](./docs/getting-started.md)
 - [Core concepts](./docs/concepts.md)
 - [Directives](./docs/directives.md)
@@ -171,3 +182,17 @@ this.on(event, handler)
 - Recipes:
   - [Todo app](./docs/recipes/todo-app.md)
   - [Server-sent events (SSE)](./docs/recipes/sse.md)
+
+## Code generation with LLMs
+
+Micra has a small surface area, but LLMs default to jQuery / vanilla-JS or React patterns that defeat the framework. When generating Micra code (in Claude artifacts, ChatGPT canvas, Cursor, Copilot, etc.), follow these rules:
+
+1. **Lists** go through `<template data-each="items" data-key="id">`. Never `getElementById` / `innerHTML` for component output.
+2. **Derived values** (counts, totals, filtered subsets) are **methods**, not state fields. State holds raw data only.
+3. **Event handlers** use `@event` / `data-on`. Never `addEventListener` inside methods — it leaks past `destroy()`. Document-level listeners go in `onCreate` and are removed in `onDestroy`.
+4. **No manual re-render.** Micra batches a microtask render on every state write — no `this.refresh()` / `this.update()` / `this.renderList()`.
+5. **State proxy is shallow.** Replace top-level: `state.user = { ...state.user, name: x }`, not `state.user.name = x`.
+6. **No modifier syntax** like `@keydown.enter` — branch on `e.key === 'Enter'` inside the handler.
+7. **Use jsDelivr, not unpkg** — `cdn.jsdelivr.net` is in the CSP allowlist of Claude artifacts / ChatGPT canvas; `unpkg.com` is blocked there.
+
+Full anti-pattern reference with side-by-side examples: [`docs/llm-guide.md`](./docs/llm-guide.md) and [`llms-full.txt`](./llms-full.txt).

package/dist/core/mount.d.ts

@@ -11,17 +11,23 @@
  * mount() is called by both the public Micra.mount() API and by start()
  * (which scans the DOM for [data-component] elements).
  */
-import type { ComponentDefinition, ComponentInstance, StateRecord } from '../types';
+import type { ComponentDefinition, ComponentInstance, StateRecord } from "../types";
 /**
  * Mount a component definition onto a DOM element.
  * Returns the component instance, or null if the root element is not found.
  *
  * Already-mounted elements return the existing instance.
  *
+ * Both `S` (state) and `M` (methods) are inferred from the literal — the
+ * returned instance is fully typed: `inst.state.X` and `inst.someMethod()`
+ * are checked.
+ *
  * @example
  * const instance = Micra.mount('#counter', {
  *   state: { count: 0 },
  *   inc() { this.state.count++ },
  * })
+ * instance?.inc()
+ * instance?.state.count
  */
-export declare function mount<S extends StateRecord>(selector: string | HTMLElement, definition: ComponentDefinition<S>): ComponentInstance<S> | null;
+export declare function mount<S extends StateRecord, M>(selector: string | HTMLElement, definition: ComponentDefinition<S, M>): ComponentInstance<S, M> | null;

package/dist/core/registry.d.ts

@@ -14,13 +14,22 @@ export declare const _instances: Map<HTMLElement, InternalInstance<StateRecord>>
 /**
  * Register a component definition under `name`.
  *
+ * Both state shape (`S`) and method set (`M`) are inferred from the literal,
+ * so `this.state.X` and `this.someMethod()` are fully typed inside the
+ * method bodies and lifecycle hooks.
+ *
  * @example
- * define('counter', { state: { count: 0 }, inc() { this.state.count++ } })
+ * define('counter', {
+ *   state: { count: 0 },
+ *   inc() { this.state.count++ },        // this.state.count: number ✓
+ *   reset() { this.state.count = 0 },    // this.reset() is also typed ✓
+ *   onCreate() { this.inc() },           // ✓
+ * })
  */
-export declare function define<S extends StateRecord>(name: string, definition: ComponentDefinition<S>): void;
+export declare function define<S extends StateRecord, M>(name: string, definition: ComponentDefinition<S, M>): void;
 /**
  * Type-helper — returns `definition` unchanged but lets TypeScript infer `S`
- * from the `state` literal so all methods are typed with the correct `this`.
+ * and `M` from the literal so all methods are typed with the correct `this`.
  *
  * Use this when defining a component outside a `define()` call.
  *
@@ -31,7 +40,7 @@ export declare function define<S extends StateRecord>(name: string, definition:
  * })
  * Micra.define('counter', counter)
  */
-export declare function defineComponent<S extends StateRecord>(definition: ComponentDefinition<S>): ComponentDefinition<S>;
+export declare function defineComponent<S extends StateRecord, M>(definition: ComponentDefinition<S, M>): ComponentDefinition<S, M>;
 /**
  * Returns a read-only view of all live instances (keyed by root element).
  * Useful for DevTools / debugging.

package/dist/dom/directives.d.ts

@@ -4,36 +4,32 @@
  * Responsibilities:
  *   - data-text, data-html, data-if, data-show, data-bind, data-model
  *   - data-class (additive class toggling)
- *   - Directive result cache (built once per element, reused on re-renders)
  *
- * LLM NOTE: applyDirectives() is called on every render. The directive cache
- * (DirectiveCache on el.__micraCache) avoids repeated querySelectorAll on
- * re-renders — cache is built lazily on the first call for each root element.
+ * LLM NOTE: applyDirectives() is called on every render. It consumes a
+ * pre-computed ScanIndex (built once by scan.ts and cached on the element).
+ * The scan replaced 10+ querySelectorAll calls with a single TreeWalker pass.
  *
  * Important: this module does NOT handle data-each — see dom/each.ts.
  */
-import type { InternalInstance, StateRecord } from '../types';
+import type { InternalInstance, ScanIndex, StateRecord } from '../types';
 import { warn } from '../utils/expr';
 /**
  * Apply all non-each directives to a component subtree.
  *
- * For regular Elements: directive bindings are cached in `el.__micraCache`
- * after the first call — subsequent re-renders skip querySelectorAll entirely.
+ * Consumes a pre-computed ScanIndex. data-if runs first so subsequent
+ * directives don't write into a tree that's about to be detached this tick.
  *
- * For DocumentFragments (no-key each clones): always re-scan because these
- * fragments are new clones on every render.
- *
- * @param root     - Component root Element or DocumentFragment (no-key each clone)
+ * @param scan     - Pre-computed scan from scan.ts (cached per element)
  * @param state    - Expression state (may include item/index for each rows)
  * @param rawState - Raw (non-proxy) state for model sync
- * @param instance - Component instance (unused here, kept for future hooks)
  */
-export declare function applyDirectives<S extends StateRecord>(root: Element | DocumentFragment, state: StateRecord, rawState: StateRecord, _instance: InternalInstance<S>): void;
+export declare function applyDirectives<S extends StateRecord>(scan: ScanIndex, state: StateRecord, rawState: StateRecord, _instance: InternalInstance<S>): void;
 /**
  * Validate directive usage and emit dev warnings.
- * Called once after the initial render of a component.
+ * Called once after the initial render of a component, with the already-built
+ * scan so we don't walk the DOM again.
  *
  * @internal
  */
-export declare function validateDirectives(root: Element): void;
+export declare function validateDirectives(scan: ScanIndex): void;
 export { warn };

package/dist/dom/each.d.ts

@@ -8,18 +8,20 @@
  *   - Apply directives to each row with a scoped itemState
  *
  * LLM NOTE: renderList() is called on every render cycle AFTER applyDirectives().
- * Only <template> elements with data-each are processed.
+ * The template list comes pre-scanned from scan.ts — no DOM queries here.
+ * Each row node gets its own ScanIndex cached on `node.__micraScan` so
+ * re-renders of that row don't re-walk the DOM.
  * Keyed mode (data-key present) mutates the DOM in-place — nodes are
  * created once and reused. Non-keyed mode removes all nodes and re-clones.
  */
 import type { InternalInstance, StateRecord } from '../types';
 /**
- * Process all `<template data-each>` elements owned by `root`.
+ * Process all `<template data-each>` elements found by the scanner.
  * Scoped itemState makes `item`, `index`, `$index` available in row expressions.
  *
- * @param root      - Component root Element
+ * @param templates - Pre-scanned list of <template data-each> elements
  * @param state     - Expression state (proxy merging rawState + instance)
  * @param rawState  - Raw (non-proxy) state — used for model binding
  * @param instance  - Component instance (for event binding)
  */
-export declare function renderList<S extends StateRecord>(root: Element, state: StateRecord, rawState: StateRecord, instance: InternalInstance<S>): void;
+export declare function renderList<S extends StateRecord>(templates: Element[], state: StateRecord, rawState: StateRecord, instance: InternalInstance<S>): void;

package/dist/dom/events.d.ts

@@ -9,29 +9,36 @@
  * LLM NOTE: Every listener attached here is also recorded in
  * instance.__micraListeners so destroy() can remove it cleanly.
  * Re-render skips already-bound elements via per-element __micra* flags.
+ *
+ * All three binders accept pre-computed element lists from scan.ts —
+ * no DOM queries here.
  */
-import type { InternalInstance, StateRecord } from '../types';
+import type { CachedBinding, InternalInstance, StateRecord } from '../types';
 /**
  * Bind `data-on="event:method[,event2:method2]"` listeners.
  * Listeners are bound once — re-render calls are no-ops for already-bound elements.
  *
  * Supports modifiers: `click.prevent`, `click.stop`, `click.self`.
  *
+ * @param els - Pre-computed list of [data-on] elements from scan.ts
+ *
  * @example
  * <button data-on="click:save">Save</button>
  * <form  data-on="submit.prevent:handleSubmit">
  */
-export declare function bindDataOn<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
+export declare function bindDataOn<S extends StateRecord>(els: Element[], instance: InternalInstance<S>): void;
 /**
  * Bind `@event="method"` shorthand attributes (Stimulus-style).
  * Bound once per element via `__micraAtBound` — re-renders are no-ops.
- * Supports the same modifiers as data-on: `@click.prevent="submit"`.
+ *
+ * @param els - Pre-computed list of elements with at least one @-prefixed attr
+ *              (from scan.ts — replaces the old `querySelectorAll('*')` walk)
  *
  * @example
  * <button @click="increment">+</button>
  * <form @submit.prevent="handleSubmit">
  */
-export declare function bindAtEvents<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
+export declare function bindAtEvents<S extends StateRecord>(els: Element[], instance: InternalInstance<S>): void;
 /**
  * Two-way binding: `data-model="key"` wires <input>/<select>/<textarea>
  * to `state[key]`. Binding is attached once per element.
@@ -39,8 +46,11 @@ export declare function bindAtEvents<S extends StateRecord>(root: Element, insta
  * Numeric inputs (`type="number"` / `type="range"`) write numbers, not strings.
  * Checkbox inputs write booleans. Everything else writes strings.
  *
+ * @param bindings - Pre-computed model bindings from scan.ts
+ *                   (each carries { el, expr } where expr is the state key)
+ *
  * @example
  * <input data-model="search">   // updates state.search on every keystroke
  * <select data-model="sortBy">  // updates state.sortBy on change
  */
-export declare function bindModels<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
+export declare function bindModels<S extends StateRecord>(bindings: CachedBinding[], instance: InternalInstance<S>): void;

package/dist/dom/refs.d.ts

@@ -2,22 +2,22 @@
  * src/dom/refs.ts — data-ref collection.
  *
  * Responsibilities:
- *   - After each render, scan for `[data-ref]` elements (owned by this component)
- *   - Populate `instance.refs` so methods can do `this.refs.chart` etc.
+ *   - Populate `instance.refs` from a pre-scanned list of [data-ref] elements.
  *
  * LLM NOTE: This module is PURE relative to state — it only reads DOM attributes
  * and writes to instance.refs. It does NOT trigger renders.
  */
 import type { InternalInstance, StateRecord } from '../types';
 /**
- * Collect all `[data-ref="name"]` elements owned by this component root into
- * `instance.refs`.
+ * Build `instance.refs` from the pre-scanned [data-ref] elements.
  *
  * Called once after the initial render and again on every re-render (refs may
  * point to newly created elements after an each-list update).
  *
+ * @param els - List of [data-ref] elements from scan.ts
+ *
  * @example
  * // HTML: <canvas data-ref="chart">
  * // JS:   this.refs.chart  →  HTMLCanvasElement
  */
-export declare function collectRefs<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
+export declare function collectRefs<S extends StateRecord>(els: Element[], instance: InternalInstance<S>): void;

package/dist/dom/scan.d.ts

@@ -0,0 +1,34 @@
+/**
+ * src/dom/scan.ts — Single-pass directive/event/ref scanner.
+ *
+ * Replaces 10+ querySelectorAll calls per render with ONE TreeWalker
+ * traversal that classifies every directive attribute in a single visit.
+ *
+ * Boundaries:
+ *   - REJECT (skip subtree) on nested [data-component] — same semantics as
+ *     the old `filterOwn` helper, but applied during the walk so we don't
+ *     even *visit* those nodes.
+ *   - <template> contents are not visited (browser TreeWalker default).
+ *     `<template data-each>` itself IS visited and classified into scan.each;
+ *     its children are processed by each.ts on every render via scanFragment.
+ *
+ * Hot-path notes:
+ *   - We read `el.attributes` once and switch by suffix. No allocations per
+ *     non-matching attr.
+ *   - Pair-parsing (`data-bind`, `data-class`) happens here, once, at scan
+ *     time. Reused on every render.
+ */
+import type { ScanIndex } from "../types";
+/**
+ * Scan an Element subtree owned by one component. Skips nested
+ * [data-component] subtrees entirely. Visits the root itself.
+ *
+ * Cached on `el.__micraScan` after the first call — subsequent renders
+ * are free.
+ */
+export declare function scanComponent(root: Element): ScanIndex;
+/**
+ * Scan a DocumentFragment (no-key each clone). Not cached — these fragments
+ * are temporary and re-cloned every render.
+ */
+export declare function scanFragment(frag: DocumentFragment): ScanIndex;

package/dist/index.d.ts

@@ -21,7 +21,7 @@
  *
  * @module Micra
  */
-export type { StateRecord, UnsubFn, EventHandler, FetchOptions, ComponentInstance, ComponentDefinition, } from './types';
+export type { StateRecord, UnsubFn, EventHandler, FetchOptions, ComponentMethods, ComponentBuiltins, ComponentInstance, ComponentDefinition, } from './types';
 export { FetchError } from './utils/fetch';
 export { define, defineComponent, instances, registry, debug } from './core/registry';
 export { mount } from './core/mount';