@ozsarman/clarityjs 0.6.0

package/src/runtime.js

@@ -0,0 +1,1465 @@
+/**
+ * Clarity.js Runtime — Signal-based Reactivity Core
+ *
+ * Designed for AI and humans alike.
+ * Three concepts only: signal, effect, computed.
+ * No magic. No implicit behaviour. Everything is explicit.
+ *
+ * Author: Claude (Anthropic)
+ * Version: 0.1.0
+ */
+
+// ─── Reactive Context ────────────────────────────────────────────────────────
+// The currently executing effect, if any.
+// This is how signals know who is "reading" them.
+let _currentEffect = null;
+let _batchDepth = 0;
+const _pendingEffects = new Set();
+
+// ─── Signal ──────────────────────────────────────────────────────────────────
+/**
+ * Creates a reactive value.
+ *
+ * Usage:
+ *   const count = signal(0)
+ *   count.get()        // read
+ *   count.set(n + 1)   // write
+ *   count.update(n => n + 1)  // update with function
+ *
+ * When a signal is read inside an effect, the effect subscribes
+ * and will re-run whenever the signal changes.
+ */
+export function signal(initialValue) {
+  let _value = initialValue;
+  const _subscribers = new Set();
+
+  const sig = {
+    // Read the value — tracks if inside an effect
+    get() {
+      if (_currentEffect) {
+        _subscribers.add(_currentEffect);
+        _currentEffect._deps.add(sig);
+      }
+      return _value;
+    },
+
+    // Write a new value — notifies all subscribers
+    set(newValue) {
+      if (Object.is(_value, newValue)) return; // no-op if same value
+      _value = newValue;
+      _notify(_subscribers);
+    },
+
+    // Update with a function — sugar for set(fn(get()))
+    update(fn) {
+      sig.set(fn(_value));
+    },
+
+    // Peek without tracking — useful in effects that shouldn't re-run
+    peek() {
+      return _value;
+    },
+
+    // Internal: for debugging and tooling
+    _type: 'signal',
+    _subscribers,
+  };
+
+  return sig;
+}
+
+// ─── Effect ──────────────────────────────────────────────────────────────────
+/**
+ * Runs a function reactively — re-runs whenever its signal dependencies change.
+ *
+ * Usage:
+ *   effect(() => {
+ *     document.title = count.get() + ' items'
+ *   })
+ *
+ * The effect runs immediately, then re-runs when any read signal changes.
+ * Returns a cleanup/dispose function.
+ */
+export function effect(fn) {
+  const _effect = {
+    _fn: fn,
+    _deps: new Set(),
+    _cleanup: null,
+    _type: 'effect',
+    _disposed: false,
+  };
+
+  function run() {
+    if (_effect._disposed) return;
+
+    // Cleanup previous subscriptions
+    _cleanup(_effect);
+
+    // Run with this effect as the current tracker
+    const prev = _currentEffect;
+    _currentEffect = _effect;
+    try {
+      const cleanup = fn();
+      if (typeof cleanup === 'function') {
+        _effect._cleanup = cleanup;
+      }
+    } finally {
+      _currentEffect = prev;
+    }
+  }
+
+  _effect._run = run;
+  run(); // Run immediately
+
+  // Return dispose function
+  return function dispose() {
+    _effect._disposed = true;
+    _cleanup(_effect);
+  };
+}
+
+// ─── Computed ────────────────────────────────────────────────────────────────
+/**
+ * A derived signal — computes a value from other signals.
+ * Lazy: only recomputes when read and dependencies have changed.
+ *
+ * Usage:
+ *   const doubled = computed(() => count.get() * 2)
+ *   doubled.get() // always up to date
+ */
+export function computed(fn) {
+  let _dirty = true;
+  let _value;
+  const _subscribers = new Set();
+
+  const _effect = {
+    _fn: fn,
+    _deps: new Set(),
+    _cleanup: null,
+    _type: 'computed',
+    _disposed: false,
+    _run() {
+      _dirty = true;
+      _notify(_subscribers);
+    },
+  };
+
+  const comp = {
+    get() {
+      // Track who is reading this computed
+      if (_currentEffect) {
+        _subscribers.add(_currentEffect);
+        _currentEffect._deps.add(comp);
+      }
+
+      if (_dirty) {
+        // Recompute
+        _cleanup(_effect);
+        const prev = _currentEffect;
+        _currentEffect = _effect;
+        try {
+          _value = fn();
+          _dirty = false;
+        } finally {
+          _currentEffect = prev;
+        }
+      }
+
+      return _value;
+    },
+
+    peek() {
+      return _value;
+    },
+
+    _type: 'computed',
+    _subscribers,
+  };
+
+  return comp;
+}
+
+// ─── Batch ───────────────────────────────────────────────────────────────────
+/**
+ * Batch multiple signal writes — effects run once after all updates.
+ *
+ * Usage:
+ *   batch(() => {
+ *     firstName.set('Ada')
+ *     lastName.set('Lovelace')
+ *   })
+ *   // name effect runs once, not twice
+ */
+export function batch(fn) {
+  _batchDepth++;
+  try {
+    fn();
+  } finally {
+    _batchDepth--;
+    if (_batchDepth === 0) {
+      // Flush all pending effects
+      const toRun = new Set(_pendingEffects);
+      _pendingEffects.clear();
+      toRun.forEach(e => e._run());
+    }
+  }
+}
+
+// ─── DOM Helpers ─────────────────────────────────────────────────────────────
+// ─── AI Registry ─────────────────────────────────────────────────────────────
+/**
+ * Global registry of all mounted Clarity components.
+ * AI agents can call aiDiscover() to enumerate all live components
+ * and their declared permissions.
+ */
+const _aiRegistry = new Set();
+
+/**
+ * Query the AI contract for a DOM element (or its nearest Clarity ancestor).
+ *
+ * Usage (by an AI agent):
+ *   const contract = aiQuery(document.getElementById('card'));
+ *   contract.snapshot()          // { name: 'Ada', email: '...' }
+ *   contract.act('follow')       // triggers declared action
+ *   contract.forbidden           // ['balance', 'token']
+ */
+export function aiQuery(element) {
+  let el = element;
+  while (el) {
+    if (el.__clarity_ai__) return el.__clarity_ai__;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Discover all mounted Clarity components with AI contracts.
+ *
+ * Usage:
+ *   aiDiscover().forEach(c => console.log(c.component, c.snapshot()))
+ */
+export function aiDiscover() {
+  return [..._aiRegistry].filter(el => el.isConnected && el.__clarity_ai__)
+    .map(el => el.__clarity_ai__);
+}
+
+/**
+ * Mount a Clarity component into a DOM element.
+ *
+ * - Calls component.__clarity_mount__() after DOM insertion (onMount hook)
+ * - Returns an unmount() function that calls __clarity_cleanup__() and removes the node
+ *
+ * Usage:
+ *   const unmount = mount(Counter, document.getElementById('app'))
+ *   unmount() // later: removes component, disposes all effects
+ */
+export function mount(ComponentFn, container, props = {}) {
+  if (!container) throw new Error(`[Clarity] mount: container element not found`);
+  container.innerHTML = '';
+  const el = ComponentFn(props);
+
+  if (!(el instanceof Node)) {
+    console.error('[Clarity] mount: component must return a DOM Node');
+    return () => {};
+  }
+
+  container.appendChild(el);
+
+  // Register in AI discovery registry
+  if (el.__clarity_ai__) _aiRegistry.add(el);
+
+  // Run onMount hooks across the whole inserted subtree (nested components too)
+  _runMountHooks(el);
+
+  // Return unmount function for cleanup
+  return function unmount() {
+    _aiRegistry.delete(el);
+    _runCleanupHooks(el);
+    if (el.parentNode) {
+      el.parentNode.removeChild(el);
+    }
+  };
+}
+
+/**
+ * @internal — invoke __clarity_mount__ on a node and every descendant, once each.
+ * mount() and the pages router call this so nested components' onMount runs.
+ */
+export function _runMountHooks(root) {
+  if (!root) return;
+  const nodes = (typeof root.querySelectorAll === 'function')
+    ? [root, ...root.querySelectorAll('*')]
+    : [root];
+  for (const n of nodes) {
+    if (typeof n.__clarity_mount__ === 'function' && !n.__clarity_mounted__) {
+      n.__clarity_mounted__ = true;
+      if (n.__clarity_ai__) _aiRegistry.add(n);
+      try { n.__clarity_mount__(); } catch (e) { console.error('[Clarity onMount]', e); }
+    }
+  }
+}
+
+/**
+ * @internal — invoke __clarity_cleanup__ on a node and every descendant, once each.
+ */
+export function _runCleanupHooks(root) {
+  if (!root) return;
+  const nodes = (typeof root.querySelectorAll === 'function')
+    ? [root, ...root.querySelectorAll('*')]
+    : [root];
+  for (const n of nodes) {
+    if (typeof n.__clarity_cleanup__ === 'function' && !n.__clarity_cleaned__) {
+      n.__clarity_cleaned__ = true;
+      _aiRegistry.delete(n);
+      try { n.__clarity_cleanup__(); } catch (e) { console.error('[Clarity onCleanup]', e); }
+    }
+  }
+}
+
+/**
+ * Create a DOM element with reactive bindings.
+ * This is what the code generator produces — never write it manually.
+ *
+ * Usage (generated code):
+ *   const el = h('div', { class: 'card' }, [child1, child2])
+ */
+export function h(tag, props = {}, children = []) {
+  const el = document.createElement(tag);
+
+  for (const [key, value] of Object.entries(props)) {
+    if (key.startsWith('on:')) {
+      // Event binding: on:click, on:input, on:change, etc.
+      const eventName = key.slice(3);
+      el.addEventListener(eventName, typeof value === 'function' ? value : () => value);
+    } else if (key === 'class') {
+      // Reactive class
+      if (typeof value === 'function') {
+        effect(() => { el.className = value(); });
+      } else {
+        el.className = value;
+      }
+    } else if (key === 'style' && typeof value === 'object') {
+      // Style object
+      Object.assign(el.style, value);
+    } else if (key.startsWith('bind:')) {
+      // Two-way binding: bind:value, bind:checked
+      const attr = key.slice(5);
+      const sig = value;
+      // Read: update element when signal changes
+      effect(() => { el[attr] = sig.get(); });
+      // Write: update signal when element changes
+      const eventName = attr === 'checked' ? 'change' : 'input';
+      el.addEventListener(eventName, () => {
+        sig.set(attr === 'checked' ? el.checked : el.value);
+      });
+    } else if (key === 'ref') {
+      // Ref: expose the DOM node
+      if (typeof value === 'function') value(el);
+      else if (value && '_type' in value) value.set(el);
+    } else {
+      // Static or reactive attribute
+      if (typeof value === 'function') {
+        effect(() => {
+          const v = value();
+          if (v === false || v === null || v === undefined) {
+            el.removeAttribute(key);
+          } else if (v === true) {
+            el.setAttribute(key, '');
+          } else {
+            el.setAttribute(key, v);
+          }
+        });
+      } else {
+        el.setAttribute(key, value);
+      }
+    }
+  }
+
+  for (const child of children) {
+    appendChild(el, child);
+  }
+
+  return el;
+}
+
+/**
+ * Append a child to an element — handles text, signals, nodes, and arrays.
+ */
+export function appendChild(parent, child) {
+  if (child === null || child === undefined || child === false) return;
+
+  if (Array.isArray(child)) {
+    child.forEach(c => appendChild(parent, c));
+    return;
+  }
+
+  if (child instanceof Node) {
+    parent.appendChild(child);
+    return;
+  }
+
+  if (typeof child === 'object' && child._type === 'signal') {
+    // Reactive text node
+    const textNode = document.createTextNode(String(child.get()));
+    effect(() => { textNode.textContent = String(child.get()); });
+    parent.appendChild(textNode);
+    return;
+  }
+
+  if (typeof child === 'function') {
+    // Reactive content — could return different nodes
+    const anchor = document.createComment('clarity:reactive');
+    parent.appendChild(anchor);
+    let currentNodes = [];
+    effect(() => {
+      const result = child();
+      // Remove old nodes
+      currentNodes.forEach(n => n.parentNode?.removeChild(n));
+      currentNodes = [];
+      // Add new
+      if (result instanceof Node) {
+        anchor.parentNode.insertBefore(result, anchor.nextSibling);
+        currentNodes = [result];
+      } else if (result !== null && result !== undefined && result !== false) {
+        const textNode = document.createTextNode(String(result));
+        anchor.parentNode.insertBefore(textNode, anchor.nextSibling);
+        currentNodes = [textNode];
+      }
+    });
+    return;
+  }
+
+  // Static text
+  parent.appendChild(document.createTextNode(String(child)));
+}
+
+/**
+ * Conditional rendering — like a ternary but for DOM nodes.
+ *
+ * Usage:
+ *   when(() => isLoggedIn.get(), () => h('div', {}, ['Welcome!']), () => h('div', {}, ['Please log in']))
+ */
+export function when(conditionFn, thenFn, elseFn = null) {
+  const anchor = document.createComment('clarity:when');
+
+  // We need a container; return a function that resolves post-mount
+  // In practice, the code generator wraps this in appendChild
+  return () => {
+    const parent = anchor.parentNode;
+    if (!parent) return anchor;
+
+    let currentNode = null;
+    effect(() => {
+      if (currentNode) {
+        parent.removeChild(currentNode);
+        currentNode = null;
+      }
+      if (conditionFn()) {
+        currentNode = thenFn();
+        parent.insertBefore(currentNode, anchor.nextSibling);
+      } else if (elseFn) {
+        currentNode = elseFn();
+        parent.insertBefore(currentNode, anchor.nextSibling);
+      }
+    });
+
+    return anchor;
+  };
+}
+
+/**
+ * Reactive list rendering.
+ *
+ * Usage:
+ *   list(items, item => h('li', {}, [item.name.get()]))
+ */
+export function list(itemsSignal, renderFn, keyFn = (item, i) => i) {
+  const anchor = document.createComment('clarity:list');
+  const nodeMap = new Map();
+
+  return () => {
+    const parent = anchor.parentNode;
+    if (!parent) return anchor;
+
+    effect(() => {
+      const items = itemsSignal.get();
+      const newKeys = items.map(keyFn);
+
+      // Remove nodes no longer in list
+      for (const [key, node] of nodeMap) {
+        if (!newKeys.includes(key)) {
+          parent.removeChild(node);
+          nodeMap.delete(key);
+        }
+      }
+
+      // Insert/reorder nodes
+      let refNode = anchor.nextSibling;
+      for (let i = 0; i < items.length; i++) {
+        const key = keyFn(items[i], i);
+        let node = nodeMap.get(key);
+
+        if (!node) {
+          node = renderFn(items[i], i);
+          nodeMap.set(key, node);
+        }
+
+        if (node !== refNode) {
+          parent.insertBefore(node, refNode);
+        } else {
+          refNode = refNode.nextSibling;
+        }
+      }
+    });
+
+    return anchor;
+  };
+}
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+function _notify(subscribers) {
+  // Snapshot before iterating — subscribers may be removed+re-added during _run()
+  // (e.g. _cleanup removes, then re-read re-adds). Without snapshot, the Set
+  // iterator revisits re-added items causing an infinite loop.
+  const snapshot = [...subscribers];
+  for (const sub of snapshot) {
+    if (_batchDepth > 0) {
+      _pendingEffects.add(sub);
+    } else {
+      sub._run();
+    }
+  }
+}
+
+function _cleanup(eff) {
+  if (eff._cleanup) {
+    eff._cleanup();
+    eff._cleanup = null;
+  }
+  for (const dep of eff._deps) {
+    if (dep._subscribers) dep._subscribers.delete(eff);
+  }
+  eff._deps.clear();
+}
+
+// ─── Lifecycle Cleanup Helper ────────────────────────────────────────────────
+/**
+ * Recursively calls __clarity_cleanup__ on a node and its children.
+ *
+ * Used by <when> and <list> to dispose effect subscriptions when nodes
+ * are removed from the DOM.  Without this, effects keep running even after
+ * the component is gone — a silent memory / CPU leak.
+ *
+ * Handles DocumentFragment by iterating its childNodes before removal,
+ * since fragment.childNodes is live and empties once the fragment is inserted.
+ */
+export function _callCleanup(node) {
+  if (!node) return;
+  if (typeof node.__clarity_cleanup__ === 'function') {
+    node.__clarity_cleanup__();
+  }
+  // DocumentFragment: iterate children (they're moved to DOM on appendChild/insertBefore,
+  // so we check childNodes while they still belong to the fragment)
+  if (node.nodeType === 11 /* DOCUMENT_FRAGMENT_NODE */) {
+    const kids = [...node.childNodes]; // snapshot — live collection mutates on insert
+    kids.forEach(child => _callCleanup(child));
+  }
+}
+
+// ─── Lazy / Suspense ──────────────────────────────────────────────────────────
+//
+// Suspense context stack — the innermost <Suspense> component pushes a context
+// object here.  lazy() components check the top of the stack and register their
+// load-promises with it so <Suspense> knows when all children are loaded.
+const _suspenseStack = [];
+
+/** @internal — used by generated <Suspense> code */
+export function _pushSuspense(ctx) { _suspenseStack.push(ctx); }
+/** @internal */
+export function _popSuspense()     { _suspenseStack.pop(); }
+/** @internal — called by lazy() when inside a <Suspense> boundary */
+export function _registerLazy(promise) {
+  if (_suspenseStack.length > 0) {
+    _suspenseStack[_suspenseStack.length - 1]._pending.push(promise);
+  }
+}
+
+/**
+ * Lazily loads a component from a dynamic import.
+ *
+ * Usage:
+ *   import { lazy } from './clarity-runtime.js'
+ *   const HeavyChart = lazy(() => import('./HeavyChart.clarity'))
+ *
+ *   // In a component render:
+ *   <Suspense fallback="Loading chart…">
+ *     <HeavyChart data={myData} />
+ *   </Suspense>
+ *
+ *   // Or without Suspense (self-managed):
+ *   <HeavyChart data={myData} />   // shows a comment while loading, then swaps in
+ *
+ * The return value is a component function — it can be passed to
+ * <Component is={...} /> for dynamic dispatch too.
+ */
+export function lazy(importFn) {
+  const _loaded  = signal(null);   // null while loading; component fn when ready
+  let   _errored = false;
+
+  // Start loading immediately
+  const _promise = importFn().then(mod => {
+    const comp = mod.default ?? Object.values(mod)[0];
+    // Delay one tick so DOM is settled before any reactive swaps fire
+    setTimeout(() => _loaded.set(comp), 0);
+  }).catch(err => {
+    console.error('[Clarity lazy] Failed to load component:', err);
+    _errored = true;
+    setTimeout(() => _loaded.set(() => {
+      const el = document.createElement('span');
+      el.style.cssText = 'color:#f87171;font-size:0.8em;padding:4px 8px;';
+      el.textContent = `[lazy load failed: ${err.message}]`;
+      return el;
+    }), 0);
+  });
+
+  const LazyWrapper = function LazyComponent(props = {}) {
+    // Already loaded — render immediately, no overhead
+    const comp = _loaded.peek();
+    if (comp) return comp(props);
+
+    // Register with nearest Suspense boundary (if any)
+    const insideSuspense = _suspenseStack.length > 0;
+    if (insideSuspense) _registerLazy(_promise);
+
+    // Return a comment placeholder; swap it with the real component when loaded
+    const placeholder = document.createComment('clarity:lazy');
+
+    // Self-managed swap: fires after setTimeout inside _promise .then
+    _promise.then(() => {
+      // Extra setTimeout so we're always one tick after the _loaded.set() call above
+      setTimeout(() => {
+        if (placeholder.parentNode) {
+          const c = _loaded.peek();
+          if (c) {
+            const el = c(props);
+            placeholder.parentNode.insertBefore(el, placeholder);
+            placeholder.parentNode.removeChild(placeholder);
+          }
+        }
+      }, 0);
+    });
+
+    return placeholder;
+  };
+
+  LazyWrapper._clarityLazy  = true;
+  LazyWrapper._loaded       = _loaded;
+  LazyWrapper._promise      = _promise;
+  return LazyWrapper;
+}
+
+// ─── Context API ─────────────────────────────────────────────────────────────
+/**
+ * Context API — provides a way to pass data through the component tree
+ * without passing props manually at every level (equivalent to React Context
+ * or Vue provide/inject).
+ *
+ * Usage:
+ *   // 1. Create a context (usually in its own file)
+ *   export const ThemeCtx = createContext('light')
+ *
+ *   // 2. Provide a value with <Provider ctx={ThemeCtx} value={theme}> in .clarity
+ *   //    The codegen emits _pushContext / _popContext around the children.
+ *
+ *   // 3. Consume in any descendant component
+ *   const theme = useContext(ThemeCtx)  // 'light' | 'dark' | or a Signal
+ *
+ * If `value` passed to Provider is a Signal, useContext returns that signal's
+ * current value AND subscribes the calling effect to future changes.
+ *
+ * Dynamic scoping: context is pushed/popped during the synchronous initial
+ * render. Subsequent reactive reads go through the signal returned by the
+ * Provider and stay reactive automatically.
+ */
+const _ctxRegistry = new Map(); // Symbol → any[]
+
+/**
+ * Creates a context token with an optional default value.
+ * @param {*} defaultValue   — returned by useContext() when no Provider wraps the caller
+ * @returns {{ id: symbol, _type: 'context', _default: * }}
+ */
+export function createContext(defaultValue) {
+  const id = Symbol('clarity:context');
+  _ctxRegistry.set(id, []);
+  return { id, _type: 'context', _default: defaultValue };
+}
+
+/** @internal — emitted by <Provider ctx={} value={}> codegen */
+export function _pushContext(ctx, value) {
+  const stack = _ctxRegistry.get(ctx.id);
+  if (stack) stack.push(value);
+}
+
+/** @internal — emitted by <Provider> codegen after children render */
+export function _popContext(ctx) {
+  const stack = _ctxRegistry.get(ctx.id);
+  if (stack && stack.length > 0) stack.pop();
+}
+
+/**
+ * Reads the nearest provided context value.
+ *
+ * If the value on the stack is a Signal, its .get() is called so the
+ * current effect subscribes to future changes.
+ *
+ * @param {{ id: symbol, _default: * }} ctx  — context token from createContext()
+ * @returns {*} current context value
+ */
+export function useContext(ctx) {
+  const stack = _ctxRegistry.get(ctx.id);
+  const raw   = (stack && stack.length > 0) ? stack[stack.length - 1] : ctx._default;
+  // Unwrap signal — subscriber will re-run when the signal changes
+  if (raw !== null && raw !== undefined && typeof raw === 'object' && raw._type === 'signal') {
+    return raw.get();
+  }
+  return raw;
+}
+
+// ─── reactive() ──────────────────────────────────────────────────────────────
+/**
+ * Creates a reactive proxy around a plain object.
+ * Every own enumerable key is backed by a signal so reading a property
+ * inside an effect creates a subscription and writing triggers re-renders.
+ *
+ * Equivalent to Vue 3's reactive().
+ *
+ * Usage:
+ *   const state = reactive({ count: 0, name: 'Clarity' })
+ *   effect(() => console.log(state.count))   // logs 0
+ *   state.count++                            // logs 1
+ *
+ * Notes:
+ *   • Deep nesting is NOT tracked — nested objects require their own reactive()
+ *   • Adding new keys after creation creates a new signal for that key
+ *   • Symbol keys are passed through to the target without signal wrapping
+ *
+ * @param {object} obj  — plain object to make reactive
+ * @returns {Proxy}
+ */
+export function reactive(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    throw new Error('[Clarity reactive] argument must be a plain object');
+  }
+
+  const _signals = {};
+  // Seed signals from initial keys
+  for (const key of Object.keys(obj)) {
+    _signals[key] = signal(obj[key]);
+  }
+
+  // Pending signals for keys read before they were set — keeps ownKeys clean
+  const _pending = {};
+
+  return new Proxy(obj, {
+    get(target, key, receiver) {
+      // Expose _signals for tooling (DevTools, spySignal)
+      if (key === '__clarity_signals__') return _signals;
+      if (typeof key === 'string') {
+        if (key in _signals) return _signals[key].get(); // tracked read
+        // Track reads of unknown keys via a pending signal so effects re-run
+        // when the key is later written via set().
+        if (!(key in _pending)) _pending[key] = signal(undefined);
+        return _pending[key].get();
+      }
+      return Reflect.get(target, key, receiver);
+    },
+    set(target, key, value) {
+      if (typeof key === 'string') {
+        if (key in _signals) {
+          _signals[key].set(value);
+        } else if (key in _pending) {
+          // Promote pending → real signal and notify subscribed effects
+          _pending[key].set(value);
+          _signals[key] = _pending[key];
+          delete _pending[key];
+        } else {
+          // Brand-new key with no prior reads
+          _signals[key] = signal(value);
+        }
+        return true;
+      }
+      return Reflect.set(target, key, value);
+    },
+    has(target, key) {
+      return (typeof key === 'string' && key in _signals) || key in target;
+    },
+    ownKeys() {
+      return Object.keys(_signals);
+    },
+    getOwnPropertyDescriptor(target, key) {
+      if (typeof key === 'string' && key in _signals) {
+        return { enumerable: true, configurable: true, writable: true, value: _signals[key].get() };
+      }
+      return Reflect.getOwnPropertyDescriptor(target, key);
+    },
+  });
+}
+
+// ─── Component lifecycle tracking ────────────────────────────────────────────
+/**
+ * Internal: tracks the component currently being constructed so onMount /
+ * onCleanup registrations are attached to the right node.
+ *
+ * The codegen wraps each component body in _withComponent(() => { ... }) so
+ * that onMount() / onCleanup() calls inside the function body are captured.
+ */
+let _currentComponent = null;
+
+/** @internal */
+export function _withComponent(renderFn) {
+  const comp = { _befores: [], _mounts: [], _cleanups: [], _updates: [] };
+  const prev = _currentComponent;
+  _currentComponent = comp;
+  let node;
+  try {
+    node = renderFn();
+  } finally {
+    _currentComponent = prev;
+  }
+
+  // beforeMount: run synchronously now — the node has been rendered but is not
+  // yet inserted into the DOM (Vue's onBeforeMount semantics).
+  if (comp._befores.length) {
+    comp._befores.forEach(f => {
+      try { f(); } catch (e) { console.error('[Clarity beforeMount]', e); }
+    });
+  }
+
+  // Use duck-typing so this works in both browser and Node.js test environments.
+  // Any object with a numeric nodeType (real DOM node or test mock) is accepted.
+  const isNodeLike = node !== null && typeof node === 'object' && typeof node.nodeType === 'number';
+  if (isNodeLike) {
+    if (comp._mounts.length) {
+      const prevMount = node.__clarity_mount__;
+      node.__clarity_mount__ = () => {
+        if (typeof prevMount === 'function') prevMount();
+        comp._mounts.forEach(f => f());
+      };
+    }
+    if (comp._cleanups.length) {
+      const prevClean = node.__clarity_cleanup__;
+      node.__clarity_cleanup__ = () => {
+        if (typeof prevClean === 'function') prevClean();
+        comp._cleanups.forEach(f => f());
+      };
+    }
+    // onUpdate: schedule callbacks after every reactive update (not on first mount)
+    if (comp._updates.length) {
+      let _mounted = false;
+      const prevMount = node.__clarity_mount__;
+      node.__clarity_mount__ = () => {
+        if (typeof prevMount === 'function') prevMount();
+        // Mark as mounted — effects running after this point trigger onUpdate
+        Promise.resolve().then(() => { _mounted = true; });
+      };
+      // Attach update runner to node for the effect scheduler to call
+      node.__clarity_update__ = () => {
+        if (_mounted) comp._updates.forEach(f => { try { f(); } catch (e) { console.error('[Clarity onUpdate]', e); } });
+      };
+    }
+  }
+  return node;
+}
+
+// ─── createRef ────────────────────────────────────────────────────────────────
+
+/**
+ * Create an imperative ref — a mutable container for a DOM node or any value.
+ *
+ * Unlike signals, refs do NOT trigger reactivity. They are used for:
+ *   • Storing a reference to a DOM element (for focus, animations, measurements)
+ *   • Holding mutable instance values that don't affect rendering
+ *
+ * Usage in a component:
+ *   const inputRef = createRef();
+ *
+ *   // In JSX:
+ *   <input ref={inputRef} />
+ *
+ *   // In onMount or an effect:
+ *   onMount(() => inputRef.current?.focus());
+ *
+ * Usage as a callback ref:
+ *   const inputRef = createRef();
+ *   <input ref={(el) => inputRef.current = el} />
+ *
+ * @template T
+ * @param {T} [initialValue=null]  — initial value (default: null)
+ * @returns {{ current: T | null, readonly __isRef: true }}
+ */
+export function createRef(initialValue = null) {
+  return {
+    current:  initialValue,
+    __isRef:  true,
+  };
+}
+
+/** Alias — same as createRef() */
+export const useRef = createRef;
+
+// ─── onUpdate ─────────────────────────────────────────────────────────────────
+
+/**
+ * Register a callback to run after EACH reactive update of the component
+ * (but NOT on the initial mount — use onMount for that).
+ *
+ * Equivalent to React's useEffect with deps, or Vue's onUpdated hook.
+ *
+ * Must be called at the top level of a component function.
+ *
+ * @param {() => void} fn
+ */
+export function onUpdate(fn) {
+  if (_currentComponent) {
+    _currentComponent._updates = _currentComponent._updates ?? [];
+    _currentComponent._updates.push(fn);
+  } else if (typeof console !== 'undefined') {
+    console.warn('[Clarity onUpdate] called outside of a component render. Did you forget _withComponent()?');
+  }
+}
+
+/**
+ * Register a callback to run AFTER the component has rendered but BEFORE its
+ * root node is inserted into the DOM (equivalent to Vue's onBeforeMount).
+ *
+ * Runs synchronously: state is initialised and the DOM subtree exists, but it
+ * is not yet attached to the document — so measurements that require layout
+ * are not available (use onMount for those). Good for last-moment state setup,
+ * reading initial props, or kicking off data loads before paint.
+ *
+ * Must be called at the top level of a component function.
+ *
+ * @param {() => void} fn
+ */
+export function beforeMount(fn) {
+  if (_currentComponent) {
+    _currentComponent._befores = _currentComponent._befores ?? [];
+    _currentComponent._befores.push(fn);
+  } else if (typeof console !== 'undefined') {
+    console.warn('[Clarity beforeMount] called outside of a component render. Did you forget _withComponent()?');
+  }
+}
+
+/**
+ * Register a callback to run after the component's root node is inserted
+ * into the DOM (equivalent to React useEffect(fn, []) or Vue onMounted).
+ *
+ * Must be called at the top level of a component function, NOT inside an
+ * effect or async callback.
+ *
+ * @param {() => void} fn
+ */
+export function onMount(fn) {
+  if (_currentComponent) {
+    _currentComponent._mounts.push(fn);
+  } else if (typeof console !== 'undefined') {
+    console.warn('[Clarity onMount] called outside of a component render. Did you forget _withComponent()?');
+  }
+}
+
+/**
+ * Register a callback to run when the component is removed from the DOM
+ * (equivalent to the cleanup return from useEffect, or Vue onUnmounted).
+ *
+ * Must be called at the top level of a component function.
+ *
+ * @param {() => void} fn
+ */
+export function onCleanup(fn) {
+  if (_currentComponent) {
+    _currentComponent._cleanups.push(fn);
+  } else if (typeof console !== 'undefined') {
+    console.warn('[Clarity onCleanup] called outside of a component render. Did you forget _withComponent()?');
+  }
+}
+
+// ─── AI Audit Log ────────────────────────────────────────────────────────────
+/**
+ * Append-only audit trail for every AI ↔ component interaction.
+ * Each entry is an immutable record; listeners are notified synchronously.
+ *
+ * Entry shape:
+ *   { type: 'read'|'act'|'forbidden_write', component, field|action, args?, value?, timestamp }
+ */
+
+const _aiAuditLog  = [];        // all-time log (grows until clearAIAuditLog())
+const _aiListeners = new Set(); // onAIAction subscribers
+let   _inAIAction  = false;     // true while act() is executing → guards forbidden writes
+
+/** @internal — called by generated AI contract code on every read / act */
+export function _aiAuditRecord(entry) {
+  const rec = Object.freeze({ ...entry, timestamp: Date.now() });
+  _aiAuditLog.push(rec);
+  _aiListeners.forEach(fn => { try { fn(rec); } catch { /* never throw from listener */ } });
+  return rec;
+}
+
+/** @internal — set/clear the AI-action execution context */
+export function _setAIActionContext(val) { _inAIAction = Boolean(val); }
+/** @internal — read the AI-action context flag */
+export function _isInAIAction()         { return _inAIAction; }
+
+/**
+ * Returns a copy of the full audit log.
+ * @returns {ReadonlyArray<object>}
+ */
+export function getAIAuditLog()  { return [..._aiAuditLog]; }
+
+/**
+ * Clears the in-memory audit log (does not affect future entries).
+ */
+export function clearAIAuditLog() { _aiAuditLog.length = 0; }
+
+/**
+ * Subscribe to real-time AI action events.
+ * The listener is called synchronously for every read, act, or forbidden attempt.
+ * @param {(entry: object) => void} fn
+ * @returns {() => void}  unsubscribe function
+ */
+export function onAIAction(fn) {
+  _aiListeners.add(fn);
+  return () => _aiListeners.delete(fn);
+}
+
+/**
+ * Distinct error thrown when an AI agent (any code running inside an `act()`
+ * call, or a contract read of a non-readable field) touches `ai:forbidden`
+ * state. Catchable by type so hosts can handle agent violations specifically.
+ */
+export class ClarityAIForbiddenError extends Error {
+  constructor(message, info = {}) {
+    super(message);
+    this.name      = 'ClarityAIForbiddenError';
+    this.component = info.component;
+    this.field     = info.field;
+    this.kind      = info.kind;       // 'read' | 'write' | 'access'
+  }
+}
+
+/**
+ * @internal — record a forbidden-access violation in the audit log and throw.
+ * Used by `_protectedSignal` (runtime guard) and by the generated contract
+ * `read()` method. Never returns.
+ */
+export function _aiThrowForbidden(componentName, fieldName, kind = 'access') {
+  _aiAuditRecord({ type: 'forbidden_' + kind, component: componentName, field: fieldName });
+  throw new ClarityAIForbiddenError(
+    `[Clarity AI] Forbidden: an agent attempted to ${kind} '${fieldName}' on ${componentName}. ` +
+    `This field is declared ai:forbidden. Declare it ai:readable / ai:actionable, or do not access it.`,
+    { component: componentName, field: fieldName, kind }
+  );
+}
+
+/**
+ * Wraps a signal declared `ai:forbidden` so that BOTH reads and writes are
+ * blocked while inside an AI `act()` call (i.e. while _inAIAction === true).
+ *
+ * Normal component, user, and effect code is completely unaffected — the guard
+ * only fires in AI-action context. Together with the contract (which never
+ * exposes forbidden fields through `readable`/`snapshot`/`read`), this makes
+ * `ai:forbidden` a real, enforced boundary rather than a declaration.
+ *
+ * @param {object} sig           — original signal created by signal()
+ * @param {string} componentName — component name for error / audit messages
+ * @param {string} fieldName     — signal name for error / audit messages
+ */
+export function _protectedSignal(sig, componentName, fieldName) {
+  return {
+    get:    ()   => { if (_inAIAction) _aiThrowForbidden(componentName, fieldName, 'read');  return sig.get(); },
+    peek:   ()   => { if (_inAIAction) _aiThrowForbidden(componentName, fieldName, 'read');  return sig.peek(); },
+    set:    (v)  => { if (_inAIAction) _aiThrowForbidden(componentName, fieldName, 'write'); return sig.set(v); },
+    update: (fn) => { if (_inAIAction) _aiThrowForbidden(componentName, fieldName, 'write'); return sig.update(fn); },
+    _type: 'signal',
+    _forbidden: true,
+    _component: componentName,
+    _field: fieldName,
+  };
+}
+
+// ─── Shared duck-typing helper ────────────────────────────────────────────────
+// Avoids `instanceof Node` which is only available in browser environments.
+// Used by ErrorBoundary and (via hydrate.js) by hydrateRoot.
+function _isNodeLike(val) {
+  return val !== null && typeof val === 'object' && typeof val.nodeType === 'number';
+}
+
+// ─── AI Registry helper (used by hydrate.js) ─────────────────────────────────
+/** @internal — allows hydrate.js to register adopted elements without circular import */
+export function _aiRegistryAdd(el) { _aiRegistry.add(el); }
+
+// ─── Error Boundary ───────────────────────────────────────────────────────────
+/**
+ * ErrorBoundary — catches errors thrown during child component rendering and
+ * displays a fallback UI instead of crashing the whole application.
+ *
+ * Equivalent to React's class-based componentDidCatch / getDerivedStateFromError,
+ * but implemented as a plain Clarity component function.
+ *
+ * Usage:
+ *
+ *   mount(
+ *     () => ErrorBoundary({
+ *       children: () => MyComponent({ data }),
+ *       fallback: (err) => h('div', { class: 'error-box' }, [err.message]),
+ *       onError:  (err) => console.error('[App] render error:', err),
+ *     }),
+ *     document.getElementById('app')
+ *   );
+ *
+ * In .clarity files (once the compiler supports it):
+ *
+ *   <ErrorBoundary fallback={<p>Something went wrong.</p>}>
+ *     <MyComponent />
+ *   </ErrorBoundary>
+ *
+ * @param {object}   options
+ * @param {Function|Node} options.children  - Component factory or pre-rendered node
+ * @param {Function|Node} [options.fallback] - Fallback: function(Error)→Node, or static Node
+ * @param {Function}     [options.onError]  - Called with the Error when one is caught
+ * @returns {Element}
+ */
+export function ErrorBoundary({ children, fallback, onError } = {}) {
+  const _error   = signal(null);
+  const _wrapper = document.createElement('div');
+  _wrapper.setAttribute('data-clarity-boundary', '');
+
+  // ── Helper: clear wrapper children safely (works in browser + test env) ──────
+  function _clearWrapper() {
+    if (typeof _wrapper.replaceChildren === 'function') {
+      _wrapper.replaceChildren(); // Modern browsers
+    } else {
+      _wrapper.innerHTML = '';
+      // For test stubs that don't implement innerHTML setter:
+      if (Array.isArray(_wrapper.children)) _wrapper.children.length = 0;
+    }
+  }
+
+  // ── Helper: render the fallback UI ──────────────────────────────────────────
+  function _showFallback(err) {
+    _clearWrapper();
+    let fallbackNode;
+
+    if (typeof fallback === 'function') {
+      try {
+        fallbackNode = fallback(err);
+      } catch (fallbackErr) {
+        // Fallback itself threw — show a minimal default
+        console.error('[Clarity ErrorBoundary] fallback threw:', fallbackErr);
+        fallbackNode = _defaultErrorUI(err);
+      }
+    } else if (_isNodeLike(fallback)) {
+      fallbackNode = fallback;
+    } else {
+      fallbackNode = _defaultErrorUI(err);
+    }
+
+    if (_isNodeLike(fallbackNode)) {
+      _wrapper.appendChild(fallbackNode);
+    }
+  }
+
+  // ── Helper: render the child content ────────────────────────────────────────
+  function _showContent() {
+    _clearWrapper();
+    try {
+      let content;
+      if (typeof children === 'function') {
+        content = children();
+      } else {
+        content = children;
+      }
+      if (_isNodeLike(content)) {
+        _wrapper.appendChild(content);
+      } else if (content != null) {
+        _wrapper.appendChild(document.createTextNode(String(content)));
+      }
+    } catch (err) {
+      // Report the error
+      if (typeof onError === 'function') {
+        try { onError(err); } catch { /* never let onError crash the boundary */ }
+      }
+      _error.set(err);
+      _showFallback(err);
+    }
+  }
+
+  // ── Initial render ───────────────────────────────────────────────────────────
+  _showContent();
+
+  // ── reset() — allows parent code to retry rendering after fixing the error ──
+  _wrapper.reset = function () {
+    _error.set(null);
+    _showContent();
+  };
+
+  // ── Expose current error (null when healthy) ─────────────────────────────────
+  _wrapper.getError = function () { return _error.peek(); };
+
+  return _wrapper;
+}
+
+/**
+ * @internal — default error UI shown when no fallback is provided
+ */
+function _defaultErrorUI(err) {
+  const box = document.createElement('div');
+  box.setAttribute('role', 'alert');
+  box.setAttribute('data-clarity-default-error', '');
+  box.style.cssText = [
+    'padding:12px 16px',
+    'background:#fef2f2',
+    'border:1.5px solid #fecaca',
+    'border-radius:6px',
+    'color:#991b1b',
+    'font-family:ui-monospace,monospace',
+    'font-size:13px',
+    'line-height:1.5',
+  ].join(';');
+
+  const title = document.createElement('strong');
+  title.textContent = '⚠ Component Error';
+  title.style.cssText = 'display:block;margin-bottom:4px';
+
+  const msg = document.createElement('span');
+  msg.textContent = err instanceof Error ? err.message : String(err);
+
+  // Stack trace (only in development)
+  const isDev = typeof process !== 'undefined'
+    ? (process.env?.NODE_ENV !== 'production')
+    : (typeof location !== 'undefined' && location.hostname === 'localhost');
+
+  if (isDev && err instanceof Error && err.stack) {
+    const pre = document.createElement('pre');
+    pre.style.cssText = 'margin-top:8px;font-size:11px;overflow:auto;white-space:pre-wrap;opacity:0.7';
+    pre.textContent = err.stack;
+    box.appendChild(title);
+    box.appendChild(msg);
+    box.appendChild(pre);
+  } else {
+    box.appendChild(title);
+    box.appendChild(msg);
+  }
+
+  return box;
+}
+
+// ─── Portal ───────────────────────────────────────────────────────────────────
+/**
+ * Renders `children` into a DOM node that exists outside the component's
+ * own DOM hierarchy — equivalent to React's `createPortal`.
+ *
+ * Primary use-cases: modals, drawers, tooltips, toasts, dropdowns.
+ *
+ * Usage in .clarity files:
+ *
+ *   import { createPortal } from '@ozsarman/clarityjs/runtime';
+ *
+ *   component Modal(open: Boolean) {
+ *     render {
+ *       <when cond={open}>
+ *         { createPortal(
+ *             <div class="modal-backdrop">...</div>,
+ *             document.body
+ *           )
+ *         }
+ *       </when>
+ *     }
+ *   }
+ *
+ * Or use the <Portal to="body"> JSX directive (compiler sugar):
+ *
+ *   <Portal to="body">
+ *     <div class="modal">Hello</div>
+ *   </Portal>
+ *
+ * Returns an anchor comment node that acts as a placeholder in the original
+ * tree. Cleanup removes the portal children from the target element.
+ *
+ * @param {Node | Node[] | Function} children - Node(s) or factory function
+ * @param {Element | string}  [target]  - Target element or CSS selector (default: document.body)
+ * @returns {Comment}  - Anchor comment in the original tree (for unmount tracking)
+ */
+export function createPortal(children, target) {
+  // Resolve target
+  const resolveTarget = () => {
+    if (!target) return document.body;
+    if (typeof target === 'string') {
+      return document.querySelector(target) ?? document.body;
+    }
+    return target;
+  };
+
+  const anchor = document.createComment('clarity:portal');
+
+  // Collect portal nodes
+  let portalNodes = [];
+
+  function _mount() {
+    const dest = resolveTarget();
+
+    // Resolve children
+    let nodes = [];
+    if (Array.isArray(children)) {
+      nodes = children.flat();
+    } else if (typeof children === 'function') {
+      const result = children();
+      nodes = Array.isArray(result) ? result.flat() : [result];
+    } else if (children instanceof Node) {
+      nodes = [children];
+    } else if (children != null) {
+      nodes = [document.createTextNode(String(children))];
+    }
+
+    for (const node of nodes) {
+      if (node instanceof Node) {
+        dest.appendChild(node);
+        portalNodes.push(node);
+      }
+    }
+  }
+
+  function _unmount() {
+    for (const node of portalNodes) {
+      node.parentNode?.removeChild(node);
+    }
+    portalNodes = [];
+  }
+
+  // Attach cleanup to the anchor so the parent component's onCleanup fires it
+  anchor.__clarity_cleanup__ = _unmount;
+
+  // Schedule mount after the current render cycle (so the anchor is in the DOM)
+  queueMicrotask(_mount);
+
+  return anchor;
+}
+
+// ─── Suspense ─────────────────────────────────────────────────────────────────
+/**
+ * Suspense boundary — wraps lazy-loaded children and shows a fallback while
+ * they are loading.
+ *
+ * Usage (component function):
+ *
+ *   import { Suspense, lazy } from '@ozsarman/clarityjs/runtime';
+ *   const HeavyChart = lazy(() => import('./HeavyChart.clarity'));
+ *
+ *   render {
+ *     <Suspense fallback={ <Spinner /> }>
+ *       <HeavyChart data={data} />
+ *     </Suspense>
+ *   }
+ *
+ * @param {object} options
+ * @param {Function | Node} options.children  - Component factory or node
+ * @param {Function | Node} [options.fallback] - Shown while loading
+ * @returns {Element}
+ */
+export function Suspense({ children, fallback } = {}) {
+  const wrapper  = document.createElement('div');
+  wrapper.setAttribute('data-clarity-suspense', '');
+  const _pending = [];
+
+  const ctx = { _pending };
+  _pushSuspense(ctx);
+
+  try {
+    // Render children (lazy() calls inside register their promises)
+    let content;
+    if (typeof children === 'function') {
+      content = children();
+    } else {
+      content = children;
+    }
+
+    if (_isNodeLike(content)) {
+      wrapper.appendChild(content);
+    }
+  } catch (err) {
+    console.error('[Clarity Suspense] child threw during render', err);
+  } finally {
+    _popSuspense();
+  }
+
+  // If any lazy children registered pending promises, show fallback first
+  if (_pending.length > 0) {
+    // Show fallback
+    wrapper.innerHTML = '';
+    let fallbackNode;
+    if (typeof fallback === 'function') {
+      try { fallbackNode = fallback(); } catch {}
+    } else if (_isNodeLike(fallback)) {
+      fallbackNode = fallback;
+    } else if (fallback != null) {
+      fallbackNode = document.createTextNode(String(fallback));
+    }
+
+    if (fallbackNode) wrapper.appendChild(fallbackNode);
+
+    // When all promises resolve, swap in the real content
+    Promise.all(_pending).then(() => {
+      wrapper.innerHTML = '';
+      let content;
+      if (typeof children === 'function') {
+        try { content = children(); } catch {}
+      } else {
+        content = children;
+      }
+      if (_isNodeLike(content)) wrapper.appendChild(content);
+    }).catch(err => {
+      console.error('[Clarity Suspense] lazy load failed', err);
+    });
+  }
+
+  return wrapper;
+}
+
+// ─── TypeScript Types ─────────────────────────────────────────────────────────
+// These are exported so the TypeGenerator can reference them in .d.ts files.
+// They mirror the shape of signal() and computed() return values.
+
+/**
+ * @template T
+ * @typedef {{ get(): T, set(v: T): void, update(fn: (v:T)=>T): void, peek(): T }} Signal
+ */
+
+/**
+ * @template T
+ * @typedef {{ get(): T, peek(): T }} Computed
+ */
+
+// ─── Dev Tools ───────────────────────────────────────────────────────────────
+/**
+ * Expose internals to developer tools and AI assistants.
+ * LLM-friendly: structured, inspectable, auditable.
+ */
+export const __dev__ = {
+  version: '0.0.1',
+  inspect(sig) {
+    if (sig._type === 'signal') {
+      return {
+        type: 'signal',
+        value: sig.peek(),
+        subscriberCount: sig._subscribers.size,
+      };
+    }
+    if (sig._type === 'computed') {
+      return {
+        type: 'computed',
+        value: sig.peek(),
+        subscriberCount: sig._subscribers.size,
+      };
+    }
+    return { type: 'unknown' };
+  },
+};