micra.js 2.1.0 → 2.2.1

package/llms.txt

@@ -0,0 +1,148 @@
+# Micra.js
+
+> Lightweight reactive TypeScript framework for server-rendered apps and small SaaS frontends. ~5 KB gzip. No build step required.
+>
+> **For LLM code generation:** read the expanded version at https://github.com/denisfl/micra.js/blob/master/llms-full.txt — it includes 10 full inline recipes and an anti-pattern reference. The recipes are the canonical answers to common requests like "build a todo app" or "build a search-with-debounce".
+
+## When to use Micra.js instead of React/Vue
+
+- You have a server-rendered page (Laravel, Rails, Django, etc.) and need a small amount of reactivity
+- Bundle size matters (~5 KB gzip vs ~45 KB React)
+- You don't need a full SPA or client-side routing
+- You want to drop a `<script>` tag and go
+- You need reactive directives on existing HTML without rewriting templates
+
+## Install
+
+```bash
+npm install micra.js
+```
+
+```ts
+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>
+```
+
+This exposes a global `Micra` object.
+
+> **CDN choice matters for AI sandboxes.** Use `cdn.jsdelivr.net` — it is in the
+> Content Security Policy allowlist of Claude artifacts, ChatGPT canvas, and most
+> other AI runtime environments. `unpkg.com` is NOT in those allowlists and will
+> fail to load. jsDelivr auto-mirrors every npm package.
+
+## Core pattern
+
+```html
+<div data-component="counter">
+  <span data-text="count"></span>
+  <button @click="increment">+</button>
+</div>
+```
+
+```js
+Micra.define('counter', {
+  state: { count: 0 },
+  increment() { this.state.count++ },
+})
+
+Micra.start()
+```
+
+## Directives
+
+| Directive        | Example                              | Description                    |
+|------------------|--------------------------------------|--------------------------------|
+| `data-text`      | `data-text="name"`                   | Set `textContent`              |
+| `data-html`      | `data-html="content"`                | Set `innerHTML`                |
+| `data-if`        | `data-if="count > 0"`                | Mount/**unmount** from DOM     |
+| `data-show`      | `data-show="loaded"`                 | Toggle `style.display` only    |
+| `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"`    | Keyed list rendering           |
+| `data-ref`       | `data-ref="chart"`                   | DOM ref via `this.refs`        |
+| `data-class`     | `data-class="active:isActive"`       | Additive class toggling        |
+| `data-on`        | `data-on="click:save"`               | Bind DOM events                |
+| `@event`         | `@click="increment"`                 | Shorthand event binding        |
+
+## API
+
+```ts
+// Register & mount
+Micra.define(name, definition)
+Micra.mount(selector, definition)
+Micra.start(root?)          // scans DOM for [data-component] and mounts all
+
+// Event bus
+Micra.on(event, handler)
+Micra.emit(event, payload?)
+Micra.off(event, handler)
+
+// DevTools
+Micra.instances()           // ReadonlyMap of live components
+Micra.registry()            // ReadonlyMap of registered definitions
+Micra.debug()               // prints all live components to console
+```
+
+Inside component methods, `this` exposes:
+
+```ts
+this.$el        // root HTMLElement
+this.state      // reactive state proxy
+this.refs       // { [name]: HTMLElement } from data-ref
+this.render()   // force re-render
+this.destroy()  // unmount
+this.prop(name, default?)   // read data-* attributes (SSR props)
+this.fetch(url, options?)   // fetch helper
+this.emit(event, payload?)  // component-scoped event emit
+this.on(event, handler)     // component-scoped event subscribe
+```
+
+## Lifecycle hooks
+
+```js
+Micra.define('app', {
+  state: {},
+  onCreate() { /* mounted, refs available */ },
+  onDestroy() { /* cleanup */ },
+})
+```
+
+## Rules for code generation
+
+**Rule 0 — Artifact type override.** When working inside Claude artifacts, ChatGPT
+canvas, v0, Replit AI, or similar "framework-aware" runtimes: those tools default
+to React. When Micra.js is the requested library, **switch the artifact/canvas type
+to plain HTML** (Claude: `application/vnd.ant.html`). Do NOT translate Micra recipes
+into React "because the artifact is React" — change the artifact type instead.
+Micra is a standalone-HTML library; React artifacts cannot host it.
+
+When generating Micra.js code, DO NOT:
+
+1. Use `getElementById`/`querySelector`/`innerHTML` for component output. Lists go through `<template data-each>` with `data-key`.
+2. Store derived values (counts, totals, filtered subsets) as state fields. They must be methods called from directives.
+3. Use `addEventListener` inside methods — it leaks past `destroy()`. Use `@event` / `data-on`.
+4. Call `this.renderList()` / `this.refresh()` / `this.update()` after mutations — Micra batches a microtask render.
+5. Write `state.user.name = x` — shallow proxy. Replace top-level: `state.user = {...state.user, name: x}`.
+6. Use `@keydown.enter` — branch on `e.key === 'Enter'` in the method.
+7. Use `data-model="filters.search"` — writes literal flat key, not nested. Keep models top-level.
+
+Full anti-pattern list with side-by-side examples: [docs/llm-guide.md](https://github.com/denisfl/micra.js/blob/master/docs/llm-guide.md#anti-patterns-llms-gravitate-to-do-not)
+
+## Docs
+
+- LLM expanded context (read first for code generation): https://github.com/denisfl/micra.js/blob/master/llms-full.txt
+- Full LLM guide: https://github.com/denisfl/micra.js/blob/master/docs/llm-guide.md
+- Recipes (canonical full-app examples): https://github.com/denisfl/micra.js/tree/master/docs/recipes
+- Live demo docs: https://denisfl.github.io/micra.js/
+- Getting started: https://github.com/denisfl/micra.js/blob/master/docs/getting-started.md
+- Directives: https://github.com/denisfl/micra.js/blob/master/docs/directives.md
+- API reference: https://github.com/denisfl/micra.js/blob/master/docs/api-reference.md
+- Examples: https://github.com/denisfl/micra.js/blob/master/docs/examples.md
+- SSR: https://github.com/denisfl/micra.js/blob/master/docs/ssr.md
+- npm: https://www.npmjs.com/package/micra.js
+- GitHub: https://github.com/denisfl/micra.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micra.js",
-  "version": "2.1.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",
@@ -16,7 +16,12 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "scripts": {
     "build": "node build.mjs",
@@ -24,7 +29,10 @@
     "dev": "node build.mjs --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "docs:sync": "rm -rf site/dist && mkdir -p site/dist && cp -R dist/* site/dist/",
+    "docs:build": "npm run build && npm run docs:sync",
+    "docs:dev": "npm run docs:sync && npx serve -p 4321 site"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.7",

package/src/core/mount.ts

@@ -15,21 +15,24 @@
 import type {
   ComponentDefinition,
   ComponentInstance,
+  ComponentMethods,
   EventHandler,
   InternalInstance,
   MicraElement,
+
   StateRecord,
   UnsubFn,
-} from '../types'
-import { warn } from '../utils/expr'
-import { micraFetch } from '../utils/fetch'
-import { on as busOn, emit as busEmit } from '../core/bus'
-import { createReactiveState, createScheduler } from '../core/reactive'
-import { applyDirectives, validateDirectives } from '../dom/directives'
-import { renderList } from '../dom/each'
-import { bindDataOn, bindAtEvents, bindModels } from '../dom/events'
-import { collectRefs } from '../dom/refs'
-import { _instances } from '../core/registry'
+} from "../types";
+import { warn } from "../utils/expr";
+import { micraFetch } from "../utils/fetch";
+import { on as busOn, emit as busEmit } from "../core/bus";
+import { createReactiveState, createScheduler } from "../core/reactive";
+import { applyDirectives, validateDirectives } from "../dom/directives";
+import { renderList } from "../dom/each";
+import { bindDataOn, bindAtEvents, bindModels } from "../dom/events";
+import { collectRefs } from "../dom/refs";
+import { scanComponent } from "../dom/scan";
+import { _instances } from "../core/registry";
 
 /**
  * Mount a component definition onto a DOM element.
@@ -37,64 +40,82 @@ import { _instances } from '../core/registry'
  *
  * 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 function mount<S extends StateRecord>(
+export function mount<S extends StateRecord, M>(
   selector: string | HTMLElement,
-  definition: ComponentDefinition<S>,
-): ComponentInstance<S> | null {
+  definition: ComponentDefinition<S, M>,
+): ComponentInstance<S, M> | null {
   const root =
-    typeof selector === 'string'
+    typeof selector === "string"
       ? document.querySelector<HTMLElement>(selector)
-      : selector
+      : selector;
 
   if (!root) {
-    warn(`"${selector}" not found`)
-    return null
+    warn(`"${selector}" not found`);
+    return null;
   }
 
   // Already mounted — return existing instance without re-mounting
-  if (_instances.has(root)) return _instances.get(root) as ComponentInstance<S>
+  if (_instances.has(root))
+    return _instances.get(root) as unknown as ComponentInstance<S, M>;
 
-  const rawState: StateRecord = { ...(definition.state ?? {}) }
-  const instance = { $el: root, refs: {} } as InternalInstance<S>
+  const rawState: StateRecord = { ...(definition.state ?? {}) };
+  const instance = { $el: root, refs: {} } as InternalInstance<S>;
 
   // Copy user-defined methods from definition to instance
-  for (const [key, val] of Object.entries(definition as Record<string, unknown>)) {
-    if (key === 'state' || key === 'onCreate' || key === 'onDestroy') continue
-    if (typeof val === 'function') instance[key] = val
+  for (const [key, val] of Object.entries(
+    definition as Record<string, unknown>,
+  )) {
+    if (key === "state" || key === "onCreate" || key === "onDestroy") continue;
+    if (typeof val === "function") instance[key] = val;
   }
 
   // ── prop() ────────────────────────────────────────────────────────────────
   // Read data-* attributes from the root element with auto-cast.
   instance.prop = function <T>(name: string, defaultVal?: T): T | undefined {
-    const val = root.dataset[name]
-    if (val === undefined) return defaultVal
-    if (val === 'true')  return true  as unknown as T
-    if (val === 'false') return false as unknown as T
-    if (val !== '' && !isNaN(Number(val))) return Number(val) as unknown as T
-    return val as unknown as T
-  } as ComponentInstance<S>['prop']
+    const val = root.dataset[name];
+    if (val === undefined) return defaultVal;
+    if (val === "true") return true as unknown as T;
+    if (val === "false") return false as unknown as T;
+    if (val !== "" && !isNaN(Number(val))) return Number(val) as unknown as T;
+    return val as unknown as T;
+  } as ComponentInstance<S>["prop"];
 
   // ── fetch(), emit(), on() ─────────────────────────────────────────────────
-  instance.fetch = micraFetch
-  instance.emit  = busEmit
-
-  instance.on = <T = unknown>(event: string, handler: EventHandler<T>): UnsubFn => {
-    const unsub = busOn(event, handler)
-    if (!instance.__micraSubs) instance.__micraSubs = []
-    instance.__micraSubs.push(unsub)
-    return unsub
-  }
+  instance.fetch = micraFetch;
+  instance.emit = busEmit;
+
+  instance.on = <T = unknown>(
+    event: string,
+    handler: EventHandler<T>,
+  ): UnsubFn => {
+    const unsub = busOn(event, handler);
+    if (!instance.__micraSubs) instance.__micraSubs = [];
+    instance.__micraSubs.push(unsub);
+    return unsub;
+  };
 
   // ── Render ────────────────────────────────────────────────────────────────
-  let isRendering = false
-  const schedule  = createScheduler(() => instance.render())
-  instance.state  = createReactiveState(rawState, schedule) as S
+  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, (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.
@@ -106,90 +127,106 @@ export function mount<S extends StateRecord>(
   // Both traps reject Object.prototype names ('constructor', 'toString', ...) —
   // accessing them via a directive expression returns undefined instead of
   // leaking the prototype.
-  const boundMethods = new Map<string, Function>()
+  const boundMethods = new Map<string, Function>();
   const exprState = new Proxy(rawState, {
     get(target, key: string) {
-      if (Object.prototype.hasOwnProperty.call(target, key)) return target[key]
-      if (Object.prototype.hasOwnProperty.call(instance, key) &&
-          typeof instance[key] === 'function') {
-        const cached = boundMethods.get(key)
-        if (cached) return cached
-        const bound = (instance[key] as Function).bind(instance)
-        boundMethods.set(key, bound)
-        return bound
+      if (Object.prototype.hasOwnProperty.call(target, key)) return target[key];
+      if (
+        Object.prototype.hasOwnProperty.call(instance, key) &&
+        typeof instance[key] === "function"
+      ) {
+        const cached = boundMethods.get(key);
+        if (cached) return cached;
+        const bound = (instance[key] as Function).bind(instance);
+        boundMethods.set(key, bound);
+        return bound;
       }
-      return undefined
+      return undefined;
     },
     has(target, key: string) {
-      if (typeof key !== 'string') return false
-      if (Object.prototype.hasOwnProperty.call(target, key)) return true
-      return Object.prototype.hasOwnProperty.call(instance, key) &&
-             typeof instance[key] === 'function'
+      if (typeof key !== "string") return false;
+      if (Object.prototype.hasOwnProperty.call(target, key)) return true;
+      return (
+        Object.prototype.hasOwnProperty.call(instance, key) &&
+        typeof instance[key] === "function"
+      );
     },
-  })
+  });
 
-  let warnedReentry = false
+  let warnedReentry = false;
   instance.render = function () {
-    if (instance.__micraDestroyed) return
+    if (instance.__micraDestroyed) return;
+    const triggerKey = _triggerKey;
+    _triggerKey = null;
     if (isRendering) {
       if (!warnedReentry) {
-        warn('render() re-entry detected — mutation inside a directive expression is ignored. Move state writes to a method.')
-        warnedReentry = true
+        warn(
+          "render() re-entry detected — mutation inside a directive expression is ignored. Move state writes to a method.",
+        );
+        warnedReentry = true;
       }
-      return
+      return;
     }
-    isRendering = true
+    isRendering = true;
     try {
-      applyDirectives(root, exprState, rawState, instance)
-      renderList(root, exprState, rawState, instance)
-      bindDataOn(root, instance)
-      bindAtEvents(root, instance)
-      bindModels(root, instance)
-      collectRefs(root, instance)
+      // Single-pass scan, cached on the root for re-renders. Replaces what
+      // used to be ~10 separate querySelectorAll passes per render.
+      const mRoot = root as MicraElement;
+      const scan =
+        mRoot.__micraScan ?? (mRoot.__micraScan = scanComponent(root));
+      applyDirectives(scan, exprState, rawState, instance);
+      renderList(scan.each, exprState, rawState, instance, triggerKey);
+      bindDataOn(scan.on, instance);
+      bindAtEvents(scan.atEvents, instance);
+      bindModels(scan.model, instance);
+      collectRefs(scan.refs, instance);
     } finally {
-      isRendering = false
+      isRendering = false;
     }
-  }
+  };
 
   // ── Destroy ───────────────────────────────────────────────────────────────
   instance.destroy = function () {
-    if (instance.__micraDestroyed) return
-    instance.__micraDestroyed = true
+    if (instance.__micraDestroyed) return;
+    instance.__micraDestroyed = true;
 
     // Remove every DOM listener attached by bindDataOn / bindAtEvents / bindModels.
-    instance.__micraListeners?.forEach(({ el, type, fn }) => el.removeEventListener(type, fn))
-    instance.__micraListeners = []
+    instance.__micraListeners?.forEach(({ el, type, fn }) =>
+      el.removeEventListener(type, fn),
+    );
+    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
-      delete m.__micraAtBound
-      delete m.__micraModel
-      delete m.__micraCache
-    }
-    clearFlags(root)
-    root.querySelectorAll('*').forEach(clearFlags)
-
-    instance.__micraSubs?.forEach(unsub => unsub())
-    instance.__micraSubs = []
-
-    if (typeof (definition as Record<string, unknown>).onDestroy === 'function')
-      (definition.onDestroy as () => void).call(instance)
-    _instances.delete(root)
-  }
+      const m = el as MicraElement;
+      delete m.__micraEvents;
+      delete m.__micraAtBound;
+      delete m.__micraModel;
+      delete m.__micraScan;
+    };
+    clearFlags(root);
+    root.querySelectorAll("*").forEach(clearFlags);
+
+    instance.__micraSubs?.forEach((unsub) => unsub());
+    instance.__micraSubs = [];
+
+    if (typeof (definition as Record<string, unknown>).onDestroy === "function")
+      (definition.onDestroy as () => void).call(instance);
+    _instances.delete(root);
+  };
 
   // ── Bootstrap ─────────────────────────────────────────────────────────────
-  _instances.set(root, instance as InternalInstance)
-  instance.render()
+  _instances.set(root, instance as InternalInstance);
+  instance.render();
 
-  // Validate directive usage and emit dev warnings
-  validateDirectives(root)
+  // Validate directive usage and emit dev warnings — reuses the same scan.
+  const mRoot = root as MicraElement;
+  if (mRoot.__micraScan) validateDirectives(mRoot.__micraScan);
 
-  if (typeof (definition as Record<string, unknown>).onCreate === 'function')
+  if (typeof (definition as Record<string, unknown>).onCreate === "function")
     Promise.resolve().then(() =>
       (definition.onCreate as () => void | Promise<void>).call(instance),
-    )
+    );
 
-  return instance
+  return instance as unknown as ComponentInstance<S, M>;
 }

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/core/registry.ts

@@ -12,6 +12,7 @@
 import type {
   ComponentDefinition,
   ComponentInstance,
+  ComponentMethods,
   InternalInstance,
   StateRecord,
 } from '../types'
@@ -27,19 +28,28 @@ export const _instances = new Map<HTMLElement, InternalInstance>()
 /**
  * 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 function define<S extends StateRecord>(
+export function define<S extends StateRecord, M>(
   name: string,
-  definition: ComponentDefinition<S>,
+  definition: ComponentDefinition<S, M>,
 ): void {
-  _registry.set(name, definition as ComponentDefinition)
+  _registry.set(name, definition as unknown as ComponentDefinition)
 }
 
 /**
  * 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.
  *
@@ -50,9 +60,9 @@ export function define<S extends StateRecord>(
  * })
  * Micra.define('counter', counter)
  */
-export function defineComponent<S extends StateRecord>(
-  definition: ComponentDefinition<S>,
-): ComponentDefinition<S> {
+export function defineComponent<S extends StateRecord, M>(
+  definition: ComponentDefinition<S, M>,
+): ComponentDefinition<S, M> {
   return definition
 }
 
@@ -61,7 +71,7 @@ export function defineComponent<S extends StateRecord>(
  * Useful for DevTools / debugging.
  */
 export function instances(): ReadonlyMap<HTMLElement, ComponentInstance> {
-  return _instances
+  return _instances as unknown as ReadonlyMap<HTMLElement, ComponentInstance>
 }
 
 /**