solid-tag-runtime 0.0.1 → 0.0.2

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,119 @@ 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
+
+`0.0.2` adds `solid-tag-runtime/html` as an opt-in browser-facing adapter.
+
+Important architectural boundary:
+
+```text
+DOM / HTML document
+      ↓
+solid-tag-runtime/html
+      ↓
+runtime.define(...)
+      ↓
+core module graph
+```
+
+The core runtime remains DOM-independent. It does not scan documents, fetch `<script>` elements, or know about HTML attributes.
+
+### Public HTML API
+
+```ts
+await registerHTML(runtime, options?);
+await defineScript(runtime, element, options?);
+const observer = await observeHTML(runtime, options?);
+```
+
+`registerHTML()` discovers matching script elements, defines the complete discovered graph, and only then executes modules marked `entry` unless `executeEntries: false` is supplied.
+
+`observeHTML()` is the live-discovery adapter. It uses `MutationObserver` to discover scripts added after registration. Existing scripts are registered by default; `registerExisting: false` supports the pattern where `registerHTML()` already performed the initial scan.
+
+Every observer scan preserves the same graph invariant as `registerHTML()`: all newly discovered modules in that batch are defined before any newly discovered entry is executed. The observer tracks element identity so an already-seen element is not repeatedly redefined on unrelated DOM mutations.
+
+The returned controller exposes:
+
+```ts
+observer.initial;
+observer.connected;
+await observer.flush();
+observer.disconnect();
+```
+
+`flush()` waits for queued observer work and performs another scan, making it useful to synchronize application code with asynchronous `src` fetching and module evaluation. Background observer failures may be handled with `onError`.
+
+Observation in `0.0.2` is intentionally addition-only: changes to attributes/text of an already registered script and removal of that script do not implicitly update or remove its runtime module. Those semantics require explicit runtime updates today and may become a separate future feature.
+
+This ordering is an invariant: document order must not require dependencies to appear before entries.
+
+### 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. This allows multiple URL-backed source scripts to use normal relative imports.
+
+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 discovered modules are defined, the adapter performs:
+
+```ts
+await runtime.import("/App.jsx");
+```
+
+The entry module is expected to perform whatever side effect starts the application, such as calling `render()`.
+
+### 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 +344,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 +377,7 @@ Example graph:
   └── ../ui/Button.jsx     → compiled virtual source URL
 ```
 
-## 10. Resolution rules
+## 11. Resolution rules
 
 Resolution order is conceptually:
 
@@ -282,7 +393,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 +431,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 +452,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 +487,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 +524,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 +542,7 @@ When linking `/App.jsx` imports `/Button.jsx`:
 
 These edges power invalidation and tooling.
 
-## 16. Caching
+## 17. Caching
 
 A source module caches:
 
@@ -444,7 +555,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 +580,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 +596,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 +610,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 +618,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 +630,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 +648,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 +664,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 +707,33 @@ 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.
+

package/README.md

@@ -97,6 +97,150 @@ counterModule.Counter;
 
 The runtime compiles and links the dependency graph automatically.
 
+
+## Declarative HTML modules
+
+`0.0.2` adds a browser adapter at `solid-tag-runtime/html`. The core runtime remains DOM-independent; the HTML adapter only discovers source modules and feeds them into the same runtime module graph.
+
+```ts
+import { registerHTML, observeHTML } from "solid-tag-runtime/html";
+
+await registerHTML(runtime);
+```
+
+The adapter recognizes runtime script modules such as:
+
+```html
+<script type="solid-jsx" module="/ui/Button.jsx">
+  export function Button(props) {
+    return (
+      <button onClick={props.onClick}>
+        {props.children}
+      </button>
+    );
+  }
+</script>
+
+<script type="solid-jsx" module="/App.jsx" entry>
+  import { render } from "@solidjs/web";
+  import { Button } from "./ui/Button.jsx";
+
+  function App() {
+    return <Button>Hello from runtime JSX</Button>;
+  }
+
+  render(() => <App />, document.getElementById("app"));
+</script>
+```
+
+All matching scripts are **defined before any `entry` module is executed**. This means an entry may import a module that appears later in the HTML document.
+
+External source is supported as well:
+
+```html
+<script
+  type="solid-jsx"
+  module="/ui/Button.jsx"
+  src="./components/Button.jsx">
+</script>
+
+<script
+  type="solid-jsx"
+  module="/App.jsx"
+  src="./App.jsx"
+  entry>
+</script>
+```
+
+`src` answers **where the source is fetched from** while `module` answers **what its identity is in the runtime graph**. They are intentionally separate.
+
+If `module` is omitted for a `src` script, the resolved source URL becomes the module ID. This makes relative imports between externally loaded modules work naturally. Inline non-entry scripts require a `module` attribute; an inline `entry` may omit it and receives an anonymous runtime module ID.
+
+### HTML script formats
+
+Explicit script types:
+
+```text
+solid-jsx / text/solid-jsx  → JSX transformation
+solid-js  / text/solid-js   → plain JavaScript module
+solid-module                → infer from module/src extension
+```
+
+For `solid-module`, `.js`/`.mjs` are treated as JavaScript and other extensions currently default to JSX. A `language="js"` or `language="jsx"` attribute can override inference.
+
+### Register without executing entries
+
+```ts
+const registration = await registerHTML(runtime, {
+  executeEntries: false,
+});
+
+console.log(registration.modules);
+console.log(registration.entries);
+
+await runtime.import(registration.entries[0]);
+```
+
+### Register one script manually
+
+```ts
+import { defineScript } from "solid-tag-runtime/html";
+
+const definition = await defineScript(
+  runtime,
+  document.querySelector("#runtime-component"),
+);
+
+const namespace = await runtime.import(definition.id);
+```
+
+### Observe scripts added later
+
+`observeHTML()` uses `MutationObserver` to register runtime module scripts added after startup. It performs an initial scan by default and preserves the same batch invariant as `registerHTML()`: all newly discovered modules are defined before any newly discovered `entry` executes.
+
+```ts
+import { observeHTML } from "solid-tag-runtime/html";
+
+const observer = await observeHTML(runtime, {
+  onError(error) {
+    console.error("runtime module registration failed", error);
+  },
+});
+
+// Later, code may append a new runtime module script.
+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>;
+  }
+`;
+document.body.append(script);
+
+// Normally MutationObserver handles this automatically. flush() is useful when
+// code needs to wait until queued observation work has completed.
+await observer.flush();
+
+const { Greeting } = await runtime.import("/dynamic/Greeting.jsx");
+
+observer.disconnect();
+```
+
+If existing scripts were already registered separately, start observation without re-registering them:
+
+```ts
+await registerHTML(runtime);
+
+const observer = await observeHTML(runtime, {
+  registerExisting: false,
+});
+```
+
+In `0.0.2`, observation is intentionally **addition-only**. Editing attributes/text of an already registered script or removing that script does not automatically update/remove the corresponding runtime module. Use `runtime.update()` / `runtime.invalidate()` explicitly when needed.
+
+The HTML adapter does **not** reinterpret ordinary document HTML as JSX and does not currently add `<template>` component semantics. JSX remains source-code syntax inside runtime modules.
+
 ## `toModule()`
 
 For one-off source strings:

package/html.d.ts

@@ -0,0 +1,114 @@
+import { SolidTagRuntimeError } from "./index.js";
+import type { ModuleFormat, ModuleNamespaceLike, SolidTagRuntime } from "./index.js";
+
+export interface HTMLModuleScriptElement {
+  textContent?: string | null;
+  baseURI?: string;
+  getAttribute(name: string): string | null;
+  hasAttribute?(name: string): boolean;
+}
+
+export interface HTMLModuleRoot {
+  baseURI?: string;
+  querySelectorAll(selector: string): Iterable<HTMLModuleScriptElement> | ArrayLike<HTMLModuleScriptElement>;
+}
+
+export interface HTMLFetchResponse {
+  ok?: boolean;
+  status?: number;
+  statusText?: string;
+  text(): Promise<string>;
+}
+
+export type HTMLFetch = (url: string) => Promise<HTMLFetchResponse>;
+
+export interface HTMLMutationObserverLike {
+  observe(
+    target: unknown,
+    options: {
+      childList: boolean;
+      subtree: boolean;
+    },
+  ): void;
+  disconnect(): void;
+}
+
+export interface HTMLMutationObserverConstructor {
+  new (
+    callback: (...args: unknown[]) => void,
+  ): HTMLMutationObserverLike;
+}
+
+export interface DefineScriptOptions {
+  root?: HTMLModuleRoot;
+  baseUrl?: string;
+  format?: ModuleFormat | "javascript";
+  fetch?: HTMLFetch;
+}
+
+export interface HTMLModuleDefinition {
+  id: string;
+  format: ModuleFormat;
+  entry: boolean;
+  sourceUrl?: string;
+  inline: boolean;
+  element: HTMLModuleScriptElement;
+}
+
+export interface RegisterHTMLOptions extends DefineScriptOptions {
+  selector?: string;
+  executeEntries?: boolean;
+}
+
+export interface RegisterHTMLResult {
+  modules: HTMLModuleDefinition[];
+  entries: string[];
+  executed: Array<{
+    id: string;
+    namespace: ModuleNamespaceLike;
+  }>;
+}
+
+export interface ObserveHTMLOptions extends RegisterHTMLOptions {
+  /** Register scripts already present when observation starts. Default: true. */
+  registerExisting?: boolean;
+  /** Observe descendant additions as well as direct children. Default: true. */
+  subtree?: boolean;
+  /** Override the platform MutationObserver constructor, useful for DOM-like hosts/tests. */
+  MutationObserver?: HTMLMutationObserverConstructor;
+  /** Called for asynchronous observer registration/import failures. */
+  onError?: (error: unknown) => void;
+}
+
+export interface HTMLObserverController {
+  /** Result of the initial scan. Empty when registerExisting is false. */
+  initial: RegisterHTMLResult;
+  readonly connected: boolean;
+  /** Wait for queued observer work and synchronously scan for any unseen scripts. */
+  flush(): Promise<RegisterHTMLResult>;
+  disconnect(): void;
+}
+
+export declare class HTMLModuleError extends SolidTagRuntimeError {
+  element?: HTMLModuleScriptElement;
+  moduleId?: string;
+  sourceUrl?: string;
+}
+
+export declare const htmlModuleSelector: string;
+
+export declare function defineScript(
+  runtime: SolidTagRuntime,
+  element: HTMLModuleScriptElement,
+  options?: DefineScriptOptions,
+): Promise<HTMLModuleDefinition>;
+
+export declare function registerHTML(
+  runtime: SolidTagRuntime,
+  options?: RegisterHTMLOptions,
+): Promise<RegisterHTMLResult>;
+
+export declare function observeHTML(
+  runtime: SolidTagRuntime,
+  options?: ObserveHTMLOptions,
+): Promise<HTMLObserverController>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {
@@ -18,6 +18,11 @@
       "types": "./index.d.ts",
       "import": "./src/runtime.js",
       "default": "./src/runtime.js"
+    },
+    "./html": {
+      "types": "./html.d.ts",
+      "import": "./src/html.js",
+      "default": "./src/html.js"
     }
   },
   "main": "./src/index.js",
