solid-tag-runtime 0.0.6 → 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
 
@@ -980,3 +982,52 @@ Reason: applications can reparent an existing observed root without intervention
 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
@@ -334,9 +345,9 @@ The `root` may be a `Document`, normal `Element`, `DocumentFragment`, or `Shadow
 
 ### Addition-only observation
 
-Observation remains addition-only in `0.0.6`.
+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>`.
 
@@ -510,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
@@ -548,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,7 +5,8 @@ export interface HTMLModuleScriptElement {
   textContent?: string | null;
   baseURI?: string;
   ownerDocument?: HTMLDocumentLike | null;
-  parentNode?: unknown;
+  parentNode?: { removeChild?(element: any): unknown } | null;
+  remove?(): void;
   getAttribute(name: string): string | null;
   hasAttribute?(name: string): boolean;
   setAttribute?(name: string, value: string): void;
@@ -76,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;
@@ -181,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.6",
+  "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

@@ -97,6 +97,8 @@ export function createHTMLRuntime(runtime, options = {}) {
     setAppendTarget,
     defineElement,
     registerElement,
+    updateElement,
+    removeElement,
     append,
     addModule,
     owns,
@@ -259,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
@@ -649,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`.",
@@ -660,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,

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,