@ggui-ai/ui-gen 0.9.0 → 0.10.0

package/src/harness/check/runtime-render/production-act-shim.ts

@@ -0,0 +1,158 @@
+// packages/ui-gen/src/harness/check/runtime-render/production-act-shim.ts
+//
+// Minimal adaptation to two upstream constraints, neither of which
+// this package controls:
+//
+//   1. React intentionally strips `act` from its PRODUCTION build.
+//      `react/cjs/react.production.js` does not export it — only the
+//      development build does (`typeof require('react').act` is
+//      `'function'` under a dev build, `undefined` under production).
+//   2. `@testing-library/react`'s `act-compat` module hard-requires
+//      `act` at MODULE SCOPE: it snapshots
+//      `typeof React.act === 'function' ? React.act : DeprecatedReactTestUtils.act`
+//      into a `const` the first time it is imported in the process.
+//      Under a production build, that snapshot resolves to React
+//      DOM's `react-dom/test-utils` production `act` stub, which
+//      THROWS `React.act is not a function` the moment it is called.
+//
+// Hosts that run this probe inside a production Node process
+// (server-side blueprint validation) hit this: every render throws
+// through RTL's `act` wrapper before the probe ever sees the
+// component. Hosts that run it under a development/test build (every
+// CI/vitest run in this repo — `NODE_ENV=test` resolves the dev
+// build) never see it; `act` is real there and this shim is a no-op.
+//
+// **Load-order constraint**: this MUST run before the FIRST import of
+// `@testing-library/react` anywhere in the process — act-compat binds
+// its `act` reference into a module-scope `const` at import time, so
+// patching `react-dom/test-utils` AFTER that import has already
+// happened does nothing (the snapshot already captured the broken
+// stub). Patch `react-dom/test-utils`, never `react` itself — that
+// entry point is deprecated and test-only, so this patch cannot
+// perturb any production rendering path; nothing else in a server
+// process legitimately imports it.
+//
+// `createRequire` (not `import`) reaches these modules deliberately:
+// ESM namespace objects are frozen, so a normal `import` gives no way
+// to mutate `act` on it. The CJS `module.exports` objects `require`
+// resolves are mutable, and RTL's act-compat interop-copies THAT
+// object's properties at its own load time — so mutating it here,
+// before RTL loads, is what makes the patch visible to RTL at all.
+
+import { createRequire } from "node:module";
+
+let installed = false;
+
+/**
+ * The one property this module reads/mutates on `react` and
+ * `react-dom/test-utils`'s CJS exports. A minimal local shape rather
+ * than the real (deprecated, possibly absent) type declarations for
+ * `react-dom/test-utils` — narrow enough to type-check the mutation
+ * without `as any` / `Record<string, unknown>`.
+ */
+interface MutableActCarrier {
+  act?: unknown;
+}
+
+/** The one React DOM export this module needs — typed narrowly for the same reason. */
+interface FlushSyncCarrier {
+  flushSync: (fn: () => void) => void;
+}
+
+/**
+ * Patch `react-dom/test-utils`'s `act` with a `flushSync`-backed
+ * replacement, but ONLY when the current process is running React's
+ * production build (no real `act` exported). Idempotent — safe to
+ * call more than once or from more than one call site; the actual
+ * patch only ever applies once per process.
+ *
+ * No-op (by design, not by accident) whenever `react`'s own `act`
+ * export is a real function — every dev/test build, including every
+ * vitest run in this repo. This shim changes zero behavior in CI.
+ */
+export function installProductionActShim(): void {
+  if (installed) return;
+  installed = true;
+
+  const require_ = createRequire(import.meta.url);
+
+  let reactCjs: MutableActCarrier;
+  try {
+    reactCjs = require_("react");
+  } catch {
+    // React itself isn't resolvable in this process — the probe
+    // surfaces its own load error; nothing for this shim to patch.
+    return;
+  }
+
+  if (typeof reactCjs.act === "function") {
+    // Dev/test builds export a real `act` — strict no-op.
+    return;
+  }
+
+  try {
+    const testUtils: MutableActCarrier = require_("react-dom/test-utils");
+    const reactDom: FlushSyncCarrier = require_("react-dom");
+    testUtils.act = createFlushSyncAct(reactDom.flushSync);
+  } catch {
+    // Frozen/locked exports (or a react-dom build without flushSync)
+    // — leave it. The probe then surfaces the raw upstream error,
+    // which is the pre-fix behavior: an honest failure, not a
+    // silently-broken patch.
+  }
+}
+
+/**
+ * Build an `act`-compatible replacement backed by `flushSync`, which
+ * — unlike `act` — DOES exist in React's production build.
+ *
+ * `flushSync` is the single property this shim relies on from dev
+ * `act`: it forces the scheduled render to commit SYNCHRONOUSLY
+ * before returning, so a render throw propagates synchronously to the
+ * caller and the DOM is fully committed by the time this resolves.
+ *
+ * Returned function is act-style: if the callback itself returned a
+ * thenable (RTL's async act-wrapped interactions), the result
+ * resolves once that thenable settles (rejecting on its rejection);
+ * otherwise it resolves after one microtask, mirroring `act`'s own
+ * "flush the microtask queue" contract for the synchronous case.
+ *
+ * **Known, documented delta vs. a real dev `act`**: passive effects
+ * (`useEffect`) flush on a LATER task under `flushSync`, not
+ * synchronously at act-exit — `flushSync` only guarantees the
+ * synchronous commit, not effect flushing. The probe's uncaught-error
+ * handlers plus its 100ms teardown grace window (`render-check.ts`'s
+ * `cleanupAsyncInfra`) already cover a late effect throwing after this
+ * resolves, so this delta does not reopen the crash class the probe
+ * exists to catch.
+ *
+ * Exported separately so the flushSync/thenable semantics are unit
+ * testable without a real React runtime.
+ */
+export function createFlushSyncAct(
+  flushSync: (fn: () => void) => void,
+): (callback: () => unknown) => Promise<void> {
+  return (callback: () => unknown): Promise<void> => {
+    let callbackResult: unknown;
+    flushSync(() => {
+      callbackResult = callback();
+    });
+    if (isThenable(callbackResult)) {
+      const pending = callbackResult;
+      return new Promise<void>((resolve, reject) => {
+        pending.then(() => resolve(), reject);
+      });
+    }
+    return new Promise<void>((resolve) => {
+      queueMicrotask(resolve);
+    });
+  };
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}

package/src/harness/check/runtime-render/render-check.ts

@@ -24,6 +24,7 @@ import { HOOK_NAME_RE, listContractGadgets } from "@ggui-ai/protocol";
 import { createProbe, createProbeWireConfig, type Probe } from "./probe.js";
 import { loadComponent } from "./load-component.js";
 import { findWiring, type WiringDetection } from "./find-wiring.js";
+import { installProductionActShim } from "./production-act-shim.js";
 // All happy-dom / RTL / user-event narrowing flows through the typed
 // host boundary (one set of structural interfaces + validating guards;
 // DOM-lib-free — some downstream packages, e.g. cloud/amplify, exclude
@@ -70,7 +71,8 @@ export interface RenderCheckIssue {
     | "render-no-throw"
     | "action-wiring"
     | "prop-coverage"
-    | "stream-rerender";
+    | "stream-rerender"
+    | "optional-props-omitted";
   readonly outcome: CheckOutcome;
   readonly subject?: string;
   readonly reason: string;
@@ -237,6 +239,9 @@ export async function runRenderCheck(
     // internals.
     uninstallSpy = probe.installPostMessageSpy();
 
+    // Must run before RTL's first import in this process — see
+    // production-act-shim.ts's docstring for why.
+    installProductionActShim();
     const { render, cleanup } = await import("@testing-library/react");
     // user-event v14 default export — see https://testing-library.com/docs/user-event/intro/
     const userEventModule = await import("@testing-library/user-event");
@@ -514,6 +519,72 @@ export async function runRenderCheck(
           if (issue) issues.push(issue);
         }
       }
+
+      // ── Check 7: Optional-props omission (BLOCK on crash, ggui#528) ──
+      // The main pass renders with EVERY declared prop filled, so a
+      // component that assumes an optional prop is present always
+      // passes here and crashes only live, when an agent legitimately
+      // omits it (the wire gate requires only `required === true`
+      // props). Render a second instance with the optional props
+      // STRIPPED — a throw is exactly the latent-undefined class this
+      // check exists to surface. Runs only when the contract declares
+      // at least one optional prop that the mockup filled; zero cost
+      // otherwise.
+      const declaredProps = input.contract?.propsSpec?.properties;
+      if (declaredProps) {
+        const optionalFilled = Object.entries(declaredProps)
+          .filter(([name, entry]) =>
+            (entry as { required?: boolean }).required !== true &&
+            input.mockupProps[name] !== undefined,
+          )
+          .map(([name]) => name);
+        if (optionalFilled.length > 0) {
+          const requiredOnlyProps: JsonObject = { ...input.mockupProps };
+          for (const name of optionalFilled) delete requiredOnlyProps[name];
+          const omitBoundaryRef: { error?: Error } = {};
+          class OmitErrorBoundary extends React.Component<
+            { children?: React.ReactNode },
+            { caught: boolean }
+          > {
+            state = { caught: false };
+            static getDerivedStateFromError(): { caught: boolean } {
+              return { caught: true };
+            }
+            componentDidCatch(error: Error): void {
+              omitBoundaryRef.error ??= error;
+            }
+            render(): React.ReactNode {
+              if (this.state.caught) return null;
+              return this.props.children;
+            }
+          }
+          try {
+            render(
+              React.createElement(GguiWireProvider, {
+                config: wireConfig,
+                children: React.createElement(OmitErrorBoundary, {
+                  children: React.createElement(Component, requiredOnlyProps),
+                }),
+              }),
+            );
+          } catch (e) {
+            omitBoundaryRef.error ??=
+              e instanceof Error ? e : new Error(String(e));
+          }
+          if (omitBoundaryRef.error) {
+            issues.push({
+              check: "optional-props-omitted",
+              outcome: "failed",
+              subject: optionalFilled.join(", "),
+              reason:
+                `Render crashed when the optional prop(s) ${optionalFilled
+                  .map((n) => `'${n}'`)
+                  .join(", ")} were omitted: ${omitBoundaryRef.error.message}. ` +
+                `The contract marks them optional (no \`required: true\`), so a legitimate render may leave them out.`,
+            });
+          }
+        }
+      }
     } finally {
       cleanup();
     }

