partial-react 0.0.0 → 0.0.1

package/package.json

@@ -1,11 +1,30 @@
 {
   "name": "partial-react",
-  "version": "0.0.0",
-  "description": "Placeholder for partial-react",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": [],
-  "author": "muspi-merol (https://www.npmjs.com/~muspi-merol)",
-  "license": "UNLICENSED",
-  "private": false
-}
+  "description": "A state-preserving renderer for prefix-growing streaming React/TSX.",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MindLab-Research/macaron-genui-demo",
+    "directory": "lib/partial-react"
+  },
+  "exports": {
+    ".": "./src/runtime.tsx",
+    "./compiler": "./src/compiler.ts",
+    "./import-map": "./src/importMap.ts",
+    "./render-context": "./src/renderContext.ts"
+  },
+  "files": [
+    "src/**/*",
+    "!src/**/*.test.*"
+  ],
+  "dependencies": {
+    "@esm.sh/tsx": "^1.5.0",
+    "partial-tsx": "0.0.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "sideEffects": false
+}

package/src/compiler.ts

@@ -0,0 +1,39 @@
+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";
+
+export type CompileOptions = { importMap?: RendererImportMap; partial?: boolean; previousCode?: string; filename?: string; 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();
+};
+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.
+    }
+    return initTsx(tsxWasmUrl);
+  })().catch((error) => {
+    initPromise = null;
+    throw error;
+  }));
+
+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 compiled = new TextDecoder().decode(result.code);
+      return { code: compiled, source, changed: compiled !== options.previousCode };
+    },
+  };
+}

package/src/hookSignature.ts

