@ggui-ai/ui-gen 0.10.0 → 0.12.0

package/dist/{render-check-BNYGVDJd.d.ts → render-check-WfOVO9kU.d.ts}

@@ -10,7 +10,7 @@ import { JsonObject, DataContract } from '@ggui-ai/protocol';
  */
 type CheckOutcome = "verified" | "failed" | "unverified" | "skipped";
 interface RenderCheckIssue {
-    readonly check: "render-no-throw" | "action-wiring" | "prop-coverage" | "stream-rerender" | "optional-props-omitted";
+    readonly check: "render-no-throw" | "action-wiring" | "selection-identity" | "prop-coverage" | "prop-sensitivity" | "stream-rerender" | "optional-props-omitted";
     readonly outcome: CheckOutcome;
     readonly subject?: string;
     readonly reason: string;
@@ -45,6 +45,26 @@ interface RunRenderCheckInput {
     readonly mockupProps: JsonObject;
     readonly contract?: DataContract;
 }
+/**
+ * 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.
+ */
 declare function runRenderCheck(input: RunRenderCheckInput): Promise<RenderCheckResult>;
 
 export { type RenderCheckIssue as R, type RenderCheckResult as a, runRenderCheck as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -188,9 +188,9 @@
     "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/mcp-server-core": "0.10.0",
-    "@ggui-ai/project-config": "0.10.0",
-    "@ggui-ai/protocol": "0.10.0"
+    "@ggui-ai/mcp-server-core": "0.12.0",
+    "@ggui-ai/protocol": "0.12.0",
+    "@ggui-ai/project-config": "0.12.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -229,11 +229,11 @@
     "openai": "^6.29.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/gadgets": "0.10.0",
-    "@ggui-ai/design": "0.10.0",
-    "@ggui-ai/sandbox": "0.10.0",
-    "@ggui-ai/ui-visual-tester": "0.10.0",
-    "@ggui-ai/wire": "0.10.0"
+    "@ggui-ai/design": "0.12.0",
+    "@ggui-ai/gadgets": "0.12.0",
+    "@ggui-ai/sandbox": "0.12.0",
+    "@ggui-ai/ui-visual-tester": "0.12.0",
+    "@ggui-ai/wire": "0.12.0"
   },
   "devDependencies": {
     "@google/adk": "^0.5.0",
@@ -248,9 +248,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.10.0",
-    "@ggui-ai/project-config": "0.10.0",
-    "@ggui-ai/protocol": "0.10.0"
+    "@ggui-ai/mcp-server-core": "0.12.0",
+    "@ggui-ai/protocol": "0.12.0",
+    "@ggui-ai/project-config": "0.12.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/boilerplate/system-prompt.ts

@@ -572,15 +572,15 @@ EVERY color, spacing, typography, shadow, and radius value MUST come from design
 
 MANDATORY:
 1. NEVER use hardcoded hex colors like \`#7c3aed\` — ONLY \`var(--ggui-color-*)\` tokens.
-2. NEVER use CSS gradients with custom colors. If you need a gradient: \`linear-gradient(to bottom, var(--ggui-color-primary-500, #0ea5e9), var(--ggui-color-primary-700, #0369a1))\`.
+2. NEVER use CSS gradients with custom colors. If you need a gradient: \`linear-gradient(to bottom, var(--ggui-color-primary-500), var(--ggui-color-primary-700))\`.
 3. NEVER invent your own palette. The system provides primary, neutral, success, warning, error, and info — use ONLY these.
-4. ALWAYS include fallback values: \`var(--ggui-color-primary-600, #0284c7)\`.
+4. NEVER include literal fallback values in color tokens — write \`var(--ggui-color-primary-600)\` bare, never \`var(--ggui-color-primary-600, #0284c7)\`. The runtime injects every token; a literal fallback paints the wrong brand exactly when the operator's theme matters most.
 
 Token categories:
-- Brand: \`var(--ggui-color-primary-600, #0284c7)\`, \`var(--ggui-color-primary-50, #f0f9ff)\`
-- Text: \`var(--ggui-color-onSurface, #18181b)\`, \`var(--ggui-color-onSurfaceVariant, #52525b)\`
-- Backgrounds: \`var(--ggui-color-surface, #fafafa)\`, \`var(--ggui-color-surfaceVariant, #f4f4f5)\`
-- Borders: \`var(--ggui-color-outline, #d4d4d8)\`
+- Brand: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
+- Text: \`var(--ggui-color-onSurface)\`, \`var(--ggui-color-onSurfaceVariant)\`
+- Backgrounds: \`var(--ggui-color-surface)\`, \`var(--ggui-color-surfaceVariant)\`
+- Borders: \`var(--ggui-color-outline)\`
 - Spacing: \`var(--ggui-spacing-4, 16px)\`, \`var(--ggui-spacing-6, 24px)\`
 - Typography: \`var(--ggui-font-size-sm, 14px)\`, \`var(--ggui-font-weight-semibold, 600)\`
 - Shadows: \`var(--ggui-shape-shadow-sm)\`, \`var(--ggui-shape-shadow-md)\`, \`var(--ggui-shape-shadow-lg)\`
@@ -765,7 +765,7 @@ Hero sections should feel airy. Use \`padding="xl"\` (32px) on the main card, no
 
 - [ ] Imports ONLY from: react, @ggui-ai/design, @ggui-ai/wire
 - [ ] No raw HTML elements (\`<button>\`, \`<input>\`, \`<div>\` for layout) — uses primitives
-- [ ] ZERO hardcoded hex colors — every color is \`var(--ggui-color-*, fallback)\`
+- [ ] ZERO hardcoded hex colors — every color is a bare \`var(--ggui-color-*)\`, no literal fallback
 - [ ] No raw pixel values for spacing — all via \`var(--ggui-spacing-*)\` tokens
 - [ ] Primary palette used throughout (headers, borders, icons) — not just buttons
 - [ ] Typed Props interface exported; request-specific data is a prop with default

package/src/check/run-tier0.ts

@@ -508,22 +508,41 @@ export async function runTier0Checks(
     // typed escape on Box (`assetColor` + `assetSemantic`) — see
     // T-4 follow-up.
     const hexMatch = line.match(/#[0-9a-fA-F]{3,8}\b/);
-    if (
-      hexMatch &&
-      !line.includes('var(--ggui-') &&
-      !line.includes('// fallback') &&
-      !assetEscapedLines.has(lineNum)
-    ) {
-      issues.push({
-        tier: 0,
-        result: 'fail',
-        category: 'tokens',
-        subcategory: 'hex-color',
-        severity: 'critical',
-        description: `Hardcoded color "${hexMatch[0]}" breaks theme switching — use design tokens.`,
-        fix: `Replace with a primitive variant (Button variant="primary"|Badge variant="success"|...) OR a token reference like var(--ggui-color-primary-500, ${hexMatch[0]}). Hardcoded colors mean the operator's theme has no effect on this surface.`,
-        line: lineNum,
-      });
+    if (hexMatch && !assetEscapedLines.has(lineNum)) {
+      // ggui#598 slice 4 (origin-kill): hex inside a `var(--ggui-*, #hex)`
+      // fallback is ALSO a violation now — the runtime injects every
+      // token, so a literal fallback can only ever paint default-brand
+      // pixels under a failed injection, which must be visible (unset)
+      // rather than silently sky-blue under someone's brand. The old
+      // exemption plus a remediation text that suggested
+      // `var(--x, ${hex})` actively taught the model to launder its
+      // invented hex INTO fallbacks (adversarial-cycle find).
+      const fallbackVarMatch = line.match(
+        /var\((--ggui-[a-zA-Z0-9-]+)\s*,[^)]*#[0-9a-fA-F]{3,8}/,
+      );
+      if (fallbackVarMatch) {
+        issues.push({
+          tier: 0,
+          result: 'fail',
+          category: 'tokens',
+          subcategory: 'token-fallback',
+          severity: 'critical',
+          description: `Literal fallback "${hexMatch[0]}" inside a token reference — the runtime injects every token, and the fallback paints the wrong brand exactly when the theme matters most.`,
+          fix: `Drop the fallback: write var(${fallbackVarMatch[1]}) bare. If the token might not exist, that is a vocabulary problem to fix by choosing a token from the design-system docs, never by a literal.`,
+          line: lineNum,
+        });
+      } else if (!line.includes('// fallback')) {
+        issues.push({
+          tier: 0,
+          result: 'fail',
+          category: 'tokens',
+          subcategory: 'hex-color',
+          severity: 'critical',
+          description: `Hardcoded color "${hexMatch[0]}" breaks theme switching — use design tokens.`,
+          fix: `Replace with a primitive variant (Button variant="primary"|Badge variant="success"|...) OR a bare token reference like var(--ggui-color-primary-500) — never a literal fallback. Hardcoded colors mean the operator's theme has no effect on this surface.`,
+          line: lineNum,
+        });
+      }
     }
 
     // Hardcoded rgba()/hsl() color functions — same reasoning as above.

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

@@ -250,6 +250,34 @@ function toEvalIssue(issue: RenderCheckIssue): EvalIssue | null {
       };
     }
 
+    case "selection-identity":
+      return {
+        tier: 0,
+        result,
+        category: "contract",
+        subcategory,
+        severity: "critical",
+        description: `${issue.reason}${elementHint}${diagSuffix}`,
+        fix:
+          `Key the action payload (and any selection state) on the item's ID from the data, never on its display text. ` +
+          `Common fix: map over items and pass the item's id into the handler — onClick={() => ${subject}({ ...payload, id: item.id })} — ` +
+          `and store selection as the id (setSelected(item.id)), not the label.`,
+      };
+
+    case "prop-sensitivity":
+      return {
+        tier: 0,
+        result,
+        category: "contract",
+        subcategory,
+        severity: "critical",
+        description: `${issue.reason}${diagSuffix}`,
+        fix:
+          `Derive the display AND any logic from props.${subject} — render {props.${subject}} and branch on the prop's value, ` +
+          `never on the literal value the request happened to mention (e.g. props.${subject} ?? 'January' followed by ` +
+          `January-special-cased logic bakes the request into the component). The contract delivers the value; trust it.`,
+      };
+
     case "prop-coverage":
       return {
         tier: 0,

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