solid-tag-runtime 0.0.5 → 0.0.6

package/ARCHITECTURE.md

@@ -235,6 +235,10 @@ html.observe(options?);
 html.flush(options?);
 html.disconnect();
 
+await html.setRoot(root, options?);
+await html.moveTo(root, options?);
+html.setAppendTarget(target);
+
 html.defineElement(element, options?);
 html.registerElement(element, options?);
 html.append(element, options?);
@@ -321,6 +325,45 @@ A scoped controller accepts matching scripts. It may also claim unscoped scripts
 
 An unscoped controller does not silently claim a script carrying `data-solid-runtime` for another runtime.
 
+
+### Mutable root and append-target semantics
+
+`0.0.6` makes the HTML controller's DOM boundaries mutable without replacing the controller or core runtime.
+
+The discovery root may be any DOM-like container that supports `querySelectorAll()` and can be observed by `MutationObserver`, including browser `Document`, `Element`, `DocumentFragment`, and `ShadowRoot`.
+
+```ts
+await html.setRoot(nextRoot, {
+  registerExisting: true,
+});
+
+await html.moveTo(nextRoot);
+html.setAppendTarget(target);
+```
+
+The two boundaries remain distinct:
+
+```text
+root
+  one-shot discovery + MutationObserver target
+
+appendTarget
+  default destination for append()/addModule()
+```
+
+Important invariants:
+
+1. Reparenting the exact same observed root node does not require rebinding; MutationObserver follows node identity rather than the node's former parent.
+2. Replacing that root with a different node requires `setRoot()`/`moveTo()` for the controller to observe the new subtree.
+3. A connected controller stays connected when `setRoot()` changes the node: pending work against the old root is drained, the old observer target is disconnected, and observation is rebound to the new root.
+4. Connected root changes register matching scripts already present in the new root by default; `registerExisting: false` opts out.
+5. Disconnected `setRoot()` is configuration-only by default; `registerExisting: true` explicitly performs a one-shot scan.
+6. `moveTo()` changes both discovery root and append target. For a `Document`, its body/documentElement is chosen as the append target rather than appending directly beside the document element.
+7. `setAppendTarget()` never changes observation.
+8. Root rebinding does not reset module ownership or the runtime graph. Elements already owned remain owned; module IDs remain reserved by the same controller.
+
+Each HTML runtime controller owns its own MutationObserver instance. The observer is attached directly to the selected root; the implementation does not observe the entire document and then perform containment filtering. This keeps unrelated DOM mutation traffic out of the controller and correctly supports isolated `ShadowRoot` trees.
+
 ### User-created script elements
 
 Applications may create the element themselves and explicitly associate it with one runtime:
@@ -926,3 +969,14 @@ Invariant: invalidation must result in a fresh executable module identity on the
 
 Regression coverage: host-module replacement must update already-imported dependents, and explicit `runtime.invalidate()` must cause a side-effecting module to evaluate again on the next import.
 
+
+
+### 0.0.6 — mutable HTML runtime roots and append targets
+
+Decision: HTML runtime controllers now expose `setRoot()`, `moveTo()`, and `setAppendTarget()`, plus `root` and `appendTarget` introspection. A connected observer is rebound directly to the new root rather than keeping a document-wide observer and filtering by containment.
+
+Reason: applications can reparent an existing observed root without intervention, but replacing a mount/container with a different DOM node would otherwise leave the observer and append destination attached to stale nodes. Explicit mutable boundaries preserve one controller/module graph while allowing UI containers, previews, micro-frontends, and shadow roots to move during application lifetime.
+
+Invariant: a root change must not create a second observer, lose ownership records, or race pending scans from the old root. Pending observer work is drained before rebinding. A live root change registers existing scripts in the new root by default; a disconnected root change does not perform discovery unless requested.
+
+Regression coverage: the suite verifies same-node reparenting, live root rebinding, skipping existing scripts, disconnected root changes, `moveTo()` synchronization of root/append target, and independent append-target changes.

package/README.md

@@ -270,9 +270,71 @@ solid-module                → infer from module/src extension
 
 `language="js"` or `language="jsx"` may override inference.
 
