solid-tag-runtime 0.0.5 → 0.0.7

package/ARCHITECTURE.md

@@ -38,9 +38,11 @@ The runtime should allow applications to:
 5. expose host components, signals, callbacks, services, and data as modules
 6. reuse compiled/evaluated modules through caching
 7. invalidate and rebuild a module graph when source changes
-8. inspect dependencies and compiled source
-9. support normal JavaScript modules in the same graph
-10. keep the JSX compiler replaceable behind a narrow adapter
+8. explicitly remove and clear module definitions
+9. observe runtime lifecycle transitions for tooling/tracing
+10. inspect dependencies and compiled source
+11. support normal JavaScript modules in the same graph
+12. keep the JSX compiler replaceable behind a narrow adapter
 
 ## 3. Current non-goals
 
@@ -235,6 +237,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 +327,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 +971,63 @@ 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.
+
+
+### 0.0.7 — explicit module lifecycle, batching, and HTML-owned replacement
+
+Decision: add `defineMany()`, `remove()`, `clear()`, and `subscribe()` to the core runtime, and `updateElement()` / `removeElement()` to `solid-tag-runtime/html`.
+
+Reason: long-lived runtime environments need an explicit lifecycle beyond define/update/invalidate. Editors, previews, CMSs, and plugin hosts must be able to install related modules together, remove stale definitions, reset runtime state while preserving host modules, trace module transitions, and keep HTML ownership synchronized with explicit module replacement/removal.
+
+Core lifecycle semantics:
+
+- `defineMany()` validates the definition list before applying it and rejects duplicate IDs inside one batch. No module evaluation happens during definition, so the full batch is available before an import starts linking. Lifecycle events produced while applying the batch are buffered and published only after every definition has been installed, preventing a subscriber from observing or importing a partially installed batch.
+- `remove(id)` deletes one module record, revokes generated URLs, removes host-registry state when applicable, and invalidates transitive dependents by default.
+- `clear()` removes source/URL modules while preserving host modules by default; `preserveHostModules:false` removes every record.
+- `subscribe(listener)` emits synchronous lifecycle events but isolates subscriber exceptions from runtime execution.
+- public `resolve()` remains the canonical tooling hook for asking how a specifier resolves without evaluating it.
+
+Lifecycle event contract:
+
+```text
+module-defined
+module-invalidated
+module-compiled
+module-evaluating
+module-evaluated
+module-removed
+module-error
+runtime-cleared
+runtime-disposed
+```
+
+HTML lifecycle semantics:
+
+- `updateElement(element)` only operates on an element already owned by that controller. It re-reads/fetches source and calls `runtime.update()` while preserving logical module identity. Changing `module` identity requires explicit remove + register.
+- `removeElement(element)` releases the shared WeakMap ownership and per-controller binding. By default it also removes the runtime module and DOM node. `removeModule` and `removeFromDOM` can be controlled independently.
+- DOM removal by itself still does not imply module removal. Module lifecycle remains explicit.
+- If ownership is released while the element remains under an active observed root, the controller marks that element ignored so the observer does not immediately reclaim it. An explicit `registerElement()` may claim it again.
+
+Invariants:
+
+1. Removing a module must revoke its executable URL/namespace cache and clean outbound graph edges.
+2. Dependents are invalidated before dependency removal unless explicitly disabled.
+3. `defineMany()` must not publish lifecycle events until the whole batch has been installed.
+4. `clear()` must not silently discard host environment modules under its default configuration.
+5. Lifecycle listeners are observational; listener failures cannot alter runtime execution.
+6. HTML element ownership and runtime module existence are related but separate lifecycles.
+7. `updateElement()` never changes the module identity associated with an owned element.
+8. `removeElement()` is the canonical operation for releasing shared WeakMap ownership.
+
+Regression coverage: package tests cover batch definition and duplicate rejection, dependency removal/invalidation, clear-with-host-preservation, lifecycle event delivery/unsubscribe, owned element updates, identity-change rejection, ownership release, DOM removal, and preserving a runtime module while releasing its HTML element.

package/README.md

@@ -102,6 +102,17 @@ The runtime compiles and links the dependency graph automatically.
 
 `solid-tag-runtime/html` is the browser/DOM adapter. The core runtime remains DOM-independent.
 
