solid-tag-runtime 0.0.11 → 0.0.12

package/ARCHITECTURE.md

@@ -1191,7 +1191,7 @@ The shared render adapter lazily resolves the host application's own `solid-js`
 10. Initial light-DOM child nodes are captured once and exposed as reusable `props.children`; named slots and dynamic child recapture are not part of this phase.
 11. Multiple elements may share one evaluated module namespace while owning independent Solid component roots.
 12. Disconnect disposes the mounted root; reconnect mounts a fresh component instance from the retained declaration inputs.
-13. Custom-element registration is global/idempotent per `CustomElementRegistry`. `createHTMLRuntime()` registers it after installing the controller in the shared registry; registration/observation paths remain idempotent. `registerSolidRenderElement()` remains available for explicit/custom-registry use.
+13. Custom-element registration is global/idempotent per `CustomElementRegistry`, but controller creation does **not** eagerly upgrade existing `solid-render` elements. Initial `register()` / `observe()` first install the complete declarative script batch and then ensure the custom element is registered. `registerSolidRenderElement()` remains available for explicit/custom-registry use.
 14. Runtime/controller disposal tears down both script-owned mounts and connected `solid-render` instances so no Solid owners are orphaned.
 
 Rendering lifecycle joins the existing HTML event stream through `render-mounting`, `render-mounted`, `render-disposing`, and `render-disposed`; failures are also reported through `html-error` with `render`/`solid-render` operations. Lifecycle subscriptions remain observational and cannot alter rendering.
@@ -1235,3 +1235,22 @@ Rules now enforced:
 7. `/ui/Button.jsx` and `./ui/Button.jsx` both resolve to the same registered virtual ID `/ui/Button.jsx` when imported at top level from the correct runtime.
 
 This keeps DOM routing and module routing failures separate and produces actionable errors instead of accidental browser network requests.
+
+
+### 0.0.12 — declarative registration barrier for `solid-render`
+
+Decision: an existing `<solid-render>` must never fail simply because its referenced `<script module>` has not yet been installed by the HTML adapter's initial registration pass.
+
+The 0.0.11 routing fix correctly selected the containing runtime, but `createHTMLRuntime()` still registered the global custom element immediately. Defining a custom element upgrades already-present `<solid-render>` nodes synchronously. Their `connectedCallback()` could therefore call `runtime.import("/ui/Button.jsx")` before `html.register()` had scanned and defined an earlier `<script module="/ui/Button.jsx">`, producing a legitimate but transient `ModuleResolutionError`.
+
+Rules now enforced:
+
+1. `createHTMLRuntime()` installs the controller in the shared registry but does not eagerly define/upgrade `<solid-render>`.
+2. Initial `register()` and initial `observe()` install their complete matching script batch first, then ensure the global custom element is registered. This preserves document-level declaration-before-instance semantics even though custom-element upgrade timing is synchronous.
+3. If the `solid-render` class was already registered globally by another controller, a connected instance may still run before this controller's declaration pass. A missing virtual module during an active registration/observer pass is treated as a pending reference rather than a terminal render error.
+4. After the registration/observer batch settles, pending instances inside that controller's root are retried. If the module is still missing after the batch, normal `solid-render` error semantics apply.
+5. A pending instance is also retried when its selected runtime later emits `module-defined` for the resolved module ID. This supports dynamically arriving declarative/programmatic modules without remounting already-successful instances.
+6. Retries remain generation-guarded, so stale async work cannot replace a newer module/component/runtime identity.
+7. The existing graph invariant remains unchanged: all declarations in a discovered script batch are defined before entry/render execution or recovery mounts are allowed to succeed.
+
+This separates three orderings that must all be correct: DOM parsing order, custom-element upgrade/connection timing, and runtime module-definition timing.

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.11",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.11/html"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.12",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.12/html"
   }
 }
 ```
@@ -275,7 +275,7 @@ Initial light-DOM children become `props.children`:
 
 The first implementation deliberately has no named-slot system and no Shadow DOM. Nested `<solid-render>` elements work through normal custom-element connection when captured children are instantiated.
 
-`createHTMLRuntime()` ensures the custom element is registered globally once after the controller has entered the shared runtime registry. `registerHTML()` / `observeHTML()` keep the same idempotent guarantee. Most applications therefore do not need to call a registration helper directly.
+The HTML adapter registers the custom element automatically **after the initial declarative script batch is installed** by `register()` / `registerHTML()` or the initial `observe()` / `observeHTML()` pass. `createHTMLRuntime()` intentionally does not upgrade existing `<solid-render>` elements immediately, because doing so could make them import modules before preceding `<script module>` declarations have been registered. Most applications therefore do not need to call a registration helper directly.
 
 For custom registries, tests, or explicit registration, the helper remains available:
 
@@ -298,6 +298,20 @@ Both of these reference the same registered virtual module when used with the co
 
 Top-level relative module references are normalized as virtual paths; they are not browser URL fetches.
 
+A document may safely declare a module and immediately reference it later in the same HTML before calling `register()`:
+
+```html
+<script type="solid-jsx" module="/ui/Button.jsx">
+  export default function Button() {
+    return <button>Ready</button>;
+  }
+</script>
+
+<solid-render module="/ui/Button.jsx"></solid-render>
+```
+
+The adapter installs the declaration batch before existing `solid-render` instances mount. If the custom element class was already registered by another runtime, unresolved instances are retried when the matching module becomes available. A transient startup ordering race therefore does not surface as a `ModuleResolutionError`. If the registration/observer queue settles and the referenced virtual module is still absent, the normal `solid-render` error is reported; the retry behavior does not hide genuine missing-module mistakes.
+
 A scope is written to owned script elements as:
 
 ```html

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {

package/src/html.js

@@ -1,4 +1,4 @@
-import { SolidTagRuntimeError } from "./errors.js";
+import { ModuleResolutionError, SolidTagRuntimeError } from "./errors.js";
 import { createEventDispatcher } from "./events.js";
 import { HTMLRenderError, createDefaultHTMLRenderAdapter, resolveRenderComponent } from "./render.js";
 
@@ -83,6 +83,9 @@ export function createHTMLRuntime(runtime, options = {}) {
     queue: Promise.resolve(),
     lastError: undefined,
     connected: false,
+    registrationDepth: 0,
+    registrationPasses: 0,
+    solidRenderRetryScheduled: false,
     initial: emptyRegistrationResult(),
   };
 
@@ -127,10 +130,13 @@ export function createHTMLRuntime(runtime, options = {}) {
 
   controller.api = api;
   activeControllers.add(controller);
-  // The HTML adapter owns the global custom-element registration. Registering
-  // here means a controller is already available before any existing
-  // <solid-render> elements are upgraded/connected. The helper is idempotent.
-  registerSolidRenderElement();
+  // Do not define/upgrade <solid-render> here. Existing declarative script
+  // modules must be installed first; otherwise connectedCallback() can import
+  // a module before register()/observe() has defined the preceding <script>.
+  // register()/observe() register the element after their initial script batch.
+  controller.runtimeModuleDefinedUnsubscribe = runtime.subscribe?.("module-defined", event => {
+    scheduleSolidRenderRetryForModule(controller, event.id);
+  });
   controller.runtimeDisposeUnsubscribe = runtime.subscribe?.("runtime-disposed", () => {
     void disposeController(controller, { runtimeDisposed: true });
   });
@@ -147,21 +153,23 @@ export function createHTMLRuntime(runtime, options = {}) {
     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);
-      else maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
-    }
+    const pendingBeforeUpgrade = collectConnectedSolidRenderElements(controller, root);
+    controller.registrationDepth += 1;
 
     try {
+      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);
+        else maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
+      }
+
       const result = await processElements(controller, elements, {
         ...callOptions,
         root,
@@ -169,11 +177,21 @@ export function createHTMLRuntime(runtime, options = {}) {
         executeEntries: callOptions.executeEntries ?? controller.executeEntries,
         executeRenders: callOptions.executeRenders ?? controller.executeRenders,
       });
+
+      // Existing upgraded instances may have connected before this controller's
+      // declaration batch was installed. Retry those after the batch completes.
       registerSolidRenderElement();
+      controller.registrationPasses += 1;
+      await retrySolidRenderElements(controller, pendingBeforeUpgrade, {
+        reason: "registration-complete",
+        forceMissingError: true,
+      });
       return result;
     } catch (error) {
       emitHTMLError(controller, "register", error, { origin });
       throw error;
+    } finally {
+      controller.registrationDepth = Math.max(0, controller.registrationDepth - 1);
     }
   }
 
