solid-tag-runtime 0.0.9 → 0.0.11

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.
@@ -1196,3 +1197,41 @@ The shared render adapter lazily resolves the host application's own `solid-js`
 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.

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.11",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.11/html"
   }
 }
 ```
@@ -287,6 +287,17 @@ 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 scope is written to owned script elements as:
 
 ```html
@@ -295,6 +306,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 +866,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 +942,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 +950,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.11",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {

package/src/html.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;
 
@@ -157,6 +158,7 @@ export function createHTMLRuntime(runtime, options = {}) {
         accepted,
       });
       if (accepted) elements.push(element);
+      else maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
     }
 
     try {
@@ -906,30 +908,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 },
   );
 }
@@ -1103,6 +1130,7 @@ async function enqueueObserverScan(controller, callOptions = {}) {
       });
       if (!accepted) {
         ignored += 1;
+        maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
         continue;
       }
       matched += 1;
@@ -1778,6 +1806,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);
       }