solid-tag-runtime 0.0.8 → 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
 
@@ -1144,3 +1146,53 @@ Implementation note: core and HTML event streams share a small internal dispatch
 
 Regression coverage: package tests cover catch-all, single-type, and multi-type subscriptions; independent unsubscribe; listener exception isolation; update/batch events; resolution/link/evaluation ordering and payloads; structured resolution errors; HTML ownership origins; observer connect/disconnect/batch events; root and append-target events; external source loading; entry execution; update/removal events; HTML error reporting; and HTML subscriber exception isolation.
 
+
+
+### 0.0.9 — shared declarative rendering and `solid-render`
+
+Decision: rendering remains entirely inside `solid-tag-runtime/html`. The core runtime still owns module identity, resolution, linking, execution, caching, invalidation, and host-module injection; it has no DOM or component-mounting responsibility.
+
+Two public rendering forms now share one internal rendering core:
+
+```text
+<script module render>
+  define source + mount one component instance
+
+<solid-render module>
+  reference an existing module + mount one component instance
+```
+
+Declarative script rendering follows these invariants:
+
+- `render="#selector"` imports the module, selects `default` unless `component="Name"` is present, and uses normal Solid container rendering.
+- bare `render` replaces the declaration with start/end comment markers and mounts with positional insertion before the end marker; no wrapper element is introduced.
+- every discovered module in a batch is defined before any `entry` or render action executes.
+- `entry` and `render` on the same declaration are rejected as ambiguous.
+- anonymous `render` declarations receive internal runtime IDs just like anonymous entries.
+- render ownership/disposal is stored on the HTML declaration record and remains separate from module lifetime.
+- `updateElement()` remounts a rendered declaration after source/component/render metadata changes while preserving the same logical module identity.
+- `removeElement()` disposes mounted UI before releasing declaration/module ownership.
+- observer-discovered render declarations use the same batch/ownership pipeline as ordinary declarations.
+
+The shared render adapter lazily resolves the host application's own `solid-js` and `@solidjs/web` modules through the runtime (with `solid-js/web` as a compatibility fallback). This preserves the no-duplicate-Solid invariant and keeps the HTML package free of a direct Solid dependency. Tests/special hosts may inject a render adapter.
+
+`solid-render` invariants:
+
+1. It references an existing runtime module; it never defines source.
+2. Missing `component` means `namespace.default`; `component="Name"` selects a named export.
+3. `data-solid-runtime` selects 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.8",
-    "solid-tag-runtime/html": "https://esm.sh/solid-tag-runtime@0.0.8/html"
+    "solid-tag-runtime": "https://esm.sh/solid-tag-runtime@0.0.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
@@ -689,12 +838,17 @@ append-target-changed
 entry-executing
 entry-executed
 
+render-mounting
+render-mounted
+render-disposing
+render-disposed
+
 html-error
 ```
 
 Ownership-related events include an `origin` describing how the element entered the controller (`observer`, `append`, `register-element`, `add-module`, and related internal scan origins). This is useful for tracing observer/manual-registration races and proving that an explicit `append()` was not processed a second time by the observer.
 
-`observer-batch` summarizes a DOM discovery pass instead of exposing noisy raw `MutationRecord` objects. `element-loading` / `element-loaded` are emitted for `src`-backed modules, and entry events distinguish evaluation caused by an HTML `entry` declaration from an ordinary `runtime.import()`.
+`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.
 

package/html.d.ts

@@ -1,17 +1,31 @@
 import { SolidTagRuntimeError } from "./index.js";
 import type { ModuleFormat, ModuleNamespaceLike, SolidTagRuntime } from "./index.js";
 
