solid-tag-runtime 0.0.12 → 0.0.13

package/src/runtime.js

@@ -6,8 +6,11 @@ import {
 } from "./errors.js";
 import { createDefaultModuleUrlBackend } from "./url-backend.js";
 import { createEventDispatcher } from "./events.js";
+import { approximateByteSize, sha256, stableSerialize } from "./compile-cache.js";
 
 const HOST_REGISTRY_KEY = "__solidTagRuntimeHostModules__";
+const COMPILED_ARTIFACT_ABI = "solid-tag-runtime:compiled-artifact:v1";
+const COMPILED_ARTIFACT_SCHEMA = 1;
 let runtimeSequence = 0;
 
 export function createRuntime(options = {}) {
@@ -18,10 +21,11 @@ export function createRuntime(options = {}) {
     allowNativeImports = true,
     resolve: customResolve,
     moduleUrlBackend = createDefaultModuleUrlBackend(),
+    compileCache: compileCacheOptions,
   } = options;
 
-  if (!compiler || typeof compiler.analyze !== "function" || typeof compiler.transform !== "function") {
-    throw new TypeError("createRuntime() requires a compiler with analyze() and transform() methods.");
+  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 = `solid-tag-runtime-${++runtimeSequence}-${randomId()}`;
@@ -35,6 +39,10 @@ export function createRuntime(options = {}) {
   });
   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();
@@ -61,6 +69,7 @@ export function createRuntime(options = {}) {
     getModuleInfo,
     dispose,
     resolve: resolvePublic,
+    compileCache: createCompileCacheManager(),
   };
 
   for (const [id, namespace] of Object.entries(modules)) defineModule(id, namespace);
@@ -141,6 +150,10 @@ export function createRuntime(options = {}) {
       dependencies: new Set(),
       dependents: existing?.dependents ?? new Set(),
       compiledCode: undefined,
+      compiledArtifact: undefined,
+      compiledArtifactKey: undefined,
+      compileCacheInfo: createInitialCompileCacheInfo(),
+      forceCompileRefresh: false,
       diagnostics: [],
       url: undefined,
       importPromise: undefined,
@@ -302,7 +315,7 @@ export function createRuntime(options = {}) {
     return record.importPromise;
   }
 
-  async function compile(id) {
+  async function compile(id, compileOptions = {}) {
     assertActive();
     const resolved = resolveSpecifier(String(id), null);
     const record = records.get(resolved);
@@ -318,7 +331,14 @@ export function createRuntime(options = {}) {
       };
     }
 
-    const url = await ensureSourceUrl(record, []);
+    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,
@@ -365,28 +385,40 @@ export function createRuntime(options = {}) {
     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);
+    invalidateOne(normalized, true);
     return [...seen];
 
-    function invalidateOne(targetId) {
+    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);
+        for (const dependent of record.dependents) invalidateOne(dependent, false);
       }
 
       if (record.kind === "source") {
         revokeRecordUrl(record);
         record.compiledCode = undefined;
-        record.diagnostics = [];
         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";
@@ -493,7 +525,539 @@ export function createRuntime(options = {}) {
     return resolveSpecifier(specifier, importer ?? null);
   }
 
-  async function ensureSourceUrl(record, stack) {
+  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?.(
+          "solid-tag-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 `solid-tag-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)) {
@@ -512,21 +1076,12 @@ export function createRuntime(options = {}) {
       version: record.version,
     });
 
-    let analysis;
-    try {
-      analysis = compiler.analyze(record.source, { id: record.id, format: record.format });
-    } catch (error) {
-      record.state = "error";
-      const wrapped = new ModuleCompileError(record.id, error);
-      emitError(record, "analyze", wrapped);
-      throw wrapped;
-    }
-
+    const artifact = await ensureCompiledArtifact(record, linkOptions.cacheMode ?? "use");
     const resolvedImports = [];
     const linkedDependencies = [];
     const nextDependencies = new Set();
 
-    for (const reference of analysis.imports ?? []) {
+    for (const reference of artifact.imports ?? []) {
       let resolved;
       try {
         resolved = resolveSpecifier(reference.specifier, record.id);
@@ -544,7 +1099,7 @@ export function createRuntime(options = {}) {
           nextDependencies.add(dependencyRecord.id);
 
           if (dependencyRecord.kind === "source") {
-            replacement = await ensureSourceUrl(dependencyRecord, nextStack);
+            replacement = await ensureSourceUrl(dependencyRecord, nextStack, { cacheMode: "use" });
           } else if (dependencyRecord.kind === "host") {
             replacement = await ensureHostUrl(dependencyRecord);
           } else {
@@ -570,35 +1125,7 @@ export function createRuntime(options = {}) {
 
     let linkedSource;
     try {
-      linkedSource = applyImportReplacements(record.source, resolvedImports);
-
-      // JSX produced by solid-tag needs @solidjs/html. Resolve it through the
-      // same module system so host applications can share their existing runtime.
-      let htmlImportSource;
-      const needsHtmlRuntime = record.format !== "js" && analysis.needsHtmlRuntime !== false;
-      if (needsHtmlRuntime) {
-        const htmlResolved = resolveSpecifier("@solidjs/html", record.id);
-        const htmlRecord = records.get(htmlResolved);
-
-        if (htmlRecord) {
-          nextDependencies.add(htmlRecord.id);
-          htmlImportSource = htmlRecord.kind === "source"
-            ? await ensureSourceUrl(htmlRecord, nextStack)
-            : htmlRecord.kind === "host"
-              ? await ensureHostUrl(htmlRecord)
-              : htmlRecord.externalUrl;
-        } else if (allowNativeImports) {
-          htmlImportSource = htmlResolved;
-        } else {
-          throw new ModuleResolutionError("@solidjs/html", record.id);
-        }
-
-        linkedDependencies.push({
-          specifier: "@solidjs/html",
-          resolvedId: htmlRecord?.id ?? htmlResolved,
-        });
-      }
-
+      linkedSource = applyImportReplacements(artifact.code, resolvedImports);
       syncDependencyEdges(record, nextDependencies);
       emit({
         type: "module-linked",
@@ -608,31 +1135,11 @@ export function createRuntime(options = {}) {
         dependencies: linkedDependencies,
         module: toModuleInfo(record),
       });
-
-      try {
-        if (record.format === "js") {
-          record.compiledCode = linkedSource;
-          record.diagnostics = [];
-        } else {
-          const transformed = compiler.transform(linkedSource, {
-            id: record.id,
-            format: record.format,
-            htmlImportSource,
-          });
-          record.compiledCode = transformed.code;
-          record.diagnostics = [...(transformed.diagnostics ?? [])];
-        }
-      } catch (error) {
-        record.state = "error";
-        const wrapped = new ModuleCompileError(record.id, error);
-        emitError(record, "compile", wrapped);
-        throw wrapped;
-      }
+      record.compiledCode = linkedSource;
+      record.diagnostics = [...(artifact.diagnostics ?? [])];
     } catch (error) {
-      if (record.state !== "error") {
-        record.state = "error";
-        emitError(record, error instanceof ModuleResolutionError ? "resolve" : "link", error);
-      }
+      record.state = "error";
+      emitError(record, error instanceof ModuleResolutionError ? "resolve" : "link", error);
       throw error;
     }
 
@@ -805,6 +1312,7 @@ export function createRuntime(options = {}) {
       dependents: [...record.dependents],
       url: record.kind === "url" ? record.externalUrl : record.url,
       diagnostics: [...(record.diagnostics ?? [])],
+      ...(record.kind === "source" ? { compileCache: { ...record.compileCacheInfo } } : {}),
     };
   }
 }
@@ -911,3 +1419,77 @@ function randomId() {
   if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
   return Math.random().toString(36).slice(2);
 }
+
+function normalizeCompileCacheOptions(options) {
+  if (options == null || options === false || options.enabled === false) return undefined;
+  if (typeof options !== "object") {
+    throw new TypeError("compileCache must be an options object with a store.");
+  }
+  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] : [],
+    ...(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();
+}