solid-tag-runtime 0.0.14 → 0.0.17

package/ARCHITECTURE.md

@@ -1458,3 +1458,94 @@ 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`.
+
+
+### 0.0.16 — incremental mutation-driven observation
+
+Decision: keep the 0.0.15 declaration-driven relevance filter, but stop turning every relevant `MutationObserver` callback back into `enqueueObserverScan()`. Normal observer callbacks now derive a bounded work set directly from `MutationRecord[]`.
+
+Pipeline:
+
+```text
+MutationRecord[]
+    ↓
+collectObserverMutationBatch()
+    ├── exact added declaration elements
+    ├── exact added <solid-render> retry candidates
+    ├── tracked mounted records affected by removal
+    └── unsafe/unknown host mutation → conservative full scan
+    ↓
+enqueueObserverBatch()
+    ↓
+process exact candidates once
+```
+
+Rules:
+
+1. An added element is checked directly and only its added subtree is queried for matching declarations.
+2. Candidate identity is deduplicated across mutation records before registration.
+3. Elements already owned by the same controller are dropped before observer work is queued, so `append()`/`addModule()` do not rediscover their own DOM mutations.
+4. Relevant removals carry the exact mounted ownership records forward and dispose only records that are actually detached after the mutation batch settles.
+5. `register()`, initial `observe({ registerExisting:true })`, explicit `flush()`, and root-change registration retain full-root scan semantics.
+6. Unknown/custom DOM hosts that cannot be classified safely fall back to the previous full-root scan path.
+7. Define-before-entry/render ordering is preserved because all exact declaration candidates in one observer callback are still claimed and defined as one batch before entries/renders execute.
+
+Invariant: live observation is mutation-driven and incremental. Relevant mutation cost should scale with the changed subtree or tracked removal set, not with total root size. Full-root discovery is reserved for explicit scan operations and conservative fallback.
+
+Regression coverage adds direct-addition and nested-subtree cases that assert zero root selector calls, duplicate-record deduplication, and explicit `append()` under active observation producing no observer batch. `bench/observer.mjs` provides a synthetic scaling check comparing incremental addition with forced `flush()`.
+
+
+### 0.0.17 — explicit observation lifecycle strategies
+
+Decision: observation is a compatibility mechanism for DOM changes the runtime does not already know about, not the primary module lifecycle mechanism. Keep `observe()` continuous by default for compatibility, but add an opt-in bootstrap lifecycle for applications that only need automatic discovery during initial page/framework startup.
+
+Public modes:
+
+```text
+manual / no observer
+    html.register() + explicit APIs + optional html.flush()
+
+bootstrap / temporary observer
+    html.observe({ mode: "bootstrap", idleMs })
+
+continuous / long-lived observer
+    html.observe()
+    html.observe({ mode: "continuous" })
+```
+
+Bootstrap semantics:
+
+1. connect the normal incremental observer;
+2. optionally register existing declarations using the existing `registerExisting` behavior;
+3. remain connected through DOM readiness;
+4. only relevant observer mutations increment bootstrap activity; unrelated UI mutations do not extend observation;
+5. after `idleMs` with no new relevant activity, wait for the controller queue to drain;
+6. if activity occurred during the wait, repeat the quiet-period check;
+7. otherwise disconnect with lifecycle reason `bootstrap-idle`;
+8. a manual `disconnect()` cancels bootstrap settling;
+9. root rebinding preserves bootstrap state and resets relevant activity rather than creating a second observer;
+10. after bootstrap completes, a later `observe()` may start a fresh continuous session.
+
+Default `idleMs` is 50 ms. Invalid modes and negative/non-finite idle values are rejected.
+
+Invariant: use continuous observation only when runtime declarations may enter the DOM through code outside the runtime's explicit APIs. Controlled dynamic module loading should remain observer-free after initial registration.
+
+Regression coverage verifies continuous compatibility, bootstrap initial registration, late startup additions, unrelated mutation filtering, automatic disconnect, option validation, and re-observation after bootstrap.

package/README.md

@@ -16,6 +16,37 @@ 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.17 observation strategies
+
+`0.0.17` adds explicit observation lifecycle strategies while keeping existing behavior backward compatible. `observe()` is still continuous by default. Applications that only need DOM discovery during startup can use `observe({ mode: "bootstrap" })`; it observes through DOM readiness and disconnects after a configurable quiet period of relevant runtime mutations.
+
+```ts
+// Lowest ongoing overhead: initial scan, then explicit runtime APIs.
+await html.register();
+
+// Mostly declarative startup: temporary observer.
+await html.observe({ mode: "bootstrap", idleMs: 50 });
+
+// Unknown external DOM mutations throughout application lifetime.
+await html.observe({ mode: "continuous" });
+```
+
+Only relevant declaration/removal activity extends bootstrap lifetime. Ordinary application UI mutations do not.
+
+## 0.0.16 incremental observer processing
+
+`0.0.16` keeps the `0.0.15` declaration-driven filter but removes the normal relevant-mutation root rescan. `MutationRecord[]` are converted into exact declaration, `<solid-render>`, and mounted-removal candidates; added subtrees are queried locally and duplicate candidates are coalesced before one observer batch.
+
+Explicit APIs such as `append()` and `addModule()` claim ownership before DOM insertion, so an active observer now ignores that already-known work entirely. Full-root discovery remains available for initial registration, `flush()`, root-change registration, and conservative fallback when a host DOM cannot be classified safely.
+
+The key performance invariant is that relevant observer work scales with the changed subtree rather than total root size.
+
+## 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 +242,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.17",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.17/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.17/solid"
   }
 }
 ```

