solid-tag-runtime 0.0.14 → 0.0.15

package/ARCHITECTURE.md

@@ -1458,3 +1458,21 @@ Decision: fix wrapperless Solid 2 delegated events with the smallest ownership-p
 
 The delegation host is infrastructure only. It is not a shared application owner, is not a parent of declarative roots, is not disposed with an individual range, and does not change selector rendering or `<solid-render>` container ownership. Low-level `createRuntime()` behavior is unchanged.
 
+### 0.0.15 — declaration-driven observer scheduling
+
+Decision: harden `solid-tag-runtime/html` observation by filtering `MutationObserver` child-list records before `enqueueObserverScan()` is scheduled. The observer no longer rescans its root for arbitrary UI DOM churn.
+
+A mutation requires observer work when at least one of these is true:
+
+1. an added node is, or contains, an element matching the controller's runtime declaration selector;
+2. an added node is, or contains, `<solid-render>`, preserving observer-batch retry behavior for newly connected renderer instances;
+3. a removed subtree contains the active anchor for a mounted declarative render, so detached render ownership can still be disposed;
+4. the host MutationObserver/DOM implementation cannot be classified safely, in which case the runtime conservatively preserves the previous scan behavior.
+
+Explicit `html.flush()` remains a forced scan and does not apply mutation filtering. Empty mutation batches from custom/test `MutationObserver` implementations also retain conservative scan behavior for compatibility.
+
+Reason: HTML lifecycle subscribers, devtools, status panels, and normal application rendering may mutate DOM inside a document-scoped observer. Previously every child-list mutation queued a full discovery scan, `observer-batch` could cause subscriber UI updates, and those updates could schedule another scan indefinitely. Observer scheduling must be driven by possible runtime-declaration effects rather than arbitrary DOM activity.
+
+Invariant: unrelated DOM mutations must not enqueue runtime discovery or emit `observer-batch`. Observing `document` is therefore robust against diagnostic/application UI churn, while matching declarations and mounted-render cleanup remain live.
+
+Regression coverage: package tests verify unrelated child-list additions enqueue no observer batch, matching runtime scripts still register normally, an `observer-batch` subscriber may render unrelated DOM without recursively triggering additional scans, and relevant declaration removals still dispose mounted render ownership. The browser playground test suite carries the same feedback-loop regression against the native `MutationObserver`.

package/README.md

@@ -16,6 +16,12 @@ host Solid runtime
 
 The core package is module-first and DOM-independent. Browser discovery, ownership, declarative rendering, and `<solid-render>` live in `solid-tag-runtime/html`. Optional Solid setup/provider helpers live in `solid-tag-runtime/solid`.
 
+## 0.0.15 observer hardening
+
+`0.0.15` filters `MutationObserver` records before scheduling HTML discovery. Ordinary UI DOM changes no longer enqueue a full runtime scan or emit an `observer-batch`; matching runtime declarations, `<solid-render>` retry boundaries, and removals that can detach mounted declarative renders still trigger observer work. Explicit `html.flush()` remains a deterministic forced scan.
+
+This prevents lifecycle/devtools subscribers that render diagnostics into an observed document from creating observer → event → DOM mutation feedback loops.
+
 ## Install
 
 ```bash
@@ -211,9 +217,9 @@ When loading from an import map, map every used package subpath to the same rele
 ```json
 {
   "imports": {
-    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.14",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.14/html",
-    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.14/solid"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.15",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.15/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.15/solid"
   }
 }
 ```

package/docs/api/html.md

@@ -35,6 +35,8 @@ await html.flush(options?);
 html.disconnect();
 ```
 
+`observe()` filters child-list mutation records and schedules discovery only for mutations that can affect runtime declarations, `<solid-render>` retry work, or mounted declarative-render cleanup. `flush()` bypasses that filter and forces a scan.
+
 ## Explicit ownership
 
 ```ts

package/docs/getting-started.md

@@ -104,9 +104,9 @@ Map every used package subpath explicitly:
 ```json
 {
   "imports": {
-    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.14",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.14/html",
-    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.14/solid"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.15",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.15/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.15/solid"
   }
 }
 ```

package/docs/html-runtime.md

@@ -29,6 +29,10 @@ await html.observe({ registerExisting: false });
 await html.flush();
 ```
 
+The live observer is declaration-driven rather than mutation-driven. It inspects each `MutationRecord` before scheduling discovery and ignores ordinary UI child-list changes that cannot add a matching runtime declaration or require mounted-render cleanup. This means a document-scoped controller can coexist with application/devtools DOM updates without repeatedly rescanning the document.
+
+`flush()` is intentionally different: it remains an explicit forced scan and can be used as a deterministic synchronization point even when no relevant observer mutation was seen.
+
 ## Script declarations
 
 ```html

package/docs/lifecycle-events.md

@@ -74,4 +74,6 @@ html.subscribe("element-registered", event => {
 
 HTML events cover ownership, observation, roots, entry execution, render mounting/disposal, warnings, and errors.
 
+`observer-batch` is emitted only when observer work is actually scheduled. Unrelated child-list mutations are filtered before discovery, so a lifecycle subscriber may render diagnostics/status UI inside an observed document without causing a self-sustaining observer/event loop. Explicit `html.flush()` still performs and reports a forced scan.
+
 Listener exceptions are isolated from runtime/HTML operations and are reported to the console rather than aborting the underlying action.

package/docs/solid-runtime-setup.md

@@ -126,7 +126,7 @@ When provider fallback is needed and there is no versioned Solid anchor, this re
 import { TESTED_SOLID_VERSION } from "solid-tag-runtime/solid";
 ```
 
-For `0.0.14`, the tested fallback line is Solid `2.0.0-rc.13`.
+For `0.0.14` and `0.0.15`, the tested fallback line is Solid `2.0.0-rc.13`.
 
 If an existing Solid mapping is explicitly versioned, that version becomes the family anchor for generated siblings. An explicitly unversioned existing mapping remains unversioned; the loader does not pretend it is pinned.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {

package/src/html.js

@@ -1219,7 +1219,8 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
     }
   }
 
-  const observer = new MutationObserverImpl(() => {
+  const observer = new MutationObserverImpl(records => {
+    if (!observerMutationsRequireScan(controller, records, callOptions)) return;
     void enqueueObserverScan(controller, callOptions).catch(() => {});
   });
 
@@ -1247,6 +1248,80 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   return result;
 }
 
+function observerMutationsRequireScan(controller, records, callOptions = {}) {
+  const mutations = Array.from(records ?? []);
+
+  // MutationObserver never invokes its callback with an empty batch, but custom
+  // test/host implementations sometimes do. Preserve the historical conservative
+  // behavior for those implementations instead of silently dropping discovery.
+  if (mutations.length === 0) return true;
+
+  const selector = callOptions.selector ?? controller.selector;
+
+  for (const mutation of mutations) {
+    if (!mutation || mutation.type !== "childList") return true;
+
+    const addedNodes = mutation.addedNodes;
+    const removedNodes = mutation.removedNodes;
+    if (addedNodes == null || removedNodes == null) return true;
+
+    for (const node of Array.from(addedNodes)) {
+      if (nodeOrDescendantMatches(node, selector)) return true;
+
+      // <solid-render> is not part of the script selector, but observer batch
+      // completion is also a retry boundary for newly connected render instances.
+      if (nodeOrDescendantMatches(node, "solid-render")) return true;
+    }
+
+    for (const node of Array.from(removedNodes)) {
+      if (removedNodeContainsMountedDeclaration(controller, node)) return true;
+    }
+  }
+
+  return false;
+}
+
+function nodeOrDescendantMatches(node, selector) {
+  if (!node) return false;
+
+  try {
+    if (typeof node.matches === "function" && node.matches(selector)) return true;
+    if (typeof node.querySelector === "function" && node.querySelector(selector)) return true;
+    if (typeof node.querySelectorAll === "function" && node.querySelectorAll(selector)?.length > 0) return true;
+  } catch {
+    // A custom selector/DOM implementation that cannot be classified safely
+    // should keep the old conservative behavior rather than miss discovery.
+    return true;
+  }
+
+  // Standard DOM nodes that did not match above cannot affect discovery.
+  if (typeof node.nodeType === "number") return false;
+
+  // Unknown host DOM objects cannot be classified safely.
+  return typeof node.getAttribute === "function";
+}
+
+function removedNodeContainsMountedDeclaration(controller, node) {
+  if (!node) return false;
+
+  for (const record of controller.bindings.values()) {
+    if (!record.mount) continue;
+    const anchor = record.mount.mode === "in-place"
+      ? record.range?.startMarker
+      : record.element;
+    if (!anchor) continue;
+    if (node === anchor) return true;
+
+    try {
+      if (typeof node.contains === "function" && node.contains(anchor)) return true;
+    } catch {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 function stopObserver(controller, options = {}) {
   if (!controller.connected && !controller.observer) return;
   const root = controller.observerRoot;