solid-tag-runtime 0.0.7 → 0.0.9

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
 
@@ -101,6 +103,7 @@ const runtime = createRuntime(options);
 
 ```ts
 runtime.define(id, source, options?);
+runtime.defineMany(definitions);
 runtime.update(id, source, options?);
 ```
 
@@ -138,9 +141,18 @@ runtime.getModuleInfo(id);
 
 ```ts
 runtime.invalidate(id);
+runtime.remove(id, options?);
+runtime.clear(options?);
+
+runtime.subscribe(listener);
+runtime.subscribe(type, listener);
+runtime.subscribe(types, listener);
+
 runtime.dispose();
 ```
 
+Lifecycle subscriptions are synchronous observational notifications. They do not intercept or modify runtime behavior. Resolution behavior remains customizable through `resolve()`, compilation through the compiler adapter, and executable-module creation through `ModuleUrlBackend`.
+
 ## 6. Module kinds
 
 The runtime currently has three module record kinds.
@@ -232,6 +244,10 @@ await html.observe({ registerExisting: false });
 The controller exposes:
 
 ```ts
+html.subscribe(listener);
+html.subscribe(type, listener);
+html.subscribe(types, listener);
+
 html.register(options?);
 html.observe(options?);
 html.flush(options?);
@@ -1031,3 +1047,152 @@ Invariants:
 8. `removeElement()` is the canonical operation for releasing shared WeakMap ownership.
 
 Regression coverage: package tests cover batch definition and duplicate rejection, dependency removal/invalidation, clear-with-host-preservation, lifecycle event delivery/unsubscribe, owned element updates, identity-change rejection, ownership release, DOM removal, and preserving a runtime module while releasing its HTML element.
+
+### 0.0.8 — selective lifecycle subscriptions and HTML observability
+
+Decision: expand lifecycle observation into typed, independently removable subscriptions on both the core runtime and the HTML adapter. Keep lifecycle subscriptions observational and separate from behavioral hooks/interceptors.
+
+Core subscription forms:
+
+```ts
+runtime.subscribe(listener);
+runtime.subscribe("module-error", listener);
+runtime.subscribe(["module-evaluating", "module-evaluated"], listener);
+```
+
+HTML controllers expose the same shape:
+
+```ts
+html.subscribe(listener);
+html.subscribe("element-registered", listener);
+html.subscribe(["observer-batch", "html-error"], listener);
+```
+
+Each call creates an independent subscription and returns its own disposer. Disposing one subscription never affects another registration of the same callback or subscriptions to other event groups. Subscriber exceptions are reported but cannot alter runtime/HTML operations.
+
+Core event additions:
+
+```text
+module-updated
+modules-defined
+module-resolving
+module-resolved
+module-linking
+module-linked
+```
+
+The evaluation pipeline is now observed in semantic order:
+
+```text
+module-linking
+  ↓
+module-resolving / module-resolved
+  ↓
+module-linked
+  ↓
+module-compiled
+  ↓
+module-evaluating
+  ↓
+module-evaluated
+```
+
+`module-resolved` exposes the logical resolution result and resolution kind, while `module-linked` exposes source specifier → resolved module-ID dependencies without exposing Blob/data URL implementation details. `modules-defined` marks the completion of a `defineMany()` batch after buffered per-module events become observable. `module-updated` supplements the backward-compatible `module-defined { operation: "update" }` event with an explicit semantic update notification.
+
+`module-error` remains one event with a structured pipeline phase instead of creating separate error event types. Supported phases are `resolve`, `analyze`, `compile`, `link`, `url-create`, `evaluate`, and `host-bridge`.
+
+HTML controller event additions:
+
+```text
+element-discovered
+element-claimed
+element-loading
+element-loaded
+element-registered
+element-updating
+element-updated
+element-removing
+element-released
+element-removed
+observer-connected
+observer-disconnected
+observer-batch
+root-changing
+root-changed
+append-target-changed
+entry-executing
+entry-executed
+html-error
+```
+
+HTML ownership events include an origin describing the ingestion path (`initial-scan`, `observer`, `register-element`, `append`, `add-module`, etc.). The observer emits summarized `observer-batch` events instead of exposing raw `MutationRecord` values. Root/append-target events belong only to the HTML controller and are deliberately not mixed into core runtime events.
+
+Architectural boundary:
+
+```text
+Observation
+  runtime.subscribe()
+  html.subscribe()
+
+Behavior customization
+  resolve()
+  compiler adapter
+  ModuleUrlBackend
+```
+
+Lifecycle listeners are not interceptors: they cannot cancel evaluation, rewrite source, change resolution, or alter cache behavior. If source/evaluation interception is needed later, it must be designed as a separate hook contract with explicit ordering, async, cancellation, and caching semantics.
+
+Implementation note: core and HTML event streams share a small internal dispatcher so all/selective subscription behavior, independent disposers, and listener-error isolation have identical semantics while keeping separate event unions.
+
+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 the HTML runtime through the shared controller registry. With no attribute, a single unambiguous controller may be used.
+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.

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.7",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.7/html"
+    "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"
   }
 }
 ```
@@ -138,6 +138,155 @@ 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.
+
 A scope is written to owned script elements as:
 
 ```html
@@ -572,28 +721,136 @@ removes everything. The returned array contains the IDs that were removed.
 
 ### Lifecycle events
 
+`0.0.8` expands lifecycle subscriptions into a typed event stream with independent join/leave semantics.
+
+Subscribe to everything:
+
 ```ts
 const unsubscribe = runtime.subscribe(event => {
   console.log(event.type, event);
 });
+```
+
+Subscribe to one event type:
+
+```ts
+const leaveErrors = runtime.subscribe(
+  "module-error",
+  event => {
+    console.error(event.phase, event.error);
+  },
+);
+```
+
+Subscribe to several event types:
+
+```ts
+const leaveEvaluation = runtime.subscribe(
+  ["module-evaluating", "module-evaluated"],
+  event => {
+    console.log(event.type, event.id);
+  },
+);
+```
+
+Each call owns an independent subscription:
+
+```ts
+leaveEvaluation();
+// the error subscription remains active
+```
+
+Core events include:
+
+```text
+module-defined
+module-updated
+modules-defined
+
+module-resolving
+module-resolved
+
+module-linking
+module-linked
+
+module-invalidated
+module-compiled
+module-evaluating
+module-evaluated
+
+module-removed
+module-error
+
+runtime-cleared
+runtime-disposed
+```
+
+`module-resolved` reports how a specifier was resolved (`relative`, `registered`, `custom`, `native`, and so on). `module-linked` exposes the logical dependency mapping used to link a source module. `modules-defined` marks the completion of a `defineMany()` batch after all definitions have been installed.
+
+`module-error.phase` is one of the runtime pipeline phases such as `resolve`, `analyze`, `compile`, `link`, `url-create`, `evaluate`, or `host-bridge`.
+
+Subscribers are observational only: they cannot cancel or modify runtime operations, and subscriber exceptions are isolated from runtime execution. Behavioral extension remains separate through the resolver, compiler adapter, and module URL backend.
+
+### HTML lifecycle events
+
+The HTML controller has its own event stream because DOM ownership/observation is intentionally separate from the core module engine:
+
+```ts
+const leaveHTML = html.subscribe(event => {
+  console.log(event.type, event);
+});
+```
+
+The same selective forms are supported:
+
+```ts
+const leaveOwnership = html.subscribe(
+  ["element-claimed", "element-registered", "element-removed"],
+  event => {
+    console.log(event.type, event.moduleId);
+  },
+);
+```
+
+HTML events include:
+
+```text
+element-discovered
+element-claimed
+element-loading
+element-loaded
+element-registered
+
+element-updating
+element-updated
+element-removing
+element-released
+element-removed
+
+observer-connected
+observer-disconnected
+observer-batch
+
+root-changing
+root-changed
+append-target-changed
+
+entry-executing
+entry-executed
+
+render-mounting
+render-mounted
+render-disposing
+render-disposed
 
-// later
-unsubscribe();
+html-error
 ```
 
-Events currently include:
+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.
 
-- `module-defined`
-- `module-invalidated`
-- `module-compiled`
-- `module-evaluating`
-- `module-evaluated`
-- `module-removed`
-- `module-error`
-- `runtime-cleared`
-- `runtime-disposed`
+`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.
 
-Subscriber exceptions are isolated from runtime execution. This makes `subscribe()` suitable for tracing, developer tools, and editor diagnostics.
+Like core runtime subscribers, HTML subscribers are observational and exception-isolated.
 
 ## HTML-owned module updates and removal