+Browser import maps must map the subpath explicitly as well as the package root:
+
+```json
+{
+  "imports": {
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.7",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.7/html"
+  }
+}
+```
+
 For simple single-runtime use, the original helpers remain available:
 
 ```ts
@@ -270,11 +281,73 @@ 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-oriented.
 
-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.
+Changing the source/attributes of an already owned script or removing it from the DOM does not implicitly update/delete the corresponding runtime module. In `0.0.7`, use `html.updateElement()` and `html.removeElement()` when the lifecycle should follow an owned script explicitly, or use the core `runtime.update()` / `runtime.remove()` APIs directly.
 
 The HTML adapter does **not** reinterpret arbitrary document HTML as JSX and does not currently assign component semantics to `<template>`.
 
@@ -448,6 +521,120 @@ Updating a module invalidates its compiled URL and its dependent runtime modules
 
 Existing references to an older module namespace/component are not mutated. Applications that implement live editing should import the updated entry module again.
 
+### Define several source modules together
+
+```ts
+runtime.defineMany([
+  {
+    id: "/ui/Button.jsx",
+    source: buttonSource,
+  },
+  {
+    id: "/App.jsx",
+    source: appSource,
+  },
+]);
+```
+
+`defineMany()` validates the whole definition list before applying it and rejects duplicate module IDs inside the batch. It is useful when a group of modules should become available before anything is imported. Lifecycle notifications from the batch are published only after every definition has been installed.
+
+### Remove modules
+
+```ts
+runtime.remove("/ui/Button.jsx");
+```
+
+Removal invalidates transitive dependents by default. A later import of a dependent will fail resolution until the missing module is defined again.
+
+If you intentionally want to leave currently linked dependents untouched:
+
+```ts
+runtime.remove("/ui/Button.jsx", {
+  invalidateDependents: false,
+});
+```
+
+### Clear a runtime
+
+```ts
+runtime.clear();
+```
+
+By default `clear()` removes source and URL modules while preserving host modules registered with `defineModule()`. This is convenient for editor/preview resets where the host environment should remain installed.
+
+```ts
+runtime.clear({
+  preserveHostModules: false,
+});
+```
+
+removes everything. The returned array contains the IDs that were removed.
+
+### Lifecycle events
+
+```ts
+const unsubscribe = runtime.subscribe(event => {
+  console.log(event.type, event);
+});
+
+// later
+unsubscribe();
+```
+
+Events currently include:
+
+- `module-defined`
+- `module-invalidated`
+- `module-compiled`
+- `module-evaluating`
+- `module-evaluated`
+- `module-removed`
+- `module-error`
+- `runtime-cleared`
+- `runtime-disposed`
+
+Subscriber exceptions are isolated from runtime execution. This makes `subscribe()` suitable for tracing, developer tools, and editor diagnostics.
+
+## HTML-owned module updates and removal
+
+When a script element is already owned by an HTML runtime controller, update the runtime module from the current element contents with:
+
+```ts
+script.textContent = `
+  export function Card() {
+    return <div>updated</div>;
+  }
+`;
+
+await html.updateElement(script);
+```
+
+`updateElement()` keeps the existing logical module ID and calls `runtime.update()` underneath. Changing the element's logical `module` identity is intentionally rejected; remove and register it again instead.
+
+Release an owned element explicitly with:
+
+```ts
+await html.removeElement(script);
+```
+
+By default this:
+
+1. removes the runtime module,
+2. invalidates its dependents,
+3. releases HTML ownership, and
+4. removes the script element from the DOM.
+
+The two lifecycles can be controlled independently:
+
+```ts
+await html.removeElement(script, {
+  removeModule: false,
+  removeFromDOM: true,
+});
+```
+
+This is intentionally explicit: ordinary DOM removal does not silently delete a runtime module.
+
 ## Custom resolution
 
 ```ts
@@ -486,10 +673,12 @@ Set it to `false` when all module dependencies must be explicitly registered wit
 
 ```ts
 runtime.invalidate("/App.jsx");
+runtime.remove("/Unused.jsx");
+runtime.clear();
 runtime.dispose();
 ```
 
-`dispose()` revokes generated module URLs and clears the host-module registry for that runtime instance.
+`invalidate()` forces fresh compilation/evaluation without deleting the module definition. `remove()` deletes one definition, `clear()` resets a group of definitions, and `dispose()` permanently tears down the runtime instance.
 
 ## Current limitations
 

package/html.d.ts

@@ -5,6 +5,8 @@ export interface HTMLModuleScriptElement {
   textContent?: string | null;
   baseURI?: string;
   ownerDocument?: HTMLDocumentLike | null;
+  parentNode?: { removeChild?(element: any): unknown } | null;
+  remove?(): void;
   getAttribute(name: string): string | null;
   hasAttribute?(name: string): boolean;
   setAttribute?(name: string, value: string): void;
@@ -75,6 +77,22 @@ export interface HTMLModuleDefinition {
   element: HTMLModuleScriptElement;
 }
 
+export interface RemoveHTMLElementOptions {
+  /** Remove the runtime module as well as releasing HTML ownership. Default: true. */
+  removeModule?: boolean;
+  /** Remove the script element from the DOM. Default: true. */
+  removeFromDOM?: boolean;
+  /** Invalidate runtime dependents when removing the module. Default: true. */
+  invalidateDependents?: boolean;
+}
+
+export interface RemoveHTMLElementResult {
+  id: string;
+  element: HTMLModuleScriptElement;
+  moduleRemoved: boolean;
+  elementRemoved: boolean;
+}
+
 export interface RegisterHTMLOptions extends DefineScriptOptions {
   selector?: string;
   executeEntries?: boolean;
@@ -119,10 +137,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 +168,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,
@@ -148,6 +198,18 @@ export interface HTMLRuntimeController {
     options?: RegisterHTMLOptions,
   ): Promise<HTMLModuleDefinition>;
 
+  /** Re-read and replace source for an element already owned by this controller. */
+  updateElement(
+    element: HTMLModuleScriptElement,
+    options?: RegisterHTMLOptions,
+  ): Promise<HTMLModuleDefinition>;
+
+  /** Release an owned element and optionally remove its module and DOM node. */
+  removeElement(
+    element: HTMLModuleScriptElement,
+    options?: RemoveHTMLElementOptions,
+  ): Promise<RemoveHTMLElementResult>;
+
   /** Claim first, append a user-created element, then register it directly. */
   append(
     element: HTMLModuleScriptElement,

package/index.d.ts

@@ -76,8 +76,35 @@ export interface CompileResult {
   diagnostics: unknown[];
 }
 
+export interface SourceModuleDefinition extends DefineOptions {
+  id: string;
+  source: string;
+}
+
+export interface RemoveModuleOptions {
+  /** Invalidate transitive dependents before removal. Default: true. */
+  invalidateDependents?: boolean;
+}
+
+export interface ClearRuntimeOptions {
+  /** Keep host namespace modules registered with defineModule(). Default: true. */
+  preserveHostModules?: boolean;
+}
+
+export type RuntimeLifecycleEvent =
+  | { runtimeId: string; timestamp: number; type: "module-defined"; id: string; kind: ModuleInfo["kind"]; version: number; operation: "define" | "defineMany" | "update" | "defineModule" | "defineUrl"; replaced: boolean; module: ModuleInfo }
+  | { runtimeId: string; timestamp: number; type: "module-invalidated"; id: string; kind: ModuleInfo["kind"]; version: number; reason: string }
+  | { runtimeId: string; timestamp: number; type: "module-compiled"; id: string; kind: ModuleInfo["kind"]; version: number; module: ModuleInfo }
+  | { runtimeId: string; timestamp: number; type: "module-evaluating"; id: string; kind: ModuleInfo["kind"]; version: number }
+  | { runtimeId: string; timestamp: number; type: "module-evaluated"; id: string; kind: ModuleInfo["kind"]; version: number; module: ModuleInfo }
+  | { runtimeId: string; timestamp: number; type: "module-removed"; id: string; kind: ModuleInfo["kind"]; version: number; invalidateDependents: boolean }
+  | { runtimeId: string; timestamp: number; type: "module-error"; id?: string; kind?: ModuleInfo["kind"]; version?: number; phase: string; error: unknown }
+  | { runtimeId: string; timestamp: number; type: "runtime-cleared"; ids: string[]; preserveHostModules: boolean }
+  | { runtimeId: string; timestamp: number; type: "runtime-disposed" };
+
 export interface SolidTagRuntime {
   define(id: string, source: string, options?: DefineOptions): string;
+  defineMany(definitions: SourceModuleDefinition[]): string[];
   update(id: string, source: string, options?: DefineOptions): string;
   defineModule(id: string, namespace: ModuleNamespaceLike | Function): string;
   defineUrl(id: string, url: string): string;
@@ -87,6 +114,9 @@ export interface SolidTagRuntime {
   toComponent<T extends Function = Function>(source: string, options?: ToComponentOptions): Promise<T>;
   has(id: string): boolean;
   invalidate(id: string, options?: { dependents?: boolean }): string[];
+  remove(id: string, options?: RemoveModuleOptions): boolean;
+  clear(options?: ClearRuntimeOptions): string[];
+  subscribe(listener: (event: RuntimeLifecycleEvent) => void): () => boolean;
   modules(): ModuleInfo[];
   dependencies(id: string): string[];
   dependents(id: string): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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,12 +82,23 @@ 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,
+    updateElement,
+    removeElement,
     append,
     addModule,
     owns,
@@ -120,47 +132,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 +163,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. */
@@ -213,6 +261,97 @@ export function createHTMLRuntime(runtime, options = {}) {
     return result.modules[0] ?? definitionFromOwnedElement(controller, element);
   }
 
+  /**
+   * Re-read an owned script element and replace its runtime module source. The
+   * logical module id is stable; changing `module`/src-derived identity requires
+   * removeElement() + registerElement() instead.
+   */
+  async function updateElement(element, callOptions = {}) {
+    const record = requireOwnedRecord(controller, element, "updateElement");
+    const metadata = inspectElement(controller, element, {
+      ...callOptions,
+      existingId: record.moduleId,
+    });
+    const nextModuleId = normalizeModuleId(runtime, metadata.id);
+
+    if (nextModuleId !== record.moduleId) {
+      throw new HTMLModuleError(
+        `updateElement() cannot change module identity from ${JSON.stringify(record.moduleId)} to ${JSON.stringify(nextModuleId)}. Remove and register the element again instead.`,
+        { element, moduleId: record.moduleId, sourceUrl: metadata.sourceUrl },
+      );
+    }
+
+    const candidate = {
+      ...record,
+      format: metadata.format,
+      entry: metadata.entry,
+      sourceUrl: metadata.sourceUrl,
+      inline: !metadata.sourceUrl,
+    };
+
+    const { source } = await prepareRecordSource(controller, candidate, callOptions);
+    runtime.update(record.moduleId, source, { format: candidate.format });
+
+    record.format = candidate.format;
+    record.entry = candidate.entry;
+    record.sourceUrl = candidate.sourceUrl;
+    record.inline = candidate.inline;
+    record.state = "defined";
+    record.error = undefined;
+    record.definition = definitionFromRecord(record);
+
+    if (record.entry && (callOptions.executeEntries ?? controller.executeEntries) !== false) {
+      record.state = "executing";
+      try {
+        await runtime.import(record.moduleId);
+        record.state = "ready";
+      } catch (error) {
+        record.state = "error";
+        record.error = error;
+        throw error;
+      }
+    }
+
+    return record.definition;
+  }
+
+  /**
+   * Release an element from this HTML controller. By default both the runtime
+   * module and DOM element are removed. DOM removal and module removal can be
+   * controlled independently.
+   */
+  async function removeElement(element, callOptions = {}) {
+    const record = requireOwnedRecord(controller, element, "removeElement");
+    const removeModule = callOptions.removeModule !== false;
+    const removeFromDOM = callOptions.removeFromDOM !== false;
+    const invalidateDependents = callOptions.invalidateDependents !== false;
+
+    let moduleRemoved = false;
+    if (removeModule) {
+      moduleRemoved = runtime.remove(record.moduleId, { invalidateDependents });
+    }
+
+    controller.bindings.delete(record.moduleId);
+    elementOwners.delete(element);
+    record.state = "removed";
+
+    let elementRemoved = false;
+    if (removeFromDOM) {
+      elementRemoved = removeDOMElement(element);
+    } else {
+      // Keep a released element in the observed tree from being immediately
+      // rediscovered. Explicit registerElement() can still claim it again.
+      controller.ignoredExisting.add(element);
+    }
+
+    return {
+      id: record.moduleId,
+      element,
+      moduleRemoved,
+      elementRemoved,
+    };
+  }
+
   /**
    * Claim a user-created script before DOM insertion, append it to this
    * controller's target, then register it directly. The observer will see the
@@ -326,6 +465,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();
@@ -550,7 +742,7 @@ function inspectElement(controller, element, options = {}) {
     sourceUrl,
   });
 
-  const id = explicitId ?? sourceUrl ?? (entry ? createAnonymousId(format) : undefined);
+  const id = explicitId ?? sourceUrl ?? (entry ? options.existingId ?? createAnonymousId(format) : undefined);
   if (!id) {
     throw new HTMLModuleError(
       "Inline solid runtime module scripts require a `module` attribute unless they are marked `entry`.",
@@ -561,6 +753,35 @@ function inspectElement(controller, element, options = {}) {
   return { id, format, entry, sourceUrl };
 }
 
+function requireOwnedRecord(controller, element, caller) {
+  assertElement(element, caller);
+  const record = elementOwners.get(element);
+  if (!record) {
+    throw new HTMLModuleOwnershipError(
+      `${caller}() requires an element already owned by this HTML runtime.`,
+      { element, requestedScope: controller.scope },
+    );
+  }
+  if (record.owner !== controller) throw ownershipError(controller, element, record);
+  return record;
+}
+
+function removeDOMElement(element) {
+  if (typeof element?.remove === "function") {
+    const wasConnected = Boolean(element.parentNode);
+    element.remove();
+    return wasConnected || !element.parentNode;
+  }
+
+  const parent = element?.parentNode;
+  if (parent && typeof parent.removeChild === "function") {
+    parent.removeChild(element);
+    return true;
+  }
+
+  return false;
+}
+
 function definitionFromRecord(record) {
   return {
     id: record.moduleId,
@@ -669,6 +890,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/runtime.js

@@ -27,6 +27,9 @@ export function createRuntime(options = {}) {
   const records = new Map();
   let anonymousSequence = 0;
   let disposed = false;
+  const subscribers = new Set();
+  let eventBufferDepth = 0;
+  const eventBuffer = [];
 
   const globalRegistry = getHostRegistry();
   const hostNamespaces = new Map();
@@ -34,6 +37,7 @@ export function createRuntime(options = {}) {
 
   const api = {
     define,
+    defineMany,
     defineModule,
     defineUrl,
     update,
@@ -43,6 +47,9 @@ export function createRuntime(options = {}) {
     toComponent,
     has,
     invalidate,
+    remove,
+    clear,
+    subscribe,
     modules: listModules,
     dependencies,
     dependents,
@@ -61,11 +68,57 @@ export function createRuntime(options = {}) {
   }
 
   function define(id, source, defineOptions = {}) {
+    return defineSource(id, source, defineOptions, "define");
+  }
+
+  function defineMany(definitions) {
+    assertActive();
+    if (!Array.isArray(definitions)) {
+      throw new TypeError("defineMany(definitions) expects an array of source module definitions.");
+    }
+
+    const prepared = definitions.map((definition, index) => {
+      if (!definition || typeof definition !== "object") {
+        throw new TypeError(`defineMany() item ${index} must be an object with id and source.`);
+      }
+      if (definition.id == null) {
+        throw new TypeError(`defineMany() item ${index} is missing id.`);
+      }
+      const id = normalizeDefinedId(definition.id);
+      return {
+        id,
+        source: String(definition.source ?? ""),
+        format: definition.format ?? "jsx",
+      };
+    });
+
+    const seen = new Set();
+    for (const item of prepared) {
+      if (seen.has(item.id)) {
+        throw new SolidTagRuntimeError(`defineMany() contains duplicate module id ${JSON.stringify(item.id)}.`);
+      }
+      seen.add(item.id);
+    }
+
+    eventBufferDepth += 1;
+    try {
+      return prepared.map(item => defineSource(item.id, item.source, { format: item.format }, "defineMany"));
+    } finally {
+      eventBufferDepth -= 1;
+      if (eventBufferDepth === 0) flushEventBuffer();
+    }
+  }
+
+  function update(id, source, updateOptions = {}) {
+    return defineSource(id, source, updateOptions, "update");
+  }
+
+  function defineSource(id, source, defineOptions = {}, operation = "define") {
     assertActive();
     const normalized = normalizeDefinedId(id);
     const existing = records.get(normalized);
 
-    if (existing) invalidate(normalized, { dependents: true });
+    if (existing) invalidate(normalized, { dependents: true, reason: operation });
 
     const record = {
       id: normalized,
@@ -84,18 +137,23 @@ export function createRuntime(options = {}) {
     };
 
     records.set(normalized, record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation,
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
+    });
     return normalized;
   }
 
-  function update(id, source, updateOptions = {}) {
-    return define(id, source, updateOptions);
-  }
-
   function defineModule(id, namespace) {
     assertActive();
     const normalized = normalizeDefinedId(id);
     const existing = records.get(normalized);
-    if (existing) invalidate(normalized, { dependents: true });
+    if (existing) invalidate(normalized, { dependents: true, reason: "defineModule" });
 
     if ((typeof namespace !== "object" || namespace === null) && typeof namespace !== "function") {
       throw new TypeError("defineModule(id, namespace) expects an object, function, or ES module namespace-like value.");
@@ -103,7 +161,7 @@ export function createRuntime(options = {}) {
 
     hostNamespaces.set(normalized, namespace);
 
-    records.set(normalized, {
+    const record = {
       id: normalized,
       kind: "host",
       namespace,
@@ -112,6 +170,16 @@ export function createRuntime(options = {}) {
       dependencies: new Set(),
       dependents: existing?.dependents ?? new Set(),
       url: undefined,
+    };
+    records.set(normalized, record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation: "defineModule",
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
     });
 
     return normalized;
@@ -121,10 +189,10 @@ export function createRuntime(options = {}) {
     assertActive();
     const normalized = normalizeDefinedId(id);
     const existing = records.get(normalized);
-    if (existing) invalidate(normalized, { dependents: true });
+    if (existing) invalidate(normalized, { dependents: true, reason: "defineUrl" });
 
     const href = String(url);
-    records.set(normalized, {
+    const record = {
       id: normalized,
       kind: "url",
       externalUrl: href,
@@ -134,6 +202,16 @@ export function createRuntime(options = {}) {
       dependents: existing?.dependents ?? new Set(),
       importPromise: undefined,
       namespace: undefined,
+    };
+    records.set(normalized, record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation: "defineUrl",
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
     });
 
     return normalized;
@@ -155,23 +233,36 @@ export function createRuntime(options = {}) {
 
     if (record.kind === "url") {
       if (!record.importPromise) {
+        record.state = "evaluating";
+        emit({ type: "module-evaluating", id: record.id, kind: record.kind, version: record.version });
         record.importPromise = import(record.externalUrl).then(namespace => {
           record.namespace = namespace;
           record.state = "ready";
+          emit({ type: "module-evaluated", id: record.id, kind: record.kind, version: record.version, module: toModuleInfo(record) });
           return namespace;
+        }).catch(error => {
+          record.importPromise = undefined;
+          record.state = "error";
+          emitError(record, "evaluate", error);
+          throw error;
         });
       }
       return record.importPromise;
     }
 
     if (!record.importPromise) {
+      record.state = "evaluating";
+      emit({ type: "module-evaluating", id: record.id, kind: record.kind, version: record.version });
       record.importPromise = ensureSourceUrl(record, []).then(url => import(url)).then(namespace => {
         record.namespace = namespace;
         record.state = "ready";
+        emit({ type: "module-evaluated", id: record.id, kind: record.kind, version: record.version, module: toModuleInfo(record) });
         return namespace;
       }).catch(error => {
         record.importPromise = undefined;
+        const alreadyReported = record.state === "error";
         record.state = "error";
+        if (!alreadyReported) emitError(record, "evaluate", error);
         throw error;
       });
     }
@@ -241,6 +332,7 @@ export function createRuntime(options = {}) {
     assertActive();
     const normalized = normalizeLookupId(id);
     const includeDependents = invalidateOptions.dependents ?? true;
+    const reason = invalidateOptions.reason ?? "explicit";
     const seen = new Set();
 
     invalidateOne(normalized);
@@ -271,7 +363,71 @@ export function createRuntime(options = {}) {
         record.namespace = undefined;
         record.state = "defined";
       }
+
+      emit({
+        type: "module-invalidated",
+        id: record.id,
+        kind: record.kind,
+        version: record.version,
+        reason,
+      });
+    }
+  }
+
+  function remove(id, removeOptions = {}) {
+    assertActive();
+    const normalized = normalizeLookupId(id);
+    const record = records.get(normalized);
+    if (!record) return false;
+
+    if (removeOptions.invalidateDependents !== false) {
+      for (const dependent of [...record.dependents]) {
+        invalidate(dependent, { dependents: true, reason: `dependency-removed:${normalized}` });
+      }
+    }
+
+    for (const dependency of record.dependencies) {
+      records.get(dependency)?.dependents.delete(normalized);
+    }
+
+    revokeRecordUrl(record);
+    if (record.kind === "host") hostNamespaces.delete(normalized);
+    records.delete(normalized);
+
+    emit({
+      type: "module-removed",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      invalidateDependents: removeOptions.invalidateDependents !== false,
+    });
+    return true;
+  }
+
+  function clear(clearOptions = {}) {
+    assertActive();
+    const preserveHostModules = clearOptions.preserveHostModules !== false;
+    const ids = [...records.values()]
+      .filter(record => !(preserveHostModules && record.kind === "host"))
+      .map(record => record.id);
+
+    for (const id of ids) remove(id, { invalidateDependents: false });
+
+    emit({
+      type: "runtime-cleared",
+      ids: [...ids],
+      preserveHostModules,
+    });
+    return ids;
+  }
+
+  function subscribe(listener) {
+    assertActive();
+    if (typeof listener !== "function") {
+      throw new TypeError("subscribe(listener) expects a function.");
     }
+    subscribers.add(listener);
+    return () => subscribers.delete(listener);
   }
 
   function listModules() {
@@ -296,11 +452,13 @@ export function createRuntime(options = {}) {
   function dispose() {
     if (disposed) return;
     disposed = true;
+    emit({ type: "runtime-disposed" });
 
     for (const record of records.values()) revokeRecordUrl(record);
     records.clear();
     hostNamespaces.clear();
     globalRegistry.delete(runtimeId);
+    subscribers.clear();
   }
 
   function resolvePublic(specifier, importer) {
@@ -323,7 +481,9 @@ export function createRuntime(options = {}) {
       analysis = compiler.analyze(record.source, { id: record.id, format: record.format });
     } catch (error) {
       record.state = "error";
-      throw new ModuleCompileError(record.id, error);
+      const wrapped = new ModuleCompileError(record.id, error);
+      emitError(record, "analyze", wrapped);
+      throw wrapped;
     }
 
     const resolvedImports = [];
@@ -394,11 +554,20 @@ export function createRuntime(options = {}) {
       }
     } catch (error) {
       record.state = "error";
-      throw new ModuleCompileError(record.id, error);
+      const wrapped = new ModuleCompileError(record.id, error);
+      emitError(record, "transform", wrapped);
+      throw wrapped;
     }
 
     record.url = moduleUrlBackend.create(appendSourceUrl(record.compiledCode, record.id));
     record.state = "compiled";
+    emit({
+      type: "module-compiled",
+      id: record.id,
+      kind: record.kind,
+      version: record.version,
+      module: toModuleInfo(record),
+    });
     return record.url;
   }
 
@@ -472,6 +641,47 @@ export function createRuntime(options = {}) {
     }
   }
 
+  function emit(event) {
+    if (subscribers.size === 0) return;
+    const payload = {
+      runtimeId,
+      timestamp: Date.now(),
+      ...event,
+    };
+    if (eventBufferDepth > 0) {
+      eventBuffer.push(payload);
+      return;
+    }
+    dispatchEvent(payload);
+  }
+
+  function flushEventBuffer() {
+    if (eventBuffer.length === 0) return;
+    const pending = eventBuffer.splice(0, eventBuffer.length);
+    for (const event of pending) dispatchEvent(event);
+  }
+
+  function dispatchEvent(payload) {
+    for (const listener of [...subscribers]) {
+      try {
+        listener(payload);
+      } catch (error) {
+        globalThis.console?.error?.("solid-tag-runtime lifecycle subscriber error", error);
+      }
+    }
+  }
+
+  function emitError(record, phase, error) {
+    emit({
+      type: "module-error",
+      id: record?.id,
+      kind: record?.kind,
+      version: record?.version,
+      phase,
+      error,
+    });
+  }
+
   function toModuleInfo(record) {
     return {
       id: record.id,