partial-react 0.0.1 → 0.0.2

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.2",
   "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.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/compiler.ts

@@ -3,22 +3,23 @@ import tsxWasmUrl from "@esm.sh/tsx/pkg/tsx_bg.wasm?url";
 import { normalizeGeneratedTsx } from "partial-tsx";
 import 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,8 @@ 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 result = transformTsx({ filename: options.filename ?? "_.tsx", code: source, 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,26 @@
-export type RendererImportMap = { imports?: Record<string, string> };
+export type RendererImportMap = { imports?: Record<string, string>; scopes?: Record<string, Record<string, string>>; styles?: string[] };
+
+// 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 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;
+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);
+// 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 +66,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) => {
@@ -172,7 +188,7 @@ const readFromSpecifier = (code: string, index: number) => {
     }
     if (isKeywordAt(code, index, "from")) {
       const literal = readStringLiteral(code, skipWhitespaceAndComments(code, index + "from".length));
-      if (literal) return { specifier: literal.value, end: literal.end };
+      if (literal) return { specifier: literal.value, end: literal.end, terminated: literal.terminated };
       index += "from".length;
       continue;
     }
@@ -189,7 +205,7 @@ const readExportFromSpecifier = (code: string, index: number) => {
   return readFromSpecifier(code, next);
 };
 
-const collectBareModuleSpecifiers = (code: string, specifiers: Set<string>, start = 0, end = code.length) => {
+const collectModuleSpecifiers = (code: string, specifiers: Set<string>, includeSpecifier: (specifier: string) => boolean, start = 0, end = code.length) => {
   for (let index = start; index < end; index += 1) {
     const char = code[index];
     if (char === "/" && code[index + 1] === "/") {
@@ -209,7 +225,7 @@ 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, specifiers, includeSpecifier, expressionStart, expressionEnd));
       continue;
     }
     if (isKeywordAt(code, index, "import")) {
@@ -220,19 +236,19 @@ const collectBareModuleSpecifiers = (code: string, specifiers: Set<string>, star
       }
       if (code[afterImport] === "(") {
         const literal = readStringLiteral(code, skipWhitespaceAndComments(code, afterImport + 1));
-        if (literal?.value && isBareModuleSpecifier(literal.value)) specifiers.add(literal.value);
+        if (literal?.terminated && literal.value && includeSpecifier(literal.value)) specifiers.add(literal.value);
         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 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);
       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 && includeSpecifier(from.specifier)) specifiers.add(from.specifier);
       index = from?.end ?? index;
     }
   }
@@ -240,7 +256,13 @@ const collectBareModuleSpecifiers = (code: string, specifiers: Set<string>, star
 
 export function extractBareModuleSpecifiers(code: string) {
   const specifiers = new Set<string>();
-  collectBareModuleSpecifiers(code, specifiers);
+  collectModuleSpecifiers(code, specifiers, isBareModuleSpecifier);
+  return specifiers;
+}
+
+export function extractModuleSpecifiers(code: string) {
+  const specifiers = new Set<string>();
+  collectModuleSpecifiers(code, specifiers, () => true);
   return specifiers;
 }
 
@@ -251,25 +273,193 @@ export function hasImportMapEntry(imports: Record<string, string> | Set<string>
   return false;
 }
 
-export function toEsmShImportUrl(specifier: string) {
+export function toEsmShImportUrl(specifier: string, external: readonly string[] = DEFAULT_ESM_SH_EXTERNALS) {
   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`;
+  const externalParam = external.length ? `&external=${external.join(",")}` : "";
+  return `https://esm.sh/${versionedSpecifier}${separator}bundle&target=es2022${externalParam}`;
 }
 
+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 {
+        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[]; 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 { 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, ...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;
+  return (await createImportMapResolver([literalImportMap({ imports }), esmShFallback(options)]).resolve({ code })).imports;
 }

package/src/remoteModule.ts

@@ -0,0 +1,120 @@
+import { createTsxCompiler, type TsxCompiler } from "./compiler";
+import { esmShFallback, extractModuleSpecifiers, isBareModuleSpecifier, isRuntimeSingletonSpecifier, type ImportMapProvider, type RendererImportMap } from "./importMap";
+
+// 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). 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 {
+  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();
+
+  // 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;
+  };
+
+  // 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>> => {
+    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 (!isRuntimeSingletonSpecifier(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).then((blob) => [absolute, blob] as const))), esmSh.resolve({ code, missing: bareMissing })]);
+    return { ...bare.imports, ...Object.fromEntries(remote) };
+  };
+
+  const resolveModule = (url: string): Promise<string> => {
+    let blob = blobByUrl.get(url);
+    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);
+        // 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(url);
+        importsOf.delete(url);
+      });
+      blobByUrl.set(url, 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 }): Promise<RendererImportMap> => {
+      const entries = await Promise.all([...extractModuleSpecifiers(code)].flatMap((specifier) => (isRemoteSourceModuleSpecifier(specifier) ? [resolveModule(specifier).then((blob) => [specifier, blob] as const)] : [])));
+      return { imports: Object.fromEntries(entries) };
+    },
+  };
+}

package/src/{runtime.tsx → runtime.ts}

@@ -1,14 +1,15 @@
 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 { 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 };
@@ -20,9 +21,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) {
@@ -71,6 +72,8 @@ 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;
@@ -124,7 +127,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 +226,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 +265,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 });
     } 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 +323,17 @@ 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 };
+      const module = (await import(/* @vite-ignore */ moduleUrl)) as { default?: GeneratedComponent };
       if (!module.default) throw new Error("No default export found in compiled module.");
       rememberCompiledComponent(code, module.default);
       return { component: module.default, moduleUrl };
@@ -325,7 +354,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;