solid-tag-runtime 0.0.1 → 0.0.3

package/ARCHITECTURE.md

@@ -42,7 +42,7 @@ The runtime should allow applications to:
 9. support normal JavaScript modules in the same graph
 10. keep the JSX compiler replaceable behind a narrow adapter
 
-## 3. Non-goals for the first version
+## 3. Current non-goals
 
 The initial package does not attempt to provide:
 
@@ -54,9 +54,8 @@ The initial package does not attempt to provide:
 - circular runtime source-module support
 - transparent live replacement of already-held component references
 - full HMR propagation semantics
-- script-tag discovery/registration
 
-These may be added later without changing the module-first public model.
+These may be added later without changing the module-first public model. HTML script discovery was added in `0.0.2` as a separate browser adapter rather than as a responsibility of the core module engine.
 
 ## 4. Package relationship
 
@@ -193,7 +192,270 @@ No JSX transformation. Imports are still resolved and rewritten through the runt
 
 This permits ordinary JavaScript and JSX modules to coexist in one graph.
 
-## 8. Compiler adapter boundary
+
+## 8. HTML/browser adapter
+
+`solid-tag-runtime/html` is an opt-in browser-facing adapter over the core module runtime.
+
+`0.0.3` makes the adapter runtime-aware rather than treating document scripts as a single global pool.
+
+Important architectural boundary:
+
+```text
+DOM / HTML document
+      ↓
+HTML runtime controller
+      ↓
+runtime.define(...)
+      ↓
+core module graph
+```
+
+The core runtime remains DOM-independent. It does not scan documents, own HTML elements, run `MutationObserver`, or know about HTML attributes.
+
+### Public HTML API
+
+The preferred API for non-trivial usage is a persistent controller:
+
+```ts
+const html = createHTMLRuntime(runtime, {
+  scope: "preview",
+  root: document,
+});
+
+await html.register();
+await html.observe({ registerExisting: false });
+```
+
+The controller exposes:
+
+```ts
+html.register(options?);
+html.observe(options?);
+html.flush(options?);
+html.disconnect();
+
+html.defineElement(element, options?);
+html.registerElement(element, options?);
+html.append(element, options?);
+html.addModule(options);
+
+html.owns(element);
+html.getModuleId(element);
+html.getElement(moduleId);
+```
+
+The original convenience functions remain supported and are implemented on top of a cached default controller for each runtime:
+
+```ts
+await registerHTML(runtime, options?);
+await defineScript(runtime, element, options?);
+const observer = await observeHTML(runtime, options?);
+```
+
+This keeps the simple single-runtime API while giving multi-runtime applications an explicit ownership object.
+
+### Element ownership model
+
+A module-level `WeakMap` is the authoritative in-memory ownership registry for runtime script elements.
+
+Conceptually:
+
+```ts
+WeakMap<HTMLScriptElement, ElementRecord>
+```
+
+An element record stores at least:
+
+```text
+owner controller
+module ID
+format
+entry flag
+source URL
+registration state
+pending registration promise
+result/error
+```
+
+This registry is shared by all HTML runtime controllers created by this package instance.
+
+Important invariants:
+
+1. A runtime script element has at most one HTML-runtime owner.
+2. Ownership is claimed synchronously before asynchronous fetch/compile work.
+3. `append()` claims ownership before inserting the node into the DOM.
+4. Observer discovery, scans, explicit registration, and append/add helpers all use the same ownership record.
+5. Re-registering an element through the same controller is idempotent and waits on the same pending registration work.
+6. A different controller attempting to claim an owned element receives `HTMLModuleOwnershipError`.
+7. The observer must never redefine a module already being handled through `append()` or `registerElement()`.
+8. Distinct HTML elements cannot silently claim the same module ID in one HTML controller.
+9. Existing non-HTML runtime modules are not silently replaced by HTML registration.
+10. DOM removal does not implicitly delete a runtime module.
+
+A `WeakSet` alone is insufficient because the adapter needs to distinguish ownership, pending work, success, and failure. The shared `WeakMap` also avoids retaining detached elements after all external references disappear.
+
+### Controller scope and multiple runtimes
+
+A controller may declare a scope:
+
+```ts
+const previewHTML = createHTMLRuntime(previewRuntime, {
+  scope: "preview",
+});
+```
+
+Owned elements are marked declaratively:
+
+```html
+<script
+  type="solid-jsx"
+  data-solid-runtime="preview"
+  module="/App.jsx">
+</script>
+```
+
+`data-solid-runtime` is useful for declarative selection and DevTools visibility. It is not the authoritative ownership record; the `WeakMap` points to the actual controller object and prevents two controllers with the same string scope from owning the same element.
+
+A scoped controller accepts matching scripts. It may also claim unscoped scripts when `acceptUnscoped` is enabled (default `true`). Setting `acceptUnscoped: false` is recommended when multiple scoped runtimes observe the same DOM root.
+
+An unscoped controller does not silently claim a script carrying `data-solid-runtime` for another runtime.
+
+### User-created script elements
+
+Applications may create the element themselves and explicitly associate it with one runtime:
+
+```ts
+const script = document.createElement("script");
+script.type = "solid-jsx";
+script.setAttribute("module", "/Preview.jsx");
+script.textContent = source;
+
+await previewHTML.append(script);
+```
+
+`append()` performs this ordering:
+
+```text
+claim element
+    ↓
+stamp data-solid-runtime (when scoped)
+    ↓
+append to DOM
+    ↓
+load/define module directly
+    ↓
+observer later sees mutation and skips duplicate work
+```
+
+This is deliberately not implemented as “append and wait for MutationObserver”. Explicit APIs are deterministic even when observation is disabled.
+
+For an element already in the DOM:
+
+```ts
+await previewHTML.registerElement(script);
+```
+
+### Controller-created script elements
+
+`addModule()` creates and owns the script element for the caller:
+
+```ts
+await previewHTML.addModule({
+  id: "/dynamic/Greeting.jsx",
+  source: `
+    export function Greeting(props) {
+      return <p>Hello {props.name}</p>;
+    }
+  `,
+});
+```
+
+It uses the same claim-before-append pipeline as `append()`.
+
+### One-shot registration and live observation
+
+`register()` / `registerHTML()` perform one-shot discovery.
+
+`observe()` / `observeHTML()` use `MutationObserver` for newly added scripts. Existing scripts are registered by default; `registerExisting: false` supports the pattern where a one-shot registration already ran.
+
+Every discovered batch preserves the graph invariant:
+
+```text
+discover complete batch
+      ↓
+claim applicable elements
+      ↓
+load all source
+      ↓
+define all modules
+      ↓
+execute newly discovered entries
+```
+
+An entry may therefore import a dependency that appears later in the same discovery batch.
+
+`flush()` waits for queued observer work and scans again, providing a deterministic synchronization point after external DOM mutations.
+
+Observation in `0.0.3` remains addition-only: changing attributes/text of an already owned script or removing it does not implicitly update/remove the runtime module. Module replacement remains explicit through the core runtime update/invalidation APIs.
+
+### Supported script declarations
+
+```html
+<script type="solid-jsx" module="/App.jsx">...</script>
+<script type="solid-js" module="/utils.js">...</script>
+<script type="solid-module" module="/App.jsx">...</script>
+```
+
+`text/solid-jsx`, `text/solid-js`, and `text/solid-module` aliases are also accepted.
+
+Format rules:
+
+- `solid-jsx` → `jsx`
+- `solid-js` → `js`
+- `solid-module` → infer from `module`/`src` extension
+- `language="js"` or `language="jsx"` overrides inference
+
+### `src` versus `module`
+
+These attributes deliberately have different roles:
+
+```text
+src     = source provider / fetch location
+module  = identity in the runtime module graph
+```
+
+Example:
+
+```html
+<script
+  type="solid-jsx"
+  src="./source/Button.jsx"
+  module="/ui/Button.jsx">
+</script>
+```
+
+The source may move without changing imports of `/ui/Button.jsx`.
+
+If a `src` script omits `module`, its resolved source URL becomes the module ID. Inline non-entry scripts require an explicit `module` identity. Inline entries may omit it and receive an anonymous runtime ID.
+
+### Entry execution
+
+`entry` is an adapter concern, not a new runtime module kind.
+
+```html
+<script type="solid-jsx" module="/App.jsx" entry>...</script>
+```
+
+After all newly discovered modules in the batch are defined, the adapter imports each entry unless `executeEntries: false` is supplied.
+
+### Explicitly not HTML-as-JSX
+
+The adapter does not transform arbitrary document HTML into JSX and does not currently assign semantics to `<template>` elements. JSX remains inside JavaScript module source.
+
+This avoids introducing a second template language, implicit lexical scope rules, or ambiguous ownership of already-parsed DOM.
+
+## 9. Compiler adapter boundary
 
 The runtime engine itself does not depend on Acorn or the `solid-tag` AST.
 