package/src/harness/coding/run-eval-round.ts

@@ -121,6 +121,29 @@ export interface EvalRoundResult {
 /** Cap feedback to N issues per eval-fix turn so the LLM stays surgical. */
 const MAX_FEEDBACK_ISSUES = 3;
 
+/**
+ * Pick the ≤{@link MAX_FEEDBACK_ISSUES} issues an eval-fix turn feeds
+ * back. Provenance-aware (Exp 54 P1 addendum): ONE slot is reserved
+ * for the first deterministic tier-0 fail (axis/mode checks —
+ * machine-verified findings) when one exists; the rest fill
+ * fails-first then warns. Without the reservation, the merge order
+ * put deterministic findings last and any round with ≥3 LLM-judge
+ * fails silently starved them — the model never saw a precision-1.00
+ * structural finding while the stuck detector blamed it for not
+ * fixing it. Exactly one slot, so crash-class LLM fails keep the
+ * other two. Exported for the pins.
+ */
+export function selectActionableFeedback(issues: readonly EvalIssue[]): EvalIssue[] {
+  const pool = issues.filter((i) => i.result === "fail" || i.result === "warn");
+  const reserved = pool.find((i) => i.tier === 0 && i.result === "fail");
+  return [
+    ...(reserved ? [reserved] : []),
+    ...pool
+      .filter((i) => i !== reserved)
+      .sort((a, b) => (a.result === "fail" ? 0 : 1) - (b.result === "fail" ? 0 : 1)),
+  ].slice(0, MAX_FEEDBACK_ISSUES);
+}
+
 /**
  * Fingerprint a fail issue for cross-round stuck detection. Identifies the
  * "same fail" without being thrown by minor description-text variation.
@@ -424,6 +447,13 @@ export async function runEvalRound(
               // inside the same concurrent generation, so the race is
               // real here too, not just on the coding turn).
               routeOverride: evaluationAgent.routeOverride,
+              // #489 — thread the same provider-429-retry observer.
+              // Without this, a rate-limited retry inside the
+              // evaluation agent's apiCall() happens (the base-class
+              // retry loop is unconditional) but never reaches the
+              // caller, silently missing the host application's
+              // structured log.
+              onRetry: evaluationAgent.onRetry,
             },
             preWarmedContext,
           )
@@ -437,6 +467,14 @@ export async function runEvalRound(
               passThreshold: visualThreshold,
               sampleProps: visualEvaluation?.sampleProps,
               viewport: visualEvaluation?.viewport,
+              // #484/#489 — same threading as the LLM-eval leg above:
+              // the visual eval's multimodal call runs inside the same
+              // concurrent generation, so it needs the same routing
+              // override (never fall back to `process.env`) and the
+              // same provider-429-retry observer (retries reach the
+              // host application's structured log).
+              routeOverride: visualEvalAgent.routeOverride,
+              onRetry: visualEvalAgent.onRetry,
             },
           )
         : null,
@@ -758,10 +796,19 @@ export async function runEvalRound(
     // Feeding too many issues at once causes the LLM to make many simultaneous
     // changes, breaking JSX nesting in complex components. Prioritize fails
     // first, then warns, capped to keep fixes surgical.
-    const allActionable = evalResult.issues
-      .filter((i) => i.result === "fail" || i.result === "warn")
-      .sort((a, b) => (a.result === "fail" ? 0 : 1) - (b.result === "fail" ? 0 : 1))
-      .slice(0, MAX_FEEDBACK_ISSUES);
+    //
+    // Provenance-aware selection (Exp 54 P1 addendum): deterministic
+    // tier-0 fails (axis/mode checks — machine-verified, precision-1.00
+    // findings) get ONE reserved slot, first. Before this, the merge
+    // order (`allIssues = [...llm, ...visual, ...mode]`) + stable sort
+    // + slice meant any round where the LLM leg emitted ≥3 fails
+    // silently starved every deterministic finding — the model never
+    // saw it, the fingerprint set still recorded it, and the stuck
+    // detector exited on an issue that was never delivered (2/9 cells
+    // shipped a P0 structural defect this way, one displaced by
+    // design-token nits). Exactly one slot is reserved so crash-class
+    // LLM fails keep the other two.
+    const allActionable = selectActionableFeedback(evalResult.issues);
     const issueLines = allActionable.map((issue) => {
       const tag = issue.result === "fail" ? "FAIL" : "WARN";
       return `[${tag}] ${issue.category}${issue.subcategory ? "/" + issue.subcategory : ""}: ${issue.description}\n  Fix: ${issue.fix}`;
@@ -777,7 +824,16 @@ export async function runEvalRound(
       evalResult,
       evalRoundsUsed,
       prevModeSubcats: updatedPrevModeSubcats,
-      prevFailFingerprints: currFailFingerprints,
+      // DELIVERED fails only (Exp 54 P1 addendum, proposal 2): the
+      // stuck detector's premise is "the LLM saw these and did not
+      // resolve them" — recording fails that the MAX_FEEDBACK_ISSUES
+      // cap cut from the feedback turns truncation into a premature
+      // stuck-exit (the model never saw the issue it is blamed for
+      // not fixing). An undelivered fail recurring next round now
+      // reads as NEW, gets delivered, and earns its fix round.
+      prevFailFingerprints: new Set(
+        allActionable.filter((i) => i.result === "fail").map(fingerprintFail),
+      ),
       preWarmedContext,
       evalTokens,
       evalLlmMs,

package/src/harness/index.ts

@@ -27,7 +27,7 @@ export type {
 } from "./types-public.js";
 export { defaultApplyPatch, applyLineRanges } from "../patch.js";
 export { callLLM, createAgent } from "./llm-router.js";
-export type { AgentConfig, LLMResponse } from "./llm-router.js";
+export type { AgentConfig, LLMResponse, ProviderRetryInfo } from "./llm-router.js";
 export {
   computeHarnessId,
   computeHarnessName,