+
+### Change the observed root
+
+The HTML controller can move to a different discovery root without creating a new runtime:
+
+```ts
+const first = document.querySelector("#first-runtime")!;
+const second = document.querySelector("#second-runtime")!;
+
+const html = createHTMLRuntime(runtime, {
+  root: first,
+  appendTo: first,
+});
+
+await html.observe({ registerExisting: false });
+
+// Rebind a live observer to a different node. Because the observer is already
+// connected, matching scripts already in the new root are registered by default.
+await html.setRoot(second);
+```
+
+If the controller is disconnected, `setRoot()` only changes configuration unless `registerExisting: true` is passed:
+
+```ts
+await html.setRoot(second, {
+  registerExisting: true,
+});
+```
+
+Use `registerExisting: false` when switching a live observer but intentionally ignoring scripts already present in the new root.
+
+Moving the **same root node** elsewhere in the DOM does not require `setRoot()`. `MutationObserver` remains attached to that node object even when it is reparented.
+
+### Move root and append target together
+
+When the runtime module area itself moves to another container, `moveTo()` changes both boundaries:
+
+```ts
+await html.moveTo(nextContainer, {
+  registerExisting: true,
+});
+```
+
+For an `Element`, `DocumentFragment`, or `ShadowRoot`, future `append()` / `addModule()` calls insert into that root. For a `Document`, the controller chooses the document body (or document element fallback) as the append target.
+
+### Change only the append target
+
+Observation and insertion can have different boundaries:
+
+```ts
+html.setAppendTarget(document.head);
+```
+
+This does not change the currently observed root. The controller exposes the active values for diagnostics:
+
+```ts
+html.root;
+html.appendTarget;
+```
+
+The `root` may be a `Document`, normal `Element`, `DocumentFragment`, or `ShadowRoot` (which is a `DocumentFragment`). A controller observes the selected root directly rather than observing the whole document and filtering mutations afterward.
+
 ### Addition-only observation
 
-Observation remains addition-only in `0.0.5`.
+Observation remains addition-only in `0.0.6`.
 
 Changing the source/attributes of an already owned script or removing it from the DOM does not implicitly update/delete the corresponding runtime module. Use `runtime.update()` / `runtime.invalidate()` for explicit module lifecycle changes.
 

package/html.d.ts

