micra.js 2.3.0 → 2.3.2

package/CHANGELOG.md

@@ -4,6 +4,88 @@ 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.3.2] — 2026-06-10
+
+### Fixed — `data-each` row root detection
+
+- **A pretty-printed template with one root element is no longer wrapped
+  in `<micra-each-item>`.** Single-root detection used
+  `frag.childNodes.length === 1`, which counts whitespace text nodes — so
+  `<template data-each>\n  <tr>…</tr>\n</template>` (three child nodes:
+  text, element, text) took the multi-root path and wrapped every row.
+  For table rows this put invalid content inside `<tbody>` and broke
+  `tbody > tr` child selectors.
+- Exact semantics of the new check (top-level child nodes only, O(1)-ish
+  per row): plain whitespace (space, `\t`, `\n`, `\f`, `\r`) beside the
+  single element is ignored; **NBSP and any other visible character keep
+  the wrapper** (they render, so they must survive); **comment nodes
+  beside the root are dropped** — they don't render and aren't worth
+  invalid wrapper content inside `<tbody>`.
+- Found by the official `isKeyed` compliance check while preparing the
+  [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark)
+  submission — Micra now passes it for run / remove / swap.
+- Affects both keyed and non-keyed paths (shared `createRowNode`).
+- Internal: `ALLOWED_GLOBALS` in the expression evaluator is now built
+  from a split string (identical semantics, smaller minified output).
+  Bundle: **5.5 KB gzip** (5632 bytes — exactly at the size guard; the
+  next feature pays for itself or raises the limit consciously).
+
+### Internal — LLM-benchmark harness hardening (no library impact)
+
+Post-review fixes to `bench-llm/` so published numbers are trustworthy:
+windows now close even when an assertion fails (stray timers no longer
+misattribute errors to the next generation); errors aggregate across all
+pages of multi-scenario tasks; quoted `>` inside template attributes no
+longer mangles pages; ESM micra imports are rewritten to UMD bindings
+instead of being dropped; the injected bundle is marked with
+`data-harness-bundle` (single source of truth for loader and lint);
+`Object.groupBy` replaced for Node 20 compatibility; `--only` no longer
+overwrites aggregate results; the `@next` publish guard distinguishes
+"version not published" from registry/network failures.
+
+## [2.3.1] — 2026-05-30
+
+### Performance
+
+- **Batch scheduler now uses `queueMicrotask` instead of
+  `Promise.resolve().then(...)`.** Each render batch enqueues a single
+  microtask instead of allocating a Promise plus a reaction job, and the
+  flush callback is hoisted out of the hot path so it isn't re-created on
+  every `schedule()` call. Behaviour is identical — same microtask timing,
+  same write-collapsing. No public-API change.
+
+### Internal — dead-code removal
+
+- Removed the `src/dom/query.ts` module (`queryAll` / `queryOwn` /
+  `queryOwnAll` / `filterOwn`). It had no importers since the 2.2.0
+  single-pass scan replaced per-render `querySelectorAll` calls with one
+  `TreeWalker` traversal — esbuild already tree-shook it out of the
+  bundle, so this is a source-only cleanup.
+- Removed two dead bookkeeping writes: `node.__micraEach` and
+  `node.__micraKey` were assigned during list rendering but never read
+  (keys live in the keyed-diff `Map`; the no-key path doesn't tag rows).
+  Dropped the matching fields from `MicraElement`.
+- Dropped the unused `instance` parameter from `applyDirectives` — it was
+  never referenced in the body.
+
+### Docs
+
+- New [Rails + Micra recipe](https://github.com/denisfl/micra.js/blob/master/docs/recipes/rails.md)
+  (`docs/recipes/rails.md` + a site page): manual importmap integration,
+  the `micra-rails` gem with its caveats, a Tasks board demonstrating SSR
+  props / CSRF-attached `this.fetch` / cross-component bus, and the Turbo
+  Drive / Streams / Frames mount-and-cleanup story.
+- README gains a **TypeScript** section spelling out what's checked
+  end-to-end (state, methods, event payloads) versus what isn't (the
+  expression strings inside `data-*` attributes).
+- Landing page gains **Speed** (cross-library benchmark cards) and **AI
+  sandboxes** (copy-the-LLM-prompt) sections.
+
+### Bundle
+
+- **5.5 KB gzip** (5582 bytes) — a few bytes lighter than 2.3.0 after the
+  dead-code removal.
+
 ## [2.3.0] — 2026-05-30
 
 ### TypeScript — type-safe event bus

package/README.md

@@ -1,7 +1,24 @@
 # Micra.js
 
+[![CI](https://github.com/denisfl/micra.js/actions/workflows/ci.yml/badge.svg)](https://github.com/denisfl/micra.js/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/micra.js)](https://www.npmjs.com/package/micra.js)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/micra.js?label=gzip)](https://bundlephobia.com/package/micra.js)
+[![types included](https://img.shields.io/badge/types-included-blue)](./dist/index.d.ts)
+[![license MIT](https://img.shields.io/npm/l/micra.js)](./LICENSE)
+
 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.
 
+## Project status
+
+- **Stable, SemVer-disciplined.** Breaking changes only in majors; every
+  release documented in [CHANGELOG.md](./CHANGELOG.md) with migration notes.
+- **Tested.** 255 tests across 14 suites run on every push and before every
+  npm publish; the build fails if the bundle exceeds **5.5 KB gzip**.
+- **Typed.** Ships its own `.d.ts` — state, methods, and event-bus payloads
+  are checked end-to-end (see [TypeScript](#typescript)).
+- **Security policy.** See [SECURITY.md](./SECURITY.md) — private reporting,
+  72-hour acknowledgement, supported-versions table.
+
 ## When to use Micra.js
 
 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.
@@ -71,6 +88,48 @@ npm install micra.js
 import * as Micra from "micra.js";
 ```
 
+### TypeScript
+
+The npm package ships its own `dist/index.d.ts` — no `@types/micra.js` package
+needed. Inside every method body and lifecycle hook, both `this.state.X` and
+`this.someMethod()` are fully checked at the call site (both `state` and the
+method set are inferred from the literal you pass to `Micra.define`).
+
+```ts
+import * as Micra from "micra.js";
+
+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--; },
+});
+
+// Type-safe event bus via declaration merging
+declare module "micra.js" {
+  interface MicraEvents {
+    "cart:updated": { count: number };
+    "modal:close":  void;
+  }
+}
+
+Micra.emit("cart:updated", { count: 3 });    // ✓
+Micra.emit("cart:updated", { count: "3" });  // ✗ type error
+Micra.emit("modal:close");                   // ✓ void → no args
+```
+
+**What's checked:** imports, state shape, method names, event-bus payloads,
+lifecycle hooks, refs, `Micra.mount()` return type.
+
+**What's not:** the expression strings inside `data-text="…"` / `@click="…"`
+attributes — those are plain HTML to the IDE and validated only at mount
+time. Same trade-off as Alpine.js `x-*` and petite-vue `v-*`; the
+alternatives are JSX or a single-file-component compiler, neither of which
+Micra ships.
+
 ## Basic usage
 
 A counter mounted automatically from `data-component`:
@@ -183,6 +242,7 @@ this.on(event, handler)
   - [Todo app](./docs/recipes/todo-app.md)
   - [Server-sent events (SSE)](./docs/recipes/sse.md)
   - [htmx bridge](./docs/recipes/htmx.md)
+  - [Rails + Micra](./docs/recipes/rails.md)
 
 ## Code generation with LLMs
 

package/dist/core/reactive.d.ts

@@ -23,6 +23,10 @@ export declare function createReactiveState<S extends StateRecord>(obj: S, sched
  * 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

package/dist/dom/directives.d.ts

@@ -11,7 +11,7 @@
  *
  * Important: this module does NOT handle data-each — see dom/each.ts.
  */
-import type { InternalInstance, ScanIndex, StateRecord } from '../types';
+import type { ScanIndex, StateRecord } from '../types';
 import { warn } from '../utils/expr';
 /**
  * Apply all non-each directives to a component subtree.
@@ -23,7 +23,7 @@ import { warn } from '../utils/expr';
  * @param state    - Expression state (may include item/index for each rows)
  * @param rawState - Raw (non-proxy) state for model sync
  */
-export declare function applyDirectives<S extends StateRecord>(scan: ScanIndex, state: StateRecord, rawState: StateRecord, _instance: InternalInstance<S>): void;
+export declare function applyDirectives(scan: ScanIndex, state: StateRecord, rawState: StateRecord): void;
 /**
  * Validate directive usage and emit dev warnings.
  * Called once after the initial render of a component, with the already-built

package/dist/dom/scan.d.ts

@@ -5,9 +5,9 @@
  * 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.
+ *   - REJECT (skip subtree) on nested [data-component] — a parent component
+ *     never processes directives owned by a nested child. 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 — fresh rows

package/dist/micra.cjs.js

@@ -1,4 +1,4 @@
-/* Micra.js v2.3.0 — https://github.com/micra-js/micra — MIT */
+/* Micra.js v2.3.2 — https://github.com/micra-js/micra — MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -119,23 +119,9 @@ function debug() {
 var exprCache = /* @__PURE__ */ new Map();
 var warnedRuntime = /* @__PURE__ */ new Set();
 var SIMPLE_PATH = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/;
-var ALLOWED_GLOBALS = /* @__PURE__ */ new Set([
-  "Math",
-  "JSON",
-  "Date",
-  "String",
-  "Number",
-  "Boolean",
-  "Array",
-  "Object",
-  "parseInt",
-  "parseFloat",
-  "isNaN",
-  "isFinite",
-  "NaN",
-  "Infinity",
-  "undefined"
-]);
+var ALLOWED_GLOBALS = new Set(
+  "Math,JSON,Date,String,Number,Boolean,Array,Object,parseInt,parseFloat,isNaN,isFinite,NaN,Infinity,undefined".split(",")
+);
 var PARAM_S = "$s";
 var PARAM_SAFE = "$safe";
 var SAFE_OUTER = new Proxy(/* @__PURE__ */ Object.create(null), {
@@ -253,13 +239,14 @@ function createReactiveState(obj, schedule, onKey) {
 }
 function createScheduler(render) {
   let pending = false;
+  const flush = () => {
+    pending = false;
+    render();
+  };
   return function schedule() {
     if (pending) return;
     pending = true;
-    Promise.resolve().then(() => {
-      pending = false;
-      render();
-    });
+    queueMicrotask(flush);
   };
 }
 
@@ -325,7 +312,7 @@ function applyModel(el, key, rawState) {
   const desired = stateVal == null ? "" : String(stateVal);
   if (html.value !== desired) html.value = desired;
 }
-function applyDirectives(scan, state, rawState, _instance) {
+function applyDirectives(scan, state, rawState) {
   for (const b of scan.if) applyIf(b, state);
   for (const b of scan.text) applyText(b.el, b.expr, state);
   for (const b of scan.html) applyHtml(b.el, b.expr, state);
@@ -573,8 +560,13 @@ function renderList(templates, state, rawState, instance, triggerKey) {
 function createRowNode(tmpl, state, instance) {
   const frag = tmpl.content.cloneNode(true);
   let node;
-  if (frag.childNodes.length === 1) {
-    node = frag.firstElementChild;
+  const first = frag.firstElementChild;
+  const single = !!first && !first.nextElementSibling && !Array.prototype.some.call(
+    frag.childNodes,
+    (c) => c.nodeType === 3 && /[^\x00- ]/.test(c.textContent)
+  );
+  if (single) {
+    node = first;
   } else {
     node = document.createElement("micra-each-item");
     node.style.display = "contents";
@@ -608,7 +600,6 @@ function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, inst
     let node = keyMap.get(key);
     if (!node) {
       node = createRowNode(tmpl, state, instance);
-      node.__micraKey = key;
       keyMap.set(key, node);
     } else if (canSkipUnchanged && node.__micraItem === item && node.__micraIndex === index) {
       nextNodes.push(node);
@@ -621,7 +612,7 @@ function renderKeyed(tmpl, items, keyAttr, marker, keyMap, state, rawState, inst
     itemState.index = index;
     itemState.$index = index;
     const rowScan = (_a = node.__micraScan) != null ? _a : node.__micraScan = scanComponent(node);
-    applyDirectives(rowScan, itemState, rawState, instance);
+    applyDirectives(rowScan, itemState, rawState);
     nextNodes.push(node);
   }
   for (const [key, node] of keyMap) {
@@ -706,7 +697,7 @@ function renderNoKey(tmpl, items, marker, state, rawState, instance, canSkipUnch
     itemState.item = item;
     itemState.index = i;
     itemState.$index = i;
-    applyDirectives(node.__micraScan, itemState, rawState, instance);
+    applyDirectives(node.__micraScan, itemState, rawState);
     nextList[i] = node;
   }
   for (let i = nextLen; i < prevLen; i++) {
@@ -721,10 +712,9 @@ function renderNoKey(tmpl, items, marker, state, rawState, instance, canSkipUnch
       itemState.item = item;
       itemState.index = i;
       itemState.$index = i;
-      node.__micraEach = true;
       node.__micraItem = item;
       node.__micraIndex = i;
-      applyDirectives(node.__micraScan, itemState, rawState, instance);
+      applyDirectives(node.__micraScan, itemState, rawState);
       nextList[i] = node;
       frag.append(node);
     }
@@ -823,7 +813,7 @@ function mount(selector, definition) {
     try {
       const mRoot2 = root;
       const scan = (_a2 = mRoot2.__micraScan) != null ? _a2 : mRoot2.__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);