micra.js 2.2.0 → 2.2.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.0
+npm install micra.js@^2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.1/dist/micra.min.js"></script>
 <script>
   Micra.define('search-bar', {
     state: { query: '' },
@@ -569,9 +569,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.0/dist/micra.min.js"></script>
+<script src="https://unpkg.com/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0/dist/micra.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/micra.js@2.2.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.0",
+  "version": "2.2.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",

package/src/core/mount.ts

@@ -19,6 +19,7 @@ import type {
   EventHandler,
   InternalInstance,
   MicraElement,
+
   StateRecord,
   UnsubFn,
 } from "../types";
@@ -107,8 +108,14 @@ export function mount<S extends StateRecord, M>(
 
   // ── Render ────────────────────────────────────────────────────────────────
   let isRendering = false;
+  // Track which state key triggered the current render cycle.
+  // 'MULTIPLE' means more than one key was written before the microtask fired.
+  let _triggerKey: string | null | "MULTIPLE" = null;
   const schedule = createScheduler(() => instance.render());
-  instance.state = createReactiveState(rawState, schedule) as S;
+  instance.state = createReactiveState(rawState, schedule, (key) => {
+    if (_triggerKey === null) _triggerKey = key;
+    else if (_triggerKey !== key) _triggerKey = "MULTIPLE";
+  }) as S;
 
   // Expression state: proxy that falls back to instance methods so expressions
   // like `data-text="formatDate(item.date)"` can call component methods.
@@ -149,6 +156,8 @@ export function mount<S extends StateRecord, M>(
   let warnedReentry = false;
   instance.render = function () {
     if (instance.__micraDestroyed) return;
+    const triggerKey = _triggerKey;
+    _triggerKey = null;
     if (isRendering) {
       if (!warnedReentry) {
         warn(
@@ -166,7 +175,7 @@ export function mount<S extends StateRecord, M>(
       const scan =
         mRoot.__micraScan ?? (mRoot.__micraScan = scanComponent(root));
       applyDirectives(scan, exprState, rawState, instance);
-      renderList(scan.each, exprState, rawState, instance);
+      renderList(scan.each, exprState, rawState, instance, triggerKey);
       bindDataOn(scan.on, instance);
       bindAtEvents(scan.atEvents, instance);
       bindModels(scan.model, instance);
@@ -187,7 +196,7 @@ export function mount<S extends StateRecord, M>(
     );
     instance.__micraListeners = [];
 
-    // Clear per-element flags & cached directive scan so a future re-mount of the same DOM works.
+    // Clear per-element flags & cached scan so a future re-mount of the same DOM works.
     const clearFlags = (el: Element) => {
       const m = el as MicraElement;
       delete m.__micraEvents;

package/src/core/reactive.ts

@@ -20,11 +20,12 @@ import type { StateRecord } from '../types'
  * const state = createReactiveState(raw, render)
  * state.count = 5  // triggers render() in next microtask
  */
-export function createReactiveState<S extends StateRecord>(obj: S, schedule: () => void): S {
+export function createReactiveState<S extends StateRecord>(obj: S, schedule: () => void, onKey?: (key: string) => void): S {
   return new Proxy(obj, {
     set(target, key: string, value: unknown) {
       // Cast through StateRecord — TypeScript cannot write through a generic index
       ;(target as StateRecord)[key] = value
+      onKey?.(key)
       schedule()
       return true
     },

package/src/dom/directives.ts

@@ -36,7 +36,8 @@ function applyText(el: Element, expr: string, state: StateRecord): void {
  * for the full security model.
  */
 function applyHtml(el: Element, expr: string, state: StateRecord): void {
-  el.innerHTML = String(evalExpr(expr, state) ?? '')
+  const html = String(evalExpr(expr, state) ?? '')
+  if (el.innerHTML !== html) el.innerHTML = html
 }
 
 /**
@@ -72,7 +73,9 @@ function applyIf(binding: CachedIfBinding, state: StateRecord): void {
  * data-show — visibility toggle via `style.display`. Element stays in the DOM.
  */
 function applyShow(el: Element, expr: string, state: StateRecord): void {
-  (el as HTMLElement).style.display = evalExpr(expr, state) ? '' : 'none'
+  const desired = evalExpr(expr, state) ? '' : 'none'
+  const htmlEl = el as HTMLElement
+  if (htmlEl.style.display !== desired) htmlEl.style.display = desired
 }
 
 function applyBind(

package/src/dom/each.ts

@@ -30,16 +30,18 @@ import { scanComponent, scanFragment } from './scan'
  * Process all `<template data-each>` elements found by the scanner.
  * Scoped itemState makes `item`, `index`, `$index` available in row expressions.
  *
- * @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)
+ * @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)
+ * @param triggerKey - Which state key triggered this render (null = initial, 'MULTIPLE' = batch)
  */
 export function renderList<S extends StateRecord>(
   templates: Element[],
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
+  triggerKey: string | null | 'MULTIPLE',
 ): void {
   for (const tmplEl of templates) {
     if (tmplEl.tagName !== 'TEMPLATE') continue
@@ -60,10 +62,9 @@ export function renderList<S extends StateRecord>(
 
     const marker = tmpl.__micraMarker
     const keyMap = tmpl.__micraNodes
-    const parent = marker.parentNode
     // The template (and its marker) is currently detached — likely a data-if
     // ancestor unmounted this subtree. Nothing to do until it returns.
-    if (!parent) continue
+    if (!marker.parentNode) continue
 
     // Empty / non-array: clear all rendered rows
     if (!Array.isArray(items)) {
@@ -73,10 +74,16 @@ export function renderList<S extends StateRecord>(
       continue
     }
 
+    // canSkipUnchanged: true when only this list's state key changed — rows
+    // whose item reference and index are both unchanged can skip applyDirectives.
+    const canSkipUnchanged = triggerKey !== null &&
+                             triggerKey !== 'MULTIPLE' &&
+                             triggerKey === itemsExpr
+
     if (keyAttr) {
-      renderKeyed(tmpl, items as StateRecord[], keyAttr, marker, keyMap, parent, state, rawState, instance)
+      renderKeyed(tmpl, items as StateRecord[], keyAttr, marker, keyMap, state, rawState, instance, canSkipUnchanged)
     } else {
-      renderNoKey(tmpl, items as StateRecord[], marker, parent, state, rawState, instance)
+      renderNoKey(tmpl, items as StateRecord[], marker, state, rawState, instance)
     }
   }
 }
@@ -89,10 +96,10 @@ function renderKeyed<S extends StateRecord>(
   keyAttr: string,
   marker: Comment,
   keyMap: Map<unknown, MicraElement>,
-  parent: Node,
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
+  canSkipUnchanged: boolean,
 ): void {
   const nextKeys  = new Set<unknown>()
   const nextNodes: MicraElement[] = []
@@ -132,12 +139,26 @@ function renderKeyed<S extends StateRecord>(
       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.
+      nextNodes.push(node)
+      continue
     }
 
-    const itemState = Object.assign(
-      Object.create(state) as StateRecord,
-      { item, index, $index: index },
-    )
+    node.__micraItem  = item
+    node.__micraIndex = index
+
+    // Reuse the cached itemState, just update the per-row values.
+    const itemState = node._itemState!
+    itemState.item = item
+    itemState.index = index
+    itemState.$index = index
+
     // 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))
@@ -150,23 +171,81 @@ function renderKeyed<S extends StateRecord>(
     if (!nextKeys.has(key)) { node.remove(); keyMap.delete(key) }
   }
 
-  // Insert / reorder nodes after marker (insertBefore is no-op if already in place)
-  let cursor: Node = marker
-  for (const node of nextNodes) {
-    if (cursor.nextSibling !== node) parent.insertBefore(node, cursor.nextSibling)
-    cursor = node
+  const prevList = tmpl.__micraList
+  if (prevList.length === 0) {
+    // First render (or refill after a clear): every node is new and already in
+    // order — batch into one fragment so the DOM takes a single insertion
+    // instead of N anchor.after() calls. Skips LIS entirely.
+    if (nextNodes.length) {
+      const frag = document.createDocumentFragment()
+      for (const node of nextNodes) frag.append(node)
+      marker.after(frag)
+    }
+  } else {
+    // Skip DOM reorder when list order is unchanged (pure JS array compare, no DOM reads).
+    let orderChanged = nextNodes.length !== prevList.length
+    if (!orderChanged) {
+      for (let i = 0; i < nextNodes.length; i++) {
+        if (nextNodes[i] !== prevList[i]) { orderChanged = true; break }
+      }
+    }
+    if (orderChanged) reorderKeyed(nextNodes, prevList, marker)
   }
 
   tmpl.__micraList = nextNodes
 }
 
+// ── Keyed list reorder (LIS) ───────────────────────────────────────────────────
+
+/**
+ * Move DOM nodes to match `nextNodes` order using the minimum number of moves.
+ *
+ * Computes the Longest Increasing Subsequence of each node's position in prevList —
+ * nodes in the LIS keep their place. Only the others are re-inserted via anchor.after().
+ *
+ * Complexity: O(n log n) for LIS, O(k) DOM operations where k = nodes that moved.
+ * For a 2-node swap this means 2 DOM ops instead of n.
+ */
+function reorderKeyed(nextNodes: MicraElement[], prevList: MicraElement[], marker: Comment): void {
+  const prevPos = new Map<MicraElement, number>()
+  for (let i = 0; i < prevList.length; i++) prevPos.set(prevList[i]!, i)
+
+  const n = nextNodes.length
+  const tails: number[] = []     // patience sort: smallest tail at each LIS length
+  const tailIdx: number[] = []   // index into nextNodes for each tail
+  const prev: number[] = new Array(n).fill(-1)
+
+  for (let i = 0; i < n; i++) {
+    const p = prevPos.get(nextNodes[i]!)
+    if (p === undefined) continue  // new node — always moved
+    let lo = 0, hi = tails.length
+    while (lo < hi) { const m = (lo + hi) >> 1; tails[m]! < p ? lo = m + 1 : hi = m }
+    if (lo > 0) prev[i] = tailIdx[lo - 1]!
+    tails[lo] = p
+    tailIdx[lo] = i
+  }
+
+  // Reconstruct stable (non-moving) set from LIS parent chain
+  const stable = new Set<number>()
+  let idx: number = tailIdx[tails.length - 1]!
+  while (idx >= 0) { stable.add(idx); idx = prev[idx]! }
+
+  // Move unstable nodes into position; stable (LIS) nodes serve as anchors
+  let anchor: ChildNode = marker
+  for (let i = 0; i < n; i++) {
+    const node = nextNodes[i]!
+    if (stable.has(i)) { anchor = node; continue }
+    anchor.after(node)
+    anchor = node
+  }
+}
+
 // ── Non-keyed (full re-render) ─────────────────────────────────────────────────
 
 function renderNoKey<S extends StateRecord>(
   tmpl: MicraTemplate,
   items: StateRecord[],
   marker: Comment,
-  parent: Node,
   state: StateRecord,
   rawState: StateRecord,
   instance: InternalInstance<S>,
@@ -192,5 +271,5 @@ function renderNoKey<S extends StateRecord>(
     nodes.forEach(n => { n.__micraEach = true; frag.append(n) })
     tmpl.__micraList.push(...nodes)
   }
-  parent.insertBefore(frag, marker.nextSibling)
+  marker.after(frag)
 }

package/src/dom/refs.ts

@@ -26,6 +26,7 @@ export function collectRefs<S extends StateRecord>(
   els: Element[],
   instance: InternalInstance<S>,
 ): void {
+  if (!els.length) return
   instance.refs = {}
   for (const el of els) {
     const name = (el as MicraElement).dataset['ref']

package/src/types.ts

@@ -149,6 +149,9 @@ export interface MicraElement extends HTMLElement {
   __micraKey?: unknown      // keyed-diff key
   __micraEach?: true        // belongs to a no-key each list
   __micraScan?: ScanIndex   // single-pass scan result (cached after 1st render)
+  __micraItem?: StateRecord  // keyed row: last-rendered item ref (for skip check)
+  __micraIndex?: number      // keyed row: last-rendered index (for skip check)
+  _itemState?: StateRecord  // keyed row: reused itemState (avoids Object.create per render)
 }
 
 /**
@@ -166,7 +169,7 @@ export interface TrackedListener {
 export interface MicraTemplate extends HTMLTemplateElement {
   __micraMarker?: Comment
   __micraNodes: Map<unknown, MicraElement>
-  __micraList: ChildNode[]
+  __micraList: MicraElement[]
   __micraNoKeyWarned?: true
 }
 

package/src/utils/expr.ts

@@ -29,8 +29,15 @@ import type { StateRecord } from '../types'
 
 // LLM NOTE: exprCache is module-level (shared across all components).
 // This is intentional — most apps reuse the same expressions.
-type Compiled = (state: object, safe: object) => unknown
-const exprCache = new Map<string, Compiled>()
+
+// Compiled fn for complex expressions; pre-split parts for simple dot-paths.
+// Storing parts once avoids the SIMPLE_PATH regex test + split on every evalExpr call.
+type CompiledFn = (state: object, safe: object) => unknown
+type CachedEntry =
+  | { kind: 'fn';   fn:    CompiledFn }
+  | { kind: 'path'; parts: string[]   }
+
+const exprCache = new Map<string, CachedEntry>()
 // Expressions whose runtime error we have already warned about. Prevents log spam
 // when the same `data-text="item.naame"` typo fires every render.
 const warnedRuntime = new Set<string>()
@@ -141,32 +148,38 @@ function safeStateHas(state: object, key: PropertyKey): boolean {
  * evalExpr('price * qty', { price: 9.99, qty: 3 })   // → 29.97
  */
 export function evalExpr(expr: string, state: StateRecord): unknown {
+  let cached = exprCache.get(expr)
+
+  if (!cached) {
+    // Determine once whether this is a simple dot-path and cache the result.
+    if (SIMPLE_PATH.test(expr)) {
+      cached = { kind: 'path', parts: expr.split('.') }
+    } else {
+      try {
+        cached = {
+          kind: 'fn',
+          fn: new Function('$s', '$safe', `with($safe){with($s){return (${expr})}}`) as CompiledFn,
+        }
+      } catch {
+        warn(`invalid expression "${expr}"`)
+        cached = { kind: 'fn', fn: () => undefined }
+      }
+    }
+    exprCache.set(expr, cached)
+  }
+
   // Fast-path: simple property access — no Function() needed.
   // Still guarded so bare access to Object.prototype names returns undefined.
-  if (SIMPLE_PATH.test(expr)) {
-    const parts = expr.split('.')
-    if (!safeStateHas(state, parts[0]!)) return undefined
-    return parts.reduce<unknown>((obj, key) =>
-      obj != null ? (obj as StateRecord)[key] : undefined,
+  if (cached.kind === 'path') {
+    if (!safeStateHas(state, cached.parts[0]!)) return undefined
+    return cached.parts.reduce<unknown>(
+      (obj, key) => (obj != null ? (obj as StateRecord)[key] : undefined),
       state,
     )
   }
 
-  if (!exprCache.has(expr)) {
-    try {
-      // Two with() statements: $s wins for state keys; $safe shadows globals.
-      exprCache.set(
-        expr,
-        new Function('$s', '$safe', `with($safe){with($s){return (${expr})}}`) as Compiled,
-      )
-    } catch {
-      warn(`invalid expression "${expr}"`)
-      exprCache.set(expr, () => undefined)
-    }
-  }
-
   try {
-    return exprCache.get(expr)!(safeStateWrap(state), SAFE_OUTER)
+    return cached.fn(safeStateWrap(state), SAFE_OUTER)
   } catch (e) {
     if (!warnedRuntime.has(expr)) {
       warnedRuntime.add(expr)