@@ -0,0 +1,247 @@
+// A tiny hand-rolled TSX lexer that extracts the ordered list of React hook calls from generated source. The renderer compares
+// successive signatures: same layout keeps preserved state, a changed layout remounts the stable boundary so React reassigns hook cells.
+const identifierPartPattern = /[\w$]/;
+const hookCallPattern = /use[A-Z][\w$]*/y;
+const regexPrefixKeywords = new Set(["return", "throw", "case", "delete", "void", "typeof", "yield", "await", "in", "of"]);
+const jsxPrefixKeywords = new Set(["return", "throw", "case", "yield", "await"]);
+const skipQuotedString = (code: string, index: number) => {
+  const quote = code[index];
+  index += 1;
+  while (index < code.length) {
+    if (code[index] === "\\") index += 2;
+    else if (code[index] === quote) return index + 1;
+    else index += 1;
+  }
+  return code.length;
+};
+const skipLineComment = (code: string, index: number) => {
+  const end = code.indexOf("\n", index + 2);
+  return end === -1 ? code.length : end;
+};
+const skipBlockComment = (code: string, index: number) => {
+  const end = code.indexOf("*/", index + 2);
+  return end === -1 ? code.length : end + 2;
+};
+const isRegexLiteralStart = (code: string, index: number) => {
+  const previous = previousNonSpaceIndex(code, index);
+  if (previous < 0) return true;
+  if ("([{=,:;!&|?+-*~^<>".includes(code[previous])) return true;
+  if (!identifierPartPattern.test(code[previous])) return false;
+  let word = "";
+  for (let cursor = previous; cursor >= 0 && identifierPartPattern.test(code[cursor]); cursor -= 1) word = code[cursor] + word;
+  return regexPrefixKeywords.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;
+    else if (char === "[") {
+      inClass = true;
+      index += 1;
+    } else if (char === "]") {
+      inClass = false;
+      index += 1;
+    } else if (char === "/" && !inClass) {
+      index += 1;
+      while (/[A-Za-z]/.test(code[index] ?? "")) index += 1;
+      return index;
+    } else index += 1;
+  }
+  return code.length;
+};
+type HookSignatureContext = { localHookNames: Set<string>; reactNamespaces: Set<string> };
+const previousNonSpaceIndex = (code: string, index: number) => {
+  let previous = index - 1;
+  while (previous >= 0 && /\s/.test(code[previous])) previous -= 1;
+  return previous;
+};
+const readIdentifierEndingBefore = (code: string, index: number) => {
+  let end = index;
+  while (end > 0 && /\s/.test(code[end - 1] ?? "")) end -= 1;
+  let start = end;
+  while (start > 0 && identifierPartPattern.test(code[start - 1] ?? "")) start -= 1;
+  return start === end ? null : { name: code.slice(start, end), start };
+};
+const readMemberNamespaceBefore = (code: string, index: number) => {
+  const dot = previousNonSpaceIndex(code, index);
+  if (dot < 0 || code[dot] !== ".") return null;
+  const namespace = readIdentifierEndingBefore(code, code[dot - 1] === "?" ? dot - 1 : dot);
+  if (!namespace) return "";
+  const previous = previousNonSpaceIndex(code, namespace.start);
+  if (previous >= 0 && (identifierPartPattern.test(code[previous]) || ".)]}".includes(code[previous]))) return "";
+  return namespace.name;
+};
+const skipHookTypeArguments = (code: string, index: number) => {
+  if (code[index] !== "<") return index;
+  let depth = 0;
+  while (index < code.length) {
+    const char = code[index];
+    if (char === '"' || char === "'") index = skipQuotedString(code, index);
+    else if (char === "/" && code[index + 1] === "/") index = skipLineComment(code, index);
+    else if (char === "/" && code[index + 1] === "*") index = skipBlockComment(code, index);
+    else if (char === "<") {
+      depth += 1;
+      index += 1;
+    } else if (char === ">" && code[index - 1] === "=") index += 1;
+    else if (char === ">") {
+      depth -= 1;
+      index += 1;
+      if (depth === 0) return index;
+    } else index += 1;
+  }
+  return -1;
+};
+const isFunctionDeclarationName = (code: string, index: number) => /\bfunction\s*\*?\s*$/.test(code.slice(0, index).trimEnd());
+const collectReactHookNamespaces = (code: string) => {
+  const namespaces = new Set(["React", "react"]);
+  for (const match of code.matchAll(/(?:^|[;\n])\s*import\s+((?:(?![;\n]\s*import\b)[\s\S])*?)\s+from\s+["']react["']/g)) {
+    const clause = match[1].trim();
+    if (/^type\b/.test(clause)) continue;
+    if (!clause.startsWith("{") && !clause.startsWith("*")) {
+      const defaultMatch = /^([A-Za-z_$][\w$]*)/.exec(clause);
+      if (defaultMatch) namespaces.add(defaultMatch[1]);
+    }
+    const namespaceMatch = /\*\s+as\s+([A-Za-z_$][\w$]*)/.exec(clause);
+    if (namespaceMatch) namespaces.add(namespaceMatch[1]);
+  }
+  return namespaces;
+};
+const collectLocalHookNames = (code: string) => {
+  const names = new Set<string>();
+  for (const match of code.matchAll(/\bfunction\s*\*?\s+(use[A-Z][\w$]*)\s*\(/g)) names.add(match[1]);
+  for (const match of code.matchAll(/\b(?:const|let|var)\s+(use[A-Z][\w$]*)\s*=/g)) names.add(match[1]);
+  return names;
+};
+const readHookCall = (code: string, index: number, context: HookSignatureContext) => {
+  hookCallPattern.lastIndex = index;
+  const match = hookCallPattern.exec(code);
+  if (!match || match.index !== index) return null;
+  const hookName = match[0];
+  const namespace = readMemberNamespaceBefore(code, index);
+  if (namespace !== null) {
+    if (!context.reactNamespaces.has(namespace)) return null;
+  } else {
+    if (identifierPartPattern.test(code[index - 1] ?? "")) return null;
+    if (isFunctionDeclarationName(code, index)) return null;
+  }
+  let end = index + hookName.length;
+  while (/\s/.test(code[end] ?? "")) end += 1;
+  if (code[end] === "<") {
+    end = skipHookTypeArguments(code, end);
+    if (end === -1) return null;
+    while (/\s/.test(code[end] ?? "")) end += 1;
+  }
+  if (code[end] !== "(") return null;
+  return { name: context.localHookNames.has(hookName) ? "useCustomHook" : hookName, end: end + 1 };
+};
+const shouldStartJsxTag = (code: string, index: number) => {
+  if (!/[A-Za-z>]/.test(code[index + 1] ?? "")) return false;
+  const previous = previousNonSpaceIndex(code, index);
+  if (previous < 0 || "([{=,:;!?&|+-*~^<>".includes(code[previous])) return true;
+  if (!identifierPartPattern.test(code[previous])) return false;
+  let word = "";
+  for (let cursor = previous; cursor >= 0 && identifierPartPattern.test(code[cursor]); cursor -= 1) word = code[cursor] + word;
+  return jsxPrefixKeywords.has(word);
+};
+const scanHookSignatureJs = (code: string, hooks: string[], context: HookSignatureContext, start = 0, end = code.length): number => {
+  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);
+    else if (char === '"' || char === "'") index = skipQuotedString(code, index);
+    else if (char === "`") index = scanHookSignatureTemplate(code, hooks, context, index);
+    else if (char === "/" && isRegexLiteralStart(code, index)) index = skipRegexLiteral(code, index);
+    else if (char === "<" && shouldStartJsxTag(code, index)) index = scanHookSignatureJsx(code, hooks, context, index);
+    else {
+      const hook = readHookCall(code, index, context);
+      if (hook) {
+        hooks.push(hook.name);
+        index = hook.end;
+      } else index += 1;
+    }
+  }
+  return end;
+};
+const scanHookSignatureTemplate = (code: string, hooks: string[], context: HookSignatureContext, index: number) => {
+  index += 1;
+  while (index < code.length) {
+    if (code[index] === "\\") index += 2;
+    else if (code[index] === "`") return index + 1;
+    else if (code[index] === "$" && code[index + 1] === "{") index = scanHookSignatureBraces(code, hooks, context, index + 1);
+    else index += 1;
+  }
+  return code.length;
+};
+const scanHookSignatureBraces = (code: string, hooks: string[], context: HookSignatureContext, index: number) => {
+  let depth = 1;
+  index += 1;
+  while (index < code.length) {
+    const char = code[index];
+    if (char === "/" && code[index + 1] === "/") index = skipLineComment(code, index);
+    else if (char === "/" && code[index + 1] === "*") index = skipBlockComment(code, index);
+    else if (char === '"' || char === "'") index = skipQuotedString(code, index);
+    else if (char === "`") index = scanHookSignatureTemplate(code, hooks, context, index);
+    else if (char === "/" && isRegexLiteralStart(code, index)) index = skipRegexLiteral(code, index);
+    else if (char === "<" && shouldStartJsxTag(code, index)) index = scanHookSignatureJsx(code, hooks, context, index);
+    else if (char === "{") {
+      depth += 1;
+      index += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      index += 1;
+      if (depth === 0) return index;
+    } else {
+      const hook = readHookCall(code, index, context);
+      if (hook) {
+        hooks.push(hook.name);
+        index = hook.end;
+      } else index += 1;
+    }
+  }
+  return code.length;
+};
+const scanJsxOpeningTag = (code: string, hooks: string[], context: HookSignatureContext, index: number) => {
+  while (index < code.length) {
+    const char = code[index];
+    if (char === "`") index = scanHookSignatureTemplate(code, hooks, context, index);
+    else if (char === '"' || char === "'") index = skipQuotedString(code, index);
+    else if (char === "{") index = scanHookSignatureBraces(code, hooks, context, index);
+    else if (char === ">") {
+      const previous = previousNonSpaceIndex(code, index);
+      return { index: index + 1, selfClosing: code[previous] === "/" };
+    } else index += 1;
+  }
+  return { index: code.length, selfClosing: true };
+};
+const scanHookSignatureJsx = (code: string, hooks: string[], context: HookSignatureContext, index: number): number => {
+  let depth = 0;
+  while (index < code.length) {
+    if (code.startsWith("</>", index)) {
+      index += 3;
+      depth -= 1;
+      if (depth <= 0) return index;
+    } else if (code.startsWith("</", index)) {
+      const close = code.indexOf(">", index + 2);
+      index = close === -1 ? code.length : close + 1;
+      depth -= 1;
+      if (depth <= 0) return index;
+    } else if (code.startsWith("<>", index)) {
+      depth += 1;
+      index += 2;
+    } else if (code[index] === "<" && /[A-Za-z]/.test(code[index + 1] ?? "")) {
+      const opened = scanJsxOpeningTag(code, hooks, context, index + 1);
+      index = opened.index;
+      if (!opened.selfClosing) depth += 1;
+      else if (depth <= 0) return index;
+    } else if (code[index] === "{") index = scanHookSignatureBraces(code, hooks, context, index);
+    else index += 1;
+  }
+  return code.length;
+};
+export const getGenUIHookSignature = (code: string) => {
+  const hooks: string[] = [];
+  scanHookSignatureJs(code, hooks, { localHookNames: collectLocalHookNames(code), reactNamespaces: collectReactHookNamespaces(code) });
+  return hooks.join("\n");
+};

package/src/importMap.ts

@@ -0,0 +1,275 @@
+export type RendererImportMap = { imports?: Record<string, string> };
+
+const ESM_SH_VERSION_OVERRIDES = { "@number-flow/react": "0.6.0" } as const;
+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);
+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 };
+    value += char;
+    index += 1;
+  }
+  return { value, end: code.length };
+};
+
+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 };
+      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 collectBareModuleSpecifiers = (code: string, specifiers: Set<string>, 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) => collectBareModuleSpecifiers(code, specifiers, 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?.value && isBareModuleSpecifier(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);
+      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);
+      index = from?.end ?? index;
+    }
+  }
+};
+
+export function extractBareModuleSpecifiers(code: string) {
+  const specifiers = new Set<string>();
+  collectBareModuleSpecifiers(code, specifiers);
+  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) {
+  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`;
+}
+
+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 };
+}
+
+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;
+}

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);

package/src/runtime.tsx

@@ -0,0 +1,389 @@
+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 { 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 GenUIRendererClearOptions = { preserveVisualState?: boolean };
+export type GenUIRendererFlushMode = "microtask" | "immediate";
+export type GenUIRendererOptions = { importmap?: RendererImportMap; callbacks?: GenUIRendererCallbacks; compiler?: TsxCompiler; preserveStateOnUpdate?: boolean; flushMode?: GenUIRendererFlushMode };
+export type GenUIRendererUpdateMode = "push" | "render";
+
+const attachedRenderer = Symbol.for("@macaron/genui-runtime:attached-renderer");
+type AttachableHost = HTMLElement & { [attachedRenderer]?: GenUIRenderer };
+const normalizeError = (error: unknown) => (error instanceof Error ? error : new Error(String(error)));
+const COMPILED_COMPONENT_CACHE_LIMIT = 256;
+let rendererScopeSerial = 0;
+const createRendererScope = () => `renderer:${(rendererScopeSerial += 1).toString(36)}`;
+const compiledComponentCache = new Map<string, unknown>();
+const getPreserveBoundaryKey = (epoch: number) => (epoch === 0 ? "boundary" : `boundary:${epoch}`);
+const rememberCompiledComponent = (code: string, component: unknown) => {
+  if (compiledComponentCache.has(code)) compiledComponentCache.delete(code);
+  compiledComponentCache.set(code, component);
+  if (compiledComponentCache.size > COMPILED_COMPONENT_CACHE_LIMIT) {
+    const oldestKey = compiledComponentCache.keys().next().value;
+    if (oldestKey !== undefined) compiledComponentCache.delete(oldestKey);
+  }
+};
+
+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 };
+  }
+  static getDerivedStateFromProps(props: { resetKey?: number }, state: { hasError: boolean; lastResetKey?: number }) {
+    // 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 };
+    return null;
+  }
+  componentDidCatch(error: Error) {
+    this.props.onError?.(error);
+  }
+  render() {
+    if (this.state.hasError) return "ERROR";
+    return this.props.children;
+  }
+}
+
+const RenderNotify = ({ onCommit, onReady }: { onCommit?: () => void; onReady?: () => void }) => {
+  useEffect(() => {
+    onCommit?.();
+    if (typeof document !== "undefined" && document.hidden) {
+      onReady?.();
+      return;
+    }
+    const frameId = requestAnimationFrame(() => onReady?.());
+    return () => cancelAnimationFrame(frameId);
+  }, [onCommit, onReady]);
+  return null;
+};
+
+export class GenUIRenderer {
+  private callbacks: GenUIRendererCallbacks;
+  private compiler: TsxCompiler;
+  private compileSerial = 0;
+  private currentBuffer = "";
+  private compileScheduled = false;
+  private compileScheduleToken = 0;
+  private scheduledPartial = false;
+  private scheduledSerial?: number;
+  private errorEpoch = 0;
+  private finished = false;
+  private flushMode: GenUIRendererFlushMode;
+  private importmap?: RendererImportMap;
+  private lastCompiledCode = "";
+  private lastGoodHookSignature = "";
+  private lastHookSignature: string | null = null;
+  private moduleUrl: string | null = null;
+  private preserveBoundaryEpoch = 0;
+  private preserveStateOnUpdate: boolean;
+  private renderRound = 0;
+  private rendererScope: string;
+  private root: Root | null = null;
+  private slot: GeneratedComponentSlot;
+  private target: HTMLElement | null = null;
+  private updateMode: GenUIRendererUpdateMode = "render";
+
+  private constructor(target: HTMLElement | null | undefined, options: GenUIRendererOptions) {
+    this.callbacks = options.callbacks ?? {};
+    this.compiler = options.compiler ?? createTsxCompiler();
+    this.flushMode = options.flushMode ?? "microtask";
+    this.importmap = options.importmap;
+    this.preserveStateOnUpdate = options.preserveStateOnUpdate ?? true;
+    this.rendererScope = createRendererScope();
+    this.slot = createGeneratedComponentSlot();
+    if (target) this.attach(target);
+  }
+
+  static async create(target?: HTMLElement | null, options: GenUIRendererOptions = {}) {
+    return new GenUIRenderer(target, options);
+  }
+
+  attach(target: HTMLElement) {
+    const element = target as AttachableHost;
+    if (element[attachedRenderer] && element[attachedRenderer] !== this) element[attachedRenderer].detach();
+    if (this.target === target && this.root) {
+      element[attachedRenderer] = this;
+      return this;
+    }
+    const previous = this.target as AttachableHost | null;
+    if (previous && previous[attachedRenderer] === this) delete previous[attachedRenderer];
+    this.root?.unmount();
+    this.target = target;
+    this.root = createRoot(target);
+    element[attachedRenderer] = this;
+    this.renderComponent();
+    return this;
+  }
+
+  detach() {
+    // Bump compileSerial so any in-flight compile resolves into a no-op instead of adopting onto a dead renderer.
+    this.compileSerial += 1;
+    const previous = this.target as AttachableHost | null;
+    if (previous && previous[attachedRenderer] === this) delete previous[attachedRenderer];
+    this.root?.unmount();
+    this.root = null;
+    this.target = null;
+    this.rendererScope = createRendererScope();
+    this.revokeModuleUrl();
+    return this;
+  }
+
+  setPreserveStateOnUpdate(value: boolean) {
+    this.preserveStateOnUpdate = value;
+    return this;
+  }
+
+  setFlushMode(value: GenUIRendererFlushMode) {
+    this.flushMode = value;
+    return this;
+  }
+
+  setImportMap(importmap: RendererImportMap) {
+    this.importmap = importmap;
+    return this;
+  }
+
+  render(code: string, serial?: number) {
+    this.finished = true;
+    this.currentBuffer = code;
+    this.updateMode = "render";
+    this.scheduleCompile(false, serial);
+  }
+
+  pushCode(code: string, serial?: number) {
+    this.finished = false;
+    this.currentBuffer += code;
+    this.updateMode = "push";
+    this.scheduleCompile(true, serial);
+  }
+
+  finish(code?: string, serial?: number) {
+    this.finished = true;
+    if (code !== undefined) this.currentBuffer = code;
+    this.scheduleCompile(false, serial);
+  }
+
+  getCurrentBuffer() {
+    return this.currentBuffer;
+  }
+
+  getUpdateMode() {
+    return this.updateMode;
+  }
+
+  restoreLastGood() {
+    if (!this.slot.restoreLastGood()) return false;
+    this.errorEpoch += 1;
+    this.renderComponent(this.slot.current(), this.currentBuffer, undefined, this.currentBuffer, this.lastGoodHookSignature);
+    return true;
+  }
+
+  private buildStreamingRenderContext(streamingPartialFrame: boolean) {
+    let streamingRenderKeyIndex = 0;
+    return getGenUIRenderContextValue(streamingPartialFrame, this.rendererScope, () => `chart-${streamingRenderKeyIndex++}`);
+  }
+
+  private canRenderComponent(component: unknown, streamingPartialFrame: boolean) {
+    const renderContext = this.buildStreamingRenderContext(streamingPartialFrame);
+    const previousConsoleError = console.error;
+    let firstConsoleError: string | undefined;
+    let caughtError: unknown;
+    try {
+      // Preflight intentionally renders bad partial frames; keep React's development console noise off the debug page.
+      console.error = (...args) => {
+        firstConsoleError ??= args.map(String).join(" ");
+      };
+      renderToString(createElement(GenUIRenderContext.Provider, { value: renderContext }, createElement(component as ComponentType<Record<string, unknown>>)));
+    } catch (error) {
+      caughtError = error;
+    } finally {
+      console.error = previousConsoleError;
+    }
+    if (caughtError === undefined && firstConsoleError !== undefined) caughtError = new Error(firstConsoleError);
+    if (caughtError === undefined) return true;
+    this.callbacks.onError?.(normalizeError(caughtError), "render");
+    return false;
+  }
+
+  clear(options: GenUIRendererClearOptions = {}) {
+    this.compileSerial += 1;
+    this.currentBuffer = "";
+    // `clear` terminates the current stream; the next `pushCode`/`render` selects partial vs full mode again.
+    this.finished = true;
+    this.compileScheduled = false;
+    this.scheduledPartial = false;
+    this.scheduledSerial = undefined;
+    this.compileScheduleToken += 1;
+    this.lastCompiledCode = "";
+    if (options.preserveVisualState) return this;
+    this.lastGoodHookSignature = "";
+    this.lastHookSignature = null;
+    this.preserveBoundaryEpoch = 0;
+    this.rendererScope = createRendererScope();
+    this.slot.clear();
+    this.revokeModuleUrl();
+    this.root?.render(null);
+    return this;
+  }
+
+  private scheduleCompile(partial: boolean, serial?: number) {
+    if (this.flushMode === "immediate") {
+      this.compileScheduled = false;
+      this.scheduledPartial = false;
+      this.scheduledSerial = undefined;
+      this.compileScheduleToken += 1;
+      void this.compile(partial, serial);
+      return;
+    }
+    this.scheduledPartial = partial;
+    this.scheduledSerial = serial;
+    if (this.compileScheduled) return;
+    this.compileScheduled = true;
+    const scheduleToken = (this.compileScheduleToken += 1);
+    queueMicrotask(() => {
+      if (scheduleToken !== this.compileScheduleToken) return;
+      const nextPartial = this.scheduledPartial;
+      const nextSerial = this.scheduledSerial;
+      this.compileScheduled = false;
+      this.scheduledPartial = false;
+      this.scheduledSerial = undefined;
+      void this.compile(nextPartial, nextSerial);
+    });
+  }
+
+  private async compile(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;
+      this.callbacks.onError?.(normalizeError(error), "transform");
+      return;
+    }
+    if (serial !== this.compileSerial) return;
+    if (!result.changed) {
+      const component = this.slot.current();
+      // The final full compile can equal the last partial frame; re-render once with finished=true so the chart render
+      // context settles from streaming to complete (charts key off streamingPartialFrame and would otherwise stay streaming).
+      if (component && this.preserveStateOnUpdate && this.updateMode === "push" && this.finished) {
+        this.renderComponent(component, code, renderSerial, result.source);
+        return;
+      }
+      if (component) this.scheduleRenderedCallback(component, code, renderSerial, serial);
+      return;
+    }
+    try {
+      const { component, moduleUrl } = await this.importCompiledComponent(result.code);
+      if (serial !== this.compileSerial) {
+        if (moduleUrl) URL.revokeObjectURL(moduleUrl);
+        return;
+      }
+      this.lastCompiledCode = result.code;
+      if (moduleUrl) this.adoptModuleUrl(moduleUrl);
+      else this.revokeModuleUrl();
+      this.callbacks.onReady?.(component, moduleUrl, code);
+      this.slot.setCurrent(component);
+      this.renderComponent(component, code, renderSerial, result.source);
+    } catch (error) {
+      if (serial !== this.compileSerial) return;
+      this.callbacks.onError?.(normalizeError(error), "compile");
+    }
+  }
+
+  private async importCompiledComponent(code: 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 };
+      if (!module.default) throw new Error("No default export found in compiled module.");
+      rememberCompiledComponent(code, module.default);
+      return { component: module.default, moduleUrl };
+    } catch (error) {
+      URL.revokeObjectURL(moduleUrl);
+      throw error;
+    }
+  }
+
+  private adoptModuleUrl(moduleUrl: string) {
+    if (this.moduleUrl && this.moduleUrl !== moduleUrl) URL.revokeObjectURL(this.moduleUrl);
+    this.moduleUrl = moduleUrl;
+  }
+
+  private revokeModuleUrl() {
+    if (!this.moduleUrl) return;
+    URL.revokeObjectURL(this.moduleUrl);
+    this.moduleUrl = null;
+  }
+
+  private scheduleRenderedCallback(component: unknown, code: string, renderSerial: number | undefined, compileSerial: number) {
+    const notify = () => {
+      if (compileSerial === this.compileSerial) this.callbacks.onRendered?.(component, code, renderSerial);
+    };
+    if (typeof document !== "undefined" && document.hidden) {
+      notify();
+      return;
+    }
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(notify);
+    else queueMicrotask(notify);
+  }
+
+  private renderComponent(component = this.slot.current(), renderedCode = this.currentBuffer, renderSerial?: number, sourceCode = renderedCode, hookSignature = getGenUIHookSignature(sourceCode)) {
+    if (!this.root || !component) return;
+    this.renderRound += 1;
+    const renderedComponent = component;
+    // streamingPartialFrame only drives the chart render context below (chart keys remount per partial frame). Preserve
+    // stays on throughout streaming: each partial frame can have a different hook count, so the hook-signature diff in
+    // the preserve branch remounts the stable wrapper whenever the layout changes, which is what would otherwise reuse
+    // the wrong hook cells and violate the Rules of Hooks (React #310).
+    const streamingPartialFrame = this.updateMode === "push" && !this.finished;
+    const preserve = this.preserveStateOnUpdate;
+    const renderedHookSignature = hookSignature;
+    const lastGood = this.slot.lastGood();
+    if (preserve && streamingPartialFrame && lastGood && lastGood !== renderedComponent && !this.canRenderComponent(renderedComponent, streamingPartialFrame)) {
+      this.slot.restoreLastGood();
+      return;
+    }
+    if (preserve) {
+      // Preserving state across hook layout changes reuses the wrong hook cells; remount only that stable wrapper epoch.
+      // lastHookSignature is null only before the first committed frame; "" is a real hookless signature, so a hookless→hooked
+      // transition (the common JSX-first-then-useState stream shape) must still bump the epoch and remount (React #310).
+      if (this.lastHookSignature !== null && this.lastHookSignature !== renderedHookSignature) this.preserveBoundaryEpoch += 1;
+      this.lastHookSignature = renderedHookSignature;
+    }
+    const renderContext = this.buildStreamingRenderContext(streamingPartialFrame);
+    const onRenderError = (error: Error) => {
+      this.callbacks.onError?.(error, "render");
+      if (!preserve) return;
+      if (this.slot.lastGood() === renderedComponent || !this.restoreLastGood()) this.errorEpoch += 1;
+    };
+    this.root.render(
+      createElement(
+        RuntimeErrorBoundary,
+        { key: preserve ? getPreserveBoundaryKey(this.preserveBoundaryEpoch) : `boundary:${this.renderRound}`, resetKey: this.errorEpoch, onError: onRenderError },
+        createElement(GenUIRenderContext.Provider, { value: renderContext }, createElement(preserve ? this.slot.Component : (renderedComponent as ComponentType<Record<string, unknown>>), { key: "generated-component" })),
+        createElement(RenderNotify, {
+          key: `render-notify:${this.renderRound}`,
+          onCommit: () => {
+            if (this.slot.current() === renderedComponent) {
+              this.slot.markRendered(renderedComponent);
+              if (preserve) this.lastGoodHookSignature = renderedHookSignature;
+            }
+          },
+          onReady: () => {
+            this.callbacks.onRendered?.(renderedComponent, renderedCode, renderSerial);
+          },
+        }),
+      ),
+    );
+  }
+}

package/src/state.ts

@@ -0,0 +1,38 @@
+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 };
+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 Component = (props: Record<string, unknown>) => {
+    const Current = currentRef.current;
+    if (!Current) return null;
+    // Function components are invoked inside this stable wrapper so React keeps their hooks on the wrapper fiber.
+    if (typeof Current === "function" && !isClassComponent(Current)) return (Current as (props: Record<string, unknown>) => ReactNode | Promise<ReactNode>)(props);
+    return createElement(Current as never, props);
+  };
+  return {
+    Component,
+    current: () => currentRef.current,
+    lastGood: () => lastGoodRef.current,
+    setCurrent(component) {
+      currentRef.current = component;
+    },
+    markRendered(component = currentRef.current) {
+      if (component) lastGoodRef.current = component;
+    },
+    restoreLastGood() {
+      if (!lastGoodRef.current) return false;
+      currentRef.current = lastGoodRef.current;
+      return true;
+    },
+    clear() {
+      currentRef.current = null;
+      lastGoodRef.current = null;
+    },
+  };
+}

package/index.js

@@ -1 +0,0 @@
-// Placeholder