-export interface HTMLModuleScriptElement {
+export interface HTMLAttributeElementLike {
   textContent?: string | null;
   baseURI?: string;
   ownerDocument?: HTMLDocumentLike | null;
-  parentNode?: { removeChild?(element: any): unknown } | null;
+  parentNode?: {
+    removeChild?(element: any): unknown;
+    insertBefore?(element: any, reference: any): unknown;
+  } | null;
   remove?(): void;
+  replaceWith?(...nodes: any[]): void;
   getAttribute(name: string): string | null;
   hasAttribute?(name: string): boolean;
   setAttribute?(name: string, value: string): void;
 }
 
+export interface HTMLModuleScriptElement extends HTMLAttributeElementLike {}
+
+export interface SolidRenderElement extends HTMLAttributeElementLike, HTMLAppendTarget {
+  props: Record<string, unknown>;
+  childNodes?: ArrayLike<any> | Iterable<any>;
+  attributes?: ArrayLike<{ name: string; value: string }> | Iterable<{ name: string; value: string }>;
+  replaceChildren?(...nodes: any[]): void;
+  dispatchEvent?(event: unknown): boolean;
+}
+
 export interface HTMLAppendTarget {
   append?(...nodes: any[]): void;
   appendChild?(element: any): unknown;
@@ -21,6 +35,8 @@ export interface HTMLDocumentLike extends HTMLModuleRoot, HTMLAppendTarget {
   body?: HTMLAppendTarget;
   documentElement?: HTMLAppendTarget;
   createElement?(tagName: string): any;
+  createComment?(data: string): any;
+  createDocumentFragment?(): any;
 }
 
 export interface HTMLModuleRoot {
@@ -28,7 +44,9 @@ export interface HTMLModuleRoot {
   ownerDocument?: HTMLDocumentLike | null;
   body?: HTMLAppendTarget;
   documentElement?: HTMLAppendTarget;
-  querySelectorAll(selector: string): Iterable<HTMLModuleScriptElement> | ArrayLike<HTMLModuleScriptElement>;
+  querySelectorAll(selector: string): Iterable<any> | ArrayLike<any>;
+  querySelector?(selector: string): any;
+  contains?(node: any): boolean;
 }
 
 export interface HTMLFetchResponse {
@@ -44,8 +62,9 @@ export interface HTMLMutationObserverLike {
   observe(
     target: unknown,
     options: {
-      childList: boolean;
-      subtree: boolean;
+      childList?: boolean;
+      subtree?: boolean;
+      attributes?: boolean;
     },
   ): void;
   disconnect(): void;
@@ -53,12 +72,44 @@ export interface HTMLMutationObserverLike {
 
 export interface HTMLMutationObserverConstructor {
   new (
-    callback: (...args: unknown[]) => void,
+    callback: (...args: any[]) => void,
   ): HTMLMutationObserverLike;
 }
 
+export interface HTMLMountRecord {
+  kind?: "container" | "range" | string;
+  target?: unknown;
+  updateProps?(props: Record<string, unknown>): void;
+  dispose?(): void | Promise<void>;
+}
+
+export interface HTMLRenderAdapter {
+  mountContainer(options: {
+    runtime: SolidTagRuntime;
+    target: any;
+    Component: Function;
+    props: Record<string, unknown>;
+    element?: HTMLAttributeElementLike | SolidRenderElement;
+    moduleId?: string;
+  }): HTMLMountRecord | Promise<HTMLMountRecord>;
+
+  mountRange(options: {
+    runtime: SolidTagRuntime;
+    parent: any;
+    before: any;
+    startMarker: any;
+    endMarker: any;
+    Component: Function;
+    props: Record<string, unknown>;
+    element?: HTMLModuleScriptElement;
+    moduleId?: string;
+  }): HTMLMountRecord | Promise<HTMLMountRecord>;
+}
+
 export interface DefineScriptOptions {
   root?: HTMLModuleRoot;
+  /** Optional selector-resolution root for declarative render="...". */
+  renderRoot?: HTMLModuleRoot;
   baseUrl?: string;
   format?: ModuleFormat | "javascript";
   fetch?: HTMLFetch;
@@ -72,15 +123,28 @@ export interface HTMLModuleDefinition {
   id: string;
   format: ModuleFormat;
   entry: boolean;
+  /** undefined = no render, true = in-place, string = selector target. */
+  render?: true | string;
+  /** Named component export. Missing means default export. */
+  component?: string;
   sourceUrl?: string;
   inline: boolean;
   element: HTMLModuleScriptElement;
 }
 
+export interface HTMLRenderedModule {
+  id: string;
+  namespace: ModuleNamespaceLike;
+  component: string;
+  mode: "selector" | "in-place";
+  target?: unknown;
+  element: HTMLModuleScriptElement;
+}
+
 export interface RemoveHTMLElementOptions {
   /** Remove the runtime module as well as releasing HTML ownership. Default: true. */
   removeModule?: boolean;
-  /** Remove the script element from the DOM. Default: true. */
+  /** Remove the script declaration/range from the DOM. Default: true. */
   removeFromDOM?: boolean;
   /** Invalidate runtime dependents when removing the module. Default: true. */
   invalidateDependents?: boolean;
@@ -96,6 +160,8 @@ export interface RemoveHTMLElementResult {
 export interface RegisterHTMLOptions extends DefineScriptOptions {
   selector?: string;
   executeEntries?: boolean;
+  /** Execute declarative render actions. Default: true. */
+  executeRenders?: boolean;
 }
 
 export interface RegisterHTMLResult {
@@ -105,6 +171,8 @@ export interface RegisterHTMLResult {
     id: string;
     namespace: ModuleNamespaceLike;
   }>;
+  renders: string[];
+  rendered: HTMLRenderedModule[];
 }
 
 export type HTMLRegistrationOrigin =
@@ -119,11 +187,15 @@ export type HTMLRegistrationOrigin =
   | "add-module"
   | "update-element"
   | "remove-element"
+  | "solid-render"
   | string;
 
+export type HTMLRenderSource = "script-render" | "solid-render";
+export type HTMLRenderMode = "selector" | "in-place" | "container";
+
 export type HTMLRuntimeEvent =
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-discovered"; element: HTMLModuleScriptElement; moduleId?: string; origin: HTMLRegistrationOrigin; accepted: boolean }
-  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-claimed"; element: HTMLModuleScriptElement; moduleId: string; format: ModuleFormat; entry: boolean; sourceUrl?: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-claimed"; element: HTMLModuleScriptElement; moduleId: string; format: ModuleFormat; entry: boolean; render?: true | string; component?: string; sourceUrl?: string; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-loading"; element: HTMLModuleScriptElement; moduleId: string; sourceUrl: string; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-loaded"; element: HTMLModuleScriptElement; moduleId: string; sourceUrl: string; origin: HTMLRegistrationOrigin; bytes: number; durationMs: number }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-registered"; element: HTMLModuleScriptElement; moduleId: string; definition: HTMLModuleDefinition; origin: HTMLRegistrationOrigin }
@@ -140,7 +212,11 @@ export type HTMLRuntimeEvent =
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "append-target-changed"; previousTarget?: HTMLAppendTarget; target: HTMLAppendTarget }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "entry-executing"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "entry-executed"; element: HTMLModuleScriptElement; moduleId: string; namespace: ModuleNamespaceLike; origin: HTMLRegistrationOrigin }
-  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-error"; operation: "discover" | "claim" | "fetch" | "register" | "update" | "remove" | "entry" | "root-change" | "observer" | string; error: unknown; element?: HTMLModuleScriptElement; moduleId?: string; origin?: HTMLRegistrationOrigin };
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-mounting"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-mounted"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; target?: unknown; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-disposing"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; reason: string; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-disposed"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; reason: string; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-error"; operation: "discover" | "claim" | "fetch" | "register" | "update" | "remove" | "entry" | "render" | "solid-render" | "root-change" | "observer" | string; error: unknown; element?: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; origin?: HTMLRegistrationOrigin };
 
 export type HTMLRuntimeEventType = HTMLRuntimeEvent["type"];
 export type HTMLRuntimeEventOfType<T extends HTMLRuntimeEventType> =
@@ -163,9 +239,12 @@ export interface AddHTMLModuleOptions extends DefineScriptOptions {
   source?: string;
   src?: string;
   entry?: boolean;
+  render?: true | string;
+  component?: string;
   type?: string;
   language?: string;
   executeEntries?: boolean;
+  executeRenders?: boolean;
   appendTo?: HTMLAppendTarget;
   document?: HTMLDocumentLike;
   createElement?: (tagName: string) => HTMLModuleScriptElement;
@@ -174,6 +253,8 @@ export interface AddHTMLModuleOptions extends DefineScriptOptions {
 export interface HTMLRuntimeOptions extends ObserveHTMLOptions {
   appendTo?: HTMLAppendTarget;
   createElement?: (tagName: string) => HTMLModuleScriptElement;
+  /** Override Solid mounting for tests/special hosts. */
+  renderAdapter?: HTMLRenderAdapter;
 }
 
 export interface SetHTMLRootOptions extends RegisterHTMLOptions {
@@ -190,11 +271,8 @@ export interface HTMLRuntimeController {
   readonly runtime: SolidTagRuntime;
   readonly scope?: string;
   readonly connected: boolean;
-  /** Current configured/effective discovery root when available. */
   readonly root?: HTMLModuleRoot;
-  /** Current effective target used by append()/addModule() when available. */
   readonly appendTarget?: HTMLAppendTarget;
-  /** Result of the observer's initial scan. */
   readonly initial: RegisterHTMLResult;
 
   subscribe(listener: (event: HTMLRuntimeEvent) => void): () => boolean;
@@ -207,65 +285,22 @@ export interface HTMLRuntimeController {
     listener: (event: HTMLRuntimeEventOfType<T[number]>) => void,
   ): () => boolean;
 
-  /** One-shot scan of matching scripts under the configured/root override. */
   register(options?: RegisterHTMLOptions): Promise<RegisterHTMLResult>;
-
-  /** Start live addition observation. Returns this controller. */
   observe(options?: ObserveHTMLOptions): Promise<HTMLRuntimeController>;
-
-  /** Wait for queued observer work and scan for newly discoverable scripts. */
   flush(options?: RegisterHTMLOptions): Promise<RegisterHTMLResult>;
   disconnect(): void;
+  /** Dispose HTML-owned mounts/registry state without disposing the core runtime. */
+  dispose(): Promise<void>;
 
-  /**
-   * Change the discovery/observation root. A connected observer is rebound to
-   * the new node automatically.
-   */
-  setRoot(
-    root: HTMLModuleRoot,
-    options?: SetHTMLRootOptions,
-  ): Promise<RegisterHTMLResult>;
-
-  /** Change both the discovery root and append target to the selected root. */
-  moveTo(
-    root: HTMLModuleRoot,
-    options?: SetHTMLRootOptions,
-  ): Promise<RegisterHTMLResult>;
-
-  /** Change only where append()/addModule() insert future elements. */
+  setRoot(root: HTMLModuleRoot, options?: SetHTMLRootOptions): Promise<RegisterHTMLResult>;
+  moveTo(root: HTMLModuleRoot, options?: SetHTMLRootOptions): Promise<RegisterHTMLResult>;
   setAppendTarget(target: HTMLAppendTarget): HTMLRuntimeController;
 
-  /** Define one element without auto-running an entry. */
-  defineElement(
-    element: HTMLModuleScriptElement,
-    options?: DefineScriptOptions,
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Explicitly claim/register an existing element for this runtime. */
-  registerElement(
-    element: HTMLModuleScriptElement,
-    options?: RegisterHTMLOptions,
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Re-read and replace source for an element already owned by this controller. */
-  updateElement(
-    element: HTMLModuleScriptElement,
-    options?: RegisterHTMLOptions,
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Release an owned element and optionally remove its module and DOM node. */
-  removeElement(
-    element: HTMLModuleScriptElement,
-    options?: RemoveHTMLElementOptions,
-  ): Promise<RemoveHTMLElementResult>;
-
-  /** Claim first, append a user-created element, then register it directly. */
-  append(
-    element: HTMLModuleScriptElement,
-    options?: RegisterHTMLOptions & { appendTo?: HTMLAppendTarget },
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Create a runtime script element and add it through the controller. */
+  defineElement(element: HTMLModuleScriptElement, options?: DefineScriptOptions): Promise<HTMLModuleDefinition>;
+  registerElement(element: HTMLModuleScriptElement, options?: RegisterHTMLOptions): Promise<HTMLModuleDefinition>;
+  updateElement(element: HTMLModuleScriptElement, options?: RegisterHTMLOptions): Promise<HTMLModuleDefinition>;
+  removeElement(element: HTMLModuleScriptElement, options?: RemoveHTMLElementOptions): Promise<RemoveHTMLElementResult>;
+  append(element: HTMLModuleScriptElement, options?: RegisterHTMLOptions & { appendTo?: HTMLAppendTarget }): Promise<HTMLModuleDefinition>;
   addModule(options: AddHTMLModuleOptions): Promise<HTMLModuleDefinition>;
 
   owns(element: HTMLModuleScriptElement): boolean;
@@ -273,7 +308,16 @@ export interface HTMLRuntimeController {
   getElement(id: string): HTMLModuleScriptElement | undefined;
 }
 
-/** Legacy observer shape is now the full HTML runtime controller. */
+export interface CustomElementRegistryLike {
+  define(name: string, constructor: any): void;
+  get(name: string): any;
+}
+
+export interface RegisterSolidRenderElementOptions {
+  customElements?: CustomElementRegistryLike;
+  HTMLElement?: new (...args: any[]) => any;
+}
+
 export type HTMLObserverController = HTMLRuntimeController;
 
 export declare class HTMLModuleError extends SolidTagRuntimeError {
@@ -287,6 +331,12 @@ export declare class HTMLModuleOwnershipError extends HTMLModuleError {
   requestedScope?: string;
 }
 
+export declare class HTMLRenderError extends SolidTagRuntimeError {
+  element?: HTMLModuleScriptElement | SolidRenderElement;
+  moduleId?: string;
+  component?: string;
+}
+
 export declare const htmlModuleSelector: string;
 export declare const htmlRuntimeScopeAttribute: "data-solid-runtime";
 
@@ -295,6 +345,10 @@ export declare function createHTMLRuntime(
   options?: HTMLRuntimeOptions,
 ): HTMLRuntimeController;
 
+export declare function registerSolidRenderElement(
+  options?: RegisterSolidRenderElementOptions,
+): any | undefined;
+
 export declare function defineScript(
   runtime: SolidTagRuntime,
   element: HTMLModuleScriptElement,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {