@ggui-ai/ui-gen 0.9.0 → 0.11.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-host.ts

@@ -0,0 +1,201 @@
+/**
+ * Host side of the isolated runtime render check (#592).
+ *
+ * Spawns `render-check-worker.ts` in a sandboxed subprocess and maps
+ * every sandbox outcome onto the check's own `RenderCheckResult`
+ * vocabulary, so callers see one result shape whether the check ran
+ * in-process (DOM-owning environments) or isolated (plain Node).
+ *
+ * Outcome mapping policy (mirrors the adapter's escaped-error
+ * doctrine — component faults are `failed`, harness faults are
+ * `unverified`, and nothing throws):
+ *
+ *   - worker exit 0 + parseable verdict → the verdict, verbatim.
+ *   - timeout                    → `failed` (runaway component: the
+ *     in-process check has no comparable wall-clock bound, the
+ *     subprocess finally gives us one).
+ *   - spawn-error / overflow / non-zero exit / unparseable stdout
+ *                                → `unverified` (the harness could not
+ *     run the check; never blame the component for our plumbing).
+ *
+ * Spawn resolution copies the proven `src/tools/render-check.ts`
+ * pattern: prefer the built `dist/.../render-check-worker.js`; in
+ * dev/test (vitest imports `src/`), fall back to `node --import tsx`
+ * on the `.ts` source. tsup inlines THIS module into several dist
+ * entries (`dist/index.js`, `dist/harness/index.js`,
+ * `dist/check/index.js`, `dist/advanced/index.js`, …), so the
+ * candidate list walks from each of those locations to the one real
+ * `dist/harness/check/runtime-render/render-check-worker.js`.
+ */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { runSandboxed } from '@ggui-ai/sandbox';
+import type { SandboxResult } from '@ggui-ai/sandbox';
+import type { RenderCheckResult, RunRenderCheckInput } from './render-check.js';
+
+/**
+ * Wall-clock bound for one isolated check. The rich probe renders,
+ * clicks every declared action, and re-renders streams — slower than
+ * the smoke worker's 12s budget; 30s bounds runaway components while
+ * staying far under any generation-turn budget.
+ */
+const CHECK_TIMEOUT_MS = 30_000;
+
+/**
+ * stdout cap. The verdict JSON carries issue lists with diagnostics
+ * arrays — bigger than the smoke worker's one-liner, still tiny in
+ * absolute terms. 2 MiB is far above any legitimate verdict.
+ */
+const CHECK_STDOUT_CAP = 2 * 1024 * 1024;
+
+/**
+ * V8 heap cap. The worker realm loads react-dom, happy-dom and
+ * testing-library on top of the component itself; 512 MB leaves
+ * headroom while still bounding pathological allocation.
+ */
+const CHECK_NODE_HEAP_MB = 512;
+
+const WORKER_BASENAME = 'render-check-worker';
+
+function resolveWorkerSpawn(): { command: string; args: string[] } {
+  const jsCandidates = [
+    // Sibling — when import.meta.url is already .../harness/check/runtime-render/.
+    new URL(`./${WORKER_BASENAME}.js`, import.meta.url),
+    // From dist/index.js.
+    new URL(`./harness/check/runtime-render/${WORKER_BASENAME}.js`, import.meta.url),
+    // From dist/harness/index.js.
+    new URL(`./check/runtime-render/${WORKER_BASENAME}.js`, import.meta.url),
+    // From dist/check/index.js, dist/advanced/index.js, dist/<flat>.js.
+    new URL(`../harness/check/runtime-render/${WORKER_BASENAME}.js`, import.meta.url),
+  ];
+  for (const jsUrl of jsCandidates) {
+    const jsPath = fileURLToPath(jsUrl);
+    if (existsSync(jsPath)) {
+      return { command: process.execPath, args: [jsPath] };
+    }
+  }
+  // Dev / vitest: only the .ts source exists — run it through tsx.
+  const tsCandidates = [
+    new URL(`./${WORKER_BASENAME}.ts`, import.meta.url),
+    new URL(`../harness/check/runtime-render/${WORKER_BASENAME}.ts`, import.meta.url),
+  ];
+  for (const tsUrl of tsCandidates) {
+    const tsPath = fileURLToPath(tsUrl);
+    if (existsSync(tsPath)) {
+      const require_ = createRequire(import.meta.url);
+      const tsxLoader = pathToFileURL(require_.resolve('tsx')).href;
+      return { command: process.execPath, args: ['--import', tsxLoader, tsPath] };
+    }
+  }
+  const tried = [...jsCandidates, ...tsCandidates]
+    .map((u) => fileURLToPath(u))
+    .join(', ');
+  throw new Error(
+    `render-check: isolated worker not found at any of: ${tried}. Did \`pnpm build\` run?`,
+  );
+}
+
+function failed(reason: string, t0: number): RenderCheckResult {
+  return {
+    ok: false,
+    issues: [{ check: 'render-no-throw', outcome: 'failed', reason }],
+    stats: { actionsChecked: 0, streamsChecked: 0, renderMs: Date.now() - t0 },
+  };
+}
+
+function unverified(reason: string, t0: number): RenderCheckResult {
+  return {
+    ok: false,
+    issues: [{ check: 'render-no-throw', outcome: 'unverified', reason }],
+    stats: { actionsChecked: 0, streamsChecked: 0, renderMs: Date.now() - t0 },
+  };
+}
+
+/**
+ * Map one sandbox result onto a `RenderCheckResult`. Exported for the
+ * unit pins — the spawn itself is exercised by the integration test.
+ */
+export function mapSandboxResultToCheckResult(
+  result: SandboxResult,
+  t0: number,
+): RenderCheckResult {
+  if (result.outcome === 'timeout') {
+    return failed(
+      `render check timed out after ${CHECK_TIMEOUT_MS}ms in the isolated worker (likely infinite loop or runaway effect in the component).`,
+      t0,
+    );
+  }
+  if (result.outcome === 'overflow-stdout' || result.outcome === 'overflow-stderr') {
+    return failed(
+      `render check worker produced excessive output (${result.outcome}) — the component is likely in a pathological logging or error loop.`,
+      t0,
+    );
+  }
+  if (result.outcome === 'spawn-error') {
+    return unverified(
+      `render check worker failed to start — ${result.errorMessage}`,
+      t0,
+    );
+  }
+  if (result.outcome === 'canceled') {
+    return unverified('render check worker was canceled before completing.', t0);
+  }
+  if (result.outcome !== 'exit') {
+    return unverified(
+      `render check worker ended with unexpected sandbox outcome '${result.outcome}'.`,
+      t0,
+    );
+  }
+  if (result.exitCode !== 0) {
+    const tail = result.stderr.trim() || result.stdout.trim();
+    return unverified(
+      `render check worker exited ${result.exitCode}${tail ? ` — ${tail.slice(0, 600)}` : ''}`,
+      t0,
+    );
+  }
+  const stdout = result.stdout.trim();
+  if (stdout.length === 0) {
+    return unverified('render check worker exited without producing a verdict.', t0);
+  }
+  try {
+    return JSON.parse(stdout) as RenderCheckResult;
+  } catch (err) {
+    return unverified(
+      `render check worker verdict was not valid JSON — ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      t0,
+    );
+  }
+}
+
+/**
+ * Run the render check in an isolated subprocess. See module doc.
+ */
+export async function runRenderCheckViaWorker(
+  input: RunRenderCheckInput,
+): Promise<RenderCheckResult> {
+  const t0 = Date.now();
+  let spawn: { command: string; args: string[] };
+  try {
+    spawn = resolveWorkerSpawn();
+  } catch (err) {
+    return unverified(err instanceof Error ? err.message : String(err), t0);
+  }
+
+  const result = await runSandboxed({
+    command: spawn.command,
+    args: spawn.args,
+    timeoutMs: CHECK_TIMEOUT_MS,
+    maxStdoutBytes: CHECK_STDOUT_CAP,
+    nodeHeapMb: CHECK_NODE_HEAP_MB,
+    stdin: JSON.stringify(input),
+    // NODE_ENV steers React's production vs development build — keep
+    // parity with the caller; everything else stays on the sandbox's
+    // default allowlist.
+    env: { NODE_ENV: process.env.NODE_ENV ?? 'production' },
+  });
+
+  return mapSandboxResultToCheckResult(result, t0);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Isolated worker for the in-loop runtime render check (#592).
+ *
+ * Runs `runRenderCheckInProcess` in a SUBPROCESS so the check's
+ * happy-dom global install (`window`, `document`, `navigator`, … onto
+ * `globalThis`) lands on THIS process's globals, never the caller's.
+ *
+ * Why this exists — the process-global install is a TOCTOU hazard in
+ * any concurrent host: provider SDKs (OpenAI and Anthropic alike)
+ * sniff `typeof window !== 'undefined' && window.document && navigator`
+ * at client construction and refuse with "browser-like environment"
+ * when another cell's check-window happens to be open (#592, the
+ * 2026-08-19 bench run's gpt-5.6-sol hard failures). Two overlapping
+ * in-process checks also corrupt each other's install/teardown. A
+ * subprocess gives one private global scope per check plus real kill
+ * semantics via `@ggui-ai/sandbox` on the host side.
+ *
+ * Wire protocol (single JSON document each way):
+ *
+ *   stdin:  RunRenderCheckInput  ({ sourceCode, mockupProps, contract? })
+ *   stdout: RenderCheckResult    ({ ok, issues, stats })
+ *   exit:   0 on any verdict (issues are data, not status); non-zero
+ *           only when the worker itself is broken (malformed input,
+ *           harness crash) — the host maps that to an `unverified`
+ *           issue, mirroring the adapter's escaped-error semantics.
+ *
+ * Same file-path distribution model as `src/tools/render-check-worker.ts`
+ * (the render SMOKE worker): reached by spawn path, never by import
+ * specifier; registered as a tsup entry so `dist/harness/check/
+ * runtime-render/render-check-worker.js` ships.
+ */
+import { runRenderCheckInProcess } from './render-check.js';
+import type { RunRenderCheckInput } from './render-check.js';
+
+async function readAllStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function emit(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+async function main(): Promise<void> {
+  const raw = await readAllStdin();
+  let input: RunRenderCheckInput;
+  try {
+    input = JSON.parse(raw) as RunRenderCheckInput;
+  } catch (err) {
+    process.stderr.write(
+      `render-check worker: malformed input JSON — ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (typeof input.sourceCode !== 'string' || input.sourceCode.length === 0) {
+    process.stderr.write(
+      'render-check worker: input.sourceCode must be a non-empty string\n',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // The in-process check never throws for component failures (they are
+  // reported as issues); an escape here is a harness defect — let it
+  // crash the worker so the host maps it to `unverified` with the
+  // stderr tail as the reason.
+  const result = await runRenderCheckInProcess(input);
+  emit(result);
+  // The check's async-infra grace period (React scheduler drain) holds
+  // handlers for ~100ms; exit through the event loop naturally so that
+  // drain completes inside the worker instead of leaking crashes.
+}
+
+void main();

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;
@@ -112,8 +114,48 @@ export interface RunRenderCheckInput {
 // Public entry
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Run the in-loop runtime render check.
+ *
+ * Isolation dispatcher (#592): when the CALLING environment already
+ * owns a DOM (`window` + `document` on `globalThis` — e.g. a vitest
+ * `happy-dom` environment, where the environment owner installed the
+ * globals deliberately), the check runs in-process exactly as before.
+ * In a plain Node process it runs in an ISOLATED SUBPROCESS
+ * (`render-check-host.ts` → `render-check-worker.ts`), because the
+ * in-process path installs happy-dom globals on `globalThis`
+ * process-wide — a TOCTOU hazard for anything that sniffs `window`
+ * concurrently (provider SDKs throw "browser-like environment" at
+ * client construction; two overlapping checks corrupt each other's
+ * teardown). See #592 for the measured incident (4 bench cells hard-
+ * failed on the 2026-08-19 run).
+ *
+ * The host is loaded lazily so the worker bundle (which imports this
+ * module for `runRenderCheckInProcess`) never drags in the sandbox
+ * spawn machinery.
+ */
 export async function runRenderCheck(
   input: RunRenderCheckInput,
+): Promise<RenderCheckResult> {
+  const g = hostGlobals();
+  if ("window" in g && "document" in g) {
+    return runRenderCheckInProcess(input);
+  }
+  const { runRenderCheckViaWorker } = await import("./render-check-host.js");
+  return runRenderCheckViaWorker(input);
+}
+
+/**
+ * The actual check, executed IN THE CURRENT PROCESS — installs
+ * happy-dom globals on `globalThis` for the duration when the
+ * environment doesn't already provide a DOM. Call sites outside this
+ * module should use {@link runRenderCheck}; this export exists for the
+ * isolation worker (which IS the private process the globals may own)
+ * and for DOM-owning test environments that want to bypass the
+ * dispatcher explicitly.
+ */
+export async function runRenderCheckInProcess(
+  input: RunRenderCheckInput,
 ): Promise<RenderCheckResult> {
   const t0 = Date.now();
   const issues: RenderCheckIssue[] = [];
@@ -237,6 +279,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 +559,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();
     }