partial-react 0.0.2 → 0.0.4

package/README.md

@@ -36,6 +36,12 @@ import { mergeFallbackImports, prepareRendererImportMap } from "partial-react/im
 import { useGenUIRenderContext } from "partial-react/render-context";
 ```
 
+## Bundlers
+
+The loader's `import()` specifiers are computed at runtime — a blob URL for the generated module, import-map targets for its dependencies — so no bundler may resolve them at build time. They carry `@vite-ignore`, `webpackIgnore: true`, and `turbopackIgnore: true` together, which covers Vite, webpack/Rspack, and Turbopack (Next.js); if you re-emit this source through a tool that strips comments, preserve those three.
+
+Turbopack builds also need [#1690](https://github.com/MindLab-Research/macaron-genui-demo/issues/1690): `compiler.ts` loads the tsx wasm through Vite's `?url` query, which Turbopack rejects. Until that lands, Next.js consumers still need to patch that import.
+
 ## State and Streaming
 
 - Keep `preserveStateOnUpdate: true` for normal previews. It preserves useful React state and DOM continuity across regenerated code.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "partial-react",
   "description": "A state-preserving renderer for prefix-growing streaming React/TSX.",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
   ],
   "dependencies": {
     "@esm.sh/tsx": "^1.5.3",
-    "partial-tsx": "0.0.2"
+    "partial-tsx": "0.0.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/compiler.ts

@@ -1,7 +1,6 @@
 import initTsx, { transform as transformTsx } from "@esm.sh/tsx";
-import tsxWasmUrl from "@esm.sh/tsx/pkg/tsx_bg.wasm?url";
 import { normalizeGeneratedTsx } from "partial-tsx";
-import type { RendererImportMap } from "./importMap";
+import { rewriteImportMetaResolveSpecifiers, type RendererImportMap } from "./importMap";
 
 export type CompileOptions = { importMap?: RendererImportMap; partial?: boolean; previousCode?: string; filename?: string; lang?: "ts" | "tsx" | "js" | "jsx"; jsxImportSource?: string };
 export type CompileResult = { code: string; source: string; changed: boolean };
@@ -19,9 +18,10 @@ const initCompiler = () =>
     try {
       if (typeof window === "undefined") return initTsx(await loadNodeWasm());
     } catch {
-      // Environments without a filesystem (e.g. web workers) fall back to Vite's asset URL below.
+      // Environments without a filesystem (e.g. web workers) fall back to the bundled asset below.
     }
-    return initTsx(tsxWasmUrl);
+    // No argument: wasm-bindgen resolves `new URL("tsx_bg.wasm", import.meta.url)`, which every bundler understands — a Vite-only `?url` import here broke the rest. #1690
+    return initTsx();
   })().catch((error) => {
     initPromise = null;
     throw error;
@@ -32,7 +32,8 @@ export function createTsxCompiler(): TsxCompiler {
     async compile(code, options = {}) {
       await initCompiler();
       const source = options.partial ? normalizeGeneratedTsx(code, { mode: "streaming" }) : code;
-      const result = transformTsx({ filename: options.filename ?? "_.tsx", code: source, lang: options.lang, target: "es2022", importMap: options.importMap, jsxImportSource: options.jsxImportSource ?? "react" });
+      const resolvedSource = options.importMap?.imports ? rewriteImportMetaResolveSpecifiers(source, options.importMap.imports) : source;
+      const result = transformTsx({ filename: options.filename ?? "_.tsx", code: resolvedSource, lang: options.lang, target: "es2022", importMap: options.importMap, jsxImportSource: options.jsxImportSource ?? "react" });
       const compiled = new TextDecoder().decode(result.code);
       return { code: compiled, source, changed: compiled !== options.previousCode };
     },

package/src/importMap.ts

@@ -2,10 +2,11 @@ export type RendererImportMap = { imports?: Record<string, string>; scopes?: Rec
 
 // A provider contributes import-map entries. `base` providers always run; `fallback` providers only run when earlier
 // providers left some required specifier unresolved, and only see (and should answer for) those `missing` specifiers.
-export type ImportMapProviderContext = { code: string; missing: string[] };
+export type ImportMapProviderContext = { code: string; missing: string[]; imports?: Readonly<Record<string, string>> };
 export type ImportMapProvider = { kind?: "base" | "fallback"; prefetch?: () => Promise<unknown> | void; resolve: (context: ImportMapProviderContext) => RendererImportMap | Promise<RendererImportMap> };
 
-const ESM_SH_VERSION_OVERRIDES = { "@number-flow/react": "0.6.0" } as const;
+// Packages whose identity must be shared with a dependent's own bundled copy — see `toEsmShImportUrl`.
+const SHARED_INSTANCE_PACKAGES = new Set(["three"]);
 const DEFAULT_ESM_SH_EXTERNALS = ["react", "react-dom", "scheduler"] as const;
 export const RUNTIME_SINGLETON_SPECIFIERS = ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime", "scheduler"] as const;
 export type RuntimeSingletonSpecifier = (typeof RUNTIME_SINGLETON_SPECIFIERS)[number];
@@ -18,6 +19,10 @@ const LOCAL_EXPORT_KEYWORDS = ["abstract", "async", "class", "const", "declare",
 
 export const isBareModuleSpecifier = (specifier: string) => !specifier.startsWith(".") && !specifier.startsWith("/") && !/^(?:[a-z][a-z\d+.-]*:|#)/i.test(specifier);
 export const getBarePackageName = (specifier: string) => (specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0] || specifier);
+// A shared-instance package must stay on its canonical esm.sh URL end to end: `toEsmShImportUrl` keeps it unbundled so
+// it resolves to the same `/three@x/es2022/three.mjs` a dependent's bundle imports, and callers must not blob it either
+// — a blob: copy is a distinct module object, which is exactly the duplication the unbundled path exists to avoid.
+export const isSharedInstancePackage = (specifier: string) => SHARED_INSTANCE_PACKAGES.has(getBarePackageName(specifier));
 // Shared #1178 contract: /src/… and /node_modules/… targets are root-relative disk paths each engine rebases against
 // its own root (dev: Vite's resolved root; build: cwd). Single-sourced so a new local prefix lands in both engines.
 export const isLocalRootRelativeTarget = (target: string) => target.startsWith("/src/") || target.startsWith("/node_modules/");
@@ -187,8 +192,9 @@ const readFromSpecifier = (code: string, index: number) => {
       continue;
     }
     if (isKeywordAt(code, index, "from")) {
-      const literal = readStringLiteral(code, skipWhitespaceAndComments(code, index + "from".length));
-      if (literal) return { specifier: literal.value, end: literal.end, terminated: literal.terminated };
+      const start = skipWhitespaceAndComments(code, index + "from".length);
+      const literal = readStringLiteral(code, start);
+      if (literal) return { specifier: literal.value, start, end: literal.end, terminated: literal.terminated };
       index += "from".length;
       continue;
     }
@@ -205,7 +211,99 @@ const readExportFromSpecifier = (code: string, index: number) => {
   return readFromSpecifier(code, next);
 };
 
-const collectModuleSpecifiers = (code: string, specifiers: Set<string>, includeSpecifier: (specifier: string) => boolean, start = 0, end = code.length) => {
+// `.meta.resolve(` after the `import` keyword, returning the string-literal argument. Null means this `import.` is
+// something else (`import.meta.url`, `import.meta.env`) and the caller should just skip past the dot.
+const readImportMetaResolveSpecifier = (code: string, dotIndex: number) => {
+  let next = skipWhitespaceAndComments(code, dotIndex + 1);
+  if (!isKeywordAt(code, next, "meta")) return null;
+  next = skipWhitespaceAndComments(code, next + "meta".length);
+  if (code[next] !== ".") return null;
+  next = skipWhitespaceAndComments(code, next + 1);
+  if (!isKeywordAt(code, next, "resolve")) return null;
+  next = skipWhitespaceAndComments(code, next + "resolve".length);
+  if (code[next] !== "(") return null;
+  const start = skipWhitespaceAndComments(code, next + 1);
+  const literal = readStringLiteral(code, start);
+  return literal ? { ...literal, start } : { value: "", start, end: next, terminated: false };
+};
+
+const readIdentifierWord = (code: string, index: number) => {
+  let end = index;
+  while (end < code.length && IDENTIFIER_CHAR_PATTERN.test(code[end])) end += 1;
+  return end > index ? { name: code.slice(index, end), end } : null;
+};
+
+// Parses one static import clause right after the `import` keyword into the export names the module must provide
+// ("default" for default imports; namespace and side-effect imports demand none). `notLinked` marks a type-only import,
+// which survives specifier collection but is erased before the module is ever instantiated. Returns null on clauses it does not understand
+// (streaming-truncated ones) so callers can fall back to the lenient readFromSpecifier.
+const readImportBindings = (code: string, index: number): { specifier: string; names: string[]; start: number; end: number; terminated: boolean; notLinked?: boolean } | null => {
+  const names: string[] = [];
+  index = skipWhitespaceAndComments(code, index);
+  const sideEffect = readStringLiteral(code, index);
+  if (sideEffect) return sideEffect.value ? { specifier: sideEffect.value, names, start: index, end: sideEffect.end, terminated: sideEffect.terminated } : null;
+  if (isKeywordAt(code, index, "type")) {
+    const after = skipWhitespaceAndComments(code, index + "type".length);
+    // `import type …` is erased at runtime — but `import type from "x"` binds a default named `type`.
+    if (!isKeywordAt(code, after, "from")) {
+      const from = readFromSpecifier(code, after);
+      return from ? { ...from, names, notLinked: true } : null;
+    }
+  }
+  if (code[index] !== "{" && code[index] !== "*") {
+    const afterDefault = readIdentifierWord(code, index)?.end;
+    if (afterDefault === undefined) return null;
+    names.push("default");
+    index = skipWhitespaceAndComments(code, afterDefault);
+    if (code[index] === ",") index = skipWhitespaceAndComments(code, index + 1);
+  }
+  if (code[index] === "*") {
+    index = skipWhitespaceAndComments(code, index + 1);
+    if (!isKeywordAt(code, index, "as")) return null;
+    const afterNamespace = readIdentifierWord(code, skipWhitespaceAndComments(code, index + "as".length))?.end;
+    if (afterNamespace === undefined) return null;
+    index = skipWhitespaceAndComments(code, afterNamespace);
+  } else if (code[index] === "{") {
+    index = skipWhitespaceAndComments(code, index + 1);
+    while (index < code.length && code[index] !== "}") {
+      let typeOnly = false;
+      if (isKeywordAt(code, index, "type")) {
+        const after = skipWhitespaceAndComments(code, index + "type".length);
+        // `{ type Foo }` is erased; a lone `{ type }` / `{ type as t }` demands an export literally named `type`.
+        if (code[after] !== "," && code[after] !== "}" && !isKeywordAt(code, after, "as")) {
+          typeOnly = true;
+          index = after;
+        }
+      }
+      const literal = readStringLiteral(code, index);
+      const imported = literal ? { name: literal.value, end: literal.end } : readIdentifierWord(code, index);
+      if (!imported) return null;
+      index = skipWhitespaceAndComments(code, imported.end);
+      if (isKeywordAt(code, index, "as")) {
+        const local = readIdentifierWord(code, skipWhitespaceAndComments(code, index + "as".length));
+        if (!local) return null;
+        index = skipWhitespaceAndComments(code, local.end);
+      }
+      if (!typeOnly) names.push(imported.name);
+      if (code[index] === ",") index = skipWhitespaceAndComments(code, index + 1);
+      else if (code[index] !== "}") return null;
+    }
+    if (code[index] !== "}") return null;
+    index = skipWhitespaceAndComments(code, index + 1);
+  }
+  if (!isKeywordAt(code, index, "from")) return null;
+  const start = skipWhitespaceAndComments(code, index + "from".length);
+  const literal = readStringLiteral(code, start);
+  return literal?.value ? { specifier: literal.value, names, start, end: literal.end, terminated: literal.terminated } : null;
+};
+
+// Walks module-level import/export statements and reports each specifier with the export names bound from it
+// (empty for namespace, side-effect, re-export and dynamic imports). `onSpecifier` is the single output channel —
+// callers project it into whatever shape they need. `site` separates the module graph from `import.meta.resolve()`,
+// which is a runtime asset lookup rather than an edge.
+type ResolutionSite = "import" | "meta-resolve";
+type SpecifierRange = { start: number; end: number };
+const collectModuleSpecifiers = (code: string, onSpecifier: (specifier: string, names: string[], notLinked: boolean | undefined, site: ResolutionSite, range?: SpecifierRange) => void, start = 0, end = code.length) => {
   for (let index = start; index < end; index += 1) {
     const char = code[index];
     if (char === "/" && code[index + 1] === "/") {
@@ -225,45 +323,110 @@ const collectModuleSpecifiers = (code: string, specifiers: Set<string>, includeS
       continue;
     }
     if (char === "`") {
-      index = skipTemplateLiteral(code, index, (expressionStart, expressionEnd) => collectModuleSpecifiers(code, specifiers, includeSpecifier, expressionStart, expressionEnd));
+      index = skipTemplateLiteral(code, index, (expressionStart, expressionEnd) => collectModuleSpecifiers(code, onSpecifier, expressionStart, expressionEnd));
       continue;
     }
     if (isKeywordAt(code, index, "import")) {
       const afterImport = skipWhitespaceAndComments(code, index + "import".length);
       if (code[afterImport] === ".") {
+        // Keep runtime asset lookups visible to callers that scan all specifiers, while separating them from actual
+        // module-graph edges. The renderer no longer projects these into a browser-native import map.
+        const literal = readImportMetaResolveSpecifier(code, afterImport);
+        if (literal) {
+          // notLinked: nothing is instantiated here, so probing it would fetch what the module never requested.
+          if (literal.terminated && literal.value) onSpecifier(literal.value, [], true, "meta-resolve", { start: literal.start, end: literal.end });
+          index = literal.end;
+          continue;
+        }
         index = afterImport;
         continue;
       }
       if (code[afterImport] === "(") {
-        const literal = readStringLiteral(code, skipWhitespaceAndComments(code, afterImport + 1));
-        if (literal?.terminated && literal.value && includeSpecifier(literal.value)) specifiers.add(literal.value);
+        const literalStart = skipWhitespaceAndComments(code, afterImport + 1);
+        const literal = readStringLiteral(code, literalStart);
+        // A dynamic target is not linked at instantiation, so probing it would issue a real request.
+        if (literal?.terminated && literal.value) onSpecifier(literal.value, [], true, "import", { start: literalStart, end: literal.end });
         index = literal?.end ?? afterImport;
         continue;
       }
-      const sideEffect = readStringLiteral(code, afterImport);
-      const from = sideEffect ? { specifier: sideEffect.value, end: sideEffect.end, terminated: sideEffect.terminated } : readFromSpecifier(code, afterImport);
-      if (from?.terminated && from.specifier && includeSpecifier(from.specifier)) specifiers.add(from.specifier);
+      const bindings = readImportBindings(code, afterImport);
+      const from = bindings ?? readFromSpecifier(code, afterImport);
+      if (from?.terminated && from.specifier) onSpecifier(from.specifier, bindings?.names ?? [], bindings?.notLinked, "import", { start: from.start, end: from.end });
       index = from?.end ?? afterImport;
       continue;
     }
     if (isKeywordAt(code, index, "export")) {
       const from = readExportFromSpecifier(code, index + "export".length);
-      if (from?.terminated && from.specifier && includeSpecifier(from.specifier)) specifiers.add(from.specifier);
+      if (from?.terminated && from.specifier) onSpecifier(from.specifier, [], undefined, "import", { start: from.start, end: from.end });
       index = from?.end ?? index;
     }
   }
 };
 
-export function extractBareModuleSpecifiers(code: string) {
+const extractSpecifiers = (code: string, keep: (specifier: string, site: ResolutionSite) => boolean) => {
   const specifiers = new Set<string>();
-  collectModuleSpecifiers(code, specifiers, isBareModuleSpecifier);
+  collectModuleSpecifiers(code, (specifier, _names, _notLinked, site) => {
+    if (keep(specifier, site)) specifiers.add(specifier);
+  });
   return specifiers;
+};
+
+export const extractBareModuleSpecifiers = (code: string) => extractSpecifiers(code, isBareModuleSpecifier);
+
+// Specifiers reached through an `import`/`export` statement only — the actual module graph. Excludes
+// `import.meta.resolve()` targets, which are runtime asset lookups (WASM binaries, worker scripts) rather than graph
+// edges, so a consumer walking imports (the UnoCSS source tracer) doesn't try to parse a multi-MB binary as source.
+export const extractImportSpecifiers = (code: string) => extractSpecifiers(code, (_specifier, site) => site === "import");
+
+export const extractImportMetaResolveSpecifiers = (code: string) => extractSpecifiers(code, (_specifier, site) => site === "meta-resolve");
+
+export const extractModuleSpecifiers = (code: string) => extractSpecifiers(code, () => true);
+
+export function resolveImportMapSpecifier(imports: Readonly<Record<string, string>>, specifier: string) {
+  if (imports[specifier]) return imports[specifier];
+  let bestPrefix = "";
+  for (const prefix of Object.keys(imports)) if (prefix.endsWith("/") && specifier.startsWith(prefix) && prefix.length > bestPrefix.length) bestPrefix = prefix;
+  return bestPrefix ? `${imports[bestPrefix]}${specifier.slice(bestPrefix.length)}` : undefined;
 }
 
-export function extractModuleSpecifiers(code: string) {
-  const specifiers = new Set<string>();
-  collectModuleSpecifiers(code, specifiers, () => true);
-  return specifiers;
+// Replace the parsed string-literal specifiers at `keepSite` with their import-map targets. Working from the scanner's
+// ranges — not a text match — is what makes this safe on minified bundles, where a string constant can read exactly
+// like an import clause (`from"in $)}function S$(`).
+const rewriteSpecifiers = (code: string, imports: Readonly<Record<string, string>>, keepSite: ResolutionSite) => {
+  // collectModuleSpecifiers scans forward, so ranges arrive in ascending order: emit the gap before each one and skip
+  // past it, then join once. Splicing the string per replacement would recopy the whole source each time.
+  const segments: string[] = [];
+  let copied = 0;
+  collectModuleSpecifiers(code, (specifier, _names, _notLinked, site, range) => {
+    const target = site === keepSite ? resolveImportMapSpecifier(imports, specifier) : undefined;
+    if (!target || !range) return;
+    segments.push(code.slice(copied, range.start), JSON.stringify(target));
+    copied = range.end;
+  });
+  if (!segments.length) return code;
+  segments.push(code.slice(copied));
+  return segments.join("");
+};
+
+// @esm.sh/tsx rewrites import declarations but deliberately leaves import.meta.resolve() calls intact. Replace only
+// their parsed string-literal arguments with resolved URLs so blob: modules never need a browser-native import map.
+export const rewriteImportMetaResolveSpecifiers = (code: string, imports: Readonly<Record<string, string>>) => rewriteSpecifiers(code, imports, "meta-resolve");
+
+// The counterpart for code no compiler pass ever sees: host facade bundles are built with the runtime singletons
+// externalized (that externalization is what keeps React a singleton), so their bare imports would otherwise survive to
+// the browser and need a native import map. Rewriting them to the emitted chunk URLs is what lets that map go away.
+export const rewriteImportSpecifiers = (code: string, imports: Readonly<Record<string, string>>) => rewriteSpecifiers(code, imports, "import");
+
+// Maps each specifier linked when the module is instantiated to the export names bound from it ("default" included;
+// namespace, side-effect and re-export imports demand no specific names). Type-only and dynamic imports are excluded:
+// neither is linked at instantiation, so probing them would fetch something the failed module never requested.
+// importProbe runs this over *compiled* code, where the import-map rewrite already resolved bare specifiers.
+export function extractImportBindings(code: string) {
+  const bindings = new Map<string, string[]>();
+  collectModuleSpecifiers(code, (specifier, names, notLinked) => {
+    if (!notLinked) bindings.set(specifier, [...new Set([...(bindings.get(specifier) ?? []), ...names])]);
+  });
+  return bindings;
 }
 
 export function hasImportMapEntry(imports: Record<string, string> | Set<string> | Map<string, string>, specifier: string) {
@@ -273,14 +436,69 @@ export function hasImportMapEntry(imports: Record<string, string> | Set<string>
   return false;
 }
 
-export function toEsmShImportUrl(specifier: string, external: readonly string[] = DEFAULT_ESM_SH_EXTERNALS) {
+export type EsmShDependencyRanges = Readonly<Record<string, string>>;
+type EsmShImportUrlOptions = { dev?: boolean; dependencyRanges?: EsmShDependencyRanges };
+
+export function toEsmShImportUrl(specifier: string, external: readonly string[] = DEFAULT_ESM_SH_EXTERNALS, options?: EsmShImportUrlOptions) {
   if (!canUseEsmShFallback(specifier)) throw new Error(`Cannot create an esm.sh fallback for ${specifier}`);
   const packageName = getBarePackageName(specifier);
-  const version = ESM_SH_VERSION_OVERRIDES[packageName as keyof typeof ESM_SH_VERSION_OVERRIDES];
-  const versionedSpecifier = version ? `${packageName}@${version}${specifier.slice(packageName.length)}` : specifier;
-  const separator = versionedSpecifier.includes("?") ? "&" : "?";
+  // Dev builds: production bundles strip the dev-only dispatcher fields (e.g. getOwner) that the dev jsx-runtime
+  // calls while an externalized reconciler (react-reconciler inside @react-three/fiber) owns the render pass.
+  const devParam = options?.dev ? "&dev" : "";
+  // `bundle`/`external` both fork esm.sh's build path, so a bundled `three` is a different module object than the plain
+  // `/three@x/es2022/three.mjs` that `@react-three/fiber` imports. Shared-instance packages use that unbundled path so
+  // R3F's `instanceof THREE.Layers/Color` checks see the same constructors as user-created Three.js objects. Their
+  // identity comes from agreeing with a dependent's own pinned range (R3F asks for `three@>=0.156`), so our side stays
+  // unconstrained too and both float onto latest, landing on the same pinned build. The invariant is that agreement,
+  // not version-freedom — it would break the day R3F pins an upper bound or we constrain our side.
+  if (isSharedInstancePackage(specifier)) return `https://esm.sh/${specifier}${specifier.includes("?") ? "&" : "?"}target=es2022${devParam}`;
+  // Keep the repository's declared semver range as the single source of truth. Protocol-based specs describe local,
+  // aliased, or non-registry packages that esm.sh cannot resolve and therefore stay version-free here.
+  const dependencyRange = options?.dependencyRanges?.[packageName];
+  const constrainedSpecifier = dependencyRange && !dependencyRange.includes(":") ? `${packageName}@${encodeURIComponent(dependencyRange)}${specifier.slice(packageName.length)}` : specifier;
+  const separator = constrainedSpecifier.includes("?") ? "&" : "?";
   const externalParam = external.length ? `&external=${external.join(",")}` : "";
-  return `https://esm.sh/${versionedSpecifier}${separator}bundle&target=es2022${externalParam}`;
+  return `https://esm.sh/${constrainedSpecifier}${separator}bundle&target=es2022${devParam}${externalParam}`;
+}
+
+type EsmShPreloadFetch = (url: string) => Promise<Pick<Response, "ok" | "status">>;
+type EsmShPreloadOptions = { fetch?: EsmShPreloadFetch; attempts?: number; retryDelayMs?: number };
+const esmShPreloadCache = new Map<string, Promise<void>>();
+
+// A browser module loader memoizes a rejected URL for the page lifetime, so retrying the generated blob cannot recover
+// from a transient esm.sh cold-build failure. Warm the entry URL with ordinary fetch first — a version range still
+// leaves it a mutable entry esm.sh has to resolve and build, not a pinned artifact. Failures remain retryable, while a
+// 2xx means esm.sh has finished resolving/building before import() sees the URL.
+export function preloadEsmShImportUrl(url: string, options?: EsmShPreloadOptions): Promise<void> {
+  let preload = esmShPreloadCache.get(url);
+  if (!preload) {
+    const fetcher = options?.fetch ?? fetch;
+    // 3 attempts at 250ms exponential backoff spans ~750ms of retrying, which covers a typical esm.sh cold build
+    // without stalling first paint. There is no ack to wait on — esm.sh answers 5xx while the build is still running.
+    const attempts = options?.attempts ?? 3;
+    const retryDelayMs = options?.retryDelayMs ?? 250;
+    preload = (async () => {
+      let lastFailure: unknown;
+      for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, retryDelayMs * 2 ** (attempt - 1)));
+        try {
+          const response = await fetcher(url);
+          if (response.ok) return;
+          lastFailure = new Error(`HTTP ${response.status}`);
+          // esm.sh answers 5xx while a cold build is still running, and 429 when npm rate-limits it — both transient,
+          // same classification the probes below use. Any other 4xx is a decided answer (unknown package, rejected
+          // specifier); retrying burns the full backoff for the same result.
+          if (response.status < 500 && response.status !== 429) break;
+        } catch (error) {
+          lastFailure = error;
+        }
+      }
+      throw new Error(`Failed to preload esm.sh module ${url}`, { cause: lastFailure });
+    })();
+    preload.catch(() => esmShPreloadCache.delete(url));
+    esmShPreloadCache.set(url, preload);
+  }
+  return preload;
 }
 
 export type EsmShProbe = { alive: true } | { alive: false; detail: string };
@@ -310,6 +528,9 @@ export const probeEsmShSpecifier = (specifier: string, fetcher: EsmShProbeFetch
     probe = (async (): Promise<EsmShProbe | null> => {
       let url: string;
       try {
+        // Deliberately unranged: this is a package-existence check, and the cache is keyed by bare specifier. A
+        // package that exists unranged exists ranged, so the only gap is a declared range with no esm.sh build —
+        // probe says alive, render 404s. #1573 tracks threading ranges through if that ever bites.
         url = toEsmShImportUrl(specifier);
       } catch {
         return null;
@@ -419,14 +640,14 @@ export function packageImportMap(packageName: string, options?: { resolve?: (nam
 
 // esm.sh fallback only answers for `missing` specifiers, so the resolver can merge its output without re-checking
 // coverage. In dev, locally installed packages are preferred so peer deps like React stay on the preview's runtime.
-export function esmShFallback(options?: { external?: readonly string[]; hasLocalPackage?: (packageName: string) => Promise<boolean> }): ImportMapProvider {
+export function esmShFallback(options?: { external?: readonly string[]; dev?: boolean; dependencyRanges?: EsmShDependencyRanges; hasLocalPackage?: (packageName: string) => Promise<boolean> }): ImportMapProvider {
   return {
     kind: "fallback",
     resolve: async ({ missing }) => {
       const entries = await Promise.all(
         missing.filter(canUseEsmShFallback).map(async (specifier) => {
           const isLocal = await options?.hasLocalPackage?.(getBarePackageName(specifier));
-          return [specifier, isLocal ? `/node_modules/${specifier}` : toEsmShImportUrl(specifier, options?.external)] as const;
+          return [specifier, isLocal ? `/node_modules/${specifier}` : toEsmShImportUrl(specifier, options?.external, { dev: options?.dev, dependencyRanges: options?.dependencyRanges })] as const;
         }),
       );
       return { imports: Object.fromEntries(entries) };
@@ -448,7 +669,7 @@ export function createImportMapResolver(providers: ImportMapProvider[]) {
         const covered = new Set(Object.keys(imports));
         const missing = required.filter((specifier) => !hasImportMapEntry(covered, specifier));
         if (provider.kind === "fallback" && missing.length === 0) continue;
-        const next = await provider.resolve({ code, missing });
+        const next = await provider.resolve({ code, missing, imports });
         imports = { ...imports, ...next.imports };
         // scopes is an advanced compat field with no producer today, so a later provider replaces an earlier one's
         // entries for the same scope key rather than deep-merging them. Revisit if two providers ever both emit scopes.
@@ -460,6 +681,6 @@ export function createImportMapResolver(providers: ImportMapProvider[]) {
   };
 }
 
-export async function mergeFallbackImports(imports: Record<string, string>, code: string, options?: { hasLocalPackage?: (packageName: string) => Promise<boolean> }) {
+export async function mergeFallbackImports(imports: Record<string, string>, code: string, options?: { dependencyRanges?: EsmShDependencyRanges; hasLocalPackage?: (packageName: string) => Promise<boolean> }) {
   return (await createImportMapResolver([literalImportMap({ imports }), esmShFallback(options)]).resolve({ code })).imports;
 }

package/src/importProbe.ts

@@ -0,0 +1,65 @@
+import { extractImportBindings } from "./importMap";
+
+export type GenUIImportDiagnostic = { specifier: string; target: string; detail: string };
+
+// Replaces the browser's opaque blob-module failure once the probe has named the imports that actually broke.
+// `message` doubles as the heal signal fed back to the generating model, so it must stay self-contained.
+export class GenUIImportError extends Error {
+  readonly diagnostics: GenUIImportDiagnostic[];
+  constructor(diagnostics: GenUIImportDiagnostic[], cause: unknown) {
+    super(`Unresolvable imports:\n${diagnostics.map(({ specifier, target, detail }) => `- '${specifier}'${target === specifier ? "" : ` (→ ${target})`} ${detail}`).join("\n")}`, { cause });
+    this.name = "GenUIImportError";
+    this.diagnostics = diagnostics;
+  }
+}
+
+// Cap the export listing so a barrel module with hundreds of exports can't bloat the heal message; enough for the
+// model to spot the name it meant (e.g. `avataaars` vs `avataars`) and infer the rest. Mirrors MAX_HINT_SUBPATHS.
+const MAX_EXPORT_HINTS = 20;
+const listAvailableExports = (module: Record<string, unknown>) => {
+  const keys = Object.keys(module).toSorted();
+  if (!keys.length) return "";
+  return `; module exports: ${keys.slice(0, MAX_EXPORT_HINTS).join(", ")}${keys.length > MAX_EXPORT_HINTS ? `, … (${keys.length - MAX_EXPORT_HINTS} more)` : ""}`;
+};
+
+// Recover the bare specifier the model wrote from a compiled (import-map-rewritten) target. An exact entry wins; a
+// trailing-slash prefix entry (`"lucide-react/"` → `".../lucide-react/"`) maps the whole subpath back, mirroring
+// hasImportMapEntry's prefix semantics — so the heal signal names `lucide-react/icons/home`, not the resolved URL.
+const reverseResolveSpecifier = (entries: [string, string][], target: string) => {
+  for (const [specifier, mapped] of entries) if (mapped === target) return specifier;
+  for (const [specifier, mapped] of entries) if (specifier.endsWith("/") && target.startsWith(mapped)) return specifier + target.slice(mapped.length);
+  return target;
+};
+
+// Re-imports each dependency of a failed compiled module one by one to name what the blanket blob error hid. Costs no
+// extra network traffic: a dependency that linked is already in the module map, and a dependency that failed reuses the
+// engine's own rejection rather than re-fetching it to explain. `imports` (the resolved importmap) maps rewritten
+// targets back to the bare specifiers the model wrote.
+export async function probeModuleImports(code: string, imports?: Record<string, string>): Promise<GenUIImportDiagnostic[]> {
+  const importEntries = Object.entries(imports ?? {});
+  const probes = [...extractImportBindings(code)].map(async ([target, names]): Promise<GenUIImportDiagnostic | null> => {
+    const specifier = reverseResolveSpecifier(importEntries, target);
+    let module: Record<string, unknown>;
+    try {
+      // `target` is import-map-resolved at runtime, so it needs the same three-bundler ignore stack as the blob import
+      // in runtime.ts — otherwise every probe throws `Cannot find module 'unknown'` and reports each dependency as
+      // broken, burying the one that actually is. #1688
+      module = (await import(/* @vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ target)) as Record<string, unknown>;
+    } catch (error) {
+      return { specifier, target, detail: `failed to load: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const missing = names.filter((name) => !(name in module));
+    return missing.length ? { specifier, target, detail: `has no export named ${missing.map((name) => `'${name}'`).join(", ")}${listAvailableExports(module)}` } : null;
+  });
+  return (await Promise.all(probes)).filter((diagnostic) => diagnostic !== null);
+}
+
+// The probe must never replace the real failure with one of its own — fall back to the original error on any surprise.
+export async function enrichModuleImportError(error: unknown, code: string, imports?: Record<string, string>) {
+  try {
+    const diagnostics = await probeModuleImports(code, imports);
+    return diagnostics.length ? new GenUIImportError(diagnostics, error) : error;
+  } catch {
+    return error;
+  }
+}

package/src/remoteModule.ts

@@ -1,5 +1,148 @@
 import { createTsxCompiler, type TsxCompiler } from "./compiler";
-import { esmShFallback, extractModuleSpecifiers, isBareModuleSpecifier, isRuntimeSingletonSpecifier, type ImportMapProvider, type RendererImportMap } from "./importMap";
+import {
+  esmShFallback,
+  extractImportMetaResolveSpecifiers,
+  extractImportSpecifiers,
+  extractModuleSpecifiers,
+  hasImportMapEntry,
+  isBareModuleSpecifier,
+  isLocalRootRelativeTarget,
+  isSharedInstancePackage,
+  prepareRendererImportMap,
+  resolveImportMapSpecifier,
+  type EsmShDependencyRanges,
+  type ImportMapProvider,
+  type RendererImportMap,
+} from "./importMap";
+
+type EsmShModuleResponse = Pick<Response, "ok" | "status" | "statusText" | "text"> & { headers: Pick<Headers, "get"> } & Partial<Pick<Response, "url">>;
+export type EsmShModuleResolver = (url: string, imports: Readonly<Record<string, string>>) => Promise<string>;
+type EsmShModuleResolverOptions = {
+  baseUrl?: string;
+  compiler?: TsxCompiler;
+  fetch?: (url: string) => Promise<EsmShModuleResponse>;
+  preload?: (url: string) => Promise<unknown> | unknown;
+  createModuleUrl?: (code: string) => string;
+};
+
+const importMapCacheKey = (entries: readonly (readonly string[])[]) => JSON.stringify(entries.toSorted(([a], [b]) => a.localeCompare(b)));
+
+// esm.sh bundles still contain bare runtime imports when React/scheduler are externalized. Fetch the pinned bundle and
+// run it through the same @esm.sh/tsx compiler as user code, so those imports become concrete host-module URLs before
+// the browser sees the module. This keeps one transform-based resolver and removes the need for a page-level importmap.
+export function createEsmShModuleResolver(options?: EsmShModuleResolverOptions): EsmShModuleResolver {
+  const compiler = options?.compiler ?? createTsxCompiler();
+  const fetcher = options?.fetch ?? (fetch as (url: string) => Promise<EsmShModuleResponse>);
+  const createModuleUrl = options?.createModuleUrl ?? ((code: string) => URL.createObjectURL(new Blob([code], { type: "text/javascript" })));
+  const moduleByKey = new Map<string, Promise<string>>();
+  const sourceByUrl = new Map<string, Promise<{ sourceUrl: string; source: string; specifiers: string[] }>>();
+  // Every specifier in one resolve pass gets the same `imports` object, and normalizing it is O(map) — which grows with
+  // each stream chunk. Key on object identity so the pass runs once per chunk instead of once per esm.sh package.
+  const normalizedImports = new WeakMap<Readonly<Record<string, string>>, Record<string, string>>();
+
+  const loadSource = (url: string) => {
+    let pending = sourceByUrl.get(url);
+    if (!pending) {
+      pending = (async () => {
+        await options?.preload?.(url);
+        const entry = await fetcher(url);
+        if (!entry.ok) throw new Error(`Failed to fetch esm.sh module ${url}: ${entry.status} ${entry.statusText}`);
+        // esm.sh answers an entry URL with a re-export shim, not the bundle itself, so `x-esm-path` is the only way to
+        // reach the source worth compiling. Falling back to the shim would compile four `export *` lines and leave the
+        // real bundle's bare `react` import to the browser, which has no import map to resolve it — fail loudly instead.
+        const pinnedPath = entry.headers.get("x-esm-path");
+        if (!pinnedPath) throw new Error(`esm.sh returned no x-esm-path for ${url}; cannot locate the pinned bundle to compile`);
+        const sourceUrl = new URL(pinnedPath, url).href;
+        const sourceResponse = await fetcher(sourceUrl);
+        if (!sourceResponse.ok) throw new Error(`Failed to fetch esm.sh module ${sourceUrl}: ${sourceResponse.status} ${sourceResponse.statusText}`);
+        // Scan the bundle's specifiers once here, not per resolve — these bundles run to hundreds of KB.
+        const source = await sourceResponse.text();
+        return { sourceUrl, source, specifiers: [...extractModuleSpecifiers(source)] };
+      })();
+      pending.catch(() => sourceByUrl.delete(url));
+      sourceByUrl.set(url, pending);
+    }
+    return pending;
+  };
+
+  return async (url, imports) => {
+    const { sourceUrl, source, specifiers } = await loadSource(url);
+    // A blob: module cannot resolve `/src/...` relative to itself. Normalize the host map before compiling so the
+    // transform emits absolute page URLs and the resulting module is independent of browser-native import maps.
+    let compilerImports = normalizedImports.get(imports);
+    if (!compilerImports) normalizedImports.set(imports, (compilerImports = prepareRendererImportMap({ imports }, options?.baseUrl).imports));
+    // Key on the entries this bundle actually links, not the whole map: the map grows with every stream chunk, and a
+    // whole-map key would recompile the same bundle into a fresh blob: for each unrelated addition — re-running its
+    // side effects (`customElements.define` in @number-flow/react throws on the second module object).
+    const linked = specifiers.flatMap((specifier) => {
+      const target = resolveImportMapSpecifier(compilerImports, specifier);
+      return target ? [[specifier, target]] : [];
+    });
+    const key = `${url}\n${importMapCacheKey(linked)}`;
+    let moduleUrl = moduleByKey.get(key);
+    if (!moduleUrl) {
+      moduleUrl = compiler.compile(source, { filename: sourceUrl, lang: "js", importMap: { imports: compilerImports } }).then(({ code }) => createModuleUrl(code));
+      moduleUrl.catch(() => moduleByKey.delete(key));
+      moduleByKey.set(key, moduleUrl);
+    }
+    return moduleUrl;
+  };
+}
+
+export function transformedEsmShFallback(options?: {
+  dev?: boolean;
+  dependencyRanges?: EsmShDependencyRanges;
+  baseUrl?: string;
+  hasLocalPackage?: (packageName: string) => Promise<boolean>;
+  resolveEsmSh?: EsmShModuleResolver;
+  compiler?: TsxCompiler;
+  fetch?: (url: string) => Promise<EsmShModuleResponse>;
+  preload?: (url: string) => Promise<unknown> | unknown;
+}): ImportMapProvider {
+  const resolveEsmSh = options?.resolveEsmSh ?? createEsmShModuleResolver({ compiler: options?.compiler, fetch: options?.fetch, preload: options?.preload, baseUrl: options?.baseUrl });
+  // Decorate the plain fallback rather than restate it: the specifier filter, the local-package preference and the
+  // esm.sh URL shape all stay single-sourced, and this provider only decides what to do with each resolved target.
+  const base = esmShFallback({ dev: options?.dev, dependencyRanges: options?.dependencyRanges, hasLocalPackage: options?.hasLocalPackage });
+  // A failed compile evicts its cache entry so a later render can retry, which means every stream chunk re-attempts and
+  // would re-warn — hundreds of identical lines burying the first, actually diagnostic one. Warn once per target.
+  const warned = new Set<string>();
+  return {
+    kind: "fallback",
+    resolve: async ({ code, missing, imports = {} }) => {
+      const metaResolveSpecifiers = extractImportMetaResolveSpecifiers(code);
+      const importedSpecifiers = extractImportSpecifiers(code);
+      const entries = await Promise.all(
+        Object.entries((await base.resolve({ code, missing, imports })).imports ?? {}).map(async ([specifier, target]) => {
+          if (isLocalRootRelativeTarget(target)) return [specifier, target] as const;
+          // Two independent reasons to use the target as-is rather than compile it to a blob: an asset reached only
+          // through import.meta.resolve() is a value, not a JS module; a shared-instance package must keep its
+          // canonical esm.sh URL so a dependent's bundle importing that same URL gets the same module object. Either
+          // way the URL is only warmed, then the compiler rewrites the reference straight to it — and a failed warm
+          // changes nothing about what we return, so it stays outside the compile fallback below.
+          const isAssetOnly = metaResolveSpecifiers.has(specifier) && !importedSpecifiers.has(specifier);
+          if (isSharedInstancePackage(specifier) || isAssetOnly) {
+            await Promise.resolve(options?.preload?.(target)).catch(() => {});
+            return [specifier, target] as const;
+          }
+          try {
+            return [specifier, await resolveEsmSh(target, imports)] as const;
+          } catch (error) {
+            // Dropping the entry would make this specifier permanently `missing`, so every stream chunk re-resolves and
+            // re-fetches it, and the heal message loses the `(→ https://esm.sh/…)` part that reverse-resolves from the
+            // import map. Fall back to the uncompiled target: the browser still fails on it, but with a diagnosable URL.
+            if (!warned.has(target)) {
+              warned.add(target);
+              console.warn(`Falling back to the uncompiled esm.sh target for ${specifier} (${target})`, error);
+            }
+
+            return [specifier, target] as const;
+          }
+        }),
+      );
+      return { imports: Object.fromEntries(entries) };
+    },
+  };
+}
 
 // A remote https module worth compiling is one that ships source the browser can't `import` directly. Already-JS URLs
 // (esm.sh builds, .mjs) import natively, so they pass through; only these source extensions need a transpile pass.
@@ -19,15 +162,18 @@ const langFromRemoteUrl = (url: string): "ts" | "tsx" | "jsx" => {
 // Fetches remote https TSX/TS/JSX components, compiles each to a blob: module, and hands back `{ [httpsUrl]: blobUrl }`
 // so the transform's importMap rewrites the original specifiers. Recurses into a remote module's own remote imports
 // (a global import graph breaks cycles even across concurrent entry branches; a per-provider cache dedupes DAGs and
-// survives across renders). React runtime singletons stay bare and resolve through the page's importmap, exactly like
-// the esm.sh fallback path.
-export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?: typeof fetch }): ImportMapProvider {
+// survives across renders). Every bare import is rewritten by @esm.sh/tsx: host-owned packages use the mappings already
+// resolved by earlier providers, and unknown packages use transformed esm.sh bundles.
+export function remoteModuleImportMap(options?: { baseUrl?: string; compiler?: TsxCompiler; fetch?: typeof fetch; dev?: boolean; dependencyRanges?: EsmShDependencyRanges; preloadEsmSh?: (url: string) => Promise<unknown> | unknown; resolveEsmSh?: EsmShModuleResolver }): ImportMapProvider {
   const compiler = options?.compiler ?? createTsxCompiler();
   const fetcher = options?.fetch ?? fetch;
   const blobByUrl = new Map<string, Promise<string>>();
-  // No `hasLocalPackage`: a remote module's own bare deps deliberately don't bind to the host's local /node_modules —
-  // third-party remote code resolves through esm.sh in every env, unlike the top-level chain's dev local-package preference.
-  const esmSh = esmShFallback();
+  // No `hasLocalPackage`: a bare dep the host map doesn't already own is never probed against the host's local
+  // /node_modules — it goes to esm.sh in every env, unlike the top-level chain's dev local-package preference. (Deps
+  // the host map DOES own bind to its targets, so one copy is shared instead of a second esm.sh build.)
+  // `dev` must match the top-level chain's: a remote module's esm.sh dep bundles its own reconciler, and a production
+  // one mixed with the page's dev jsx-runtime hits the missing-`getOwner` dispatcher.
+  const esmSh = transformedEsmShFallback({ dev: options?.dev, dependencyRanges: options?.dependencyRanges, baseUrl: options?.baseUrl, preload: options?.preloadEsmSh, resolveEsmSh: options?.resolveEsmSh, compiler, fetch: fetcher as unknown as (url: string) => Promise<EsmShModuleResponse> });
 
   // module → the remote modules it directly imports, recorded synchronously as each edge is discovered. A per-branch
   // `visited` set can't catch a cycle reached through two separate entry branches (a↔b where the entry imports both) —
@@ -48,15 +194,20 @@ export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?
     return false;
   };
 
+  // The host map is identical for every node in one graph walk, so `key` (its `importMapCacheKey`) is computed once per
+  // resolve() and threaded down with it — re-serializing per module would be O(nodes × map size).
+  type BaseMap = { imports: Readonly<Record<string, string>>; key: string };
+
   // Resolve a remote module's own imports to a self-contained import map, keyed by ABSOLUTE URL so the transform (given
   // the module's URL as `filename`) matches them after rebasing relatives: nested remote source → blob, bare npm dep →
-  // esm.sh. Relative browser-native deps (./x.mjs, ./x.css) need no entry — the transform rebases them to absolute URLs
-  // against `filename` on its own. Runtime singletons stay bare for the page importmap; esm.sh builds pass through.
-  // `identityUrl` is how importers reference this module (its request URL — the key for blobByUrl, the cycle graph, and
-  // eviction). `rebaseUrl` is the post-redirect `response.url`, used ONLY to resolve the module's relative imports. They
-  // must stay separate: keying edges by `rebaseUrl` would disconnect the graph at every redirect (a redirected node's
-  // own edges land under its final URL while every importer refers to it by its request URL → missed cross-branch cycle).
-  const collect = async (code: string, identityUrl: string, rebaseUrl: string): Promise<Record<string, string>> => {
+  // transformed esm.sh blobs. Relative browser-native deps (./x.mjs, ./x.css) need no entry — the transform rebases
+  // them to absolute URLs against `filename` on its own. Host runtime entries are passed through to the compiler too.
+  // `identityUrl` is how importers reference this module (its request URL — the cycle graph's key, and the URL half of
+  // the blobByUrl key). `rebaseUrl` is the post-redirect `response.url`, used ONLY to resolve the module's relative
+  // imports. They must stay separate: keying edges by `rebaseUrl` would disconnect the graph at every redirect (a
+  // redirected node's own edges land under its final URL while every importer refers to it by its request URL → missed
+  // cross-branch cycle).
+  const collect = async (code: string, identityUrl: string, rebaseUrl: string, base: BaseMap): Promise<Record<string, string>> => {
     const specifiers = [...extractModuleSpecifiers(code)];
     // Two passes on purpose. Pass 1 records every edge and checks cycles synchronously (no await) so a concurrent sibling
     // branch sees the edges — but it starts NO async work, so a mid-loop cyclic throw can't strand an already-launched
@@ -69,7 +220,7 @@ export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?
       // source extension (`@acme/ui/Button.tsx`, `pkg/foo.ts`) must stay bare for esm.sh — rebasing it first would turn
       // it into a bogus `https://…/pkg/foo.ts` remote fetch that 404s before the fallback can map the package.
       if (isBareModuleSpecifier(specifier)) {
-        if (!isRuntimeSingletonSpecifier(specifier)) bareMissing.push(specifier);
+        if (!hasImportMapEntry(base.imports, specifier)) bareMissing.push(specifier);
         continue;
       }
       const absolute = new URL(specifier, rebaseUrl).href;
@@ -78,12 +229,13 @@ export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?
       if (reaches(absolute, identityUrl)) throw new Error(`Cyclic remote module import: ${absolute}`);
       deps.add(absolute);
     }
-    const [remote, bare] = await Promise.all([Promise.all([...deps].map((absolute) => resolveModule(absolute).then((blob) => [absolute, blob] as const))), esmSh.resolve({ code, missing: bareMissing })]);
-    return { ...bare.imports, ...Object.fromEntries(remote) };
+    const [remote, bare] = await Promise.all([Promise.all([...deps].map((absolute) => resolveModule(absolute, base).then((blob) => [absolute, blob] as const))), esmSh.resolve({ code, missing: bareMissing, imports: base.imports })]);
+    return { ...base.imports, ...bare.imports, ...Object.fromEntries(remote) };
   };
 
-  const resolveModule = (url: string): Promise<string> => {
-    let blob = blobByUrl.get(url);
+  const resolveModule = (url: string, base: BaseMap): Promise<string> => {
+    const cacheKey = `${url}\n${base.key}`;
+    let blob = blobByUrl.get(cacheKey);
     if (!blob) {
       blob = (async () => {
         const response = await fetcher(url);
@@ -92,7 +244,7 @@ export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?
         // A CDN/raw endpoint may redirect to a versioned/storage URL; rebase the module's relative imports against the
         // final `response.url` (falling back to the request URL) so `./Leaf.tsx` resolves from the right directory.
         const finalUrl = response.url || url;
-        const imports = await collect(source, url, finalUrl);
+        const imports = await collect(source, url, finalUrl, base);
         // filename = the module's own URL so the transform rebases its relative imports against it (matching the
         // absolute-keyed entries above, and turning relative browser-native imports into absolute URLs natively).
         const { code } = await compiler.compile(source, { filename: finalUrl, lang: langFromRemoteUrl(url), importMap: { imports } });
@@ -101,10 +253,10 @@ export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?
       // A failed fetch/compile must not pin this URL for the provider's lifetime — evict the rejected promise so a
       // later render retries, mirroring probeEsmShSpecifier's fail-open eviction.
       blob.catch(() => {
-        blobByUrl.delete(url);
+        blobByUrl.delete(cacheKey);
         importsOf.delete(url);
       });
-      blobByUrl.set(url, blob);
+      blobByUrl.set(cacheKey, blob);
     }
     return blob;
   };
@@ -112,8 +264,10 @@ export function remoteModuleImportMap(options?: { compiler?: TsxCompiler; fetch?
   // The entry code isn't fetched or compiled here — the outer resolver chain compiles it and maps its bare specifiers,
   // so this provider only surfaces its remote-source imports as blob: entries (keyed by their already-absolute URL).
   return {
-    resolve: async ({ code }): Promise<RendererImportMap> => {
-      const entries = await Promise.all([...extractModuleSpecifiers(code)].flatMap((specifier) => (isRemoteSourceModuleSpecifier(specifier) ? [resolveModule(specifier).then((blob) => [specifier, blob] as const)] : [])));
+    resolve: async ({ code, imports = {} }): Promise<RendererImportMap> => {
+      const compilerImports = prepareRendererImportMap({ imports }, options?.baseUrl).imports;
+      const base: BaseMap = { imports: compilerImports, key: importMapCacheKey(Object.entries(compilerImports)) };
+      const entries = await Promise.all([...extractModuleSpecifiers(code)].flatMap((specifier) => (isRemoteSourceModuleSpecifier(specifier) ? [resolveModule(specifier, base).then((blob) => [specifier, blob] as const)] : [])));
       return { imports: Object.fromEntries(entries) };
     },
   };

package/src/runtime.ts

@@ -3,6 +3,8 @@ import { createRoot, type Root } from "react-dom/client";
 import { renderToString } from "react-dom/server";
 import { createGeneratedComponentSlot, type GeneratedComponent, type GeneratedComponentSlot } from "./state";
 export type { GeneratedComponent } from "./state";
+import { enrichModuleImportError } from "./importProbe";
+export { GenUIImportError, type GenUIImportDiagnostic } from "./importProbe";
 import { createTsxCompiler, type TsxCompiler, type CompileResult } from "./compiler";
 import { GenUIRenderContext, getGenUIRenderContextValue } from "./renderContext";
 import { getGenUIHookSignature } from "./hookSignature";
@@ -12,7 +14,9 @@ export type GenUIRenderPhase = "transform" | "compile" | "render";
 export type GenUIRendererCallbacks = { onReady?: (component: GeneratedComponent, url?: string, code?: string) => void; onRendered?: (component: GeneratedComponent, code: string, serial?: number) => void; onError?: (error: Error, phase: GenUIRenderPhase) => void };
 export type GenUIRendererClearOptions = { preserveVisualState?: boolean };
 export type GenUIRendererFlushMode = "microtask" | "immediate";
-export type GenUIRendererOptions = { importmap?: RendererImportMap; callbacks?: GenUIRendererCallbacks; compiler?: TsxCompiler; preserveStateOnUpdate?: boolean; flushMode?: GenUIRendererFlushMode };
+// `filename` is the base @esm.sh/tsx resolves relative specifiers against. Hosts that render a file from disk pass its
+// path so `./data` stays `./data`; without one the default `_.tsx` turns it into the unresolvable `_.tsx/data` (#1601).
+export type GenUIRendererOptions = { importmap?: RendererImportMap; callbacks?: GenUIRendererCallbacks; compiler?: TsxCompiler; preserveStateOnUpdate?: boolean; flushMode?: GenUIRendererFlushMode; filename?: string };
 export type GenUIRendererUpdateMode = "push" | "render";
 
 const attachedRenderer = Symbol.for("@macaron/genui-runtime:attached-renderer");
@@ -32,22 +36,27 @@ const rememberCompiledComponent = (code: string, component: GeneratedComponent)
   }
 };
 
-class RuntimeErrorBoundary extends Component<{ resetKey?: number; onError?: (error: Error) => void; children?: ReactNode }, { hasError: boolean; lastResetKey?: number }> {
-  state = { hasError: false, lastResetKey: undefined as number | undefined };
-  static getDerivedStateFromError() {
-    return { hasError: true };
+type RuntimeErrorBoundaryState = { hasError: boolean; message?: string; lastResetKey?: number };
+
+class RuntimeErrorBoundary extends Component<{ resetKey?: number; onError?: (error: Error) => void; children?: ReactNode }, RuntimeErrorBoundaryState> {
+  state: RuntimeErrorBoundaryState = { hasError: false };
+  // React forwards whatever was thrown, including primitives and null; normalize before reading `.message`.
+  static getDerivedStateFromError(error: unknown) {
+    return { hasError: true, message: normalizeError(error).message };
   }
-  static getDerivedStateFromProps(props: { resetKey?: number }, state: { hasError: boolean; lastResetKey?: number }) {
+  static getDerivedStateFromProps(props: { resetKey?: number }, state: RuntimeErrorBoundaryState) {
     // Streaming errors bump resetKey to clear the caught state in place; recreating the boundary via `key`
     // would unmount the entire subtree below and produce visible flicker on every retry.
-    if (props.resetKey !== state.lastResetKey) return { hasError: false, lastResetKey: props.resetKey };
+    if (props.resetKey !== state.lastResetKey) return { hasError: false, message: undefined, lastResetKey: props.resetKey };
     return null;
   }
-  componentDidCatch(error: Error) {
-    this.props.onError?.(error);
+  componentDidCatch(error: unknown) {
+    this.props.onError?.(normalizeError(error));
   }
   render() {
-    if (this.state.hasError) return "ERROR";
+    // Hosts that pass onError paint their own error UI over this; hosts that don't (few-shots, batch) used to be
+    // left with a bare "ERROR" and nothing to diagnose from.
+    if (this.state.hasError) return this.state.message ? `ERROR: ${this.state.message}` : "ERROR";
     return this.props.children;
   }
 }
@@ -80,6 +89,7 @@ export class GenUIRenderer {
   private finished = false;
   private flushMode: GenUIRendererFlushMode;
   private importmap?: RendererImportMap;
+  private filename?: string;
   private lastCompiledCode = "";
   private lastGoodHookSignature = "";
   private lastHookSignature: string | null = null;
@@ -98,6 +108,7 @@ export class GenUIRenderer {
     this.compiler = options.compiler ?? createTsxCompiler();
     this.flushMode = options.flushMode ?? "microtask";
     this.importmap = options.importmap;
+    this.filename = options.filename;
     this.preserveStateOnUpdate = options.preserveStateOnUpdate ?? true;
     this.rendererScope = createRendererScope();
     this.slot = createGeneratedComponentSlot();
@@ -290,7 +301,7 @@ export class GenUIRenderer {
     const code = this.currentBuffer;
     let result: CompileResult;
     try {
-      result = await this.compiler.compile(code, { importMap: this.importmap, partial: partial && !this.finished, previousCode: this.lastCompiledCode });
+      result = await this.compiler.compile(code, { importMap: this.importmap, partial: partial && !this.finished, previousCode: this.lastCompiledCode, filename: this.filename });
     } catch (error) {
       // A queued follow-up means this frame is already superseded; its error is stale noise (pre-single-flight, the
       // newer compile's serial bump suppressed it the same way).
@@ -333,7 +344,19 @@ export class GenUIRenderer {
     if (cached) return { component: cached };
     const moduleUrl = URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
     try {
-      const module = (await import(/* @vite-ignore */ moduleUrl)) as { default?: GeneratedComponent };
+      let module: { default?: GeneratedComponent };
+      try {
+        // The specifier is a runtime-built blob URL, so every bundler must leave it alone: @vite-ignore for Vite,
+        // webpackIgnore for webpack/Rspack, turbopackIgnore for Turbopack. Dropping any of them makes the host bundler
+        // resolve it at build time and the renderer dies with `Cannot find module 'unknown'`. #1688
+        module = (await import(/* @vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ moduleUrl)) as { default?: GeneratedComponent };
+      } catch (error) {
+        // The browser reports a failed blob module as one opaque "Failed to fetch dynamically imported module" without
+        // naming the entry that broke; re-probe each dependency to raise an actionable, heal-ready error instead. #1371
+        throw await enrichModuleImportError(error, code, this.importmap?.imports);
+      }
+      // A missing default is a transient "stream not finished yet" frame, not a dependency failure: the blob import
+      // resolved, so every dependency already linked, and probing would re-scan cached modules to no effect.
       if (!module.default) throw new Error("No default export found in compiled module.");
       rememberCompiledComponent(code, module.default);
       return { component: module.default, moduleUrl };