solid-tag-runtime 0.0.4 → 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:
@@ -916,3 +959,24 @@ Reason: attributes are useful across declarative HTML and DevTools but cannot un
 ### 0.0.4 — typing/test/documentation hardening
 
 Decision: publish the next package as `0.0.4` because `0.0.3` has already been published. `0.0.4` preserves the `0.0.3` runtime/HTML semantics while shipping the DOM-compatible HTML adapter declaration fixes, broader regression coverage, and updated feature documentation. No module-resolution, ownership, execution-backend, or cache-invalidation semantics change in this release.
+### 0.0.5 — fresh module identity after invalidation
+
+Decision: every execution-backend `create(code)` call must produce a fresh native ESM module identity, even when the generated source text is byte-for-byte identical to an earlier version. The `data:` backend now appends a monotonically increasing fragment to each generated URL. This matches the naturally unique URLs returned by `URL.createObjectURL()` and prevents the browser/Node ESM cache from returning a previously evaluated module after `invalidate()`, `update()`, or `defineModule()` replacement.
+
+Reason: replacing a host namespace correctly invalidated its dependents in the runtime graph, but a deterministic `data:` URL could recreate the exact same URL for the host bridge and dependent source. Native ESM caches by URL, so the old evaluation was reused and dependents continued to observe stale host exports.
+
+Invariant: invalidation must result in a fresh executable module identity on the next compile/import. Cache invalidation is not complete if the execution backend can recreate an already-evaluated URL.
+
+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.4`.
+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.4",
+  "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;

package/src/url-backend.js

@@ -23,10 +23,17 @@ export function createBlobModuleUrlBackend() {
 }
 
 export function createDataModuleUrlBackend() {
+  let sequence = 0;
+
   return {
     kind: "data",
     create(code) {
-      return `data:text/javascript;charset=utf-8,${encodeURIComponent(code)}`;
+      // Native ESM caches modules by URL. Recreating the same data: URL after
+      // invalidation would otherwise return the previously evaluated module.
+      // Give every backend create() call a fresh module identity, matching the
+      // naturally unique identity of URL.createObjectURL() in the blob backend.
+      const identity = ++sequence;
+      return `data:text/javascript;charset=utf-8,${encodeURIComponent(code)}#solid-tag-runtime-${identity}`;
     },
     revoke() {},
   };