solid-tag-runtime 0.0.7 → 0.0.8

package/ARCHITECTURE.md

@@ -101,6 +101,7 @@ const runtime = createRuntime(options);
 
 ```ts
 runtime.define(id, source, options?);
+runtime.defineMany(definitions);
 runtime.update(id, source, options?);
 ```
 
@@ -138,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.
@@ -232,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?);
@@ -1031,3 +1045,102 @@ Invariants:
 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

@@ -107,8 +107,8 @@ 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"
+    "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"
   }
 }
 ```
@@ -572,28 +572,131 @@ 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
 
-// later
-unsubscribe();
+html-error
 ```
 
-Events currently include:
+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.
 
-- `module-defined`
-- `module-invalidated`
-- `module-compiled`
-- `module-evaluating`
-- `module-evaluated`
-- `module-removed`
-- `module-error`
-- `runtime-cleared`
-- `runtime-disposed`
+`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()`.
 
-Subscriber exceptions are isolated from runtime execution. This makes `subscribe()` suitable for tracing, developer tools, and editor diagnostics.
+Like core runtime subscribers, HTML subscribers are observational and exception-isolated.
 
 ## HTML-owned module updates and removal
 

package/html.d.ts

@@ -107,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;
@@ -158,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>;
 

package/index.d.ts

@@ -91,17 +91,50 @@ export interface ClearRuntimeOptions {
   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: string; error: unknown }
+  | { 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[];
@@ -117,6 +150,14 @@ export interface SolidTagRuntime {
   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.7",
+  "version": "0.0.8",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {

package/src/events.js

@@ -0,0 +1,63 @@
+export function createEventDispatcher(options = {}) {
+  const subscriptions = new Set();
+  const onListenerError = options.onListenerError;
+
+  return {
+    subscribe,
+    emit,
+    clear,
+    get size() {
+      return subscriptions.size;
+    },
+  };
+
+  function subscribe(typesOrListener, maybeListener) {
+    let types;
+    let listener;
+
+    if (typeof typesOrListener === "function") {
+      listener = typesOrListener;
+      types = undefined;
+    } else {
+      listener = maybeListener;
+      if (typeof typesOrListener === "string") {
+        types = new Set([typesOrListener]);
+      } else if (Array.isArray(typesOrListener)) {
+        if (typesOrListener.length === 0 || typesOrListener.some(type => typeof type !== "string" || !type)) {
+          throw new TypeError("subscribe(types, listener) expects a non-empty event type or event type array.");
+        }
+        types = new Set(typesOrListener);
+      } else {
+        throw new TypeError("subscribe() expects a listener, event type + listener, or event type array + listener.");
+      }
+    }
+
+    if (typeof listener !== "function") {
+      throw new TypeError("subscribe() expects a listener function.");
+    }
+
+    const subscription = { types, listener };
+    subscriptions.add(subscription);
+
+    return () => subscriptions.delete(subscription);
+  }
+
+  function emit(event) {
+    for (const subscription of [...subscriptions]) {
+      if (subscription.types && !subscription.types.has(event.type)) continue;
+      try {
+        subscription.listener(event);
+      } catch (error) {
+        try {
+          onListenerError?.(error, event);
+        } catch {
+          // Listener error reporting must never break the emitter.
+        }
+      }
+    }
+  }
+
+  function clear() {
+    subscriptions.clear();
+  }
+}