@@ -5,6 +5,7 @@ export interface HTMLModuleScriptElement {
   textContent?: string | null;
   baseURI?: string;
   ownerDocument?: HTMLDocumentLike | null;
+  parentNode?: unknown;
   getAttribute(name: string): string | null;
   hasAttribute?(name: string): boolean;
   setAttribute?(name: string, value: string): void;
@@ -119,10 +120,24 @@ export interface HTMLRuntimeOptions extends ObserveHTMLOptions {
   createElement?: (tagName: string) => HTMLModuleScriptElement;
 }
 
+export interface SetHTMLRootOptions extends RegisterHTMLOptions {
+  /**
+   * Register matching scripts already present in the new root.
+   * Defaults to true when rebinding a connected observer and false otherwise.
+   */
+  registerExisting?: boolean;
+  /** Optionally update the controller's default append target at the same time. */
+  appendTo?: HTMLAppendTarget;
+}
+
 export interface HTMLRuntimeController {
   readonly runtime: SolidTagRuntime;
   readonly scope?: string;
   readonly connected: boolean;
+  /** Current configured/effective discovery root when available. */
+  readonly root?: HTMLModuleRoot;
+  /** Current effective target used by append()/addModule() when available. */
+  readonly appendTarget?: HTMLAppendTarget;
   /** Result of the observer's initial scan. */
   readonly initial: RegisterHTMLResult;
 
@@ -136,6 +151,24 @@ export interface HTMLRuntimeController {
   flush(options?: RegisterHTMLOptions): Promise<RegisterHTMLResult>;
   disconnect(): void;
 
+  /**
+   * Change the discovery/observation root. A connected observer is rebound to
+   * the new node automatically.
+   */
+  setRoot(
+    root: HTMLModuleRoot,
+    options?: SetHTMLRootOptions,
+  ): Promise<RegisterHTMLResult>;
+
+  /** Change both the discovery root and append target to the selected root. */
+  moveTo(
+    root: HTMLModuleRoot,
+    options?: SetHTMLRootOptions,
+  ): Promise<RegisterHTMLResult>;
+
+  /** Change only where append()/addModule() insert future elements. */
+  setAppendTarget(target: HTMLAppendTarget): HTMLRuntimeController;
+
   /** Define one element without auto-running an entry. */
   defineElement(
     element: HTMLModuleScriptElement,

package/package.json

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

package/src/html.js

@@ -61,6 +61,7 @@ export function createHTMLRuntime(runtime, options = {}) {
     bindings: new Map(),
     observer: undefined,
     observerRoot: undefined,
+    observerOptions: undefined,
     ignoredExisting: new WeakSet(),
     queue: Promise.resolve(),
     lastError: undefined,
@@ -81,10 +82,19 @@ export function createHTMLRuntime(runtime, options = {}) {
     get initial() {
       return controller.initial;
     },
+    get root() {
+      return controller.root ?? globalThis.document;
+    },
+    get appendTarget() {
+      return getAppendTarget(controller);
+    },
     register,
     observe,
     flush,
     disconnect,
+    setRoot,
+    moveTo,
+    setAppendTarget,
     defineElement,
     registerElement,
     append,
@@ -120,47 +130,14 @@ export function createHTMLRuntime(runtime, options = {}) {
   async function observe(callOptions = {}) {
     if (controller.connected) return api;
 
-    const merged = mergeOptions(controller, callOptions);
-    const root = getRoot(merged, "HTML runtime observe");
-    const MutationObserverImpl = callOptions.MutationObserver ?? controller.MutationObserver ?? globalThis.MutationObserver;
-
-    if (typeof MutationObserverImpl !== "function") {
-      throw new TypeError(
-        "observe() requires MutationObserver support or a MutationObserver option.",
-      );
-    }
-
-    controller.observerRoot = root;
-    controller.connected = true;
-    controller.lastError = undefined;
-    controller.ignoredExisting = new WeakSet();
-
-    if (callOptions.registerExisting === false) {
-      for (const element of Array.from(root.querySelectorAll(callOptions.selector ?? controller.selector))) {
-        if (acceptsDiscoveredElement(controller, element, callOptions)) {
-          controller.ignoredExisting.add(element);
-        }
-      }
-      controller.initial = emptyRegistrationResult();
-    }
-
-    const observer = new MutationObserverImpl(() => {
-      void enqueueObserverScan(controller, callOptions).catch(() => {});
-    });
-
-    controller.observer = observer;
-    observer.observe(root, {
-      childList: true,
-      subtree: callOptions.subtree ?? controller.subtree,
-    });
+    const root = getRoot(mergeOptions(controller, callOptions), "HTML runtime observe");
+    controller.observerOptions = { ...callOptions };
 
     try {
-      if (callOptions.registerExisting !== false) {
-        controller.initial = await enqueueObserverScan(controller, {
-          ...callOptions,
-          origin: "observer-initial",
-        });
-      }
+      controller.initial = await connectObserver(controller, root, callOptions, {
+        registerExisting: callOptions.registerExisting !== false,
+        initial: true,
+      });
     } catch (error) {
       disconnect();
       throw error;
@@ -184,11 +161,80 @@ export function createHTMLRuntime(runtime, options = {}) {
   }
 
   function disconnect() {
-    if (!controller.connected) return;
-    controller.connected = false;
-    controller.observer?.disconnect();
-    controller.observer = undefined;
-    controller.observerRoot = undefined;
+    stopObserver(controller);
+  }
+
+  /**
+   * Change the discovery/observation root. If observation is active, it is
+   * rebound to the new root and existing matching scripts are registered by
+   * default. When disconnected, changing the root is configuration-only unless
+   * registerExisting:true is requested.
+   */
+  async function setRoot(root, callOptions = {}) {
+    const nextRoot = getRoot({ root }, "HTML runtime setRoot");
+
+    // Finish work scheduled against the old root before rebinding observer state.
+    await controller.queue;
+    if (controller.lastError) {
+      const error = controller.lastError;
+      controller.lastError = undefined;
+      throw error;
+    }
+
+    const wasConnected = controller.connected;
+    const previousObserverOptions = controller.observerOptions ?? {};
+
+    if (wasConnected) stopObserver(controller, { preserveOptions: true });
+
+    controller.root = nextRoot;
+    if (Object.prototype.hasOwnProperty.call(callOptions, "appendTo")) {
+      controller.appendTo = callOptions.appendTo;
+    }
+
+    const registerExisting = callOptions.registerExisting ?? wasConnected;
+
+    if (wasConnected) {
+      const observeOptions = {
+        ...previousObserverOptions,
+        ...callOptions,
+        root: nextRoot,
+        registerExisting,
+      };
+      controller.observerOptions = { ...observeOptions };
+      try {
+        return await connectObserver(controller, nextRoot, observeOptions, {
+          registerExisting,
+          initial: false,
+        });
+      } catch (error) {
+        stopObserver(controller, { preserveOptions: true });
+        throw error;
+      }
+    }
+
+    if (registerExisting) {
+      return register({ ...callOptions, root: nextRoot });
+    }
+
+    return emptyRegistrationResult();
+  }
+
+  /** Change both observation root and default append target to the same node. */
+  async function moveTo(root, callOptions = {}) {
+    const nextRoot = getRoot({ root }, "HTML runtime moveTo");
+    return setRoot(nextRoot, {
+      ...callOptions,
+      appendTo: callOptions.appendTo ?? defaultAppendTargetForRoot(nextRoot),
+    });
+  }
+
+  /** Change only where append()/addModule() insert future script elements. */
+  function setAppendTarget(target) {
+    if (!target || (typeof target.append !== "function" && typeof target.appendChild !== "function")) {
+      throw new TypeError("setAppendTarget() requires a target with append() or appendChild().");
+    }
+    controller.appendTo = target;
+    return api;
   }
 
   /** Define one element without automatically executing an entry module. */
@@ -326,6 +372,59 @@ export async function defineScript(runtime, element, options = {}) {
 export const htmlModuleSelector = DEFAULT_SELECTOR;
 export const htmlRuntimeScopeAttribute = RUNTIME_SCOPE_ATTRIBUTE;
 
+async function connectObserver(controller, root, callOptions = {}, mode = {}) {
+  const MutationObserverImpl = callOptions.MutationObserver ?? controller.MutationObserver ?? globalThis.MutationObserver;
+
+  if (typeof MutationObserverImpl !== "function") {
+    throw new TypeError(
+      "observe() requires MutationObserver support or a MutationObserver option.",
+    );
+  }
+
+  controller.observerRoot = root;
+  controller.connected = true;
+  controller.lastError = undefined;
+  controller.ignoredExisting = new WeakSet();
+
+  const registerExisting = mode.registerExisting !== false;
+  if (!registerExisting) {
+    for (const element of Array.from(root.querySelectorAll(callOptions.selector ?? controller.selector))) {
+      if (acceptsDiscoveredElement(controller, element, callOptions)) {
+        controller.ignoredExisting.add(element);
+      }
+    }
+  }
+
+  const observer = new MutationObserverImpl(() => {
+    void enqueueObserverScan(controller, callOptions).catch(() => {});
+  });
+
+  controller.observer = observer;
+  observer.observe(root, {
+    childList: true,
+    subtree: callOptions.subtree ?? controller.subtree,
+  });
+
+  const result = registerExisting
+    ? await enqueueObserverScan(controller, {
+        ...callOptions,
+        origin: mode.initial ? "observer-initial" : "observer-root-change",
+      })
+    : emptyRegistrationResult();
+
+  if (mode.initial) controller.initial = result;
+  return result;
+}
+
+function stopObserver(controller, options = {}) {
+  if (!controller.connected && !controller.observer) return;
+  controller.connected = false;
+  controller.observer?.disconnect();
+  controller.observer = undefined;
+  controller.observerRoot = undefined;
+  if (!options.preserveOptions) controller.observerOptions = undefined;
+}
+
 async function enqueueObserverScan(controller, callOptions = {}) {
   const task = controller.queue.then(async () => {
     if (!controller.connected) return emptyRegistrationResult();
@@ -669,6 +768,10 @@ function getAppendTarget(controller, options = {}) {
   if (explicit) return explicit;
 
   const root = options.root ?? controller.root ?? globalThis.document;
+  return defaultAppendTargetForRoot(root);
+}
+
+function defaultAppendTargetForRoot(root) {
   if (root?.body) return root.body;
   if (root?.documentElement && root.documentElement !== root) return root.documentElement;
   return root;