solid-tag-runtime 0.0.8 → 0.0.11

package/src/html.js

@@ -1,5 +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"]',
@@ -13,6 +14,10 @@ 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();
+const unresolvedRenderScopeWarnings = new WeakMap();
 let anonymousSequence = 0;
 let controllerSequence = 0;
 
@@ -35,6 +40,8 @@ export class HTMLModuleOwnershipError extends HTMLModuleError {
   }
 }
 
+export { HTMLRenderError };
+
 /**
  * Create a persistent DOM/HTML adapter for one solid-tag-runtime instance.
  *
@@ -58,13 +65,17 @@ export function createHTMLRuntime(runtime, options = {}) {
     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,
@@ -111,9 +122,18 @@ 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) {
@@ -138,15 +158,19 @@ export function createHTMLRuntime(runtime, options = {}) {
         accepted,
       });
       if (accepted) elements.push(element);
+      else maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
     }
 
     try {
-      return await processElements(controller, elements, {
+      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;
@@ -168,6 +192,7 @@ export function createHTMLRuntime(runtime, options = {}) {
         registerExisting: callOptions.registerExisting !== false,
         initial: true,
       });
+      registerSolidRenderElement();
     } catch (error) {
       disconnect();
       throw error;
@@ -194,6 +219,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
@@ -297,6 +326,7 @@ export function createHTMLRuntime(runtime, options = {}) {
       origin: callOptions.origin ?? "define-element",
       explicit: true,
       executeEntries: false,
+      executeRenders: false,
     });
     return result.modules[0] ?? definitionFromOwnedElement(controller, element);
   }
@@ -308,6 +338,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);
   }
@@ -342,15 +373,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";
@@ -358,33 +404,15 @@ export function createHTMLRuntime(runtime, options = {}) {
     record.definition = definitionFromRecord(record);
 
     if (record.entry && (callOptions.executeEntries ?? controller.executeEntries) !== false) {
-      record.state = "executing";
-      emitHTML(controller, {
-        type: "entry-executing",
-        element,
-        moduleId: record.moduleId,
+      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",
       });
-      try {
-        const namespace = await runtime.import(record.moduleId);
-        record.state = "ready";
-        emitHTML(controller, {
-          type: "entry-executed",
-          element,
-          moduleId: record.moduleId,
-          namespace,
-          origin: callOptions.origin ?? "update-element",
-        });
-      } catch (error) {
-        record.state = "error";
-        record.error = error;
-        emitHTMLError(controller, "entry", error, {
-          element,
-          moduleId: record.moduleId,
-          origin: callOptions.origin ?? "update-element",
-        });
-        throw error;
-      }
     }
 
     emitHTML(controller, {
@@ -417,6 +445,14 @@ export function createHTMLRuntime(runtime, options = {}) {
     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 });
@@ -434,7 +470,7 @@ export function createHTMLRuntime(runtime, options = {}) {
 
     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.
@@ -477,6 +513,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;
@@ -515,6 +552,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);
 
@@ -571,6 +611,424 @@ 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);
+
+  // <solid-render> must use the same routing semantics as discovered script
+  // declarations. In particular, an unscoped element may be handled by a
+  // scoped controller when that controller accepts unscoped declarations.
+  // Root containment is also authoritative: never fall back to a controller
+  // outside the element's DOM boundary merely because it is the only candidate.
+  const candidates = live.filter(controller => {
+    if (scope) return controller.scope === scope;
+    return controller.scope ? controller.acceptUnscoped !== false : true;
+  });
+  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 (contained.length === 0) {
+    if (scope) {
+      if (candidates.length === 0) {
+        throw new HTMLRenderError(
+          `No HTML runtime is registered for data-solid-runtime=${JSON.stringify(scope)}.`,
+          { element },
+        );
+      }
+      throw new HTMLRenderError(
+        `HTML runtime scope ${JSON.stringify(scope)} is registered, but no matching controller root contains this <solid-render> element.`,
+        { element },
+      );
+    }
+
+    if (candidates.length === 0) {
+      throw new HTMLRenderError(
+        "No HTML runtime accepts this unscoped <solid-render>. Add data-solid-runtime or enable acceptUnscoped on the intended controller.",
+        { element },
+      );
+    }
+
+    throw new HTMLRenderError(
+      "No HTML runtime that accepts unscoped declarations has a root containing this <solid-render> element.",
+      { element },
+    );
+  }
+
+  throw new HTMLRenderError(
+    `Multiple HTML runtimes match <solid-render>${scope ? ` for scope ${JSON.stringify(scope)}` : ""}. Use data-solid-runtime, distinct scopes, or non-overlapping 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;
 
@@ -672,6 +1130,7 @@ async function enqueueObserverScan(controller, callOptions = {}) {
       });
       if (!accepted) {
         ignored += 1;
+        maybeWarnUnresolvedRenderScope(controller, element, callOptions, origin);
         continue;
       }
       matched += 1;
@@ -696,12 +1155,15 @@ async function enqueueObserverScan(controller, 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,
@@ -804,52 +1266,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 {
-        emitHTML(controller, {
-          type: "entry-executing",
-          element: entry.element,
-          moduleId: entry.id,
-          origin: record?.origin ?? options.origin ?? "entry",
-        });
-        const namespace = await controller.runtime.import(entry.id);
-        if (record) record.state = "ready";
-        executed.push({ id: entry.id, namespace });
-        emitHTML(controller, {
-          type: "entry-executed",
-          element: entry.element,
-          moduleId: entry.id,
-          namespace,
-          origin: record?.origin ?? options.origin ?? "entry",
-        });
-      } catch (error) {
-        if (record) {
-          record.state = "error";
-          record.error = error;
-        }
-        emitHTMLError(controller, "entry", error, {
-          element: entry.element,
-          moduleId: entry.id,
-          origin: record?.origin ?? options.origin ?? "entry",
-        });
-        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");
 
@@ -897,8 +1631,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,
@@ -916,6 +1654,8 @@ function claimElement(controller, element, options = {}) {
     moduleId,
     format: record.format,
     entry: record.entry,
+    render: record.render,
+    component: record.component,
     sourceUrl: record.sourceUrl,
     origin: record.origin,
   });
@@ -960,6 +1700,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
@@ -977,15 +1725,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) {
@@ -1022,6 +1771,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,
@@ -1055,6 +1806,52 @@ function acceptsDiscoveredElement(controller, element, options = {}) {
   return !elementScope;
 }
 
+function maybeWarnUnresolvedRenderScope(controller, element, options = {}, origin = "discover") {
+  if ((options.executeRenders ?? controller.executeRenders) === false) return false;
+  if (!hasAttribute(element, "render")) return false;
+
+  const requestedScope = nonEmpty(element?.getAttribute?.(RUNTIME_SCOPE_ATTRIBUTE));
+  if (!requestedScope) return false;
+
+  const live = [...activeControllers].filter(candidate => !candidate.disposed);
+  const matchingScopeControllers = live.filter(candidate => candidate.scope === requestedScope);
+  const handlingController = matchingScopeControllers.find(candidate =>
+    rootContainsElement(candidate.root ?? globalThis.document, element)
+  );
+  if (handlingController) return false;
+
+  if (unresolvedRenderScopeWarnings.get(element) === requestedScope) return false;
+  unresolvedRenderScopeWarnings.set(element, requestedScope);
+
+  const registeredScopes = [...new Set(live.map(candidate => candidate.scope).filter(Boolean))].sort();
+  const moduleId = nonEmpty(element?.getAttribute?.("module"));
+  const scopeLabel = JSON.stringify(requestedScope);
+  const moduleLabel = moduleId ? ` module=${JSON.stringify(moduleId)}` : "";
+  const message = matchingScopeControllers.length > 0
+    ? `solid-tag-runtime/html: Unable to render <script${moduleLabel}> for data-solid-runtime=${scopeLabel} because matching HTML runtime controller(s) exist, but none has a root containing this declaration.`
+    : `solid-tag-runtime/html: Unable to render <script${moduleLabel}> because data-solid-runtime=${scopeLabel} does not match any registered HTML runtime.`;
+
+  emitHTML(controller, {
+    type: "html-warning",
+    code: "unresolved-runtime-scope",
+    operation: "render",
+    message,
+    element,
+    moduleId,
+    requestedScope,
+    registeredScopes,
+    matchingScopeRegistered: matchingScopeControllers.length > 0,
+    origin,
+  });
+
+  globalThis.console?.warn?.(message, {
+    element,
+    requestedScope,
+    registeredScopes,
+  });
+  return true;
+}
+
 function assertExplicitScopeCompatibility(controller, element, options = {}) {
   const requestedScope = normalizeScope(options.scope ?? controller.scope);
   const elementScope = nonEmpty(element.getAttribute(RUNTIME_SCOPE_ATTRIBUTE));
@@ -1146,6 +1943,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,
@@ -1198,6 +1996,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,
@@ -1212,6 +2011,8 @@ function emptyRegistrationResult() {
     modules: [],
     entries: [],
     executed: [],
+    renders: [],
+    rendered: [],
   };
 }
 
@@ -1312,9 +2113,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) {