solid-tag-runtime 0.0.9 → 0.0.12

package/ARCHITECTURE.md

@@ -1122,6 +1122,7 @@ root-changed
 append-target-changed
 entry-executing
 entry-executed
+html-warning
 html-error
 ```
 
@@ -1180,7 +1181,7 @@ The shared render adapter lazily resolves the host application's own `solid-js`
 
 1. It references an existing runtime module; it never defines source.
 2. Missing `component` means `namespace.default`; `component="Name"` selects a named export.
-3. `data-solid-runtime` selects the HTML runtime through the shared controller registry. With no attribute, a single unambiguous controller may be used.
+3. `data-solid-runtime` selects a matching HTML controller whose configured root contains the element. Without the attribute, controller selection follows the same rule as unscoped script discovery: a containing scoped controller may participate when `acceptUnscoped:true`, while an unscoped controller naturally accepts it. Equally specific matches are ambiguous and require explicit scope. A controller outside the element's root is never selected merely because it is the only candidate.
 4. The element remains in the DOM and is the light-DOM mount container. Wrapperless rendering belongs to bare `<script render>`.
 5. Renderer configuration (`module`, `component`, `data-solid-runtime`) is never forwarded as component props.
 6. Declarative props use `prop:*`; kebab names normalize to camelCase. Empty/presence values are boolean `true`, other values remain strings.
@@ -1190,9 +1191,66 @@ 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.
 
 The first `solid-render` phase intentionally excludes named slots, Shadow DOM, automatic numeric/JSON coercion, arbitrary unprefixed prop forwarding, loading/fallback templates, and expression evaluation inside attributes.
+
+### 0.0.10 — unresolved scoped render diagnostics
+
+Decision: a declarative `<script render>` with an explicit `data-solid-runtime` scope must not disappear silently when no registered HTML controller can perform that immediate render action.
+
+The diagnostic remains an HTML-adapter concern. Core runtime resolution and module semantics are unchanged.
+
+Rules:
+
+1. Plain scoped module declarations remain quiet when seen by a non-matching controller; scope filtering is still normal routing behavior.
+2. An active render declaration (`render` present and `executeRenders !== false`) is immediate work. If no live controller with the requested scope has a root containing that declaration, discovery emits one warning.
+3. The warning is deduplicated per element + requested scope across overlapping controller scans. Repeated `register()` / observer passes must not spam the console.
+4. If a matching scoped controller is already registered and can cover the element's root, other controllers silently ignore the declaration and no warning is emitted.
+5. `executeRenders:false` intentionally disables render execution and therefore suppresses the missing-scope warning.
+6. The diagnostic is observable as `html-warning` with `code: "unresolved-runtime-scope"`, and is also surfaced through `console.warn` for developers who have not installed lifecycle tooling.
+7. `<solid-render>` remains stricter: a connected custom element that cannot resolve its runtime reports a render error because it is itself the active renderer.
+
+The warning belongs at the shared controller-registry/discovery boundary rather than being treated as an ownership or module-resolution error. This preserves the distinction between ordinary cross-scope filtering and an unfulfilled immediate render request.
+
+
+
+### 0.0.11 — `solid-render` routing parity and virtual top-level import safety
+
+Decision: `<solid-render>` controller selection must use the same scope/`acceptUnscoped`/root-boundary semantics as declarative script discovery.
+
+The 0.0.10 custom-element resolver treated an unscoped `<solid-render>` differently from an unscoped `<script>` declaration: it preferred controllers whose own scope was empty and could fall back to a sole candidate even when that controller's root did not contain the element. In pages/playgrounds with multiple active controllers this could select the wrong runtime. A registered virtual module such as `/ui/Button.jsx` would then appear missing and `runtime.import()` could fall through to native ESM loading, producing misleading network URLs such as an esm.sh-relative path.
+
+Rules now enforced:
+
+1. Explicit `data-solid-runtime="name"` considers only live controllers with that scope and whose root contains the element.
+2. An unscoped `<solid-render>` considers every containing controller that would accept an unscoped declaration: unscoped controllers plus scoped controllers with `acceptUnscoped:true`.
+3. When multiple containing controllers match, the most-specific root wins when one root is strictly nested inside the others; otherwise the selection is ambiguous and reports a render error.
+4. A controller outside the element's DOM root is never used as a fallback.
+5. Top-level `runtime.import()` now mirrors static-link resolution for virtual paths: unresolved relative (`./x`) and absolute virtual (`/x`) specifiers throw `ModuleResolutionError` even when `allowNativeImports:true`.
+6. Native fallback remains available for unresolved bare specifiers when `allowNativeImports:true`, and real absolute URLs remain native-loadable.
+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.9",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.9/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:
 
@@ -287,6 +287,31 @@ registerSolidRenderElement();
 
 Multiple `<solid-render>` elements may share one cached runtime module namespace while each mounted component owns independent Solid state. Async module changes are generation-guarded so a stale import can never replace a newer `module`/`component`/runtime selection.
 
+`<solid-render>` uses the same runtime-routing rules as declarative scripts. An explicit `data-solid-runtime` selects a controller with that scope **whose root contains the element**. Without an explicit scope, any containing controller that accepts unscoped declarations (`acceptUnscoped: true`) may handle the element. If more than one equally specific controller can handle it, add `data-solid-runtime` to disambiguate. Controllers outside the element's DOM root are never selected as a fallback.
+
+Both of these reference the same registered virtual module when used with the correct runtime:
+
+```html
+<solid-render module="/ui/Button.jsx"></solid-render>
+<solid-render module="./ui/Button.jsx"></solid-render>
+```
+
+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
@@ -295,6 +320,18 @@ A scope is written to owned script elements as:
 
 When multiple runtimes observe the same document, give each one a unique scope and normally set `acceptUnscoped: false`.
 
+A scoped declaration that only defines a module may be ignored by non-matching controllers without noise. A scoped declaration with active `render` semantics is different: rendering requests immediate UI work. If no registered HTML runtime with that scope can handle the declaration's DOM root, the adapter emits one deduplicated console warning and an `html-warning` lifecycle event with `code: "unresolved-runtime-scope"`. `executeRenders: false` suppresses this diagnostic because rendering was explicitly disabled.
+
+```ts
+html.subscribe("html-warning", event => {
+  if (event.code === "unresolved-runtime-scope") {
+    console.warn(event.requestedScope, event.moduleId);
+  }
+});
+```
+
+`<solid-render>` keeps stronger semantics: when it actively connects and cannot resolve its selected runtime, that is a render error rather than only a warning.
+
 ### Declarative modules
 
 ```html
