micra.js 2.2.1 → 2.3.1

package/llms-full.txt

@@ -7,7 +7,7 @@ This file follows the llmstxt.org "expanded" convention: it inlines code recipes
 ## Install
 
 ```bash
-npm install micra.js@^2.2.1
+npm install micra.js@^2.3.1
 ```
 
 ```ts
@@ -17,7 +17,7 @@ import * as Micra from 'micra.js'
 Or CDN (no build step):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.
@@ -146,7 +146,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <button @click="inc">+</button>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('counter', {
     state: { count: 0 },
@@ -190,7 +190,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   </footer>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('todo-app', {
     state: {
@@ -262,7 +262,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="filtered().length === 0">No matches.</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('users-table', {
     state: {
@@ -303,7 +303,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="success">Invitation sent ✓</p>
 </form>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('invite-form', {
     state: { email: '', loading: false, error: '', success: false },
@@ -345,7 +345,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   </div>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('open-modal-btn', {
     open() {
@@ -394,7 +394,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <section data-if="tab === 'security'">Security content</section>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('tabs', {
     state: { tab: 'overview' },
@@ -414,7 +414,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <button @click="upgrade" data-if="plan !== 'enterprise'">Upgrade</button>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('user-card', {
     state: { name: '', plan: '' },
@@ -445,7 +445,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="!loading && results.length === 0 && query">No results.</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('search', {
     state: { query: '', results: [], loading: false },
@@ -479,7 +479,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="loading">Loading chart…</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('revenue-chart', {
     state: { loading: true },
@@ -511,7 +511,7 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
   <p data-if="!loading && rows.length === 0">No results.</p>
 </div>
 
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 <script>
   Micra.define('search-bar', {
     state: { query: '' },
@@ -533,6 +533,154 @@ Everything else (`window`, `document`, `fetch`, `eval`, `constructor`, `setTimeo
 </script>
 ```
 
+## Recipe 11 — htmx bridge (server-driven HTML swaps + Micra islands)
+
+Wire htmx for server-driven DOM swaps and Micra for local reactivity on
+the same page. Twelve lines of glue, written once.
+
+```html
+<main hx-get="/page/home" hx-trigger="load" hx-swap="innerHTML"></main>
+
+<script src="https://cdn.jsdelivr.net/npm/htmx.org@2/dist/htmx.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
+<script>
+  Micra.define('counter', {
+    state: { count: 0 },
+    inc() { this.state.count++ },
+  })
+
+  Micra.start()  // initial mount
+
+  // Mount new [data-component] arriving via htmx swap.
+  document.body.addEventListener('htmx:afterSettle', (e) => {
+    Micra.start(e.target)
+  })
+
+  // Destroy Micra instances inside HTML about to be replaced.
+  document.body.addEventListener('htmx:beforeSwap', (e) => {
+    Micra.instances().forEach((inst, root) => {
+      if (e.target.contains(root)) inst.destroy()
+    })
+  })
+
+  // Bridge server-sent HX-Trigger events into the Micra bus.
+  document.body.addEventListener('htmx:trigger', (e) => {
+    const d = e.detail
+    if (typeof d === 'string') return Micra.emit(d)
+    for (const [k, v] of Object.entries(d)) Micra.emit(k, v)
+  })
+</script>
+```
+
+Rules of thumb:
+
+- **Never put `hx-swap` directly on a `[data-component]` element that
+  swaps its own `innerHTML`** — the cached directive scan points at gone
+  DOM. Use a wrapper as the swap target.
+- **`Micra.start()` is idempotent**, so re-scanning a subtree that
+  contains already-mounted siblings is safe.
+- **Always scope to `e.target`** in the bridge, not `document` — scanning
+  the whole page on every swap is wasteful.
+
+Full reference with state-survival patterns, `hx-vals`/`hx-include`
+bridging, and per-component loading state lives in
+`docs/recipes/htmx.md`.
+
+## Recipe 12 — Rails + Micra (importmap, CSRF, Turbo Drive)
+
+Pin Micra in `config/importmap.rb`, boot it once in the layout — that's
+the whole integration. CSRF works automatically (Micra reads
+`<meta name="csrf-token">` that Rails already ships). Turbo Drive needs
+a `turbo:load` mirror so the second navigation doesn't ghost.
+
+```ruby
+# config/importmap.rb
+pin "micra",
+    to: "https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.esm.js",
+    preload: true
+```
+
+```erb
+<%# app/views/layouts/application.html.erb — inside <head> %>
+<%= csrf_meta_tags %>
+<%= javascript_importmap_tags %>
+<script type="module">
+  import * as Micra from "micra"
+  window.Micra = Micra
+  document.addEventListener("DOMContentLoaded", () => Micra.start())
+  document.addEventListener("turbo:load",        () => Micra.start())
+</script>
+```
+
+```erb
+<%# app/views/tasks/index.html.erb %>
+<section data-component="tasks-board"
+         data-initial-tasks='<%= @tasks.as_json(only: %i[id title done]).to_json %>'>
+  <form @submit.prevent="add">
+    <input data-model="draft" placeholder="New task…" />
+    <button data-bind="disabled:!draft.trim()">Add</button>
+  </form>
+  <template data-each="tasks" data-key="id">
+    <li data-class="done:item.done">
+      <input type="checkbox" data-bind="checked:item.done" @change="toggle" />
+      <span data-text="item.title"></span>
+      <button @click="remove" data-bind="data-id:item.id">×</button>
+    </li>
+  </template>
+</section>
+```
+
+```js
+// app/javascript/application.js
+import * as Micra from "micra"
+
+Micra.define("tasks-board", {
+  state: { tasks: [], draft: "" },
+  onCreate() { this.state.tasks = JSON.parse(this.prop("initialTasks") || "[]") },
+  async add() {
+    const task = await this.fetch("/tasks", { method: "POST", body: { title: this.state.draft.trim() } })
+    this.state.tasks = [...this.state.tasks, task]
+    this.state.draft = ""
+  },
+  async toggle(e) {
+    const id = Number(e.currentTarget.closest("li").querySelector("[data-id]").dataset.id)
+    const next = !this.state.tasks.find(t => t.id === id).done
+    const task = await this.fetch(`/tasks/${id}`, { method: "PATCH", body: { done: next } })
+    this.state.tasks = this.state.tasks.map(t => t.id === id ? task : t)
+  },
+  async remove(e) {
+    const id = Number(e.currentTarget.dataset.id)
+    await this.fetch(`/tasks/${id}`, { method: "DELETE" })
+    this.state.tasks = this.state.tasks.filter(t => t.id !== id)
+  },
+})
+```
+
+Rules of thumb:
+
+- **CSRF is automatic** — keep `<%= csrf_meta_tags %>` in the layout.
+  `this.fetch()` sends `X-CSRF-Token` on every non-GET request.
+- **Add `turbo:load`** alongside `DOMContentLoaded` if you have Turbo
+  Drive enabled (default since Rails 7). Without it, only the first
+  page load wires up.
+- **JSON in `data-*` attributes does NOT auto-parse.** Non-primitive
+  props (`@tasks.as_json.to_json`) are strings client-side — call
+  `JSON.parse(this.prop('initialTasks'))` in `onCreate`. Primitives
+  (numbers, booleans) auto-cast through `this.prop()`.
+- **Turbo Frames** that swap their own `innerHTML` and contain a
+  `[data-component]` will leave the cached scan pointing at gone DOM.
+  Same footgun as htmx — keep `data-component` outside the frame, or
+  destroy+remount on `turbo:frame-render`.
+- The optional **`micra-rails`** gem adds an ERB helper
+  (`micra_component`) and a one-shot installer. Its importmap pin can lag
+  the latest Micra.js release between gem versions (override it in your
+  own `config/importmap.rb`), and the `micra_state.to_html` example in
+  its README doesn't compile — see `docs/recipes/rails.md` §2 for
+  workarounds.
+
+Full reference with Turbo Streams cleanup, no-flicker hydration pattern,
+and the Stimulus-vs-Micra split is in `docs/recipes/rails.md`.
+
 ---
 
 # Anti-pattern reference (what LLMs gravitate to — DO NOT)
@@ -569,9 +717,9 @@ import { ref, computed } from 'vue'
 import Alpine from 'alpinejs'
 
 // ❌ unpkg CDN — blocked by Claude artifacts and most AI sandbox CSPs
-<script src="https://unpkg.com/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://unpkg.com/micra.js@2.3.1/dist/micra.min.js"></script>
 // ✅ Use jsDelivr instead — it auto-mirrors npm and is CSP-allowlisted everywhere
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 ```
 
 # Final checklist

