@ggui-ai/ui-gen 0.25.0 → 0.26.0

package/dist/visual-evaluator-C9L-o6ap.d.ts

@@ -0,0 +1,639 @@
+import { h as CriteriaContext, i as CriteriaChroma, j as CanvasJudgeRecord, k as CriteriaBlock, l as CanvasPresentationOutcome, n as CanvasHostPresentation, b as AgentConfig, L as LLMResponse, J as JudgeSalvageCounts, E as EvalIssue, o as VisualEvalSummary, p as VisualCoverage } from './types-public-B7wn4ce5.js';
+import { G as GenerationProfileInput } from './styling-profile-CxfvV48g.js';
+import { C as CriteriaBank } from './bank-Ctdp3FUA.js';
+import { DataContract, JsonObject } from '@ggui-ai/protocol';
+import { C as Classification } from './axes-CKVCzR_x.js';
+import { EvaluationIssue, EvaluationResult } from './evaluation/types.js';
+import { LaunchOptions } from 'puppeteer-core';
+import { C as CanvasClass, a as CanvasViewport } from './design-mode-DGWN_Gkm.js';
+
+/**
+ * The selector's inputs for one card — ggui#1436. Every key here is hashed into `criteriaSetId`
+ * and STORED in the block (the CTO's A1), so a stored verdict reproduces its own set from the
+ * record alone. `canvas` is added per canvas inside the judge; the rest is the harness's.
+ */
+
+/** Read the theme's chroma off its tokens; `unknown` when no primary is named. */
+declare function chromaOfCssTokens(cssTokens: string | undefined): CriteriaChroma;
+interface CriteriaContextSources {
+    readonly classification: Classification;
+    readonly contract: DataContract | undefined;
+    readonly cssTokens: string | undefined;
+    readonly profile: GenerationProfileInput | undefined;
+    readonly shell: string;
+    readonly kind?: string;
+}
+/** The context minus `canvas` — the judge fills that per canvas. */
+type CriteriaContextInput = Omit<CriteriaContext, 'canvas'>;
+declare function criteriaContextFor(src: CriteriaContextSources): CriteriaContextInput;
+
+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.
+ *
+ * A function of the TREE, not of the spelling of `root`: the relative keys
+ * are taken against the RESOLVED root, so `…/design/src`, `…/design/src/` and
+ * `…/ui-gen/../design/src` hash the same bytes. Before this the key was
+ * sliced by the unresolved root's length while each entry had already been
+ * resolved, so an un-normalised root produced a different hash for the same
+ * tree — a phantom design skew for any caller composing the path.
+ */
+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;
+
+/**
+ * `space.edge` as an instrument (#1663): the alignment rule applied to measured blocks, never to a model's estimate.
+ *
+ * The rule (docs/design/direction/visual-criteria.md, "The edge rule, measurable"): in each column of a card, the things
+ * that stack start on one edge. A block may start in only two other places — inside a box, on the box's inner edge,
+ * which everything inside the box then shares; or next to a box or a band, on the box's own outer edge or on the edge
+ * of the text inside it. Same edge means within 2 px. A card fails if any captured width fails; this function judges one
+ * width.
+ *
+ * Levels that are allowed: a hanging marker (a block with two edges, the marker's and its text's); a list inside
+ * running text (list items share an edge of their own); a table (measured at its rule, its cells not re-checked);
+ * columns side by side (each with its own edge); a centred group (one centre axis). A frame that shows only loading
+ * placeholders is not evaluated.
+ *
+ * Input is the measured block list (a DOM probe at capture produces it); output is the verdict plus every offset in
+ * px, so a near miss reads apart from a split. This module measures nothing itself. *
+ * **Validated instrument (#1663, 2026-10-02):** this file as of `cec465319` (with `7bb4da13e`) passed a fresh sealed
+ * blind draw at the registered bar (27/30, κ 0.76), stricter than the design lead's reading on its disagreements. Any
+ * later change to what this file measures or decides is a new instrument until another fresh sealed draw.
+ */
+/** The rule's tolerance: two edges within this many px are the same edge. */
+declare const EDGE_TOLERANCE_PX = 2;
+/** One block of a captured card, at one canvas width. All x in CSS px from the card's left. */
+interface EdgeBlock {
+    /** A stable label for evidence (a DOM path in production, a name in tests). */
+    readonly id: string;
+    /** A text block, a control group (measured at its first control), or a surface (a box: border or its own fill). */
+    readonly kind: 'text' | 'controls' | 'surface';
+    /**
+     * The block's edge: a text's first-character origin, a bounded control's or a surface's border box, an unbounded
+     * control's text. For a hanging marker, the marker's edge.
+     */
+    readonly edge: number;
+    /** Horizontal extent, for telling side-by-side columns apart. */
+    readonly left: number;
+    readonly right: number;
+    /** Vertical position, for finding a surface's first text. */
+    readonly top: number;
+    /** The surface this block sits inside, by id; absent at the card's own level. */
+    readonly within?: string;
+    /** A hanging marker's text edge: what stacks with the block may line up with this or with `edge`. */
+    readonly textEdge?: number;
+    /** Structure the DOM names: a list item, a table (measured at its rule), a member of a centred group. */
+    readonly role?: 'list-item' | 'table' | 'centred' | 'placeholder';
+}
+interface EdgeOffset {
+    /** The container checked: the card, or a surface's id. */
+    readonly container: string;
+    /** The block that sits off every allowed edge. */
+    readonly block: string;
+    /** Its edge, and the nearest edge the rule allowed it, in px. */
+    readonly at: number;
+    readonly nearest: number;
+    readonly offPx: number;
+    /** Why the block is off when it is not plain distance (a centred block among edge-aligned ones). */
+    readonly reason?: string;
+}
+interface EdgeVerdict {
+    readonly verdict: 'pass' | 'fail' | 'n/a';
+    /** Every block that sits off the allowed edges, with its offset; empty on a pass. */
+    readonly offsets: readonly EdgeOffset[];
+    readonly evidence: string;
+}
+/**
+ * Judge one captured width. `placeholdersOnly`: the frame shows only loading placeholders, so the row is not evaluated.
+ */
+declare function judgeEdges(measured: readonly EdgeBlock[], opts?: {
+    readonly placeholdersOnly?: boolean;
+}): EdgeVerdict;
+
+/**
+ * An issue as the visual leg CREATES it (ggui#1545 follow-up): its `origin` is required here, so a new producer, an
+ * instrument check or a judge-side parse, that forgets to say whose finding it is fails to compile instead of
+ * quietly dropping out of `visualEvaluation.actOn`'s treatment. The public `EvaluationIssue` keeps `origin` optional
+ * for stored and external data.
+ */
+type VisualIssue = EvaluationIssue & {
+    origin: 'judge' | 'instrument';
+};
+
+interface VisualEvalConfig {
+    /** LLM provider for multimodal evaluation */
+    provider: 'claude' | 'google';
+    /** Model ID (must support vision/multimodal) */
+    model?: string;
+    /** Pass threshold for visual score (0-100) */
+    passThreshold: number;
+    /** Sample props to render the component with */
+    sampleProps?: Record<string, unknown>;
+    /** Viewport dimensions for screenshot */
+    viewport?: {
+        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[];
+    /**
+     * ggui#1195 — the box a canvas is COMPOSED for and CAPTURED at when the
+     * order declared one (the chat card at the visitor's real column, not the
+     * class's 400×640). Keyed by canvas; a canvas without an entry is judged
+     * at `CANVAS_VIEWPORTS[canvas]` as before. The composer's
+     * `rendering.viewport` and this entry are ONE value written once (the
+     * seam derives it), so the judge never scores a box the mint did not
+     * target. Only read in per-canvas mode. Captured at WHOLE CSS px: the
+     * browser's device-metrics override takes integers (measured — a 383.5 px
+     * width is refused by CDP), so a fractional declared box is rounded once
+     * where it enters and the capture, the ceiling and the reported
+     * `viewport` all carry that same integer box.
+     */
+    canvasViewports?: Partial<Readonly<Record<CanvasClass, CanvasViewport>>>;
+    /**
+     * ggui#1492 — how a host presents each canvas, as data the caller supplies (a lane that knows its host). Keyed by
+     * canvas; a canvas without an entry is judged exactly as before (the generic stand-in round the inline card, the
+     * scrim under a panel). The box stays in {@link canvasViewports}. An entry this judge cannot use (a colour that is
+     * not `#rrggbb`, a number out of range, a frame on a canvas that is not the inline card) is ignored for its canvas,
+     * said once in the log, never partly applied.
+     */
+    hostPresentations?: Partial<Readonly<Record<CanvasClass, CanvasHostPresentation>>>;
+    /**
+     * 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`.
+     * Without it, a rate-limited retry inside the evaluation call
+     * happens (the agent's retry loop is unconditional) but never
+     * reaches the caller's structured log.
+     */
+    onRetry?: AgentConfig['onRetry'];
+}
+/**
+ * ggui#1436 — what the report-only criteria call spent. Kept APART from the scoring calls' `inputTokens` /
+ * `outputTokens`: those price the judgement a caller may meter, and the criteria call is a measurement beside it.
+ */
+interface CriteriaCallTokens {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** 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). */
+    /**
+     * ggui#1120 — how far down the capture anything was painted (the last inked row over the measured
+     * region's height, read against the capture's dominant colour, inside a drawn panel's chrome); `0`
+     * is the blank the judge fails, `null` an unreadable capture.
+     */
+    inkRatio: number | null;
+    judge: CanvasJudgeRecord;
+    /** How the judge composed the mount (ggui#1100): `'fill'` on every fullscreen canvas, absent on the inline card. */
+    fit?: 'fill';
+    /** ggui#1195 — `true` when the order DECLARED this canvas's box (`config.canvasViewports` carried an entry), whatever its value. */
+    declared?: true;
+    /** ggui#1436 — the typed criteria block, when a bank was configured. */
+    criteria?: CriteriaBlock;
+    /** ggui#1436 — the criteria call's own spend, when one was asked and answered; never inside the canvas's scoring tokens. */
+    criteriaTokens?: CriteriaCallTokens;
+    /** ggui#1492 — what the judge did with this canvas's host presentation (drawn, or ignored and why), when one was supplied. */
+    presentation?: CanvasPresentationOutcome;
+}
+/** How a canvas is captured for the judge and what an overflow means there (ggui#1027). */
+type CaptureMode = 'viewport' | 'full-page' | 'natural';
+interface CanvasFitPolicy {
+    /**
+     * `viewport` = the whole box; `full-page` = the whole scrolled document; `natural` (ggui#1475) = the
+     * card at its OWN height, clipped to its extent and capped at the box — the inline card a host sizes
+     * to its content, on the host's ground ({@link JUDGE_GROUND_MARGIN_PX}).
+     */
+    readonly capture: CaptureMode;
+    /** The verdict an overflow earns on this canvas. */
+    readonly overflow: 'fail' | 'warn' | 'none';
+}
+/**
+ * The inline chat card takes its NATURAL height under a ceiling (ggui#1475):
+ * an MCP Apps host sizes the inline frame to the card's content
+ * (`ui/notifications/size-changed`, auto-resize) up to its maximum, so the
+ * visitor sees the card and nothing under it. The judge captures exactly
+ * that — the card's own extent on the host's ground, capped at the box — and
+ * never the box's remainder (a fixed 640 px capture scored every hello
+ * against a void no visitor sees). The box stays the ceiling: content taller
+ * than it is a critical layout issue that fails the canvas (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). 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;
+/**
+ * How far in from a panelled page's edges the ink is read (ggui#1120): past the panel's gap, its
+ * largest rounded corner (the `round` bucket, 24 px — the scrim shows through the corner) and its
+ * 1 px hairline, so the host's chrome never counts as paint. The card's own inset is 16 px, so the
+ * band skipped inside the card is 25 px of a canvas — reported ratios are over the region.
+ */
+declare const JUDGE_INK_INSET_PX: number;
+/**
+ * The host ground round a naturally-captured inline card (ggui#1475): the card is mounted this far in
+ * from the page's edges and captured with this margin, so its edge and radius are read against the
+ * host surface — the page's scrim ground, never the card's own. The design's one gap (the panel's).
+ */
+declare const JUDGE_GROUND_MARGIN_PX: 16;
+/**
+ * The bounds a host frame must meet to be drawn (ggui#1492), exported so a lane's reader applies exactly the frames
+ * this judge draws: an entry the reader accepts and the judge ignores would be echoed as applied while never drawn.
+ */
+declare const HOST_COLOUR_PATTERN: RegExp;
+declare const HOST_FRAME_BOUNDS: {
+    readonly ringWidthPx: {
+        readonly min: 0;
+        readonly max: 8;
+    };
+    readonly ringAlpha: {
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly radiusPx: {
+        readonly min: 0;
+        readonly max: 64;
+    };
+    readonly minHeightPx: {
+        readonly min: 0;
+        readonly max: 2560;
+    };
+};
+/** 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'): VisualIssue;
+/** ggui#1120 — the deterministic blank: the capture is one flat colour, so the component mounted and painted nothing. */
+declare function canvasBlankIssue(canvas: CanvasClass, viewport: CanvasViewport): VisualIssue;
+/**
+ * `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[];
+    /**
+     * ggui#1436 — the criteria calls' spend across canvases, when any was asked and answered. `inputTokens` /
+     * `outputTokens` stay the SCORING calls' alone, so a cost read off them never includes the report-only block.
+     */
+    criteriaTokens?: CriteriaCallTokens;
+    /**
+     * ggui#1127 — salvaged judge answers across the canvases, per leg, as N of M (scoring answers; criteria calls
+     * answered). Present on every canvas run, zeros included, so a reader can tell "none salvaged" from "not counted".
+     */
+    judgeSalvage?: JudgeSalvageCounts;
+    /** 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;
+    /** ggui#1436 — a criteria bank and the card's context; the judge selects per canvas and answers report-only. */
+    criteria?: {
+        readonly bank: CriteriaBank;
+        readonly context: CriteriaContextInput;
+    };
+}
+/**
+ * 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;
+/** A screenshot's region in page px (puppeteer's `clip`). */
+interface ScreenshotClip {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** 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;
+        clip?: ScreenshotClip;
+    }): 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;
+    /** ggui#1475 — a natural capture's horizontal overflow: how many px the card's content runs past its width; absent on every other capture. */
+    readonly overflowX?: number | null;
+    /**
+     * ggui#1663 — the edge rule on this capture's DOM, read just before the screenshot (report-only); `null` when the
+     * probe failed. Absent on a failed capture.
+     */
+    readonly edge?: EdgeVerdict | 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)";
+/** The stand-in page's card height ({@link cardHeightExpression} at the stand-in's pad). */
+declare const CARD_HEIGHT_EXPRESSION: string;
+/** ggui#1492 — a natural capture's geometry: the page's pad per side, and the host's floor when it has one. */
+interface NaturalCaptureOptions {
+    readonly padPx: number;
+    readonly floorPx?: number;
+}
+declare function captureScreenshotDetailed(html: string, viewport?: {
+    width: number;
+    height: number;
+}, deps?: ScreenshotDeps, capture?: CaptureMode, natural?: NaturalCaptureOptions): 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`
+ * (rather than constructing provider SDK clients inline) is what puts
+ * this call inside the same `apiCall()` choke point as every other
+ * completion: provider 429s retry with `Retry-After` honoring, the
+ * caller's `onRetry` observer sees each retry, and `routeOverride`
+ * governs credentials and model routing (including the Anthropic
+ * Bedrock path) instead of `process.env`.
+ */
+/**
+ * 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, criteriaBlock?: 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;
+/** One stored capture to judge: the frame the judge saw at capture time, plus what the capture measured. */
+interface StoredCaptureInput {
+    readonly canvas: CanvasClass;
+    /** The capture as saved (`canvas-<class>.png`). */
+    readonly png: Buffer;
+    /** The box the capture was taken at — the class box, or the declared one. */
+    readonly viewport: CanvasViewport;
+    /** The document's scroll height the capture recorded; `null` when it did not. */
+    readonly contentHeight: number | null;
+    readonly originalPrompt: string;
+    readonly profile?: GenerationProfileInput;
+    /** ggui#1436 — the bank and the card's context; absent = today's judge, no block. */
+    readonly criteria?: {
+        readonly bank: CriteriaBank;
+        readonly context: CriteriaContextInput;
+    };
+    /** The props the capture was rendered with — handed to the criteria block for the rows whose evidence names props. */
+    readonly sampleProps?: JsonObject;
+}
+interface StoredCaptureVerdict {
+    readonly canvas: CanvasClass;
+    readonly viewport: CanvasViewport;
+    readonly score: number;
+    readonly passed: boolean;
+    readonly issues: EvaluationIssue[];
+    readonly judge: CanvasJudgeRecord;
+    readonly contentHeight: number | null;
+    readonly overflow: boolean;
+    readonly inkRatio: number | null;
+    readonly criteria?: CriteriaBlock;
+    /** The scoring calls' spend. */
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** ggui#1436 — the report-only criteria call's spend, apart from the scoring calls'; absent when none was asked or answered. */
+    readonly criteriaTokens?: CriteriaCallTokens;
+}
+type StoredCaptureOutcome = {
+    readonly kind: 'ok';
+    readonly verdict: StoredCaptureVerdict;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+/**
+ * Judge a STORED capture exactly as the per-canvas leg judges a fresh one — the same K scoring calls on the
+ * same frame, the same median, the same fit and blank verdicts, the same report-only criteria call — without
+ * rendering.
+ * This is the calibration's path (ggui#1438): the frame his eye marks is the frame the judge saw, and a
+ * re-judge costs judge tokens only. Fit reads the capture's recorded `contentHeight`; ink is read off the
+ * PNG inside the canvas's chrome, as at capture.
+ */
+declare function judgeStoredCapture(input: StoredCaptureInput, config: VisualEvalConfig, deps?: Pick<VisualEvalDeps, 'judge'>): Promise<StoredCaptureOutcome>;
+
+/**
+ * ggui#1522 — what a visual leg's judge calls spent: the scoring calls, and the report-only criteria calls apart
+ * (ggui#1436). Priced at the VISUAL agent's model, never folded into a text evaluator's or a coding turn's tokens.
+ */
+interface VisualLegTokens {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly criteria?: CriteriaCallTokens;
+}
+/** 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;
+    /**
+     * ggui#1221 — whether the judge leg ran or was skipped (with the reason
+     * `runVisualEvaluationDetailed` names). Always present: the absence of a
+     * summary used to be indistinguishable from a clean single-shot run.
+     */
+    coverage: VisualCoverage;
+    /**
+     * ggui#1522 — the leg's own spend, when its judge ran and reported tokens. The round records it in the cost
+     * tracker at the visual agent's model and carries it apart; absent on a skipped leg.
+     */
+    tokens?: VisualLegTokens;
+}
+/**
+ * Run visual evaluation and return tier 2 EvalIssues (+ the per-canvas
+ * summary when canvases were requested).
+ */
+declare function runVisualEval(context: VisualEvalContext, config: VisualEvalConfig, deps?: VisualEvalDeps): Promise<VisualEvalOutcome>;
+
+export { resolveLaunchOptions as $, type VisualEvalConfig as A, type VisualEvalContext as B, type CriteriaCallTokens as C, type VisualEvalDeps as D, type EdgeVerdict as E, type VisualEvalDetailed as F, type VisualEvalOutcome as G, HOST_COLOUR_PATTERN as H, type VisualEvaluationResult as I, JUDGE_GROUND_MARGIN_PX as J, callMultimodalLLM as K, canvasBlankIssue as L, canvasFitPolicy as M, type NaturalCaptureOptions as N, canvasOverflowIssue as O, captureScreenshot as P, captureScreenshotDetailed as Q, chromaOfCssTokens as R, type ScreenshotAttempt as S, criteriaContextFor as T, designTreeSha256 as U, type VisualLegTokens as V, judgeDesignIdentity as W, judgeEdges as X, judgeStoredCapture as Y, resetJudgeDesignIdentityCache as Z, resolveDesignPackageDir as _, type EdgeBlock as a, runVisualEval as a0, runVisualEvaluation as a1, runVisualEvaluationDetailed as a2, summarizeVisualResult as a3, CARD_HEIGHT_EXPRESSION as b, CONTENT_HEIGHT_EXPRESSION as c, type CanvasFitPolicy as d, type CanvasVisualResult as e, type CaptureMode as f, type ChromiumProvider as g, type CriteriaContextInput as h, type CriteriaContextSources as i, EDGE_TOLERANCE_PX as j, type EdgeOffset as k, HOST_FRAME_BOUNDS as l, JUDGE_INK_INSET_PX as m, type JudgeDesignIdentity as n, type ScreenshotBrowser as o, type ScreenshotClip as p, type ScreenshotDeps as q, type ScreenshotLauncher as r, type ScreenshotPage as s, type StoredCaptureInput as t, type StoredCaptureOutcome as u, type StoredCaptureVerdict as v, VISUAL_EVAL_PROMPT as w, VISUAL_JUDGE_MAX_OUTPUT_TOKENS as x, VISUAL_JUDGE_PROMPT_DIGEST as y, VISUAL_JUDGE_PROMPT_VERSION as z };

package/dist/workflows.d.ts

@@ -2,11 +2,11 @@ import { C as Classification } from './axes-CKVCzR_x.js';
 import { Workflow } from './harness/types-public.js';
 import '@ggui-ai/protocol';
 import './styling-profile-CxfvV48g.js';
-import './types-public-BJTLpzWn.js';
+import './types-public-B7wn4ce5.js';
+import './llm.js';
 import '@ggui-ai/mcp-server-core';
-import './design-mode-DLufhrNp.js';
+import './design-mode-DGWN_Gkm.js';
 import './types-Dh1s4K9j.js';
-import './llm.js';
 import './policy.js';
 
 declare const WORKFLOWS: {