@ggui-ai/ui-gen 0.11.0 → 0.13.0

package/dist/{render-check-BZoIE8-u.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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.11.0",
+  "version": "0.13.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/project-config": "0.11.0",
-    "@ggui-ai/mcp-server-core": "0.11.0",
-    "@ggui-ai/protocol": "0.11.0"
+    "@ggui-ai/mcp-server-core": "0.13.0",
+    "@ggui-ai/protocol": "0.13.0",
+    "@ggui-ai/project-config": "0.13.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -229,11 +229,11 @@
     "openai": "^6.29.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/gadgets": "0.11.0",
-    "@ggui-ai/sandbox": "0.11.0",
-    "@ggui-ai/ui-visual-tester": "0.11.0",
-    "@ggui-ai/wire": "0.11.0",
-    "@ggui-ai/design": "0.11.0"
+    "@ggui-ai/design": "0.13.0",
+    "@ggui-ai/gadgets": "0.13.0",
+    "@ggui-ai/ui-visual-tester": "0.13.0",
+    "@ggui-ai/sandbox": "0.13.0",
+    "@ggui-ai/wire": "0.13.0"
   },
   "devDependencies": {
     "@google/adk": "^0.5.0",
@@ -248,16 +248,16 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/mcp-server-core": "0.11.0",
-    "@ggui-ai/project-config": "0.11.0",
-    "@ggui-ai/protocol": "0.11.0"
+    "@ggui-ai/mcp-server-core": "0.13.0",
+    "@ggui-ai/project-config": "0.13.0",
+    "@ggui-ai/protocol": "0.13.0"
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "author": "ggui contributors <hello@ggui.ai>",
   "scripts": {
-    "build": "NODE_OPTIONS=--max-old-space-size=8192 tsup",
+    "build": "NODE_OPTIONS=--max-old-space-size=8192 TSUP_OUT_DIR=dist.staging tsup && node ../scripts/atomic-swap.mjs dist.staging dist",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

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.ts

@@ -21,7 +21,12 @@ import type {
   PropsSpec,
 } from "@ggui-ai/protocol";
 import { HOOK_NAME_RE, listContractGadgets } from "@ggui-ai/protocol";
-import { createProbe, createProbeWireConfig, type Probe } from "./probe.js";
+import {
+  createProbe,
+  createProbeWireConfig,
+  type ActionFiredEvent,
+  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";
@@ -70,7 +75,9 @@ export interface RenderCheckIssue {
   readonly check:
     | "render-no-throw"
     | "action-wiring"
+    | "selection-identity"
     | "prop-coverage"
+    | "prop-sensitivity"
     | "stream-rerender"
     | "optional-props-omitted";
   readonly outcome: CheckOutcome;
@@ -519,6 +526,35 @@ export async function runRenderCheckInProcess(
         }
       }
 
+      // ── Check 2b: Selection identity — duplicate-label cells (#601) ───
+      // The live bug: a slot grid rendered several cells with the same
+      // visible label ("09:00" across stylist rows); clicking one
+      // selected ALL of them because the generated code keyed
+      // selection/payload on the DISPLAY VALUE instead of the cell's
+      // identity — even though the action schema carried an id field.
+      // Wire-behavior check, DOM-shape independent: click two
+      // same-label clickables and require their fired payloads to
+      // differ on the id-like field. Conservative: any ambiguity
+      // (no duplicate labels, clicks that fire nothing, payloads
+      // missing the field) yields NO issue — those belong to other
+      // checks.
+      if (input.contract?.actionSpec) {
+        for (const [name, entry] of Object.entries(input.contract.actionSpec)) {
+          const idField = idLikeRequiredStringField(
+            entry.schema as Record<string, unknown> | undefined,
+          );
+          if (idField === null) continue;
+          const issue = await checkSelectionIdentity({
+            container,
+            probe,
+            user,
+            actionName: name,
+            idField,
+          });
+          if (issue) issues.push(issue);
+        }
+      }
+
       // ── Check 3: Agent-tool wiring — RETIRED ──────────────────────────
       // `useWiredTool` is retired. The contract's `agentCapabilities.tools`
       // is a catalog of tools the AGENT invokes — there is no component hook
@@ -545,6 +581,72 @@ export async function runRenderCheckInProcess(
         }
       }
 
+      // ── Check 5c: Prop sensitivity (#563) ─────────────────────────────
+      // The measured class (economy/001 run 6): generated code renders a
+      // value the contract delivers via props but BAKES the request's
+      // literal — `props.month ?? 'January'` date math, hardcoded display
+      // text — so a cached blueprint reused under a different value serves
+      // the wrong surface. Deterministic detection for the DISPLAYED-value
+      // half: re-render with a distinct value for each required scalar
+      // prop whose original value visibly appears in the DOM; if the
+      // rendered text is IDENTICAL under the change, the prop's value is
+      // dead — baked. Scope honesty: value-ANCHORED logic that still
+      // reacts (differently-wrong branches) is not deterministically
+      // decidable here; the matcher-side pair armor and the judge track
+      // that half. Conservative nulls: non-displayed props (ids are
+      // legitimately non-visual), varied-value crashes (the code READ the
+      // prop — not dead), and non-scalar props are all skipped.
+      if (input.contract?.propsSpec) {
+        const propsSpec5c = input.contract.propsSpec as PropsSpec;
+        const normalize = (s: string | null): string =>
+          (s ?? "").replace(/\s+/g, " ").trim();
+        const baseText = normalize(container.textContent);
+        for (const [propName, entry] of Object.entries(propsSpec5c.properties)) {
+          if (!entry.required) continue;
+          const orig = input.mockupProps[propName];
+          if (typeof orig !== "string" && typeof orig !== "number") continue;
+          const marker = pickScalarMarker(orig);
+          if (marker === null || !baseText.includes(marker)) continue;
+          // Distinct same-type value. A token that never substring-matches
+          // the original, so value-anchored branches (`includes(orig)`)
+          // genuinely flip.
+          const varied: string | number =
+            typeof orig === "string" ? "Zzyzx Qw" : (orig as number) + 137731;
+          // Isolated probe/wire per varied mount — events must not leak
+          // into the primary probe's fire log.
+          const variedProbe = createProbe();
+          const variedConfig = createProbeWireConfig(variedProbe);
+          let variedResult: ReturnType<typeof render> | undefined;
+          try {
+            variedResult = render(
+              React.createElement(GguiWireProvider, {
+                config: variedConfig,
+                children: React.createElement(ProbeErrorBoundary, {
+                  children: React.createElement(Component, {
+                    ...input.mockupProps,
+                    [propName]: varied,
+                  }),
+                }),
+              }),
+            );
+          } catch {
+            continue; // crash on varied value ⇒ the prop is read, not dead
+          }
+          await flushPromises();
+          const variedText = normalize(variedResult.container.textContent);
+          variedResult.unmount();
+          if (variedText === baseText) {
+            issues.push({
+              check: "prop-sensitivity",
+              outcome: "failed",
+              subject: propName,
+              reason:
+                `props.${propName} is displayed ('${marker}' appears in the DOM) but changing its value to '${String(varied)}' left the rendered output BYTE-IDENTICAL — the value is baked into the component instead of derived from the prop. A cached reuse of this blueprint under a different ${propName} would show the original value.`,
+            });
+          }
+        }
+      }
+
       // ── Check 6: Stream re-render (WARN) ──────────────────────────────
       if (input.contract?.streamSpec) {
         const streamSpec = input.contract.streamSpec;
@@ -1081,6 +1183,127 @@ async function checkActionWiring(input: CheckActionInput): Promise<RenderCheckIs
 // `streamSpec[*].source.tool` ride through the action / stream check
 // arms in `runRenderCheck` instead.
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Selection identity (#601) — duplicate-label cells must carry their own id
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Find the id-like required string property in an action's payload
+ * schema, or null. "id-like" = a required property whose name ends in
+ * `id`/`Id`/`ID` and whose declared type is string — the shape the
+ * matcher's booking/selection contracts carry (`bookSlot { slotId }`).
+ */
+function idLikeRequiredStringField(
+  schema: Record<string, unknown> | undefined,
+): string | null {
+  if (schema === undefined) return null;
+  const properties = schema['properties'];
+  const required = schema['required'];
+  if (properties === null || typeof properties !== 'object') return null;
+  if (!Array.isArray(required)) return null;
+  for (const [propName, propSchema] of Object.entries(
+    properties as Record<string, unknown>,
+  )) {
+    if (!/id$/i.test(propName)) continue;
+    if (!required.includes(propName)) continue;
+    const t =
+      propSchema !== null && typeof propSchema === 'object'
+        ? (propSchema as Record<string, unknown>)['type']
+        : undefined;
+    if (t === 'string') return propName;
+  }
+  return null;
+}
+
+interface CheckSelectionIdentityInput {
+  container: MinimalElement;
+  probe: Probe;
+  user: { click: (el: MinimalElement) => Promise<void> };
+  actionName: string;
+  idField: string;
+}
+
+/**
+ * Click two clickables that share a visible label and require the two
+ * fired payloads to DIFFER on the id-like field. Identical values mean
+ * the component keys the action on the display value, not the element's
+ * identity — the ggui#601 class (every "09:00" cell selecting together).
+ *
+ * Emits at most one `failed` issue; every ambiguous situation returns
+ * null (covered by other checks or genuinely unjudgeable here).
+ */
+async function checkSelectionIdentity(
+  input: CheckSelectionIdentityInput,
+): Promise<RenderCheckIssue | null> {
+  const { container, probe, user, actionName, idField } = input;
+
+  const clickables = Array.from(
+    container.querySelectorAll<MinimalElement>('button, [role="button"]'),
+  );
+  const byLabel = new Map<string, MinimalElement[]>();
+  for (const el of clickables) {
+    const label = (el.textContent ?? '').replace(/\s+/g, ' ').trim();
+    if (label.length === 0) continue;
+    const group = byLabel.get(label);
+    if (group) group.push(el);
+    else byLabel.set(label, [el]);
+  }
+
+  for (const [label, group] of byLabel) {
+    if (group.length < 2) continue;
+
+    const payloadFor = async (
+      el: MinimalElement,
+    ): Promise<unknown | undefined> => {
+      const before = probe.getFireLog().length;
+      try {
+        await user.click(el);
+      } catch {
+        return undefined;
+      }
+      await flushPromises();
+      const events = probe
+        .getFireLog()
+        .slice(before)
+        .filter(
+          (e): e is ActionFiredEvent =>
+            e.kind === 'action.fired' && e.name === actionName,
+        );
+      return events.length > 0 ? events[events.length - 1]!.payload : undefined;
+    };
+
+    const first = await payloadFor(group[0]!);
+    const second = await payloadFor(group[1]!);
+    // Either click firing nothing for this action = not this check's
+    // question (wiring check owns "does it fire").
+    if (first === undefined || second === undefined) continue;
+
+    const idOf = (payload: unknown): string | undefined => {
+      if (payload === null || typeof payload !== 'object') return undefined;
+      const v = (payload as Record<string, unknown>)[idField];
+      return typeof v === 'string' ? v : undefined;
+    };
+    const firstId = idOf(first);
+    const secondId = idOf(second);
+    // Payloads missing the required field = schema territory, not ours.
+    if (firstId === undefined || secondId === undefined) continue;
+
+    if (firstId === secondId) {
+      return {
+        check: 'selection-identity',
+        outcome: 'failed',
+        subject: actionName,
+        reason:
+          `Two clickable elements share the visible label '${label}', and clicking EACH fired '${actionName}' with the same ${idField} ('${firstId}') — the action payload is keyed on the display value, not the element's identity. Distinct cells must send their own ${idField} (the contract requires it), or selecting one "${label}" acts on every "${label}".`,
+        elementHint: describeElement(group[0]!),
+      };
+    }
+    // Distinct ids on the first duplicate group — identity keying holds.
+    return null;
+  }
+  return null;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Trigger simulators — narrow set, deterministic only
 // ─────────────────────────────────────────────────────────────────────────────