@@ -26,6 +31,7 @@
   "files": [
     "src",
     "index.d.ts",
+    "html.d.ts",
     "README.md",
     "ARCHITECTURE.md"
   ],

package/src/html.js

@@ -0,0 +1,362 @@
+import { SolidTagRuntimeError } from "./errors.js";
+
+const DEFAULT_SELECTOR = [
+  'script[type="solid-jsx"]',
+  'script[type="text/solid-jsx"]',
+  'script[type="solid-js"]',
+  'script[type="text/solid-js"]',
+  'script[type="solid-module"]',
+  'script[type="text/solid-module"]',
+].join(",");
+
+let anonymousSequence = 0;
+
+export class HTMLModuleError extends SolidTagRuntimeError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "HTMLModuleError";
+    this.element = options.element;
+    this.moduleId = options.moduleId;
+    this.sourceUrl = options.sourceUrl;
+  }
+}
+
+/**
+ * Discover runtime module scripts under a Document/Element-like root, define
+ * all of them first, then optionally execute scripts marked with `entry`.
+ */
+export async function registerHTML(runtime, options = {}) {
+  assertRuntime(runtime);
+
+  const root = getRoot(options, "registerHTML");
+  const elements = Array.from(root.querySelectorAll(options.selector ?? DEFAULT_SELECTOR));
+
+  return registerElements(runtime, elements, {
+    ...options,
+    root,
+  });
+}
+
+/**
+ * Observe a DOM root for newly-added runtime module scripts.
+ *
+ * Existing scripts are registered by default. Every discovered mutation batch
+ * preserves the same invariant as registerHTML(): all modules in the batch are
+ * defined before any entry module from that batch executes.
+ *
+ * v0.0.2 intentionally observes additions only. Mutating or removing a script
+ * that was already registered does not update/remove its runtime module.
+ */
+export async function observeHTML(runtime, options = {}) {
+  assertRuntime(runtime);
+
+  const root = getRoot(options, "observeHTML");
+  const MutationObserverImpl = options.MutationObserver ?? globalThis.MutationObserver;
+
+  if (typeof MutationObserverImpl !== "function") {
+    throw new TypeError(
+      "observeHTML() requires MutationObserver support or a MutationObserver option.",
+    );
+  }
+
+  const selector = options.selector ?? DEFAULT_SELECTOR;
+  const seen = new WeakSet();
+  let connected = true;
+  let lastError;
+  let queue = Promise.resolve();
+
+  if (options.registerExisting === false) {
+    for (const element of Array.from(root.querySelectorAll(selector))) {
+      seen.add(element);
+    }
+  }
+
+  const scanAndRegister = async () => {
+    const elements = Array.from(root.querySelectorAll(selector)).filter(
+      element => !seen.has(element),
+    );
+
+    if (elements.length === 0) return emptyRegistrationResult();
+
+    return registerElements(
+      runtime,
+      elements,
+      {
+        ...options,
+        root,
+      },
+      element => seen.add(element),
+    );
+  };
+
+  const reportError = error => {
+    lastError = error;
+
+    if (typeof options.onError === "function") {
+      options.onError(error);
+      return;
+    }
+
+    // MutationObserver callbacks cannot be awaited by the DOM. Keep the error
+    // available for flush(), but also make background failures visible.
+    globalThis.console?.error?.("solid-tag-runtime/html observer error", error);
+  };
+
+  const enqueue = () => {
+    const task = queue.then(scanAndRegister);
+    queue = task.then(
+      () => undefined,
+      error => {
+        reportError(error);
+      },
+    );
+    return task;
+  };
+
+  const observer = new MutationObserverImpl(() => {
+    // The settled queue owns background error reporting. Attach a rejection
+    // handler here as well so the callback never creates an unhandled promise.
+    void enqueue().catch(() => {});
+  });
+
+  observer.observe(root, {
+    childList: true,
+    subtree: options.subtree !== false,
+  });
+
+  let initial = emptyRegistrationResult();
+
+  try {
+    if (options.registerExisting !== false) {
+      initial = await enqueue();
+    }
+  } catch (error) {
+    connected = false;
+    observer.disconnect();
+    throw error;
+  }
+
+  return {
+    initial,
+
+    get connected() {
+      return connected;
+    },
+
+    async flush() {
+      await queue;
+
+      if (lastError) {
+        const error = lastError;
+        lastError = undefined;
+        throw error;
+      }
+
+      return enqueue();
+    },
+
+    disconnect() {
+      if (!connected) return;
+      connected = false;
+      observer.disconnect();
+    },
+  };
+}
+
+/**
+ * Define one <script> element as a runtime module without executing it.
+ */
+export async function defineScript(runtime, element, options = {}) {
+  assertRuntime(runtime);
+
+  if (!element || typeof element.getAttribute !== "function") {
+    throw new TypeError("defineScript() expects a script element-like object.");
+  }
+
+  const type = normalizeType(element.getAttribute("type"));
+  const entry = hasAttribute(element, "entry");
+  const srcAttribute = nonEmpty(element.getAttribute("src"));
+  const explicitId = nonEmpty(element.getAttribute("module"));
+  const sourceUrl = srcAttribute
+    ? resolveSourceUrl(srcAttribute, options.baseUrl ?? element.baseURI ?? options.root?.baseURI)
+    : undefined;
+
+  const format = inferFormat({
+    explicitFormat: options.format,
+    language: nonEmpty(element.getAttribute("language")),
+    type,
+    moduleId: explicitId,
+    sourceUrl,
+  });
+
+  const id = explicitId ?? sourceUrl ?? (entry ? createAnonymousId(format) : undefined);
+
+  if (!id) {
+    throw new HTMLModuleError(
+      "Inline solid runtime module scripts require a `module` attribute unless they are marked `entry`.",
+      { element },
+    );
+  }
+
+  let source;
+  if (sourceUrl) {
+    source = await fetchSource(sourceUrl, options.fetch ?? globalThis.fetch, element, id);
+  } else {
+    source = element.textContent ?? "";
+  }
+
+  runtime.define(id, source, { format });
+
+  return {
+    id: runtime.resolve(id),
+    format,
+    entry,
+    sourceUrl,
+    inline: !sourceUrl,
+    element,
+  };
+}
+
+export const htmlModuleSelector = DEFAULT_SELECTOR;
+
+async function registerElements(runtime, elements, options, onDefined) {
+  const modules = [];
+
+  // Define the complete discovered batch before evaluating any entry. This
+  // allows an entry to import another module discovered later in the same scan.
+  for (const element of elements) {
+    const definition = await defineScript(runtime, element, options);
+    modules.push(definition);
+    onDefined?.(element, definition);
+  }
+
+  const entries = modules.filter(module => module.entry);
+  const executed = [];
+
+  if (options.executeEntries !== false) {
+    for (const entry of entries) {
+      executed.push({
+        id: entry.id,
+        namespace: await runtime.import(entry.id),
+      });
+    }
+  }
+
+  return {
+    modules,
+    entries: entries.map(entry => entry.id),
+    executed,
+  };
+}
+
+function emptyRegistrationResult() {
+  return {
+    modules: [],
+    entries: [],
+    executed: [],
+  };
+}
+
+function getRoot(options, caller) {
+  const root = options.root ?? globalThis.document;
+  if (!root || typeof root.querySelectorAll !== "function") {
+    throw new TypeError(`${caller}() requires a DOM root with querySelectorAll().`);
+  }
+  return root;
+}
+
+function assertRuntime(runtime) {
+  if (!runtime || typeof runtime.define !== "function" || typeof runtime.import !== "function") {
+    throw new TypeError("Expected a solid-tag-runtime instance.");
+  }
+}
+
+function normalizeType(value) {
+  return String(value ?? "").trim().toLowerCase();
+}
+
+function inferFormat({ explicitFormat, language, type, moduleId, sourceUrl }) {
+  if (explicitFormat != null) return normalizeFormat(explicitFormat);
+  if (language != null) return normalizeFormat(language);
+
+  if (type === "solid-js" || type === "text/solid-js") return "js";
+  if (type === "solid-jsx" || type === "text/solid-jsx") return "jsx";
+
+  const target = moduleId ?? sourceUrl ?? "";
+  const pathname = stripQueryAndHash(target).toLowerCase();
+  if (pathname.endsWith(".js") || pathname.endsWith(".mjs")) return "js";
+  return "jsx";
+}
+
+function normalizeFormat(value) {
+  const format = String(value).trim().toLowerCase();
+  if (format === "js" || format === "javascript") return "js";
+  if (format === "jsx") return "jsx";
+  throw new HTMLModuleError(`Unsupported HTML runtime module format ${JSON.stringify(value)}.`);
+}
+
+async function fetchSource(url, fetchImpl, element, moduleId) {
+  if (typeof fetchImpl !== "function") {
+    throw new HTMLModuleError(
+      `Cannot load ${JSON.stringify(url)} because no fetch implementation is available.`,
+      { element, moduleId, sourceUrl: url },
+    );
+  }
+
+  let response;
+  try {
+    response = await fetchImpl(url);
+  } catch (cause) {
+    throw new HTMLModuleError(
+      `Failed to fetch runtime module ${JSON.stringify(url)}.`,
+      { cause, element, moduleId, sourceUrl: url },
+    );
+  }
+
+  if (!response || response.ok === false) {
+    const status = response?.status ? ` (${response.status}${response.statusText ? ` ${response.statusText}` : ""})` : "";
+    throw new HTMLModuleError(
+      `Failed to fetch runtime module ${JSON.stringify(url)}${status}.`,
+      { element, moduleId, sourceUrl: url },
+    );
+  }
+
+  try {
+    return await response.text();
+  } catch (cause) {
+    throw new HTMLModuleError(
+      `Failed to read runtime module ${JSON.stringify(url)} as text.`,
+      { cause, element, moduleId, sourceUrl: url },
+    );
+  }
+}
+
+function resolveSourceUrl(src, baseUrl) {
+  try {
+    if (baseUrl) return new URL(src, baseUrl).href;
+    return new URL(src).href;
+  } catch {
+    // A DOM element normally supplies baseURI. Keeping the original string is
+    // still useful for custom DOM-like environments and injected fetchers.
+    return src;
+  }
+}
+
+function createAnonymousId(format) {
+  const extension = format === "js" ? "js" : "jsx";
+  return `/__solid_tag_runtime__/html-entry-${++anonymousSequence}.${extension}`;
+}
+
+function stripQueryAndHash(value) {
+  return String(value).split(/[?#]/, 1)[0];
+}
+
+function nonEmpty(value) {
+  const text = String(value ?? "").trim();
+  return text || undefined;
+}
+
+function hasAttribute(element, name) {
+  if (typeof element.hasAttribute === "function") return element.hasAttribute(name);
+  return element.getAttribute(name) != null;
+}