@ggui-ai/ui-gen 0.16.0 → 0.18.0

package/src/evaluation/design-identity.ts

@@ -0,0 +1,96 @@
+// The design tree a judge paints with is an INPUT to the judgement and a
+// part of its identity (ggui#1042, D3): a judge-only re-judge renders every
+// arm with the tree on disk, so the row must say WHICH tree — `srcSha256`
+// over every RENDERING INPUT under the design package's `src`, sorted by
+// relative path — and the local judge path must accept the tree explicitly.
+// A served hello is compared to a judged one only when this hash and the
+// runtime's design agree (`design@judge == design@runtime`, generation-triad.md).
+//
+// Rendering inputs only: tests (`*.test.*`, `__tests__/`), stories
+// (`*.stories.*`) and docs (`*.md`) paint nothing, and a built image ships
+// the design package without them — the first rows on candidate 34 stamped
+// `e2dc89e4…` (123 files) while a checkout of the same git tree computed
+// `2cd62cb7…` (199 files). One identity must read the same on every host
+// that carries the same rendering inputs.
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface JudgeDesignIdentity {
+  /** Absolute path of the design `src` tree the judge bundled against. */
+  readonly src: string;
+  /** sha256 over every rendering input under `src` (see {@link isDesignRenderingInput}) — sorted relative path, then contents. */
+  readonly srcSha256: string;
+}
+
+/**
+ * Whether a file under the design `src` tree is something the judge PAINTS
+ * with. Tests, stories and docs are not — and a built image carries the
+ * package without them, so they must not move the identity.
+ */
+export function isDesignRenderingInput(relativePath: string): boolean {
+  const rel = relativePath.split('\\').join('/');
+  if (rel.startsWith('__tests__/') || rel.includes('/__tests__/')) return false;
+  if (/\.test\.[cm]?[jt]sx?$/.test(rel)) return false;
+  if (/\.stories\.[cm]?[jt]sx?$/.test(rel)) return false;
+  if (rel.endsWith('.md')) return false;
+  return true;
+}
+
+/** sha256 over every rendering input under `root` (sorted relative path + contents) — the identity of a design tree as it paints. */
+export function designTreeSha256(root: string): string {
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    for (const name of readdirSync(dir).sort()) {
+      const full = resolve(dir, name);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (isDesignRenderingInput(full.slice(root.length + 1))) files.push(full);
+    }
+  };
+  walk(root);
+  const h = createHash('sha256');
+  for (const f of files) {
+    h.update(f.slice(root.length + 1) + '\n');
+    h.update(readFileSync(f));
+    h.update('\n');
+  }
+  return h.digest('hex');
+}
+
+const identityCache = new Map<string, JudgeDesignIdentity | null>();
+
+/**
+ * The identity of the tree at `src`, computed once per process per path (a
+ * judge run paints hundreds of frames from one tree).
+ *
+ * `null` when the tree cannot be READ (ggui#1110): a deployed image ships the
+ * design package as built output with no `src/`, and an identity is a receipt
+ * about a judgement — never a precondition for making one. Before this,
+ * `scandir` threw ENOENT inside the evaluation round wherever the package ships
+ * built output only, the round returned no evaluation at all, and a bar refused
+ * a card that had cleared it. A row without the receipt says so; a round that cannot
+ * stamp one still runs.
+ */
+export function judgeDesignIdentity(src: string): JudgeDesignIdentity | null {
+  const key = resolve(src);
+  const cached = identityCache.get(key);
+  if (cached !== undefined) return cached;
+  let identity: JudgeDesignIdentity | null;
+  try {
+    identity = { src: key, srcSha256: designTreeSha256(key) };
+  } catch (e) {
+    // Unreadable tree: no source directory (a built package), no permission,
+    // a path that is not a directory. The reason is logged ONCE per path —
+    // the judgement proceeds unstamped rather than not at all.
+    const reason = e instanceof Error ? e.message : String(e);
+    console.warn(`[visual-eval] design tree unreadable at ${key} — the judgement carries no design identity (${reason})`);
+    identity = null;
+  }
+  identityCache.set(key, identity);
+  return identity;
+}
+
+/** Test seam: forget cached identities (a test that rewrites a tree between runs). */
+export function resetJudgeDesignIdentityCache(): void {
+  identityCache.clear();
+}

package/src/evaluation/index.ts

