solid-tag-runtime 0.0.12 → 0.0.13

package/README.md

@@ -1,45 +1,34 @@
 # solid-tag-runtime
 
-`solid-tag-runtime` is a small runtime module system for applications that want to load, compose, and execute Solid JSX modules dynamically in the browser.
-
-It builds on [`solid-tag`](https://www.npmjs.com/package/solid-tag):
+`solid-tag-runtime` is a runtime module system for dynamically defined Solid JSX and JavaScript modules.
 
 ```text
-JSX source modules
-      ↓
-solid-tag
-      ↓
-JavaScript containing html``
-      ↓
-solid-tag-runtime module linker
-      ↓
-@solidjs/html + the host application's Solid runtime
+source module
+    ↓
+solid-tag compiler
+    ↓
+pre-link compiled artifact
+    ↓
+solid-tag-runtime linker
+    ↓
+@solidjs/html + host Solid runtime
 ```
 
-The package is intentionally runtime-oriented. It is not a build plugin and does not require a traditional application compilation workflow for the dynamic modules it executes.
+The core package is module-first and DOM-independent. Browser discovery, ownership, declarative rendering, and `<solid-render>` live in the `solid-tag-runtime/html` adapter.
 
-## Installation
+## Install
 
 ```bash
 npm install solid-tag-runtime solid-tag
 ```
 
-`solid-tag-runtime` does **not** install its own copy of Solid. A host application can expose its already-loaded Solid modules with `defineModule()` so dynamically loaded components share the same reactive runtime.
-
-## Create a runtime
-
-```ts
-import { createRuntime } from "solid-tag-runtime";
-
-const runtime = createRuntime();
-```
-
-For a real Solid application, register the host runtime:
+## Quick start
 
 ```ts
 import * as Solid from "solid-js";
 import * as SolidWeb from "@solidjs/web";
 import html from "@solidjs/html";
+import { createRuntime } from "solid-tag-runtime";
 
 const runtime = createRuntime({
   modules: {
@@ -48,121 +37,31 @@ const runtime = createRuntime({
     "@solidjs/html": { default: html },
   },
 });
-```
-
-This is important: dynamic modules now use the **same** `solid-js`, `@solidjs/web`, and `@solidjs/html` instances as the host application.
-
-## Define and import runtime modules
-
-```ts
-runtime.define(
-  "/ui/Button.jsx",
-  `
-    export function Button(props) {
-      return (
-        <button onClick={props.onClick}>
-          {props.children}
-        </button>
-      );
-    }
-  `,
-);
-```
-
-A second module can import the first one normally:
-
-```ts
-runtime.define(
-  "/features/Counter.jsx",
-  `
-    import { createSignal } from "solid-js";
-    import { Button } from "../ui/Button.jsx";
-
-    export function Counter() {
-      const [count, setCount] = createSignal(0);
-
-      return (
-        <Button onClick={() => setCount(value => value + 1)}>
-          Count: {count()}
-        </Button>
-      );
-    }
-  `,
-);
-
-const counterModule = await runtime.import("/features/Counter.jsx");
-
-counterModule.Counter;
-```
-
-The runtime compiles and links the dependency graph automatically.
 
-
-## Declarative HTML modules
-
-`solid-tag-runtime/html` is the browser/DOM adapter. The core runtime remains DOM-independent.
-
-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.12",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.12/html"
+runtime.define("/Greeting.jsx", `
+  export default function Greeting() {
+    return <p>Hello from runtime JSX</p>;
   }
-}
-```
-
-For simple single-runtime use, the original helpers remain available:
-
-```ts
-import {
-  registerHTML,
-  observeHTML,
-} from "solid-tag-runtime/html";
+`);
 
-await registerHTML(runtime);
+const module = await runtime.import("/Greeting.jsx");
+module.default;
 ```
 
-For applications that may have multiple runtimes or that create runtime scripts programmatically, `0.0.3` added a persistent HTML runtime controller:
+## Declarative browser modules
 
 ```ts
 import { createHTMLRuntime } from "solid-tag-runtime/html";
 
-const html = createHTMLRuntime(runtime, {
+const htmlRuntime = createHTMLRuntime(runtime, {
   scope: "main",
   root: document,
 });
 
-await html.register();
-await html.observe({ registerExisting: false });
+await htmlRuntime.register();
 ```
 
-
-## 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"
@@ -170,824 +69,102 @@ Render the default export into a normal Solid container:
   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>;
+    return <h1>Hello</h1>;
   }
 </script>
 ```
 
-Bare `render` mounts at the declaration's exact sibling position without adding a wrapper:
+Bare `render` mounts in place 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.
-
-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:
-
-```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 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
-<script data-solid-runtime="main" ...></script>
 ```
 
-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
+## Reusable `<solid-render>` instances
 
 ```html
-<script
-  type="solid-jsx"
-  data-solid-runtime="main"
-  module="/ui/Button.jsx">
-  export function Button(props) {
-    return (
-      <button onClick={props.onClick}>
-        {props.children}
-      </button>
-    );
+<script type="solid-jsx" module="/Counter.jsx">
+  export default function Counter() {
+    return <button>Counter</button>;
   }
 </script>
-```
-
-Runtime modules import one another normally:
-
-```tsx
-import { Button } from "./ui/Button.jsx";
-```
-
-All newly discovered scripts in one batch are defined before any newly discovered `entry` module executes, so HTML document order does not require dependencies to appear first.
 
-### External source
-
-```html
-<script
-  type="solid-jsx"
-  data-solid-runtime="main"
-  module="/ui/Button.jsx"
-  src="./components/Button.jsx">
-</script>
+<solid-render module="/Counter.jsx"></solid-render>
+<solid-render module="/Counter.jsx"></solid-render>
 ```
 
-`src` answers **where source is loaded from**. `module` answers **what identity the source has in the runtime graph**.
-
-### User-created script elements
-
-If application code creates a script itself, use the controller to associate it with the correct runtime:
-
-```ts
-const script = document.createElement("script");
-script.type = "solid-jsx";
-script.setAttribute("module", "/dynamic/Greeting.jsx");
-script.textContent = `
-  export function Greeting(props) {
-    return <p>Hello {props.name}</p>;
-  }
-`;
-
-await html.append(script);
-```
-
-`append()` claims the element **before** inserting it in the DOM, stamps the controller scope, then registers it directly. If a `MutationObserver` is active, the later mutation callback sees that the element is already owned and does not compile it twice.
-
-For an element that is already in the DOM:
-
-```ts
-await html.registerElement(script);
-```
+**In HTML, always use the explicit closing tag.** Do not write `<solid-render ... />`; custom elements are not HTML void elements and the self-closing slash is ignored by the HTML parser.
 
-Same-controller repeated registration is idempotent. Trying to register an element already owned by another HTML controller throws `HTMLModuleOwnershipError`.
+## Persistent compile cache
 
-### Let the controller create the script
+`0.0.13` adds an opt-in persistent cache for **pre-link compiler artifacts**. Runtime-specific linked URLs and evaluated module namespaces are never persisted.
 
 ```ts
-await html.addModule({
-  id: "/dynamic/Badge.jsx",
-  source: `
-    export function Badge(props) {
-      return <span>{props.children}</span>;
-    }
-  `,
-});
-```
-
-`addModule()` creates the `<script>` element, associates it with the controller, appends it, and registers it.
-
-### Observe scripts added by other code
+import {
+  createRuntime,
+  createIndexedDBCompileCache,
+} from "solid-tag-runtime";
 
-```ts
-await html.observe({
-  registerExisting: false,
-  onError(error) {
-    console.error(error);
+const runtime = createRuntime({
+  compileCache: {
+    store: createIndexedDBCompileCache({
+      database: "my-app-runtime",
+    }),
+    namespace: "main",
+    version: "1",
   },
 });
-
-// Some unrelated code mutates the DOM directly.
-const script = document.createElement("script");
-script.type = "solid-jsx";
-script.setAttribute("data-solid-runtime", "main");
-script.setAttribute("module", "/observed/Thing.jsx");
-script.textContent = `export const value = 42;`;
-document.body.append(script);
-
-await html.flush();
-const module = await runtime.import("/observed/Thing.jsx");
-```
-
-The observer is for DOM changes that happen **outside** the controller API. Prefer `html.append()` / `html.addModule()` when your code controls insertion because those operations are deterministic and do not depend on observer timing.
-
-### Ownership and deduplication
-
-All HTML controllers share an internal `WeakMap` of script element → ownership/registration record.
-
-That controller model gives these guarantees:
-
-- one script element has at most one HTML-runtime owner;
-- manual registration and observer registration cannot compile the same element twice;
-- the same controller can register the same element repeatedly without redefining it;
-- two distinct elements cannot silently define the same HTML-owned module ID;
-- an HTML script cannot silently replace a module already defined outside that HTML controller;
-- `data-solid-runtime` is declarative metadata while the in-memory owner record is authoritative.
-
-The controller also exposes lightweight introspection:
-
-```ts
-html.owns(script);
-html.getModuleId(script);
-html.getElement("/dynamic/Greeting.jsx");
 ```
 
-### Script formats
-
-```text
-solid-jsx / text/solid-jsx  → JSX transformation
-solid-js  / text/solid-js   → plain JavaScript module
-solid-module                → infer from module/src extension
-```
-
-`language="js"` or `language="jsx"` may override inference.
-
-
-### Change the observed root
-
-The HTML controller can move to a different discovery root without creating a new runtime:
+The cache key is content-based and includes the source hash, compiler fingerprint, artifact ABI, format, and compile-affecting context. Dependency versions and resolver state are deliberately excluded, so unchanged importers can reuse compiler work and relink against changed dependencies.
 
 ```ts
-const first = document.querySelector("#first-runtime")!;
-const second = document.querySelector("#second-runtime")!;
+await runtime.compile("/App.jsx", { cache: "use" });
+await runtime.compile("/App.jsx", { cache: "refresh" });
+await runtime.compile("/App.jsx", { cache: "bypass" });
 
-const html = createHTMLRuntime(runtime, {
-  root: first,
-  appendTo: first,
-});
-
-await html.observe({ registerExisting: false });
-
-// Rebind a live observer to a different node. Because the observer is already
-// connected, matching scripts already in the new root are registered by default.
-await html.setRoot(second);
-```
-
-If the controller is disconnected, `setRoot()` only changes configuration unless `registerExisting: true` is passed:
-
-```ts
-await html.setRoot(second, {
-  registerExisting: true,
-});
-```
-
-Use `registerExisting: false` when switching a live observer but intentionally ignoring scripts already present in the new root.
-
-Moving the **same root node** elsewhere in the DOM does not require `setRoot()`. `MutationObserver` remains attached to that node object even when it is reparented.
-
-### Move root and append target together
-
-When the runtime module area itself moves to another container, `moveTo()` changes both boundaries:
-
-```ts
-await html.moveTo(nextContainer, {
-  registerExisting: true,
-});
-```
-
-For an `Element`, `DocumentFragment`, or `ShadowRoot`, future `append()` / `addModule()` calls insert into that root. For a `Document`, the controller chooses the document body (or document element fallback) as the append target.
-
-### Change only the append target
-
-Observation and insertion can have different boundaries:
-
-```ts
-html.setAppendTarget(document.head);
-```
-
-This does not change the currently observed root. The controller exposes the active values for diagnostics:
-
-```ts
-html.root;
-html.appendTarget;
+await runtime.compileCache.invalidate("/App.jsx");
+await runtime.compileCache.clear();
 ```
 
-The `root` may be a `Document`, normal `Element`, `DocumentFragment`, or `ShadowRoot` (which is a `DocumentFragment`). A controller observes the selected root directly rather than observing the whole document and filtering mutations afterward.
+## Documentation
 
-### Addition-only observation
+The detailed documentation now lives under [`docs/`](./docs/README.md):
 
-Observation remains addition-oriented.
+- [Getting started](./docs/getting-started.md)
+- [Runtime modules and resolution](./docs/modules.md)
+- [HTML runtime and ownership](./docs/html-runtime.md)
+- [Declarative rendering](./docs/rendering.md)
+- [`<solid-render>`](./docs/solid-render.md)
+- [Lifecycle events](./docs/lifecycle-events.md)
+- [Persistent compile cache](./docs/compile-cache.md)
+- [Core runtime API](./docs/api/runtime.md)
+- [HTML runtime API](./docs/api/html.md)
+- [Compile-cache API](./docs/api/compile-cache.md)
 
-Changing the source/attributes of an already owned script or removing it from the DOM does not implicitly update/delete the corresponding runtime module. In `0.0.7`, use `html.updateElement()` and `html.removeElement()` when the lifecycle should follow an owned script explicitly, or use the core `runtime.update()` / `runtime.remove()` APIs directly.
+For engineering invariants and design decisions, see [`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
-The HTML adapter does **not** reinterpret arbitrary document HTML as JSX and does not currently assign component semantics to `<template>`.
+## Browser import maps
 
-## `toModule()`
+When loading from an import map, map both entries to the same version:
 
-For one-off source strings:
-
-```ts
-const module = await runtime.toModule(`
-  export function MyComponent(props) {
-    return <>{props.message} {props.name}</>;
-  }
-`);
-
-const MyComponent = module.MyComponent;
-```
-
-`toModule()` creates an anonymous runtime module, compiles it with `solid-tag`, evaluates it as a real ES module, and returns the module namespace.
-
-It is asynchronous because the runtime preserves ES-module-style evaluation rather than using `new Function()`.
-
-## `toComponent()`
-
-For the common single-component case:
-
-```ts
-const MyComponent = await runtime.toComponent(
-  `
-    export function MyComponent(props) {
-      return <div>{props.message}</div>;
-    }
-  `,
-  { exportName: "MyComponent" },
-);
-```
-
-For a default export:
-
-```ts
-const Counter = await runtime.toComponent(`
-  export default function Counter() {
-    return <button>Count</button>;
+```json
+{
+  "imports": {
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.13",
+    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.13/html"
   }
-`);
-```
-
-## Inject application values as modules
-
-The runtime deliberately does not rewrite unresolved identifiers into a magical scope object.
-
-Instead, application scope can be expressed as a normal module:
-
-```ts
-const [count, setCount] = createSignal(0);
-
-runtime.defineModule("@app/state", {
-  count,
-  setCount,
-});
-```
-
-Runtime source imports those references normally:
-
-```tsx
-import { count, setCount } from "@app/state";
-
-export function Counter() {
-  return (
-    <button onClick={() => setCount(value => value + 1)}>
-      {count()}
-    </button>
-  );
 }
 ```
 
-This works for:
-
-- Solid signals and setters
-- stores
-- components
-- callbacks
-- services
-- data objects
-- application utilities
-
-The values cross the boundary as actual JavaScript references; they are not serialized.
-
-## Expose existing components
-
-```ts
-runtime.defineModule("@app/components", {
-  Button,
-  Dialog,
-  Card,
-});
-```
-
-Then runtime JSX can use them like any other module:
-
-```tsx
-import { Button } from "@app/components";
-
-export function SaveButton() {
-  return <Button>Save</Button>;
-}
-```
-
-## URL modules
-
-A package or external library can be mapped to a native ESM URL:
-
-```ts
-runtime.defineUrl(
-  "some-library",
-  "https://esm.sh/some-library@1.2.3",
-);
-```
-
-Then dynamic modules can write:
-
-```js
-import something from "some-library";
-```
-
-## Plain JavaScript modules
-
-JSX transformation can be disabled per module:
-
-```ts
-runtime.define(
-  "/config.js",
-  `export const value = 42;`,
-  { format: "js" },
-);
-```
-
-This is useful when the same runtime graph contains both JSX-backed modules and ordinary JavaScript modules.
-
-## Compilation without execution
-
-```ts
-runtime.define("/App.jsx", source);
-
-const compiled = await runtime.compile("/App.jsx");
-
-console.log(compiled.code);
-console.log(compiled.dependencies);
-console.log(compiled.diagnostics);
-```
-
-This is useful for editors, debugging tools, and inspecting the exact `html\`\`` output generated by `solid-tag`.
-
-## Module graph introspection
-
-```ts
-runtime.modules();
-runtime.dependencies("/App.jsx");
-runtime.dependents("/ui/Button.jsx");
-runtime.getModuleInfo("/App.jsx");
-```
-
-## Updating modules
-
-```ts
-runtime.update("/ui/Button.jsx", newButtonSource);
-
-const app = await runtime.import("/App.jsx");
-```
-
-Updating a module invalidates its compiled URL and its dependent runtime modules. Re-importing produces a newly linked graph.
-
-Existing references to an older module namespace/component are not mutated. Applications that implement live editing should import the updated entry module again.
-
-### Define several source modules together
-
-```ts
-runtime.defineMany([
-  {
-    id: "/ui/Button.jsx",
-    source: buttonSource,
-  },
-  {
-    id: "/App.jsx",
-    source: appSource,
-  },
-]);
-```
-
-`defineMany()` validates the whole definition list before applying it and rejects duplicate module IDs inside the batch. It is useful when a group of modules should become available before anything is imported. Lifecycle notifications from the batch are published only after every definition has been installed.
-
-### Remove modules
-
-```ts
-runtime.remove("/ui/Button.jsx");
-```
-
-Removal invalidates transitive dependents by default. A later import of a dependent will fail resolution until the missing module is defined again.
-
-If you intentionally want to leave currently linked dependents untouched:
-
-```ts
-runtime.remove("/ui/Button.jsx", {
-  invalidateDependents: false,
-});
-```
-
-### Clear a runtime
-
-```ts
-runtime.clear();
-```
-
-By default `clear()` removes source and URL modules while preserving host modules registered with `defineModule()`. This is convenient for editor/preview resets where the host environment should remain installed.
-
-```ts
-runtime.clear({
-  preserveHostModules: false,
-});
-```
-
-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
-
-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.
-
-## HTML-owned module updates and removal
-
-When a script element is already owned by an HTML runtime controller, update the runtime module from the current element contents with:
-
-```ts
-script.textContent = `
-  export function Card() {
-    return <div>updated</div>;
-  }
-`;
-
-await html.updateElement(script);
-```
-
-`updateElement()` keeps the existing logical module ID and calls `runtime.update()` underneath. Changing the element's logical `module` identity is intentionally rejected; remove and register it again instead.
-
-Release an owned element explicitly with:
-
-```ts
-await html.removeElement(script);
-```
-
-By default this:
-
-1. removes the runtime module,
-2. invalidates its dependents,
-3. releases HTML ownership, and
-4. removes the script element from the DOM.
-
-The two lifecycles can be controlled independently:
-
-```ts
-await html.removeElement(script, {
-  removeModule: false,
-  removeFromDOM: true,
-});
-```
-
-This is intentionally explicit: ordinary DOM removal does not silently delete a runtime module.
-
-## Custom resolution
-
-```ts
-const runtime = createRuntime({
-  resolve(specifier, importer) {
-    if (specifier.startsWith("@ui/")) {
-      return `/ui/${specifier.slice(4)}`;
-    }
-  },
-});
-```
-
-Default runtime resolution supports:
-
-- exact virtual module IDs
-- relative virtual imports
-- absolute virtual paths
-- registered URL modules
-- native/bare imports when `allowNativeImports` is enabled
-
-## Native imports
-
-`allowNativeImports` defaults to `true`.
-
-This means an unresolved **bare** import can be left for the browser's native module resolver/import map:
-
-```ts
-const runtime = createRuntime({
-  allowNativeImports: true,
-});
-```
-
-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
-
-```ts
-runtime.invalidate("/App.jsx");
-runtime.remove("/Unused.jsx");
-runtime.clear();
-runtime.dispose();
-```
-
-`invalidate()` forces fresh compilation/evaluation without deleting the module definition. `remove()` deletes one definition, `clear()` resets a group of definitions, and `dispose()` permanently tears down the runtime instance.
-
 ## Current limitations
 
-The first version deliberately keeps module semantics constrained:
-
-- circular dependencies between runtime-defined source modules are not supported yet
-- generated modules normally use Blob URLs in browsers, so CSP must permit the chosen execution strategy
-- host-module export bridges expose the export values present when the bridge module is created; redefining the host module invalidates dependents
-- module updates create new module identities; already-held namespaces/components remain the old version
-- TypeScript/TSX parsing depends on what the underlying `solid-tag` compiler supports
-- this package is **not a security sandbox**; loaded source executes with the privileges of the page
-
-See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the detailed design and decision log.
+- runtime-defined source-module cycles are not supported yet
+- generated browser modules require a compatible CSP for the selected module URL backend
+- persistent compile caching is an optimization, not a security sandbox
+- already-held namespace/component references are not mutated by module updates
+- TypeScript/TSX support depends on the configured compiler