package/bench/observer.mjs

@@ -0,0 +1,103 @@
+import { performance } from "node:perf_hooks";
+import { createRuntime } from "../src/runtime.js";
+import { createHTMLRuntime } from "../src/html.js";
+
+class BenchMutationObserver {
+  static instances = [];
+  constructor(callback) { this.callback = callback; BenchMutationObserver.instances.push(this); }
+  observe(target) { this.target = target; this.connected = true; }
+  disconnect() { this.connected = false; }
+  trigger(records) { if (this.connected) this.callback(records, this); }
+}
+
+function script(id) {
+  const attrs = { type: "solid-js", module: id };
+  return {
+    nodeType: 1,
+    textContent: "export const value = 1;",
+    parentNode: null,
+    getAttribute(name) { return attrs[name] ?? null; },
+    hasAttribute(name) { return Object.prototype.hasOwnProperty.call(attrs, name); },
+    setAttribute(name, value) { attrs[name] = String(value); },
+    matches(selector) { return String(selector).includes('script[type="solid-js"]'); },
+    querySelectorAll() { return []; },
+    contains(target) { return target === this; },
+  };
+}
+
+function makeRoot(size) {
+  const filler = Array.from({ length: size }, () => ({ nodeType: 1 }));
+  const scripts = [];
+  let visited = 0;
+  return {
+    nodes: filler,
+    scripts,
+    querySelectorAll(selector) {
+      visited += this.nodes.length + this.scripts.length;
+      if (selector === "solid-render") return [];
+      return [...this.scripts];
+    },
+    contains(node) { return this.nodes.includes(node) || this.scripts.includes(node); },
+    resetVisited() { visited = 0; },
+    getVisited() { return visited; },
+  };
+}
+
+function makeRuntime() {
+  return createRuntime({
+    compiler: {
+      fingerprint: "observer-bench-v1",
+      analyze() { return { imports: [] }; },
+      transform(source) { return { code: source, diagnostics: [] }; },
+    },
+  });
+}
+
+async function waitTask() { await new Promise(resolve => setTimeout(resolve, 0)); }
+
+async function measureIncremental(size) {
+  BenchMutationObserver.instances.length = 0;
+  const runtime = makeRuntime();
+  const root = makeRoot(size);
+  const html = createHTMLRuntime(runtime, { root, MutationObserver: BenchMutationObserver });
+  await html.observe({ registerExisting: false });
+  root.resetVisited();
+  const element = script(`/incremental-${size}.js`);
+  element.parentNode = root;
+  root.scripts.push(element);
+  const t0 = performance.now();
+  BenchMutationObserver.instances[0].trigger([{ type: "childList", addedNodes: [element], removedNodes: [] }]);
+  await waitTask();
+  const ms = performance.now() - t0;
+  const visited = root.getVisited();
+  html.disconnect();
+  runtime.dispose();
+  return { ms, visited };
+}
+
+async function measureForcedScan(size) {
+  BenchMutationObserver.instances.length = 0;
+  const runtime = makeRuntime();
+  const root = makeRoot(size);
+  const html = createHTMLRuntime(runtime, { root, MutationObserver: BenchMutationObserver });
+  await html.observe({ registerExisting: false });
+  const element = script(`/scan-${size}.js`);
+  element.parentNode = root;
+  root.scripts.push(element);
+  root.resetVisited();
+  const t0 = performance.now();
+  await html.flush();
+  const ms = performance.now() - t0;
+  const visited = root.getVisited();
+  html.disconnect();
+  runtime.dispose();
+  return { ms, visited };
+}
+
+console.log("observer benchmark (synthetic root; lower visited count is the main invariant)");
+console.log("nodes\tincremental ms\tincremental visited\tflush ms\tflush visited");
+for (const size of [1_000, 10_000, 50_000]) {
+  const incremental = await measureIncremental(size);
+  const scan = await measureForcedScan(size);
+  console.log(`${size}\t${incremental.ms.toFixed(3)}\t${incremental.visited}\t${scan.ms.toFixed(3)}\t${scan.visited}`);
+}

package/docs/api/html.md

@@ -30,11 +30,19 @@ Common options:
 
 ```ts
 await html.register(options?);
-await html.observe(options?);
+await html.observe({
+  mode: "continuous" | "bootstrap",
+  idleMs: 50,
+  ...options,
+});
 await html.flush(options?);
 html.disconnect();
 ```
 
+`observe()` is continuous by default. `mode: "bootstrap"` temporarily observes startup DOM activity and resolves after DOM readiness plus `idleMs` with no relevant runtime mutations, at which point the observer is disconnected. `mode: "continuous"` retains long-lived observation.
+
+`observe()` processes relevant child-list mutation records incrementally. Added declarations are discovered from the added node/subtree itself, removals consult tracked mounted ownership, and explicit API-owned elements are skipped. A full-root scan is reserved for initial registration, `flush()`, root-change registration, or conservative fallback. `flush()` always forces a full 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.17",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.17/html",
+    "solid-tag-runtime/solid": "https://esm.sh/solid-tag-runtime@0.0.17/solid"
   }
 }
 ```

package/docs/html-runtime.md

@@ -20,15 +20,49 @@ const html = createHTMLRuntime(runtime, {
 await html.register();
 ```
 
-## Observe later declarations
+## Choose an observation strategy
+
+For controlled applications, prefer one initial scan plus explicit runtime APIs:
 
 ```ts
-await html.observe({ registerExisting: false });
+await html.register();
+
+await html.addModule(...);
+await html.append(script);
+```
+
+If raw DOM insertion is known and occasional, keep observation disabled and synchronize explicitly:
 
-// after external DOM mutations
+```ts
+root.insertAdjacentHTML("beforeend", markup);
 await html.flush();
 ```
 