@@ -23,6 +23,7 @@ export type {
   EvalCategory,
   EvalResult,
   VisualEvalSummary,
+  CanvasJudgeRecord,
   CanvasVisualSummary,
   EvalCriterion,
   CriterionCoverage,
@@ -92,6 +93,16 @@ export {
   captureScreenshot,
   resolveLaunchOptions,
   runVisualEvaluation,
+  resolveDesignPackageDir,
+  runVisualEvaluationDetailed,
+  VISUAL_JUDGE_MAX_OUTPUT_TOKENS,
+  VISUAL_JUDGE_PROMPT_VERSION,
+  VISUAL_JUDGE_PROMPT_DIGEST,
+  VISUAL_EVAL_PROMPT,
+  captureScreenshotDetailed,
+  canvasFitPolicy,
+  canvasOverflowIssue,
+  CONTENT_HEIGHT_EXPRESSION,
   runVisualEval,
   summarizeVisualResult,
 } from './visual-evaluator.js';
@@ -101,7 +112,11 @@ export type {
   VisualEvalDeps,
   VisualEvalOutcome,
   VisualEvaluationResult,
+  VisualEvalDetailed,
+  ScreenshotAttempt,
   CanvasVisualResult,
+  CanvasFitPolicy,
+  CaptureMode,
   ScreenshotDeps,
   ScreenshotLauncher,
   ScreenshotBrowser,
@@ -130,3 +145,5 @@ export type {
   CanvasDisplayMode,
   CanvasDescriptor,
 } from '../design-mode.js';
+export { cssTokensForAppTheme } from './theme-css.js';
+export { designTreeSha256, judgeDesignIdentity, resetJudgeDesignIdentityCache, type JudgeDesignIdentity } from './design-identity.js';

package/src/evaluation/llm-evaluator.ts

@@ -14,6 +14,8 @@
 // Caching: Anthropic ephemeral cache, OpenAI auto-cache, Google explicit cache.
 // Same system prompt across all 7 calls → first call caches, 6 remaining hit cache.
 
+import { buildStylingProfileJudgeBlock } from '../boilerplate/styling-profile.js';
+import type { GenerationProfileInput } from '../boilerplate/styling-profile.js';
 import type {
   EvalIssue,
   EvalResult,
@@ -75,6 +77,8 @@ export interface LLMEvalContext {
    * means `constrained` (byte-identical to the pre-`designMode` prompt).
    */
   designMode?: DesignMode;
+  /** The app's generation profile (#991) — the judge reads the same text the coder was given. */
+  profile?: GenerationProfileInput;
 }
 
 export interface LLMEvalConfig {
@@ -119,6 +123,8 @@ export interface EvalContext {
   designSystemSummary?: string;
   /** See `LLMEvalContext.designMode`. */
   designMode?: DesignMode;
+  /** See `LLMEvalContext.profile`. */
+  profile?: GenerationProfileInput;
 }
 
 /**
@@ -129,6 +135,7 @@ export interface EvalContext {
  */
 const FREE_STYLING_RULES = `## Styling Rules (important for evaluation)
 - Color: every color must be a bare \`var(--ggui-color-*)\` token — a hardcoded #hex, rgb()/hsl() or CSS named color is a fail, and so is a literal fallback inside \`var(--ggui-*, …)\`.
+- Accent text (eyebrow, tagline, link, label) painted with a bare \`var(--ggui-color-primary-300…600)\` is a readability fail — the accent ink is \`var(--ggui-color-link)\`; a tint as text on a primary fill and a deep stop (700–900) on a light tint are fine
 - Spacing, typography, radius, shadow geometry and layout values MAY be literals (\`padding: '20px'\`, \`fontSize: 18\`, \`borderRadius: 12\`) — NEVER flag them.
 - Raw HTML elements with inline styles or \`<style>\` blocks are a first-class choice — never flag "not using the design system" or reward using it.
 - When \`@ggui-ai/design\` primitives ARE used, their enum/scale props (\`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`tone="muted"\`, \`surface="accent"\`) are valid.
@@ -136,7 +143,8 @@ const FREE_STYLING_RULES = `## Styling Rules (important for evaluation)
 
 const CONSTRAINED_STYLING_RULES = `## Design System Rules (important for evaluation)
 - Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** — each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
-- All colors must use CSS variables: \`color="var(--ggui-color-primary-600)"\` — hardcoded #hex or rgb() is a fail
+- All colors must use CSS variables: \`color="var(--ggui-color-onContainer)"\` — hardcoded #hex or rgb() is a fail
+- Accent text (eyebrow, tagline, link, label) painted with a bare \`primary-300…600\` stop is a readability fail — the accent ink is \`var(--ggui-color-link)\` (or \`tone="emphasized"\`); tints as text on a primary fill and deep stops on a light tint are fine
 - Component props that take enum/scale values — \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` — are all design system tokens and are always valid
 - One \`export default function Component\` — helper components as named functions above it are fine`;
 
@@ -323,6 +331,8 @@ ${free ? FREE_RAW_CLICK_TARGET_GAP : CONSTRAINED_RAW_CLICK_TARGET_GAP}
 - Inverted or skipped heading levels (an \`<Heading level={3}>\` rendered
   before the page's \`<Heading level={1}>\`).`);
 
+  const profileBlock = buildStylingProfileJudgeBlock(ctx.profile);
+  if (profileBlock.length > 0) parts.push(profileBlock);
   return parts.join('\n\n');
 }
 
@@ -733,6 +743,7 @@ export async function preWarmEval(
     contract: context.contract,
     designSystemSummary: context.designContext,
     designMode: context.designMode,
+    profile: context.profile,
   });
 
   return { motherPrompt, dynamicCriteria: [] };
@@ -837,6 +848,7 @@ export async function runLLMEvaluation(
     contract: context.contract,
     designSystemSummary: context.designContext,
     designMode,
+    profile: context.profile,
   });
 
   // Add line numbers to source

package/src/evaluation/theme-css.ts

@@ -0,0 +1,14 @@
+import type { AppTheme } from '@ggui-ai/protocol';
+import { composeThemeCss, getCssTokens } from '@ggui-ai/design/rendering';
+
+/**
+ * The stylesheet a visual judge renders under for an app: the app's theme
+ * composed the way the runtime composes it (`composeThemeCss`, layer `page`
+ * — one composition, never a second), so a judged canvas paints the tokens a
+ * visitor's page paints. Absent theme ⇒ the design's default tokens,
+ * byte-for-byte what the judge used before.
+ */
+export function cssTokensForAppTheme(theme: AppTheme | undefined, mode: 'light' | 'dark' = 'light'): string {
+  if (theme === undefined) return getCssTokens(mode);
+  return composeThemeCss({ layer: 'page', mode: theme.mode ?? mode, appTheme: theme });
+}

package/src/evaluation/types-public.ts

@@ -188,13 +188,43 @@ export interface EvalResult {
 }
 
 /** One canvas's visual verdict, PNG-free — see `EvalResult.visual`. */
+/**
+ * How one canvas's `score` was reached (ggui#1072): `k` vision calls on the
+ * SAME captured frame, aggregated by `rule`. Always present — `k: 1` ⇒
+ * `samples: [score]`, `sigma: 0`, `notes: [critique]` — so one shape serves
+ * a single judgement and a median of many. `samples`/`notes` carry only the
+ * calls the judge could parse (in call order); `k` stays the requested count,
+ * so a short `samples` is visible on the row rather than filled in.
+ */
+export interface CanvasJudgeRecord {
+  readonly k: number;
+  readonly rule: 'median';
+  readonly samples: number[];
+  /** Population σ of `samples` (0 when one sample). */
+  readonly sigma: number;
+  /** The judge's per-canvas critique per sample — the words beside a swing. */
+  readonly notes: string[];
+}
+
 export interface CanvasVisualSummary {
   canvas: CanvasClass;
   viewport: { width: number; height: number };
   /** The judge's weighted score at this canvas (0-100). */
   score: number;
-  /** `score >= passThreshold`. */
+  /** `score >= passThreshold`, and on the inline card: no overflow (ggui#1027). */
   passed: boolean;
+  /** The document's scroll height at this canvas, CSS px; `null` when unmeasurable (ggui#1027). */
+  contentHeight: number | null;
+  /** `contentHeight > viewport.height` — measured on every canvas, judged per `canvasFitPolicy`. */
+  overflow: boolean;
+  /** How `score` was reached — always present (ggui#1072). */
+  judge: CanvasJudgeRecord;
+  /**
+   * How the judge composed the mount (ggui#1100): `'fill'` on every
+   * fullscreen canvas — the served runtime's fit, the root stretched to
+   * the frame; absent on the inline card, which keeps its natural height.
+   */
+  fit?: 'fill';
 }
 
 /** The visual leg's per-canvas summary — see `EvalResult.visual`. */
@@ -204,6 +234,10 @@ export interface VisualEvalSummary {
   /** Every canvas passed. */
   passed: boolean;
   canvases: CanvasVisualSummary[];
+  /** The design tree the judge painted with (ggui#1042): `src` + `srcSha256` — `design@judge`. */
+  design?: { readonly src: string; readonly srcSha256: string };
+  /** The mode the judge's tokens were composed in, when the caller said (ggui#1076). */
+  themeMode?: 'light' | 'dark';
 }
 
 // ─── Quality mode ──────────────────────────────────────────────────────────