solid-tag-runtime 0.0.7 → 0.0.9

package/src/html.js

@@ -1,4 +1,6 @@
 import { SolidTagRuntimeError } from "./errors.js";
+import { createEventDispatcher } from "./events.js";
+import { HTMLRenderError, createDefaultHTMLRenderAdapter, resolveRenderComponent } from "./render.js";
 
 const DEFAULT_SELECTOR = [
   'script[type="solid-jsx"]',
@@ -12,6 +14,9 @@ const DEFAULT_SELECTOR = [
 const RUNTIME_SCOPE_ATTRIBUTE = "data-solid-runtime";
 const elementOwners = new WeakMap();
 const defaultControllers = new WeakMap();
+const activeControllers = new Set();
+const solidRenderClasses = new WeakMap();
+const solidRenderInternals = new WeakMap();
 let anonymousSequence = 0;
 let controllerSequence = 0;
 
@@ -34,6 +39,8 @@ export class HTMLModuleOwnershipError extends HTMLModuleError {
   }
 }
 
+export { HTMLRenderError };
+
 /**
  * Create a persistent DOM/HTML adapter for one solid-tag-runtime instance.
  *
@@ -47,18 +54,27 @@ export function createHTMLRuntime(runtime, options = {}) {
   const controller = {
     id: `solid-tag-html-${++controllerSequence}`,
     runtime,
+    events: createEventDispatcher({
+      onListenerError(error) {
+        globalThis.console?.error?.("solid-tag-runtime/html lifecycle subscriber error", error);
+      },
+    }),
     scope: normalizeScope(options.scope),
     root: options.root,
     selector: options.selector ?? DEFAULT_SELECTOR,
     acceptUnscoped: options.acceptUnscoped !== false,
     executeEntries: options.executeEntries !== false,
+    executeRenders: options.executeRenders !== false,
     fetch: options.fetch,
     baseUrl: options.baseUrl,
     MutationObserver: options.MutationObserver,
     subtree: options.subtree !== false,
     createElement: options.createElement,
     appendTo: options.appendTo,
+    renderAdapter: options.renderAdapter ?? createDefaultHTMLRenderAdapter(runtime),
     bindings: new Map(),
+    renderElements: new Set(),
+    disposed: false,
     observer: undefined,
     observerRoot: undefined,
     observerOptions: undefined,
@@ -88,6 +104,7 @@ export function createHTMLRuntime(runtime, options = {}) {
     get appendTarget() {
       return getAppendTarget(controller);
     },
+    subscribe,
     register,
     observe,
     flush,
@@ -104,25 +121,58 @@ export function createHTMLRuntime(runtime, options = {}) {
     owns,
     getModuleId,
     getElement,
+    dispose,
   };
 
   controller.api = api;
+  activeControllers.add(controller);
+  // The HTML adapter owns the global custom-element registration. Registering
+  // here means a controller is already available before any existing
+  // <solid-render> elements are upgraded/connected. The helper is idempotent.
+  registerSolidRenderElement();
+  controller.runtimeDisposeUnsubscribe = runtime.subscribe?.("runtime-disposed", () => {
+    void disposeController(controller, { runtimeDisposed: true });
+  });
   return api;
 
+  function subscribe(typesOrListener, maybeListener) {
+    return controller.events.subscribe(typesOrListener, maybeListener);
+  }
+
   /** One-shot scan of matching scripts. */
   async function register(callOptions = {}) {
     const root = getRoot(mergeOptions(controller, callOptions), "HTML runtime register");
     const selector = callOptions.selector ?? controller.selector;
-    const elements = Array.from(root.querySelectorAll(selector)).filter(element =>
-      acceptsDiscoveredElement(controller, element, callOptions),
-    );
+    const origin = callOptions.origin ?? "initial-scan";
+    const discovered = Array.from(root.querySelectorAll(selector));
+    const elements = [];
+
+    for (const element of discovered) {
+      const accepted = acceptsDiscoveredElement(controller, element, callOptions);
+      emitHTML(controller, {
+        type: "element-discovered",
+        element,
+        moduleId: nonEmpty(element?.getAttribute?.("module")),
+        origin,
+        accepted,
+      });
+      if (accepted) elements.push(element);
+    }
 
-    return processElements(controller, elements, {
-      ...callOptions,
-      root,
-      origin: callOptions.origin ?? "initial-scan",
-      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
-    });
+    try {
+      const result = await processElements(controller, elements, {
+        ...callOptions,
+        root,
+        origin,
+        executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+        executeRenders: callOptions.executeRenders ?? controller.executeRenders,
+      });
+      registerSolidRenderElement();
+      return result;
+    } catch (error) {
+      emitHTMLError(controller, "register", error, { origin });
+      throw error;
+    }
   }
 
   /**
@@ -140,6 +190,7 @@ export function createHTMLRuntime(runtime, options = {}) {
         registerExisting: callOptions.registerExisting !== false,
         initial: true,
       });
+      registerSolidRenderElement();
     } catch (error) {
       disconnect();
       throw error;
@@ -166,6 +217,10 @@ export function createHTMLRuntime(runtime, options = {}) {
     stopObserver(controller);
   }
 
+  async function dispose() {
+    await disposeController(controller, { runtimeDisposed: false });
+  }
+
   /**
    * Change the discovery/observation root. If observation is active, it is
    * rebound to the new root and existing matching scripts are registered by
@@ -174,6 +229,15 @@ export function createHTMLRuntime(runtime, options = {}) {
    */
   async function setRoot(root, callOptions = {}) {
     const nextRoot = getRoot({ root }, "HTML runtime setRoot");
+    const previousRoot = controller.root ?? globalThis.document;
+    const previousAppendTarget = getAppendTarget(controller);
+    emitHTML(controller, {
+      type: "root-changing",
+      previousRoot,
+      root: nextRoot,
+      connected: controller.connected,
+      registerExisting: callOptions.registerExisting ?? controller.connected,
+    });
 
     // Finish work scheduled against the old root before rebinding observer state.
     await controller.queue;
@@ -186,7 +250,7 @@ export function createHTMLRuntime(runtime, options = {}) {
     const wasConnected = controller.connected;
     const previousObserverOptions = controller.observerOptions ?? {};
 
-    if (wasConnected) stopObserver(controller, { preserveOptions: true });
+    if (wasConnected) stopObserver(controller, { preserveOptions: true, reason: "root-change" });
 
     controller.root = nextRoot;
     if (Object.prototype.hasOwnProperty.call(callOptions, "appendTo")) {
@@ -204,10 +268,13 @@ export function createHTMLRuntime(runtime, options = {}) {
       };
       controller.observerOptions = { ...observeOptions };
       try {
-        return await connectObserver(controller, nextRoot, observeOptions, {
+        const result = await connectObserver(controller, nextRoot, observeOptions, {
           registerExisting,
           initial: false,
+          reason: "root-change",
         });
+        emitRootChanged(controller, previousRoot, nextRoot, registerExisting, previousAppendTarget);
+        return result;
       } catch (error) {
         stopObserver(controller, { preserveOptions: true });
         throw error;
@@ -215,9 +282,12 @@ export function createHTMLRuntime(runtime, options = {}) {
     }
 
     if (registerExisting) {
-      return register({ ...callOptions, root: nextRoot });
+      const result = await register({ ...callOptions, root: nextRoot, origin: callOptions.origin ?? "root-change-scan" });
+      emitRootChanged(controller, previousRoot, nextRoot, registerExisting, previousAppendTarget);
+      return result;
     }
 
+    emitRootChanged(controller, previousRoot, nextRoot, registerExisting, previousAppendTarget);
     return emptyRegistrationResult();
   }
 
@@ -235,7 +305,15 @@ export function createHTMLRuntime(runtime, options = {}) {
     if (!target || (typeof target.append !== "function" && typeof target.appendChild !== "function")) {
       throw new TypeError("setAppendTarget() requires a target with append() or appendChild().");
     }
+    const previousTarget = getAppendTarget(controller);
     controller.appendTo = target;
+    if (previousTarget !== target) {
+      emitHTML(controller, {
+        type: "append-target-changed",
+        previousTarget,
+        target,
+      });
+    }
     return api;
   }
 
@@ -246,6 +324,7 @@ export function createHTMLRuntime(runtime, options = {}) {
       origin: callOptions.origin ?? "define-element",
       explicit: true,
       executeEntries: false,
+      executeRenders: false,
     });
     return result.modules[0] ?? definitionFromOwnedElement(controller, element);
   }
@@ -257,6 +336,7 @@ export function createHTMLRuntime(runtime, options = {}) {
       origin: callOptions.origin ?? "register-element",
       explicit: true,
       executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+      executeRenders: callOptions.executeRenders ?? controller.executeRenders,
     });
     return result.modules[0] ?? definitionFromOwnedElement(controller, element);
   }
@@ -268,6 +348,12 @@ export function createHTMLRuntime(runtime, options = {}) {
    */
   async function updateElement(element, callOptions = {}) {
     const record = requireOwnedRecord(controller, element, "updateElement");
+    emitHTML(controller, {
+      type: "element-updating",
+      element,
+      moduleId: record.moduleId,
+      origin: callOptions.origin ?? "update-element",
+    });
     const metadata = inspectElement(controller, element, {
       ...callOptions,
       existingId: record.moduleId,
@@ -285,15 +371,30 @@ export function createHTMLRuntime(runtime, options = {}) {
       ...record,
       format: metadata.format,
       entry: metadata.entry,
+      render: metadata.render,
+      component: metadata.component,
       sourceUrl: metadata.sourceUrl,
       inline: !metadata.sourceUrl,
     };
 
     const { source } = await prepareRecordSource(controller, candidate, callOptions);
+    const previousRender = record.render;
     runtime.update(record.moduleId, source, { format: candidate.format });
 
+    if (record.mount) {
+      const previousInPlace = previousRender === true;
+      const nextInPlace = candidate.render === true;
+      await disposeRecordMount(controller, record, {
+        reason: "element-update",
+        removeAnchors: previousInPlace && !nextInPlace,
+        restoreElement: previousInPlace && !nextInPlace,
+      });
+    }
+
     record.format = candidate.format;
     record.entry = candidate.entry;
+    record.render = candidate.render;
+    record.component = candidate.component;
     record.sourceUrl = candidate.sourceUrl;
     record.inline = candidate.inline;
     record.state = "defined";
@@ -301,17 +402,24 @@ export function createHTMLRuntime(runtime, options = {}) {
     record.definition = definitionFromRecord(record);
 
     if (record.entry && (callOptions.executeEntries ?? controller.executeEntries) !== false) {
-      record.state = "executing";
-      try {
-        await runtime.import(record.moduleId);
-        record.state = "ready";
-      } catch (error) {
-        record.state = "error";
-        record.error = error;
-        throw error;
-      }
+      await executeEntryRecord(controller, record, {
+        ...callOptions,
+        origin: callOptions.origin ?? "update-element",
+      });
+    } else if (record.render !== undefined && (callOptions.executeRenders ?? controller.executeRenders) !== false) {
+      await renderDeclarationRecord(controller, record, {
+        ...callOptions,
+        origin: callOptions.origin ?? "update-element",
+      });
     }
 
+    emitHTML(controller, {
+      type: "element-updated",
+      element,
+      moduleId: record.moduleId,
+      definition: record.definition,
+      origin: callOptions.origin ?? "update-element",
+    });
     return record.definition;
   }
 
@@ -322,10 +430,27 @@ export function createHTMLRuntime(runtime, options = {}) {
    */
   async function removeElement(element, callOptions = {}) {
     const record = requireOwnedRecord(controller, element, "removeElement");
+    const origin = callOptions.origin ?? "remove-element";
+    emitHTML(controller, {
+      type: "element-removing",
+      element,
+      moduleId: record.moduleId,
+      origin,
+      removeModule: callOptions.removeModule !== false,
+      removeFromDOM: callOptions.removeFromDOM !== false,
+    });
     const removeModule = callOptions.removeModule !== false;
     const removeFromDOM = callOptions.removeFromDOM !== false;
     const invalidateDependents = callOptions.invalidateDependents !== false;
 
+    if (record.mount) {
+      await disposeRecordMount(controller, record, {
+        reason: "element-remove",
+        removeAnchors: record.render === true,
+        restoreElement: record.render === true && !removeFromDOM,
+      });
+    }
+
     let moduleRemoved = false;
     if (removeModule) {
       moduleRemoved = runtime.remove(record.moduleId, { invalidateDependents });
@@ -334,22 +459,37 @@ export function createHTMLRuntime(runtime, options = {}) {
     controller.bindings.delete(record.moduleId);
     elementOwners.delete(element);
     record.state = "removed";
+    emitHTML(controller, {
+      type: "element-released",
+      element,
+      moduleId: record.moduleId,
+      origin,
+    });
 
     let elementRemoved = false;
     if (removeFromDOM) {
-      elementRemoved = removeDOMElement(element);
+      elementRemoved = record.render === true ? true : removeDOMElement(element);
     } else {
       // Keep a released element in the observed tree from being immediately
       // rediscovered. Explicit registerElement() can still claim it again.
       controller.ignoredExisting.add(element);
     }
 
-    return {
+    const result = {
       id: record.moduleId,
       element,
       moduleRemoved,
       elementRemoved,
     };
+    emitHTML(controller, {
+      type: "element-removed",
+      element,
+      moduleId: record.moduleId,
+      origin,
+      moduleRemoved,
+      elementRemoved,
+    });
+    return result;
   }
 
   /**
@@ -371,6 +511,7 @@ export function createHTMLRuntime(runtime, options = {}) {
       ...callOptions,
       origin: callOptions.origin ?? "append",
       executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+      executeRenders: callOptions.executeRenders ?? controller.executeRenders,
     });
 
     if (!claim.fresh) await claim.record.promise;
@@ -409,6 +550,9 @@ export function createHTMLRuntime(runtime, options = {}) {
     if (id) element.setAttribute("module", id);
     if (moduleOptions.src) element.setAttribute("src", String(moduleOptions.src));
     if (moduleOptions.entry) element.setAttribute("entry", "");
+    if (moduleOptions.render === true) element.setAttribute("render", "");
+    else if (typeof moduleOptions.render === "string") element.setAttribute("render", moduleOptions.render);
+    if (moduleOptions.component) element.setAttribute("component", String(moduleOptions.component));
     if (moduleOptions.language) element.setAttribute("language", String(moduleOptions.language));
     if (moduleOptions.source != null) element.textContent = String(moduleOptions.source);
 
@@ -465,6 +609,399 @@ export async function defineScript(runtime, element, options = {}) {
 export const htmlModuleSelector = DEFAULT_SELECTOR;
 export const htmlRuntimeScopeAttribute = RUNTIME_SCOPE_ATTRIBUTE;
 
+
+/**
+ * Register the global <solid-render> custom element once for the selected
+ * CustomElementRegistry. registerHTML()/observe() call this automatically in a
+ * browser; programmatic-only applications may call it explicitly.
+ */
+export function registerSolidRenderElement(options = {}) {
+  const registry = options.customElements ?? globalThis.customElements;
+  const HTMLElementBase = options.HTMLElement ?? globalThis.HTMLElement;
+  if (!registry || typeof registry.define !== "function" || typeof registry.get !== "function" || typeof HTMLElementBase !== "function") {
+    return undefined;
+  }
+
+  const existing = registry.get("solid-render");
+  if (existing) return existing;
+  const cached = solidRenderClasses.get(registry);
+  if (cached) return cached;
+
+  class SolidRenderElement extends HTMLElementBase {
+    static get observedAttributes() {
+      return ["module", "component", RUNTIME_SCOPE_ATTRIBUTE];
+    }
+
+    constructor() {
+      super();
+      solidRenderInternals.set(this, {
+        connected: false,
+        generation: 0,
+        captured: false,
+        childrenTemplate: undefined,
+        programmaticProps: {},
+        mount: undefined,
+        controller: undefined,
+        propObserver: undefined,
+      });
+    }
+
+    connectedCallback() {
+      const state = getSolidRenderState(this);
+      state.connected = true;
+      captureSolidRenderChildren(this, state);
+      startSolidRenderPropObserver(this, state);
+      void remountSolidRender(this, "connect");
+    }
+
+    disconnectedCallback() {
+      const state = getSolidRenderState(this);
+      state.connected = false;
+      state.generation += 1;
+      state.propObserver?.disconnect?.();
+      state.propObserver = undefined;
+      void disposeSolidRenderMount(this, state, "disconnect");
+    }
+
+    attributeChangedCallback(name, oldValue, newValue) {
+      if (oldValue === newValue) return;
+      const state = getSolidRenderState(this);
+      if (!state.connected) return;
+      void remountSolidRender(this, `identity:${name}`);
+    }
+
+    get props() {
+      return getSolidRenderState(this).programmaticProps;
+    }
+
+    set props(value) {
+      const state = getSolidRenderState(this);
+      state.programmaticProps = value && typeof value === "object" ? value : {};
+      updateSolidRenderProps(this, state);
+    }
+  }
+
+  registry.define("solid-render", SolidRenderElement);
+  solidRenderClasses.set(registry, SolidRenderElement);
+  return SolidRenderElement;
+}
+
+function getSolidRenderState(element) {
+  let state = solidRenderInternals.get(element);
+  if (!state) {
+    state = {
+      connected: false,
+      generation: 0,
+      captured: false,
+      childrenTemplate: undefined,
+      programmaticProps: {},
+      mount: undefined,
+      controller: undefined,
+      propObserver: undefined,
+    };
+    solidRenderInternals.set(element, state);
+  }
+  return state;
+}
+
+function captureSolidRenderChildren(element, state) {
+  if (state.captured) return;
+  state.captured = true;
+  const document = element.ownerDocument ?? globalThis.document;
+  if (!document || typeof document.createDocumentFragment !== "function") return;
+  const template = document.createDocumentFragment();
+  for (const node of Array.from(element.childNodes ?? [])) {
+    template.appendChild?.(node.cloneNode ? node.cloneNode(true) : node);
+  }
+  state.childrenTemplate = template;
+  element.replaceChildren?.();
+}
+
+function startSolidRenderPropObserver(element, state) {
+  if (state.propObserver) return;
+  let controller;
+  try {
+    controller = resolveHTMLControllerForElement(element);
+  } catch {
+    controller = undefined;
+  }
+  const MutationObserverImpl = controller?.MutationObserver ?? globalThis.MutationObserver;
+  if (typeof MutationObserverImpl !== "function") return;
+
+  const observer = new MutationObserverImpl(records => {
+    if (!Array.from(records ?? []).some(record => String(record?.attributeName ?? "").startsWith("prop:"))) return;
+    updateSolidRenderProps(element, state);
+  });
+  observer.observe(element, { attributes: true });
+  state.propObserver = observer;
+}
+
+async function remountSolidRender(element, reason) {
+  const state = getSolidRenderState(element);
+  if (!state.connected) return;
+  const generation = ++state.generation;
+  await disposeSolidRenderMount(element, state, reason === "connect" ? "reconnect" : reason);
+  if (!state.connected || generation !== state.generation) return;
+
+  let controller;
+  try {
+    controller = resolveHTMLControllerForElement(element);
+    state.controller = controller;
+    controller.renderElements.add(element);
+
+    const moduleId = nonEmpty(element.getAttribute?.("module"));
+    if (!moduleId) {
+      throw new HTMLRenderError("<solid-render> requires a `module` attribute.", { element });
+    }
+    const componentName = nonEmpty(element.getAttribute?.("component"));
+    const exportName = componentName ?? "default";
+    const props = buildSolidRenderProps(element, state);
+
+    emitHTML(controller, {
+      type: "render-mounting",
+      element,
+      moduleId,
+      component: exportName,
+      mode: "container",
+      origin: "solid-render",
+      source: "solid-render",
+    });
+
+    const namespace = await controller.runtime.import(moduleId);
+    if (!state.connected || generation !== state.generation) return;
+    const { Component } = resolveRenderComponent(namespace, componentName, {
+      moduleId,
+      element,
+    });
+
+    element.replaceChildren?.();
+    const mount = await controller.renderAdapter.mountContainer({
+      runtime: controller.runtime,
+      target: element,
+      Component,
+      props,
+      element,
+      moduleId,
+    });
+    if (!state.connected || generation !== state.generation) {
+      await mount.dispose?.();
+      return;
+    }
+
+    mount.mode = "container";
+    state.mount = mount;
+    emitHTML(controller, {
+      type: "render-mounted",
+      element,
+      moduleId,
+      component: exportName,
+      mode: "container",
+      target: element,
+      origin: "solid-render",
+      source: "solid-render",
+    });
+  } catch (error) {
+    // Identity changes or disconnects invalidate in-flight work. A stale
+    // failure belongs to the abandoned generation just like a stale success,
+    // so it must not overwrite/report against the current element state.
+    if (!state.connected || generation !== state.generation) return;
+    if (controller) {
+      emitHTMLError(controller, "solid-render", error, {
+        element,
+        moduleId: nonEmpty(element.getAttribute?.("module")),
+        origin: "solid-render",
+      });
+    }
+    dispatchSolidRenderError(element, error);
+  }
+}
+
+async function disposeSolidRenderMount(element, state, reason = "dispose") {
+  const mount = state.mount;
+  const controller = state.controller;
+  if (!mount) {
+    controller?.renderElements?.delete(element);
+    state.controller = undefined;
+    return;
+  }
+
+  const moduleId = nonEmpty(element.getAttribute?.("module"));
+  const component = nonEmpty(element.getAttribute?.("component")) ?? "default";
+  if (controller) {
+    emitHTML(controller, {
+      type: "render-disposing",
+      element,
+      moduleId,
+      component,
+      mode: "container",
+      reason,
+      source: "solid-render",
+      origin: "solid-render",
+    });
+  }
+
+  try {
+    await mount.dispose?.();
+  } finally {
+    state.mount = undefined;
+    element.replaceChildren?.();
+    controller?.renderElements?.delete(element);
+    state.controller = undefined;
+  }
+
+  if (controller) {
+    emitHTML(controller, {
+      type: "render-disposed",
+      element,
+      moduleId,
+      component,
+      mode: "container",
+      reason,
+      source: "solid-render",
+      origin: "solid-render",
+    });
+  }
+}
+
+function updateSolidRenderProps(element, state) {
+  if (!state.mount?.updateProps) return;
+  state.mount.updateProps(buildSolidRenderProps(element, state));
+}
+
+function buildSolidRenderProps(element, state) {
+  const declarative = {};
+  for (const attribute of Array.from(element.attributes ?? [])) {
+    const name = String(attribute?.name ?? "").toLowerCase();
+    if (!name.startsWith("prop:")) continue;
+    const key = kebabToCamel(name.slice(5));
+    if (!key) continue;
+    declarative[key] = attribute.value === "" ? true : attribute.value;
+  }
+
+  if (state.childrenTemplate && !("children" in (state.programmaticProps ?? {}))) {
+    Object.defineProperty(declarative, "children", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return state.childrenTemplate.cloneNode?.(true) ?? state.childrenTemplate;
+      },
+    });
+  }
+
+  const merged = Object.create(null);
+  for (const key of Reflect.ownKeys(declarative)) {
+    const descriptor = Object.getOwnPropertyDescriptor(declarative, key);
+    if (descriptor) Object.defineProperty(merged, key, descriptor);
+  }
+  for (const key of Reflect.ownKeys(state.programmaticProps ?? {})) {
+    merged[key] = state.programmaticProps[key];
+  }
+  return merged;
+}
+
+function kebabToCamel(value) {
+  return String(value).replace(/-([a-z0-9])/g, (_match, character) => character.toUpperCase());
+}
+
+function resolveHTMLControllerForElement(element) {
+  const scope = nonEmpty(element.getAttribute?.(RUNTIME_SCOPE_ATTRIBUTE));
+  const live = [...activeControllers].filter(controller => !controller.disposed);
+  let candidates = scope
+    ? live.filter(controller => controller.scope === scope)
+    : live.filter(controller => !controller.scope);
+
+  if (!scope && candidates.length === 0 && live.length === 1) candidates = live;
+  const contained = candidates.filter(controller => rootContainsElement(controller.root ?? globalThis.document, element));
+  if (contained.length === 1) return contained[0];
+  if (contained.length > 1) {
+    const specific = mostSpecificController(contained);
+    if (specific) return specific;
+  }
+  if (candidates.length === 1) return candidates[0];
+
+  if (candidates.length === 0) {
+    throw new HTMLRenderError(
+      scope
+        ? `No HTML runtime is registered for data-solid-runtime=${JSON.stringify(scope)}.`
+        : "No unambiguous HTML runtime is available for <solid-render>. Add data-solid-runtime when multiple runtimes exist.",
+      { element },
+    );
+  }
+
+  throw new HTMLRenderError(
+    `Multiple HTML runtimes match <solid-render>${scope ? ` for scope ${JSON.stringify(scope)}` : ""}. Use distinct scopes or DOM roots.`,
+    { element },
+  );
+}
+
+function rootContainsElement(root, element) {
+  if (!root || !element) return false;
+  if (root === element) return true;
+  if (typeof root.contains === "function") return root.contains(element);
+  let node = element.parentNode;
+  while (node) {
+    if (node === root) return true;
+    node = node.parentNode;
+  }
+  return false;
+}
+
+function mostSpecificController(controllers) {
+  for (const candidate of controllers) {
+    const root = candidate.root ?? globalThis.document;
+    if (controllers.every(other => {
+      if (other === candidate) return true;
+      const otherRoot = other.root ?? globalThis.document;
+      return !rootContainsElement(root, otherRoot);
+    })) return candidate;
+  }
+  return undefined;
+}
+
+function dispatchSolidRenderError(element, error) {
+  try {
+    const EventImpl = globalThis.CustomEvent;
+    if (typeof element?.dispatchEvent === "function" && typeof EventImpl === "function") {
+      element.dispatchEvent(new EventImpl("solid-render-error", {
+        detail: { error },
+        bubbles: false,
+        composed: false,
+      }));
+    }
+  } catch {
+    // Error reporting must not create a second failure.
+  }
+  globalThis.console?.error?.("solid-tag-runtime <solid-render> error", error);
+}
+
+async function disposeController(controller, options = {}) {
+  if (controller.disposed) return;
+  controller.disposed = true;
+  stopObserver(controller, { reason: options.runtimeDisposed ? "runtime-disposed" : "controller-disposed" });
+
+  for (const record of controller.bindings.values()) {
+    if (record.mount) {
+      await disposeRecordMount(controller, record, {
+        reason: options.runtimeDisposed ? "runtime-disposed" : "controller-disposed",
+        removeAnchors: record.render === true,
+        restoreElement: record.render === true,
+      });
+    }
+  }
+
+  for (const element of [...controller.renderElements]) {
+    const state = solidRenderInternals.get(element);
+    if (!state || state.controller !== controller) continue;
+    state.generation += 1;
+    await disposeSolidRenderMount(element, state, options.runtimeDisposed ? "runtime-disposed" : "controller-disposed");
+  }
+
+  activeControllers.delete(controller);
+  controller.runtimeDisposeUnsubscribe?.();
+  controller.runtimeDisposeUnsubscribe = undefined;
+  controller.events.clear();
+}
+
 async function connectObserver(controller, root, callOptions = {}, mode = {}) {
   const MutationObserverImpl = callOptions.MutationObserver ?? controller.MutationObserver ?? globalThis.MutationObserver;
 
@@ -497,6 +1034,13 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
     childList: true,
     subtree: callOptions.subtree ?? controller.subtree,
   });
+  emitHTML(controller, {
+    type: "observer-connected",
+    root,
+    subtree: callOptions.subtree ?? controller.subtree,
+    registerExisting,
+    reason: mode.reason ?? (mode.initial ? "observe" : "connect"),
+  });
 
   const result = registerExisting
     ? await enqueueObserverScan(controller, {
@@ -511,11 +1055,17 @@ async function connectObserver(controller, root, callOptions = {}, mode = {}) {
 
 function stopObserver(controller, options = {}) {
   if (!controller.connected && !controller.observer) return;
+  const root = controller.observerRoot;
   controller.connected = false;
   controller.observer?.disconnect();
   controller.observer = undefined;
   controller.observerRoot = undefined;
   if (!options.preserveOptions) controller.observerOptions = undefined;
+  emitHTML(controller, {
+    type: "observer-disconnected",
+    root,
+    reason: options.reason ?? "disconnect",
+  });
 }
 
 async function enqueueObserverScan(controller, callOptions = {}) {
@@ -524,23 +1074,79 @@ async function enqueueObserverScan(controller, callOptions = {}) {
 
     const root = controller.observerRoot ?? getRoot(mergeOptions(controller, callOptions), "HTML runtime observer");
     const selector = callOptions.selector ?? controller.selector;
-    const elements = Array.from(root.querySelectorAll(selector)).filter(element => {
-      if (controller.ignoredExisting.has(element)) return false;
-      if (!acceptsDiscoveredElement(controller, element, callOptions)) return false;
+    const origin = callOptions.origin ?? "observer";
+    const discovered = Array.from(root.querySelectorAll(selector));
+    const elements = [];
+    let matched = 0;
+    let ignored = 0;
+
+    for (const element of discovered) {
+      if (controller.ignoredExisting.has(element)) {
+        ignored += 1;
+        emitHTML(controller, {
+          type: "element-discovered",
+          element,
+          moduleId: nonEmpty(element?.getAttribute?.("module")),
+          origin,
+          accepted: false,
+        });
+        continue;
+      }
+
+      const accepted = acceptsDiscoveredElement(controller, element, callOptions);
+      emitHTML(controller, {
+        type: "element-discovered",
+        element,
+        moduleId: nonEmpty(element?.getAttribute?.("module")),
+        origin,
+        accepted,
+      });
+      if (!accepted) {
+        ignored += 1;
+        continue;
+      }
+      matched += 1;
 
       const ownership = elementOwners.get(element);
-      if (!ownership) return true;
-      if (ownership.owner === controller) return false;
+      if (!ownership) {
+        elements.push(element);
+        continue;
+      }
+      if (ownership.owner === controller) {
+        ignored += 1;
+        continue;
+      }
 
       throw ownershipError(controller, element, ownership);
-    });
+    }
 
-    return processElements(controller, elements, {
-      ...callOptions,
+    let result;
+    try {
+      result = await processElements(controller, elements, {
+        ...callOptions,
+        root,
+        origin,
+        executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+        executeRenders: callOptions.executeRenders ?? controller.executeRenders,
+      });
+    } catch (error) {
+      emitHTMLError(controller, "observer", error, { origin });
+      throw error;
+    }
+
+    await cleanupDetachedRenderedDeclarations(controller, root);
+
+    emitHTML(controller, {
+      type: "observer-batch",
       root,
-      origin: callOptions.origin ?? "observer",
-      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+      origin,
+      discovered: discovered.length,
+      matched,
+      claimed: result.modules.length,
+      ignored,
+      modules: result.modules.map(module => module.id),
     });
+    return result;
   });
 
   controller.queue = task.then(
@@ -587,6 +1193,12 @@ async function processClaims(controller, records, options = {}) {
   try {
     prepared = await Promise.all(records.map(record => prepareRecordSource(controller, record, options)));
   } catch (error) {
+    const failed = records.find(record => record.state === "loading") ?? records[0];
+    emitHTMLError(controller, failed?.sourceUrl ? "fetch" : "register", error, {
+      element: failed?.element,
+      moduleId: failed?.moduleId,
+      origin: failed?.origin ?? options.origin,
+    });
     for (const record of records) rejectRecord(record, error);
     throw error;
   }
@@ -604,8 +1216,21 @@ async function processClaims(controller, records, options = {}) {
       record.definition = definitionFromRecord(record);
       record.resolve(record.definition);
       modules.push(record.definition);
+      emitHTML(controller, {
+        type: "element-registered",
+        element: record.element,
+        moduleId: record.moduleId,
+        definition: record.definition,
+        origin: record.origin,
+      });
     }
   } catch (error) {
+    const failed = records.find(record => record.state === "claimed" || record.state === "loading") ?? records[0];
+    emitHTMLError(controller, "register", error, {
+      element: failed?.element,
+      moduleId: failed?.moduleId,
+      origin: failed?.origin ?? options.origin,
+    });
     for (const record of records) {
       if (record.state === "claimed" || record.state === "loading") rejectRecord(record, error);
     }
@@ -613,34 +1238,324 @@ async function processClaims(controller, records, options = {}) {
   }
 
   const entries = modules.filter(module => module.entry);
+  const renders = modules.filter(module => module.render !== undefined);
   const executed = [];
+  const rendered = [];
 
-  if (options.executeEntries !== false) {
-    for (const entry of entries) {
-      const record = elementOwners.get(entry.element);
-      if (record) record.state = "executing";
+  // Every module in the batch is defined before any side-effect entry or render
+  // action executes. This keeps document ordering independent from imports.
+  for (const module of modules) {
+    const record = elementOwners.get(module.element);
+    if (!record) continue;
 
-      try {
-        const namespace = await controller.runtime.import(entry.id);
-        if (record) record.state = "ready";
-        executed.push({ id: entry.id, namespace });
-      } catch (error) {
-        if (record) {
-          record.state = "error";
-          record.error = error;
-        }
-        throw error;
-      }
+    if (record.entry && options.executeEntries !== false) {
+      executed.push(await executeEntryRecord(controller, record, options));
+      continue;
+    }
+
+    if (record.render !== undefined && options.executeRenders !== false) {
+      rendered.push(await renderDeclarationRecord(controller, record, options));
     }
   }
 
+  registerSolidRenderElement();
   return {
     modules,
     entries: entries.map(entry => entry.id),
     executed,
+    renders: renders.map(render => render.id),
+    rendered,
   };
 }
 
+
+async function executeEntryRecord(controller, record, options = {}) {
+  record.state = "executing";
+  const origin = record.origin ?? options.origin ?? "entry";
+  try {
+    emitHTML(controller, {
+      type: "entry-executing",
+      element: record.element,
+      moduleId: record.moduleId,
+      origin,
+    });
+    const namespace = await controller.runtime.import(record.moduleId);
+    record.state = "ready";
+    emitHTML(controller, {
+      type: "entry-executed",
+      element: record.element,
+      moduleId: record.moduleId,
+      namespace,
+      origin,
+    });
+    return { id: record.moduleId, namespace };
+  } catch (error) {
+    record.state = "error";
+    record.error = error;
+    emitHTMLError(controller, "entry", error, {
+      element: record.element,
+      moduleId: record.moduleId,
+      origin,
+    });
+    throw error;
+  }
+}
+
+async function renderDeclarationRecord(controller, record, options = {}) {
+  const origin = record.origin ?? options.origin ?? "render";
+  const mode = record.render === true ? "in-place" : "selector";
+  const exportName = record.component ?? "default";
+
+  emitHTML(controller, {
+    type: "render-mounting",
+    element: record.element,
+    moduleId: record.moduleId,
+    component: exportName,
+    mode,
+    origin,
+    source: "script-render",
+  });
+
+  try {
+    if (record.mount) {
+      await disposeRecordMount(controller, record, {
+        reason: "remount",
+        removeAnchors: false,
+      });
+    }
+
+    const namespace = await controller.runtime.import(record.moduleId);
+    const { Component } = resolveRenderComponent(namespace, record.component, {
+      moduleId: record.moduleId,
+      element: record.element,
+    });
+
+    let mount;
+    if (mode === "selector") {
+      const target = resolveRenderTarget(controller, record.element, record.render, options);
+      mount = await controller.renderAdapter.mountContainer({
+        runtime: controller.runtime,
+        target,
+        Component,
+        props: {},
+        element: record.element,
+        moduleId: record.moduleId,
+      });
+      mount.mode = "selector";
+      mount.renderTarget = record.render;
+      mount.target = target;
+    } else {
+      const range = ensureInPlaceRange(record);
+      mount = await controller.renderAdapter.mountRange({
+        runtime: controller.runtime,
+        parent: range.parent,
+        before: range.endMarker,
+        startMarker: range.startMarker,
+        endMarker: range.endMarker,
+        Component,
+        props: {},
+        element: record.element,
+        moduleId: record.moduleId,
+      });
+      mount.mode = "in-place";
+      mount.range = range;
+    }
+
+    record.mount = mount;
+    record.state = "ready";
+    const result = {
+      id: record.moduleId,
+      namespace,
+      component: exportName,
+      mode,
+      target: mount.target,
+      element: record.element,
+    };
+    emitHTML(controller, {
+      type: "render-mounted",
+      element: record.element,
+      moduleId: record.moduleId,
+      component: exportName,
+      mode,
+      target: mount.target,
+      origin,
+      source: "script-render",
+    });
+    return result;
+  } catch (error) {
+    record.state = "error";
+    record.error = error;
+    emitHTMLError(controller, "render", error, {
+      element: record.element,
+      moduleId: record.moduleId,
+      origin,
+    });
+    throw error;
+  }
+}
+
+async function disposeRecordMount(controller, record, options = {}) {
+  const mount = record?.mount;
+  if (!mount) return false;
+  const mode = mount.mode ?? (record.render === true ? "in-place" : "selector");
+  emitHTML(controller, {
+    type: "render-disposing",
+    element: record.element,
+    moduleId: record.moduleId,
+    component: record.component ?? "default",
+    mode,
+    reason: options.reason ?? "dispose",
+    source: "script-render",
+    origin: record.origin ?? "render",
+  });
+
+  try {
+    await mount.dispose?.();
+  } finally {
+    if (mode === "in-place" && options.removeAnchors !== false) {
+      removeRangeAnchors(record, { restoreElement: options.restoreElement === true });
+    }
+    record.mount = undefined;
+  }
+
+  emitHTML(controller, {
+    type: "render-disposed",
+    element: record.element,
+    moduleId: record.moduleId,
+    component: record.component ?? "default",
+    mode,
+    reason: options.reason ?? "dispose",
+    source: "script-render",
+    origin: record.origin ?? "render",
+  });
+  return true;
+}
+
+function resolveRenderTarget(controller, element, selector, options = {}) {
+  if (typeof selector !== "string" || !selector) {
+    throw new HTMLRenderError("Selector rendering requires a non-empty render selector.", {
+      moduleId: elementOwners.get(element)?.moduleId,
+      element,
+    });
+  }
+
+  const root = options.renderRoot
+    ?? options.root
+    ?? controller.root
+    ?? element.ownerDocument
+    ?? globalThis.document;
+
+  if (!root || typeof root.querySelectorAll !== "function") {
+    throw new HTMLRenderError(`Cannot resolve render target ${JSON.stringify(selector)} without a queryable DOM root.`, {
+      moduleId: elementOwners.get(element)?.moduleId,
+      element,
+    });
+  }
+
+  let target;
+  try {
+    if (typeof root.querySelector === "function") target = root.querySelector(selector);
+    else target = Array.from(root.querySelectorAll(selector))[0];
+  } catch (cause) {
+    throw new HTMLRenderError(`Invalid render selector ${JSON.stringify(selector)}.`, {
+      cause,
+      moduleId: elementOwners.get(element)?.moduleId,
+      element,
+    });
+  }
+
+  if (!target) {
+    throw new HTMLRenderError(`Render target ${JSON.stringify(selector)} was not found.`, {
+      moduleId: elementOwners.get(element)?.moduleId,
+      element,
+    });
+  }
+  return target;
+}
+
+function ensureInPlaceRange(record) {
+  if (record.range?.startMarker?.parentNode && record.range?.endMarker?.parentNode) {
+    return record.range;
+  }
+
+  const element = record.element;
+  const parent = element?.parentNode;
+  if (!parent) {
+    throw new HTMLRenderError("In-place rendering requires the declaration script to have a parent node.", {
+      moduleId: record.moduleId,
+      element,
+    });
+  }
+
+  const document = element.ownerDocument ?? globalThis.document;
+  if (!document || typeof document.createComment !== "function") {
+    throw new HTMLRenderError("In-place rendering requires document.createComment().", {
+      moduleId: record.moduleId,
+      element,
+    });
+  }
+
+  const startMarker = document.createComment("solid-runtime:start");
+  const endMarker = document.createComment("solid-runtime:end");
+
+  if (typeof element.replaceWith === "function") {
+    element.replaceWith(startMarker, endMarker);
+  } else if (typeof parent.insertBefore === "function" && typeof parent.removeChild === "function") {
+    parent.insertBefore(startMarker, element);
+    parent.insertBefore(endMarker, element);
+    parent.removeChild(element);
+  } else {
+    throw new HTMLRenderError("In-place rendering requires replaceWith() or insertBefore()/removeChild() support.", {
+      moduleId: record.moduleId,
+      element,
+    });
+  }
+
+  record.range = { parent, startMarker, endMarker };
+  return record.range;
+}
+
+function removeRangeAnchors(record, options = {}) {
+  const range = record.range;
+  if (!range) return;
+  const { parent, startMarker, endMarker } = range;
+
+  if (options.restoreElement && parent && startMarker?.parentNode === parent) {
+    if (typeof parent.insertBefore === "function") parent.insertBefore(record.element, startMarker);
+  }
+
+  clearNodesBetween(startMarker, endMarker);
+  startMarker?.parentNode?.removeChild?.(startMarker);
+  endMarker?.parentNode?.removeChild?.(endMarker);
+  record.range = undefined;
+}
+
+function clearNodesBetween(start, end) {
+  if (!start || !end) return;
+  let node = start.nextSibling;
+  while (node && node !== end) {
+    const next = node.nextSibling;
+    node.parentNode?.removeChild?.(node);
+    node = next;
+  }
+}
+
+async function cleanupDetachedRenderedDeclarations(controller, root) {
+  if (!root || typeof root.contains !== "function") return;
+  for (const record of controller.bindings.values()) {
+    if (!record.mount) continue;
+    const anchor = record.mount.mode === "in-place"
+      ? record.range?.startMarker
+      : record.element;
+    if (anchor && !root.contains(anchor)) {
+      await disposeRecordMount(controller, record, {
+        reason: "declaration-detached",
+        removeAnchors: false,
+      });
+    }
+  }
+}
+
 function claimElement(controller, element, options = {}) {
   assertElement(element, options.origin ?? "HTML runtime");
 
@@ -688,8 +1603,12 @@ function claimElement(controller, element, options = {}) {
     moduleId,
     format: metadata.format,
     entry: metadata.entry,
+    render: metadata.render,
+    component: metadata.component,
     sourceUrl: metadata.sourceUrl,
     inline: !metadata.sourceUrl,
+    mount: undefined,
+    range: undefined,
     state: "claimed",
     origin: options.origin ?? "unknown",
     promise,
@@ -701,6 +1620,17 @@ function claimElement(controller, element, options = {}) {
 
   elementOwners.set(element, record);
   controller.bindings.set(moduleId, record);
+  emitHTML(controller, {
+    type: "element-claimed",
+    element,
+    moduleId,
+    format: record.format,
+    entry: record.entry,
+    render: record.render,
+    component: record.component,
+    sourceUrl: record.sourceUrl,
+    origin: record.origin,
+  });
   return { fresh: true, record };
 }
 
@@ -709,12 +1639,29 @@ async function prepareRecordSource(controller, record, options) {
 
   let source;
   if (record.sourceUrl) {
+    const startedAt = performanceNow();
+    emitHTML(controller, {
+      type: "element-loading",
+      element: record.element,
+      moduleId: record.moduleId,
+      sourceUrl: record.sourceUrl,
+      origin: record.origin,
+    });
     source = await fetchSource(
       record.sourceUrl,
       options.fetch ?? controller.fetch ?? globalThis.fetch,
       record.element,
       record.moduleId,
     );
+    emitHTML(controller, {
+      type: "element-loaded",
+      element: record.element,
+      moduleId: record.moduleId,
+      sourceUrl: record.sourceUrl,
+      origin: record.origin,
+      bytes: String(source).length,
+      durationMs: performanceNow() - startedAt,
+    });
   } else {
     source = record.element.textContent ?? "";
   }
@@ -725,6 +1672,14 @@ async function prepareRecordSource(controller, record, options) {
 function inspectElement(controller, element, options = {}) {
   const type = normalizeType(element.getAttribute("type"));
   const entry = hasAttribute(element, "entry");
+  const render = inspectRenderAttribute(element);
+  const component = nonEmpty(element.getAttribute("component"));
+  if (entry && render !== undefined) {
+    throw new HTMLModuleError(
+      "Runtime script declarations cannot combine `entry` and `render`. Use separate declarations for side effects and UI mounting.",
+      { element },
+    );
+  }
   const srcAttribute = nonEmpty(element.getAttribute("src"));
   const explicitId = nonEmpty(element.getAttribute("module"));
   const baseUrl = options.baseUrl
@@ -742,15 +1697,16 @@ function inspectElement(controller, element, options = {}) {
     sourceUrl,
   });
 
-  const id = explicitId ?? sourceUrl ?? (entry ? options.existingId ?? createAnonymousId(format) : undefined);
+  const action = entry ? "entry" : render !== undefined ? "render" : undefined;
+  const id = explicitId ?? sourceUrl ?? (action ? options.existingId ?? createAnonymousId(format, action) : undefined);
   if (!id) {
     throw new HTMLModuleError(
-      "Inline solid runtime module scripts require a `module` attribute unless they are marked `entry`.",
+      "Inline solid runtime module scripts require a `module` attribute unless they are marked `entry` or `render`.",
       { element },
     );
   }
 
-  return { id, format, entry, sourceUrl };
+  return { id, format, entry, render, component, sourceUrl };
 }
 
 function requireOwnedRecord(controller, element, caller) {
@@ -787,6 +1743,8 @@ function definitionFromRecord(record) {
     id: record.moduleId,
     format: record.format,
     entry: record.entry,
+    render: record.render,
+    component: record.component,
     sourceUrl: record.sourceUrl,
     inline: record.inline,
     element: record.element,
@@ -863,6 +1821,46 @@ function ownershipError(controller, element, ownership) {
   );
 }
 
+function emitHTML(controller, event) {
+  controller.events.emit({
+    htmlRuntimeId: controller.id,
+    scope: controller.scope,
+    timestamp: Date.now(),
+    ...event,
+  });
+}
+
+function emitHTMLError(controller, operation, error, context = {}) {
+  emitHTML(controller, {
+    type: "html-error",
+    operation,
+    error,
+    ...context,
+  });
+}
+
+function emitRootChanged(controller, previousRoot, root, registerExisting, previousAppendTarget) {
+  emitHTML(controller, {
+    type: "root-changed",
+    previousRoot,
+    root,
+    registerExisting,
+    connected: controller.connected,
+  });
+  const nextAppendTarget = getAppendTarget(controller);
+  if (previousAppendTarget !== nextAppendTarget) {
+    emitHTML(controller, {
+      type: "append-target-changed",
+      previousTarget: previousAppendTarget,
+      target: nextAppendTarget,
+    });
+  }
+}
+
+function performanceNow() {
+  return globalThis.performance?.now?.() ?? Date.now();
+}
+
 function getDefaultController(runtime, options = {}) {
   assertRuntime(runtime);
   let controller = defaultControllers.get(runtime);
@@ -871,6 +1869,7 @@ function getDefaultController(runtime, options = {}) {
       root: options.root,
       selector: options.selector,
       executeEntries: options.executeEntries,
+      executeRenders: options.executeRenders,
       fetch: options.fetch,
       baseUrl: options.baseUrl,
       MutationObserver: options.MutationObserver,
@@ -923,6 +1922,7 @@ function mergeOptions(controller, options) {
     root: options.root ?? controller.root,
     selector: options.selector ?? controller.selector,
     executeEntries: options.executeEntries ?? controller.executeEntries,
+    executeRenders: options.executeRenders ?? controller.executeRenders,
     fetch: options.fetch ?? controller.fetch,
     baseUrl: options.baseUrl ?? controller.baseUrl,
     MutationObserver: options.MutationObserver ?? controller.MutationObserver,
@@ -937,6 +1937,8 @@ function emptyRegistrationResult() {
     modules: [],
     entries: [],
     executed: [],
+    renders: [],
+    rendered: [],
   };
 }
 
@@ -1037,9 +2039,15 @@ function resolveSourceUrl(src, baseUrl) {
   }
 }
 
-function createAnonymousId(format) {
+function createAnonymousId(format, kind = "entry") {
   const extension = format === "js" ? "js" : "jsx";
-  return `/__solid_tag_runtime__/html-entry-${++anonymousSequence}.${extension}`;
+  return `/__solid_tag_runtime__/html-${kind}-${++anonymousSequence}.${extension}`;
+}
+
+function inspectRenderAttribute(element) {
+  if (!hasAttribute(element, "render")) return undefined;
+  const value = element.getAttribute("render");
+  return value == null || value === "" ? true : String(value);
 }
 
 function stripQueryAndHash(value) {