@@ -186,6 +204,8 @@ export function createHTMLRuntime(runtime, options = {}) {
 
     const root = getRoot(mergeOptions(controller, callOptions), "HTML runtime observe");
     controller.observerOptions = { ...callOptions };
+    const pendingBeforeUpgrade = collectConnectedSolidRenderElements(controller, root);
+    controller.registrationDepth += 1;
 
     try {
       controller.initial = await connectObserver(controller, root, callOptions, {
@@ -193,9 +213,16 @@ export function createHTMLRuntime(runtime, options = {}) {
         initial: true,
       });
       registerSolidRenderElement();
+      controller.registrationPasses += 1;
+      await retrySolidRenderElements(controller, pendingBeforeUpgrade, {
+        reason: "observation-ready",
+        forceMissingError: true,
+      });
     } catch (error) {
       disconnect();
       throw error;
+    } finally {
+      controller.registrationDepth = Math.max(0, controller.registrationDepth - 1);
     }
 
     return api;
@@ -645,6 +672,8 @@ export function registerSolidRenderElement(options = {}) {
         mount: undefined,
         controller: undefined,
         propObserver: undefined,
+        pendingModuleResolution: undefined,
+        pendingCheckGeneration: undefined,
       });
     }
 
@@ -700,6 +729,8 @@ function getSolidRenderState(element) {
       mount: undefined,
       controller: undefined,
       propObserver: undefined,
+      pendingModuleResolution: undefined,
+      pendingCheckGeneration: undefined,
     };
     solidRenderInternals.set(element, state);
   }
@@ -738,10 +769,12 @@ function startSolidRenderPropObserver(element, state) {
   state.propObserver = observer;
 }
 