@@ -843,11 +880,14 @@ render-mounted
 render-disposing
 render-disposed
 
+html-warning
 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.
 
+`html-warning` currently reports non-fatal adapter diagnostics. `unresolved-runtime-scope` is emitted once per render declaration/scope when `data-solid-runtime` requests immediate rendering but no registered controller can handle that scoped declaration. The event includes `requestedScope`, `registeredScopes`, `moduleId` when available, and whether a matching scope exists outside the declaration's root.
+
 `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()`. Render events cover both `<script render>` and `<solid-render>`; `source` identifies `script-render` versus `solid-render`, and `mode` identifies selector, in-place, or container mounting.
 
 Like core runtime subscribers, HTML subscribers are observational and exception-isolated.
@@ -916,7 +956,7 @@ Default runtime resolution supports:
 
 `allowNativeImports` defaults to `true`.
 
-This means an unresolved bare import can be left for the browser's native module resolver/import map:
+This means an unresolved **bare** import can be left for the browser's native module resolver/import map:
 
 ```ts
 const runtime = createRuntime({
@@ -924,7 +964,9 @@ const runtime = createRuntime({
 });
 ```
 
-Set it to `false` when all module dependencies must be explicitly registered with the runtime.
+Relative and absolute virtual paths are different. If `/ui/Button.jsx` or `./ui/Button.jsx` does not resolve to a registered runtime module, `runtime.import()` throws `ModuleResolutionError`; it does not turn the path into a browser/native network import. Use `defineUrl()` or an actual absolute URL when native URL loading is intended.
+
+Set `allowNativeImports` to `false` when even unresolved bare imports must be explicitly registered with the runtime.
 
 ## Runtime lifecycle
 

package/html.d.ts

@@ -216,6 +216,7 @@ export type HTMLRuntimeEvent =
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-mounted"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; target?: unknown; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-disposing"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; reason: string; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-disposed"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; reason: string; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-warning"; code: "unresolved-runtime-scope"; operation: "render"; message: string; element: HTMLModuleScriptElement; moduleId?: string; requestedScope: string; registeredScopes: string[]; matchingScopeRegistered: boolean; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-error"; operation: "discover" | "claim" | "fetch" | "register" | "update" | "remove" | "entry" | "render" | "solid-render" | "root-change" | "observer" | string; error: unknown; element?: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; origin?: HTMLRegistrationOrigin };
 
 export type HTMLRuntimeEventType = HTMLRuntimeEvent["type"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.9",
+  "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";
 
@@ -17,6 +17,7 @@ const defaultControllers = new WeakMap();
 const activeControllers = new Set();
 const solidRenderClasses = new WeakMap();
 const solidRenderInternals = new WeakMap();
+const unresolvedRenderScopeWarnings = new WeakMap();
 let anonymousSequence = 0;
 let controllerSequence = 0;
 
@@ -82,6 +83,9 @@ export function createHTMLRuntime(runtime, options = {}) {
     queue: Promise.resolve(),
     lastError: undefined,
     connected: false,
+    registrationDepth: 0,
+    registrationPasses: 0,
+    solidRenderRetryScheduled: false,
     initial: emptyRegistrationResult(),
   };
 
@@ -126,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 });
   });
@@ -146,20 +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);
-    }
+    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,
@@ -167,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);
     }
   }
 
@@ -184,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, {
@@ -191,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;
@@ -643,6 +672,8 @@ export function registerSolidRenderElement(options = {}) {
         mount: undefined,
         controller: undefined,
         propObserver: undefined,
+        pendingModuleResolution: undefined,
+        pendingCheckGeneration: undefined,
       });
     }
 
@@ -698,6 +729,8 @@ function getSolidRenderState(element) {
       mount: undefined,
       controller: undefined,
       propObserver: undefined,
+      pendingModuleResolution: undefined,
+      pendingCheckGeneration: undefined,
     };
     solidRenderInternals.set(element, state);
   }
@@ -736,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;
 
@@ -790,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,
@@ -805,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,
@@ -906,30 +963,55 @@ function kebabToCamel(value) {
 function resolveHTMLControllerForElement(element) {
   const scope = nonEmpty(element.getAttribute?.(RUNTIME_SCOPE_ATTRIBUTE));
   const live = [...activeControllers].filter(controller => !controller.disposed);
-  let candidates = scope
-    ? live.filter(controller => controller.scope === scope)
-    : live.filter(controller => !controller.scope);
 
-  if (!scope && candidates.length === 0 && live.length === 1) candidates = live;
-  const contained = candidates.filter(controller => rootContainsElement(controller.root ?? globalThis.document, element));
+  // <solid-render> must use the same routing semantics as discovered script
+  // declarations. In particular, an unscoped element may be handled by a
+  // scoped controller when that controller accepts unscoped declarations.
+  // Root containment is also authoritative: never fall back to a controller
+  // outside the element's DOM boundary merely because it is the only candidate.
+  const candidates = live.filter(controller => {
+    if (scope) return controller.scope === scope;
+    return controller.scope ? controller.acceptUnscoped !== false : true;
+  });
+  const contained = candidates.filter(controller =>
+    rootContainsElement(controller.root ?? globalThis.document, element)
+  );
+
   if (contained.length === 1) return contained[0];
   if (contained.length > 1) {
     const specific = mostSpecificController(contained);
     if (specific) return specific;
   }
-  if (candidates.length === 1) return candidates[0];
 
-  if (candidates.length === 0) {
+  if (contained.length === 0) {
+    if (scope) {
+      if (candidates.length === 0) {
+        throw new HTMLRenderError(
+          `No HTML runtime is registered for data-solid-runtime=${JSON.stringify(scope)}.`,
+          { element },
+        );
+      }
+      throw new HTMLRenderError(
+        `HTML runtime scope ${JSON.stringify(scope)} is registered, but no matching controller root contains this <solid-render> element.`,
+        { element },
+      );
+    }
+
+    if (candidates.length === 0) {
+      throw new HTMLRenderError(
+        "No HTML runtime accepts this unscoped <solid-render>. Add data-solid-runtime or enable acceptUnscoped on the intended controller.",
+        { element },
+      );
+    }
+
     throw new HTMLRenderError(
-      scope
-        ? `No HTML runtime is registered for data-solid-runtime=${JSON.stringify(scope)}.`
-        : "No unambiguous HTML runtime is available for <solid-render>. Add data-solid-runtime when multiple runtimes exist.",
+      "No HTML runtime that accepts unscoped declarations has a root containing this <solid-render> element.",
       { element },
     );
   }
 
   throw new HTMLRenderError(
-    `Multiple HTML runtimes match <solid-render>${scope ? ` for scope ${JSON.stringify(scope)}` : ""}. Use distinct scopes or DOM roots.`,
+    `Multiple HTML runtimes match <solid-render>${scope ? ` for scope ${JSON.stringify(scope)}` : ""}. Use data-solid-runtime, distinct scopes, or non-overlapping DOM roots.`,
     { element },
   );
 }
@@ -958,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;
@@ -997,6 +1189,8 @@ async function disposeController(controller, options = {}) {
   }
 
   activeControllers.delete(controller);
+  controller.runtimeModuleDefinedUnsubscribe?.();
+  controller.runtimeModuleDefinedUnsubscribe = undefined;
   controller.runtimeDisposeUnsubscribe?.();
   controller.runtimeDisposeUnsubscribe = undefined;
   controller.events.clear();
@@ -1103,6 +1297,7 @@ async function enqueueObserverScan(controller, callOptions = {}) {
       });
       if (!accepted) {
         ignored += 1;
+        maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
         continue;
       }
       matched += 1;
@@ -1135,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",
@@ -1778,6 +1978,52 @@ function acceptsDiscoveredElement(controller, element, options = {}) {
   return !elementScope;
 }
 
+function maybeWarnUnresolvedRenderScope(controller, element, options = {}, origin = "discover") {
+  if ((options.executeRenders ?? controller.executeRenders) === false) return false;
+  if (!hasAttribute(element, "render")) return false;
+
+  const requestedScope = nonEmpty(element?.getAttribute?.(RUNTIME_SCOPE_ATTRIBUTE));
+  if (!requestedScope) return false;
+
+  const live = [...activeControllers].filter(candidate => !candidate.disposed);
+  const matchingScopeControllers = live.filter(candidate => candidate.scope === requestedScope);
+  const handlingController = matchingScopeControllers.find(candidate =>
+    rootContainsElement(candidate.root ?? globalThis.document, element)
+  );
+  if (handlingController) return false;
+
+  if (unresolvedRenderScopeWarnings.get(element) === requestedScope) return false;
+  unresolvedRenderScopeWarnings.set(element, requestedScope);
+
+  const registeredScopes = [...new Set(live.map(candidate => candidate.scope).filter(Boolean))].sort();
+  const moduleId = nonEmpty(element?.getAttribute?.("module"));
+  const scopeLabel = JSON.stringify(requestedScope);
+  const moduleLabel = moduleId ? ` module=${JSON.stringify(moduleId)}` : "";
+  const message = matchingScopeControllers.length > 0
+    ? `solid-tag-runtime/html: Unable to render <script${moduleLabel}> for data-solid-runtime=${scopeLabel} because matching HTML runtime controller(s) exist, but none has a root containing this declaration.`
+    : `solid-tag-runtime/html: Unable to render <script${moduleLabel}> because data-solid-runtime=${scopeLabel} does not match any registered HTML runtime.`;
+
+  emitHTML(controller, {
+    type: "html-warning",
+    code: "unresolved-runtime-scope",
+    operation: "render",
+    message,
+    element,
+    moduleId,
+    requestedScope,
+    registeredScopes,
+    matchingScopeRegistered: matchingScopeControllers.length > 0,
+    origin,
+  });
+
+  globalThis.console?.warn?.(message, {
+    element,
+    requestedScope,
+    registeredScopes,
+  });
+  return true;
+}
+
 function assertExplicitScopeCompatibility(controller, element, options = {}) {
   const requestedScope = normalizeScope(options.scope ?? controller.scope);
   const elementScope = nonEmpty(element.getAttribute(RUNTIME_SCOPE_ATTRIBUTE));

package/src/runtime.js

@@ -245,6 +245,14 @@ export function createRuntime(options = {}) {
     const record = records.get(resolved);
 
     if (!record) {
+      // Top-level virtual path imports follow the same rule as static imports:
+      // unresolved relative/absolute virtual IDs are runtime resolution errors,
+      // not native browser fetches. Native fallback is reserved for absolute
+      // URLs and unresolved bare specifiers when allowNativeImports is enabled.
+      const raw = String(id);
+      if (isRelativeSpecifier(raw) || raw.startsWith("/")) {
+        throw new ModuleResolutionError(id, null);
+      }
       if (!allowNativeImports && !isAbsoluteUrl(resolved)) {
         throw new ModuleResolutionError(id, null);
       }