solid-tag-runtime 0.0.6 → 0.0.8

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();
+  }
+}

package/src/html.js

@@ -1,4 +1,5 @@
 import { SolidTagRuntimeError } from "./errors.js";
+import { createEventDispatcher } from "./events.js";
 
 const DEFAULT_SELECTOR = [
   'script[type="solid-jsx"]',
@@ -47,6 +48,11 @@ export function createHTMLRuntime(runtime, options = {}) {
   const controller = {
     id: `solid-tag-html-${++controllerSequence}`,
     runtime,
+    events: createEventDispatcher({
+      onListenerError(error) {
+        globalThis.console?.error?.("solid-tag-runtime/html lifecycle subscriber error", error);
+      },
+    }),
     scope: normalizeScope(options.scope),
     root: options.root,
     selector: options.selector ?? DEFAULT_SELECTOR,
@@ -88,6 +94,7 @@ export function createHTMLRuntime(runtime, options = {}) {
     get appendTarget() {
       return getAppendTarget(controller);
     },
+    subscribe,
     register,
     observe,
     flush,
@@ -97,6 +104,8 @@ export function createHTMLRuntime(runtime, options = {}) {
     setAppendTarget,
     defineElement,
     registerElement,
+    updateElement,
+    removeElement,
     append,
     addModule,
     owns,
@@ -107,20 +116,41 @@ export function createHTMLRuntime(runtime, options = {}) {
   controller.api = api;
   return api;
 
+  function subscribe(typesOrListener, maybeListener) {
+    return controller.events.subscribe(typesOrListener, maybeListener);
+  }
+
   /** One-shot scan of matching scripts. */
   async function register(callOptions = {}) {
     const root = getRoot(mergeOptions(controller, callOptions), "HTML runtime register");
     const selector = callOptions.selector ?? controller.selector;
-    const elements = Array.from(root.querySelectorAll(selector)).filter(element =>
-      acceptsDiscoveredElement(controller, element, callOptions),
-    );
+    const origin = callOptions.origin ?? "initial-scan";
+    const discovered = Array.from(root.querySelectorAll(selector));
+    const elements = [];
+
+    for (const element of discovered) {
+      const accepted = acceptsDiscoveredElement(controller, element, callOptions);
+      emitHTML(controller, {
+        type: "element-discovered",
+        element,
+        moduleId: nonEmpty(element?.getAttribute?.("module")),
+        origin,
+        accepted,
+      });
+      if (accepted) elements.push(element);
+    }
 
-    return processElements(controller, elements, {
-      ...callOptions,
-      root,
-      origin: callOptions.origin ?? "initial-scan",
-      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
-    });
+    try {
+      return await processElements(controller, elements, {
+        ...callOptions,
+        root,
+        origin,
+        executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+      });
+    } catch (error) {
+      emitHTMLError(controller, "register", error, { origin });
+      throw error;
+    }
   }
 
   /**
@@ -172,6 +202,15 @@ export function createHTMLRuntime(runtime, options = {}) {
    */
   async function setRoot(root, callOptions = {}) {
     const nextRoot = getRoot({ root }, "HTML runtime setRoot");
+    const previousRoot = controller.root ?? globalThis.document;
+    const previousAppendTarget = getAppendTarget(controller);
+    emitHTML(controller, {
+      type: "root-changing",
+      previousRoot,
+      root: nextRoot,
+      connected: controller.connected,
+      registerExisting: callOptions.registerExisting ?? controller.connected,
+    });
 
     // Finish work scheduled against the old root before rebinding observer state.
     await controller.queue;
@@ -184,7 +223,7 @@ export function createHTMLRuntime(runtime, options = {}) {
     const wasConnected = controller.connected;
     const previousObserverOptions = controller.observerOptions ?? {};
 
-    if (wasConnected) stopObserver(controller, { preserveOptions: true });
+    if (wasConnected) stopObserver(controller, { preserveOptions: true, reason: "root-change" });
 
     controller.root = nextRoot;
     if (Object.prototype.hasOwnProperty.call(callOptions, "appendTo")) {
@@ -202,10 +241,13 @@ export function createHTMLRuntime(runtime, options = {}) {
       };
       controller.observerOptions = { ...observeOptions };
       try {
-        return await connectObserver(controller, nextRoot, observeOptions, {
+        const result = await connectObserver(controller, nextRoot, observeOptions, {
           registerExisting,
           initial: false,
+          reason: "root-change",
         });
+        emitRootChanged(controller, previousRoot, nextRoot, registerExisting, previousAppendTarget);
+        return result;
       } catch (error) {
         stopObserver(controller, { preserveOptions: true });
         throw error;
@@ -213,9 +255,12 @@ export function createHTMLRuntime(runtime, options = {}) {
     }
 
     if (registerExisting) {
-      return register({ ...callOptions, root: nextRoot });
+      const result = await register({ ...callOptions, root: nextRoot, origin: callOptions.origin ?? "root-change-scan" });
+      emitRootChanged(controller, previousRoot, nextRoot, registerExisting, previousAppendTarget);
+      return result;
     }
 
+    emitRootChanged(controller, previousRoot, nextRoot, registerExisting, previousAppendTarget);
     return emptyRegistrationResult();
   }
 
@@ -233,7 +278,15 @@ export function createHTMLRuntime(runtime, options = {}) {
     if (!target || (typeof target.append !== "function" && typeof target.appendChild !== "function")) {
       throw new TypeError("setAppendTarget() requires a target with append() or appendChild().");
     }
+    const previousTarget = getAppendTarget(controller);
     controller.appendTo = target;
+    if (previousTarget !== target) {
+      emitHTML(controller, {
+        type: "append-target-changed",
+        previousTarget,
+        target,
+      });
+    }
     return api;
   }
 
@@ -259,6 +312,152 @@ 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");
+    emitHTML(controller, {
+      type: "element-updating",
+      element,
+      moduleId: record.moduleId,
+      origin: callOptions.origin ?? "update-element",
+    });
+    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";
+      emitHTML(controller, {
+        type: "entry-executing",
+        element,
+        moduleId: record.moduleId,
+        origin: callOptions.origin ?? "update-element",
+      });
+      try {
+        const namespace = await runtime.import(record.moduleId);
+        record.state = "ready";
+        emitHTML(controller, {
+          type: "entry-executed",
+          element,
+          moduleId: record.moduleId,
+          namespace,
+          origin: callOptions.origin ?? "update-element",
+        });
+      } catch (error) {
+        record.state = "error";
+        record.error = error;
+        emitHTMLError(controller, "entry", error, {
+          element,
+          moduleId: record.moduleId,
+          origin: callOptions.origin ?? "update-element",
+        });
+        throw error;
+      }
+    }
+
+    emitHTML(controller, {
+      type: "element-updated",
+      element,
+      moduleId: record.moduleId,
+      definition: record.definition,
+      origin: callOptions.origin ?? "update-element",
+    });
+    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 origin = callOptions.origin ?? "remove-element";
+    emitHTML(controller, {
+      type: "element-removing",
+      element,
+      moduleId: record.moduleId,
+      origin,
+      removeModule: callOptions.removeModule !== false,
+      removeFromDOM: callOptions.removeFromDOM !== false,
+    });
+    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";
+    emitHTML(controller, {
+      type: "element-released",
+      element,
+      moduleId: record.moduleId,
+      origin,
+    });
+
+    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);
+    }
+
+    const result = {
+      id: record.moduleId,
+      element,
+      moduleRemoved,
+      elementRemoved,
+    };
+    emitHTML(controller, {
+      type: "element-removed",
+      element,
+      moduleId: record.moduleId,
+      origin,
+      moduleRemoved,
+      elementRemoved,
+    });
+    return result;
+  }
+
   /**
    * Claim a user-created script before DOM insertion, append it to this
    * controller's target, then register it directly. The observer will see the
@@ -404,6 +603,13 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
     childList: true,
     subtree: callOptions.subtree ?? controller.subtree,
   });
+  emitHTML(controller, {
+    type: "observer-connected",
+    root,
+    subtree: callOptions.subtree ?? controller.subtree,
+    registerExisting,
+    reason: mode.reason ?? (mode.initial ? "observe" : "connect"),
+  });
 
   const result = registerExisting
     ? await enqueueObserverScan(controller, {
@@ -418,11 +624,17 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
 
 function stopObserver(controller, options = {}) {
   if (!controller.connected && !controller.observer) return;
+  const root = controller.observerRoot;
   controller.connected = false;
   controller.observer?.disconnect();
   controller.observer = undefined;
   controller.observerRoot = undefined;
   if (!options.preserveOptions) controller.observerOptions = undefined;
+  emitHTML(controller, {
+    type: "observer-disconnected",
+    root,
+    reason: options.reason ?? "disconnect",
+  });
 }
 
 async function enqueueObserverScan(controller, callOptions = {}) {
@@ -431,23 +643,76 @@ async function enqueueObserverScan(controller, callOptions = {}) {
 
     const root = controller.observerRoot ?? getRoot(mergeOptions(controller, callOptions), "HTML runtime observer");
     const selector = callOptions.selector ?? controller.selector;
-    const elements = Array.from(root.querySelectorAll(selector)).filter(element => {
-      if (controller.ignoredExisting.has(element)) return false;
-      if (!acceptsDiscoveredElement(controller, element, callOptions)) return false;
+    const origin = callOptions.origin ?? "observer";
+    const discovered = Array.from(root.querySelectorAll(selector));
+    const elements = [];
+    let matched = 0;
+    let ignored = 0;
+
+    for (const element of discovered) {
+      if (controller.ignoredExisting.has(element)) {
+        ignored += 1;
+        emitHTML(controller, {
+          type: "element-discovered",
+          element,
+          moduleId: nonEmpty(element?.getAttribute?.("module")),
+          origin,
+          accepted: false,
+        });
+        continue;
+      }
+
+      const accepted = acceptsDiscoveredElement(controller, element, callOptions);
+      emitHTML(controller, {
+        type: "element-discovered",
+        element,
+        moduleId: nonEmpty(element?.getAttribute?.("module")),
+        origin,
+        accepted,
+      });
+      if (!accepted) {
+        ignored += 1;
+        continue;
+      }
+      matched += 1;
 
       const ownership = elementOwners.get(element);
-      if (!ownership) return true;
-      if (ownership.owner === controller) return false;
+      if (!ownership) {
+        elements.push(element);
+        continue;
+      }
+      if (ownership.owner === controller) {
+        ignored += 1;
+        continue;
+      }
 
       throw ownershipError(controller, element, ownership);
-    });
+    }
 
-    return processElements(controller, elements, {
-      ...callOptions,
+    let result;
+    try {
+      result = await processElements(controller, elements, {
+        ...callOptions,
+        root,
+        origin,
+        executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+      });
+    } catch (error) {
+      emitHTMLError(controller, "observer", error, { origin });
+      throw error;
+    }
+
+    emitHTML(controller, {
+      type: "observer-batch",
       root,
-      origin: callOptions.origin ?? "observer",
-      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+      origin,
+      discovered: discovered.length,
+      matched,
+      claimed: result.modules.length,
+      ignored,
+      modules: result.modules.map(module => module.id),
     });
+    return result;
   });
 
   controller.queue = task.then(
@@ -494,6 +759,12 @@ async function processClaims(controller, records, options = {}) {
   try {
     prepared = await Promise.all(records.map(record => prepareRecordSource(controller, record, options)));
   } catch (error) {
+    const failed = records.find(record => record.state === "loading") ?? records[0];
+    emitHTMLError(controller, failed?.sourceUrl ? "fetch" : "register", error, {
+      element: failed?.element,
+      moduleId: failed?.moduleId,
+      origin: failed?.origin ?? options.origin,
+    });
     for (const record of records) rejectRecord(record, error);
     throw error;
   }
@@ -511,8 +782,21 @@ async function processClaims(controller, records, options = {}) {
       record.definition = definitionFromRecord(record);
       record.resolve(record.definition);
       modules.push(record.definition);
+      emitHTML(controller, {
+        type: "element-registered",
+        element: record.element,
+        moduleId: record.moduleId,
+        definition: record.definition,
+        origin: record.origin,
+      });
     }
   } catch (error) {
+    const failed = records.find(record => record.state === "claimed" || record.state === "loading") ?? records[0];
+    emitHTMLError(controller, "register", error, {
+      element: failed?.element,
+      moduleId: failed?.moduleId,
+      origin: failed?.origin ?? options.origin,
+    });
     for (const record of records) {
       if (record.state === "claimed" || record.state === "loading") rejectRecord(record, error);
     }
@@ -528,14 +812,32 @@ async function processClaims(controller, records, options = {}) {
       if (record) record.state = "executing";
 
       try {
+        emitHTML(controller, {
+          type: "entry-executing",
+          element: entry.element,
+          moduleId: entry.id,
+          origin: record?.origin ?? options.origin ?? "entry",
+        });
         const namespace = await controller.runtime.import(entry.id);
         if (record) record.state = "ready";
         executed.push({ id: entry.id, namespace });
+        emitHTML(controller, {
+          type: "entry-executed",
+          element: entry.element,
+          moduleId: entry.id,
+          namespace,
+          origin: record?.origin ?? options.origin ?? "entry",
+        });
       } catch (error) {
         if (record) {
           record.state = "error";
           record.error = error;
         }
+        emitHTMLError(controller, "entry", error, {
+          element: entry.element,
+          moduleId: entry.id,
+          origin: record?.origin ?? options.origin ?? "entry",
+        });
         throw error;
       }
     }
@@ -608,6 +910,15 @@ function claimElement(controller, element, options = {}) {
 
   elementOwners.set(element, record);
   controller.bindings.set(moduleId, record);
+  emitHTML(controller, {
+    type: "element-claimed",
+    element,
+    moduleId,
+    format: record.format,
+    entry: record.entry,
+    sourceUrl: record.sourceUrl,
+    origin: record.origin,
+  });
   return { fresh: true, record };
 }
 
@@ -616,12 +927,29 @@ async function prepareRecordSource(controller, record, options) {
 
   let source;
   if (record.sourceUrl) {
+    const startedAt = performanceNow();
+    emitHTML(controller, {
+      type: "element-loading",
+      element: record.element,
+      moduleId: record.moduleId,
+      sourceUrl: record.sourceUrl,
+      origin: record.origin,
+    });
     source = await fetchSource(
       record.sourceUrl,
       options.fetch ?? controller.fetch ?? globalThis.fetch,
       record.element,
       record.moduleId,
     );
+    emitHTML(controller, {
+      type: "element-loaded",
+      element: record.element,
+      moduleId: record.moduleId,
+      sourceUrl: record.sourceUrl,
+      origin: record.origin,
+      bytes: String(source).length,
+      durationMs: performanceNow() - startedAt,
+    });
   } else {
     source = record.element.textContent ?? "";
   }
@@ -649,7 +977,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 +988,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,
@@ -741,6 +1098,46 @@ function ownershipError(controller, element, ownership) {
   );
 }
 
+function emitHTML(controller, event) {
+  controller.events.emit({
+    htmlRuntimeId: controller.id,
+    scope: controller.scope,
+    timestamp: Date.now(),
+    ...event,
+  });
+}
+
+function emitHTMLError(controller, operation, error, context = {}) {
+  emitHTML(controller, {
+    type: "html-error",
+    operation,
+    error,
+    ...context,
+  });
+}
+
+function emitRootChanged(controller, previousRoot, root, registerExisting, previousAppendTarget) {
+  emitHTML(controller, {
+    type: "root-changed",
+    previousRoot,
+    root,
+    registerExisting,
+    connected: controller.connected,
+  });
+  const nextAppendTarget = getAppendTarget(controller);
+  if (previousAppendTarget !== nextAppendTarget) {
+    emitHTML(controller, {
+      type: "append-target-changed",
+      previousTarget: previousAppendTarget,
+      target: nextAppendTarget,
+    });
+  }
+}
+
+function performanceNow() {
+  return globalThis.performance?.now?.() ?? Date.now();
+}
+
 function getDefaultController(runtime, options = {}) {
   assertRuntime(runtime);
   let controller = defaultControllers.get(runtime);