package/llms.txt

@@ -25,7 +25,7 @@ import * as Micra from 'micra.js'
 Or via CDN (no build step):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.3.1/dist/micra.min.js"></script>
 ```
 
 This exposes a global `Micra` object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micra.js",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Lightweight reactive UI framework for server-rendered pages — reactive state, directives, event bus. < 5 KB gzip.",
   "type": "module",
   "main": "./dist/micra.cjs.js",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "build": "node build.mjs",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
     "dev": "node build.mjs --watch",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/core/bus.ts

@@ -11,41 +11,50 @@
  * the unsub token in `instance.__micraSubs` for cleanup on destroy().
  */
 
-import type { EventHandler, UnsubFn } from '../types'
+import type { EmitArgs, EventHandler, EventPayload, UnsubFn } from '../types'
 
 // Module-level bus state — one bus per page load.
 const _bus = new Map<string, Set<EventHandler>>()
 
 /**
  * Subscribe to a named event. Returns an unsubscribe function.
+ * Payload is typed via the `MicraEvents` interface (augmentable).
  *
  * @example
  * const unsub = on('user:login', (user) => console.log(user))
  * unsub()  // stop listening
  */
-export function on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn {
+export function on<K extends string>(
+  event: K,
+  handler: (payload: EventPayload<K>) => void,
+): UnsubFn {
   if (!_bus.has(event)) _bus.set(event, new Set())
   _bus.get(event)!.add(handler as EventHandler)
-  return () => off(event, handler as EventHandler)
+  return () => off(event, handler)
 }
 
 /**
  * Unsubscribe a specific handler from an event.
  */
-export function off(event: string, handler: EventHandler): void {
+export function off<K extends string>(
+  event: K,
+  handler: (payload: EventPayload<K>) => void,
+): void {
   const set = _bus.get(event)
   if (!set) return
-  set.delete(handler)
+  set.delete(handler as EventHandler)
   if (set.size === 0) _bus.delete(event)
 }
 
 /**
  * Publish an event to all subscribers. Errors are caught per-handler.
+ * Payload is typed via the `MicraEvents` interface (augmentable).
  *
  * @example
  * emit('user:updated', { id: 1, name: 'Alice' })
  */
-export function emit(event: string, payload?: unknown): void {
+export function emit<K extends string>(event: K, ...args: EmitArgs<K>): void {
+  const payload = args[0]
   _bus.get(event)?.forEach(h => {
     try { h(payload) } catch (e) { console.error(`[Micra] bus error [${event}]:`, e) }
   })

package/src/core/mount.ts

@@ -17,6 +17,7 @@ import type {
   ComponentInstance,
   ComponentMethods,
   EventHandler,
+  EventPayload,
   InternalInstance,
   MicraElement,
 
@@ -96,11 +97,11 @@ export function mount<S extends StateRecord, M>(
   instance.fetch = micraFetch;
   instance.emit = busEmit;
 
-  instance.on = <T = unknown>(
-    event: string,
-    handler: EventHandler<T>,
+  instance.on = <K extends string>(
+    event: K,
+    handler: (payload: EventPayload<K>) => void,
   ): UnsubFn => {
-    const unsub = busOn(event, handler);
+    const unsub = busOn(event, handler as EventHandler);
     if (!instance.__micraSubs) instance.__micraSubs = [];
     instance.__micraSubs.push(unsub);
     return unsub;
@@ -174,7 +175,7 @@ export function mount<S extends StateRecord, M>(
       const mRoot = root as MicraElement;
       const scan =
         mRoot.__micraScan ?? (mRoot.__micraScan = scanComponent(root));
-      applyDirectives(scan, exprState, rawState, instance);
+      applyDirectives(scan, exprState, rawState);
       renderList(scan.each, exprState, rawState, instance, triggerKey);
       bindDataOn(scan.on, instance);
       bindAtEvents(scan.atEvents, instance);

package/src/core/reactive.ts

@@ -36,6 +36,10 @@ export function createReactiveState<S extends StateRecord>(obj: S, schedule: ()
  * Return a debounce function that defers `render` to the next microtask.
  * Multiple calls within the same tick collapse to a single render.
  *
+ * Uses `queueMicrotask` so each batch enqueues a single microtask instead of
+ * allocating a Promise + reaction job. `flush` is hoisted out of the hot path
+ * so it isn't re-created on every schedule() call.
+ *
  * @example
  * const schedule = createScheduler(render)
  * schedule()  // defers render
@@ -43,9 +47,10 @@ export function createReactiveState<S extends StateRecord>(obj: S, schedule: ()
  */
 export function createScheduler(render: () => void): () => void {
   let pending = false
+  const flush = () => { pending = false; render() }
   return function schedule() {
     if (pending) return
     pending = true
-    Promise.resolve().then(() => { pending = false; render() })
+    queueMicrotask(flush)
   }
 }

package/src/dom/directives.ts

@@ -14,7 +14,6 @@
 
 import type {
   CachedIfBinding,
-  InternalInstance,
   ScanIndex,
   StateRecord,
 } from '../types'
@@ -147,11 +146,10 @@ function applyModel(
  * @param state    - Expression state (may include item/index for each rows)
  * @param rawState - Raw (non-proxy) state for model sync
  */
-export function applyDirectives<S extends StateRecord>(
+export function applyDirectives(
   scan: ScanIndex,
   state: StateRecord,
   rawState: StateRecord,
-  _instance: InternalInstance<S>,
 ): void {
   // data-if runs first so subsequent directives don't write into a tree that's
   // about to be detached this tick.

package/src/dom/each.ts

@@ -4,7 +4,8 @@
  * Responsibilities:
  *   - Process `<template data-each="items" data-key="id">` elements
  *   - Keyed diff: reuse/reorder DOM nodes by key — O(n) with a Map
- *   - Non-keyed fallback: full replace (no key → warn in dev, full re-render)
+ *   - Non-keyed fallback: length-based positional reuse — min(old, new) rows
+ *     are kept as-is, the tail is removed or new rows are appended
  *   - Apply directives to each row with a scoped itemState
  *
  * LLM NOTE: renderList() is called on every render cycle AFTER applyDirectives().
@@ -12,7 +13,9 @@
  * 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.
+ * created once and reused. Non-keyed mode also reuses existing nodes
+ * positionally: only the length delta is touched, the rest gets a fresh
+ * itemState and re-applies directives.
  */
 
 import type {
@@ -24,7 +27,7 @@ import type {
 import { evalExpr, warn } from '../utils/expr'
 import { applyDirectives } from './directives'
 import { bindDataOn, bindAtEvents, bindModels } from './events'
-import { scanComponent, scanFragment } from './scan'
+import { scanComponent } from './scan'
 
 /**
  * Process all `<template data-each>` elements found by the scanner.
@@ -83,11 +86,42 @@ export function renderList<S extends StateRecord>(
     if (keyAttr) {
       renderKeyed(tmpl, items as StateRecord[], keyAttr, marker, keyMap, state, rawState, instance, canSkipUnchanged)
     } else {
-      renderNoKey(tmpl, items as StateRecord[], marker, state, rawState, instance)
+      renderNoKey(tmpl, items as StateRecord[], marker, state, rawState, instance, canSkipUnchanged)
     }
   }
 }
 
+// ── Row node creation (shared by both paths) ──────────────────────────────────
+
+/**
+ * Clone the template into a fresh row node, wrapping multi-root content in
+ * `<micra-each-item style="display:contents">` so the row always corresponds
+ * to a single, stable DOM element. Scans, binds listeners once, and caches
+ * an empty itemState prototyped from `state` (filled in by the caller).
+ */
+function createRowNode<S extends StateRecord>(
+  tmpl: MicraTemplate,
+  state: StateRecord,
+  instance: InternalInstance<S>,
+): MicraElement {
+  const frag = tmpl.content.cloneNode(true) as DocumentFragment
+  let node: MicraElement
+  if (frag.childNodes.length === 1) {
+    node = frag.firstElementChild as MicraElement
+  } else {
+    node = document.createElement('micra-each-item') as MicraElement
+    node.style.display = 'contents'
+    node.append(frag)
+  }
+  const rowScan = scanComponent(node)
+  node.__micraScan = rowScan
+  node._itemState = Object.create(state) as StateRecord
+  bindDataOn(rowScan.on, instance)
+  bindAtEvents(rowScan.atEvents, instance)
+  bindModels(rowScan.model, instance)
+  return node
+}
+
 // ── Keyed diff ────────────────────────────────────────────────────────────────
 
 function renderKeyed<S extends StateRecord>(
@@ -121,28 +155,8 @@ function renderKeyed<S extends StateRecord>(
     let node = keyMap.get(key) as MicraElement | undefined
 
     if (!node) {
-      // Clone template and wrap multi-root fragments in a display:contents element
-      const frag = tmpl.content.cloneNode(true) as DocumentFragment
-      if (frag.childNodes.length === 1) {
-        node = frag.firstElementChild as MicraElement
-      } else {
-        node = document.createElement('micra-each-item') as MicraElement
-        node.style.display = 'contents'
-        node.append(frag)
-      }
-      node.__micraKey = key
+      node = createRowNode(tmpl, state, instance)
       keyMap.set(key, node)
-      // Bind data-on / @event / data-model listeners once per row node.
-      // Scan the row, cache the scan on the node for future re-renders.
-      const rowScan = scanComponent(node)
-      node.__micraScan = rowScan
-      bindDataOn(rowScan.on, instance)
-      bindAtEvents(rowScan.atEvents, instance)
-      bindModels(rowScan.model, instance)
-      // itemState is created once per node and reused across renders.
-      // item / index / $index are mutated in place each render — avoids
-      // Object.create + assign on every cycle and lets safeWrapCache hit.
-      node._itemState = Object.create(state) as StateRecord
     } else if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === index) {
       // Item reference and index are unchanged, and no other state key changed
       // this cycle — the DOM already reflects the latest values. Skip re-render.
@@ -162,7 +176,7 @@ function renderKeyed<S extends StateRecord>(
     // Use the cached scan if present (created above on first sight of this key);
     // older paths may pass a node we haven't scanned yet.
     const rowScan = node.__micraScan ?? (node.__micraScan = scanComponent(node))
-    applyDirectives(rowScan, itemState, rawState, instance)
+    applyDirectives(rowScan, itemState, rawState)
     nextNodes.push(node)
   }
 
@@ -240,8 +254,14 @@ function reorderKeyed(nextNodes: MicraElement[], prevList: MicraElement[], marke
   }
 }
 
-// ── Non-keyed (full re-render) ─────────────────────────────────────────────────
+// ── Non-keyed (positional reuse) ──────────────────────────────────────────────
 
+/**
+ * Diff a non-keyed list by length: reuse the first min(prev, next) DOM nodes,
+ * remove the tail when the list shrinks, clone fresh rows for the growth delta.
+ * Multi-root template rows are wrapped in `<micra-each-item style="display:contents">`
+ * — same as keyed mode — so the reused list is one DOM node per row.
+ */
 function renderNoKey<S extends StateRecord>(
   tmpl: MicraTemplate,
   items: StateRecord[],
@@ -249,27 +269,57 @@ function renderNoKey<S extends StateRecord>(
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
+  canSkipUnchanged: boolean,
 ): void {
-  tmpl.__micraList.forEach(n => n.remove())
-  tmpl.__micraList = []
+  const prevList = tmpl.__micraList
+  const prevLen = prevList.length
+  const nextLen = items.length
+  const reuseLen = nextLen < prevLen ? nextLen : prevLen
+  const nextList: MicraElement[] = new Array(nextLen)
 
-  const frag = document.createDocumentFragment()
-  for (const [index, item] of items.entries()) {
-    const clone = tmpl.content.cloneNode(true) as DocumentFragment
-    const itemState = Object.assign(
-      Object.create(state) as StateRecord,
-      { item, index, $index: index },
-    )
-    // Fresh clone each render → fresh scan each render (uncached).
-    const fragScan = scanFragment(clone)
-    applyDirectives(fragScan, itemState, rawState, instance)
-    bindDataOn(fragScan.on, instance)
-    bindAtEvents(fragScan.atEvents, instance)
-    bindModels(fragScan.model, instance)
-
-    const nodes = Array.from(clone.childNodes) as MicraElement[]
-    nodes.forEach(n => { n.__micraEach = true; frag.append(n) })
-    tmpl.__micraList.push(...nodes)
+  // 1. Reuse [0, reuseLen): refresh itemState, re-apply directives in place.
+  for (let i = 0; i < reuseLen; i++) {
+    const node = prevList[i]!
+    const item = items[i]!
+    if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === i) {
+      nextList[i] = node
+      continue
+    }
+    node.__micraItem = item
+    node.__micraIndex = i
+    const itemState = node._itemState!
+    itemState.item = item
+    itemState.index = i
+    itemState.$index = i
+    applyDirectives(node.__micraScan!, itemState, rawState)
+    nextList[i] = node
   }
-  marker.after(frag)
+
+  // 2. Shrink: remove tail nodes [nextLen, prevLen).
+  for (let i = nextLen; i < prevLen; i++) {
+    prevList[i]!.remove()
+  }
+
+  // 3. Grow: clone and attach fresh rows for [prevLen, nextLen).
+  if (nextLen > prevLen) {
+    const frag = document.createDocumentFragment()
+    for (let i = prevLen; i < nextLen; i++) {
+      const node = createRowNode(tmpl, state, instance)
+      const item = items[i]!
+      const itemState = node._itemState!
+      itemState.item = item
+      itemState.index = i
+      itemState.$index = i
+      node.__micraItem = item
+      node.__micraIndex = i
+      applyDirectives(node.__micraScan!, itemState, rawState)
+      nextList[i] = node
+      frag.append(node)
+    }
+    // Insert after the last reused node, or the marker if the list was empty.
+    const anchor: ChildNode = prevLen > 0 ? nextList[prevLen - 1]! : marker
+    anchor.after(frag)
+  }
+
+  tmpl.__micraList = nextList
 }