-async function remountSolidRender(element, reason) {
+async function remountSolidRender(element, reason, options = {}) {
   const state = getSolidRenderState(element);
   if (!state.connected) return;
   const generation = ++state.generation;
+  state.pendingModuleResolution = undefined;
+  state.pendingCheckGeneration = undefined;
   await disposeSolidRenderMount(element, state, reason === "connect" ? "reconnect" : reason);
   if (!state.connected || generation !== state.generation) return;
 
@@ -792,6 +825,8 @@ async function remountSolidRender(element, reason) {
 
     mount.mode = "container";
     state.mount = mount;
+    state.pendingModuleResolution = undefined;
+    state.pendingCheckGeneration = undefined;
     emitHTML(controller, {
       type: "render-mounted",
       element,
@@ -807,6 +842,26 @@ async function remountSolidRender(element, reason) {
     // failure belongs to the abandoned generation just like a stale success,
     // so it must not overwrite/report against the current element state.
     if (!state.connected || generation !== state.generation) return;
+    if (error instanceof ModuleResolutionError && controller) {
+      state.pendingModuleResolution = {
+        moduleId: nonEmpty(element.getAttribute?.("module")),
+        error,
+      };
+
+      // During startup or observer-driven DOM insertion a connected custom
+      // element can run before the matching declarative module has been
+      // installed. Treat that as a pending reference only until the relevant
+      // registration/observer queue has had a chance to settle.
+      if (!options.forceMissingError && (
+        controller.registrationDepth > 0
+        || controller.connected
+        || controller.registrationPasses === 0
+      )) {
+        schedulePendingSolidRenderResolutionCheck(element, state, controller, generation);
+        return;
+      }
+    }
+
     if (controller) {
       emitHTMLError(controller, "solid-render", error, {
         element,
@@ -985,6 +1040,116 @@ function mostSpecificController(controllers) {
   return undefined;
 }
 
+function schedulePendingSolidRenderResolutionCheck(element, state, controller, generation) {
+  if (state.pendingCheckGeneration === generation) return;
+  state.pendingCheckGeneration = generation;
+
+  const schedule = globalThis.setTimeout ?? ((callback) => Promise.resolve().then(callback));
+  schedule(async () => {
+    if (!state.connected || generation !== state.generation) return;
+    if (!state.pendingModuleResolution || state.mount) return;
+
+    // MutationObserver callbacks run before the next task. If this missing
+    // module came from a script + solid-render insertion batch, controller.queue
+    // now points at that registration work. Wait for it before deciding the
+    // reference is genuinely unresolved.
+    if (controller.connected) {
+      try {
+        await controller.queue;
+      } catch {
+        // Observer errors are reported through the normal controller path.
+      }
+    }
+
+    if (!state.connected || generation !== state.generation) return;
+    if (!state.pendingModuleResolution || state.mount) return;
+
+    // A direct register() may still be loading external source. Do not report
+    // a transient missing module while that pass is active.
+    if (controller.registrationDepth > 0) {
+      state.pendingCheckGeneration = undefined;
+      schedulePendingSolidRenderResolutionCheck(element, state, controller, generation);
+      return;
+    }
+
+    state.pendingCheckGeneration = undefined;
+    await remountSolidRender(element, "pending-module-settled", {
+      forceMissingError: true,
+    });
+  }, 0);
+}
+
+function collectConnectedSolidRenderElements(controller, root) {
+  const elements = new Set();
+
+  for (const element of controller.renderElements ?? []) {
+    const state = solidRenderInternals.get(element);
+    if (state?.connected && rootContainsElement(root, element)) elements.add(element);
+  }
+
+  if (root && typeof root.querySelectorAll === "function") {
+    for (const element of Array.from(root.querySelectorAll("solid-render") ?? [])) {
+      const state = solidRenderInternals.get(element);
+      if (state?.connected) elements.add(element);
+    }
+  }
+
+  return [...elements];
+}
+
+async function retrySolidRenderElements(controller, elements, options = {}) {
+  for (const element of elements ?? []) {
+    const state = solidRenderInternals.get(element);
+    if (!state?.connected) continue;
+    if (state.mount && !state.pendingModuleResolution) continue;
+
+    let selected;
+    try {
+      selected = resolveHTMLControllerForElement(element);
+    } catch {
+      continue;
+    }
+    if (selected !== controller) continue;
+
+    await remountSolidRender(element, options.reason ?? "retry", {
+      forceMissingError: options.forceMissingError === true,
+    });
+  }
+}
+
+function scheduleSolidRenderRetryForModule(controller, definedId) {
+  if (controller.disposed || controller.solidRenderRetryScheduled) return;
+  controller.solidRenderRetryScheduled = true;
+
+  const schedule = globalThis.queueMicrotask ?? (callback => Promise.resolve().then(callback));
+  schedule(() => {
+    controller.solidRenderRetryScheduled = false;
+    if (controller.disposed) return;
+
+    const matches = [];
+    for (const element of controller.renderElements) {
+      const state = solidRenderInternals.get(element);
+      if (!state?.connected || !state.pendingModuleResolution) continue;
+      const requested = nonEmpty(element.getAttribute?.("module"));
+      if (!requested) continue;
+      let resolved;
+      try {
+        resolved = controller.runtime.resolve(requested);
+      } catch {
+        continue;
+      }
+      if (resolved === definedId) matches.push(element);
+    }
+
+    if (matches.length > 0) {
+      void retrySolidRenderElements(controller, matches, {
+        reason: "module-defined",
+        forceMissingError: false,
+      });
+    }
+  });
+}
+
 function dispatchSolidRenderError(element, error) {
   try {
     const EventImpl = globalThis.CustomEvent;
@@ -1024,6 +1189,8 @@ async function disposeController(controller, options = {}) {
   }
 
   activeControllers.delete(controller);
+  controller.runtimeModuleDefinedUnsubscribe?.();
+  controller.runtimeModuleDefinedUnsubscribe = undefined;
   controller.runtimeDisposeUnsubscribe?.();
   controller.runtimeDisposeUnsubscribe = undefined;
   controller.events.clear();
@@ -1163,6 +1330,11 @@ async function enqueueObserverScan(controller, callOptions = {}) {
     }
 
     await cleanupDetachedRenderedDeclarations(controller, root);
+    await retrySolidRenderElements(
+      controller,
+      collectConnectedSolidRenderElements(controller, root),
+      { reason: "observer-batch-complete", forceMissingError: true },
+    );
 
     emitHTML(controller, {
       type: "observer-batch",