solid-tag-runtime 0.0.7 → 0.0.8

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,
@@ -109,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;
+    }
   }
 
   /**
@@ -174,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;
@@ -186,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")) {
@@ -204,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;
@@ -215,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();
   }
 
@@ -235,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;
   }
 
@@ -268,6 +319,12 @@ export function createHTMLRuntime(runtime, options = {}) {
    */
   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,
@@ -302,16 +359,41 @@ export function createHTMLRuntime(runtime, options = {}) {
 
     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 {
-        await runtime.import(record.moduleId);
+        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;
   }
 
@@ -322,6 +404,15 @@ export function createHTMLRuntime(runtime, options = {}) {
    */
   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;
@@ -334,6 +425,12 @@ export function createHTMLRuntime(runtime, options = {}) {
     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) {
@@ -344,12 +441,21 @@ export function createHTMLRuntime(runtime, options = {}) {
       controller.ignoredExisting.add(element);
     }
 
-    return {
+    const result = {
       id: record.moduleId,
       element,
       moduleRemoved,
       elementRemoved,
     };
+    emitHTML(controller, {
+      type: "element-removed",
+      element,
+      moduleId: record.moduleId,
+      origin,
+      moduleRemoved,
+      elementRemoved,
+    });
+    return result;
   }
 
   /**
@@ -497,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, {
@@ -511,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 = {}) {
@@ -524,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(
@@ -587,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;
   }
@@ -604,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);
     }
@@ -621,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;
       }
     }
@@ -701,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 };
 }
 
@@ -709,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 ?? "";
   }
@@ -863,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);