partial-react 0.0.7 → 0.0.9

package/README.md

@@ -52,6 +52,7 @@ Turbopack builds also need [#1690](https://github.com/MindLab-Research/macaron-g
 ## Corner Cases
 
 - `render(code)` replaces the current buffer with a complete TSX module.
+- While using `pushCode`, the last inferred entry that committed non-empty React output stays selected while a later component is still unclosed, so a half-streamed helper cannot blank the preview. Once that component closes, the last declared one takes over as usual. Explicit default exports always take precedence, empty output never becomes the displayed entry, and any `clear()` or source replacement resets it. Entry state belongs to the renderer, so a compiler can still be shared between previews.
 - `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.

package/package.json

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

package/src/compiler.ts

@@ -1,9 +1,9 @@
 import initTsx, { transform as transformTsx } from "@esm.sh/tsx";
-import { normalizeGeneratedTsx } from "partial-tsx";
+import { normalizeGeneratedTsxWithMetadata } from "partial-tsx";
 import { rewriteImportMetaResolveSpecifiers, type RendererImportMap } from "./importMap";
 
-export type CompileOptions = { importMap?: RendererImportMap; partial?: boolean; previousCode?: string; filename?: string; lang?: "ts" | "tsx" | "js" | "jsx"; jsxImportSource?: string };
-export type CompileResult = { code: string; source: string; changed: boolean };
+export type CompileOptions = { importMap?: RendererImportMap; partial?: boolean; previousCode?: string; filename?: string; lang?: "ts" | "tsx" | "js" | "jsx"; jsxImportSource?: string; synthesizeDefaultExport?: boolean; preferredComponent?: string };
+export type CompileResult = { code: string; source: string; changed: boolean; inferredComponent?: string };
 export type TsxCompiler = { compile: (code: string, options?: CompileOptions) => Promise<CompileResult> };
 
 let initPromise: Promise<unknown> | null = null;
@@ -25,11 +25,11 @@ export function createTsxCompiler(): TsxCompiler {
   return {
     async compile(code, options = {}) {
       await initCompiler();
-      const source = options.partial ? normalizeGeneratedTsx(code, { mode: "streaming" }) : code;
+      const { source, inferredComponent } = options.partial ? normalizeGeneratedTsxWithMetadata(code, { mode: "streaming", synthesizeDefaultExport: options.synthesizeDefaultExport, preferredComponent: options.preferredComponent }) : { source: code };
       const resolvedSource = options.importMap?.imports ? rewriteImportMetaResolveSpecifiers(source, options.importMap.imports) : source;
       const result = transformTsx({ filename: options.filename ?? "_.tsx", code: resolvedSource, lang: options.lang, target: "es2022", importMap: options.importMap, jsxImportSource: options.jsxImportSource ?? "react" });
       const compiled = new TextDecoder().decode(result.code);
-      return { code: compiled, source, changed: compiled !== options.previousCode };
+      return { code: compiled, source, changed: compiled !== options.previousCode, inferredComponent };
     },
   };
 }

package/src/importMap.ts

@@ -838,33 +838,39 @@ export function toEsmShImportUrl(specifier: string, external: readonly string[]
 }
 
 type EsmShPreloadFetch = (url: string) => Promise<Pick<Response, "ok" | "status">>;
-type EsmShPreloadOptions = { fetch?: EsmShPreloadFetch; attempts?: number; retryDelayMs?: number };
+type EsmShPreloadOptions = { fetch?: EsmShPreloadFetch; attempts?: number };
 const esmShPreloadCache = new Map<string, Promise<void>>();
 
 // A browser module loader memoizes a rejected URL for the page lifetime, so retrying the generated blob cannot recover
 // from a transient esm.sh cold-build failure. Warm the entry URL with ordinary fetch first — a version range still
-// leaves it a mutable entry esm.sh has to resolve and build, not a pinned artifact. Failures remain retryable, while a
-// 2xx means esm.sh has finished resolving/building before import() sees the URL.
+// leaves it a mutable entry esm.sh has to resolve and build, not a pinned artifact. A 2xx means esm.sh has finished
+// resolving/building before import() sees the URL; transient failures get bounded response-driven attempts below.
 export function preloadEsmShImportUrl(url: string, options?: EsmShPreloadOptions): Promise<void> {
   let preload = esmShPreloadCache.get(url);
   if (!preload) {
     const fetcher = options?.fetch ?? fetch;
-    // 3 attempts at 250ms exponential backoff spans ~750ms of retrying, which covers a typical esm.sh cold build
-    // without stalling first paint. There is no ack to wait on — esm.sh answers 5xx while the build is still running.
+    // Three total attempts cover the initial request plus two response-driven retries, each sent only after the
+    // previous fetch settles. Answers that stop early are evicted below, so an independent preload caller can start a
+    // fresh request instead of this one sending an immediate retry burst.
     const attempts = options?.attempts ?? 3;
-    const retryDelayMs = options?.retryDelayMs ?? 250;
     preload = (async () => {
       let lastFailure: unknown;
+      let retriedColdBuild = false;
       for (let attempt = 0; attempt < attempts; attempt += 1) {
-        if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, retryDelayMs * 2 ** (attempt - 1)));
         try {
           const response = await fetcher(url);
           if (response.ok) return;
           lastFailure = new Error(`HTTP ${response.status}`);
-          // esm.sh answers 5xx while a cold build is still running, and 429 when npm rate-limits it — both transient,
-          // same classification the probes below use. Any other 4xx is a decided answer (unknown package, rejected
-          // specifier); retrying burns the full backoff for the same result.
-          if (response.status < 500 && response.status !== 429) break;
+          // esm.sh answers 408 after its cold-build wait, so the retry re-joins the same queued build; it gets at most
+          // one follow-up within the shared budget, since repeating it can hold a render for another full build window.
+          // 5xx responses and network errors use the bounded budget, but expose no client-side ready event, so the loop
+          // does not pretend to wait out a still-running build. 429 has no completion signal we can await, and any
+          // other 4xx is decided, so those answers stop this request.
+          if (response.status === 408 && !retriedColdBuild) {
+            retriedColdBuild = true;
+            continue;
+          }
+          if (response.status < 500) break;
         } catch (error) {
           lastFailure = error;
         }

package/src/remoteModule.ts

@@ -90,6 +90,7 @@ export function createEsmShModuleResolver(options?: EsmShModuleResolverOptions):
 }
 
 export function transformedEsmShFallback(options?: {
+  external?: readonly string[];
   dev?: boolean;
   dependencyRanges?: EsmShDependencyRanges;
   baseUrl?: string;
@@ -102,7 +103,7 @@ export function transformedEsmShFallback(options?: {
   const resolveEsmSh = options?.resolveEsmSh ?? createEsmShModuleResolver({ compiler: options?.compiler, fetch: options?.fetch, preload: options?.preload, baseUrl: options?.baseUrl });
   // Decorate the plain fallback rather than restate it: the specifier filter, the local-package preference and the
   // esm.sh URL shape all stay single-sourced, and this provider only decides what to do with each resolved target.
-  const base = esmShFallback({ dev: options?.dev, dependencyRanges: options?.dependencyRanges, hasLocalPackage: options?.hasLocalPackage });
+  const base = esmShFallback({ external: options?.external, dev: options?.dev, dependencyRanges: options?.dependencyRanges, hasLocalPackage: options?.hasLocalPackage });
   // A failed compile evicts its cache entry so a later render can retry, which means every stream chunk re-attempts and
   // would re-warn — hundreds of identical lines burying the first, actually diagnostic one. Warn once per target.
   const warned = new Set<string>();

package/src/runtime.ts

@@ -16,7 +16,7 @@ export type GenUIRendererClearOptions = { preserveVisualState?: boolean };
 export type GenUIRendererFlushMode = "microtask" | "immediate";
 // `filename` is the base @esm.sh/tsx resolves relative specifiers against. Hosts that render a file from disk pass its
 // path so `./data` stays `./data`; without one the default `_.tsx` turns it into the unresolvable `_.tsx/data` (#1601).
-export type GenUIRendererOptions = { importmap?: RendererImportMap; callbacks?: GenUIRendererCallbacks; compiler?: TsxCompiler; preserveStateOnUpdate?: boolean; flushMode?: GenUIRendererFlushMode; filename?: string };
+export type GenUIRendererOptions = { importmap?: RendererImportMap; callbacks?: GenUIRendererCallbacks; compiler?: TsxCompiler; preserveStateOnUpdate?: boolean; flushMode?: GenUIRendererFlushMode; filename?: string; synthesizeDefaultExport?: boolean };
 export type GenUIRendererUpdateMode = "push" | "render";
 
 const attachedRenderer = Symbol.for("@macaron/genui-runtime:attached-renderer");
@@ -27,6 +27,13 @@ let rendererScopeSerial = 0;
 const createRendererScope = () => `renderer:${(rendererScopeSerial += 1).toString(36)}`;
 const compiledComponentCache = new Map<string, GeneratedComponent>();
 const getPreserveBoundaryKey = (epoch: number) => (epoch === 0 ? "boundary" : `boundary:${epoch}`);
+// Any element or non-blank text counts. Deliberately not a layout check: hosts may hide their first paint for measurement.
+const hasCommittedContent = (target: HTMLElement) => {
+  for (let node = target.firstChild; node; node = node.nextSibling) {
+    if (node.nodeType === Node.ELEMENT_NODE || (node.nodeType === Node.TEXT_NODE && /\S/.test(node.nodeValue ?? ""))) return true;
+  }
+  return false;
+};
 const rememberCompiledComponent = (code: string, component: GeneratedComponent) => {
   if (compiledComponentCache.has(code)) compiledComponentCache.delete(code);
   compiledComponentCache.set(code, component);
@@ -90,6 +97,9 @@ export class GenUIRenderer {
   private flushMode: GenUIRendererFlushMode;
   private importmap?: RendererImportMap;
   private filename?: string;
+  private synthesizeDefaultExport?: boolean;
+  private inferredComponent?: string;
+  private entryEpoch = 0;
   private lastCompiledCode = "";
   private lastGoodHookSignature = "";
   private lastHookSignature: string | null = null;
@@ -109,6 +119,7 @@ export class GenUIRenderer {
     this.flushMode = options.flushMode ?? "microtask";
     this.importmap = options.importmap;
     this.filename = options.filename;
+    this.synthesizeDefaultExport = options.synthesizeDefaultExport;
     this.preserveStateOnUpdate = options.preserveStateOnUpdate ?? true;
     this.rendererScope = createRendererScope();
     this.slot = createGeneratedComponentSlot();
@@ -137,6 +148,7 @@ export class GenUIRenderer {
   }
 
   detach() {
+    this.resetEntry();
     // 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;
@@ -167,6 +179,7 @@ export class GenUIRenderer {
   }
 
   render(code: string, serial?: number) {
+    if (!code.startsWith(this.currentBuffer)) this.resetEntry();
     this.finished = true;
     this.currentBuffer = code;
     this.updateMode = "render";
@@ -181,6 +194,7 @@ export class GenUIRenderer {
   }
 
   finish(code?: string, serial?: number) {
+    if (code !== undefined && !code.startsWith(this.currentBuffer)) this.resetEntry();
     this.finished = true;
     if (code !== undefined) this.currentBuffer = code;
     this.scheduleCompile(false, serial);
@@ -229,6 +243,7 @@ export class GenUIRenderer {
   }
 
   clear(options: GenUIRendererClearOptions = {}) {
+    this.resetEntry();
     this.compileSerial += 1;
     this.currentBuffer = "";
     // `clear` terminates the current stream; the next `pushCode`/`render` selects partial vs full mode again.
@@ -250,6 +265,11 @@ export class GenUIRenderer {
     return this;
   }
 
+  private resetEntry() {
+    this.inferredComponent = undefined;
+    this.entryEpoch += 1;
+  }
+
   private scheduleCompile(partial: boolean, serial?: number) {
     if (this.flushMode === "immediate") {
       this.compileScheduled = false;
@@ -298,10 +318,12 @@ export class GenUIRenderer {
 
   private async compileOnce(partial: boolean, renderSerial?: number) {
     const serial = (this.compileSerial += 1);
+    const entryEpoch = this.entryEpoch;
+    const preferredComponent = this.inferredComponent;
     const code = this.currentBuffer;
     let result: CompileResult;
     try {
-      result = await this.compiler.compile(code, { importMap: this.importmap, partial: partial && !this.finished, previousCode: this.lastCompiledCode, filename: this.filename });
+      result = await this.compiler.compile(code, { importMap: this.importmap, partial: partial && !this.finished, previousCode: this.lastCompiledCode, filename: this.filename, synthesizeDefaultExport: this.synthesizeDefaultExport, preferredComponent });
     } catch (error) {
       // A queued follow-up means this frame is already superseded; its error is stale noise (pre-single-flight, the
       // newer compile's serial bump suppressed it the same way).
@@ -310,6 +332,13 @@ export class GenUIRenderer {
       return;
     }
     if (serial !== this.compileSerial) return;
+    // A preceding React commit can establish the entry while this asynchronous compile/import is still in flight. Within one
+    // epoch the only writer is that commit, which always stores a name, so a moved latch is necessarily non-empty.
+    const entryChanged = () => entryEpoch === this.entryEpoch && preferredComponent !== this.inferredComponent && !!result.inferredComponent && result.inferredComponent !== this.inferredComponent;
+    if (entryChanged()) {
+      this.compilePending ??= { partial, serial: renderSerial };
+      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
@@ -323,16 +352,22 @@ export class GenUIRenderer {
     }
     try {
       const { component, moduleUrl } = await this.importCompiledComponent(result.code);
+      // Superseded frames just drop; a moved entry instead re-compiles against the new preference.
       if (serial !== this.compileSerial) {
         if (moduleUrl) URL.revokeObjectURL(moduleUrl);
         return;
       }
+      if (entryChanged()) {
+        if (moduleUrl) URL.revokeObjectURL(moduleUrl);
+        this.compilePending ??= { partial, serial: renderSerial };
+        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);
+      this.renderComponent(component, code, renderSerial, result.source, undefined, result.inferredComponent ? { component: result.inferredComponent, epoch: entryEpoch } : undefined);
     } catch (error) {
       if (serial !== this.compileSerial || this.compilePending) return;
       this.callbacks.onError?.(normalizeError(error), "compile");
@@ -389,7 +424,7 @@ export class GenUIRenderer {
     else queueMicrotask(notify);
   }
 
-  private renderComponent(component = this.slot.current(), renderedCode = this.currentBuffer, renderSerial?: number, sourceCode = renderedCode, hookSignature = getGenUIHookSignature(sourceCode)) {
+  private renderComponent(component = this.slot.current(), renderedCode = this.currentBuffer, renderSerial?: number, sourceCode = renderedCode, hookSignature = getGenUIHookSignature(sourceCode), entry?: { component: string; epoch: number }) {
     if (!this.root || !component) return;
     this.renderRound += 1;
     const renderedComponent = component;
@@ -413,7 +448,9 @@ export class GenUIRenderer {
       this.lastHookSignature = renderedHookSignature;
     }
     const renderContext = this.buildStreamingRenderContext(streamingPartialFrame);
+    let failed = false;
     const onRenderError = (error: Error) => {
+      failed = true;
       this.callbacks.onError?.(error, "render");
       if (!preserve) return;
       if (this.slot.lastGood() === renderedComponent || !this.restoreLastGood()) this.errorEpoch += 1;
@@ -430,6 +467,8 @@ export class GenUIRenderer {
             if (this.slot.current() === renderedComponent) {
               this.slot.markRendered(renderedComponent);
               if (preserve) this.lastGoodHookSignature = renderedHookSignature;
+              // Empty helpers are legal React output but cannot choose the stream's entry.
+              if (!failed && entry && entry.component !== this.inferredComponent && entry.epoch === this.entryEpoch && this.target && hasCommittedContent(this.target)) this.inferredComponent = entry.component;
             }
           },
           onReady: () => {