micra.js 2.2.1 → 2.3.0

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.0
 ```
 
 ```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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/dist/micra.min.js"></script>
 <script>
   Micra.define('search-bar', {
     state: { query: '' },
@@ -533,6 +533,59 @@ 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.0/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`.
+
 ---
 
 # Anti-pattern reference (what LLMs gravitate to — DO NOT)
@@ -569,9 +622,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.0/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.0/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.0/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.0",
   "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;

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,9 @@ 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 = createRowNode(tmpl, state, instance)
       node.__micraKey = key
       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.
@@ -240,8 +255,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 +270,58 @@ 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, instance)
+    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.__micraEach = true
+      node.__micraItem = item
+      node.__micraIndex = i
+      applyDirectives(node.__micraScan!, itemState, rawState, instance)
+      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
 }

package/src/dom/scan.ts

@@ -10,7 +10,8 @@
  *     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.
+ *     its children are processed by each.ts on every render — fresh rows
+ *     are wrapped in a per-row element and scanned via scanComponent.
  *
  * Hot-path notes:
  *   - We read `el.attributes` once and switch by suffix. No allocations per
@@ -166,24 +167,3 @@ export function scanComponent(root: Element): ScanIndex {
   return scan;
 }
 
-/**
- * Scan a DocumentFragment (no-key each clone). Not cached — these fragments
- * are temporary and re-cloned every render.
- */
-export function scanFragment(frag: DocumentFragment): ScanIndex {
-  const scan = emptyScan();
-
-  const walker = document.createTreeWalker(
-    frag,
-    NodeFilter.SHOW_ELEMENT,
-    NESTED_COMPONENT_FILTER,
-  );
-
-  let node: Element | null = walker.nextNode() as Element | null;
-  while (node) {
-    classify(node, scan);
-    node = walker.nextNode() as Element | null;
-  }
-
-  return scan;
-}

package/src/index.ts

@@ -27,6 +27,9 @@ export type {
   StateRecord,
   UnsubFn,
   EventHandler,
+  EventPayload,
+  EmitArgs,
+  MicraEvents,
   FetchOptions,
   ComponentMethods,
   ComponentBuiltins,

package/src/types.ts

@@ -22,6 +22,53 @@ export type UnsubFn = () => void
 /** Event bus handler. Generic `T` types the payload. */
 export type EventHandler<T = unknown> = (payload: T) => void
 
+/**
+ * Type-safe event bus registry. Empty by default — augment it via
+ * declaration merging to type your application's events.
+ *
+ * @example
+ * declare module 'micra.js' {
+ *   interface MicraEvents {
+ *     'cart:updated': { count: number }
+ *     'user:login':   { id: number; name: string }
+ *     'modal:close':  void
+ *   }
+ * }
+ *
+ * Micra.emit('cart:updated', { count: 3 })       // ✓ typed
+ * Micra.emit('cart:updated', { count: '3' })     // ✗ type error
+ * Micra.on('user:login', user => user.id)        // user: { id, name }
+ *
+ * Events not present in the interface fall back to `unknown` payload —
+ * fully backward-compatible with untyped usage.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface MicraEvents {}
+
+/**
+ * Resolves the payload type for an event key. For keys registered in
+ * `MicraEvents` returns the declared payload; for any other string key
+ * returns `unknown` (preserving backward compatibility).
+ */
+export type EventPayload<K extends string> = K extends keyof MicraEvents
+  ? MicraEvents[K]
+  : unknown
+
+/**
+ * Tuple of arguments passed to `emit` after the event name. When the
+ * payload type for a known event includes `undefined` (or the payload is
+ * declared as `void`), the argument is optional. For known events with a
+ * required payload, the argument is required. Unknown events accept any
+ * optional payload (backward compat).
+ */
+export type EmitArgs<K extends string> = K extends keyof MicraEvents
+  ? [MicraEvents[K]] extends [void]
+    ? [payload?: undefined]
+    : undefined extends MicraEvents[K]
+      ? [payload?: MicraEvents[K]]
+      : [payload: MicraEvents[K]]
+  : [payload?: unknown]
+
 /** Options for `this.fetch()`. For GET/HEAD extra keys become query params. */
 export interface FetchOptions {
   method?: string
@@ -71,10 +118,16 @@ export interface ComponentBuiltins<S extends StateRecord = StateRecord> {
   prop<T>(name: string, defaultVal: T): T
   /** Fetch helper: CSRF header, JSON body, query params, typed errors. */
   fetch(url: string, options?: FetchOptions): Promise<unknown>
-  /** Publish an event on the global bus. */
-  emit(event: string, payload?: unknown): void
-  /** Subscribe to the global bus. Subscription is auto-removed on destroy(). */
-  on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn
+  /**
+   * Publish an event on the global bus.
+   * Payload is typed via the `MicraEvents` interface (augmentable).
+   */
+  emit<K extends string>(event: K, ...args: EmitArgs<K>): void
+  /**
+   * Subscribe to the global bus. Subscription is auto-removed on destroy().
+   * Handler payload is typed via the `MicraEvents` interface (augmentable).
+   */
+  on<K extends string>(event: K, handler: (payload: EventPayload<K>) => void): UnsubFn
 }
 
 /**