solid-tag-runtime 0.0.6 → 0.0.8

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
 
@@ -99,6 +101,7 @@ const runtime = createRuntime(options);
 
 ```ts
 runtime.define(id, source, options?);
+runtime.defineMany(definitions);
 runtime.update(id, source, options?);
 ```
 
@@ -136,9 +139,18 @@ runtime.getModuleInfo(id);
 
 ```ts
 runtime.invalidate(id);
+runtime.remove(id, options?);
+runtime.clear(options?);
+
+runtime.subscribe(listener);
+runtime.subscribe(type, listener);
+runtime.subscribe(types, listener);
+
 runtime.dispose();
 ```
 
+Lifecycle subscriptions are synchronous observational notifications. They do not intercept or modify runtime behavior. Resolution behavior remains customizable through `resolve()`, compilation through the compiler adapter, and executable-module creation through `ModuleUrlBackend`.
+
 ## 6. Module kinds
 
 The runtime currently has three module record kinds.
@@ -230,6 +242,10 @@ await html.observe({ registerExisting: false });
 The controller exposes:
 
 ```ts
+html.subscribe(listener);
+html.subscribe(type, listener);
+html.subscribe(types, listener);
+
 html.register(options?);
 html.observe(options?);
 html.flush(options?);
@@ -980,3 +996,151 @@ 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.
+
+### 0.0.8 — selective lifecycle subscriptions and HTML observability
+
+Decision: expand lifecycle observation into typed, independently removable subscriptions on both the core runtime and the HTML adapter. Keep lifecycle subscriptions observational and separate from behavioral hooks/interceptors.
+
+Core subscription forms:
+
+```ts
+runtime.subscribe(listener);
+runtime.subscribe("module-error", listener);
+runtime.subscribe(["module-evaluating", "module-evaluated"], listener);
+```
+
+HTML controllers expose the same shape:
+
+```ts
+html.subscribe(listener);
+html.subscribe("element-registered", listener);
+html.subscribe(["observer-batch", "html-error"], listener);
+```
+
+Each call creates an independent subscription and returns its own disposer. Disposing one subscription never affects another registration of the same callback or subscriptions to other event groups. Subscriber exceptions are reported but cannot alter runtime/HTML operations.
+
+Core event additions:
+
+```text
+module-updated
+modules-defined
+module-resolving
+module-resolved
+module-linking
+module-linked
+```
+
+The evaluation pipeline is now observed in semantic order:
+
+```text
+module-linking
+  ↓
+module-resolving / module-resolved
+  ↓
+module-linked
+  ↓
+module-compiled
+  ↓
+module-evaluating
+  ↓
+module-evaluated
+```
+
+`module-resolved` exposes the logical resolution result and resolution kind, while `module-linked` exposes source specifier → resolved module-ID dependencies without exposing Blob/data URL implementation details. `modules-defined` marks the completion of a `defineMany()` batch after buffered per-module events become observable. `module-updated` supplements the backward-compatible `module-defined { operation: "update" }` event with an explicit semantic update notification.
+
+`module-error` remains one event with a structured pipeline phase instead of creating separate error event types. Supported phases are `resolve`, `analyze`, `compile`, `link`, `url-create`, `evaluate`, and `host-bridge`.
+
+HTML controller event additions:
+
+```text
+element-discovered
+element-claimed
+element-loading
+element-loaded
+element-registered
+element-updating
+element-updated
+element-removing
+element-released
+element-removed
+observer-connected
+observer-disconnected
+observer-batch
+root-changing
+root-changed
+append-target-changed
+entry-executing
+entry-executed
+html-error
+```
+
+HTML ownership events include an origin describing the ingestion path (`initial-scan`, `observer`, `register-element`, `append`, `add-module`, etc.). The observer emits summarized `observer-batch` events instead of exposing raw `MutationRecord` values. Root/append-target events belong only to the HTML controller and are deliberately not mixed into core runtime events.
+
+Architectural boundary:
+
+```text
+Observation
+  runtime.subscribe()
+  html.subscribe()
+
+Behavior customization
+  resolve()
+  compiler adapter
+  ModuleUrlBackend
+```
+
+Lifecycle listeners are not interceptors: they cannot cancel evaluation, rewrite source, change resolution, or alter cache behavior. If source/evaluation interception is needed later, it must be designed as a separate hook contract with explicit ordering, async, cancellation, and caching semantics.
+
+Implementation note: core and HTML event streams share a small internal dispatcher so all/selective subscription behavior, independent disposers, and listener-error isolation have identical semantics while keeping separate event unions.
+
+Regression coverage: package tests cover catch-all, single-type, and multi-type subscriptions; independent unsubscribe; listener exception isolation; update/batch events; resolution/link/evaluation ordering and payloads; structured resolution errors; HTML ownership origins; observer connect/disconnect/batch events; root and append-target events; external source loading; entry execution; update/removal events; HTML error reporting; and HTML subscriber exception isolation.
+

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.8",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.8/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,223 @@ 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
+
+`0.0.8` expands lifecycle subscriptions into a typed event stream with independent join/leave semantics.
+
+Subscribe to everything:
+
+```ts
+const unsubscribe = runtime.subscribe(event => {
+  console.log(event.type, event);
+});
+```
+
+Subscribe to one event type:
+
+```ts
+const leaveErrors = runtime.subscribe(
+  "module-error",
+  event => {
+    console.error(event.phase, event.error);
+  },
+);
+```
+
+Subscribe to several event types:
+
+```ts
+const leaveEvaluation = runtime.subscribe(
+  ["module-evaluating", "module-evaluated"],
+  event => {
+    console.log(event.type, event.id);
+  },
+);
+```
+
+Each call owns an independent subscription:
+
+```ts
+leaveEvaluation();
+// the error subscription remains active
+```
+
+Core events include:
+
+```text
+module-defined
+module-updated
+modules-defined
+
+module-resolving
+module-resolved
+
+module-linking
+module-linked
+
+module-invalidated
+module-compiled
+module-evaluating
+module-evaluated
+
+module-removed
+module-error
+
+runtime-cleared
+runtime-disposed
+```
+
+`module-resolved` reports how a specifier was resolved (`relative`, `registered`, `custom`, `native`, and so on). `module-linked` exposes the logical dependency mapping used to link a source module. `modules-defined` marks the completion of a `defineMany()` batch after all definitions have been installed.
+
+`module-error.phase` is one of the runtime pipeline phases such as `resolve`, `analyze`, `compile`, `link`, `url-create`, `evaluate`, or `host-bridge`.
+
+Subscribers are observational only: they cannot cancel or modify runtime operations, and subscriber exceptions are isolated from runtime execution. Behavioral extension remains separate through the resolver, compiler adapter, and module URL backend.
+
+### HTML lifecycle events
+
+The HTML controller has its own event stream because DOM ownership/observation is intentionally separate from the core module engine:
+
+```ts
+const leaveHTML = html.subscribe(event => {
+  console.log(event.type, event);
+});
+```
+
+The same selective forms are supported:
+
+```ts
+const leaveOwnership = html.subscribe(
+  ["element-claimed", "element-registered", "element-removed"],
+  event => {
+    console.log(event.type, event.moduleId);
+  },
+);
+```
+
+HTML events include:
+
+```text
+element-discovered
+element-claimed
+element-loading
+element-loaded
+element-registered
+
+element-updating
+element-updated
+element-removing
+element-released
+element-removed
+
+observer-connected
+observer-disconnected
+observer-batch
+
+root-changing
+root-changed
+append-target-changed
+
+entry-executing
+entry-executed
+
+html-error
+```
+
+Ownership-related events include an `origin` describing how the element entered the controller (`observer`, `append`, `register-element`, `add-module`, and related internal scan origins). This is useful for tracing observer/manual-registration races and proving that an explicit `append()` was not processed a second time by the observer.
+
+`observer-batch` summarizes a DOM discovery pass instead of exposing noisy raw `MutationRecord` objects. `element-loading` / `element-loaded` are emitted for `src`-backed modules, and entry events distinguish evaluation caused by an HTML `entry` declaration from an ordinary `runtime.import()`.
+
+Like core runtime subscribers, HTML subscribers are observational and exception-isolated.
+
+## 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 +776,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;
@@ -90,6 +107,45 @@ export interface RegisterHTMLResult {
   }>;
 }
 
+export type HTMLRegistrationOrigin =
+  | "initial-scan"
+  | "observer"
+  | "observer-initial"
+  | "observer-root-change"
+  | "root-change-scan"
+  | "define-element"
+  | "register-element"
+  | "append"
+  | "add-module"
+  | "update-element"
+  | "remove-element"
+  | string;
+
+export type HTMLRuntimeEvent =
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-discovered"; element: HTMLModuleScriptElement; moduleId?: string; origin: HTMLRegistrationOrigin; accepted: boolean }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-claimed"; element: HTMLModuleScriptElement; moduleId: string; format: ModuleFormat; entry: boolean; sourceUrl?: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-loading"; element: HTMLModuleScriptElement; moduleId: string; sourceUrl: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-loaded"; element: HTMLModuleScriptElement; moduleId: string; sourceUrl: string; origin: HTMLRegistrationOrigin; bytes: number; durationMs: number }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-registered"; element: HTMLModuleScriptElement; moduleId: string; definition: HTMLModuleDefinition; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-updating"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-updated"; element: HTMLModuleScriptElement; moduleId: string; definition: HTMLModuleDefinition; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-removing"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin; removeModule: boolean; removeFromDOM: boolean }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-released"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-removed"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin; moduleRemoved: boolean; elementRemoved: boolean }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "observer-connected"; root: HTMLModuleRoot; subtree: boolean; registerExisting: boolean; reason: string }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "observer-disconnected"; root?: HTMLModuleRoot; reason: string }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "observer-batch"; root: HTMLModuleRoot; origin: HTMLRegistrationOrigin; discovered: number; matched: number; claimed: number; ignored: number; modules: string[] }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "root-changing"; previousRoot?: HTMLModuleRoot; root: HTMLModuleRoot; connected: boolean; registerExisting: boolean }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "root-changed"; previousRoot?: HTMLModuleRoot; root: HTMLModuleRoot; connected: boolean; registerExisting: boolean }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "append-target-changed"; previousTarget?: HTMLAppendTarget; target: HTMLAppendTarget }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "entry-executing"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "entry-executed"; element: HTMLModuleScriptElement; moduleId: string; namespace: ModuleNamespaceLike; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-error"; operation: "discover" | "claim" | "fetch" | "register" | "update" | "remove" | "entry" | "root-change" | "observer" | string; error: unknown; element?: HTMLModuleScriptElement; moduleId?: string; origin?: HTMLRegistrationOrigin };
+
+export type HTMLRuntimeEventType = HTMLRuntimeEvent["type"];
+export type HTMLRuntimeEventOfType<T extends HTMLRuntimeEventType> =
+  Extract<HTMLRuntimeEvent, { type: T }>;
+
 export interface ObserveHTMLOptions extends RegisterHTMLOptions {
   /** Register scripts already present when observation starts. Default: true. */
   registerExisting?: boolean;
@@ -141,6 +197,16 @@ export interface HTMLRuntimeController {
   /** Result of the observer's initial scan. */
   readonly initial: RegisterHTMLResult;
 
+  subscribe(listener: (event: HTMLRuntimeEvent) => void): () => boolean;
+  subscribe<T extends HTMLRuntimeEventType>(
+    type: T,
+    listener: (event: HTMLRuntimeEventOfType<T>) => void,
+  ): () => boolean;
+  subscribe<const T extends readonly HTMLRuntimeEventType[]>(
+    types: T,
+    listener: (event: HTMLRuntimeEventOfType<T[number]>) => void,
+  ): () => boolean;
+
   /** One-shot scan of matching scripts under the configured/root override. */
   register(options?: RegisterHTMLOptions): Promise<RegisterHTMLResult>;
 
@@ -181,6 +247,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,68 @@ 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 ModuleResolutionKind =
+  | "custom"
+  | "registered"
+  | "url"
+  | "absolute"
+  | "relative"
+  | "native";
+
+export type ModuleErrorPhase =
+  | "resolve"
+  | "analyze"
+  | "compile"
+  | "link"
+  | "url-create"
+  | "evaluate"
+  | "host-bridge";
+
+export interface LinkedDependency {
+  specifier: string;
+  resolvedId: string;
+}
+
+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-updated"; id: string; kind: ModuleInfo["kind"]; previousVersion: number; version: number; format?: ModuleFormat; module: ModuleInfo }
+  | { runtimeId: string; timestamp: number; type: "modules-defined"; ids: string[]; modules: ModuleInfo[] }
+  | { runtimeId: string; timestamp: number; type: "module-resolving"; specifier: string; importer: string | null }
+  | { runtimeId: string; timestamp: number; type: "module-resolved"; specifier: string; importer: string | null; resolvedId: string; resolutionKind: ModuleResolutionKind }
+  | { runtimeId: string; timestamp: number; type: "module-linking"; id: string; kind: ModuleInfo["kind"]; version: number }
+  | { runtimeId: string; timestamp: number; type: "module-linked"; id: string; kind: ModuleInfo["kind"]; version: number; dependencies: LinkedDependency[]; 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: ModuleErrorPhase; error: unknown }
+  | { runtimeId: string; timestamp: number; type: "runtime-cleared"; ids: string[]; preserveHostModules: boolean }
+  | { runtimeId: string; timestamp: number; type: "runtime-disposed" };
+
+export type RuntimeLifecycleEventType = RuntimeLifecycleEvent["type"];
+export type RuntimeLifecycleEventOfType<T extends RuntimeLifecycleEventType> =
+  Extract<RuntimeLifecycleEvent, { type: T }>;
+
+
 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 +147,17 @@ 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;
+  subscribe<T extends RuntimeLifecycleEventType>(
+    type: T,
+    listener: (event: RuntimeLifecycleEventOfType<T>) => void,
+  ): () => boolean;
+  subscribe<const T extends readonly RuntimeLifecycleEventType[]>(
+    types: T,
+    listener: (event: RuntimeLifecycleEventOfType<T[number]>) => 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.8",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {