partial-react 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,57 @@
+# partial-react
+
+Renderer for generated React/TSX.
+
+## Input
+
+`GenUIRenderer` accepts TSX source strings:
+
+```ts
+import { GenUIRenderer } from "partial-react";
+
+const renderer = await GenUIRenderer.create(document.getElementById("preview"), {
+  preserveStateOnUpdate: true,
+  callbacks: {
+    onRendered: (_component, code) => console.log(code),
+    onError: (error, phase) => console.error(phase, error),
+  },
+});
+
+renderer.render("export default function App() { return <div>Hello world</div>; }");
+```
+
+## Output
+
+- The target element receives a React preview.
+- `onReady(component, url, code)` fires after a module compiles and imports.
+- `onRendered(component, code, serial)` fires after React commits.
+- `onError(error, phase)` reports `"transform"`, `"compile"`, or `"render"`.
+
+## Imports
+
+```ts
+import { GenUIRenderer } from "partial-react";
+import { createTsxCompiler } from "partial-react/compiler";
+import { mergeFallbackImports, prepareRendererImportMap } from "partial-react/import-map";
+import { useGenUIRenderContext } from "partial-react/render-context";
+```
+
+## State and Streaming
+
+- Keep `preserveStateOnUpdate: true` for normal previews. It preserves useful React state and DOM continuity across regenerated code.
+- Set `preserveStateOnUpdate: false` only when every update should remount from scratch, usually while debugging renderer state bugs.
+- Use the preview wrapper's `streaming` prop (`GenUIPreviewHost` / `StaticGenUIRenderer`) when the input is still growing or being patched in place. It treats the code as partial TSX and avoids surfacing transient mid-stream errors.
+- Leave `streaming` off for complete snapshots, final answers, history replay, and deterministic one-shot renders.
+
+## Corner Cases
+
+- `render(code)` replaces the current buffer with a complete TSX module.
+- `clear({ preserveVisualState: true })` clears pending code but leaves the last visual tree in place.
+- Missing default exports fail at compile/import time.
+- Render failures call `onError` and, with state preservation on, try to restore the last good component.
+
+## Test
+
+```sh
+bun test lib/partial-react
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "partial-react",
   "description": "A state-preserving renderer for prefix-growing streaming React/TSX.",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -9,9 +9,10 @@
     "directory": "lib/partial-react"
   },
   "exports": {
-    ".": "./src/runtime.tsx",
+    ".": "./src/runtime.ts",
     "./compiler": "./src/compiler.ts",
     "./import-map": "./src/importMap.ts",
+    "./remote-module": "./src/remoteModule.ts",
     "./render-context": "./src/renderContext.ts"
   },
   "files": [
@@ -19,8 +20,8 @@
     "!src/**/*.test.*"
   ],
   "dependencies": {
-    "@esm.sh/tsx": "^1.5.0",
-    "partial-tsx": "0.0.1"
+    "@esm.sh/tsx": "^1.5.3",
+    "partial-tsx": "0.0.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/compiler.ts

@@ -1,24 +1,25 @@
 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; jsxImportSource?: string };
+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 };
 export type TsxCompiler = { compile: (code: string, options?: CompileOptions) => Promise<CompileResult> };
 
 let initPromise: Promise<unknown> | null = null;
 const loadNodeWasm = async () => {
-  if (typeof Bun === "undefined") throw new Error("Bun runtime is required to load local TSX WASM in tests.");
-  const wasmPath = new URL(import.meta.resolve("@esm.sh/tsx/pkg/tsx_bg.wasm"));
-  return Bun.file(wasmPath).arrayBuffer();
+  // `import.meta.resolve` yields a `file://` URL under both Bun and Node/Vite SSR, so `new URL` is safe — don't "fix" it with pathToFileURL.
+  const wasmUrl = new URL(import.meta.resolve("@esm.sh/tsx/pkg/tsx_bg.wasm"));
+  if (typeof Bun !== "undefined") return Bun.file(wasmUrl).arrayBuffer();
+  return (await import("node:fs/promises")).readFile(wasmUrl);
 };
 const initCompiler = () =>
   (initPromise ??= (async () => {
     try {
       if (typeof window === "undefined") return initTsx(await loadNodeWasm());
     } catch {
-      // Browser builds should use Vite's asset URL; Node tests use the direct filesystem path above.
+      // Environments without a filesystem (e.g. web workers) fall back to Vite's asset URL below.
     }
     return initTsx(tsxWasmUrl);
   })().catch((error) => {
@@ -30,8 +31,9 @@ export function createTsxCompiler(): TsxCompiler {
   return {
     async compile(code, options = {}) {
       await initCompiler();
-      const source = options.partial ? normalizeGeneratedTsx(code) : code;
-      const result = transformTsx({ filename: options.filename ?? "_.tsx", code: source, target: "es2022", importMap: options.importMap, jsxImportSource: options.jsxImportSource ?? "react" });
+      const source = options.partial ? normalizeGeneratedTsx(code, { mode: "streaming" }) : code;
+      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/hookSignature.ts

@@ -146,7 +146,7 @@ const shouldStartJsxTag = (code: string, index: number) => {
   return jsxPrefixKeywords.has(word);
 };
 const scanHookSignatureJs = (code: string, hooks: string[], context: HookSignatureContext, start = 0, end = code.length): number => {
-  for (let index = start; index < end; ) {
+  for (let index = start; index < end;) {
     const char = code[index];
     if (char === "/" && code[index + 1] === "/") index = skipLineComment(code, index);
     else if (char === "/" && code[index + 1] === "*") index = skipBlockComment(code, index);

package/src/importMap.ts

@@ -1,12 +1,31 @@
-export type RendererImportMap = { imports?: Record<string, string> };
+export type RendererImportMap = { imports?: Record<string, string>; scopes?: Record<string, Record<string, string>>; styles?: string[] };
 
-const ESM_SH_VERSION_OVERRIDES = { "@number-flow/react": "0.6.0" } as const;
+// 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[]; imports?: Readonly<Record<string, string>> };
+export type ImportMapProvider = { kind?: "base" | "fallback"; prefetch?: () => Promise<unknown> | void; resolve: (context: ImportMapProviderContext) => RendererImportMap | Promise<RendererImportMap> };
+
+// 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];
+export const isRuntimeSingletonSpecifier = (specifier: string): specifier is RuntimeSingletonSpecifier => RUNTIME_SINGLETON_SPECIFIERS.includes(specifier as RuntimeSingletonSpecifier);
+// A trailing-slash import-map key also owns matching singleton subpaths.
+export const isRuntimeSingletonImportMapKey = (specifier: string) => isRuntimeSingletonSpecifier(specifier) || (specifier.endsWith("/") && RUNTIME_SINGLETON_SPECIFIERS.some((runtimeSpecifier) => runtimeSpecifier.startsWith(specifier)));
 const IDENTIFIER_CHAR_PATTERN = /[\w$]/;
 const REGEX_PREFIX_WORDS = new Set(["return", "throw", "case", "delete", "typeof", "void", "new", "in", "of", "await", "yield"]);
 const LOCAL_EXPORT_KEYWORDS = ["abstract", "async", "class", "const", "declare", "default", "enum", "function", "interface", "let", "namespace", "var"];
 
 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/");
 const canUseEsmShFallback = (specifier: string) => isBareModuleSpecifier(specifier) && !specifier.startsWith("@/");
 
 const isKeywordAt = (code: string, index: number, keyword: string) => code.startsWith(keyword, index) && !IDENTIFIER_CHAR_PATTERN.test(code[index - 1] ?? "") && !IDENTIFIER_CHAR_PATTERN.test(code[index + keyword.length] ?? "");
@@ -52,11 +71,13 @@ const readStringLiteral = (code: string, index: number) => {
       index += 2;
       continue;
     }
-    if (char === quote) return { value, end: index + 1 };
+    if (char === quote) return { value, end: index + 1, terminated: true };
     value += char;
     index += 1;
   }
-  return { value, end: code.length };
+  // Unterminated literal (a streamed import mid-chunk, e.g. `import X from "https://x/Foo.ts`). Report end so scanning
+  // still advances past it, but flag it so callers don't treat a half-typed specifier as a real import to fetch.
+  return { value, end: code.length, terminated: false };
 };
 
 const skipTemplateLiteral = (code: string, index: number, onExpression?: (start: number, end: number) => void) => {
@@ -171,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 };
+      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;
     }
@@ -189,7 +211,99 @@ const readExportFromSpecifier = (code: string, index: number) => {
   return readFromSpecifier(code, next);
 };
 
-const collectBareModuleSpecifiers = (code: string, specifiers: Set<string>, 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] === "/") {
@@ -209,39 +323,110 @@ const collectBareModuleSpecifiers = (code: string, specifiers: Set<string>, star
       continue;
     }
     if (char === "`") {
-      index = skipTemplateLiteral(code, index, (expressionStart, expressionEnd) => collectBareModuleSpecifiers(code, specifiers, 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?.value && isBareModuleSpecifier(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 } : readFromSpecifier(code, afterImport);
-      if (from?.specifier && isBareModuleSpecifier(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?.specifier && isBareModuleSpecifier(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>();
-  collectBareModuleSpecifiers(code, specifiers);
+  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;
+}
+
+// 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) {
@@ -251,25 +436,251 @@ export function hasImportMapEntry(imports: Record<string, string> | Set<string>
   return false;
 }
 
-export function toEsmShImportUrl(specifier: string) {
+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("?") ? "&" : "?";
-  return `https://esm.sh/${versionedSpecifier}${separator}bundle&target=es2022&external=react,react-dom,scheduler`;
+  // 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/${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 };
+type EsmShProbeFetch = (url: string) => Promise<Pick<Response, "ok" | "status" | "text" | "json">>;
+// esm.sh 404/2xx verdicts are deterministic per specifier, so they're cached for the process lifetime; transient
+// fail-open verdicts (5xx/rate-limit/network) are evicted on resolve so they don't pin. Tests inject a fetcher and
+// must use per-test specifiers to dodge the shared cache.
+const esmShProbeCache = new Map<string, Promise<EsmShProbe | null>>();
+
+// A dead entry usually means the model hallucinated the package or its layout; the registry's real subpaths are the
+// heal signal that lets it rewrite the import in one shot.
+const MAX_HINT_SUBPATHS = 8; // enough real subpaths for the model to spot the right one without bloating the diagnostic
+const registryExportsHint = async (packageName: string, fetcher: EsmShProbeFetch) => {
+  const response = await fetcher(`https://registry.npmjs.org/${packageName}/latest`);
+  if (!response.ok) return response.status === 404 ? "the package does not exist on npm" : "";
+  const { exports: exportsMap } = (await response.json()) as { exports?: Record<string, unknown> };
+  const subpaths = Object.keys(exportsMap ?? {}).filter((key) => key.startsWith("./"));
+  return subpaths.length ? `its real exports subpaths are ${subpaths.slice(0, MAX_HINT_SUBPATHS).join(", ")}${subpaths.length > MAX_HINT_SUBPATHS ? `, … (${subpaths.length} total)` : ""}` : "";
+};
+
+// Would the esm.sh fallback actually answer this specifier at render time? Null means the fallback never applies
+// (relative path, `@/` alias) — the caller should leave its own resolution verdict alone. Only a deterministic 404
+// condemns an import: network failures and 5xx must not fail checks that run offline or during an esm.sh incident. #1372
+export const probeEsmShSpecifier = (specifier: string, fetcher: EsmShProbeFetch = fetch): Promise<EsmShProbe | null> => {
+  let probe = esmShProbeCache.get(specifier);
+  if (!probe) {
+    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;
+      }
+      // A non-404 status esm.sh can't build deterministically (5xx incident, 429/403 npm rate-limit) or a network
+      // failure fails open so offline `check` still passes, but that verdict isn't deterministic; evict it so a
+      // genuinely-dead import isn't pinned `alive` for the host's lifetime.
+      const failOpenTransiently = (): EsmShProbe => {
+        esmShProbeCache.delete(specifier);
+        return { alive: true };
+      };
+      try {
+        const response = await fetcher(url);
+        if (response.status === 404) {
+          const body = (await response.text()).trim().split("\n")[0];
+          const hint = await registryExportsHint(getBarePackageName(specifier), fetcher).catch(() => "");
+          return { alive: false, detail: `The renderer's esm.sh fallback fails too (404: ${body})${hint ? `; ${hint}` : ""}.` };
+        }
+        // Only a 2xx means esm.sh actually resolved the build; anything else joins the fail-open path above.
+        return response.ok ? { alive: true } : failOpenTransiently();
+      } catch {
+        return failOpenTransiently();
+      }
+    })();
+    esmShProbeCache.set(specifier, probe);
+  }
+  return probe;
+};
+
+// `build` fetch-bundles remote http(s) module imports and dev/the runtime import them directly, so the URL itself is
+// the authority to consult before condemning a remote specifier's TS2307 (#1468). Same doctrine as the esm.sh probe:
+// only a deterministic 404 condemns; transient verdicts (5xx/rate-limit/network) fail open and are evicted so they don't pin.
+const remoteModuleProbeCache = new Map<string, Promise<EsmShProbe>>();
+export const probeRemoteModuleUrl = (url: string, fetcher: EsmShProbeFetch = fetch): Promise<EsmShProbe> => {
+  let probe = remoteModuleProbeCache.get(url);
+  if (!probe) {
+    probe = (async (): Promise<EsmShProbe> => {
+      const failOpenTransiently = (): EsmShProbe => {
+        remoteModuleProbeCache.delete(url);
+        return { alive: true };
+      };
+      try {
+        const response = await fetcher(url);
+        if (response.status === 404) return { alive: false, detail: `The renderer's remote module fetch fails too (404: ${(await response.text()).trim().split("\n")[0]}).` };
+        return response.ok ? { alive: true } : failOpenTransiently();
+      } catch {
+        return failOpenTransiently();
+      }
+    })();
+    remoteModuleProbeCache.set(url, probe);
+  }
+  return probe;
+};
+
+// One probe for every specifier `check`'s local TS resolution can't see: remote http(s) URLs consult the origin itself,
+// bare specifiers consult the esm.sh fallback, anything else (relative path, `@/` alias) keeps the caller's own verdict.
+export const probeImportSpecifier = (specifier: string, fetcher: EsmShProbeFetch = fetch): Promise<EsmShProbe | null> => (/^https?:\/\//i.test(specifier) ? probeRemoteModuleUrl(specifier, fetcher) : probeEsmShSpecifier(specifier, fetcher));
+
 export function prepareRendererImportMap(map: RendererImportMap | null | undefined, baseUrl = typeof location === "undefined" ? undefined : location.href) {
-  const imports = Object.fromEntries(Object.entries(map?.imports ?? {}).map(([specifier, target]) => [specifier, baseUrl ? new URL(target, baseUrl).href : target]));
-  return { imports };
+  const resolveTarget = (target: string) => (baseUrl ? new URL(target, baseUrl).href : target);
+  const resolveEntries = (entries: Record<string, string>) => Object.fromEntries(Object.entries(entries).map(([specifier, target]) => [specifier, resolveTarget(target)]));
+  const imports = resolveEntries(map?.imports ?? {});
+  const styles = map?.styles?.map(resolveTarget);
+  const scopes = map?.scopes && Object.fromEntries(Object.entries(map.scopes).map(([scope, entries]) => [scope, resolveEntries(entries)]));
+  return { imports, ...(scopes ? { scopes } : {}), ...(styles?.length ? { styles } : {}) };
+}
+
+export function literalImportMap(map: RendererImportMap): ImportMapProvider {
+  return { resolve: () => map };
+}
+
+// Loads a remote/JSON import map once. `prefetch()` and `resolve()` share the in-flight promise so an idle-time
+// prefetch and a later render both reuse the same fetch instead of hitting the network twice.
+export function urlImportMap(source: string, options?: { kind?: ImportMapProvider["kind"]; fetch?: (source: string) => Promise<Pick<Response, "ok" | "status" | "statusText" | "json">> }): ImportMapProvider {
+  const fetcher = options?.fetch ?? fetch;
+  let loadPromise: Promise<RendererImportMap> | undefined;
+  const load = () =>
+    (loadPromise ??= (async () => {
+      const response = await fetcher(source);
+      if (!response.ok) throw new Error(`Failed to load import map ${source}: ${response.status} ${response.statusText}`);
+      const baseUrl = typeof location === "undefined" ? source : new URL(source, location.href).href;
+      return prepareRendererImportMap((await response.json()) as RendererImportMap, baseUrl);
+    })());
+  return { kind: options?.kind ?? "base", prefetch: load, resolve: load };
+}
+
+// Node-only: resolve `packageName`'s package.json#genui.importMap into a provider. Relative targets (./dist/…) are
+// rebased to absolute disk paths so Vite/Rollup can load them; absolute paths and URLs pass through. Throws if the
+// package declares no genui.importMap. Resolution is from the caller's cwd (where the user installed the package),
+// not this file's location — so `bunx @genui/cli -i @macaron/ui` finds the user's package, not the CLI's. node:
+// imports stay inside resolve() so this module remains browser-bundleable.
+export function packageImportMap(packageName: string, options?: { resolve?: (name: string) => string }): ImportMapProvider {
+  return {
+    resolve: async () => {
+      const [{ createRequire }, { readFile }, { dirname, resolve: resolvePath }] = await Promise.all([import("node:module"), import("node:fs/promises"), import("node:path")]);
+      const resolveName = options?.resolve ?? createRequire(resolvePath("package.json")).resolve;
+      const manifestPath = resolveName(`${packageName}/package.json`);
+      const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as { genui?: { importMap?: RendererImportMap } };
+      const importMap = manifest.genui?.importMap;
+      if (!importMap) throw new Error(`${packageName} has no package.json#genui.importMap — add it to declare the GenUI importmap contract`);
+      const packageDir = dirname(manifestPath);
+      const rebase = (target: string) => (target.startsWith(".") ? resolvePath(packageDir, target) : target);
+      return { imports: Object.fromEntries(Object.entries(importMap.imports ?? {}).map(([specifier, target]) => [specifier, rebase(target)])), styles: importMap.styles?.map(rebase) };
+    },
+  };
+}
+
+// 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[]; 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, { dev: options?.dev, dependencyRanges: options?.dependencyRanges })] as const;
+        }),
+      );
+      return { imports: Object.fromEntries(entries) };
+    },
+  };
+}
+
+export function createImportMapResolver(providers: ImportMapProvider[]) {
+  return {
+    // Idle/build-time warmup only touches base providers. Fallback providers stay lazy until resolve() has scanned the
+    // TSX for missing specifiers, so prefetching them would fetch remote maps the rendered code may never reference.
+    prefetch: () => Promise.all(providers.filter((provider) => provider.kind !== "fallback").map((provider) => provider.prefetch?.())).then(() => undefined),
+    async resolve({ code = "" }: { code?: string } = {}) {
+      const required = [...extractBareModuleSpecifiers(code)];
+      let imports: Record<string, string> = {};
+      let scopes: RendererImportMap["scopes"];
+      let styles: string[] | undefined;
+      for (const provider of providers) {
+        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, 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.
+        if (next.scopes) scopes = { ...scopes, ...next.scopes };
+        if (next.styles?.length) styles = [...(styles ?? []), ...next.styles];
+      }
+      return { imports, ...(scopes ? { scopes } : {}), ...(styles?.length ? { styles: [...new Set(styles)] } : {}) };
+    },
+  };
 }
 
-export async function mergeFallbackImports(imports: Record<string, string>, code: string, options?: { hasLocalPackage?: (packageName: string) => Promise<boolean> }) {
-  const next = { ...imports };
-  const knownSpecifiers = new Set(Object.keys(next));
-  const fallbackSpecifiers = [...extractBareModuleSpecifiers(code)].filter((specifier) => !hasImportMapEntry(knownSpecifiers, specifier) && canUseEsmShFallback(specifier));
-  const localPackageMatches = await Promise.all(fallbackSpecifiers.map((specifier) => options?.hasLocalPackage?.(getBarePackageName(specifier))));
-  for (const [index, specifier] of fallbackSpecifiers.entries()) next[specifier] = localPackageMatches[index] ? `/node_modules/${specifier}` : toEsmShImportUrl(specifier);
-  return next;
+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,62 @@
+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 {
+      module = (await import(/* @vite-ignore */ 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

@@ -0,0 +1,274 @@
+import { createTsxCompiler, type TsxCompiler } from "./compiler";
+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.
+// Only the path decides — a source extension inside a query/hash (`?path=lib/index.ts`) belongs to a native URL that must
+// pass through, not a source module to compile. Splitting off `[?#]` keeps `a.tsx?v=1` matching while dropping that case.
+const REMOTE_SOURCE_EXTENSION = /\.(?:tsx|ts|jsx|mts|cts)$/;
+export const isRemoteSourceModuleSpecifier = (specifier: string) => /^https?:\/\//.test(specifier) && REMOTE_SOURCE_EXTENSION.test(specifier.split(/[?#]/, 1)[0]);
+// The compiler picks its parser from the filename extension, but `filename` must be the post-redirect URL (to rebase
+// relative imports) which a CDN often strips to a signed, extension-less path — so JSX/TS in a redirected module would
+// parse as plain JS and fail. Derive `lang` from the REQUEST URL, which always carries a real source extension, and pass
+// it explicitly so the parser is fixed regardless of where the fetch redirected to.
+const langFromRemoteUrl = (url: string): "ts" | "tsx" | "jsx" => {
+  const ext = REMOTE_SOURCE_EXTENSION.exec(url.split(/[?#]/, 1)[0])?.[0];
+  return ext === ".tsx" ? "tsx" : ext === ".jsx" ? "jsx" : "ts"; // .mts/.cts/.ts all parse as ts; only .tsx/.jsx enable 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). 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 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) —
+  // each branch caches an in-flight promise before the other's traversal sees the loop, so they await each other and
+  // hang. This global graph makes the cross-branch cycle observable regardless of which branch discovers the edge first.
+  const importsOf = new Map<string, Set<string>>();
+  const reaches = (from: string, target: string): boolean => {
+    const seen = new Set<string>();
+    const stack = [from];
+    while (stack.length) {
+      const url = stack.pop()!;
+      if (url === target) return true;
+      if (seen.has(url)) continue;
+      seen.add(url);
+      const deps = importsOf.get(url);
+      if (deps) stack.push(...deps);
+    }
+    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 →
+  // 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
+    // resolveModule() as an unhandled rejection. Pass 2 launches the fetches once the whole edge set is known valid.
+    let deps = importsOf.get(identityUrl);
+    if (!deps) importsOf.set(identityUrl, (deps = new Set()));
+    const bareMissing: string[] = [];
+    for (const specifier of specifiers) {
+      // Rebase only relative/absolute paths against the module URL. A bare specifier whose subpath happens to end in a
+      // 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 (!hasImportMapEntry(base.imports, specifier)) bareMissing.push(specifier);
+        continue;
+      }
+      const absolute = new URL(specifier, rebaseUrl).href;
+      if (!isRemoteSourceModuleSpecifier(absolute)) continue;
+      // A cycle exists iff the dependency can already reach this module (reaches() returns true for a direct self-import too).
+      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, 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, base: BaseMap): Promise<string> => {
+    const cacheKey = `${url}\n${base.key}`;
+    let blob = blobByUrl.get(cacheKey);
+    if (!blob) {
+      blob = (async () => {
+        const response = await fetcher(url);
+        if (!response.ok) throw new Error(`Failed to fetch remote module ${url}: ${response.status} ${response.statusText}`);
+        const source = await response.text();
+        // 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, 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 } });
+        return URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
+      })();
+      // 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(cacheKey);
+        importsOf.delete(url);
+      });
+      blobByUrl.set(cacheKey, blob);
+    }
+    return blob;
+  };
+
+  // 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, 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.tsx → runtime.ts}

@@ -1,17 +1,22 @@
 import { Component, createElement, useEffect, type ComponentType, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { renderToString } from "react-dom/server";
-import { createGeneratedComponentSlot, type GeneratedComponentSlot } from "./state";
+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";
 import type { RendererImportMap } from "./importMap";
 
 export type GenUIRenderPhase = "transform" | "compile" | "render";
-export type GenUIRendererCallbacks = { onReady?: (component: unknown, url?: string, code?: string) => void; onRendered?: (component: unknown, code: string, serial?: number) => void; onError?: (error: Error, phase: GenUIRenderPhase) => void };
+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");
@@ -20,9 +25,9 @@ const normalizeError = (error: unknown) => (error instanceof Error ? error : new
 const COMPILED_COMPONENT_CACHE_LIMIT = 256;
 let rendererScopeSerial = 0;
 const createRendererScope = () => `renderer:${(rendererScopeSerial += 1).toString(36)}`;
-const compiledComponentCache = new Map<string, unknown>();
+const compiledComponentCache = new Map<string, GeneratedComponent>();
 const getPreserveBoundaryKey = (epoch: number) => (epoch === 0 ? "boundary" : `boundary:${epoch}`);
-const rememberCompiledComponent = (code: string, component: unknown) => {
+const rememberCompiledComponent = (code: string, component: GeneratedComponent) => {
   if (compiledComponentCache.has(code)) compiledComponentCache.delete(code);
   compiledComponentCache.set(code, component);
   if (compiledComponentCache.size > COMPILED_COMPONENT_CACHE_LIMIT) {
@@ -31,22 +36,27 @@ const rememberCompiledComponent = (code: string, component: unknown) => {
   }
 };
 
-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;
   }
 }
@@ -71,12 +81,15 @@ export class GenUIRenderer {
   private currentBuffer = "";
   private compileScheduled = false;
   private compileScheduleToken = 0;
+  private compileRunning = false;
+  private compilePending: { partial: boolean; serial?: number } | null = null;
   private scheduledPartial = false;
   private scheduledSerial?: number;
   private errorEpoch = 0;
   private finished = false;
   private flushMode: GenUIRendererFlushMode;
   private importmap?: RendererImportMap;
+  private filename?: string;
   private lastCompiledCode = "";
   private lastGoodHookSignature = "";
   private lastHookSignature: string | null = null;
@@ -95,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();
@@ -124,7 +138,9 @@ export class GenUIRenderer {
 
   detach() {
     // Bump compileSerial so any in-flight compile resolves into a no-op instead of adopting onto a dead renderer.
+    // Drop the queued follow-up too: it would start a fresh chain (self-consistent serial) that the bump can't invalidate.
     this.compileSerial += 1;
+    this.compilePending = null;
     const previous = this.target as AttachableHost | null;
     if (previous && previous[attachedRenderer] === this) delete previous[attachedRenderer];
     this.root?.unmount();
@@ -221,6 +237,7 @@ export class GenUIRenderer {
     this.scheduledPartial = false;
     this.scheduledSerial = undefined;
     this.compileScheduleToken += 1;
+    this.compilePending = null;
     this.lastCompiledCode = "";
     if (options.preserveVisualState) return this;
     this.lastGoodHookSignature = "";
@@ -259,13 +276,36 @@ export class GenUIRenderer {
   }
 
   private async compile(partial: boolean, renderSerial?: number) {
+    // A compile chain (transform + blob import) spans multiple event-loop turns, so under per-frame pushes starting a
+    // new chain per push keeps bumping compileSerial and every in-flight result resolves superseded — nothing commits
+    // until the pushes stop (the storyboard's per-rAF typewriter froze previews this way). Run chains single-flight:
+    // remember only the latest request and start it once the current chain settles; compileOnce reads currentBuffer
+    // fresh at start, so all pushes queued behind a chain coalesce into one follow-up compile.
+    if (this.compileRunning) {
+      this.compilePending = { partial, serial: renderSerial };
+      return;
+    }
+    this.compileRunning = true;
+    try {
+      await this.compileOnce(partial, renderSerial);
+    } finally {
+      this.compileRunning = false;
+      const pending = this.compilePending;
+      this.compilePending = null;
+      if (pending) void this.compile(pending.partial, pending.serial);
+    }
+  }
+
+  private async compileOnce(partial: boolean, renderSerial?: number) {
     const serial = (this.compileSerial += 1);
     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) {
-      if (serial !== this.compileSerial) return;
+      // 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).
+      if (serial !== this.compileSerial || this.compilePending) return;
       this.callbacks.onError?.(normalizeError(error), "transform");
       return;
     }
@@ -294,17 +334,26 @@ export class GenUIRenderer {
       this.slot.setCurrent(component);
       this.renderComponent(component, code, renderSerial, result.source);
     } catch (error) {
-      if (serial !== this.compileSerial) return;
+      if (serial !== this.compileSerial || this.compilePending) return;
       this.callbacks.onError?.(normalizeError(error), "compile");
     }
   }
 
-  private async importCompiledComponent(code: string) {
+  private async importCompiledComponent(code: string): Promise<{ component: GeneratedComponent; moduleUrl?: string }> {
     const cached = compiledComponentCache.get(code);
     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?: unknown };
+      let module: { default?: GeneratedComponent };
+      try {
+        module = (await import(/* @vite-ignore */ 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 };
@@ -325,7 +374,7 @@ export class GenUIRenderer {
     this.moduleUrl = null;
   }
 
-  private scheduleRenderedCallback(component: unknown, code: string, renderSerial: number | undefined, compileSerial: number) {
+  private scheduleRenderedCallback(component: GeneratedComponent, code: string, renderSerial: number | undefined, compileSerial: number) {
     const notify = () => {
       if (compileSerial === this.compileSerial) this.callbacks.onRendered?.(component, code, renderSerial);
     };

package/src/state.ts

@@ -2,12 +2,20 @@ import { createElement, type ComponentType, type ReactNode } from "react";
 
 export type GeneratedFunctionComponent = (props: Record<string, unknown>) => ReactNode | Promise<ReactNode>;
 export type GeneratedComponent = ComponentType<Record<string, unknown>> | GeneratedFunctionComponent;
-export type GeneratedComponentSlot = { Component: GeneratedFunctionComponent; current: () => unknown; lastGood: () => unknown; setCurrent: (component: unknown) => void; markRendered: (component?: unknown) => void; restoreLastGood: () => boolean; clear: () => void };
+export type GeneratedComponentSlot = {
+  Component: GeneratedFunctionComponent;
+  current: () => GeneratedComponent | null;
+  lastGood: () => GeneratedComponent | null;
+  setCurrent: (component: GeneratedComponent) => void;
+  markRendered: (component?: GeneratedComponent | null) => void;
+  restoreLastGood: () => boolean;
+  clear: () => void;
+};
 const isClassComponent = (component: unknown) => typeof component === "function" && Boolean((component as { prototype?: { isReactComponent?: unknown } }).prototype?.isReactComponent);
 
 export function createGeneratedComponentSlot(): GeneratedComponentSlot {
-  const currentRef = { current: null as unknown };
-  const lastGoodRef = { current: null as unknown };
+  const currentRef = { current: null as GeneratedComponent | null };
+  const lastGoodRef = { current: null as GeneratedComponent | null };
   const Component = (props: Record<string, unknown>) => {
     const Current = currentRef.current;
     if (!Current) return null;