browser-module-runtime 0.0.0-stage → 0.0.1

package/src/engine/runtime.js

@@ -0,0 +1,2044 @@
+import { createPackagePolicy, PackageVersionResolutionError } from "./package-resolution/index.js";
+import {
+  CircularDependencyError,
+  ModuleCompileError,
+  ModuleResolutionError,
+  ModuleWaitTimeoutError,
+  ModuleRuntimeError,
+} from "./errors.js";
+import { createDefaultModuleUrlBackend } from "./url-backend.js";
+import { createEventDispatcher } from "./events.js";
+import { approximateByteSize, createCompileCache, sha256, stableSerialize } from "./compile-cache.js";
+
+const HOST_REGISTRY_KEY = "__browserModuleRuntimeHostModules__";
+const COMPILED_ARTIFACT_ABI = "browser-module-runtime:compiled-artifact:v1";
+const COMPILED_ARTIFACT_SCHEMA = 1;
+let runtimeSequence = 0;
+
+export function createRuntime(options = {}) {
+  const normalizedCompileCacheOption = normalizeCompileCacheAlias(options);
+  const {
+    compiler,
+    modules = {},
+    urls = {},
+    allowNativeImports = true,
+    resolve: customResolve,
+    fallbackResolve: customFallbackResolve,
+    moduleUrlBackend = createDefaultModuleUrlBackend(),
+    compileCache: _compileCacheOptions,
+    cache: _cacheAlias,
+    packages,
+    _solidFamilyRules,
+  } = options;
+  const compileCacheOptions = normalizedCompileCacheOption;
+  const packagePolicy = createPackagePolicy(packages, { familyRules: _solidFamilyRules });
+  for (const name of Object.keys(modules)) {
+    if (packagePolicy.pins.has(name)) {
+      throw new PackageVersionResolutionError("PACKAGE_VERSION_CONFLICT", `Package pin ${JSON.stringify(name)} conflicts with an explicit modules entry. Remove the pin or module override.`, { packageName: name });
+    }
+  }
+
+
+  if (!compiler || (typeof compiler.compile !== "function" && (typeof compiler.analyze !== "function" || typeof compiler.transform !== "function"))) {
+    throw new TypeError("createRuntime() requires compile(), or analyze() + transform(), on its compiler.");
+  }
+
+  const runtimeId = `browser-module-runtime-${++runtimeSequence}-${randomId()}`;
+  const records = new Map();
+  const moduleWaiters = new Map();
+  let anonymousSequence = 0;
+  let disposed = false;
+  const events = createEventDispatcher({
+    onListenerError(error) {
+      globalThis.console?.error?.("browser-module-runtime lifecycle subscriber error", error);
+    },
+  });
+  let eventBufferDepth = 0;
+  const eventBuffer = [];
+  const memoryCompileArtifacts = new Map();
+  const inFlightCompiles = new Map();
+  const compileCacheConfig = normalizeCompileCacheOptions(compileCacheOptions);
+  let warnedMissingCompilerFingerprint = false;
+
+  const globalRegistry = getHostRegistry();
+  const hostNamespaces = new Map();
+  globalRegistry.set(runtimeId, hostNamespaces);
+
+  const api = {
+    define,
+    defineMany,
+    defineModule,
+    defineUrl,
+    update,
+    import: importModule,
+    waitForModule,
+    compile,
+    toModule,
+    toComponent,
+    has,
+    invalidate,
+    remove,
+    clear,
+    subscribe,
+    modules: listModules,
+    dependencies,
+    dependents,
+    getModuleInfo,
+    getPrivateImports,
+    dispose,
+    resolve: resolvePublic,
+    inspectPackageResolution: packagePolicy.inspect,
+    compileCache: createCompileCacheManager(),
+  };
+
+  for (const [id, namespace] of Object.entries(modules)) defineModule(id, namespace);
+  for (const [id, url] of Object.entries(urls)) defineUrl(id, url);
+
+  return api;
+
+  function assertActive() {
+    if (disposed) throw new ModuleRuntimeError("This browser-module-runtime instance has been disposed.");
+  }
+
+  function define(id, source, defineOptions = {}) {
+    return defineSource(id, source, defineOptions, "define");
+  }
+
+  function defineMany(definitions) {
+    assertActive();
+    if (!Array.isArray(definitions)) {
+      throw new TypeError("defineMany(definitions) expects an array of source module definitions.");
+    }
+
+    const prepared = definitions.map((definition, index) => {
+      if (!definition || typeof definition !== "object") {
+        throw new TypeError(`defineMany() item ${index} must be an object with id and source.`);
+      }
+      if (definition.id == null) {
+        throw new TypeError(`defineMany() item ${index} is missing id.`);
+      }
+      const id = normalizeDefinedId(definition.id);
+      return {
+        id,
+        source: String(definition.source ?? ""),
+        format: definition.format ?? "jsx",
+        imports: definition.imports,
+      };
+    });
+
+    const seen = new Set();
+    for (const item of prepared) {
+      if (seen.has(item.id)) {
+        throw new ModuleRuntimeError(`defineMany() contains duplicate module id ${JSON.stringify(item.id)}.`);
+      }
+      seen.add(item.id);
+    }
+
+    eventBufferDepth += 1;
+    try {
+      const ids = prepared.map(item => defineSource(item.id, item.source, {
+        format: item.format,
+        imports: item.imports,
+      }, "defineMany"));
+      emit({
+        type: "modules-defined",
+        ids: [...ids],
+        modules: ids.map(id => toModuleInfo(records.get(id))),
+      });
+      return ids;
+    } finally {
+      eventBufferDepth -= 1;
+      if (eventBufferDepth === 0) flushEventBuffer();
+    }
+  }
+
+  function update(id, source, updateOptions = {}) {
+    return defineSource(id, source, updateOptions, "update");
+  }
+
+  // A later explicit runtime module intentionally shadows an exact root pin.
+  // Consumers previously linked against the provider URL must be relinked so
+  // the new registered module actually wins (not merely future import calls).
+  function invalidatePinnedUrlConsumers(id, reason) {
+    const pinned = packagePolicy.inspect(id);
+    if (!pinned || pinned.subpath) return;
+    for (const record of [...records.values()]) {
+      if (record.kind === "source" && record.dependencies?.has(pinned.url)) {
+        invalidate(record.id, { dependents: true, reason: `pinned-override:${reason}` });
+      }
+    }
+  }
+
+  function defineSource(id, source, defineOptions = {}, operation = "define") {
+    assertActive();
+    const normalized = normalizeDefinedId(id);
+    const existing = records.get(normalized);
+    const preservePrivateImports = operation === "update"
+      && !Object.prototype.hasOwnProperty.call(defineOptions, "imports")
+      && existing?.kind === "source";
+    const privateImports = normalizePrivateImports(
+      preservePrivateImports ? privateImportDefinitions(existing) : defineOptions.imports,
+      normalized,
+    );
+
+    if (existing) invalidate(normalized, { dependents: true, reason: operation });
+    invalidatePinnedUrlConsumers(normalized, operation);
+
+    const record = {
+      id: normalized,
+      kind: "source",
+      source: String(source),
+      format: defineOptions.format ?? "jsx",
+      version: (existing?.version ?? 0) + 1,
+      state: "defined",
+      dependencies: new Set(),
+      dependents: existing?.dependents ?? new Set(),
+      compiledCode: undefined,
+      compiledArtifact: undefined,
+      compiledArtifactKey: undefined,
+      compileCacheInfo: createInitialCompileCacheInfo(),
+      forceCompileRefresh: false,
+      diagnostics: [],
+      privateImports,
+      url: undefined,
+      importPromise: undefined,
+      namespace: undefined,
+    };
+
+    records.set(normalized, record);
+    notifyModuleWaiters(record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation,
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
+    });
+    if (operation === "update") {
+      emit({
+        type: "module-updated",
+        id: normalized,
+        kind: record.kind,
+        previousVersion: existing?.version ?? 0,
+        version: record.version,
+        format: record.format,
+        module: toModuleInfo(record),
+      });
+    }
+    return normalized;
+  }
+
+  function defineModule(id, namespace) {
+    assertActive();
+    const normalized = normalizeDefinedId(id);
+    const existing = records.get(normalized);
+    if (existing) invalidate(normalized, { dependents: true, reason: "defineModule" });
+    invalidatePinnedUrlConsumers(normalized, "defineModule");
+
+    if ((typeof namespace !== "object" || namespace === null) && typeof namespace !== "function") {
+      throw new TypeError("defineModule(id, namespace) expects an object, function, or ES module namespace-like value.");
+    }
+
+    hostNamespaces.set(normalized, namespace);
+
+    const record = {
+      id: normalized,
+      kind: "host",
+      namespace,
+      version: (existing?.version ?? 0) + 1,
+      state: "ready",
+      dependencies: new Set(),
+      dependents: existing?.dependents ?? new Set(),
+      url: undefined,
+    };
+    records.set(normalized, record);
+    notifyModuleWaiters(record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation: "defineModule",
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
+    });
+
+    return normalized;
+  }
+
+  function defineUrl(id, url) {
+    assertActive();
+    const normalized = normalizeDefinedId(id);
+    const existing = records.get(normalized);
+    if (existing) invalidate(normalized, { dependents: true, reason: "defineUrl" });
+    invalidatePinnedUrlConsumers(normalized, "defineUrl");
+
+    const href = String(url);
+    const record = {
+      id: normalized,
+      kind: "url",
+      externalUrl: href,
+      version: (existing?.version ?? 0) + 1,
+      state: "defined",
+      dependencies: new Set(),
+      dependents: existing?.dependents ?? new Set(),
+      importPromise: undefined,
+      namespace: undefined,
+    };
+    records.set(normalized, record);
+    notifyModuleWaiters(record);
+    emit({
+      type: "module-defined",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      operation: "defineUrl",
+      replaced: Boolean(existing),
+      module: toModuleInfo(record),
+    });
+
+    return normalized;
+  }
+
+  function waitForModule(id, waitOptions = {}) {
+    assertActive();
+    return waitForRegisteredModule(id, null, waitOptions, record => importRecord(record, []));
+  }
+
+  function waitForRegisteredModule(id, importer, waitOptions = {}, onAvailable) {
+    assertActive();
+    const raw = String(id);
+    const normalized = normalizeWaitForModuleId(raw, importer);
+    const options = normalizeWaitForModuleOptions(waitOptions);
+
+    if (options.signal?.aborted) {
+      return Promise.reject(createAbortError(options.signal));
+    }
+
+    const existing = records.get(normalized);
+    if (existing) {
+      return Promise.resolve().then(() => onAvailable(existing));
+    }
+
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        id: normalized,
+        raw,
+        importer,
+        settled: false,
+        timeoutId: undefined,
+        signal: options.signal,
+        abortHandler: undefined,
+        resolve,
+        reject,
+        onAvailable,
+      };
+
+      let waiters = moduleWaiters.get(normalized);
+      if (!waiters) {
+        waiters = new Set();
+        moduleWaiters.set(normalized, waiters);
+      }
+      waiters.add(waiter);
+
+      if (options.timeout != null) {
+        waiter.timeoutId = setTimeout(() => {
+          if (!settleModuleWaiter(waiter)) return;
+          reject(new ModuleWaitTimeoutError(normalized, options.timeout));
+        }, options.timeout);
+      }
+
+      if (options.signal) {
+        waiter.abortHandler = () => {
+          if (!settleModuleWaiter(waiter)) return;
+          reject(createAbortError(options.signal));
+        };
+        options.signal.addEventListener("abort", waiter.abortHandler, { once: true });
+      }
+
+      // Guard against a definition racing between the initial lookup and waiter registration.
+      const raced = records.get(normalized);
+      if (raced) notifyModuleWaiters(raced);
+    });
+  }
+
+  function notifyModuleWaiters(record) {
+    const waiters = moduleWaiters.get(record.id);
+    if (!waiters?.size) return;
+    moduleWaiters.delete(record.id);
+
+    for (const waiter of [...waiters]) {
+      if (!settleModuleWaiter(waiter, false)) continue;
+      Promise.resolve()
+        .then(() => waiter.onAvailable(record))
+        .then(waiter.resolve, waiter.reject);
+    }
+  }
+
+  function settleModuleWaiter(waiter, removeFromRegistry = true) {
+    if (waiter.settled) return false;
+    waiter.settled = true;
+
+    if (waiter.timeoutId !== undefined) {
+      clearTimeout(waiter.timeoutId);
+      waiter.timeoutId = undefined;
+    }
+    if (waiter.signal && waiter.abortHandler) {
+      waiter.signal.removeEventListener("abort", waiter.abortHandler);
+      waiter.abortHandler = undefined;
+    }
+    if (removeFromRegistry) {
+      const waiters = moduleWaiters.get(waiter.id);
+      waiters?.delete(waiter);
+      if (waiters?.size === 0) moduleWaiters.delete(waiter.id);
+    }
+    return true;
+  }
+
+  function rejectAllModuleWaiters(error) {
+    const pending = [...moduleWaiters.values()].flatMap(waiters => [...waiters]);
+    moduleWaiters.clear();
+    for (const waiter of pending) {
+      if (!settleModuleWaiter(waiter, false)) continue;
+      waiter.reject(error);
+    }
+  }
+
+  async function importModule(id) {
+    assertActive();
+    const raw = String(id);
+    const resolved = resolveSpecifier(raw, null);
+    const record = records.get(resolved);
+
+    if (!record) {
+      // Top-level virtual path imports follow the same rule as static imports:
+      // unresolved relative/absolute virtual IDs are runtime resolution errors,
+      // not native browser fetches. Native fallback is reserved for absolute
+      // URLs and unresolved bare specifiers when allowNativeImports is enabled.
+      if (isRelativeSpecifier(raw) || raw.startsWith("/")) {
+        throw new ModuleResolutionError(id, null);
+      }
+      if (!allowNativeImports && !isAbsoluteUrl(resolved)) {
+        throw new ModuleResolutionError(id, null);
+      }
+      return import(resolved);
+    }
+
+    return importRecord(record, []);
+  }
+
+  async function importRecord(record, stack) {
+    if (record.kind === "host") return record.namespace;
+
+    if (record.kind === "url") {
+      if (!record.importPromise) {
+        record.state = "evaluating";
+        emit({ type: "module-evaluating", id: record.id, kind: record.kind, version: record.version });
+        record.importPromise = import(record.externalUrl).then(namespace => {
+          record.namespace = namespace;
+          record.state = "ready";
+          emit({ type: "module-evaluated", id: record.id, kind: record.kind, version: record.version, module: toModuleInfo(record) });
+          return namespace;
+        }).catch(error => {
+          record.importPromise = undefined;
+          record.state = "error";
+          emitError(record, "evaluate", error);
+          throw error;
+        });
+      }
+      return record.importPromise;
+    }
+
+    if (stack.includes(record.id)) {
+      const cycleStart = stack.indexOf(record.id);
+      const error = new CircularDependencyError([...stack.slice(cycleStart), record.id]);
+      emitError(record, "link", error);
+      throw error;
+    }
+
+    if (!record.importPromise) {
+      record.importPromise = ensureSourceUrl(record, stack).then(url => {
+        record.state = "evaluating";
+        emit({ type: "module-evaluating", id: record.id, kind: record.kind, version: record.version });
+        return import(url);
+      }).then(namespace => {
+        record.namespace = namespace;
+        record.state = "ready";
+        emit({ type: "module-evaluated", id: record.id, kind: record.kind, version: record.version, module: toModuleInfo(record) });
+        return namespace;
+      }).catch(error => {
+        record.importPromise = undefined;
+        const alreadyReported = record.state === "error";
+        record.state = "error";
+        if (!alreadyReported) emitError(record, "evaluate", error);
+        throw error;
+      });
+    }
+
+    return record.importPromise;
+  }
+
+  async function compile(id, compileOptions = {}) {
+    assertActive();
+    const resolved = resolveSpecifier(String(id), null);
+    const record = records.get(resolved);
+    if (!record) throw new ModuleResolutionError(id, null);
+    if (record.kind !== "source") {
+      return {
+        id: record.id,
+        kind: record.kind,
+        code: undefined,
+        url: record.kind === "url" ? record.externalUrl : await ensureHostUrl(record),
+        dependencies: [...record.dependencies],
+        diagnostics: [],
+      };
+    }
+
+    const cacheMode = normalizeCompileCacheMode(compileOptions.cache);
+    if (cacheMode !== "use") {
+      // A fresh linked URL for the requested module makes any already-linked
+      // dependents stale as well. Invalidate the executable graph while
+      // preserving their reusable compiler artifacts.
+      invalidate(record.id, { dependents: true, reason: `compile-cache-${cacheMode}` });
+    }
+    const url = await ensureSourceUrl(record, [], { cacheMode });
+    return {
+      id: record.id,
+      kind: record.kind,
+      code: record.compiledCode,
+      url,
+      dependencies: [...record.dependencies],
+      diagnostics: [...(record.diagnostics ?? [])],
+      assets: [...(record.compiledArtifact?.assets ?? [])],
+    };
+  }
+
+  async function toModule(source, moduleOptions = {}) {
+    assertActive();
+    const id = moduleOptions.id ?? `/__solid_tag_runtime__/anonymous-${++anonymousSequence}.jsx`;
+    const normalized = define(id, source, {
+      format: moduleOptions.format ?? "jsx",
+      imports: moduleOptions.imports,
+    });
+    return importModule(normalized);
+  }
+
+  async function toComponent(source, componentOptions = {}) {
+    const namespace = await toModule(source, componentOptions);
+    const exportName = componentOptions.exportName ?? "default";
+
+    if (!(exportName in namespace)) {
+      throw new ModuleRuntimeError(
+        `Module does not export ${JSON.stringify(exportName)}. Available exports: ${Object.keys(namespace).join(", ") || "(none)"}.`
+      );
+    }
+
+    const component = namespace[exportName];
+    if (typeof component !== "function") {
+      throw new ModuleRuntimeError(
+        `Export ${JSON.stringify(exportName)} is not callable and cannot be used as a Solid component.`
+      );
+    }
+
+    return component;
+  }
+
+  function has(id) {
+    return records.has(normalizeLookupId(id));
+  }
+
+  function invalidate(id, invalidateOptions = {}) {
+    assertActive();
+    const normalized = normalizeLookupId(id);
+    const includeDependents = invalidateOptions.dependents ?? true;
+    const reason = invalidateOptions.reason ?? "explicit";
+    const forceCompile = invalidateOptions.compile === true;
+    const seen = new Set();
+
+    invalidateOne(normalized, true);
+    return [...seen];
+
+    function invalidateOne(targetId, isRequestedModule = false) {
+      if (seen.has(targetId)) return;
+      seen.add(targetId);
+      const record = records.get(targetId);
+      if (!record) return;
+
+      if (includeDependents) {
+        for (const dependent of record.dependents) invalidateOne(dependent, false);
+      }
+
+      if (record.kind === "source") {
+        revokeRecordUrl(record);
+        revokePrivateImportUrls(record);
+        record.compiledCode = undefined;
+        record.importPromise = undefined;
+        record.namespace = undefined;
+        record.state = "defined";
+
+        // Normal graph invalidation preserves the pre-link compiler artifact.
+        // compile:true only applies to the explicitly requested module, never
+        // to its transitive dependents.
+        if (forceCompile && isRequestedModule) {
+          if (record.compiledArtifactKey) memoryCompileArtifacts.delete(record.compiledArtifactKey);
+          record.compiledArtifact = undefined;
+          record.compiledArtifactKey = undefined;
+          record.forceCompileRefresh = true;
+          record.compileCacheInfo = createInitialCompileCacheInfo();
+          record.diagnostics = [];
+        }
+      } else if (record.kind === "host") {
+        revokeRecordUrl(record);
+        record.state = "ready";
+      } else if (record.kind === "url") {
+        record.importPromise = undefined;
+        record.namespace = undefined;
+        record.state = "defined";
+      }
+
+      emit({
+        type: "module-invalidated",
+        id: record.id,
+        kind: record.kind,
+        version: record.version,
+        reason,
+      });
+    }
+  }
+
+  function remove(id, removeOptions = {}) {
+    assertActive();
+    const normalized = normalizeLookupId(id);
+    const record = records.get(normalized);
+    if (!record) return false;
+
+    if (removeOptions.invalidateDependents !== false) {
+      for (const dependent of [...record.dependents]) {
+        invalidate(dependent, { dependents: true, reason: `dependency-removed:${normalized}` });
+      }
+    }
+
+    for (const dependency of record.dependencies) {
+      records.get(dependency)?.dependents.delete(normalized);
+    }
+
+    revokeRecordUrl(record);
+    if (record.kind === "source") revokePrivateImportUrls(record);
+    if (record.kind === "host") hostNamespaces.delete(normalized);
+    records.delete(normalized);
+
+    emit({
+      type: "module-removed",
+      id: normalized,
+      kind: record.kind,
+      version: record.version,
+      invalidateDependents: removeOptions.invalidateDependents !== false,
+    });
+    return true;
+  }
+
+  function clear(clearOptions = {}) {
+    assertActive();
+    const preserveHostModules = clearOptions.preserveHostModules !== false;
+    const ids = [...records.values()]
+      .filter(record => !(preserveHostModules && record.kind === "host"))
+      .map(record => record.id);
+
+    for (const id of ids) remove(id, { invalidateDependents: false });
+
+    emit({
+      type: "runtime-cleared",
+      ids: [...ids],
+      preserveHostModules,
+    });
+    return ids;
+  }
+
+  function subscribe(typesOrListener, maybeListener) {
+    assertActive();
+    return events.subscribe(typesOrListener, maybeListener);
+  }
+
+  function listModules() {
+    return [...records.values()].map(toModuleInfo);
+  }
+
+  function dependencies(id) {
+    const record = records.get(normalizeLookupId(id));
+    return record ? [...record.dependencies] : [];
+  }
+
+  function dependents(id) {
+    const record = records.get(normalizeLookupId(id));
+    return record ? [...record.dependents] : [];
+  }
+
+  function getModuleInfo(id) {
+    const record = records.get(normalizeLookupId(id));
+    return record ? toModuleInfo(record) : undefined;
+  }
+
+  function getPrivateImports(id) {
+    const record = records.get(normalizeLookupId(id));
+    if (!record || record.kind !== "source") return undefined;
+    return new Map([...record.privateImports].map(([specifier, entry]) => [specifier, entry.definition]));
+  }
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    emit({ type: "runtime-disposed" });
+    rejectAllModuleWaiters(new ModuleRuntimeError("This browser-module-runtime instance was disposed while waiting for a module."));
+
+    for (const record of records.values()) {
+      revokeRecordUrl(record);
+      if (record.kind === "source") revokePrivateImportUrls(record);
+    }
+    records.clear();
+    hostNamespaces.clear();
+    globalRegistry.delete(runtimeId);
+    events.clear();
+  }
+
+  function resolvePublic(specifier, importer) {
+    return resolveSpecifier(specifier, importer ?? null);
+  }
+
+  function createInitialCompileCacheInfo() {
+    return {
+      enabled: Boolean(compileCacheConfig),
+      status: "none",
+      source: undefined,
+      key: undefined,
+      compilerFingerprint: undefined,
+      sourceHash: undefined,
+      compileContextHash: undefined,
+    };
+  }
+
+  function createCompileCacheManager() {
+    return {
+      enabled: Boolean(compileCacheConfig),
+      namespace: compileCacheConfig?.namespace,
+      version: compileCacheConfig?.version,
+      store: compileCacheConfig?.store?.kind ?? (compileCacheConfig ? "custom" : undefined),
+      async invalidate(id) {
+        assertActive();
+        if (!compileCacheConfig) return false;
+        const record = records.get(normalizeLookupId(id));
+        if (!record || record.kind !== "source") return false;
+
+        const identity = await createCompileIdentity(record);
+        if (!identity?.key) {
+          record.compiledArtifact = undefined;
+          record.compiledArtifactKey = undefined;
+          record.forceCompileRefresh = true;
+          return false;
+        }
+
+        memoryCompileArtifacts.delete(identity.key);
+        if (record.compiledArtifactKey === identity.key) {
+          record.compiledArtifact = undefined;
+          record.compiledArtifactKey = undefined;
+        }
+        record.forceCompileRefresh = true;
+        record.compileCacheInfo = createInitialCompileCacheInfo();
+
+        if (!compileCacheConfig || !identity.persistable) return false;
+        const physicalKey = compileCacheStorageKey(identity.key);
+        try {
+          const deleted = await compileCacheConfig.store.delete(physicalKey);
+          return deleted !== false;
+        } catch (error) {
+          emitCompileCacheError(record, "delete", error, identity);
+          throw error;
+        }
+      },
+      async clear(clearOptions = {}) {
+        assertActive();
+        if (!compileCacheConfig) return 0;
+        memoryCompileArtifacts.clear();
+        for (const record of records.values()) {
+          if (record.kind !== "source") continue;
+          record.compiledArtifact = undefined;
+          record.compiledArtifactKey = undefined;
+          record.forceCompileRefresh = true;
+          record.compileCacheInfo = createInitialCompileCacheInfo();
+        }
+
+        const prefix = clearOptions.allVersions === true
+          ? compileCacheNamespacePrefix()
+          : compileCacheVersionPrefix();
+        try {
+          if (typeof compileCacheConfig.store.clear === "function") {
+            return Number(await compileCacheConfig.store.clear({ prefix })) || 0;
+          }
+          if (typeof compileCacheConfig.store.entries === "function") {
+            const entries = await compileCacheConfig.store.entries({ prefix });
+            let count = 0;
+            for (const [key] of entries) {
+              await compileCacheConfig.store.delete(key);
+              count += 1;
+            }
+            return count;
+          }
+          throw new Error("Compile cache store does not support clear() or entries().");
+        } catch (error) {
+          emitCompileCacheError(undefined, "clear", error);
+          throw error;
+        }
+      },
+    };
+  }
+
+  async function ensureCompiledArtifact(record, requestedMode = "use") {
+    let mode = normalizeCompileCacheMode(requestedMode);
+    if (record.forceCompileRefresh && mode === "use") mode = "refresh";
+
+    if (mode === "use" && record.compiledArtifact) {
+      record.compileCacheInfo = {
+        ...record.compileCacheInfo,
+        status: "hit",
+        source: "record",
+      };
+      return record.compiledArtifact;
+    }
+
+    let identity;
+    let identityFailed = false;
+    if (compileCacheConfig) {
+      try {
+        identity = await createCompileIdentity(record);
+      } catch (error) {
+        identityFailed = true;
+        emitCompileCacheError(record, "identity", error);
+      }
+    }
+    const canUseSharedCache = Boolean(identity?.key && identity.persistable);
+
+    if (compileCacheConfig && identity && !identity.persistable) {
+      if (identity.reason === "missing-compiler-fingerprint" && !warnedMissingCompilerFingerprint) {
+        warnedMissingCompilerFingerprint = true;
+        globalThis.console?.warn?.(
+          "browser-module-runtime: persistent compile caching is disabled for this compiler because it does not provide a stable fingerprint.",
+        );
+      }
+      emit({
+        type: "compile-cache-bypass",
+        id: record.id,
+        key: identity?.key,
+        reason: identity.reason ?? "missing-compiler-fingerprint",
+        source: "compiler",
+        store: compileCacheConfig.store.kind ?? "custom",
+      });
+    } else if (compileCacheConfig && identityFailed) {
+      emit({
+        type: "compile-cache-bypass",
+        id: record.id,
+        reason: "identity-error",
+        source: "compiler",
+        store: compileCacheConfig.store.kind ?? "custom",
+      });
+    }
+
+    if (mode === "bypass") {
+      emit({
+        type: "compile-cache-bypass",
+        id: record.id,
+        key: identity?.key,
+        reason: "requested",
+        source: "compiler",
+        store: compileCacheConfig?.store?.kind,
+      });
+      const artifact = await compileFreshArtifact(record);
+      record.compiledArtifact = artifact;
+      record.compiledArtifactKey = undefined;
+      record.forceCompileRefresh = false;
+      record.diagnostics = [...(artifact.diagnostics ?? [])];
+      record.compileCacheInfo = compileCacheInfoFrom(identity, "bypass", "compiler");
+      return artifact;
+    }
+
+    if (mode === "refresh") {
+      emit({
+        type: "compile-cache-refresh",
+        id: record.id,
+        key: identity?.key,
+        source: "compiler",
+        store: compileCacheConfig?.store?.kind,
+      });
+    } else if (canUseSharedCache) {
+      const memoryArtifact = memoryCompileArtifacts.get(identity.key);
+      if (memoryArtifact) {
+        record.compiledArtifact = memoryArtifact;
+        record.compiledArtifactKey = identity.key;
+        record.forceCompileRefresh = false;
+        record.diagnostics = [...(memoryArtifact.diagnostics ?? [])];
+        record.compileCacheInfo = compileCacheInfoFrom(identity, "hit", "memory");
+        emit({
+          type: "compile-cache-hit",
+          id: record.id,
+          key: identity.key,
+          source: "memory",
+          store: "memory",
+          byteSize: approximateByteSize(memoryArtifact),
+        });
+        return memoryArtifact;
+      }
+
+      const started = now();
+      try {
+        const cachedRecord = await compileCacheConfig.store.get(compileCacheStorageKey(identity.key));
+        const durationMs = now() - started;
+        if (cachedRecord !== undefined) {
+          const validation = validateCachedCompileRecord(cachedRecord, identity);
+          if (validation.valid && !isCacheRecordExpired(cachedRecord)) {
+            const artifact = normalizeCompiledArtifact(cachedRecord.artifact);
+            memoryCompileArtifacts.set(identity.key, artifact);
+            record.compiledArtifact = artifact;
+            record.compiledArtifactKey = identity.key;
+            record.forceCompileRefresh = false;
+            record.diagnostics = [...(artifact.diagnostics ?? [])];
+            record.compileCacheInfo = compileCacheInfoFrom(identity, "hit", compileCacheConfig.store.kind ?? "persistent");
+            cachedRecord.lastUsedAt = Date.now();
+            emit({
+              type: "compile-cache-hit",
+              id: record.id,
+              key: identity.key,
+              source: compileCacheConfig.store.kind ?? "persistent",
+              store: compileCacheConfig.store.kind ?? "custom",
+              durationMs,
+              byteSize: cachedRecord.byteSize,
+            });
+            return artifact;
+          }
+
+          try {
+            await compileCacheConfig.store.delete(compileCacheStorageKey(identity.key));
+            emit({
+              type: "compile-cache-evict",
+              id: record.id,
+              key: identity.key,
+              reason: validation.valid ? "maxAge" : "invalid",
+              store: compileCacheConfig.store.kind ?? "custom",
+            });
+          } catch (error) {
+            emitCompileCacheError(record, "delete", error, identity);
+          }
+        }
+
+        emit({
+          type: "compile-cache-miss",
+          id: record.id,
+          key: identity.key,
+          source: compileCacheConfig.store.kind ?? "persistent",
+          store: compileCacheConfig.store.kind ?? "custom",
+          durationMs,
+        });
+      } catch (error) {
+        emitCompileCacheError(record, "read", error, identity);
+        try { await compileCacheConfig.store.delete(compileCacheStorageKey(identity.key)); } catch {}
+      }
+    }
+
+    const inFlightKey = canUseSharedCache ? identity.key : undefined;
+    if (mode === "use" && inFlightKey && inFlightCompiles.has(inFlightKey)) {
+      const artifact = await inFlightCompiles.get(inFlightKey);
+      record.compiledArtifact = artifact;
+      record.compiledArtifactKey = inFlightKey;
+      record.forceCompileRefresh = false;
+      record.diagnostics = [...(artifact.diagnostics ?? [])];
+      record.compileCacheInfo = compileCacheInfoFrom(identity, "hit", "inflight");
+      return artifact;
+    }
+
+    const compilePromise = compileFreshArtifact(record);
+    if (inFlightKey) inFlightCompiles.set(inFlightKey, compilePromise);
+
+    let artifact;
+    try {
+      artifact = await compilePromise;
+    } finally {
+      if (inFlightKey && inFlightCompiles.get(inFlightKey) === compilePromise) inFlightCompiles.delete(inFlightKey);
+    }
+
+    record.compiledArtifact = artifact;
+    record.compiledArtifactKey = canUseSharedCache ? identity.key : undefined;
+    record.forceCompileRefresh = false;
+    record.diagnostics = [...(artifact.diagnostics ?? [])];
+    record.compileCacheInfo = compileCacheInfoFrom(identity, mode === "refresh" ? "refresh" : "miss", "compiler");
+
+    if (canUseSharedCache) {
+      memoryCompileArtifacts.set(identity.key, artifact);
+      const persistentRecord = {
+        schema: COMPILED_ARTIFACT_SCHEMA,
+        key: identity.key,
+        artifactAbi: COMPILED_ARTIFACT_ABI,
+        sourceHash: identity.sourceHash,
+        format: record.format,
+        compilerFingerprint: identity.compilerFingerprint,
+        compileContextHash: identity.compileContextHash,
+        artifact,
+        createdAt: Date.now(),
+        lastUsedAt: Date.now(),
+      };
+      persistentRecord.byteSize = approximateByteSize(persistentRecord);
+
+      await writePersistentCompileRecord(record, identity, persistentRecord);
+    }
+
+    return artifact;
+  }
+
+  async function compileFreshArtifact(record) {
+    try {
+      let artifact;
+      const context = { id: record.id, format: record.format };
+      if (typeof compiler.compile === "function") {
+        artifact = await compiler.compile(record.source, context);
+      } else {
+        let code = record.source;
+        let diagnostics = [];
+        let sourceMap;
+        if (record.format !== "js") {
+          const transformed = await compiler.transform(record.source, {
+            ...context,
+            htmlImportSource: "@solidjs/html",
+          });
+          code = transformed.code;
+          diagnostics = [...(transformed.diagnostics ?? [])];
+          sourceMap = transformed.sourceMap;
+        }
+        const analysis = await compiler.analyze(code, context);
+        artifact = {
+          schema: COMPILED_ARTIFACT_SCHEMA,
+          code,
+          imports: analysis.imports ?? [],
+          diagnostics,
+          ...(sourceMap == null ? {} : { sourceMap }),
+        };
+      }
+      return normalizeCompiledArtifact(artifact);
+    } catch (error) {
+      record.state = "error";
+      const wrapped = error instanceof ModuleCompileError ? error : new ModuleCompileError(record.id, error);
+      emitError(record, "compile", wrapped);
+      throw wrapped;
+    }
+  }
+
+  async function createCompileIdentity(record) {
+    const context = { id: record.id, format: record.format };
+    let compilerFingerprint;
+    try {
+      const fingerprint = typeof compiler.fingerprint === "function"
+        ? await compiler.fingerprint(context)
+        : compiler.fingerprint;
+      if (typeof fingerprint === "string" && fingerprint) compilerFingerprint = fingerprint;
+    } catch (error) {
+      emitCompileCacheError(record, "fingerprint", error);
+      return {
+        key: undefined,
+        persistable: false,
+        reason: "fingerprint-error",
+        compilerFingerprint: undefined,
+        format: record.format,
+      };
+    }
+
+    const sourceHash = await sha256(record.source);
+    const cacheContext = typeof compiler.cacheContext === "function"
+      ? await compiler.cacheContext(context)
+      : { format: record.format };
+    const compileContextHash = await sha256(stableSerialize(cacheContext ?? {}));
+
+    const persistable = Boolean(compilerFingerprint);
+    if (!persistable) {
+      return {
+        key: undefined,
+        persistable: false,
+        reason: "missing-compiler-fingerprint",
+        compilerFingerprint: undefined,
+        sourceHash,
+        compileContextHash,
+        format: record.format,
+      };
+    }
+
+    const key = await sha256(stableSerialize({
+      artifactAbi: COMPILED_ARTIFACT_ABI,
+      compilerFingerprint,
+      format: record.format,
+      compileContextHash,
+      sourceHash,
+    }));
+
+    return {
+      key,
+      persistable: true,
+      compilerFingerprint,
+      sourceHash,
+      compileContextHash,
+      format: record.format,
+    };
+  }
+
+  function compileCacheInfoFrom(identity, status, source) {
+    return {
+      enabled: Boolean(compileCacheConfig),
+      status,
+      source,
+      key: identity?.key,
+      compilerFingerprint: identity?.compilerFingerprint,
+      sourceHash: identity?.sourceHash,
+      compileContextHash: identity?.compileContextHash,
+    };
+  }
+
+  function validateCachedCompileRecord(cachedRecord, identity) {
+    if (!cachedRecord || typeof cachedRecord !== "object") return { valid: false, reason: "record" };
+    if (cachedRecord.schema !== COMPILED_ARTIFACT_SCHEMA) return { valid: false, reason: "schema" };
+    if (cachedRecord.artifactAbi !== COMPILED_ARTIFACT_ABI) return { valid: false, reason: "artifact-abi" };
+    if (cachedRecord.key !== identity.key) return { valid: false, reason: "key" };
+    if (cachedRecord.sourceHash !== identity.sourceHash) return { valid: false, reason: "source-hash" };
+    if (cachedRecord.format !== identity.format) return { valid: false, reason: "format" };
+    if (cachedRecord.compilerFingerprint !== identity.compilerFingerprint) return { valid: false, reason: "compiler-fingerprint" };
+    if (cachedRecord.compileContextHash !== identity.compileContextHash) return { valid: false, reason: "compile-context" };
+    try {
+      normalizeCompiledArtifact(cachedRecord.artifact);
+    } catch {
+      return { valid: false, reason: "artifact" };
+    }
+    return { valid: true };
+  }
+
+  function isCacheRecordExpired(cachedRecord) {
+    const maxAge = compileCacheConfig?.maxAge;
+    return Number.isFinite(maxAge) && maxAge >= 0 && Date.now() - Number(cachedRecord.createdAt ?? 0) > maxAge;
+  }
+
+  async function writePersistentCompileRecord(record, identity, persistentRecord) {
+    const storageKey = compileCacheStorageKey(identity.key);
+    try {
+      await compileCacheConfig.store.set(storageKey, persistentRecord);
+    } catch (error) {
+      if (!isQuotaError(error)) {
+        emitCompileCacheError(record, "write", error, identity);
+        return false;
+      }
+
+      await pruneCompileCache(record, { quotaRecovery: true });
+      try {
+        await compileCacheConfig.store.set(storageKey, persistentRecord);
+      } catch (retryError) {
+        emitCompileCacheError(record, "write", retryError, identity);
+        return false;
+      }
+    }
+
+    emit({
+      type: "compile-cache-write",
+      id: record.id,
+      key: identity.key,
+      source: "compiler",
+      store: compileCacheConfig.store.kind ?? "custom",
+      byteSize: persistentRecord.byteSize,
+    });
+    await pruneCompileCache(record);
+    return true;
+  }
+
+  async function pruneCompileCache(record, pruneOptions = {}) {
+    if (!compileCacheConfig || typeof compileCacheConfig.store.entries !== "function") return 0;
+    const { maxEntries, maxBytes, maxAge } = compileCacheConfig;
+    const quotaRecovery = pruneOptions.quotaRecovery === true;
+    if (!quotaRecovery && !Number.isFinite(maxEntries) && !Number.isFinite(maxBytes) && !Number.isFinite(maxAge)) return 0;
+
+    try {
+      const entries = await compileCacheConfig.store.entries({ prefix: compileCacheVersionPrefix() });
+      const nowValue = Date.now();
+      const live = [];
+      let evicted = 0;
+      for (const [key, value] of entries) {
+        if (Number.isFinite(maxAge) && maxAge >= 0 && nowValue - Number(value?.createdAt ?? 0) > maxAge) {
+          await compileCacheConfig.store.delete(key);
+          evicted += 1;
+          emit({ type: "compile-cache-evict", id: record?.id, key: value?.key, reason: "maxAge", store: compileCacheConfig.store.kind ?? "custom" });
+          continue;
+        }
+        live.push([key, value]);
+      }
+
+      live.sort((a, b) => Number(a[1]?.lastUsedAt ?? a[1]?.createdAt ?? 0) - Number(b[1]?.lastUsedAt ?? b[1]?.createdAt ?? 0));
+      let totalBytes = live.reduce((sum, [, value]) => sum + Number(value?.byteSize ?? 0), 0);
+
+      while (
+        (Number.isFinite(maxEntries) && live.length > maxEntries) ||
+        (Number.isFinite(maxBytes) && totalBytes > maxBytes)
+      ) {
+        const [key, value] = live.shift();
+        await compileCacheConfig.store.delete(key);
+        totalBytes -= Number(value?.byteSize ?? 0);
+        evicted += 1;
+        emit({
+          type: "compile-cache-evict",
+          id: record?.id,
+          key: value?.key,
+          reason: Number.isFinite(maxEntries) && live.length + 1 > maxEntries ? "maxEntries" : "maxBytes",
+          store: compileCacheConfig.store.kind ?? "custom",
+          byteSize: value?.byteSize,
+        });
+      }
+
+      if (quotaRecovery && evicted === 0 && live.length > 0) {
+        const removeCount = Math.max(1, Math.ceil(live.length * 0.1));
+        for (let index = 0; index < removeCount && live.length > 0; index += 1) {
+          const [key, value] = live.shift();
+          await compileCacheConfig.store.delete(key);
+          evicted += 1;
+          emit({
+            type: "compile-cache-evict",
+            id: record?.id,
+            key: value?.key,
+            reason: "quota",
+            store: compileCacheConfig.store.kind ?? "custom",
+            byteSize: value?.byteSize,
+          });
+        }
+      }
+      return evicted;
+    } catch (error) {
+      emitCompileCacheError(record, "prune", error);
+      return 0;
+    }
+  }
+
+  function emitCompileCacheError(record, operation, error, identity) {
+    emit({
+      type: "compile-cache-error",
+      id: record?.id,
+      key: identity?.key,
+      operation,
+      store: compileCacheConfig?.store?.kind ?? (compileCacheConfig ? "custom" : undefined),
+      error,
+    });
+  }
+
+  function compileCacheNamespacePrefix() {
+    return `browser-module-runtime/compile/${encodeURIComponent(compileCacheConfig.namespace)}/`;
+  }
+
+  function compileCacheVersionPrefix() {
+    return `${compileCacheNamespacePrefix()}${encodeURIComponent(compileCacheConfig.version)}/`;
+  }
+
+  function compileCacheStorageKey(key) {
+    return `${compileCacheVersionPrefix()}${key}`;
+  }
+
+  async function ensureSourceUrl(record, stack, linkOptions = {}) {
+    if (record.url) return record.url;
+
+    if (stack.includes(record.id)) {
+      const cycleStart = stack.indexOf(record.id);
+      const error = new CircularDependencyError([...stack.slice(cycleStart), record.id]);
+      emitError(record, "link", error);
+      throw error;
+    }
+
+    const nextStack = [...stack, record.id];
+    record.state = "linking";
+    emit({
+      type: "module-linking",
+      id: record.id,
+      kind: record.kind,
+      version: record.version,
+    });
+
+    const artifact = await ensureCompiledArtifact(record, linkOptions.cacheMode ?? "use");
+    const resolvedImports = [];
+    const linkedDependencies = [];
+    const nextDependencies = new Set();
+
+    for (const reference of artifact.imports ?? []) {
+      let resolution;
+      try {
+        resolution = resolveSpecifierDetailed(reference.specifier, record.id);
+      } catch (error) {
+        record.state = "error";
+        emitError(record, "resolve", error);
+        throw error;
+      }
+
+      const { resolved, resolutionKind } = resolution;
+      const dependencyRecord = resolutionKind === "private" ? undefined : records.get(resolved);
+      let replacement = resolved;
+
+      try {
+        if (resolutionKind === "private") {
+          replacement = await ensurePrivateHostUrl(
+            record,
+            reference.specifier,
+            nextStack,
+            nextDependencies,
+            [],
+          );
+        } else if (dependencyRecord) {
+          nextDependencies.add(dependencyRecord.id);
+
+          if (dependencyRecord.kind === "source") {
+            replacement = await ensureSourceUrl(dependencyRecord, nextStack, { cacheMode: "use" });
+          } else if (dependencyRecord.kind === "host") {
+            replacement = await ensureHostUrl(dependencyRecord);
+          } else {
+            replacement = dependencyRecord.externalUrl;
+          }
+        } else if (isRelativeSpecifier(reference.specifier) || reference.specifier.startsWith("/")) {
+          throw new ModuleResolutionError(reference.specifier, record.id);
+        } else if (!allowNativeImports && !isAbsoluteUrl(resolved)) {
+          throw new ModuleResolutionError(reference.specifier, record.id);
+        }
+      } catch (error) {
+        record.state = "error";
+        emitError(record, error instanceof ModuleResolutionError ? "resolve" : "link", error);
+        throw error;
+      }
+
+      resolvedImports.push({ ...reference, replacement });
+      linkedDependencies.push({
+        specifier: reference.specifier,
+        resolvedId: dependencyRecord?.id ?? resolved,
+      });
+    }
+
+    let linkedSource;
+    try {
+      linkedSource = applyImportReplacements(artifact.code, resolvedImports);
+      syncDependencyEdges(record, nextDependencies);
+      emit({
+        type: "module-linked",
+        id: record.id,
+        kind: record.kind,
+        version: record.version,
+        dependencies: linkedDependencies,
+        module: toModuleInfo(record),
+      });
+      record.compiledCode = linkedSource;
+      record.diagnostics = [...(artifact.diagnostics ?? [])];
+    } catch (error) {
+      record.state = "error";
+      emitError(record, error instanceof ModuleResolutionError ? "resolve" : "link", error);
+      throw error;
+    }
+
+    try {
+      record.url = moduleUrlBackend.create(appendSourceUrl(record.compiledCode, record.id));
+    } catch (error) {
+      record.state = "error";
+      emitError(record, "url-create", error);
+      throw error;
+    }
+    record.state = "compiled";
+    emit({
+      type: "module-compiled",
+      id: record.id,
+      kind: record.kind,
+      version: record.version,
+      module: toModuleInfo(record),
+    });
+    return record.url;
+  }
+
+  async function ensureHostUrl(record) {
+    if (record.url) return record.url;
+
+    const namespace = hostNamespaces.get(record.id);
+    try {
+      record.url = moduleUrlBackend.create(appendSourceUrl(
+        createHostBridgeSource(record.id, namespace, `Host module ${record.id} is unavailable.`),
+        `host:${record.id}`,
+      ));
+    } catch (error) {
+      emitError(record, "host-bridge", error);
+      throw error;
+    }
+    return record.url;
+  }
+
+  async function ensurePrivateHostUrl(importerRecord, specifier, stack, nextDependencies, providerStack) {
+    const entry = importerRecord.privateImports?.get(specifier);
+    if (!entry) throw new ModuleResolutionError(specifier, importerRecord.id);
+    if (entry.url) {
+      for (const dependencyId of entry.dependencies ?? []) nextDependencies?.add(dependencyId);
+      return entry.url;
+    }
+
+    const namespace = await resolvePrivateImportNamespace(
+      importerRecord,
+      specifier,
+      entry,
+      stack,
+      nextDependencies,
+      providerStack,
+    );
+    const registryKey = `${importerRecord.id}\u0000${specifier}\u0000${importerRecord.version}`;
+    entry.registryKey = registryKey;
+    hostNamespaces.set(registryKey, namespace);
+
+    try {
+      entry.url = moduleUrlBackend.create(appendSourceUrl(
+        createHostBridgeSource(
+          registryKey,
+          namespace,
+          `Private import ${specifier} for ${importerRecord.id} is unavailable.`,
+        ),
+        `private:${importerRecord.id}:${specifier}`,
+      ));
+    } catch (error) {
+      hostNamespaces.delete(registryKey);
+      entry.registryKey = undefined;
+      emitError(importerRecord, "host-bridge", error);
+      throw error;
+    }
+    return entry.url;
+  }
+
+  async function resolvePrivateImportNamespace(importerRecord, specifier, entry, stack, nextDependencies, providerStack) {
+    if (entry.kind === "static") return entry.namespace;
+
+    if (entry.resolved) {
+      for (const dependencyId of entry.dependencies) nextDependencies?.add(dependencyId);
+      return entry.namespace;
+    }
+
+    if (entry.kind === "promise") {
+      if (!entry.promise) {
+        entry.promise = Promise.resolve(entry.definition).then(namespace => {
+          validatePrivateImportNamespace(namespace, specifier, importerRecord.id, "Promise private import");
+          entry.namespace = namespace;
+          entry.resolved = true;
+          return namespace;
+        }).catch(error => {
+          entry.promise = undefined;
+          throw error;
+        });
+      }
+      return entry.promise;
+    }
+
+    const providerKey = `${importerRecord.id}::${specifier}`;
+    if (providerStack.includes(providerKey)) {
+      const cycleStart = providerStack.indexOf(providerKey);
+      throw new CircularDependencyError([
+        ...providerStack.slice(cycleStart).map(key => `private:${key}`),
+        `private:${providerKey}`,
+      ]);
+    }
+
+    if (!entry.promise) {
+      const nextProviderStack = [...providerStack, providerKey];
+      entry.promise = (async () => {
+        const providerDependencies = new Set();
+        const context = {
+          runtime: api,
+          importer: importerRecord.id,
+          import: async requested => importPrivateProviderDependency(
+            requested,
+            importerRecord,
+            stack,
+            providerDependencies,
+            nextProviderStack,
+          ),
+          waitForModule: async (requested, waitOptions) => importPrivateProviderWaitForModule(
+            requested,
+            importerRecord,
+            stack,
+            providerDependencies,
+            nextProviderStack,
+            waitOptions,
+          ),
+        };
+
+        let namespace;
+        try {
+          namespace = await entry.definition(context);
+        } catch (error) {
+          entry.promise = undefined;
+          throw error;
+        }
+
+        try {
+          validatePrivateImportNamespace(namespace, specifier, importerRecord.id, "Private import provider");
+        } catch (error) {
+          entry.promise = undefined;
+          throw error;
+        }
+
+        entry.namespace = namespace;
+        entry.resolved = true;
+        entry.dependencies = providerDependencies;
+        return namespace;
+      })();
+    }
+
+    const namespace = await entry.promise;
+    for (const dependencyId of entry.dependencies) nextDependencies?.add(dependencyId);
+    return namespace;
+  }
+
+  async function importPrivateProviderDependency(specifier, importerRecord, stack, providerDependencies, providerStack) {
+    const raw = String(specifier);
+    const { resolved, resolutionKind } = resolveSpecifierDetailed(raw, importerRecord.id);
+
+    if (resolutionKind === "private") {
+      const entry = importerRecord.privateImports?.get(raw);
+      if (!entry) throw new ModuleResolutionError(raw, importerRecord.id);
+      return resolvePrivateImportNamespace(
+        importerRecord,
+        raw,
+        entry,
+        stack,
+        providerDependencies,
+        providerStack,
+      );
+    }
+
+    const dependencyRecord = records.get(resolved);
+    if (dependencyRecord) {
+      providerDependencies.add(dependencyRecord.id);
+      return importRecord(dependencyRecord, stack);
+    }
+
+    if (isRelativeSpecifier(raw) || raw.startsWith("/")) {
+      throw new ModuleResolutionError(raw, importerRecord.id);
+    }
+    if (!allowNativeImports && !isAbsoluteUrl(resolved)) {
+      throw new ModuleResolutionError(raw, importerRecord.id);
+    }
+    return import(resolved);
+  }
+
+  async function importPrivateProviderWaitForModule(specifier, importerRecord, stack, providerDependencies, providerStack, waitOptions) {
+    const raw = String(specifier);
+    return waitForRegisteredModule(raw, importerRecord.id, waitOptions, async dependencyRecord => {
+      providerDependencies.add(dependencyRecord.id);
+      return importRecord(dependencyRecord, stack);
+    });
+  }
+
+  function createHostBridgeSource(registryKey, namespace, unavailableMessage) {
+    const exportNames = Object.keys(namespace ?? {}).filter(name => name !== "default" && isIdentifierName(name));
+    const lines = [
+      `const __registry = globalThis[${JSON.stringify(HOST_REGISTRY_KEY)}];`,
+      `const __runtime = __registry && __registry.get(${JSON.stringify(runtimeId)});`,
+      `const __module = __runtime && __runtime.get(${JSON.stringify(registryKey)});`,
+      `if (!__module) throw new Error(${JSON.stringify(unavailableMessage)});`,
+    ];
+
+    exportNames.forEach((name, index) => {
+      lines.push(`const __export${index} = __module[${JSON.stringify(name)}];`);
+    });
+
+    if (namespace && Object.prototype.hasOwnProperty.call(namespace, "default")) {
+      lines.push("export default __module.default;");
+    }
+
+    if (exportNames.length) {
+      lines.push(`export { ${exportNames.map((name, index) => `__export${index} as ${name}`).join(", ")} };`);
+    }
+    return lines.join("\n");
+  }
+
+  function resolveSpecifier(specifier, importer) {
+    return resolveSpecifierDetailed(specifier, importer).resolved;
+  }
+
+  function resolveSpecifierDetailed(specifier, importer) {
+    const raw = String(specifier);
+    emit({
+      type: "module-resolving",
+      specifier: raw,
+      importer: importer ?? null,
+    });
+
+    let resolved;
+    let resolutionKind;
+
+    try {
+      const pin = packagePolicy.inspect(raw);
+      if (typeof customResolve === "function") {
+        const custom = customResolve(raw, importer, api);
+        if (typeof custom === "string" && custom) {
+          const target = normalizeResolved(custom, importer);
+          if (pin && target !== pin.url) {
+            throw new PackageVersionResolutionError("PACKAGE_VERSION_CONFLICT", `Custom resolver returned ${JSON.stringify(target)} for pinned import ${JSON.stringify(raw)}, expected ${JSON.stringify(pin.url)}.`, { specifier: raw, importer, expected: pin.url, actual: target });
+          }
+          resolved = target;
+          resolutionKind = "custom";
+        }
+      }
+
+      if (resolved == null && importer) {
+        const importerRecord = records.get(normalizeLookupId(importer));
+        if (importerRecord?.kind === "source" && importerRecord.privateImports?.has(raw)) {
+          resolved = raw;
+          resolutionKind = "private";
+        }
+      }
+
+      if (resolved == null && records.has(raw)) {
+        resolved = raw;
+        resolutionKind = "registered";
+      }
+      if (resolved == null && isAbsoluteUrl(raw)) {
+        resolved = raw;
+        resolutionKind = "url";
+      }
+      if (resolved == null && raw.startsWith("/")) {
+        resolved = normalizePath(raw);
+        resolutionKind = "absolute";
+      }
+      if (resolved == null && isRelativeSpecifier(raw)) {
+        if (!importer) resolved = normalizePath(`/${raw}`);
+        else if (isAbsoluteUrl(importer)) resolved = new URL(raw, importer).href;
+        else resolved = normalizePath(`${dirname(importer)}/${raw}`);
+        resolutionKind = "relative";
+      }
+      if (resolved == null && pin) {
+        resolved = pin.url;
+        resolutionKind = pin.kind;
+      }
+      if (resolved == null && isBareSpecifier(raw) && typeof customFallbackResolve === "function") {
+        const fallback = customFallbackResolve(raw, importer, api);
+        if (typeof fallback === "string" && fallback) {
+          const fallbackResolved = normalizeResolved(fallback, importer);
+
+          // fallbackResolve() is allowed to redirect a bare specifier to a
+          // runtime-owned virtual module, but missing virtual paths must keep
+          // the runtime's normal no-network-fallback semantics. Resolver hooks
+          // are deliberately not re-entered for the returned target.
+          if ((fallback.startsWith("/") || isRelativeSpecifier(fallback)) && !records.has(fallbackResolved)) {
+            throw new ModuleResolutionError(
+              raw,
+              importer,
+              `fallbackResolve() returned unresolved virtual module ${JSON.stringify(fallback)} for ${JSON.stringify(raw)} from ${JSON.stringify(importer ?? "<runtime>")}.`,
+            );
+          }
+
+          resolved = fallbackResolved;
+          resolutionKind = "fallback";
+        }
+      }
+      if (resolved == null) {
+        resolved = raw;
+        resolutionKind = "native";
+      }
+    } catch (error) {
+      throw error;
+    }
+
+    emit({
+      type: "module-resolved",
+      specifier: raw,
+      importer: importer ?? null,
+      resolvedId: resolved,
+      resolutionKind,
+    });
+    return { resolved, resolutionKind };
+  }
+
+  function syncDependencyEdges(record, nextDependencies) {
+    for (const previous of record.dependencies) {
+      if (!nextDependencies.has(previous)) records.get(previous)?.dependents.delete(record.id);
+    }
+
+    for (const next of nextDependencies) records.get(next)?.dependents.add(record.id);
+    record.dependencies = nextDependencies;
+  }
+
+  function revokeRecordUrl(record) {
+    if (!record?.url) return;
+    try {
+      moduleUrlBackend.revoke?.(record.url);
+    } finally {
+      record.url = undefined;
+    }
+  }
+
+  function revokePrivateImportUrls(record) {
+    for (const entry of record?.privateImports?.values?.() ?? []) {
+      if (entry.url) {
+        try {
+          moduleUrlBackend.revoke?.(entry.url);
+        } finally {
+          entry.url = undefined;
+        }
+      }
+      if (entry.registryKey) {
+        hostNamespaces.delete(entry.registryKey);
+        entry.registryKey = undefined;
+      }
+      if (entry.kind !== "static") {
+        entry.namespace = undefined;
+        entry.promise = undefined;
+        entry.resolved = false;
+        entry.dependencies = new Set();
+      }
+    }
+  }
+
+  function emit(event) {
+    if (events.size === 0) return;
+    const payload = {
+      runtimeId,
+      timestamp: Date.now(),
+      ...event,
+    };
+    if (eventBufferDepth > 0) {
+      eventBuffer.push(payload);
+      return;
+    }
+    events.emit(payload);
+  }
+
+  function flushEventBuffer() {
+    if (eventBuffer.length === 0) return;
+    const pending = eventBuffer.splice(0, eventBuffer.length);
+    for (const event of pending) events.emit(event);
+  }
+
+  function emitError(record, phase, error) {
+    emit({
+      type: "module-error",
+      id: record?.id,
+      kind: record?.kind,
+      version: record?.version,
+      phase,
+      error,
+    });
+  }
+
+  function toModuleInfo(record) {
+    return {
+      id: record.id,
+      kind: record.kind,
+      state: record.state,
+      version: record.version,
+      format: record.format,
+      dependencies: [...record.dependencies],
+      dependents: [...record.dependents],
+      url: record.kind === "url" ? record.externalUrl : record.url,
+      diagnostics: [...(record.diagnostics ?? [])],
+      ...(record.kind === "source" ? {
+        compileCache: { ...record.compileCacheInfo },
+        privateImports: [...record.privateImports].map(([specifier, entry]) => ({
+          specifier,
+          shadowsRuntimeModule: records.has(specifier),
+          kind: entry.kind,
+          resolved: entry.resolved,
+          ...(entry.kind === "provider" ? { provider: true } : {}),
+          ...(entry.kind !== "static" ? { dependencies: [...entry.dependencies] } : {}),
+        })),
+      } : {}),
+    };
+  }
+}
+
+function normalizePrivateImports(value, moduleId) {
+  if (value == null) return new Map();
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`Private imports for ${JSON.stringify(moduleId)} must be an object keyed by # specifiers.`);
+  }
+
+  const result = new Map();
+  for (const [specifier, definition] of Object.entries(value)) {
+    if (!specifier.startsWith("#") || specifier.length < 2) {
+      throw new TypeError(
+        `Private import ${JSON.stringify(specifier)} for ${JSON.stringify(moduleId)} must use a #-prefixed specifier.`,
+      );
+    }
+
+    const provider = isPrivateImportProviderDefinition(definition);
+    const promise = !provider && isPromiseLike(definition);
+    const kind = provider ? "provider" : promise ? "promise" : "static";
+    if (kind === "static" && (typeof definition !== "object" || definition === null) && typeof definition !== "function") {
+      throw new TypeError(
+        `Private import ${JSON.stringify(specifier)} for ${JSON.stringify(moduleId)} must be a namespace object, PromiseLike namespace, or lazy provider function.`,
+      );
+    }
+
+    result.set(specifier, {
+      definition,
+      provider,
+      kind,
+      namespace: kind === "static" ? definition : undefined,
+      resolved: kind === "static",
+      promise: undefined,
+      dependencies: new Set(),
+      url: undefined,
+      registryKey: undefined,
+    });
+  }
+  return result;
+}
+
+function isPrivateImportProviderDefinition(value) {
+  if (typeof value !== "function") return false;
+
+  // Callable namespace objects with explicit own exports keep the 0.0.27
+  // static-namespace behavior. A plain function with no namespace-shaped own
+  // exports is interpreted as the new lazy sync/async provider form.
+  return Object.keys(value).length === 0 && !Object.prototype.hasOwnProperty.call(value, "default");
+}
+
+function isPromiseLike(value) {
+  return value != null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+
+function validatePrivateImportNamespace(namespace, specifier, importer, label) {
+  if ((typeof namespace !== "object" || namespace === null) && typeof namespace !== "function") {
+    throw new TypeError(
+      `${label} ${JSON.stringify(specifier)} for ${JSON.stringify(importer)} must resolve to an object, function, or ES module namespace-like value.`,
+    );
+  }
+}
+
+function normalizeWaitForModuleId(id, importer) {
+  const raw = String(id);
+  if (isAbsoluteUrl(raw) || isBareSpecifier(raw)) return raw;
+  if (raw.startsWith("/")) return normalizePath(raw);
+  if (isRelativeSpecifier(raw) && importer) {
+    if (isAbsoluteUrl(importer)) return new URL(raw, importer).href;
+    return normalizePath(`${dirname(importer)}/${raw}`);
+  }
+  return normalizePath(`/${raw}`);
+}
+
+function normalizeWaitForModuleOptions(options) {
+  if (options == null) return { timeout: undefined, signal: undefined };
+  if (typeof options !== "object") throw new TypeError("waitForModule() options must be an object.");
+
+  let timeout;
+  if (options.timeout != null) {
+    timeout = Number(options.timeout);
+    if (!Number.isFinite(timeout) || timeout < 0) {
+      throw new TypeError("waitForModule() timeout must be a finite number greater than or equal to 0 milliseconds.");
+    }
+  }
+
+  const signal = options.signal;
+  if (signal != null && (typeof signal !== "object" || typeof signal.addEventListener !== "function" || typeof signal.removeEventListener !== "function")) {
+    throw new TypeError("waitForModule() signal must be an AbortSignal.");
+  }
+  return { timeout, signal };
+}
+
+function createAbortError(signal) {
+  if (signal?.reason !== undefined) return signal.reason;
+  if (typeof DOMException === "function") return new DOMException("The operation was aborted.", "AbortError");
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}
+
+function privateImportDefinitions(record) {
+  const result = {};
+  for (const [specifier, entry] of record?.privateImports ?? []) result[specifier] = entry.definition;
+  return result;
+}
+
+function getHostRegistry() {
+  let registry = globalThis[HOST_REGISTRY_KEY];
+  if (!(registry instanceof Map)) {
+    registry = new Map();
+    Object.defineProperty(globalThis, HOST_REGISTRY_KEY, {
+      value: registry,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return registry;
+}
+
+function applyImportReplacements(source, references) {
+  const replacements = references
+    .map(reference => ({
+      start: reference.start,
+      end: reference.end,
+      text: JSON.stringify(reference.replacement),
+    }))
+    .sort((a, b) => b.start - a.start);
+
+  let output = source;
+  for (const replacement of replacements) {
+    output = output.slice(0, replacement.start) + replacement.text + output.slice(replacement.end);
+  }
+  return output;
+}
+
+function normalizeDefinedId(id) {
+  const value = String(id);
+  if (isAbsoluteUrl(value) || isBareSpecifier(value)) return value;
+  if (value.startsWith("/")) return normalizePath(value);
+  return normalizePath(`/${value}`);
+}
+
+function normalizeLookupId(id) {
+  const value = String(id);
+  if (isAbsoluteUrl(value) || isBareSpecifier(value)) return value;
+  if (value.startsWith("/")) return normalizePath(value);
+  return normalizePath(`/${value}`);
+}
+
+function normalizeResolved(value, importer) {
+  if (isAbsoluteUrl(value) || isBareSpecifier(value)) return value;
+  if (value.startsWith("/")) return normalizePath(value);
+  if (isRelativeSpecifier(value) && importer) {
+    if (isAbsoluteUrl(importer)) return new URL(value, importer).href;
+    return normalizePath(`${dirname(importer)}/${value}`);
+  }
+  return normalizePath(`/${value}`);
+}
+
+function isBareSpecifier(value) {
+  return !value.startsWith(".") && !value.startsWith("/") && !isAbsoluteUrl(value);
+}
+
+function isRelativeSpecifier(value) {
+  return value === "." || value === ".." || value.startsWith("./") || value.startsWith("../");
+}
+
+function isAbsoluteUrl(value) {
+  return /^[A-Za-z][A-Za-z\d+.-]*:/.test(value);
+}
+
+function dirname(id) {
+  const index = id.lastIndexOf("/");
+  return index <= 0 ? "/" : id.slice(0, index);
+}
+
+function normalizePath(path) {
+  const absolute = path.startsWith("/");
+  const parts = [];
+
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      parts.pop();
+    } else {
+      parts.push(part);
+    }
+  }
+
+  return `${absolute ? "/" : ""}${parts.join("/")}` || "/";
+}
+
+function isIdentifierName(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+
+function appendSourceUrl(code, id) {
+  return `${code}\n//# sourceURL=${sanitizeSourceUrl(id)}`;
+}
+
+function sanitizeSourceUrl(id) {
+  return `browser-module-runtime:${String(id).replace(/[\r\n]/g, "")}`;
+}
+
+function randomId() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
+  return Math.random().toString(36).slice(2);
+}
+
+function normalizeCompileCacheAlias(options) {
+  const hasCache = Object.prototype.hasOwnProperty.call(options ?? {}, "cache");
+  const hasCompileCache = Object.prototype.hasOwnProperty.call(options ?? {}, "compileCache")
+    && options.compileCache !== undefined;
+  if (hasCache && hasCompileCache) {
+    throw new TypeError("createRuntime() received both cache and compileCache. Use compileCache as the canonical option.");
+  }
+  if (!hasCache) return options?.compileCache;
+  if (options.cache !== true && options.cache !== false && options.cache != null) {
+    throw new TypeError("createRuntime().cache must be true or false.");
+  }
+  return options.cache ?? false;
+}
+
+function normalizeCompileCacheOptions(options) {
+  if (options == null || options === false) return undefined;
+  if (options === true) options = createCompileCache();
+  if (typeof options !== "object") {
+    throw new TypeError("compileCache must be true, false, or an options object with a store.");
+  }
+  if (options.enabled === false) return undefined;
+  const store = options.store;
+  if (!store || typeof store.get !== "function" || typeof store.set !== "function" || typeof store.delete !== "function") {
+    throw new TypeError("compileCache.store must provide async get(), set(), and delete() methods.");
+  }
+  return {
+    store,
+    namespace: String(options.namespace ?? "default"),
+    version: String(options.version ?? "1"),
+    maxEntries: normalizeLimit(options.maxEntries),
+    maxBytes: normalizeLimit(options.maxBytes),
+    maxAge: normalizeLimit(options.maxAge),
+  };
+}
+
+function normalizeCompileCacheMode(mode) {
+  if (mode == null) return "use";
+  if (mode === "use" || mode === "refresh" || mode === "bypass") return mode;
+  throw new TypeError(`Unknown compile cache mode ${JSON.stringify(mode)}. Expected "use", "refresh", or "bypass".`);
+}
+
+function normalizeCompiledArtifact(artifact) {
+  if (!artifact || typeof artifact !== "object") {
+    throw new TypeError("Compiler returned an invalid compiled artifact.");
+  }
+  const code = String(artifact.code ?? "");
+  const imports = Array.isArray(artifact.imports) ? artifact.imports.map((reference, index) => {
+    if (!reference || typeof reference !== "object") {
+      throw new TypeError(`Compiled artifact import ${index} is invalid.`);
+    }
+    const start = Number(reference.start);
+    const end = Number(reference.end);
+    const specifier = String(reference.specifier ?? "");
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end <= start || end > code.length) {
+      throw new TypeError(`Compiled artifact import ${JSON.stringify(specifier)} has invalid source offsets.`);
+    }
+    return {
+      specifier,
+      start,
+      end,
+      kind: reference.kind ?? "static",
+    };
+  }) : [];
+
+  return {
+    schema: COMPILED_ARTIFACT_SCHEMA,
+    code,
+    imports,
+    diagnostics: Array.isArray(artifact.diagnostics) ? [...artifact.diagnostics] : [],
+    assets: Array.isArray(artifact.assets) ? artifact.assets.map(asset => ({type:String(asset.type),id:String(asset.id??""),content:String(asset.content??"")})) : [],
+    ...(artifact.sourceMap == null ? {} : { sourceMap: String(artifact.sourceMap) }),
+    ...(artifact.changed == null ? {} : { changed: Boolean(artifact.changed) }),
+  };
+}
+
+function isQuotaError(error) {
+  const name = error?.name;
+  const code = error?.code;
+  return name === "QuotaExceededError" || name === "NS_ERROR_DOM_QUOTA_REACHED" || code === 22 || code === 1014;
+}
+
+function normalizeLimit(value) {
+  if (value == null) return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+
+function now() {
+  return globalThis.performance?.now?.() ?? Date.now();
+}