solid-tag-runtime 0.0.2 → 0.0.3

package/src/html.js

@@ -9,7 +9,11 @@ const DEFAULT_SELECTOR = [
   'script[type="text/solid-module"]',
 ].join(",");
 
+const RUNTIME_SCOPE_ATTRIBUTE = "data-solid-runtime";
+const elementOwners = new WeakMap();
+const defaultControllers = new WeakMap();
 let anonymousSequence = 0;
+let controllerSequence = 0;
 
 export class HTMLModuleError extends SolidTagRuntimeError {
   constructor(message, options = {}) {
@@ -21,165 +25,522 @@ export class HTMLModuleError extends SolidTagRuntimeError {
   }
 }
 
-/**
- * Discover runtime module scripts under a Document/Element-like root, define
- * all of them first, then optionally execute scripts marked with `entry`.
- */
-export async function registerHTML(runtime, options = {}) {
-  assertRuntime(runtime);
-
-  const root = getRoot(options, "registerHTML");
-  const elements = Array.from(root.querySelectorAll(options.selector ?? DEFAULT_SELECTOR));
-
-  return registerElements(runtime, elements, {
-    ...options,
-    root,
-  });
+export class HTMLModuleOwnershipError extends HTMLModuleError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "HTMLModuleOwnershipError";
+    this.ownerScope = options.ownerScope;
+    this.requestedScope = options.requestedScope;
+  }
 }
 
 /**
- * Observe a DOM root for newly-added runtime module scripts.
- *
- * Existing scripts are registered by default. Every discovered mutation batch
- * preserves the same invariant as registerHTML(): all modules in the batch are
- * defined before any entry module from that batch executes.
+ * Create a persistent DOM/HTML adapter for one solid-tag-runtime instance.
  *
- * v0.0.2 intentionally observes additions only. Mutating or removing a script
- * that was already registered does not update/remove its runtime module.
+ * The controller owns DOM-to-module relationships. All ingestion paths
+ * (scan, observer, registerElement, append, addModule) converge on the same
+ * module-level WeakMap so an element can only be claimed once.
  */
