@fluixi/dom 1.0.0-alpha.82 → 1.0.0-alpha.84

package/dist/lib/dom/runtime.js

@@ -1,10 +1,9 @@
 /**
- * @fileoverview Core Reactive DOM Runtime
  * @module @fluixi/dom/runtime
  *
  * Fine-grained reactive DOM manipulation utilities inspired by SolidJS.
  * Key design: Event delegation uses `$$eventname` properties on DOM nodes
- * (the SolidJS pattern) — simpler and more reliable than Map-based lookup.
+ * (the SolidJS pattern): simpler and more reliable than Map-based lookup.
  *
  * Critical fixes applied:
  * - insertContent array branch: nested signal content cleanup via onCleanup
@@ -18,8 +17,8 @@ import { stampVersions, warnOnVersionSkew } from './versions.js';
 import { isComponent } from '../component/modifiers.js';
 // Reactive primitives come straight from the signal core (the globalThis-singleton graph makes
 // this duplication-safe). The integration bridge is only for framework-provided glue that is
-// NOT in the reactive core (e.g. createComponent).
-import { batch, createEffect, createRenderEffect, createRoot, onCleanup, readChildren } from '@fluixi/reactive/signal';
+// not in the reactive core (e.g. createComponent).
+import { batch, createEffect, createRenderEffect, createRoot, onCleanup, readChildren, reportReactiveBinding, reportReactiveDirective, untrack } from '@fluixi/reactive/signal';
 import { isServer, getServerNodes, isDomNode, isDomElement, isDomText, } from './server/host.js';
 import { hydration, getHydrationWalker, isAdopted, runHydrationAt, ascendPast, } from './hydration-state.js';
 function getElementFingerprint(el) {
@@ -71,24 +70,34 @@ export const generateID = () => {
 // ============================================================================
 const EMPTY_OBJ = {};
 const EMPTY_ARR = [];
+/** Where devtools leaves the source position of a hole. Absent in a production build. */
+const HOLE_TAG = '__fx_at';
+/** Where an element's own source position goes, for devtools to read back. */
+const LOC_TAG = '__fx_loc';
+/** Only ever called with a position when the compiler recorded one. */
+function located(element, at) {
+    if (at)
+        element[LOC_TAG] = at;
+    return element;
+}
 // Template cache
 const templateCache = new Map();
 // ============================================================================
-// Event Delegation — SolidJS $$eventname property pattern
+// Event Delegation. SolidJS $$eventname property pattern
 //
 // Handlers are stored directly on DOM nodes as `node.$$click = handler`.
-// The capture listener reads `node.$$click` directly — no Map lookups needed.
+// The capture listener reads `node.$$click` directly, no Map lookups needed.
 // This approach correctly handles e.preventDefault() and stopPropagation.
 // ============================================================================
 const delegatedSet = new Set();
-// Events that don't bubble — must use direct addEventListener
+// Events that don't bubble: must use direct addEventListener
 const NON_DELEGATED = new Set(['scroll', 'focus', 'blur', 'load', 'error', 'resize', 'mouseenter', 'mouseleave', 'pointerenter', 'pointerleave', 'gotpointercapture', 'lostpointercapture']);
 /**
  * Register global delegated event listener for the given event names.
  * Stores handlers as `element.$$eventname = handler` properties.
  */
 export function delegateEvents(eventNames) {
-    if (isServer)
+    if (isServer())
         return; // no document to attach to; events are inert in SSR
     for (const name of eventNames) {
         if (delegatedSet.has(name) || NON_DELEGATED.has(name))
@@ -115,12 +124,12 @@ function delegatedEventHandler(e) {
     }
 }
 /**
- * Add a delegated event handler — stores as $$eventname property
+ * Add a delegated event handler: stores as $$eventname property
  */
 export function addDelegatedEventListener(element, name, handler) {
     element[`$$${name}`] = handler;
     if (NON_DELEGATED.has(name)) {
-        // Non-bubbling event (focus/blur/pointerenter/…): document delegation can't observe it, so
+        // Non-bubbling event (focus/blur/pointerenter/...): document delegation can't observe it, so
         // attach a direct listener once. A stable forwarder reads $$name so updating the handler
         // doesn't churn addEventListener/removeEventListener.
         const key = `__fx_${name}`;
@@ -163,9 +172,9 @@ export function isFunction(value) {
     return typeof value === 'function';
 }
 function createTextNode(value, anchor = false) {
-    if (isServer)
+    if (isServer())
         return getServerNodes().createText(value);
-    // Anchors/placeholders (insert markers) are client-only insertion points — the server
+    // Anchors/placeholders (insert markers) are client-only insertion points, the server
     // serialized nothing for them, so they must never adopt a server text node. Only real
     // content goes through the hydration walker.
     if (hydration.active && !anchor) {
@@ -176,7 +185,7 @@ function createTextNode(value, anchor = false) {
     return document.createTextNode(value);
 }
 function createMarker(value) {
-    if (isServer)
+    if (isServer())
         return getServerNodes().createComment(value);
     if (hydration.active) {
         const node = getHydrationWalker()?.hydrateMarker(value);
@@ -185,18 +194,34 @@ function createMarker(value) {
     }
     return document.createComment(value);
 }
-export function createNativeElement(tag, isSVG = false) {
-    if (isServer)
+/**
+ * Create an element, or adopt the server's during hydration.
+ *
+ * One of the calls the compiler emits, so its three modes are the whole of how a
+ * template becomes DOM. Server rendering routes to the realm's node factory and returns
+ * a string-serializable stand-in rather than a real element. Hydration asks the walker
+ * for the next element the server wrote and reuses it. Otherwise it creates one.
+ *
+ * `at` is a dev-only source position, stamped onto the node for devtools. A production
+ * build passes none and carries no marker.
+ */
+export function createNativeElement(tag, isSVG = false, at) {
+    if (isServer())
         return getServerNodes().createElement(tag, isSVG);
     if (hydration.active) {
         const node = getHydrationWalker()?.hydrateElement(tag);
         if (node)
-            return node;
+            return at ? located(node, at) : node;
     }
-    return isSVG
-        ? document.createElementNS(SVG_NAMESPACE, tag)
-        : document.createElement(tag);
+    return located(isSVG ? document.createElementNS(SVG_NAMESPACE, tag) : document.createElement(tag), at);
 }
+/**
+ * Parse static template HTML once and cache it by that string.
+ *
+ * Every clone of a template comes from one parse, which is most of why a compiled
+ * template is cheap. The cache is keyed by the markup rather than by identity, so two
+ * modules emitting the same HTML share the parse.
+ */
 export function createTemplate(html, isSVG = false) {
     const cached = templateCache.get(html);
     if (cached)
@@ -216,17 +241,17 @@ export function createTemplate(html, isSVG = false) {
  * needs it.
  *
  * The three cases mirror {@link createNativeElement}, which is the point: a template has
- * to behave like the elements it replaces, or it works only in client-rendered apps —
+ * to behave like the elements it replaces, or it works only in client-rendered apps,
  * which is exactly how it failed before this existed.
  *
- *  - **server** — carried as text and written out verbatim. Parsing it into elements
+ *  - **server**: carried as text and written out verbatim. Parsing it into elements
  *    only to serialize them straight back would be pure cost.
- *  - **hydrating** — adopt the server's existing subtree and skip past it. The subtree
+ *  - **hydrating**: adopt the server's existing subtree and skip past it. The subtree
  *    is inert, so there is nothing inside to wire up.
- *  - **client** — parse once (cached by HTML) and clone per instance.
+ *  - **client**: parse once (cached by HTML) and clone per instance.
  */
-export function templateNode(html, tag, holes = false, isSVG = false) {
-    if (isServer) {
+export function templateNode(html, tag, holes = false, isSVG = false, at) {
+    if (isServer()) {
         // With holes the server needs real nodes for the hole content to be inserted into;
         // without them the string can be written out untouched, which is strictly cheaper.
         const nodes = getServerNodes();
@@ -237,16 +262,38 @@ export function templateNode(html, tag, holes = false, isSVG = false) {
         // through the adopted tree, whose structure matches the template by construction.
         const node = getHydrationWalker()?.hydrateStatic(tag);
         if (node)
-            return node;
+            return stampPositions(node, at);
     }
-    return cloneTemplate(createTemplate(html, isSVG), isSVG).firstChild;
+    return stampPositions(cloneTemplate(createTemplate(html, isSVG), isSVG).firstChild, at);
+}
+/**
+ * Write each element's own source position onto it.
+ *
+ * The whole template is one string, so a source map traces every element in it back to the
+ * line the root opens at: devtools would name the component and nothing finer. This is the
+ * one moment the two line up: the tree holds exactly the elements the compiler listed, in
+ * the same order, because holes are filled after this returns.
+ *
+ * Only reached when the compiler emitted positions, which it does for a dev build.
+ */
+function stampPositions(node, at) {
+    const root = node;
+    if (!at || typeof root?.querySelectorAll !== 'function')
+        return node;
+    const all = [root, ...root.querySelectorAll('*')];
+    for (let i = 0; i < all.length && i * 2 + 1 < at.pos.length; i++) {
+        const line = at.pos[i * 2];
+        if (line)
+            all[i][LOC_TAG] = { file: at.file, line, column: at.pos[i * 2 + 1] };
+    }
+    return node;
 }
 /**
  * Evaluate a hole's content with the hydration cursor placed at what the server rendered
  * for *that hole*.
  *
  * Without this, only the hole's top level adopts. `templateNode` moves the cursor past the
- * whole template — the subtree is inert, so there is nothing in it to walk — which leaves
+ * whole template, the subtree is inert, so there is nothing in it to walk, which leaves
  * the cursor in the wrong place for anything the hole builds internally. A component in a
  * hole would then recreate its own elements: no duplication, but every server node thrown
  * away, which is most of what hydration is for.
@@ -257,22 +304,35 @@ export function holeScope(start, produce) {
     if (!hydration.active)
         return produce();
     // `produce` is called with the cursor already placed, because the value may be built
-    // eagerly — `props.children` is a getter, and reading it constructs its nodes there and
+    // eagerly: `props.children` is a getter, and reading it constructs its nodes there and
     // then. Wrapping the result instead would be too late: the DOM would already exist,
     // built against whatever cursor happened to be current, and the server's nodes would be
     // left behind as duplicates.
     const value = runHydrationAt(start.nextSibling, produce);
     // A memo or accessor builds nothing until it is read, which happens inside `insert`'s
-    // effect — so it needs the cursor placed again at that moment. The guard matters: once
+    // effect, so it needs the cursor placed again at that moment. The guard matters: once
     // hydration is over, later updates must render normally rather than re-enter it.
     if (typeof value === 'function') {
         const accessor = value;
-        return ((...args) => hydration.active
+        const wrapped = (...args) => hydration.active
             ? runHydrationAt(start.nextSibling, () => accessor(...args))
-            : accessor(...args));
+            : accessor(...args);
+        return carryHoleTag(accessor, wrapped);
     }
     return value;
 }
+/**
+ * The compiler tags a hole's accessor with where it was written, and devtools reads the tag
+ * off whatever finally reaches `insert`. Under hydration that is this wrapper, not the
+ * accessor, so the tag has to come along: otherwise the binding reports the frame it was
+ * created from, which is a line in this file.
+ */
+function carryHoleTag(from, to) {
+    const tag = from[HOLE_TAG];
+    if (tag !== undefined)
+        to[HOLE_TAG] = tag;
+    return to;
+}
 /**
  * The closing marker for a hole opened at `start`.
  *
@@ -293,7 +353,7 @@ export function holeEnd(start) {
  *
  * On a fresh clone the markers are adjacent and this is empty, so `insert` builds the
  * content. When hydrating, the server's rendered content sits between them and is handed
- * back — `insertExpression` then reuses those nodes (setting `.data` on a text node
+ * back: `insertExpression` then reuses those nodes (setting `.data` on a text node
  * rather than creating one), which is what adoption means here.
  *
  * Paired markers are what make this exact: a hole's content is *by definition* the nodes
@@ -331,12 +391,12 @@ export function fnName(fn) {
     return fn._name || fn.name || 'anonymous';
 }
 /**
- * iterateFn — resolves a value by calling through plain function wrappers.
+ * iterateFn: resolves a value by calling through plain function wrappers.
  *
  * Must stop at signals/memos/resources ($SIGNAL marker) and
  * component thunks (fluixi-component marker). Without this:
  *  - components returning memos get unwrapped to static values, losing reactivity
- *  - lazy component createMemo re-triggers C(props) → infinite recursion
+ *  - lazy component createMemo re-triggers C(props) -> infinite recursion
  */
 export function iterateFn(item) {
     // Stop immediately if it's a signal, memo, or resource
@@ -347,7 +407,7 @@ export function iterateFn(item) {
         return item;
     if (typeof item !== 'function')
         return item;
-    // Unwrap plain function wrappers — stop at signals and component thunks
+    // Unwrap plain function wrappers: stop at signals and component thunks
     let content = item();
     while (typeof content === 'function' &&
         !isSignal(content) &&
@@ -365,13 +425,18 @@ const MAX_INSERT_DEPTH = 200;
 // _createInsertEffect
 //
 // Creates a reactive render effect for DOM insertion.
-// Uses a componentCache to ensure component thunks are called at most once —
+// Uses a componentCache to ensure component thunks are called at most once:
 // same thunk function reference always returns the same output across re-runs.
 // ============================================================================
 function _createInsertEffect(getAccessor, parent, marker, initialCurrent, setCurrent) {
     let current = initialCurrent;
     const componentCache = new Map();
     return createRenderEffect(() => {
+        // The accessor, never its result: it carries the compiler's hole position, and calling it
+        // again here builds the dom twice, during hydration, a duplicated subtree.
+        //
+        // Every run, because what this effect writes into moves as the value does.
+        reportReactiveBinding(marker ?? parent, 'content', undefined, getAccessor);
         let value;
         // ── 0. If accessor itself is a component thunk (not a signal/memo), call it once via cache ──
         // must check !isSignal to avoid caching reactive values that are also
@@ -441,9 +506,22 @@ function _createInsertEffect(getAccessor, parent, marker, initialCurrent, setCur
 // ============================================================================
 // insert
 // ============================================================================
+/**
+ * Place content in a parent, and keep it current when the content is reactive.
+ *
+ * The other half of the compiler's output. `accessor` may be a value or a function: a
+ * function is read inside a render effect, so the position updates on its own when
+ * anything it read changes. That is where fine-grained updating actually happens, since
+ * only this position is touched rather than the subtree around it.
+ *
+ * `marker` is the node the content sits before, which is what makes several holes in one
+ * parent independent. `init` is what the position already holds, empty on a fresh clone
+ * and the server's nodes when hydrating, so hydration reconciles against them instead of
+ * building a second copy.
+ */
 export function insert(parent, accessor, marker, init) {
     if (_insertDepth > MAX_INSERT_DEPTH) {
-        console.error('[insert] Exceeded max call depth — possible infinite loop.');
+        console.error('[insert] Exceeded max call depth, possible infinite loop.');
         return () => null;
     }
     if (marker !== undefined && !marker) {
@@ -462,7 +540,7 @@ export function insert(parent, accessor, marker, init) {
     if (typeof accessor !== 'function' && !isReactiveArray(accessor)) {
         _insertDepth++;
         try {
-            // `current` — not null. The caller passes what is already in this slot, and for a
+            // `current`, not null. The caller passes what is already in this slot, and for a
             // hydrating template hole that is the server's own nodes (`holeContent`). Dropping it
             // meant a static value never adopted: insertExpression saw an empty slot and appended
             // a second copy beside the server's, so `{cmd}` rendered the string twice.
@@ -547,14 +625,14 @@ export function insertExpression(parent, value, marker, current, componentCache)
         }
         else if (!isAdopted(parent, node)) {
             // during hydration createTextNode reuses the in-place server text node and
-            // already advanced the cursor — don't re-insert (that would reorder).
+            // already advanced the cursor: don't re-insert (that would reorder).
             insertBefore(parent, node, marker);
         }
         return node;
     }
     if (isDomNode(value)) {
         // Hydration: the node was already produced from the server DOM (reused by
-        // createNativeElement) and sits in `parent` in place — adopt it without
+        // createNativeElement) and sits in `parent` in place: adopt it without
         // re-inserting, and ascend the cursor past its (already-walked) subtree.
         if (isAdopted(parent, value)) {
             ascendPast(value);
@@ -598,13 +676,13 @@ export function insertExpression(parent, value, marker, current, componentCache)
         const reactiveSlots = [];
         flattenArray(value, array, parent, marker, true, componentCache, reactiveSlots);
         const reconciled = reconcileArrays(parent, currentArray, array, marker);
-        // Markers are now in the DOM — wire a per-slot reactive insert. insert() sets up a nested
+        // Markers are now in the DOM: wire a per-slot reactive insert. insert() sets up a nested
         // render effect that re-inserts the member's content before its marker on change, so a bare
         // control-flow component return (<Show>/<Switch>/<For>) updates in place.
         //
         // The per-slot content lives OUTSIDE the reconcile array (only the marker is tracked), so if
-        // this enclosing effect re-runs with a shorter array — e.g. a <For> item dropped, or its child
-        // resolved to a memo (Provider -> component) — reconcile removes the marker but would orphan the
+        // this enclosing effect re-runs with a shorter array: e.g. a <For> item dropped, or its child
+        // resolved to a memo (Provider -> component): reconcile removes the marker but would orphan the
         // content. Register a cleanup that removes the slot's nodes when its effect is torn down. This
         // only fires when the enclosing effect re-runs (the array itself changed); an in-place update
         // (e.g. <Show> toggling) never re-runs this effect, so it keeps updating in place.
@@ -630,12 +708,12 @@ export function insertExpression(parent, value, marker, current, componentCache)
     }
     return cleanChildren(parent, current, marker);
 }
-// flattenArray — flatten a children array to DOM nodes. A signal whose result is a
+// flattenArray: flatten a children array to DOM nodes. A signal whose result is a
 // component thunk (e.g. a router memo returning a SuspenseThunk) is recursed through
 // flattenArray, not read inline, so the thunk goes through componentCache and stays
 // stable across navigations.
 function flattenArray(arr, result, parent, marker, track = true, componentCache, 
-// When provided, a reactive member is NOT read inline (which would subscribe the enclosing
+// When provided, a reactive member is not read inline (which would subscribe the enclosing
 // render effect and re-render the whole subtree on change). Instead it emits a placeholder
 // marker and records itself here; the array caller wires a fine-grained insert() per slot
 // after the markers are placed. This is what makes a bare control-flow component return
@@ -656,14 +734,14 @@ reactiveSlots) {
         if (typeof item === 'function') {
             let resolved;
             if (isComponent(item) && !isSignal(item)) {
-                // Pure component thunk (e.g. () => <div>) — call exactly once and cache so
+                // Pure component thunk (e.g. () => <div>): call exactly once and cache so
                 // re-runs of the enclosing render effect return the same DOM nodes (keeps
                 // focus etc. stable across navigations).
                 // must check !isSignal. A memo stamped as a component (e.g. an
                 // Outlet/Routes/Suspense output returned via $component/asComponent) is BOTH
                 // isComponent AND isSignal; caching it would freeze its first value (so a
-                // boundary that later switches from a single node to an array — fallback ->
-                // children — would never update). Read those reactively in the else branch.
+                // boundary that later switches from a single node to an array: fallback ->
+                // children: would never update). Read those reactively in the else branch.
                 if (!componentCache)
                     componentCache = new Map();
                 if (!componentCache.has(item))
@@ -671,17 +749,17 @@ reactiveSlots) {
                 resolved = componentCache.get(item);
             }
             else {
-                // Signal/memo (or memo-stamped component) — read to track reactivity.
+                // Signal/memo (or memo-stamped component): read to track reactivity.
                 resolved = item();
             }
             // Unwrap plain wrappers; stop at signals and component thunks.
-            // Cache calls by function reference — a plain function returned by a
+            // Cache calls by function reference, a plain function returned by a
             // signal/memo (e.g. `createMemo(() => cond ? () => <JSX> : ...)`) is a
             // stable reference as long as the memo doesn't re-evaluate. Calling it
             // once and caching the result means re-runs of the outer render effect
             // (triggered by unrelated signals like `activeLevel()`) hit the cache and
             // return the same DOM nodes. reconcileArrays then sees identical references
-            // and skips the slot — the focused <input> is never removed.
+            // and skips the slot, the focused <input> is never removed.
             while (typeof resolved === 'function' &&
                 !isPromise(resolved) &&
                 !isSignal(resolved) &&
@@ -705,8 +783,8 @@ reactiveSlots) {
                         reactiveSlots.push({ marker: slot, sig: resolved });
                         continue;
                     }
-                    // Read the signal — tracked inside the enclosing render effect.
-                    // Use flattenArray recursively (NOT normalizeValue) so
+                    // Read the signal: tracked inside the enclosing render effect.
+                    // Use flattenArray recursively (not normalizeValue) so
                     // component thunks inside the result go through componentCache.
                     let val = resolved();
                     while (typeof val === 'function' && isSignal(val))
@@ -720,7 +798,7 @@ reactiveSlots) {
                         flattenArray([val], result, parent, marker, track, componentCache);
                     continue;
                 }
-                // Other function type — skip
+                // Other function type: skip
                 continue;
             }
             // resolved is not a function
@@ -786,15 +864,15 @@ reactiveSlots) {
 // ============================================================================
 function reconcileArrays(parent, a, b, marker) {
     // Pre-process: clone any node already owned by a different parent.
-    // The Babel plugin hoists static elements to module-level — the same node
+    // The Babel plugin hoists static elements to module-level, the same node
     // can appear in `b` for multiple parents simultaneously. Clone to avoid
     // stealing it from its current owner; future reconciles track the clone.
     //
-    // A DocumentFragment is NOT such an owner. `cloneTemplate` hands back the clone still
+    // A DocumentFragment is not such an owner. `cloneTemplate` hands back the clone still
     // sitting in its fragment, so a template-cloned element arrives here with a non-null
     // parent that nothing else refers to. Cloning it again threw away the node whose props
-    // had just been applied — `cloneNode` copies attributes but not the event-handler
-    // properties — so an element built from a template lost its handlers the moment it was
+    // had just been applied: `cloneNode` copies attributes but not the event-handler
+    // properties, so an element built from a template lost its handlers the moment it was
     // inserted as part of an array. Moving it out of the fragment is exactly right.
     for (let i = 0; i < b.length; i++) {
         const owner = b[i].parentNode;
@@ -811,18 +889,18 @@ function reconcileArrays(parent, a, b, marker) {
         ? a[aEnd - 1].nextSibling ?? undefined
         : marker, map = null;
     while (aStart < aEnd || bStart < bEnd) {
-        // 1. Common prefix — already in the right place, skip.
+        // 1. Common prefix: already in the right place, skip.
         if (a[aStart] === b[bStart]) {
             aStart++;
             bStart++;
             continue;
         }
-        // 2. Common suffix — already in the right place, shrink window.
+        // 2. Common suffix: already in the right place, shrink window.
         while (aEnd > aStart && bEnd > bStart && a[aEnd - 1] === b[bEnd - 1]) {
             aEnd--;
             bEnd--;
         }
-        // 3. Old list exhausted — insert remaining new nodes.
+        // 3. Old list exhausted: insert remaining new nodes.
         if (aEnd === aStart) {
             const node = bEnd < bLength
                 ? bStart
@@ -832,7 +910,7 @@ function reconcileArrays(parent, a, b, marker) {
             while (bStart < bEnd)
                 insertBefore(parent, b[bStart++], node);
         }
-        // 4. New list exhausted — remove remaining old nodes.
+        // 4. New list exhausted: remove remaining old nodes.
         else if (bEnd === bStart) {
             while (aStart < aEnd) {
                 if ((!map || !map.has(a[aStart])) && a[aStart].parentNode === parent)
@@ -870,7 +948,7 @@ function reconcileArrays(parent, a, b, marker) {
                             insertBefore(parent, b[bStart++], node);
                     }
                     else {
-                        // Guard replaceChild: if a[aStart] was moved out by another effect, insert instead.
+                        // Guard replaceChild, if a[aStart] was moved out by another effect, insert instead.
                         if (a[aStart].parentNode === parent) {
                             parent.replaceChild(b[bStart++], a[aStart++]);
                         }
@@ -965,10 +1043,41 @@ export function addNativeEventListener(element, name, value) {
     element.addEventListener(name, handler, options);
     return () => element.removeEventListener(name, handler, options);
 }
+/**
+ * Name each key of a class or style object as the directive it came from.
+ *
+ * `class:a class:b` are merged by the compiler into one classList prop, so the keys are the
+ * only record that two directives were written.
+ */
+/**
+ * A directive the compiler had to name, because the runtime sees only what it lowers to.
+ * `bind:value` arrives as an ordinary value and an input handler.
+ */
+function reportMarked(element, accessor) {
+    if (!accessor || typeof accessor !== 'function')
+        return;
+    const written = accessor[HOLE_TAG]?.name;
+    if (!written)
+        return;
+    const colon = written.indexOf(':');
+    if (colon === -1)
+        return;
+    reportReactiveDirective(element, written.slice(0, colon), written.slice(colon + 1), accessor);
+}
+function reportKeys(element, kind, value) {
+    const from = typeof value === 'function' ? untrack(() => value()) : value;
+    if (!from || typeof from !== 'object')
+        return;
+    for (const key of Object.keys(from))
+        reportReactiveDirective(element, kind, key);
+}
 export function applyUse(element, value) {
     const call = (dir, accessor) => {
-        if (typeof dir === 'function')
-            dir(element, accessor ?? (() => undefined));
+        if (typeof dir !== 'function')
+            return;
+        // Named so a watcher can tell one directive from another. Nothing else reads it.
+        reportReactiveDirective(element, 'use', dir.name || 'use', accessor);
+        dir(element, accessor ?? (() => undefined));
     };
     if (typeof value === 'function') {
         call(value);
@@ -989,11 +1098,13 @@ export function applyUse(element, value) {
     }
 }
 export function setDynamicAttribute(element, name, accessor, isSVG = false) {
+    reportMarked(element, accessor);
     if (typeof accessor !== 'function') {
         setAttribute(element, name, accessor, isSVG);
         return () => { };
     }
     return createRenderEffect(() => {
+        reportReactiveBinding(element, 'attribute', name, accessor);
         const value = typeof accessor === 'function' ? accessor() : accessor;
         setAttribute(element, name, value, isSVG);
     });
@@ -1003,7 +1114,9 @@ export function setDynamicProperty(element, name, accessor) {
         setProperty(element, name, accessor);
         return () => { };
     }
+    reportMarked(element, accessor);
     return createRenderEffect(() => {
+        reportReactiveBinding(element, 'property', name, accessor);
         const value = typeof accessor === 'function' ? accessor() : accessor;
         setProperty(element, name, value);
     });
@@ -1016,6 +1129,7 @@ export function setDynamicBoolAttribute(element, name, accessor) {
         return () => { };
     }
     return createRenderEffect(() => {
+        reportReactiveBinding(element, 'attribute', name, accessor);
         const value = accessor();
         setAttribute(element, name, !!value);
     });
@@ -1029,9 +1143,12 @@ export function setClassName(element, value) {
         return;
     }
     if (typeof value === 'function') {
-        // A render effect, like every other attribute binding — `spread` already wraps
+        // A render effect, like every other attribute binding: `spread` already wraps
         // class this way, so going through `applyProps` shouldn't schedule it later.
-        createRenderEffect(() => setClassName(element, value()));
+        createRenderEffect(() => {
+            reportReactiveBinding(element, 'attribute', 'class', value);
+            setClassName(element, value());
+        });
         return;
     }
     if (typeof value === 'string') {
@@ -1055,7 +1172,7 @@ export function setClassName(element, value) {
     element.setAttribute('class', String(value));
 }
 /**
- * Apply a `classList`-style map `{ 'a b': condition }` — toggling each class on
+ * Apply a `classList`-style map `{ 'a b': condition }`, toggling each class on
  * the element. A condition may be a value or a reactive accessor; when
  * `disposers` is provided, accessor entries are wired with a render effect so
  * they update fine-grained (Solid-style `classList`).
@@ -1105,6 +1222,19 @@ export function setStyle(element, _value) {
 // ============================================================================
 // spread
 // ============================================================================
+/**
+ * Apply a props object to an element, and re-apply what changes.
+ *
+ * Handles every prop kind the compiler can emit: attributes, properties, events,
+ * `class`/`style` in their object and string forms, `ref` and `use:`. Each reactive prop
+ * gets its own effect, so a change touches one attribute rather than re-running the
+ * element.
+ *
+ * `prevProps` is what was applied last, which is how a removed key is cleared rather
+ * than left behind. A getter-backed prop stays reactive: the value is read inside the
+ * effect, not when the object was built, which is what keeps `splitProps` and a
+ * polymorphic wrapper live.
+ */
 export function spread(options) {
     const { element, props, prevProps = EMPTY_OBJ, isSVG = false, skipChildren = false, } = options;
     if (!element || !isDomElement(element)) {
@@ -1117,7 +1247,7 @@ export function spread(options) {
     }
     // Trust the element's real namespace over the compile-time isSVG flag: the codegen only marks
     // some SVG elements (e.g. <svg>/<defs>) and misses nested ones (<linearGradient>, <stop>). For
-    // an actually-SVG element, a key like `x1` IS `in element` (read-only SVGAnimatedLength), so the
+    // an actually-SVG element, a key like `x1` is `in element` (read-only SVGAnimatedLength), so the
     // property branch below would throw "Cannot set property x1". Detecting SVG by namespaceURI keeps
     // those on the setAttribute path. (Matters under hydration, where we adopt the real, correctly
     // namespaced server node.)
@@ -1151,22 +1281,28 @@ export function spread(options) {
             continue;
         }
         // Forced bindings: prop:x always assigns the property, attr:x always sets the
-        // attribute, bool:x toggles a boolean attribute — skipping the heuristic below.
+        // attribute, bool:x toggles a boolean attribute, skipping the heuristic below.
         if (key.startsWith('prop:')) {
+            reportReactiveDirective(element, 'prop', key.slice(5), value);
             disposers.push(setDynamicProperty(element, key.slice(5), value));
             continue;
         }
         if (key.startsWith('attr:')) {
+            reportReactiveDirective(element, 'attr', key.slice(5), value);
             disposers.push(setDynamicAttribute(element, key.slice(5), value, elementIsSVG));
             continue;
         }
         if (key.startsWith('bool:')) {
+            reportReactiveDirective(element, 'bool', key.slice(5), value);
             disposers.push(setDynamicBoolAttribute(element, key.slice(5), value));
             continue;
         }
         if (key === 'class' || key === 'className') {
             if (typeof value === 'function') {
-                disposers.push(createRenderEffect(() => setClassName(element, value())));
+                disposers.push(createRenderEffect(() => {
+                    reportReactiveBinding(element, 'attribute', 'class', value);
+                    setClassName(element, value());
+                }));
             }
             else {
                 setClassName(element, value);
@@ -1174,8 +1310,12 @@ export function spread(options) {
             continue;
         }
         if (key === 'classList') {
+            reportKeys(element, 'class', value);
             if (typeof value === 'function') {
-                disposers.push(createRenderEffect(() => setClassList(element, value())));
+                disposers.push(createRenderEffect(() => {
+                    reportReactiveBinding(element, 'attribute', 'class', value);
+                    setClassList(element, value());
+                }));
             }
             else {
                 setClassList(element, value, disposers);
@@ -1183,8 +1323,12 @@ export function spread(options) {
             continue;
         }
         if (key === 'style') {
+            reportKeys(element, 'style', value);
             if (typeof value === 'function') {
-                disposers.push(createRenderEffect(() => setStyle(element, value())));
+                disposers.push(createRenderEffect(() => {
+                    reportReactiveBinding(element, 'attribute', 'style', value);
+                    setStyle(element, value());
+                }));
             }
             else {
                 setStyle(element, value);
@@ -1207,12 +1351,12 @@ export function spread(options) {
                 : setDynamicAttribute(element, key, value, elementIsSVG));
         }
         else {
-            // A plain, non-function value may still be backed by a reactive GETTER —
+            // A plain, non-function value may still be backed by a reactive getter:
             // component props compile to `get x() {...}`, and splitProps/mergeProps
             // forward those getters. Reading `props[key]` once (above) snapshots the
             // current value and drops the dependency, so the DOM never updates. Re-read
             // it inside a render effect so the getter's reads are tracked. (A truly
-            // static value just runs the effect once with no deps — negligible.)
+            // static value just runs the effect once with no deps: negligible.)
             disposers.push(createRenderEffect(() => asProperty
                 ? setProperty(element, key, props[key])
                 : setAttribute(element, key, props[key], elementIsSVG)));
@@ -1255,16 +1399,19 @@ export function applyProps(element, props, isSVG = false) {
             addNativeEventListener(element, key.slice(3), val);
             continue;
         }
-        // Forced bindings — see spread().
+        // Forced bindings: see spread().
         if (key.startsWith('prop:')) {
+            reportReactiveDirective(element, 'prop', key.slice(5), val);
             setDynamicProperty(element, key.slice(5), val);
             continue;
         }
         if (key.startsWith('attr:')) {
+            reportReactiveDirective(element, 'attr', key.slice(5), val);
             setDynamicAttribute(element, key.slice(5), val, isSVG);
             continue;
         }
         if (key.startsWith('bool:')) {
+            reportReactiveDirective(element, 'bool', key.slice(5), val);
             setDynamicBoolAttribute(element, key.slice(5), val);
             continue;
         }
@@ -1272,7 +1419,7 @@ export function applyProps(element, props, isSVG = false) {
             const name = key.slice(2).toLowerCase();
             if (typeof val === 'function') {
                 if (NON_DELEGATED.has(name)) {
-                    // Non-bubbling events (blur, focus, scroll…): store handler on the element
+                    // Non-bubbling events (blur, focus, scroll...): store handler on the element
                     // and attach a single stable forwarder listener. This avoids
                     // addEventListener/removeEventListener churn when a reactive scope re-runs,
                     // which would silently drop the listener via onCleanup before re-adding it.
@@ -1298,27 +1445,35 @@ export function applyProps(element, props, isSVG = false) {
             continue;
         }
         if (key === 'classList') {
+            reportKeys(element, 'class', val);
             if (typeof val === 'function')
-                createRenderEffect(() => setClassList(element, val()));
+                createRenderEffect(() => {
+                    reportReactiveBinding(element, 'attribute', 'class', val);
+                    setClassList(element, val());
+                });
             else
                 setClassList(element, val);
             continue;
         }
         if (key === 'style') {
             // An accessor reaches applyProps whenever a component forwards a computed
-            // style through a props object rather than as a compiled JSX attribute —
+            // style through a props object rather than as a compiled JSX attribute,
             // which is what every polymorphic/`as` wrapper does. class and classList
             // already handled that; style applied once and never updated.
+            reportKeys(element, 'style', val);
             if (typeof val === 'function')
-                createRenderEffect(() => setStyle(element, val()));
+                createRenderEffect(() => {
+                    reportReactiveBinding(element, 'attribute', 'style', val);
+                    setStyle(element, val());
+                });
             else
                 setStyle(element, val);
             continue;
         }
         if (key === 'innerHTML') {
-            // Accept a static string OR a reactive accessor. A function is wrapped in an effect so
+            // Accept a static string or a reactive accessor. A function is wrapped in an effect so
             // updates apply; a plain value is set once. (The previous code always called val(), which
-            // threw on a static string — wiping content during hydration.)
+            // threw on a static string, wiping content during hydration.)
             if (typeof val === 'function') {
                 const dispose = createEffect(() => {
                     let v = val();
@@ -1333,7 +1488,7 @@ export function applyProps(element, props, isSVG = false) {
             }
             continue;
         }
-        // Special case: <input>/<textarea> value — use DOM property assignment, not
+        // Special case: <input>/<textarea> value: use DOM property assignment, not
         // setAttribute. Skip reactive updates while the element has focus so user
         // input is never interrupted and focus is never lost due to signal writes.
         if (key === 'value' && (element.tagName === 'INPUT' || element.tagName === 'TEXTAREA')) {
@@ -1343,7 +1498,7 @@ export function applyProps(element, props, isSVG = false) {
                     //  console.log('apply inpit props', v, element);
                     while (typeof v === 'function' && v.length === 0)
                         v = v();
-                    // Only update if element is NOT currently focused — don't fight user input
+                    // Only update if element is not currently focused: don't fight user input
                     if (document.activeElement !== element) {
                         element.value = v ?? '';
                     }
@@ -1369,7 +1524,7 @@ export function applyProps(element, props, isSVG = false) {
                     let v = val();
                     while (typeof v === 'function' && v.length === 0)
                         v = v();
-                    // Only update if element is NOT currently focused — don't fight user input
+                    // Only update if element is not currently focused: don't fight user input
                     if (document.activeElement !== element) {
                         element.checked = v ?? '';
                     }
@@ -1377,7 +1532,7 @@ export function applyProps(element, props, isSVG = false) {
                 onCleanup(() => { dispose(); });
             }
             else {
-                // Plain value possibly behind a reactive getter — re-read live. See the
+                // Plain value possibly behind a reactive getter: re-read live. See the
                 // value branch above.
                 createRenderEffect(() => {
                     if (document.activeElement !== element) {
@@ -1387,8 +1542,8 @@ export function applyProps(element, props, isSVG = false) {
             }
             continue;
         }
-        // Special case: <select value=...> — must assign .value as DOM property
-        // AFTER options are in the DOM. We defer the initial run via queueMicrotask
+        // Special case: <select value=...>: must assign .value as DOM property
+        // after options are in the DOM. We defer the initial run via queueMicrotask
         // (children/options are inserted synchronously after applyProps returns).
         if (key === 'value' && element.tagName === 'SELECT') {
             if (typeof val === 'function') {
@@ -1408,7 +1563,7 @@ export function applyProps(element, props, isSVG = false) {
                 onCleanup(() => { dispose(); });
             }
             else {
-                // Plain value possibly behind a reactive getter — re-read live, keeping the
+                // Plain value possibly behind a reactive getter: re-read live, keeping the
                 // first assignment deferred until the options are in the DOM.
                 let firstRun = true;
                 createRenderEffect(() => {
@@ -1448,19 +1603,19 @@ export function applyProps(element, props, isSVG = false) {
     }
 }
 /**
- * Merge several (possibly reactive) prop sources into one, last-source-wins — but a later
- * source's `undefined` does NOT clobber an earlier defined value; it falls through to it. This
+ * Merge several (possibly reactive) prop sources into one, last-source-wins, but a later
+ * source's `undefined` does not clobber an earlier defined value; it falls through to it. This
  * is what makes `mergeProps(defaults, props)` work, and why the compiler can emit
  * `mergeProps(...spreads, baseProps)` for JSX spreads (`<div {...a} {...b} />`) without a missing
  * `b.x` wiping `a.x`.
  *
  * Like Solid's mergeProps (and `splitProps` above), the result is a Proxy that resolves each key
- * LAZILY off the sources — getter/signal-backed props stay live (re-read on every access, not
+ * LAZILY off the sources: getter/signal-backed props stay live (re-read on every access, not
  * snapshotted), and the key set is the union across all sources (so dynamic prop objects work).
  */
 export function mergeProps(...sources) {
     // Last defined (non-undefined) value wins; scan sources from the end so a later `undefined`
-    // falls through to an earlier source. Reads `source[key]` live each call — no snapshot.
+    // falls through to an earlier source. Reads `source[key]` live each call, no snapshot.
     const resolve = (key) => {
         for (let i = sources.length - 1; i >= 0; i--) {
             const s = sources[i];
@@ -1493,7 +1648,7 @@ export function mergeProps(...sources) {
 }
 /**
  * Split a (possibly reactive) props object into groups of keys plus a `rest`,
- * preserving reactivity — each returned object is a Proxy whose `get` forwards
+ * preserving reactivity, each returned object is a Proxy whose `get` forwards
  * to the original `props`, so a getter/signal-backed prop stays live.
  *
  *   const [local, rest] = splitProps(props, ['class', 'id']);
@@ -1536,6 +1691,12 @@ export function splitProps(props, ...keys) {
 export function handleRef(ref, element) {
     if (!ref)
         return;
+    // Which variable ends up holding the element is the question a ref raises, and only the
+    // compiler's mark on the value can answer it.
+    // The compiler's mark names the variable it is stored in; a function's own name is the
+    // next best thing.
+    const held = ref[HOLE_TAG]?.name;
+    reportReactiveDirective(element, 'ref', held || (typeof ref === 'function' ? ref.name || 'ref' : 'ref'), ref);
     // Swapped-argument guard
     if (isDomNode(ref)) {
         const actualRef = element;
@@ -1624,7 +1785,7 @@ export function isPromise(v) {
         v instanceof Promise);
 }
 // ============================================================================
-// isAccessor — deprecated, kept for backward compat
+// isAccessor: deprecated, kept for backward compat
 // ============================================================================
 export function isAccessor(value) {
     return typeof value === 'function' && value.length === 0 && isSignal(value);
@@ -1641,7 +1802,7 @@ export function render(element, container, context) {
     // This is critical for context propagation (Provider/useContext).
     createRoot((dispose) => {
         batch(() => {
-            // Clear container (but not when hydrating — we reuse the server DOM).
+            // Clear container (but not when hydrating: we reuse the server DOM).
             if (!hydration.active) {
                 container.textContent = '';
             }
@@ -1667,15 +1828,15 @@ export function render(element, container, context) {
  * Normalize what `bind:` was given into a `[read, write]` pair.
  *
  * `createSignal` hands back that pair already; `signal` hands back `{ get, set }`. Both
- * are the same primitive, so `bind:value` has to take either — steering people to the
+ * are the same primitive, so `bind:value` has to take either, steering people to the
  * new API and then refusing it in a directive would be its own kind of broken.
  */
 export function bindPair(source) {
     if (Array.isArray(source))
         return source;
-    // `signal(…)` is the accessor itself with `set` attached.
+    // `signal(...)` is the accessor itself with `set` attached.
     if (typeof source === 'function' && typeof source.set === 'function') {
         return [source, source.set];
     }
-    throw new TypeError('[fluixi] bind: needs a signal — either `signal(…)` or the `[get, set]` pair from `createSignal(…)`.');
+    throw new TypeError('[fluixi] bind: needs a signal, either `signal(...)` or the `[get, set]` pair from `createSignal(...)`.');
 }