@@ -233,7 +495,7 @@ Possible future adapters include:
 
 The module graph must remain independent of parser details.
 
-## 9. Linking pipeline
+## 10. Linking pipeline
 
 For a source module `/features/Counter.jsx`:
 
@@ -266,7 +528,7 @@ Example graph:
   └── ../ui/Button.jsx     → compiled virtual source URL
 ```
 
-## 10. Resolution rules
+## 11. Resolution rules
 
 Resolution order is conceptually:
 
@@ -282,7 +544,7 @@ Relative virtual resolution uses POSIX-style paths regardless of the host operat
 
 This keeps module IDs stable in browsers and on Windows hosts.
 
-## 11. Native ESM execution backend
+## 12. Native ESM execution backend
 
 The first execution backend deliberately relies on the JavaScript engine's native ESM evaluator rather than `new Function()`.
 
@@ -320,9 +582,9 @@ Benefits:
 - no `eval` / `new Function()` runtime wrapper
 - clean `toModule()` semantics
 
-## 12. Circular dependency limitation
+## 13. Circular dependency limitation
 
-Virtual source module cycles are explicitly rejected in v0.0.1.
+Virtual source module cycles are explicitly rejected through v0.0.2.
 
 Reason: the current linker must know the final URL of dependencies before it can create a module's immutable Blob/data URL. A cycle requires module identities to exist before final source URLs can be constructed.
 
@@ -341,7 +603,7 @@ Future options:
 
 Do not add ad-hoc cycle handling that breaks module semantics; change the backend deliberately.
 
-## 13. Host module bridges
+## 14. Host module bridges
 
 `defineModule()` stores the namespace in a runtime-specific registry:
 
@@ -376,7 +638,7 @@ The ES module bridge captures each exported property value when the bridge modul
 
 To replace exports, call `defineModule()` again. This invalidates dependent runtime modules.
 
-## 14. Scope injection design choice
+## 15. Scope injection design choice
 
 The runtime does not automatically turn unknown identifiers into scope lookups.
 
@@ -413,7 +675,7 @@ Reasons:
 
 A future convenience API may create scope modules automatically, but it should still compile down to module semantics.
 
-## 15. Dependency graph
+## 16. Dependency graph
 
 Each record tracks:
 
@@ -431,7 +693,7 @@ When linking `/App.jsx` imports `/Button.jsx`:
 
 These edges power invalidation and tooling.
 
-## 16. Caching
+## 17. Caching
 
 A source module caches:
 
@@ -444,7 +706,7 @@ Repeated imports use the same module URL/import promise until invalidated.
 
 Native ESM also caches imports by URL.
 
-## 17. Invalidation and updates
+## 18. Invalidation and updates
 
 Updating a module invalidates:
 
@@ -469,7 +731,7 @@ const fresh = await runtime.import("/App.jsx");
 
 This is deliberate and matches the immutable identity of native evaluated modules.
 
-## 18. `toModule()` semantics
+## 19. `toModule()` semantics
 
 `toModule(source)` is sugar for:
 
@@ -485,7 +747,7 @@ return module namespace
 
 It is asynchronous by design.
 
-## 19. `toComponent()` semantics
+## 20. `toComponent()` semantics
 
 `toComponent()` calls `toModule()` and returns a selected callable export.
 
@@ -499,7 +761,7 @@ Named exports require an explicit `exportName`.
 
 The runtime does not guess between multiple component exports.
 
-## 20. Security model
+## 21. Security model
 
 `solid-tag-runtime` is **not a sandbox**.
 
@@ -507,7 +769,7 @@ Dynamic source executes as JavaScript in the page/module environment and has wha
 
 Do not use this package to execute untrusted hostile code without a separate isolation mechanism such as a suitably sandboxed iframe/worker/process boundary.
 
-## 21. CSP considerations
+## 22. CSP considerations
 
 The browser backend currently uses Blob module URLs by default.
 
@@ -519,7 +781,7 @@ Applications with strict Content Security Policy may need:
 
 The public module API should not depend on Blob URLs so this backend can change later.
 
-## 22. Future directions
+## 23. Future directions
 
 Potential additions, in rough architectural order:
 
@@ -537,16 +799,6 @@ await runtime.load("/App.jsx");
 
 with configurable fetch/source providers.
 
-### Script-tag module registration
-
-Possible declarative zero-build API:
-
-```html
-<script type="solid-jsx" module="/Button.jsx">...</script>
-```
-
-implemented as a thin source-provider layer over the same runtime graph.
-
 ### Runtime update/HMR helpers
 
 Graph invalidation already exists. Future APIs can add lifecycle hooks and entry re-rendering without changing module identity rules.
@@ -563,7 +815,7 @@ The runtime compiler boundary allows a future TSX-capable transformer without co
 
 If `solid-tag` later gains tagged-template → JSX transformation, runtime/editor tooling can expose source views without changing module execution semantics.
 
-## 23. Decision log
+## 24. Decision log
 
 ### 2026-10-02 — Separate runtime package
 
@@ -606,3 +858,57 @@ Reason: the current immutable URL linker cannot assign stable module identities
 Decision: the runtime engine consumes `analyze()` and `transform()` rather than importing parser internals directly.
 
 Reason: preserve the option to add TSX, tagged-source, or alternative transformer backends later.
+### 2026-10-02 — HTML integration is an adapter subpath
+
+Decision: add declarative script registration in `0.0.2` as `solid-tag-runtime/html`, not as methods on the core runtime and not as a separate npm package.
+
+Reason: HTML discovery, DOM access, and fetching are browser concerns. Keeping them behind an export subpath preserves a DOM-free core while avoiding premature package fragmentation.
+
+### 2026-10-02 — HTML declares modules; it is not itself JSX
+
+Decision: support JSX/JS source inside runtime `<script>` modules, but do not reinterpret arbitrary document HTML or `<template>` content as JSX in `0.0.2`.
+
+Reason: module source already has clear lexical/import semantics. Treating document HTML as executable JSX would introduce separate scope, parsing, hydration, and DOM-ownership semantics.
+
+### 2026-10-02 — `src` and `module` are separate concepts
+
+Decision: `src` identifies where source is fetched, while `module` identifies the module inside the runtime graph. When `module` is omitted for an external script, the resolved source URL is used as its identity.
+
+Reason: source location and logical module identity should be independently controllable while still making zero-config relative URL module graphs ergonomic.
+
+### 2026-10-02 — Define all HTML modules before running entries
+
+Decision: `registerHTML()` completes discovery/fetch/definition for all matching scripts before importing any module marked `entry`.
+
+Reason: dependency availability must not depend on HTML document order.
+
+### 2026-10-02 — Live HTML discovery uses an addition-only observer
+
+Decision: add `observeHTML()` to the existing `solid-tag-runtime/html` subpath in `0.0.2`. It uses `MutationObserver`, registers existing scripts by default, tracks seen element identities, and applies the same define-before-entry invariant to every newly discovered batch.
+
+Reason: applications that dynamically insert runtime modules should not need to manually rescan the document, while keeping DOM observation separate from the core runtime module engine. Addition-only semantics avoid silently redefining modules because of text/attribute churn or trying to infer deletion semantics before the runtime has an explicit module-removal API.
+
+### 2026-10-02 — Persistent HTML runtime controllers own DOM/module bindings
+
+Decision: `0.0.3` adds `createHTMLRuntime(runtime, options)` as the preferred advanced HTML API while keeping `registerHTML()`, `observeHTML()`, and `defineScript()` as compatibility conveniences.
+
+Reason: once multiple runtimes, explicit append/register helpers, and observers coexist, ownership must be represented by a persistent object instead of implicit document-wide behavior.
+
+### 2026-10-02 — Runtime script ownership is coordinated through a shared WeakMap
+
+Decision: all HTML ingestion paths use one module-level `WeakMap` from script element to ownership/registration record. Per-controller module-ID maps supplement element ownership.
+
+Reason: a simple observer-local `WeakSet` cannot prevent races between manual registration and MutationObserver, distinguish different owners, retain a pending registration promise, or reject cross-runtime claims deterministically.
+
+### 2026-10-02 — Explicit append claims before DOM insertion
+
+Decision: `html.append(element)` and `html.addModule()` claim ownership before mutating the DOM and register directly rather than relying on the observer callback.
+
+Reason: ownership-before-insertion guarantees the observer can only observe already-owned work, eliminating duplicate compilation and making explicit APIs deterministic even when no observer is active.
+
+### 2026-10-02 — HTML runtime scope is declarative metadata, not ownership authority
+
+Decision: scoped controllers stamp/use `data-solid-runtime="<scope>"` for discovery and debugging, while the in-memory WeakMap remains authoritative.
+
+Reason: attributes are useful across declarative HTML and DevTools but cannot uniquely identify a controller instance or safely coordinate concurrent registration work.
+

package/README.md

@@ -97,6 +97,187 @@ 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.
+
+For simple single-runtime use, the original helpers remain available:
+
+```ts
+import {
+  registerHTML,
+  observeHTML,
+} from "solid-tag-runtime/html";
+
+await registerHTML(runtime);
+```
+
+For applications that may have multiple runtimes or that create runtime scripts programmatically, `0.0.3` adds a persistent HTML runtime controller:
+
+```ts
+import { createHTMLRuntime } from "solid-tag-runtime/html";
+
+const html = createHTMLRuntime(runtime, {
+  scope: "main",
+  root: document,
+});
+
+await html.register();
+await html.observe({ registerExisting: false });
+```
+
+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`.
+
+### Declarative modules
+
+```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>
+```
+
+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>
+```
+
+`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);
+```
+
+Same-controller repeated registration is idempotent. Trying to register an element already owned by another HTML controller throws `HTMLModuleOwnershipError`.
+
+### Let the controller create the script
+
+```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
+
+```ts
+await html.observe({
+  registerExisting: false,
+  onError(error) {
+    console.error(error);
+  },
+});
+
+// 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 gives `0.0.3` 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.
+
+### Addition-only observation
+
+Observation remains addition-only in `0.0.3`.
+
+Changing the source/attributes of an already owned script or removing it from the DOM does not implicitly update/delete the corresponding runtime module. Use `runtime.update()` / `runtime.invalidate()` for explicit module lifecycle changes.
+
+The HTML adapter does **not** reinterpret arbitrary document HTML as JSX and does not currently assign component semantics to `<template>`.
+
 ## `toModule()`
 
 For one-off source strings: