@ggui-ai/ui-gen 0.15.0 → 0.17.0

package/dist/evaluation/index.d.ts

@@ -1,11 +1,16 @@
-export { A as AxisCheck, a as AxisCheckInput, C as CRITERIA, d as CriterionCoverage, e as CriterionRunStatus, D as DEFAULT_QUALITY_CONFIG, f as EvalCategory, g as EvalCriterion, E as EvalIssue, h as EvalOutcome, b as EvalResult, c as EvalTier, L as LLM_EVAL_STATIC_CRITERIA, P as Priority, Q as QualityConfig, i as QualityMode, j as buildCodingCriteriaSummary, k as getActionableIssues, l as getCriteriaByPriority, n as getCriterionById, o as getLLMCriteria, p as isBlocked, m as matches, q as notApplicableCoverage, r as priorityForIssue } from '../types-public-CkNWEov9.js';
+import { C as CanvasJudgeRecord, E as EvalIssue, V as VisualEvalSummary } from '../types-public-DVSssdc-.js';
+export { A as AxisCheck, a as AxisCheckInput, d as CRITERIA, e as CanvasVisualSummary, f as CriterionCoverage, g as CriterionRunStatus, D as DEFAULT_QUALITY_CONFIG, h as EvalCategory, i as EvalCriterion, j as EvalOutcome, b as EvalResult, c as EvalTier, L as LLM_EVAL_STATIC_CRITERIA, P as Priority, Q as QualityConfig, k as QualityMode, l as buildCodingCriteriaSummary, n as criteriaFor, o as getActionableIssues, p as getCriteriaByPriority, q as getCriterionById, r as getLLMCriteria, s as isBlocked, m as matches, t as notApplicableCoverage, u as priorityForIssue } from '../types-public-DVSssdc-.js';
 import * as _anthropic_ai_claude_agent_sdk from '@anthropic-ai/claude-agent-sdk';
 import { McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
 import { EvaluationContext, EvaluationConfig, QualityMetadata, EvaluationResult, EvaluationIssue } from './types.js';
 export { DEFAULT_EVAL_MAX_ROUNDS, DimensionScores, MAX_EVAL_ROUNDS_HARD_LIMIT } from './types.js';
-export { R as RunAxisChecksInput, r as runAxisChecks } from '../dispatch-BuZfTh9r.js';
+export { R as RunAxisChecksInput, r as runAxisChecks } from '../dispatch-D2htzi9h.js';
 import { A as AgentConfig, L as LLMResponse } from '../llm-router-D7fjBhtr.js';
-import '@ggui-ai/protocol';
+import { G as GenerationProfileInput } from '../styling-profile-CxfvV48g.js';
+import { LaunchOptions } from 'puppeteer-core';
+import { C as CanvasClass, g as CanvasViewport } from '../design-mode-DLufhrNp.js';
+export { a as CANVAS_BREAKPOINTS, b as CANVAS_CLASSES, c as CANVAS_DESCRIPTORS, d as CANVAS_VIEWPORTS, e as CanvasDescriptor, f as CanvasDisplayMode, j as canvasDisplayModeForShell, k as canvasForRendering, l as canvasForViewportWidth, m as describeCanvas } from '../design-mode-DLufhrNp.js';
+import { AppTheme } from '@ggui-ai/protocol';
 import '../axes-CzLEMDeB.js';
 import '../types-BOvHNG7K.js';
 import '../llm.js';
@@ -180,6 +185,30 @@ declare function extractCompiledCode(messages: SdkMessage[]): string | undefined
  */
 declare function extractSourceCode(messages: SdkMessage[]): string | undefined;
 
+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;
+}
+/** sha256 over every rendering input under `root` (sorted relative path + contents) — the identity of a design tree as it paints. */
+declare function designTreeSha256(root: string): string;
+/**
+ * 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.
+ */
+declare function judgeDesignIdentity(src: string): JudgeDesignIdentity | null;
+/** Test seam: forget cached identities (a test that rewrites a tree between runs). */
+declare function resetJudgeDesignIdentityCache(): void;
+
 interface VisualEvalConfig {
     /** LLM provider for multimodal evaluation */
     provider: 'claude' | 'google';
@@ -194,12 +223,41 @@ interface VisualEvalConfig {
         width: number;
         height: number;
     };
+    /**
+     * Per-canvas judging — ARM-NEUTRAL (the same judge, prompt and
+     * threshold in every design mode). When set, the SAME rendered HTML
+     * shell is screenshotted once per class at `CANVAS_VIEWPORTS[class]`
+     * and judged once per class; the result carries one entry per class
+     * in `canvases`, and the single-shot fields aggregate: `finalScore` =
+     * mean of the canvas scores (rounded), `passed` = every canvas passed,
+     * `dimensions` = per-dimension means, `issues` = every canvas's issues
+     * (description prefixed `[<canvas>]`). Unset (or empty) = today's
+     * single screenshot at `viewport`; no `canvases` field on the result.
+     */
+    canvases?: readonly CanvasClass[];
     /**
      * Optional provider-routing override — see
      * `AgentConfig.routeOverride`. Threaded onto the agent this
      * evaluator constructs so its multimodal call never falls back to
      * `process.env` for credentials or model routing.
      */
+    /**
+     * Vision calls per judged canvas on the SAME captured frame, aggregated by
+     * the median (ggui#1072). Default 1 — a single judgement, byte-identical to
+     * the instrument before this option existed. K is an instrument dial: a
+     * run mixes K at its own peril.
+     */
+    judgeK?: number;
+    /** The canvases sampled `judgeK` times; default = every judged canvas when `judgeK > 1`. */
+    judgeKCanvases?: readonly CanvasClass[];
+    /**
+     * The design `src` tree the judge bundles the component against
+     * (ggui#1042): an explicit input, so a judge-only re-judge names the tree
+     * it painted with. Default: the design package beside this one.
+     */
+    designSrcDir?: string;
+    /** The mode the caller composed `cssTokens` in — a receipt on the row, never a switch (ggui#1076: judge and runtime must name the same mode). */
+    themeMode?: 'light' | 'dark';
     routeOverride?: AgentConfig['routeOverride'];
     /**
      * Provider-429-retry observer — see `AgentConfig.onRetry`.
@@ -209,6 +267,170 @@ interface VisualEvalConfig {
      */
     onRetry?: AgentConfig['onRetry'];
 }
+/** One canvas's verdict — screenshot + judge score at that class's viewport. */
+interface CanvasVisualResult {
+    canvas: CanvasClass;
+    viewport: CanvasViewport;
+    /** The judge's weighted score for this canvas (0-100). */
+    score: number;
+    /** `score >= passThreshold`. */
+    passed: boolean;
+    /** The PNG the judge saw — kept for artefact persistence + the human look. */
+    screenshotPng: Buffer;
+    /**
+     * The document's scroll height at this canvas's viewport, CSS px — what
+     * the box would have to be for nothing to be hidden (ggui#1027). `null`
+     * when the page could not be measured.
+     */
+    contentHeight: number | null;
+    /** `contentHeight > viewport.height` — a measurement; what it MEANS is {@link canvasFitPolicy}'s. */
+    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, absent on the inline card. */
+    fit?: 'fill';
+}
+/** How a canvas is captured for the judge and what an overflow means there (ggui#1027). */
+type CaptureMode = 'viewport' | 'full-page';
+interface CanvasFitPolicy {
+    /** `viewport` = the judge sees the box the user sees; `full-page` = the whole scrolled document. */
+    readonly capture: CaptureMode;
+    /** The verdict an overflow earns on this canvas. */
+    readonly overflow: 'fail' | 'warn' | 'none';
+}
+/**
+ * The inline chat card is a BOX — the bubble bounds the component and it
+ * does not scroll — so the judge captures the viewport (a 1289 px hello on
+ * a 640 px card was scored 86 from a full-page capture that showed the
+ * judge what no user sees) and an overflow is a critical layout issue that
+ * fails the canvas. A phone's first screen may scroll, so the overflow is
+ * reported as a major issue and the score stands. Pages (`md`/`lg`/`xl`)
+ * scroll by design: measured, never judged.
+ */
+declare function canvasFitPolicy(canvas: CanvasClass): CanvasFitPolicy;
+/** The deterministic fit issue — one per overflowing canvas, in the judge's issue shape so it rides the same channel. */
+declare function canvasOverflowIssue(canvas: CanvasClass, viewport: CanvasViewport, contentHeight: number, verdict: 'fail' | 'warn'): EvaluationIssue;
+/**
+ * `runVisualEvaluation`'s result. Identical to `EvaluationResult` when
+ * `config.canvases` is unset; with canvases set, `canvases` holds the
+ * per-class verdicts and the base fields aggregate them (see
+ * `VisualEvalConfig.canvases`).
+ */
+interface VisualEvaluationResult extends EvaluationResult {
+    canvases?: CanvasVisualResult[];
+    /** The design tree the judge painted with (ggui#1042) — present on every per-canvas judgement. */
+    design?: JudgeDesignIdentity;
+    /** The mode `cssTokens` were composed in, when the caller said (ggui#1076). */
+    themeMode?: 'light' | 'dark';
+}
+/** Injection points for `runVisualEvaluation` — screenshot deps plus the judge call (tests). */
+interface VisualEvalDeps extends ScreenshotDeps {
+    /** The multimodal judge call (default: `callMultimodalLLM`). */
+    judge?: typeof callMultimodalLLM;
+}
+interface VisualEvalContext {
+    /** Compiled JavaScript code (ESM with imports) */
+    compiledCode: string;
+    /** Original user prompt */
+    originalPrompt: string;
+    /** Design system CSS tokens */
+    cssTokens?: string;
+    /** The app's generation profile (#991) — judged relative to, never against. */
+    profile?: GenerationProfileInput;
+}
+/**
+ * The `@ggui-ai/design` package root — resolved by MODULE ID, never by counting
+ * directories (ggui#1110).
+ *
+ * The arithmetic this replaced (`…/'..','..','..','design'`) was correct only
+ * for the layout it was written against — `node_modules/@ggui-ai/ui-gen/dist/
+ * evaluation` → `node_modules/@ggui-ai/` + `design`. Under a deploy-flattened
+ * layout it landed one level too high, at `node_modules/design`, a path that is
+ * not the design package at all: the judge then walked a directory that does not
+ * exist, threw ENOENT inside every evaluation round on that deployment, and a
+ * bar refused cards no one could judge. `@ggui-ai/design` exports `./package.json`,
+ * so the module resolver answers correctly in every layout — scoped, flattened,
+ * hoisted — and the receipt keeps working inside the image.
+ */
+declare function resolveDesignPackageDir(): string;
+/** The page surface the capture uses — a structural subset of puppeteer's `Page`. */
+interface ScreenshotPage {
+    setContent(html: string, options: {
+        waitUntil: 'load';
+        timeout: number;
+    }): Promise<void>;
+    waitForNetworkIdle(options: {
+        idleTime: number;
+        timeout: number;
+    }): Promise<void>;
+    waitForSelector(selector: string, options: {
+        timeout: number;
+    }): Promise<unknown>;
+    /** Evaluates a JS expression in the page and returns its serialised value — the fit measurement (ggui#1027). */
+    evaluate(expression: string): Promise<unknown>;
+    screenshot(options: {
+        type: 'png';
+        fullPage: boolean;
+    }): Promise<Uint8Array>;
+}
+/** The browser surface the capture uses — a structural subset of puppeteer's `Browser`. */
+interface ScreenshotBrowser {
+    newPage(): Promise<ScreenshotPage>;
+    close(): Promise<void>;
+}
+type ScreenshotLauncher = (options: LaunchOptions) => Promise<ScreenshotBrowser>;
+/** The two members of `@sparticuz/chromium` the fallback launch path reads. */
+interface ChromiumProvider {
+    readonly args: string[];
+    executablePath(): Promise<string>;
+}
+/**
+ * Injection points for the capture — every default is the production
+ * path; tests replace them to pin branch selection without launching a
+ * browser.
+ */
+interface ScreenshotDeps {
+    /** Launches the browser (default: `puppeteer-core`'s `launch`). */
+    launch?: ScreenshotLauncher;
+    /** Environment the executable-path override is read from (default: `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Loads `@sparticuz/chromium` (default: dynamic import) — only consulted when no override is set. */
+    loadChromium?: () => Promise<ChromiumProvider>;
+    /** Post-load settle time before the screenshot, ms (default 1000). */
+    settleMs?: number;
+}
+/**
+ * Pick the browser binary. `PUPPETEER_EXECUTABLE_PATH` (a system
+ * Chromium — the bench runner image, a dev box) wins and skips the
+ * `@sparticuz/chromium` load entirely; otherwise the bundled Lambda
+ * Chromium supplies both binary and flags, as before.
+ */
+declare function resolveLaunchOptions(viewport: {
+    width: number;
+    height: number;
+}, deps?: Pick<ScreenshotDeps, 'env' | 'loadChromium'>): Promise<LaunchOptions>;
+/**
+ * Take a screenshot of the rendered component.
+ * Returns the PNG bytes, or null if no browser could be launched.
+ */
+/** Screenshot plus the reason when none could be taken — the judge's `unavailableReason`. */
+interface ScreenshotAttempt {
+    readonly png: Buffer | null;
+    readonly reason?: string;
+    /** The document's scroll height at the viewport (ggui#1027); `null` when unmeasurable. */
+    readonly contentHeight: number | null;
+}
+/** The expression the fit measurement evaluates in the page — the taller of the two scroll heights. */
+declare const CONTENT_HEIGHT_EXPRESSION = "Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0)";
+declare function captureScreenshotDetailed(html: string, viewport?: {
+    width: number;
+    height: number;
+}, deps?: ScreenshotDeps, capture?: CaptureMode): Promise<ScreenshotAttempt>;
+declare function captureScreenshot(html: string, viewport?: {
+    width: number;
+    height: number;
+}, deps?: ScreenshotDeps): Promise<Buffer | null>;
+declare const VISUAL_EVAL_PROMPT = "You are a visual quality evaluator for ggui \u2014 a platform where AI agents generate React UI components on demand.\n\n## Context\nThe screenshot shows a generated React component built from a design system with CSS variable theming. The component was created by an LLM to fulfill a user's request. Your job is to evaluate whether the generated UI achieves the user's goal AND looks professionally designed.\n\n## Scoring Dimensions (0-100 each)\n\n1. **completeness** (25%): Does the screenshot show ALL features the user requested? Are all sections, controls, data fields, and interactive elements present? Missing features or sections = major deduction. Compare against the original request carefully.\n\n2. **layout** (25%): Is the layout well-composed? Clear sections and grouping? No overlapping elements? Proper spacing between elements? Responsive-looking? Does it look like a professional app UI, not a homework project?\n\n3. **hierarchy** (25%): Clear visual hierarchy? Headings are visually distinct from body text? Primary actions (buttons) are prominent? Information grouped logically with clear section breaks? Color and size used to guide the eye?\n\n4. **aesthetics** (25%): Professional, polished appearance? Consistent color palette? Good use of whitespace \u2014 not too sparse, not too cluttered? Cards, shadows, and borders used effectively? Does it look like something a designer would approve? Would you be comfortable showing this to a client?\n\n## Scoring Guide\n- 90-100: Production-ready. Would ship to real users. Polished layout, clear hierarchy, professional aesthetics.\n- 80-89: Good quality. Minor improvements needed (slightly tight spacing, one section could be better grouped).\n- 70-79: Acceptable but generic. Works correctly but lacks design polish or visual refinement.\n- 60-69: Below standard. Noticeable problems \u2014 cramped layout, poor hierarchy, or missing sections.\n- Below 60: Broken or fundamentally incomplete. Error messages visible, blank areas, or critical features missing.\n\n## Important\n- Check the screenshot against the \"Original Request\" \u2014 does it actually deliver what was asked for?\n- Error messages like \"Render error\" or blank white space = rendering score 0\n- A component that renders but is just a wall of text with no structure should score low on layout and hierarchy\n\nList AT MOST 6 issues, most severe first, one sentence each for \"description\" and \"fix\" \u2014 a longer list is cut off and lost.\n\nRespond with ONLY a JSON object (no markdown, no explanation):\n{\n  \"completeness\": <0-100>,\n  \"layout\": <0-100>,\n  \"hierarchy\": <0-100>,\n  \"aesthetics\": <0-100>,\n  \"issues\": [\n    { \"dimension\": \"<dimension>\", \"severity\": \"<critical|major|minor>\", \"description\": \"<what's wrong>\", \"fix\": \"<specific fix>\" }\n  ],\n  \"critique\": \"<2-3 sentences: what's good, what needs improvement, does it achieve the user's goal?>\"\n}";
 /**
  * Send the screenshot to the configured multimodal provider through
  * the shared `LLMAgent` machinery. Routing through `createVisionAgent`
@@ -219,6 +441,76 @@ interface VisualEvalConfig {
  * governs credentials and model routing (including the Anthropic
  * Bedrock path) instead of `process.env`.
  */
-declare function callMultimodalLLM(config: VisualEvalConfig, model: string, prompt: string, screenshot: Buffer, originalPrompt: string): Promise<LLMResponse>;
+/**
+ * Output budget for the judge's answer. 1500 cut a board's issue list
+ * mid-array (`Expected ',' or ']' after array element`, six kanban cells
+ * on 2026-09-11) — deterministic on the content, so a same-prompt retry
+ * could never clear it. 4096 fits the bounded list the prompt now asks for
+ * with room; the salvage path covers the remainder.
+ */
+declare const VISUAL_JUDGE_MAX_OUTPUT_TOKENS = 4096;
+/**
+ * The judge instrument's name and content digest, for the record a run
+ * stamps beside every visual score. The NAME is for readers; the DIGEST
+ * is computed from the prompt text at module load, so a stamped row can
+ * never claim a prompt version it did not run — change the prompt and the
+ * digest moves with it (the pin ties the name to the bounded-list text).
+ */
+declare const VISUAL_JUDGE_PROMPT_VERSION = "v2-bounded-issues";
+declare const VISUAL_JUDGE_PROMPT_DIGEST: string;
+declare function callMultimodalLLM(config: VisualEvalConfig, model: string, prompt: string, screenshot: Buffer, originalPrompt: string, profileBlock?: string): Promise<LLMResponse>;
+/**
+ * Run visual evaluation on a compiled component.
+ *
+ * 1. Builds an HTML page with the component + sample props
+ * 2. Takes a screenshot via puppeteer (if available)
+ * 3. Sends screenshot to multimodal LLM for visual scoring
+ *
+ * Returns null if puppeteer is not available (graceful fallback).
+ */
+/**
+ * The judge's answer WITH the reason when it could not judge: `result` is
+ * null exactly when no screenshot could be taken (no browser, a launch or
+ * in-page failure) or the component could not be bundled; `unavailableReason`
+ * names why in words and `canvas` the canvas it happened at. A production
+ * caller records the reason in its receipt — a `judge_unavailable` that only
+ * says "null" cost a log dive on 2026-09-10 (puppeteer-core missing in the
+ * deploy image).
+ */
+interface VisualEvalDetailed {
+    readonly result: VisualEvaluationResult | null;
+    readonly unavailableReason?: string;
+    readonly canvas?: CanvasClass;
+}
+declare function runVisualEvaluation(context: VisualEvalContext, config: VisualEvalConfig, deps?: VisualEvalDeps): Promise<VisualEvaluationResult | null>;
+declare function runVisualEvaluationDetailed(context: VisualEvalContext, config: VisualEvalConfig, deps?: VisualEvalDeps): Promise<VisualEvalDetailed>;
+/** The per-canvas verdicts without the PNGs — what the harness stamps on `EvalResult.visual`. */
+declare function summarizeVisualResult(result: VisualEvaluationResult): VisualEvalSummary | undefined;
+
+/** What the harness's eval round consumes from the visual leg. */
+interface VisualEvalOutcome {
+    /** Tier-2 issues (empty when no browser is available). */
+    issues: EvalIssue[];
+    /**
+     * Per-canvas summary — present ONLY when `config.canvases` was set and
+     * the leg ran; the harness stamps it on `EvalResult.visual`. Absent on
+     * the single-shot path (byte-identical to the pre-canvas result).
+     */
+    summary?: VisualEvalSummary;
+}
+/**
+ * Run visual evaluation and return tier 2 EvalIssues (+ the per-canvas
+ * summary when canvases were requested).
+ */
+declare function runVisualEval(context: VisualEvalContext, config: VisualEvalConfig): Promise<VisualEvalOutcome>;
+
+/**
+ * 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.
+ */
+declare function cssTokensForAppTheme(theme: AppTheme | undefined, mode?: 'light' | 'dark'): string;
 
-export { type EvaluateScoreInput, EvaluationConfig, EvaluationContext, EvaluationIssue, type EvaluationLoopOptions, type EvaluationLoopResult, EvaluationResult, QualityMetadata, type SdkMessage, type VisualEvalConfig, buildFixPrompt, callMultimodalLLM, computeEvaluationScore, createEvaluationToolsServer, extractCompiledCode, extractCompiledCodeFromMessage, extractEvalResult, extractSourceCode, extractSourceCodeFromMessage, extractToolResultTexts, getEvaluatorSystemPrompt, runEvaluation, runEvaluationLoop };
+export { CONTENT_HEIGHT_EXPRESSION, CanvasClass, type CanvasFitPolicy, CanvasJudgeRecord, CanvasViewport, type CanvasVisualResult, type CaptureMode, type ChromiumProvider, EvalIssue, type EvaluateScoreInput, EvaluationConfig, EvaluationContext, EvaluationIssue, type EvaluationLoopOptions, type EvaluationLoopResult, EvaluationResult, type JudgeDesignIdentity, QualityMetadata, type ScreenshotAttempt, type ScreenshotBrowser, type ScreenshotDeps, type ScreenshotLauncher, type ScreenshotPage, type SdkMessage, VISUAL_EVAL_PROMPT, VISUAL_JUDGE_MAX_OUTPUT_TOKENS, VISUAL_JUDGE_PROMPT_DIGEST, VISUAL_JUDGE_PROMPT_VERSION, type VisualEvalConfig, type VisualEvalContext, type VisualEvalDeps, type VisualEvalDetailed, type VisualEvalOutcome, VisualEvalSummary, type VisualEvaluationResult, buildFixPrompt, callMultimodalLLM, canvasFitPolicy, canvasOverflowIssue, captureScreenshot, captureScreenshotDetailed, computeEvaluationScore, createEvaluationToolsServer, cssTokensForAppTheme, designTreeSha256, extractCompiledCode, extractCompiledCodeFromMessage, extractEvalResult, extractSourceCode, extractSourceCodeFromMessage, extractToolResultTexts, getEvaluatorSystemPrompt, judgeDesignIdentity, resetJudgeDesignIdentityCache, resolveDesignPackageDir, resolveLaunchOptions, runEvaluation, runEvaluationLoop, runVisualEval, runVisualEvaluation, runVisualEvaluationDetailed, summarizeVisualResult };