partial-react 0.0.0 → 0.0.2

package/src/importMap.ts

@@ -0,0 +1,465 @@
+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] ?? "");
+
+const skipLineComment = (code: string, index: number) => {
+  const newlineIndex = code.indexOf("\n", index + 2);
+  return newlineIndex === -1 ? code.length : newlineIndex;
+};
+
+const skipBlockComment = (code: string, index: number) => {
+  const closeIndex = code.indexOf("*/", index + 2);
+  return closeIndex === -1 ? code.length : closeIndex + 2;
+};
+
+const skipWhitespaceAndComments = (code: string, index: number) => {
+  while (index < code.length) {
+    if (/\s/.test(code[index])) {
+      index += 1;
+      continue;
+    }
+    if (code[index] === "/" && code[index + 1] === "/") {
+      index = skipLineComment(code, index);
+      continue;
+    }
+    if (code[index] === "/" && code[index + 1] === "*") {
+      index = skipBlockComment(code, index);
+      continue;
+    }
+    break;
+  }
+  return index;
+};
+
+const readStringLiteral = (code: string, index: number) => {
+  const quote = code[index];
+  if (quote !== '"' && quote !== "'") return null;
+  let value = "";
+  index += 1;
+  while (index < code.length) {
+    const char = code[index];
+    if (char === "\\") {
+      value += code.slice(index, index + 2);
+      index += 2;
+      continue;
+    }
+    if (char === quote) return { value, end: index + 1, terminated: true };
+    value += char;
+    index += 1;
+  }
+  // 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) => {
+  index += 1;
+  while (index < code.length) {
+    if (code[index] === "\\") {
+      index += 2;
+      continue;
+    }
+    if (code[index] === "`") return index + 1;
+    if (code[index] === "$" && code[index + 1] === "{") {
+      const expressionStart = index + 2;
+      const expressionEnd = findBalancedBlockEnd(code, index + 1, "{", "}");
+      onExpression?.(expressionStart, Math.max(expressionStart, expressionEnd - 1));
+      index = expressionEnd;
+      continue;
+    }
+    index += 1;
+  }
+  return code.length;
+};
+
+const findBalancedBlockEnd = (code: string, index: number, opener: string, closer: string) => {
+  let depth = 0;
+  while (index < code.length) {
+    const char = code[index];
+    if (char === "/" && code[index + 1] === "/") {
+      index = skipLineComment(code, index);
+      continue;
+    }
+    if (char === "/" && code[index + 1] === "*") {
+      index = skipBlockComment(code, index);
+      continue;
+    }
+    if (isLikelyRegexLiteralStart(code, index)) {
+      index = skipRegexLiteral(code, index);
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      index = readStringLiteral(code, index)?.end ?? index + 1;
+      continue;
+    }
+    if (char === "`") {
+      index = skipTemplateLiteral(code, index);
+      continue;
+    }
+    if (char === opener) depth += 1;
+    if (char === closer) {
+      depth -= 1;
+      if (depth === 0) return index + 1;
+    }
+    index += 1;
+  }
+  return code.length;
+};
+
+const isLikelyRegexLiteralStart = (code: string, index: number) => {
+  if (code[index] !== "/" || code[index + 1] === "/" || code[index + 1] === "*") return false;
+  let previous = index - 1;
+  while (previous >= 0 && /\s/.test(code[previous])) previous -= 1;
+  if (previous < 0) return true;
+  const previousChar = code[previous];
+  if ("([{=,:;!&|?+-*~^<>".includes(previousChar)) return true;
+  if (!/[A-Za-z_$]/.test(previousChar)) return false;
+  let word = "";
+  for (let cursor = previous; cursor >= 0 && /[A-Za-z0-9_$]/.test(code[cursor]); cursor -= 1) word = code[cursor] + word;
+  return REGEX_PREFIX_WORDS.has(word);
+};
+
+const skipRegexLiteral = (code: string, index: number) => {
+  index += 1;
+  let inClass = false;
+  while (index < code.length) {
+    const char = code[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    index += 1;
+    if (char === "[" && !inClass) inClass = true;
+    else if (char === "]" && inClass) inClass = false;
+    else if (char === "/" && !inClass) {
+      while (index < code.length && /[A-Za-z]/.test(code[index])) index += 1;
+      return index;
+    }
+  }
+  return code.length;
+};
+
+const readFromSpecifier = (code: string, index: number) => {
+  while (index < code.length) {
+    const char = code[index];
+    if (char === ";") return null;
+    if (char === "/" && code[index + 1] === "/") {
+      index = skipLineComment(code, index);
+      continue;
+    }
+    if (char === "/" && code[index + 1] === "*") {
+      index = skipBlockComment(code, index);
+      continue;
+    }
+    if (isLikelyRegexLiteralStart(code, index)) {
+      index = skipRegexLiteral(code, index);
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      index = readStringLiteral(code, index)?.end ?? index + 1;
+      continue;
+    }
+    if (char === "`") {
+      index = skipTemplateLiteral(code, index);
+      continue;
+    }
+    if (isKeywordAt(code, index, "from")) {
+      const literal = readStringLiteral(code, skipWhitespaceAndComments(code, index + "from".length));
+      if (literal) return { specifier: literal.value, end: literal.end, terminated: literal.terminated };
+      index += "from".length;
+      continue;
+    }
+    index += 1;
+  }
+  return null;
+};
+
+const readExportFromSpecifier = (code: string, index: number) => {
+  let next = skipWhitespaceAndComments(code, index);
+  if (isKeywordAt(code, next, "type")) next = skipWhitespaceAndComments(code, next + "type".length);
+  if (code[next] === "*" || code[next] === "{") return readFromSpecifier(code, next);
+  for (const keyword of LOCAL_EXPORT_KEYWORDS) if (isKeywordAt(code, next, keyword)) return null;
+  return readFromSpecifier(code, next);
+};
+
+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] === "/") {
+      index = skipLineComment(code, index);
+      continue;
+    }
+    if (char === "/" && code[index + 1] === "*") {
+      index = skipBlockComment(code, index);
+      continue;
+    }
+    if (isLikelyRegexLiteralStart(code, index)) {
+      index = skipRegexLiteral(code, index);
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      index = readStringLiteral(code, index)?.end ?? index;
+      continue;
+    }
+    if (char === "`") {
+      index = skipTemplateLiteral(code, index, (expressionStart, expressionEnd) => collectModuleSpecifiers(code, specifiers, includeSpecifier, expressionStart, expressionEnd));
+      continue;
+    }
+    if (isKeywordAt(code, index, "import")) {
+      const afterImport = skipWhitespaceAndComments(code, index + "import".length);
+      if (code[afterImport] === ".") {
+        index = afterImport;
+        continue;
+      }
+      if (code[afterImport] === "(") {
+        const literal = readStringLiteral(code, skipWhitespaceAndComments(code, afterImport + 1));
+        if (literal?.terminated && literal.value && includeSpecifier(literal.value)) specifiers.add(literal.value);
+        index = literal?.end ?? afterImport;
+        continue;
+      }
+      const sideEffect = readStringLiteral(code, afterImport);
+      const from = sideEffect ? { specifier: sideEffect.value, end: sideEffect.end, terminated: sideEffect.terminated } : readFromSpecifier(code, afterImport);
+      if (from?.terminated && from.specifier && includeSpecifier(from.specifier)) specifiers.add(from.specifier);
+      index = from?.end ?? afterImport;
+      continue;
+    }
+    if (isKeywordAt(code, index, "export")) {
+      const from = readExportFromSpecifier(code, index + "export".length);
+      if (from?.terminated && from.specifier && includeSpecifier(from.specifier)) specifiers.add(from.specifier);
+      index = from?.end ?? index;
+    }
+  }
+};
+
+export function extractBareModuleSpecifiers(code: string) {
+  const specifiers = new Set<string>();
+  collectModuleSpecifiers(code, specifiers, isBareModuleSpecifier);
+  return specifiers;
+}
+
+export function extractModuleSpecifiers(code: string) {
+  const specifiers = new Set<string>();
+  collectModuleSpecifiers(code, specifiers, () => true);
+  return specifiers;
+}
+
+export function hasImportMapEntry(imports: Record<string, string> | Set<string> | Map<string, string>, specifier: string) {
+  const keys = imports instanceof Set ? imports : imports instanceof Map ? new Set(imports.keys()) : new Set(Object.keys(imports));
+  if (keys.has(specifier)) return true;
+  for (const key of keys) if (key.endsWith("/") && specifier.startsWith(key)) return true;
+  return false;
+}
+
+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("?") ? "&" : "?";
+  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 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> }) {
+  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/renderContext.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext, type Context } from "react";
+
+export type GenUIRenderContextValue = { rendererScope: string; streamingPartialFrame: boolean; nextStreamingRenderKey?: () => string };
+const defaultRendererScope = "default";
+const renderContextValues = new Map<string, { complete: GenUIRenderContextValue; streaming: GenUIRenderContextValue }>();
+const getRenderContextValues = (rendererScope: string) => {
+  const cached = renderContextValues.get(rendererScope);
+  if (cached) return cached;
+  const values = { complete: Object.freeze({ rendererScope, streamingPartialFrame: false }), streaming: Object.freeze({ rendererScope, streamingPartialFrame: true }) };
+  renderContextValues.set(rendererScope, values);
+  return values;
+};
+const completeRenderContextValue = getRenderContextValues(defaultRendererScope).complete;
+
+const renderContextKey = Symbol.for("@macaron/genui-runtime:render-context");
+const globalRenderContext = globalThis as typeof globalThis & { [renderContextKey]?: Context<GenUIRenderContextValue> };
+
+export const getGenUIRenderContextValue = (streamingPartialFrame: boolean, rendererScope = defaultRendererScope, nextStreamingRenderKey?: () => string): GenUIRenderContextValue => {
+  if (nextStreamingRenderKey) return { rendererScope, streamingPartialFrame, nextStreamingRenderKey };
+  const values = getRenderContextValues(rendererScope);
+  return streamingPartialFrame ? values.streaming : values.complete;
+};
+// Production chunks can load separate copies of this module; the global symbol keeps charts and the renderer on one Context.
+export const GenUIRenderContext = (globalRenderContext[renderContextKey] ??= createContext<GenUIRenderContextValue>(completeRenderContextValue));
+export const useGenUIRenderContext = () => useContext(GenUIRenderContext);