solid-tag-runtime 0.0.15 → 0.0.18

package/src/html.js

@@ -1,6 +1,7 @@
 import { ModuleResolutionError, SolidTagRuntimeError } from "./errors.js";
 import { createEventDispatcher } from "./events.js";
 import { HTMLRenderError, createDefaultHTMLRenderAdapter, resolveRenderComponent } from "./render.js";
+import { parseHTMLDataLiteral, parseHTMLPropsObject } from "./html/data-literal.js";
 
 const DEFAULT_SELECTOR = [
   'script[type="solid-jsx"]',
@@ -12,6 +13,10 @@ const DEFAULT_SELECTOR = [
 ].join(",");
 
 const RUNTIME_SCOPE_ATTRIBUTE = "data-solid-runtime";
+const SOLID_RENDER_STATE_ATTRIBUTE = "data-solid-render-state";
+const SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE = "show-until-ready";
+const SOLID_RENDER_VISIBILITY_STYLE_ATTRIBUTE = "data-solid-tag-render-visibility";
+const solidRenderVisibilityDocuments = new WeakSet();
 const elementOwners = new WeakMap();
 const defaultControllers = new WeakMap();
 const activeControllers = new Set();
@@ -73,6 +78,7 @@ export function createHTMLRuntime(runtime, options = {}) {
     createElement: options.createElement,
     appendTo: options.appendTo,
     renderAdapter: options.renderAdapter ?? createDefaultHTMLRenderAdapter(runtime),
+    parseProps: typeof options.parseProps === "function" ? options.parseProps : undefined,
     bindings: new Map(),
     renderElements: new Set(),
     disposed: false,
@@ -83,6 +89,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,
@@ -130,6 +140,7 @@ export function createHTMLRuntime(runtime, options = {}) {
 
   controller.api = api;
   activeControllers.add(controller);
+  ensureSolidRenderVisibilityStyle(resolveControllerDocument(controller));
   // Do not define/upgrade <solid-render> here. Existing declarative script
   // modules must be installed first; otherwise connectedCallback() can import
   // a module before register()/observe() has defined the preceding <script>.
@@ -202,8 +213,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 +247,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 +305,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")) {
@@ -645,6 +674,7 @@ export const htmlRuntimeScopeAttribute = RUNTIME_SCOPE_ATTRIBUTE;
  * browser; programmatic-only applications may call it explicitly.
  */
 export function registerSolidRenderElement(options = {}) {
+  ensureSolidRenderVisibilityStyle(options.document ?? globalThis.document);
   const registry = options.customElements ?? globalThis.customElements;
   const HTMLElementBase = options.HTMLElement ?? globalThis.HTMLElement;
   if (!registry || typeof registry.define !== "function" || typeof registry.get !== "function" || typeof HTMLElementBase !== "function") {
@@ -658,7 +688,7 @@ export function registerSolidRenderElement(options = {}) {
 
   class SolidRenderElement extends HTMLElementBase {
     static get observedAttributes() {
-      return ["module", "component", RUNTIME_SCOPE_ATTRIBUTE];
+      return ["module", "component", RUNTIME_SCOPE_ATTRIBUTE, SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE];
     }
 
     constructor() {
@@ -674,13 +704,16 @@ export function registerSolidRenderElement(options = {}) {
         propObserver: undefined,
         pendingModuleResolution: undefined,
         pendingCheckGeneration: undefined,
+        renderState: "pending",
       });
     }
 
     connectedCallback() {
       const state = getSolidRenderState(this);
       state.connected = true;
+      setSolidRenderState(this, state, "pending");
       captureSolidRenderChildren(this, state);
+      syncSolidRenderPendingContent(this, state);
       startSolidRenderPropObserver(this, state);
       void remountSolidRender(this, "connect");
     }
@@ -698,9 +731,26 @@ export function registerSolidRenderElement(options = {}) {
       if (oldValue === newValue) return;
       const state = getSolidRenderState(this);
       if (!state.connected) return;
+      if (name === SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE) {
+        syncSolidRenderPendingContent(this, state);
+        return;
+      }
       void remountSolidRender(this, `identity:${name}`);
     }
 
+    get renderState() {
+      return getSolidRenderState(this).renderState;
+    }
+
+    get hideUntilReady() {
+      return !this.hasAttribute?.(SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE);
+    }
+
+    set hideUntilReady(value) {
+      if (value === false) this.setAttribute?.(SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE, "");
+      else this.removeAttribute?.(SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE);
+    }
+
     get props() {
       return getSolidRenderState(this).programmaticProps;
     }
@@ -731,12 +781,78 @@ function getSolidRenderState(element) {
       propObserver: undefined,
       pendingModuleResolution: undefined,
       pendingCheckGeneration: undefined,
+      renderState: "pending",
     };
     solidRenderInternals.set(element, state);
   }
   return state;
 }
 
+
+function resolveControllerDocument(controller) {
+  const root = controller?.root ?? globalThis.document;
+  if (root && typeof root.createElement === "function" && (root.head || root.documentElement || root.body)) return root;
+  return root?.ownerDocument ?? globalThis.document;
+}
+
+function ensureSolidRenderVisibilityStyle(document) {
+  if (!document || (typeof document !== "object" && typeof document !== "function")) return;
+  if (solidRenderVisibilityDocuments.has(document)) return;
+
+  try {
+    if (document.querySelector?.(`style[${SOLID_RENDER_VISIBILITY_STYLE_ATTRIBUTE}]`)) {
+      solidRenderVisibilityDocuments.add(document);
+      return;
+    }
+    if (typeof document.createElement !== "function") return;
+    const style = document.createElement("style");
+    style.setAttribute?.(SOLID_RENDER_VISIBILITY_STYLE_ATTRIBUTE, "");
+    style.textContent = [
+      `solid-render:not([${SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE}]):not(:defined),`,
+      `solid-render:not([${SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE}])[${SOLID_RENDER_STATE_ATTRIBUTE}="pending"] {`,
+      "  visibility: hidden !important;",
+      "}",
+    ].join("\n");
+    const target = document.head ?? document.documentElement ?? document.body;
+    if (typeof target?.append === "function") target.append(style);
+    else if (typeof target?.appendChild === "function") target.appendChild(style);
+    else return;
+    solidRenderVisibilityDocuments.add(document);
+  } catch {
+    // Styling is a progressive enhancement for pre-upgrade visibility. The
+    // custom element still manages pending/ready/error state in JavaScript.
+  }
+}
+
+function setSolidRenderState(element, state, nextState) {
+  state.renderState = nextState;
+  element.setAttribute?.(SOLID_RENDER_STATE_ATTRIBUTE, nextState);
+}
+
+function cloneSolidRenderFallbackNodes(state) {
+  const clone = state.childrenTemplate?.cloneNode?.(true);
+  if (!clone) return [];
+  if (clone.childNodes) return Array.from(clone.childNodes);
+  return [clone];
+}
+
+function restoreSolidRenderFallback(element, state) {
+  if (!state.childrenTemplate) {
+    element.replaceChildren?.();
+    return;
+  }
+  element.replaceChildren?.(...cloneSolidRenderFallbackNodes(state));
+}
+
+function syncSolidRenderPendingContent(element, state) {
+  if (state.renderState !== "pending" || state.mount) return;
+  if (element.hasAttribute?.(SOLID_RENDER_SHOW_UNTIL_READY_ATTRIBUTE)) {
+    restoreSolidRenderFallback(element, state);
+  } else {
+    element.replaceChildren?.();
+  }
+}
+
 function captureSolidRenderChildren(element, state) {
   if (state.captured) return;
   state.captured = true;
@@ -762,7 +878,11 @@ function startSolidRenderPropObserver(element, state) {
   if (typeof MutationObserverImpl !== "function") return;
 
   const observer = new MutationObserverImpl(records => {
-    if (!Array.from(records ?? []).some(record => String(record?.attributeName ?? "").startsWith("prop:"))) return;
+    const relevant = Array.from(records ?? []).some(record => {
+      const name = String(record?.attributeName ?? "").toLowerCase();
+      return name === "props" || name.startsWith("prop:");
+    });
+    if (!relevant) return;
     updateSolidRenderProps(element, state);
   });
   observer.observe(element, { attributes: true });
@@ -775,8 +895,10 @@ async function remountSolidRender(element, reason, options = {}) {
   const generation = ++state.generation;
   state.pendingModuleResolution = undefined;
   state.pendingCheckGeneration = undefined;
+  setSolidRenderState(element, state, "pending");
   await disposeSolidRenderMount(element, state, reason === "connect" ? "reconnect" : reason);
   if (!state.connected || generation !== state.generation) return;
+  syncSolidRenderPendingContent(element, state);
 
   let controller;
   try {
@@ -790,7 +912,7 @@ async function remountSolidRender(element, reason, options = {}) {
     }
     const componentName = nonEmpty(element.getAttribute?.("component"));
     const exportName = componentName ?? "default";
-    const props = buildSolidRenderProps(element, state);
+    const props = buildSolidRenderProps(element, state, controller);
 
     emitHTML(controller, {
       type: "render-mounting",
@@ -827,6 +949,7 @@ async function remountSolidRender(element, reason, options = {}) {
     state.mount = mount;
     state.pendingModuleResolution = undefined;
     state.pendingCheckGeneration = undefined;
+    setSolidRenderState(element, state, "ready");
     emitHTML(controller, {
       type: "render-mounted",
       element,
@@ -862,6 +985,8 @@ async function remountSolidRender(element, reason, options = {}) {
       }
     }
 
+    setSolidRenderState(element, state, "error");
+    if (!state.mount) restoreSolidRenderFallback(element, state);
     if (controller) {
       emitHTMLError(controller, "solid-render", error, {
         element,
@@ -922,20 +1047,44 @@ async function disposeSolidRenderMount(element, state, reason = "dispose") {
 
 function updateSolidRenderProps(element, state) {
   if (!state.mount?.updateProps) return;
-  state.mount.updateProps(buildSolidRenderProps(element, state));
+  let controller = state.controller;
+  try {
+    controller ??= resolveHTMLControllerForElement(element);
+    const props = buildSolidRenderProps(element, state, controller);
+    state.mount.updateProps(props);
+    setSolidRenderState(element, state, "ready");
+  } catch (error) {
+    setSolidRenderState(element, state, "error");
+    if (controller) {
+      emitHTMLError(controller, "solid-render", error, {
+        element,
+        moduleId: nonEmpty(element.getAttribute?.("module")),
+        origin: "solid-render",
+      });
+    }
+    dispatchSolidRenderError(element, error);
+  }
 }
 
-function buildSolidRenderProps(element, state) {
+function buildSolidRenderProps(element, state, controller) {
   const declarative = {};
+  const bulk = parseSolidRenderBulkProps(element, controller);
+  copyPropRecord(declarative, bulk);
+
   for (const attribute of Array.from(element.attributes ?? [])) {
-    const name = String(attribute?.name ?? "").toLowerCase();
+    const rawName = String(attribute?.name ?? "");
+    const name = rawName.toLowerCase();
     if (!name.startsWith("prop:")) continue;
     const key = kebabToCamel(name.slice(5));
     if (!key) continue;
-    declarative[key] = attribute.value === "" ? true : attribute.value;
+    declarative[key] = parseSolidRenderAttributeProp(element, controller, key, attribute.value);
   }
 
-  if (state.childrenTemplate && !("children" in (state.programmaticProps ?? {}))) {
+  if (
+    state.childrenTemplate
+    && !("children" in declarative)
+    && !("children" in (state.programmaticProps ?? {}))
+  ) {
     Object.defineProperty(declarative, "children", {
       configurable: true,
       enumerable: true,
@@ -946,14 +1095,69 @@ function buildSolidRenderProps(element, state) {
   }
 
   const merged = Object.create(null);
-  for (const key of Reflect.ownKeys(declarative)) {
-    const descriptor = Object.getOwnPropertyDescriptor(declarative, key);
-    if (descriptor) Object.defineProperty(merged, key, descriptor);
+  copyPropRecord(merged, declarative);
+  copyPropRecord(merged, state.programmaticProps ?? {});
+  return merged;
+}
+
+function copyPropRecord(target, source) {
+  for (const key of Reflect.ownKeys(source ?? {})) {
+    const descriptor = Object.getOwnPropertyDescriptor(source, key);
+    if (descriptor) Object.defineProperty(target, key, descriptor);
   }
-  for (const key of Reflect.ownKeys(state.programmaticProps ?? {})) {
-    merged[key] = state.programmaticProps[key];
+  return target;
+}
+
+function parseSolidRenderBulkProps(element, controller) {
+  const source = element.getAttribute?.("props");
+  if (source == null || String(source).trim() === "") return {};
+  const value = parseSolidRenderData(controller, String(source), {
+    element,
+    kind: "props",
+    attribute: "props",
+  });
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new HTMLRenderError("<solid-render> `props` must parse to a top-level object.", { element });
+  }
+  return value;
+}
+
+function parseSolidRenderAttributeProp(element, controller, key, source) {
+  if (source === "") return true;
+  const raw = String(source);
+  const trimmed = raw.trim();
+  if (!(trimmed.startsWith("{") && trimmed.endsWith("}"))) return raw;
+
+  const inner = trimmed.slice(1, -1).trim();
+  if (!inner) {
+    throw new HTMLRenderError(
+      `<solid-render> prop:${key} uses an outer brace pair for typed data; the inner value cannot be empty.`,
+      { element },
+    );
+  }
+  return parseSolidRenderData(controller, inner, {
+    element,
+    kind: "prop",
+    attribute: `prop:${key}`,
+    key,
+  });
+}
+
+function parseSolidRenderData(controller, source, context) {
+  try {
+    if (typeof controller?.parseProps === "function") {
+      return controller.parseProps(source, context);
+    }
+    return context.kind === "props"
+      ? parseHTMLPropsObject(source)
+      : parseHTMLDataLiteral(source);
+  } catch (cause) {
+    const label = context.kind === "props" ? "props" : context.attribute;
+    throw new HTMLRenderError(
+      `<solid-render> could not parse ${label} as declarative data: ${cause?.message ?? cause}`,
+      { element: context.element, cause },
+    );
   }
-  return merged;
 }
 
 function kebabToCamel(value) {
@@ -1196,6 +1400,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;
 
@@ -1220,8 +1498,16 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   }
 
   const observer = new MutationObserverImpl(records => {
-    if (!observerMutationsRequireScan(controller, records, callOptions)) return;
-    void enqueueObserverScan(controller, callOptions).catch(() => {});
+    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;
@@ -1248,61 +1534,134 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   return result;
 }
 
-function observerMutationsRequireScan(controller, records, callOptions = {}) {
+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 instead of silently dropping discovery.
-  if (mutations.length === 0) return true;
+  // 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 true;
+    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 true;
+    if (addedNodes == null || removedNodes == null) {
+      return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+    }
 
     for (const node of Array.from(addedNodes)) {
-      if (nodeOrDescendantMatches(node, selector)) return true;
+      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);
+        }
+      }
 
-      // <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;
+      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)) {
-      if (removedNodeContainsMountedDeclaration(controller, node)) return true;
+      const result = collectRemovedMountedRecords(controller, node, removedRecords);
+      if (!result) {
+        return { declarations, solidRenders, removedRecords: [...removedRecords], requiresFallbackScan: true };
+      }
     }
   }
 
-  return false;
+  if (declarations.length === 0 && solidRenders.length === 0 && removedRecords.size === 0) {
+    return undefined;
+  }
+
+  return {
+    declarations,
+    solidRenders,
+    removedRecords: [...removedRecords],
+    requiresFallbackScan: false,
+  };
 }
 
-function nodeOrDescendantMatches(node, selector) {
-  if (!node) return 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" && 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;
+    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 {
-    // A custom selector/DOM implementation that cannot be classified safely
-    // should keep the old conservative behavior rather than miss discovery.
-    return true;
+    return { elements, uncertain: true };
   }
 
-  // Standard DOM nodes that did not match above cannot affect discovery.
-  if (typeof node.nodeType === "number") return false;
+  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 };
+  }
 
-  // Unknown host DOM objects cannot be classified safely.
-  return typeof node.getAttribute === "function";
+  return {
+    elements,
+    uncertain: typeof node.getAttribute === "function" || typeof node.contains === "function",
+  };
 }
 
-function removedNodeContainsMountedDeclaration(controller, node) {
-  if (!node) return false;
+function collectRemovedMountedRecords(controller, node, records) {
+  if (!node) return true;
 
   for (const record of controller.bindings.values()) {
     if (!record.mount) continue;
@@ -1310,16 +1669,22 @@ function removedNodeContainsMountedDeclaration(controller, node) {
       ? record.range?.startMarker
       : record.element;
     if (!anchor) continue;
-    if (node === anchor) return true;
+    if (node === anchor) {
+      records.add(record);
+      continue;
+    }
 
     try {
-      if (typeof node.contains === "function" && node.contains(anchor)) return true;
+      if (typeof node.contains === "function" && node.contains(anchor)) {
+        records.add(record);
+      }
     } catch {
-      return true;
+      return false;
     }
   }
 
-  return false;
+  if (typeof node.nodeType === "number" || typeof node.contains === "function") return true;
+  return typeof node.getAttribute !== "function";
 }
 
 function stopObserver(controller, options = {}) {
@@ -1330,6 +1695,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,
@@ -1345,54 +1714,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,
@@ -1404,26 +1775,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 => {
@@ -1435,8 +1886,6 @@ async function enqueueObserverScan(controller, callOptions = {}) {
       }
     },
   );
-
-  return task;
 }
 
 async function processElements(controller, elements, options = {}) {