@ggui-ai/ui-gen 0.15.0 → 0.16.0

package/dist/evaluation/index.d.ts

@@ -1,10 +1,14 @@
-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 { E as EvalIssue, V as VisualEvalSummary } from '../types-public-D24JLJgl.js';
+export { A as AxisCheck, a as AxisCheckInput, C as CRITERIA, d as CanvasVisualSummary, e as CriterionCoverage, f as CriterionRunStatus, D as DEFAULT_QUALITY_CONFIG, g as EvalCategory, h as EvalCriterion, i as EvalOutcome, b as EvalResult, c as EvalTier, L as LLM_EVAL_STATIC_CRITERIA, P as Priority, Q as QualityConfig, j as QualityMode, k as buildCodingCriteriaSummary, l as criteriaFor, n as getActionableIssues, o as getCriteriaByPriority, p as getCriterionById, q as getLLMCriteria, r as isBlocked, m as matches, s as notApplicableCoverage, t as priorityForIssue } from '../types-public-D24JLJgl.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-BA5dJcg-.js';
+import { C as CanvasClass, g as CanvasViewport } from '../design-mode-BHEE7flj.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-BHEE7flj.js';
 import { A as AgentConfig, L as LLMResponse } from '../llm-router-D7fjBhtr.js';
+import { LaunchOptions } from 'puppeteer-core';
 import '@ggui-ai/protocol';
 import '../axes-CzLEMDeB.js';
 import '../types-BOvHNG7K.js';
@@ -194,6 +198,18 @@ 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
@@ -209,6 +225,101 @@ 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;
+}
+/**
+ * `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[];
+}
+/** 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 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>;
+    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.
+ */
+declare function captureScreenshot(html: string, viewport?: {
+    width: number;
+    height: number;
+}, deps?: ScreenshotDeps): Promise<Buffer | null>;
 /**
  * Send the screenshot to the configured multimodal provider through
  * the shared `LLMAgent` machinery. Routing through `createVisionAgent`
@@ -220,5 +331,34 @@ interface VisualEvalConfig {
  * Bedrock path) instead of `process.env`.
  */
 declare function callMultimodalLLM(config: VisualEvalConfig, model: string, prompt: string, screenshot: Buffer, originalPrompt: 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).
+ */
+declare function runVisualEvaluation(context: VisualEvalContext, config: VisualEvalConfig, deps?: VisualEvalDeps): Promise<VisualEvaluationResult | null>;
+/** 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>;
 
-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 { CanvasClass, CanvasViewport, type CanvasVisualResult, type ChromiumProvider, EvalIssue, type EvaluateScoreInput, EvaluationConfig, EvaluationContext, EvaluationIssue, type EvaluationLoopOptions, type EvaluationLoopResult, EvaluationResult, QualityMetadata, type ScreenshotBrowser, type ScreenshotDeps, type ScreenshotLauncher, type ScreenshotPage, type SdkMessage, type VisualEvalConfig, type VisualEvalContext, type VisualEvalDeps, type VisualEvalOutcome, VisualEvalSummary, type VisualEvaluationResult, buildFixPrompt, callMultimodalLLM, captureScreenshot, computeEvaluationScore, createEvaluationToolsServer, extractCompiledCode, extractCompiledCodeFromMessage, extractEvalResult, extractSourceCode, extractSourceCodeFromMessage, extractToolResultTexts, getEvaluatorSystemPrompt, resolveLaunchOptions, runEvaluation, runEvaluationLoop, runVisualEval, runVisualEvaluation, summarizeVisualResult };