-export async function observeHTML(runtime, options = {}) {
+export function createHTMLRuntime(runtime, options = {}) {
   assertRuntime(runtime);
 
-  const root = getRoot(options, "observeHTML");
-  const MutationObserverImpl = options.MutationObserver ?? globalThis.MutationObserver;
+  const controller = {
+    id: `solid-tag-html-${++controllerSequence}`,
+    runtime,
+    scope: normalizeScope(options.scope),
+    root: options.root,
+    selector: options.selector ?? DEFAULT_SELECTOR,
+    acceptUnscoped: options.acceptUnscoped !== false,
+    executeEntries: options.executeEntries !== false,
+    fetch: options.fetch,
+    baseUrl: options.baseUrl,
+    MutationObserver: options.MutationObserver,
+    subtree: options.subtree !== false,
+    createElement: options.createElement,
+    appendTo: options.appendTo,
+    bindings: new Map(),
+    observer: undefined,
+    observerRoot: undefined,
+    ignoredExisting: new WeakSet(),
+    queue: Promise.resolve(),
+    lastError: undefined,
+    connected: false,
+    initial: emptyRegistrationResult(),
+  };
 
-  if (typeof MutationObserverImpl !== "function") {
-    throw new TypeError(
-      "observeHTML() requires MutationObserver support or a MutationObserver option.",
+  const api = {
+    get runtime() {
+      return runtime;
+    },
+    get scope() {
+      return controller.scope;
+    },
+    get connected() {
+      return controller.connected;
+    },
+    get initial() {
+      return controller.initial;
+    },
+    register,
+    observe,
+    flush,
+    disconnect,
+    defineElement,
+    registerElement,
+    append,
+    addModule,
+    owns,
+    getModuleId,
+    getElement,
+  };
+
+  controller.api = api;
+  return api;
+
+  /** 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),
     );
+
+    return processElements(controller, elements, {
+      ...callOptions,
+      root,
+      origin: callOptions.origin ?? "initial-scan",
+      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+    });
   }
 
-  const selector = options.selector ?? DEFAULT_SELECTOR;
-  const seen = new WeakSet();
-  let connected = true;
-  let lastError;
-  let queue = Promise.resolve();
+  /**
+   * Start MutationObserver-backed discovery. Existing matching scripts are
+   * registered by default. The controller itself is returned for chaining.
+   */
+  async function observe(callOptions = {}) {
+    if (controller.connected) return api;
+
+    const merged = mergeOptions(controller, callOptions);
+    const root = getRoot(merged, "HTML runtime observe");
+    const MutationObserverImpl = callOptions.MutationObserver ?? controller.MutationObserver ?? globalThis.MutationObserver;
+
+    if (typeof MutationObserverImpl !== "function") {
+      throw new TypeError(
+        "observe() requires MutationObserver support or a MutationObserver option.",
+      );
+    }
+
+    controller.observerRoot = root;
+    controller.connected = true;
+    controller.lastError = undefined;
+    controller.ignoredExisting = new WeakSet();
 
-  if (options.registerExisting === false) {
-    for (const element of Array.from(root.querySelectorAll(selector))) {
-      seen.add(element);
+    if (callOptions.registerExisting === false) {
+      for (const element of Array.from(root.querySelectorAll(callOptions.selector ?? controller.selector))) {
+        if (acceptsDiscoveredElement(controller, element, callOptions)) {
+          controller.ignoredExisting.add(element);
+        }
+      }
+      controller.initial = emptyRegistrationResult();
+    }
+
+    const observer = new MutationObserverImpl(() => {
+      void enqueueObserverScan(controller, callOptions).catch(() => {});
+    });
+
+    controller.observer = observer;
+    observer.observe(root, {
+      childList: true,
+      subtree: callOptions.subtree ?? controller.subtree,
+    });
+
+    try {
+      if (callOptions.registerExisting !== false) {
+        controller.initial = await enqueueObserverScan(controller, {
+          ...callOptions,
+          origin: "observer-initial",
+        });
+      }
+    } catch (error) {
+      disconnect();
+      throw error;
     }
+
+    return api;
   }
 
-  const scanAndRegister = async () => {
-    const elements = Array.from(root.querySelectorAll(selector)).filter(
-      element => !seen.has(element),
-    );
+  /** Wait for observer work, then synchronously scan for newly discoverable scripts. */
+  async function flush(callOptions = {}) {
+    await controller.queue;
 
-    if (elements.length === 0) return emptyRegistrationResult();
+    if (controller.lastError) {
+      const error = controller.lastError;
+      controller.lastError = undefined;
+      throw error;
+    }
 
-    return registerElements(
-      runtime,
-      elements,
-      {
-        ...options,
-        root,
-      },
-      element => seen.add(element),
-    );
-  };
+    if (!controller.connected) return emptyRegistrationResult();
+    return enqueueObserverScan(controller, callOptions);
+  }
+
+  function disconnect() {
+    if (!controller.connected) return;
+    controller.connected = false;
+    controller.observer?.disconnect();
+    controller.observer = undefined;
+    controller.observerRoot = undefined;
+  }
+
+  /** Define one element without automatically executing an entry module. */
+  async function defineElement(element, callOptions = {}) {
+    const result = await processElements(controller, [element], {
+      ...callOptions,
+      origin: callOptions.origin ?? "define-element",
+      explicit: true,
+      executeEntries: false,
+    });
+    return result.modules[0] ?? definitionFromOwnedElement(controller, element);
+  }
 
-  const reportError = error => {
-    lastError = error;
+  /** Explicitly claim/register an element for this controller. */
+  async function registerElement(element, callOptions = {}) {
+    const result = await processElements(controller, [element], {
+      ...callOptions,
+      origin: callOptions.origin ?? "register-element",
+      explicit: true,
+      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+    });
+    return result.modules[0] ?? definitionFromOwnedElement(controller, element);
+  }
+
+  /**
+   * Claim a user-created script before DOM insertion, append it to this
+   * controller's target, then register it directly. The observer will see the
+   * mutation later but skip it because ownership was already established.
+   */
+  async function append(element, callOptions = {}) {
+    const claim = claimElement(controller, element, {
+      ...callOptions,
+      origin: callOptions.origin ?? "append",
+      explicit: true,
+    });
+
+    const target = getAppendTarget(controller, callOptions);
+    appendElement(target, element);
+
+    const result = await processClaims(controller, claim.fresh ? [claim.record] : [], {
+      ...callOptions,
+      origin: callOptions.origin ?? "append",
+      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+    });
+
+    if (!claim.fresh) await claim.record.promise;
+    return result.modules[0] ?? claim.record.definition;
+  }
 
-    if (typeof options.onError === "function") {
-      options.onError(error);
-      return;
+  /** Create a runtime script element and add it through append(). */
+  async function addModule(moduleOptions = {}) {
+    const format = normalizeFormat(moduleOptions.format ?? inferFormat({
+      explicitFormat: undefined,
+      language: moduleOptions.language,
+      type: moduleOptions.type,
+      moduleId: moduleOptions.id ?? moduleOptions.module,
+      sourceUrl: moduleOptions.src,
+    }));
+
+    const createElement = moduleOptions.createElement
+      ?? controller.createElement
+      ?? getDocumentForCreation(controller, moduleOptions)?.createElement?.bind(getDocumentForCreation(controller, moduleOptions));
+
+    if (typeof createElement !== "function") {
+      throw new TypeError(
+        "addModule() requires document.createElement(), a root ownerDocument, or a createElement option.",
+      );
     }
 
-    // MutationObserver callbacks cannot be awaited by the DOM. Keep the error
-    // available for flush(), but also make background failures visible.
-    globalThis.console?.error?.("solid-tag-runtime/html observer error", error);
-  };
+    const element = createElement("script");
+    if (!element || typeof element.setAttribute !== "function") {
+      throw new TypeError("addModule() createElement must return a script element-like object with setAttribute().");
+    }
 
-  const enqueue = () => {
-    const task = queue.then(scanAndRegister);
-    queue = task.then(
-      () => undefined,
-      error => {
-        reportError(error);
-      },
-    );
-    return task;
-  };
+    const type = moduleOptions.type ?? (format === "js" ? "solid-js" : "solid-jsx");
+    element.setAttribute("type", type);
+
+    const id = nonEmpty(moduleOptions.id ?? moduleOptions.module);
+    if (id) element.setAttribute("module", id);
+    if (moduleOptions.src) element.setAttribute("src", String(moduleOptions.src));
+    if (moduleOptions.entry) element.setAttribute("entry", "");
+    if (moduleOptions.language) element.setAttribute("language", String(moduleOptions.language));
+    if (moduleOptions.source != null) element.textContent = String(moduleOptions.source);
+
+    const definition = await append(element, {
+      ...moduleOptions,
+      format,
+      origin: "add-module",
+    });
+
+    return {
+      ...definition,
+      element,
+    };
+  }
 
-  const observer = new MutationObserverImpl(() => {
-    // The settled queue owns background error reporting. Attach a rejection
-    // handler here as well so the callback never creates an unhandled promise.
-    void enqueue().catch(() => {});
-  });
+  function owns(element) {
+    return elementOwners.get(element)?.owner === controller;
+  }
 
-  observer.observe(root, {
-    childList: true,
-    subtree: options.subtree !== false,
+  function getModuleId(element) {
+    const record = elementOwners.get(element);
+    return record?.owner === controller ? record.moduleId : undefined;
+  }
+
+  function getElement(id) {
+    const normalized = normalizeModuleId(runtime, id);
+    return controller.bindings.get(normalized)?.element;
+  }
+}
+
+/**
+ * Discover runtime module scripts under a Document/Element-like root, define
+ * all of them first, then optionally execute scripts marked with `entry`.
+ *
+ * Backwards-compatible convenience wrapper over the runtime's default HTML
+ * controller.
+ */
+export async function registerHTML(runtime, options = {}) {
+  return getDefaultController(runtime, options).register(options);
+}
+
+/** Backwards-compatible observer convenience wrapper. */
+export async function observeHTML(runtime, options = {}) {
+  const controller = getDefaultController(runtime, options);
+  await controller.observe(options);
+  return controller;
+}
+
+/** Define one <script> element as a runtime module without executing it. */
+export async function defineScript(runtime, element, options = {}) {
+  return getDefaultController(runtime, options).defineElement(element, options);
+}
+
+export const htmlModuleSelector = DEFAULT_SELECTOR;
+export const htmlRuntimeScopeAttribute = RUNTIME_SCOPE_ATTRIBUTE;
+
+async function enqueueObserverScan(controller, callOptions = {}) {
+  const task = controller.queue.then(async () => {
+    if (!controller.connected) return emptyRegistrationResult();
+
+    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 ownership = elementOwners.get(element);
+      if (!ownership) return true;
+      if (ownership.owner === controller) return false;
+
+      throw ownershipError(controller, element, ownership);
+    });
+
+    return processElements(controller, elements, {
+      ...callOptions,
+      root,
+      origin: callOptions.origin ?? "observer",
+      executeEntries: callOptions.executeEntries ?? controller.executeEntries,
+    });
   });
 
-  let initial = emptyRegistrationResult();
+  controller.queue = task.then(
+    () => undefined,
+    error => {
+      controller.lastError = error;
+      if (typeof callOptions.onError === "function") {
+        callOptions.onError(error);
+      } else {
+        globalThis.console?.error?.("solid-tag-runtime/html observer error", error);
+      }
+    },
+  );
+
+  return task;
+}
+
+async function processElements(controller, elements, options = {}) {
+  const freshRecords = [];
+  const existingRecords = [];
+
+  // Claim the entire batch synchronously before any asynchronous source loading.
+  // This prevents observer/manual registration races and reserves module IDs.
+  for (const element of elements) {
+    if (!options.explicit && !acceptsDiscoveredElement(controller, element, options)) continue;
+
+    const claim = claimElement(controller, element, options);
+    if (claim.fresh) freshRecords.push(claim.record);
+    else existingRecords.push(claim.record);
+  }
+
+  const result = await processClaims(controller, freshRecords, options);
+
+  // Same-controller repeated registration is idempotent. Await currently pending
+  // registrations, but do not report/re-execute them as newly registered modules.
+  await Promise.all(existingRecords.map(record => record.promise));
+  return result;
+}
 
+async function processClaims(controller, records, options = {}) {
+  if (records.length === 0) return emptyRegistrationResult();
+
+  let prepared;
+  try {
+    prepared = await Promise.all(records.map(record => prepareRecordSource(controller, record, options)));
+  } catch (error) {
+    for (const record of records) rejectRecord(record, error);
+    throw error;
+  }
+
+  const modules = [];
   try {
-    if (options.registerExisting !== false) {
-      initial = await enqueue();
+    // Preserve the graph invariant: every module in this discovered batch is
+    // defined before any entry in the batch executes.
+    for (let index = 0; index < records.length; index++) {
+      const record = records[index];
+      const item = prepared[index];
+      controller.runtime.define(record.moduleId, item.source, { format: record.format });
+
+      record.state = "defined";
+      record.definition = definitionFromRecord(record);
+      record.resolve(record.definition);
+      modules.push(record.definition);
     }
   } catch (error) {
-    connected = false;
-    observer.disconnect();
+    for (const record of records) {
+      if (record.state === "claimed" || record.state === "loading") rejectRecord(record, error);
+    }
     throw error;
   }
 
+  const entries = modules.filter(module => module.entry);
+  const executed = [];
+
+  if (options.executeEntries !== false) {
+    for (const entry of entries) {
+      const record = elementOwners.get(entry.element);
+      if (record) record.state = "executing";
+
+      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;
+      }
+    }
+  }
+
   return {
-    initial,
+    modules,
+    entries: entries.map(entry => entry.id),
+    executed,
+  };
+}
 
-    get connected() {
-      return connected;
-    },
+function claimElement(controller, element, options = {}) {
+  assertElement(element, options.origin ?? "HTML runtime");
 
-    async flush() {
-      await queue;
+  const existing = elementOwners.get(element);
+  if (existing) {
+    if (existing.owner === controller) return { fresh: false, record: existing };
+    throw ownershipError(controller, element, existing);
+  }
 
-      if (lastError) {
-        const error = lastError;
-        lastError = undefined;
-        throw error;
-      }
+  assertExplicitScopeCompatibility(controller, element, options);
+  stampScope(controller, element, options);
 
-      return enqueue();
-    },
+  const metadata = inspectElement(controller, element, options);
+  const moduleId = normalizeModuleId(controller.runtime, metadata.id);
+  const binding = controller.bindings.get(moduleId);
 
-    disconnect() {
-      if (!connected) return;
-      connected = false;
-      observer.disconnect();
-    },
+  if (binding && binding.element !== element) {
+    throw new HTMLModuleError(
+      `HTML module ${JSON.stringify(moduleId)} is already bound to another script element in this HTML runtime.`,
+      { element, moduleId, sourceUrl: metadata.sourceUrl },
+    );
+  }
+
+  if (!binding && controller.runtime.has(moduleId)) {
+    throw new HTMLModuleError(
+      `Runtime module ${JSON.stringify(moduleId)} already exists and is not owned by this HTML runtime. Use runtime.update() for explicit replacement.`,
+      { element, moduleId, sourceUrl: metadata.sourceUrl },
+    );
+  }
+
+  let resolve;
+  let reject;
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  // A failed background observer registration may not have a caller awaiting
+  // this per-element promise. Mark the rejection as observed while preserving
+  // the original promise for explicit callers.
+  void promise.catch(() => {});
+
+  const record = {
+    owner: controller,
+    element,
+    moduleId,
+    format: metadata.format,
+    entry: metadata.entry,
+    sourceUrl: metadata.sourceUrl,
+    inline: !metadata.sourceUrl,
+    state: "claimed",
+    origin: options.origin ?? "unknown",
+    promise,
+    resolve,
+    reject,
+    definition: undefined,
+    error: undefined,
   };
+
+  elementOwners.set(element, record);
+  controller.bindings.set(moduleId, record);
+  return { fresh: true, record };
 }
 
-/**
- * Define one <script> element as a runtime module without executing it.
- */
-export async function defineScript(runtime, element, options = {}) {
-  assertRuntime(runtime);
+async function prepareRecordSource(controller, record, options) {
+  record.state = "loading";
 
-  if (!element || typeof element.getAttribute !== "function") {
-    throw new TypeError("defineScript() expects a script element-like object.");
+  let source;
+  if (record.sourceUrl) {
+    source = await fetchSource(
+      record.sourceUrl,
+      options.fetch ?? controller.fetch ?? globalThis.fetch,
+      record.element,
+      record.moduleId,
+    );
+  } else {
+    source = record.element.textContent ?? "";
   }
 
+  return { source };
+}
+
+function inspectElement(controller, element, options = {}) {
   const type = normalizeType(element.getAttribute("type"));
   const entry = hasAttribute(element, "entry");
   const srcAttribute = nonEmpty(element.getAttribute("src"));
   const explicitId = nonEmpty(element.getAttribute("module"));
-  const sourceUrl = srcAttribute
-    ? resolveSourceUrl(srcAttribute, options.baseUrl ?? element.baseURI ?? options.root?.baseURI)
-    : undefined;
+  const baseUrl = options.baseUrl
+    ?? controller.baseUrl
+    ?? element.baseURI
+    ?? options.root?.baseURI
+    ?? controller.root?.baseURI;
+  const sourceUrl = srcAttribute ? resolveSourceUrl(srcAttribute, baseUrl) : undefined;
 
   const format = inferFormat({
     explicitFormat: options.format,
@@ -190,7 +551,6 @@ export async function defineScript(runtime, element, options = {}) {
   });
 
   const id = explicitId ?? sourceUrl ?? (entry ? createAnonymousId(format) : undefined);
-
   if (!id) {
     throw new HTMLModuleError(
       "Inline solid runtime module scripts require a `module` attribute unless they are marked `entry`.",
@@ -198,54 +558,152 @@ export async function defineScript(runtime, element, options = {}) {
     );
   }
 
-  let source;
-  if (sourceUrl) {
-    source = await fetchSource(sourceUrl, options.fetch ?? globalThis.fetch, element, id);
-  } else {
-    source = element.textContent ?? "";
-  }
-
-  runtime.define(id, source, { format });
+  return { id, format, entry, sourceUrl };
+}
 
+function definitionFromRecord(record) {
   return {
-    id: runtime.resolve(id),
-    format,
-    entry,
-    sourceUrl,
-    inline: !sourceUrl,
-    element,
+    id: record.moduleId,
+    format: record.format,
+    entry: record.entry,
+    sourceUrl: record.sourceUrl,
+    inline: record.inline,
+    element: record.element,
   };
 }
 
-export const htmlModuleSelector = DEFAULT_SELECTOR;
+function definitionFromOwnedElement(controller, element) {
+  const record = elementOwners.get(element);
+  if (!record || record.owner !== controller) return undefined;
+  return record.definition ?? definitionFromRecord(record);
+}
 
-async function registerElements(runtime, elements, options, onDefined) {
-  const modules = [];
+function rejectRecord(record, error) {
+  if (record.state === "error") return;
+  record.state = "error";
+  record.error = error;
+  record.reject(error);
+}
 
-  // Define the complete discovered batch before evaluating any entry. This
-  // allows an entry to import another module discovered later in the same scan.
-  for (const element of elements) {
-    const definition = await defineScript(runtime, element, options);
-    modules.push(definition);
-    onDefined?.(element, definition);
+function acceptsDiscoveredElement(controller, element, options = {}) {
+  const elementScope = nonEmpty(element?.getAttribute?.(RUNTIME_SCOPE_ATTRIBUTE));
+  const scope = normalizeScope(options.scope ?? controller.scope);
+  const acceptUnscoped = options.acceptUnscoped ?? controller.acceptUnscoped;
+
+  if (scope) {
+    if (elementScope) return elementScope === scope;
+    return acceptUnscoped !== false;
   }
 
-  const entries = modules.filter(module => module.entry);
-  const executed = [];
+  // An unscoped controller never silently steals a declaratively scoped script.
+  return !elementScope;
+}
 
-  if (options.executeEntries !== false) {
-    for (const entry of entries) {
-      executed.push({
-        id: entry.id,
-        namespace: await runtime.import(entry.id),
-      });
-    }
+function assertExplicitScopeCompatibility(controller, element, options = {}) {
+  const requestedScope = normalizeScope(options.scope ?? controller.scope);
+  const elementScope = nonEmpty(element.getAttribute(RUNTIME_SCOPE_ATTRIBUTE));
+
+  if (elementScope && requestedScope !== elementScope) {
+    throw new HTMLModuleOwnershipError(
+      `Script is scoped to HTML runtime ${JSON.stringify(elementScope)} and cannot be claimed by ${JSON.stringify(requestedScope ?? "(unscoped)")}.`,
+      {
+        element,
+        ownerScope: elementScope,
+        requestedScope,
+      },
+    );
+  }
+}
+
+function stampScope(controller, element, options = {}) {
+  const scope = normalizeScope(options.scope ?? controller.scope);
+  if (!scope) return;
+  if (nonEmpty(element.getAttribute(RUNTIME_SCOPE_ATTRIBUTE))) return;
+
+  if (typeof element.setAttribute !== "function") {
+    throw new TypeError(
+      `Scoped HTML runtimes require script elements with setAttribute() so ${RUNTIME_SCOPE_ATTRIBUTE} can be recorded.`,
+    );
+  }
+
+  element.setAttribute(RUNTIME_SCOPE_ATTRIBUTE, scope);
+}
+
+function ownershipError(controller, element, ownership) {
+  return new HTMLModuleOwnershipError(
+    `Runtime script element is already owned by HTML runtime ${JSON.stringify(ownership.owner.scope ?? ownership.owner.id)} and cannot be claimed by ${JSON.stringify(controller.scope ?? controller.id)}.`,
+    {
+      element,
+      moduleId: ownership.moduleId,
+      sourceUrl: ownership.sourceUrl,
+      ownerScope: ownership.owner.scope,
+      requestedScope: controller.scope,
+    },
+  );
+}
+
+function getDefaultController(runtime, options = {}) {
+  assertRuntime(runtime);
+  let controller = defaultControllers.get(runtime);
+  if (!controller) {
+    controller = createHTMLRuntime(runtime, {
+      root: options.root,
+      selector: options.selector,
+      executeEntries: options.executeEntries,
+      fetch: options.fetch,
+      baseUrl: options.baseUrl,
+      MutationObserver: options.MutationObserver,
+      subtree: options.subtree,
+      createElement: options.createElement,
+      appendTo: options.appendTo,
+      scope: options.scope,
+      acceptUnscoped: options.acceptUnscoped,
+    });
+    defaultControllers.set(runtime, controller);
   }
+  return controller;
+}
 
+function getAppendTarget(controller, options = {}) {
+  const explicit = options.appendTo ?? controller.appendTo;
+  if (explicit) return explicit;
+
+  const root = options.root ?? controller.root ?? globalThis.document;
+  if (root?.body) return root.body;
+  if (root?.documentElement && root.documentElement !== root) return root.documentElement;
+  return root;
+}
+
+function appendElement(target, element) {
+  if (target && typeof target.append === "function") {
+    target.append(element);
+    return;
+  }
+  if (target && typeof target.appendChild === "function") {
+    target.appendChild(element);
+    return;
+  }
+  throw new TypeError("append() requires an append target with append() or appendChild().");
+}
+
+function getDocumentForCreation(controller, options = {}) {
+  return options.document
+    ?? controller.root?.ownerDocument
+    ?? controller.root
+    ?? globalThis.document;
+}
+
+function mergeOptions(controller, options) {
   return {
-    modules,
-    entries: entries.map(entry => entry.id),
-    executed,
+    root: options.root ?? controller.root,
+    selector: options.selector ?? controller.selector,
+    executeEntries: options.executeEntries ?? controller.executeEntries,
+    fetch: options.fetch ?? controller.fetch,
+    baseUrl: options.baseUrl ?? controller.baseUrl,
+    MutationObserver: options.MutationObserver ?? controller.MutationObserver,
+    subtree: options.subtree ?? controller.subtree,
+    scope: options.scope ?? controller.scope,
+    acceptUnscoped: options.acceptUnscoped ?? controller.acceptUnscoped,
   };
 }
 
@@ -260,7 +718,7 @@ function emptyRegistrationResult() {
 function getRoot(options, caller) {
   const root = options.root ?? globalThis.document;
   if (!root || typeof root.querySelectorAll !== "function") {
-    throw new TypeError(`${caller}() requires a DOM root with querySelectorAll().`);
+    throw new TypeError(`${caller} requires a DOM root with querySelectorAll().`);
   }
   return root;
 }
@@ -271,6 +729,20 @@ function assertRuntime(runtime) {
   }
 }
 
+function assertElement(element, caller) {
+  if (!element || typeof element.getAttribute !== "function") {
+    throw new TypeError(`${caller} expects a script element-like object.`);
+  }
+}
+
+function normalizeScope(value) {
+  return nonEmpty(value);
+}
+
+function normalizeModuleId(runtime, id) {
+  return runtime.resolve(String(id));
+}
+
 function normalizeType(value) {
   return String(value ?? "").trim().toLowerCase();
 }
@@ -336,8 +808,6 @@ function resolveSourceUrl(src, baseUrl) {
     if (baseUrl) return new URL(src, baseUrl).href;
     return new URL(src).href;
   } catch {
-    // A DOM element normally supplies baseURI. Keeping the original string is
-    // still useful for custom DOM-like environments and injected fetchers.
     return src;
   }
 }