solid-tag-runtime 0.0.8 → 0.0.11

package/ARCHITECTURE.md

@@ -42,7 +42,9 @@ The runtime should allow applications to:
 9. observe runtime lifecycle transitions for tooling/tracing
 10. inspect dependencies and compiled source
 11. support normal JavaScript modules in the same graph
-12. keep the JSX compiler replaceable behind a narrow adapter
+12. declaratively mount runtime component exports through the HTML adapter
+13. reuse existing runtime modules through a light-DOM `solid-render` custom element
+14. keep the JSX compiler replaceable behind a narrow adapter
 
 ## 3. Current non-goals
 
@@ -1120,6 +1122,7 @@ root-changed
 append-target-changed
 entry-executing
 entry-executed
+html-warning
 html-error
 ```
 
@@ -1144,3 +1147,91 @@ Implementation note: core and HTML event streams share a small internal dispatch
 
 Regression coverage: package tests cover catch-all, single-type, and multi-type subscriptions; independent unsubscribe; listener exception isolation; update/batch events; resolution/link/evaluation ordering and payloads; structured resolution errors; HTML ownership origins; observer connect/disconnect/batch events; root and append-target events; external source loading; entry execution; update/removal events; HTML error reporting; and HTML subscriber exception isolation.
 
+
+
+### 0.0.9 — shared declarative rendering and `solid-render`
+
+Decision: rendering remains entirely inside `solid-tag-runtime/html`. The core runtime still owns module identity, resolution, linking, execution, caching, invalidation, and host-module injection; it has no DOM or component-mounting responsibility.
+
+Two public rendering forms now share one internal rendering core:
+
+```text
+<script module render>
+  define source + mount one component instance
+
+<solid-render module>
+  reference an existing module + mount one component instance
+```
+
+Declarative script rendering follows these invariants:
+
+- `render="#selector"` imports the module, selects `default` unless `component="Name"` is present, and uses normal Solid container rendering.
+- bare `render` replaces the declaration with start/end comment markers and mounts with positional insertion before the end marker; no wrapper element is introduced.
+- every discovered module in a batch is defined before any `entry` or render action executes.
+- `entry` and `render` on the same declaration are rejected as ambiguous.
+- anonymous `render` declarations receive internal runtime IDs just like anonymous entries.
+- render ownership/disposal is stored on the HTML declaration record and remains separate from module lifetime.
+- `updateElement()` remounts a rendered declaration after source/component/render metadata changes while preserving the same logical module identity.
+- `removeElement()` disposes mounted UI before releasing declaration/module ownership.
+- observer-discovered render declarations use the same batch/ownership pipeline as ordinary declarations.
+
+The shared render adapter lazily resolves the host application's own `solid-js` and `@solidjs/web` modules through the runtime (with `solid-js/web` as a compatibility fallback). This preserves the no-duplicate-Solid invariant and keeps the HTML package free of a direct Solid dependency. Tests/special hosts may inject a render adapter.
+
+`solid-render` invariants:
+
+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 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.
+7. `.props` carries arbitrary JavaScript references and overrides declarative props.
+8. Prop changes update a reactive prop facade and do not remount the component, preserving local state.
+9. Module/component/runtime identity changes increment a generation token, dispose the current owner, and remount. Stale async import successes and failures are ignored; they cannot mount or report an error against a newer identity.
+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.
+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.

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.8",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.8/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"
   }
 }
 ```
@@ -138,6 +138,166 @@ await html.register();
 await html.observe({ registerExisting: false });
 ```
 
+
+## Render runtime UI
+
+`solid-tag-runtime/html` can now mount component exports as an HTML-adapter concern while the core runtime remains DOM-independent.
+
+There are two complementary forms:
+
+```text
+<script module>
+  define a runtime module
+
+<script module render>
+  define a module + mount one instance
+
+<solid-render module>
+  reference an existing module + mount one instance
+```
+
+### Define and render in one declaration
+
+Render the default export into a normal Solid container:
+
+```html
+<div id="app"></div>
+
+<script
+  type="solid-jsx"
+  data-solid-runtime="main"
+  module="/App.jsx"
+  render="#app"
+>
+  export default function App() {
+    return <h1>Hello from runtime JSX</h1>;
+  }
+</script>
+```
+
+`render` defaults to `module.default`. Select a named export with `component`:
+
+```html
+<script
+  type="solid-jsx"
+  module="/widgets.jsx"
+  render="#app"
+  component="Counter"
+>
+  export function Counter() {
+    return <button>Counter</button>;
+  }
+</script>
+```
+
+Bare `render` mounts at the declaration's exact sibling position without adding a wrapper:
+
+```html
+<p>Before</p>
+
+<script type="solid-jsx" module="/Message.jsx" render>
+  export default function Message() {
+    return <strong>Hello</strong>;
+  }
+</script>
+
+<p>After</p>
+```
+
+The adapter replaces the declaration with an owned start/end marker range and inserts the component between the markers. The module definition and mount lifecycle remain separate: removing the declaration through `html.removeElement()` disposes the Solid owner while module removal follows the existing lifecycle options.
+
+`entry` and `render` are intentionally mutually exclusive on one declaration. Use separate declarations when a side-effect entry and a mounted component are both needed.
+
+All matching modules in one scan/observer batch are defined before any `entry` or `render` action executes, so a render declaration may import a dependency declared later in the same batch.
+
+### Reuse an existing module with `<solid-render>`
+
+`<solid-render>` references an already-defined module and remains as the light-DOM mount container:
+
+```html
+<solid-render
+  data-solid-runtime="main"
+  module="/Counter.jsx"
+></solid-render>
+```
+
+Named export:
+
+```html
+<solid-render
+  data-solid-runtime="main"
+  module="/widgets.jsx"
+  component="Counter"
+></solid-render>
+```
+
+Component props use an explicit namespace so renderer configuration can never collide with component prop names:
+
+```html
+<solid-render
+  module="/UserCard.jsx"
+  prop:name="Alice"
+  prop:module="billing"
+  prop:compact
+></solid-render>
+```
+
+Declarative values are conservative:
+
+```text
+prop:name="Alice"  → "Alice"
+prop:compact       → true
+prop:count="42"    → "42"
+```
+
+Kebab-case prop names normalize to camelCase (`prop:user-id` → `userId`). Arbitrary JavaScript references use the `.props` property:
+
+```ts
+const renderer = document.querySelector("solid-render");
+
+renderer.props = {
+  user,
+  onSave,
+  service,
+};
+```
+
+Programmatic props override `prop:*` attributes. Prop changes update the existing component instance reactively and preserve local Solid state. Changes to `module`, `component`, or `data-solid-runtime` dispose the current component and mount a new identity.
+
+Initial light-DOM children become `props.children`:
+
+```html
+<solid-render module="/Card.jsx" prop:title="Profile">
+  <p>Hello from HTML.</p>
+  <solid-render module="/SaveButton.jsx"></solid-render>
+</solid-render>
+```
+
+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.
+
+For custom registries, tests, or explicit registration, the helper remains available:
+
+```ts
+import { registerSolidRenderElement } from "solid-tag-runtime/html";
+
+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
@@ -146,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
@@ -689,12 +861,20 @@ append-target-changed
 entry-executing
 entry-executed
 
+render-mounting
+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.
 
-`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()`.
+`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.
 
@@ -762,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({
@@ -770,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