+For mostly declarative startup, use a temporary bootstrap observer:
+
+```ts
+await html.observe({
+  mode: "bootstrap",
+  idleMs: 50,
+});
+```
+
+Bootstrap mode observes through DOM readiness, waits until there have been no **relevant runtime mutations** for `idleMs`, drains queued registration work, and disconnects. Ordinary UI mutations do not reset the quiet period.
+
+For pages where declarations can arrive through uncontrolled DOM code throughout the application lifetime, use continuous observation:
+
+```ts
+await html.observe({ mode: "continuous" });
+```
+
+`observe()` with no `mode` remains equivalent to continuous mode for backward compatibility.
+
+The live observer is declaration-driven and incremental. It inspects each `MutationRecord`, ignores ordinary UI child-list changes, and derives exact runtime declaration/removal candidates from relevant added or removed subtrees. Normal relevant mutations do not rescan the configured root.
+
+Added subtrees are queried only within the subtree that changed, duplicate candidates are coalesced, and elements already claimed through explicit APIs are skipped before observer work is queued. This means observer cost scales primarily with changed runtime-relevant DOM rather than total page size.
+
+`flush()` is intentionally different: it remains an explicit forced full-root scan and can be used as a deterministic synchronization point after known raw DOM insertion.
+
 ## Script declarations
 
 ```html

package/docs/lifecycle-events.md

@@ -74,4 +74,11 @@ 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 semantic observer work is scheduled. Unrelated child-list mutations are filtered before discovery, and relevant additions are processed from their exact changed subtree instead of rescanning the whole root. A lifecycle subscriber may therefore render diagnostics/status UI inside an observed document without causing a feedback loop. Explicit `html.flush()` still performs and reports a forced full-root scan.
+
 Listener exceptions are isolated from runtime/HTML operations and are reported to the console rather than aborting the underlying action.
+
+
+## Bootstrap observation lifecycle
+
+`observe({ mode: "bootstrap" })` emits the normal `observer-connected` event and later an `observer-disconnected` event with reason `bootstrap-idle` when its relevant-mutation quiet period completes. Unrelated UI DOM mutations neither emit `observer-batch` nor extend bootstrap lifetime.

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` through `0.0.17`, 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/examples/observer-strategies.js

@@ -0,0 +1,19 @@
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+export async function manual(runtime, root) {
+  const html = createHTMLRuntime(runtime, { root });
+  await html.register();
+  return html;
+}
+
+export async function bootstrap(runtime, root) {
+  const html = createHTMLRuntime(runtime, { root });
+  await html.observe({ mode: "bootstrap", idleMs: 50 });
+  return html; // disconnected after startup settles
+}
+
+export async function continuous(runtime, root) {
+  const html = createHTMLRuntime(runtime, { root });
+  await html.observe({ mode: "continuous" });
+  return html;
+}

package/html.d.ts

@@ -223,7 +223,13 @@ export type HTMLRuntimeEventType = HTMLRuntimeEvent["type"];
 export type HTMLRuntimeEventOfType<T extends HTMLRuntimeEventType> =
   Extract<HTMLRuntimeEvent, { type: T }>;
 
+export type HTMLObservationMode = "continuous" | "bootstrap";
+
 export interface ObserveHTMLOptions extends RegisterHTMLOptions {
+  /** Observation lifecycle. Default: "continuous". */
+  mode?: HTMLObservationMode;
+  /** Bootstrap-mode quiet period after DOM readiness and the last relevant mutation. Default: 50 ms. */
+  idleMs?: number;
   /** Register scripts already present when observation starts. Default: true. */
   registerExisting?: boolean;
   /** Observe descendant additions as well as direct children. Default: true. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.14",
+  "version": "0.0.17",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {
@@ -41,7 +41,8 @@
     "README.md",
     "ARCHITECTURE.md",
     "docs",
-    "examples"
+    "examples",
+    "bench"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -49,7 +50,8 @@
   },
   "scripts": {
     "test": "node ./test/run.mjs",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "bench:observer": "node ./bench/observer.mjs"
   },
   "keywords": [
     "solid",

package/src/html.js

@@ -83,6 +83,10 @@ export function createHTMLRuntime(runtime, options = {}) {
     queue: Promise.resolve(),
     lastError: undefined,
     connected: false,
+    defaultObservationMode: normalizeObservationMode(options.mode),
+    defaultBootstrapIdleMs: options.idleMs == null ? 50 : normalizeBootstrapIdleMs(options.idleMs),
+    observationMode: "continuous",
+    bootstrapState: undefined,
     registrationDepth: 0,
     registrationPasses: 0,
     solidRenderRetryScheduled: false,
@@ -202,8 +206,19 @@ export function createHTMLRuntime(runtime, options = {}) {
   async function observe(callOptions = {}) {
     if (controller.connected) return api;
 
+    const observationMode = normalizeObservationMode(callOptions.mode ?? controller.defaultObservationMode);
     const root = getRoot(mergeOptions(controller, callOptions), "HTML runtime observe");
-    controller.observerOptions = { ...callOptions };
+    controller.observationMode = observationMode;
+    controller.observerOptions = { ...callOptions, mode: observationMode };
+    controller.bootstrapState = observationMode === "bootstrap"
+      ? {
+          active: true,
+          activityVersion: 0,
+          idleMs: callOptions.idleMs == null
+            ? controller.defaultBootstrapIdleMs
+            : normalizeBootstrapIdleMs(callOptions.idleMs),
+        }
+      : undefined;
     const pendingBeforeUpgrade = collectConnectedSolidRenderElements(controller, root);
     controller.registrationDepth += 1;
 
@@ -225,6 +240,10 @@ export function createHTMLRuntime(runtime, options = {}) {
       controller.registrationDepth = Math.max(0, controller.registrationDepth - 1);
     }
 
+    if (observationMode === "bootstrap") {
+      await finishBootstrapObservation(controller, root);
+    }
+
     return api;
   }
 
@@ -279,7 +298,10 @@ export function createHTMLRuntime(runtime, options = {}) {
     const wasConnected = controller.connected;
     const previousObserverOptions = controller.observerOptions ?? {};
 
-    if (wasConnected) stopObserver(controller, { preserveOptions: true, reason: "root-change" });
+    if (wasConnected) {
+      markBootstrapObserverActivity(controller);
+      stopObserver(controller, { preserveOptions: true, preserveBootstrap: true, reason: "root-change" });
+    }
 
     controller.root = nextRoot;
     if (Object.prototype.hasOwnProperty.call(callOptions, "appendTo")) {
@@ -1196,6 +1218,80 @@ async function disposeController(controller, options = {}) {
   controller.events.clear();
 }
 
+function normalizeObservationMode(mode) {
+  if (mode == null || mode === "continuous") return "continuous";
+  if (mode === "bootstrap") return "bootstrap";
+  throw new TypeError(`Unknown HTML observation mode ${JSON.stringify(mode)}. Expected "continuous" or "bootstrap".`);
+}
+
+function normalizeBootstrapIdleMs(value) {
+  if (value == null) return 50;
+  const idleMs = Number(value);
+  if (!Number.isFinite(idleMs) || idleMs < 0) {
+    throw new TypeError("observe({ idleMs }) must be a finite non-negative number.");
+  }
+  return idleMs;
+}
+
+function markBootstrapObserverActivity(controller) {
+  const state = controller.bootstrapState;
+  if (state?.active) state.activityVersion += 1;
+}
+
+async function finishBootstrapObservation(controller, root) {
+  const state = controller.bootstrapState;
+  if (!state?.active) return;
+
+  await waitForBootstrapDOMReady(root);
+
+  while (state.active && !controller.disposed) {
+    const version = state.activityVersion;
+    await waitForBootstrapIdle(state.idleMs);
+    await controller.queue;
+
+    if (controller.lastError) {
+      const error = controller.lastError;
+      controller.lastError = undefined;
+      stopObserver(controller, { reason: "bootstrap-error" });
+      throw error;
+    }
+
+    if (!state.active || controller.disposed) return;
+    if (state.activityVersion !== version) continue;
+
+    // setRoot() may briefly disconnect/reconnect while preserving bootstrap
+    // state. Wait another turn rather than treating that transition as settled.
+    if (!controller.connected) {
+      await waitForBootstrapIdle(0);
+      continue;
+    }
+
+    stopObserver(controller, { reason: "bootstrap-idle" });
+    return;
+  }
+}
+
+function waitForBootstrapIdle(idleMs) {
+  return new Promise(resolve => {
+    const schedule = globalThis.setTimeout ?? ((callback) => Promise.resolve().then(callback));
+    schedule(resolve, idleMs);
+  });
+}
+
+function waitForBootstrapDOMReady(root) {
+  const document = root?.nodeType === 9
+    ? root
+    : root?.ownerDocument ?? (root === globalThis.document ? root : undefined);
+
+  if (!document || document.readyState !== "loading" || typeof document.addEventListener !== "function") {
+    return Promise.resolve();
+  }
+
+  return new Promise(resolve => {
+    document.addEventListener("DOMContentLoaded", resolve, { once: true });
+  });
+}
+
 async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   const MutationObserverImpl = callOptions.MutationObserver ?? controller.MutationObserver ?? globalThis.MutationObserver;
 
@@ -1219,8 +1315,17 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
     }
   }
 
-  const observer = new MutationObserverImpl(() => {
-    void enqueueObserverScan(controller, callOptions).catch(() => {});
+  const observer = new MutationObserverImpl(records => {
+    const batch = collectObserverMutationBatch(controller, records, callOptions);
+    if (!batch) return;
+    markBootstrapObserverActivity(controller);
+
+    if (batch.requiresFallbackScan) {
+      void enqueueObserverScan(controller, callOptions).catch(() => {});
+      return;
+    }
+
+    void enqueueObserverBatch(controller, batch, callOptions).catch(() => {});
   });
 
   controller.observer = observer;
@@ -1247,6 +1352,159 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   return result;
 }
 
+function collectObserverMutationBatch(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 by falling back to a full scan.
+  if (mutations.length === 0) {
+    return {
+      declarations: [],
+      solidRenders: [],
+      removedRecords: [],
+      requiresFallbackScan: true,
+    };
+  }
+
+  const selector = callOptions.selector ?? controller.selector;
+  const declarations = [];
+  const declarationSet = new Set();
+  const solidRenders = [];
+  const solidRenderSet = new Set();
+  const removedRecords = new Set();
+
+  for (const mutation of mutations) {
+    if (!mutation || mutation.type !== "childList") {
+      return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+    }
+
+    const addedNodes = mutation.addedNodes;
+    const removedNodes = mutation.removedNodes;
+    if (addedNodes == null || removedNodes == null) {
+      return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+    }
+
+    for (const node of Array.from(addedNodes)) {
+      const declarationMatches = collectNodeMatches(node, selector);
+      if (declarationMatches.uncertain) {
+        return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+      }
+      for (const element of declarationMatches.elements) {
+        // Explicit APIs claim before inserting into the DOM. If this controller
+        // already owns the element, the observer has no discovery work to do.
+        if (elementOwners.get(element)?.owner === controller) continue;
+        if (controller.ignoredExisting.has(element)) continue;
+        if (!declarationSet.has(element)) {
+          declarationSet.add(element);
+          declarations.push(element);
+        }
+      }
+
+      const renderMatches = collectNodeMatches(node, "solid-render");
+      if (renderMatches.uncertain) {
+        return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+      }
+      for (const element of renderMatches.elements) {
+        if (!solidRenderSet.has(element)) {
+          solidRenderSet.add(element);
+          solidRenders.push(element);
+        }
+      }
+    }
+
+    for (const node of Array.from(removedNodes)) {
+      const result = collectRemovedMountedRecords(controller, node, removedRecords);
+      if (!result) {
+        return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+      }
+    }
+  }
+
+  if (declarations.length === 0 && solidRenders.length === 0 && removedRecords.size === 0) {
+    return undefined;
+  }
+
+  return {
+    declarations,
+    solidRenders,
+    removedRecords: [...removedRecords],
+    requiresFallbackScan: false,
+  };
+}
+
+function collectNodeMatches(node, selector) {
+  const elements = [];
+  const seen = new Set();
+  if (!node) return { elements, uncertain: false };
+
+  let inspected = false;
+  try {
+    if (typeof node.matches === "function") {
+      inspected = true;
+      if (node.matches(selector)) {
+        seen.add(node);
+        elements.push(node);
+      }
+    }
+
+    if (typeof node.querySelectorAll === "function") {
+      inspected = true;
+      for (const element of Array.from(node.querySelectorAll(selector) ?? [])) {
+        if (seen.has(element)) continue;
+        seen.add(element);
+        elements.push(element);
+      }
+    }
+  } catch {
+    return { elements, uncertain: true };
+  }
+
+  if (inspected) return { elements, uncertain: false };
+
+  // Text/comment nodes cannot contain declarations. Element/document/fragment
+  // nodes in a standards DOM should expose matches/querySelectorAll as
+  // appropriate; a host object that does not is conservatively scanned.
+  if (typeof node.nodeType === "number") {
+    if (node.nodeType === 3 || node.nodeType === 4 || node.nodeType === 8) {
+      return { elements, uncertain: false };
+    }
+    return { elements, uncertain: true };
+  }
+
+  return {
+    elements,
+    uncertain: typeof node.getAttribute === "function" || typeof node.contains === "function",
+  };
+}
+
+function collectRemovedMountedRecords(controller, node, records) {
+  if (!node) return true;
+
+  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) {
+      records.add(record);
+      continue;
+    }
+
+    try {
+      if (typeof node.contains === "function" && node.contains(anchor)) {
+        records.add(record);
+      }
+    } catch {
+      return false;
+    }
+  }
+
+  if (typeof node.nodeType === "number" || typeof node.contains === "function") return true;
+  return typeof node.getAttribute !== "function";
+}
+
 function stopObserver(controller, options = {}) {
   if (!controller.connected && !controller.observer) return;
   const root = controller.observerRoot;
@@ -1255,6 +1513,10 @@ function stopObserver(controller, options = {}) {
   controller.observer = undefined;
   controller.observerRoot = undefined;
   if (!options.preserveOptions) controller.observerOptions = undefined;
+  if (!options.preserveBootstrap && controller.bootstrapState) {
+    controller.bootstrapState.active = false;
+    controller.bootstrapState = undefined;
+  }
   emitHTML(controller, {
     type: "observer-disconnected",
     root,
@@ -1270,54 +1532,56 @@ async function enqueueObserverScan(controller, callOptions = {}) {
     const selector = callOptions.selector ?? controller.selector;
     const origin = callOptions.origin ?? "observer";
     const discovered = Array.from(root.querySelectorAll(selector));
-    const elements = [];
-    let matched = 0;
-    let ignored = 0;
-
-    for (const element of discovered) {
-      if (controller.ignoredExisting.has(element)) {
-        ignored += 1;
-        emitHTML(controller, {
-          type: "element-discovered",
-          element,
-          moduleId: nonEmpty(element?.getAttribute?.("module")),
-          origin,
-          accepted: false,
-        });
-        continue;
-      }
+    const classified = classifyObserverElements(controller, discovered, callOptions, origin);
 
-      const accepted = acceptsDiscoveredElement(controller, element, callOptions);
-      emitHTML(controller, {
-        type: "element-discovered",
-        element,
-        moduleId: nonEmpty(element?.getAttribute?.("module")),
+    let result;
+    try {
+      result = await processElements(controller, classified.elements, {
+        ...callOptions,
+        root,
         origin,
-        accepted,
+        executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+        executeRenders: callOptions.executeRenders ?? controller.executeRenders,
       });
-      if (!accepted) {
-        ignored += 1;
-        maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
-        continue;
-      }
-      matched += 1;
+    } catch (error) {
+      emitHTMLError(controller, "observer", error, { origin });
+      throw error;
+    }
 
-      const ownership = elementOwners.get(element);
-      if (!ownership) {
-        elements.push(element);
-        continue;
-      }
-      if (ownership.owner === controller) {
-        ignored += 1;
-        continue;
-      }
+    await cleanupDetachedRenderedDeclarations(controller, root);
+    await retrySolidRenderElements(
+      controller,
+      collectConnectedSolidRenderElements(controller, root),
+      { reason: "observer-batch-complete", forceMissingError: true },
+    );
 
-      throw ownershipError(controller, element, ownership);
-    }
+    emitObserverBatch(controller, {
+      root,
+      origin,
+      discovered: discovered.length,
+      matched: classified.matched,
+      ignored: classified.ignored,
+      result,
+    });
+    return result;
+  });
+
+  trackObserverTask(controller, task, callOptions);
+  return task;
+}
+
+async function enqueueObserverBatch(controller, batch, callOptions = {}) {
+  const task = controller.queue.then(async () => {
+    if (!controller.connected) return emptyRegistrationResult();
+
+    const root = controller.observerRoot ?? getRoot(mergeOptions(controller, callOptions), "HTML runtime observer");
+    const origin = callOptions.origin ?? "observer";
+    const discovered = batch.declarations;
+    const classified = classifyObserverElements(controller, discovered, callOptions, origin);
 
     let result;
     try {
-      result = await processElements(controller, elements, {
+      result = await processElements(controller, classified.elements, {
         ...callOptions,
         root,
         origin,
@@ -1329,26 +1593,106 @@ async function enqueueObserverScan(controller, callOptions = {}) {
       throw error;
     }
 
-    await cleanupDetachedRenderedDeclarations(controller, root);
+    await cleanupRemovedRenderedDeclarations(controller, root, batch.removedRecords);
     await retrySolidRenderElements(
       controller,
-      collectConnectedSolidRenderElements(controller, root),
+      batch.solidRenders,
       { reason: "observer-batch-complete", forceMissingError: true },
     );
 
-    emitHTML(controller, {
-      type: "observer-batch",
+    emitObserverBatch(controller, {
       root,
       origin,
       discovered: discovered.length,
-      matched,
-      claimed: result.modules.length,
-      ignored,
-      modules: result.modules.map(module => module.id),
+      matched: classified.matched,
+      ignored: classified.ignored,
+      result,
     });
     return result;
   });
 
+  trackObserverTask(controller, task, callOptions);
+  return task;
+}
+
+function classifyObserverElements(controller, discovered, callOptions, origin) {
+  const elements = [];
+  let matched = 0;
+  let ignored = 0;
+
+  for (const element of discovered) {
+    if (controller.ignoredExisting.has(element)) {
+      ignored += 1;
+      emitHTML(controller, {
+        type: "element-discovered",
+        element,
+        moduleId: nonEmpty(element?.getAttribute?.("module")),
+        origin,
+        accepted: false,
+      });
+      continue;
+    }
+
+    const accepted = acceptsDiscoveredElement(controller, element, callOptions);
+    emitHTML(controller, {
+      type: "element-discovered",
+      element,
+      moduleId: nonEmpty(element?.getAttribute?.("module")),
+      origin,
+      accepted,
+    });
+    if (!accepted) {
+      ignored += 1;
+      maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
+      continue;
+    }
+    matched += 1;
+
+    const ownership = elementOwners.get(element);
+    if (!ownership) {
+      elements.push(element);
+      continue;
+    }
+    if (ownership.owner === controller) {
+      ignored += 1;
+      continue;
+    }
+
+    throw ownershipError(controller, element, ownership);
+  }
+
+  return { elements, matched, ignored };
+}
+
+async function cleanupRemovedRenderedDeclarations(controller, root, records) {
+  for (const record of records ?? []) {
+    if (!record?.mount) continue;
+    const anchor = record.mount.mode === "in-place"
+      ? record.range?.startMarker
+      : record.element;
+    if (!anchor || rootContainsElement(root, anchor)) continue;
+
+    await disposeRecordMount(controller, record, {
+      reason: "declaration-detached",
+      removeAnchors: false,
+    });
+  }
+}
+
+function emitObserverBatch(controller, { root, origin, discovered, matched, ignored, result }) {
+  emitHTML(controller, {
+    type: "observer-batch",
+    root,
+    origin,
+    discovered,
+    matched,
+    claimed: result.modules.length,
+    ignored,
+    modules: result.modules.map(module => module.id),
+  });
+}
+
+function trackObserverTask(controller, task, callOptions) {
   controller.queue = task.then(
     () => undefined,
     error => {
@@ -1360,8 +1704,6 @@ async function enqueueObserverScan(controller, callOptions = {}) {
       }
     },
   );
-
-  return task;
 }
 
 async function processElements(controller, elements, options = {}) {