@ggui-ai/ui-gen 0.24.0 → 0.26.0

package/src/evaluation/criteria/resolve.ts

@@ -0,0 +1,207 @@
+/**
+ * From K judge answers and the capture's measurements to one `CriteriaBlock` — ggui#1436.
+ *
+ * The judge is asked every `evaluation: judge` row (this block IS their implementation; the row's
+ * `status` is carried on the verdict as the author wrote it). An `instrument` row is answered by a
+ * measurement the capture already ran when its status is `live` and a binding exists; otherwise it
+ * reads `n/a` with the reason from `status`. A `human` row reads `n/a` for the judge. K-majority per
+ * id; a tie or an unanswered id reads `n/a` (the CTO's A2) — a `must` at `n/a` is never a pass when
+ * a gate later reads the set.
+ */
+import type { CriteriaAnswer } from '../types.js';
+import type { CriteriaAnswerCounts, CriteriaBlock, CriteriaContext, CriteriaVerdict, CriterionVerdict } from '../types-public.js';
+import type { VisionFinishReason } from '../../harness/llm-router.js';
+import { bankRows, type BankRow, type CriteriaBank } from './bank.js';
+import { CRITERIA_SELECTOR_VERSION, type CriteriaSelectionResult } from './select.js';
+import type { EdgeVerdict } from './edge.js';
+
+/** The instruments the capture runs today, by the bank ids they answer (v1 binding; a bank field may replace it). */
+export const INSTRUMENT_BY_ID: Readonly<Record<string, 'fit' | 'fill'>> = {
+  'comp.fit': 'fit',
+  'floor.fit': 'fit',
+  'finish.canvas.inhabited': 'fill',
+};
+
+/**
+ * ggui#1663 — instruments that read BESIDE a judge row, report-only: the row keeps the judge's verdict and gains the
+ * measurement as `instrument`, so the two can be compared before any verdict moves.
+ */
+export const INSTRUMENT_BESIDE_JUDGE: Readonly<Record<string, 'edge'>> = {
+  'space.edge': 'edge',
+};
+
+export interface CriteriaMeasurements {
+  readonly overflow: boolean;
+  readonly contentHeight: number | null;
+  readonly viewportHeight: number;
+  readonly inkRatio: number | null;
+  /**
+   * ggui#1663 — the edge rule on the capture's DOM: absent when this capture had no page to read (a stored frame),
+   * `null` when the probe ran and failed.
+   */
+  readonly edge?: EdgeVerdict | null;
+}
+
+function besideRead(kind: 'edge', m: CriteriaMeasurements): Read {
+  if (m.edge === undefined) return { verdict: 'n/a', evidence: 'not measured: this capture had no page to read' };
+  if (m.edge === null) return { verdict: 'n/a', evidence: 'edge probe failed on this capture' };
+  return { verdict: m.edge.verdict, evidence: m.edge.evidence };
+}
+
+type Read = { verdict: CriteriaVerdict; evidence: string };
+
+function majority(id: string, answers: readonly CriteriaAnswer[][], unansweredReason: string | undefined): Read {
+  const votes = answers.flatMap((a) => a.filter((x) => x.id === id));
+  if (votes.length === 0) return { verdict: 'n/a', evidence: unansweredReason ?? 'not answered' };
+  const counts = new Map<CriteriaVerdict, number>();
+  for (const v of votes) counts.set(v.verdict, (counts.get(v.verdict) ?? 0) + 1);
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  const top = ranked[0]!;
+  if (ranked.length > 1 && ranked[1]![1] === top[1]) return { verdict: 'n/a', evidence: 'no majority' };
+  const evidence = votes.find((v) => v.verdict === top[0])?.evidence ?? '';
+  return { verdict: top[0], evidence };
+}
+
+function instrumentRead(kind: 'fit' | 'fill', m: CriteriaMeasurements): Read {
+  if (kind === 'fit') {
+    if (m.contentHeight === null) return { verdict: 'n/a', evidence: 'content height unmeasurable' };
+    return { verdict: m.overflow ? 'fail' : 'pass', evidence: `content ${m.contentHeight}px against a ${m.viewportHeight}px box` };
+  }
+  if (m.inkRatio === null) return { verdict: 'n/a', evidence: 'capture unreadable' };
+  // Reported, never gated: no fill floor is ruled (hello-finish property 1).
+  return { verdict: 'n/a', evidence: `fill ${m.inkRatio.toFixed(3)} reported; no floor ruled` };
+}
+
+function readRow(row: BankRow, answers: readonly CriteriaAnswer[][], m: CriteriaMeasurements, unansweredReason: string | undefined): Read {
+  if (row.evaluation === 'judge') return majority(row.id, answers, unansweredReason);
+  if (row.evaluation === 'human') return { verdict: 'n/a', evidence: `reader's column (status ${row.status})` };
+  if (row.status !== 'live') return { verdict: 'n/a', evidence: `not implemented (status ${row.status})` };
+  const kind = INSTRUMENT_BY_ID[row.id];
+  return kind === undefined ? { verdict: 'n/a', evidence: 'instrument not wired (status live, no binding)' } : instrumentRead(kind, m);
+}
+
+export function resolveCriteriaBlock(args: {
+  readonly bank: CriteriaBank;
+  readonly context: CriteriaContext;
+  readonly selected: CriteriaSelectionResult;
+  readonly answers: readonly CriteriaAnswer[][];
+  readonly measurements: CriteriaMeasurements;
+  /**
+   * ggui#1127 — why a judge row has no answer, when the caller knows: a salvaged criteria answer keeps no criteria,
+   * so its rows say so instead of reading as a clean `n/a`. Absent ⇒ "not answered".
+   */
+  readonly unansweredReason?: string;
+  /** ggui#1687 — the call that answered, as it came back: its answer's counts and its stop reason. */
+  readonly call?: { readonly answer: CriteriaAnswerCounts; readonly finishReason?: VisionFinishReason };
+}): CriteriaBlock {
+  const byId = new Map<string, BankRow>(bankRows(args.bank).map((r) => [r.id, r]));
+  const verdicts: CriterionVerdict[] = [];
+  for (const s of args.selected.selection) {
+    const row = byId.get(s.id);
+    if (row === undefined) continue;
+    const read = readRow(row, args.answers, args.measurements, args.unansweredReason);
+    const beside = INSTRUMENT_BESIDE_JUDGE[row.id];
+    verdicts.push({
+      id: row.id,
+      severity: row.severity,
+      method: row.evaluation,
+      status: row.status,
+      source: s.source,
+      verdict: read.verdict,
+      evidence: read.evidence,
+      ...(beside !== undefined && row.evaluation === 'judge' ? { instrument: besideRead(beside, args.measurements) } : {}),
+    });
+  }
+  return {
+    criteriaSetId: args.selected.criteriaSetId,
+    bankVersion: args.bank.version,
+    selectorVersion: CRITERIA_SELECTOR_VERSION,
+    context: args.context,
+    selection: args.selected.selection,
+    verdicts,
+    ...(args.call !== undefined
+      ? {
+          call: {
+            answer: args.call.answer,
+            // Kept answers whose id names no row of the bank: the judge answered something nobody asked.
+            unknownIds: args.answers.flat().filter((a) => !byId.has(a.id)).length,
+            ...(args.call.finishReason !== undefined ? { finishReason: args.call.finishReason } : {}),
+          },
+        }
+      : {})
+  };
+}
+
+/** The judge's prompt block for the selected `judge` rows; empty when none is selected. */
+/** The capture the judge is handed: its canvas class and the box it was taken at (the class box, or a declared one). */
+export interface CriteriaJudgeFrame {
+  readonly canvas: CriteriaContext['canvas'];
+  readonly width: number;
+  readonly height: number;
+  /** ggui#1492 — the host whose presentation framed this canvas (e.g. "a chat widget, inline, reference theme"); absent ⇒ the judge's own stand-in. */
+  readonly hostLabel?: string;
+}
+
+/** What the block carries besides the selected rows: the frame's box, and the props the card was rendered with. */
+export interface CriteriaJudgeInputs {
+  readonly frame?: CriteriaJudgeFrame;
+  /** JSON text of the props the card was rendered with; bounded by {@link CRITERIA_PROPS_MAX_CHARS}. */
+  readonly propsJson?: string;
+}
+
+/** Bound on the props text handed to the judge beside the frame, in characters. */
+export const CRITERIA_PROPS_MAX_CHARS = 2000;
+
+/**
+ * The frame's box and how the card occupies it, named so the judge reads the capture it was handed and
+ * never guesses it: without it, phone rows described a 390×844 frame as a 768×1024 tablet, and the
+ * inline card's verdicts flipped between near-identical frames (the evidence audit on ggui#1438).
+ * The inline chat card is sized to its content by the host (the box grows and shrinks with the card; a
+ * `maxHeight` caps and scrolls), so the judge captures it at its natural height on the host's ground
+ * (ggui#1475) and composition is judged within the card's extent; every other canvas is a fixed box the
+ * card fills.
+ */
+export function criteriaFrameLine(frame: CriteriaJudgeFrame): string {
+  const box = `${frame.width}×${frame.height}`;
+  if (frame.canvas === 'xs-chat-card') {
+    const framedBy =
+      frame.hostLabel !== undefined
+        ? `inside the host's own frame (${frame.hostLabel}), on the host's ground`
+        : "inside a generic stand-in for the host's frame — the card's surface with a thin ring and rounded corners, on the page ground";
+    return `This frame is an inline chat card captured at its natural height (at most ${box}, the host's ceiling), ${framedBy}: the host sizes the card to its content and draws that frame, so judge composition and space within the card's own extent, and read the frame and the ground round it as the host's, not the card's.`;
+  }
+  return `This frame is ${box}, a fixed full-screen box the card fills${frame.hostLabel !== undefined ? ` (${frame.hostLabel})` : ''}: judge composition and space against the whole box, edge to edge.`;
+}
+
+/**
+ * The one declared input besides the frame. Rows whose evidence names props (whether a rendered string
+ * came from content or props, whether the primary action is the one the props and contract name) cannot
+ * be answered from pixels alone; every other row stays frame-only.
+ */
+function criteriaPropsSection(propsJson: string): string {
+  const text = propsJson.length > CRITERIA_PROPS_MAX_CHARS ? `${propsJson.slice(0, CRITERIA_PROPS_MAX_CHARS)}… (truncated)` : propsJson;
+  return (
+    'The one input besides the frame — the props this card was rendered with. Read them ONLY for rows whose evidence names props ' +
+    '(for example, whether a rendered string came from them); every other row is read off the frame alone:\n' +
+    `${text}\n`
+  );
+}
+
+/** The judge's prompt block for the selected `judge` rows; empty when none is selected. */
+export function buildCriteriaJudgeBlock(bank: CriteriaBank, selected: CriteriaSelectionResult, inputs: CriteriaJudgeInputs = {}): string {
+  const byId = new Map<string, BankRow>(bankRows(bank).map((r) => [r.id, r]));
+  const asked = selected.selection.map((s) => byId.get(s.id)).filter((r): r is BankRow => r !== undefined && r.evaluation === 'judge');
+  if (asked.length === 0) return '';
+  const lines = asked.map((r) => `- ${r.id} (${r.severity}): ${r.text} Evidence must name: ${r.evidence}`);
+  return (
+    '## Criteria — answer each one from the FRAME only\n' +
+    'Read these off the screenshot. Never infer them from the request, the styling profile or any direction text above.\n' +
+    (inputs.frame !== undefined ? `${criteriaFrameLine(inputs.frame)}\n` : '') +
+    (inputs.propsJson !== undefined ? criteriaPropsSection(inputs.propsJson) : '') +
+    `${lines.join('\n')}\n` +
+    'Add to your JSON a top-level "criteria" array with exactly these ids: ' +
+    '[{ "id": "<id>", "verdict": "pass" | "fail" | "n/a", "evidence": "<one sentence naming the region or element you read it from>" }]. ' +
+    'Every row here was selected as applicable to this card, so "n/a" never means "does not apply": ' +
+    'use it ONLY when this frame cannot show the criterion — it is then recorded as not evaluated.'
+  );
+}

package/src/evaluation/criteria/select.ts

@@ -0,0 +1,79 @@
+/**
+ * The selector — ggui#1436's "dynamic" layer, deterministic and recorded: a pure function of the
+ * bank and the card's context. Same context → same `criteriaSetId` → same selection, so verdicts
+ * pair across arms and replay from the record. A row the selector excludes is absent from the
+ * block (the selector's decision); a selected row the judge cannot read comes back `n/a` (the
+ * judge's answer). The two are different signals.
+ */
+import { createHash } from 'node:crypto';
+import type { CriteriaContext, CriteriaSelection } from '../types-public.js';
+import { bankRows, type BankRow, type CriteriaBank } from './bank.js';
+
+/** Bump when a selection rule changes: it is hashed into every `criteriaSetId`. */
+export const CRITERIA_SELECTOR_VERSION = 'selector@2';
+
+/** The context as one string, keys sorted at every level — what the id hashes and what the record stores. */
+export function canonicalCriteriaContext(ctx: CriteriaContext): string {
+  const sortKeys = (value: unknown): unknown =>
+    value !== null && typeof value === 'object' && !Array.isArray(value)
+      ? Object.fromEntries(
+          Object.entries(value as Record<string, unknown>)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, sortKeys(v)]),
+        )
+      : value;
+  return JSON.stringify(sortKeys(ctx));
+}
+
+/** sha256(bank version | selector version | canonical context), 16 hex — a label at this scale, not a security digest. */
+export function criteriaSetIdFor(bankVersion: string, ctx: CriteriaContext): string {
+  return createHash('sha256')
+    .update(`${bankVersion}|${CRITERIA_SELECTOR_VERSION}|${canonicalCriteriaContext(ctx)}`, 'utf8')
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/** The scope keys that hold for this context, or `null` when one fails; `[]` for an empty scope (static). */
+function matchedScope(row: BankRow, ctx: CriteriaContext): string[] | null {
+  const s = row.scope;
+  const matched: string[] = [];
+  if (s.kind !== undefined) {
+    if (ctx.kind !== s.kind) return null;
+    matched.push(`kind=${s.kind}`);
+  }
+  if (s.canvas !== undefined) {
+    if (ctx.canvas !== s.canvas) return null;
+    matched.push(`canvas=${s.canvas}`);
+  }
+  if (s.preset !== undefined) {
+    if (ctx.preset !== s.preset) return null;
+    matched.push(`preset=${s.preset}`);
+  }
+  return matched;
+}
+
+export interface CriteriaSelectionResult {
+  readonly criteriaSetId: string;
+  readonly selection: CriteriaSelection[];
+}
+
+/**
+ * Select the bank's rows for one card. The bank-level `applies` gate is read first (canvases always;
+ * kind only when the caller named one and the bank names kinds other than `*`); then each row's
+ * `scope`. An empty scope is `static`; a matched scope is `context` with the keys that matched.
+ */
+export function selectCriteria(bank: CriteriaBank, ctx: CriteriaContext): CriteriaSelectionResult {
+  const criteriaSetId = criteriaSetIdFor(bank.version, ctx);
+  const applies = bank.applies;
+  if (applies?.canvases !== undefined && !applies.canvases.includes(ctx.canvas)) return { criteriaSetId, selection: [] };
+  if (applies?.kind !== undefined && ctx.kind !== undefined && !applies.kind.includes('*') && !applies.kind.includes(ctx.kind)) {
+    return { criteriaSetId, selection: [] };
+  }
+  const selection: CriteriaSelection[] = [];
+  for (const row of bankRows(bank)) {
+    const matched = matchedScope(row, ctx);
+    if (matched === null) continue;
+    selection.push(matched.length === 0 ? { id: row.id, source: 'static', reason: 'static' } : { id: row.id, source: 'context', reason: `context: ${matched.join(', ')}` });
+  }
+  return { criteriaSetId, selection };
+}

package/src/evaluation/index.ts

@@ -26,6 +26,10 @@ export type {
   VisualEvalSummary,
   CanvasJudgeRecord,
   CanvasVisualSummary,
+  CanvasHostPresentation,
+  HostInlineFrame,
+  CanvasPresentationOutcome,
+  HostPresentationIgnoredReason,
   EvalCriterion,
   CriterionCoverage,
   CriterionRunStatus,
@@ -103,10 +107,18 @@ export {
   captureScreenshotDetailed,
   canvasFitPolicy,
   canvasOverflowIssue,
+  canvasBlankIssue,
+  JUDGE_INK_INSET_PX,
+  JUDGE_GROUND_MARGIN_PX,
   CONTENT_HEIGHT_EXPRESSION,
+  CARD_HEIGHT_EXPRESSION,
+  HOST_COLOUR_PATTERN,
+  HOST_FRAME_BOUNDS,
   runVisualEval,
   summarizeVisualResult,
 } from './visual-evaluator.js';
+export { readInkExtent, decodePng, INK_TOLERANCE } from './ink-extent.js';
+export type { InkExtent, InkUnreadable, PixelRegion, DecodedImage } from './ink-extent.js';
 export type {
   VisualEvalConfig,
   VisualEvalContext,
@@ -116,12 +128,16 @@ export type {
   VisualEvalDetailed,
   ScreenshotAttempt,
   CanvasVisualResult,
+  CriteriaCallTokens,
+  VisualLegTokens,
   CanvasFitPolicy,
   CaptureMode,
   ScreenshotDeps,
   ScreenshotLauncher,
   ScreenshotBrowser,
   ScreenshotPage,
+  ScreenshotClip,
+  NaturalCaptureOptions,
   ChromiumProvider,
 } from './visual-evaluator.js';
 
@@ -148,3 +164,14 @@ export type {
 } from '../design-mode.js';
 export { cssTokensForAppTheme } from './theme-css.js';
 export { designTreeSha256, judgeDesignIdentity, resetJudgeDesignIdentityCache, type JudgeDesignIdentity } from './design-identity.js';
+
+// ggui#1436 — the visual criteria: the bank loader (data), the selector, the resolver.
+export { bankRows, criteriaBankSchema, parseCriteriaBank, type BankRow, type CriteriaBank, type CriteriaScope } from './criteria/bank.js';
+export { CRITERIA_SELECTOR_VERSION, canonicalCriteriaContext, criteriaSetIdFor, selectCriteria, type CriteriaSelectionResult } from './criteria/select.js';
+export { chromaOfCssTokens, criteriaContextFor, type CriteriaContextInput, type CriteriaContextSources } from './criteria/context.js';
+export { INSTRUMENT_BESIDE_JUDGE, INSTRUMENT_BY_ID, buildCriteriaJudgeBlock, resolveCriteriaBlock, type CriteriaMeasurements } from './criteria/resolve.js';
+export { EDGE_TOLERANCE_PX, judgeEdges, type EdgeBlock, type EdgeOffset, type EdgeVerdict } from './criteria/edge.js';
+export { EDGE_BLOCKS_EXPRESSION, parseEdgeProbe, type EdgeProbe } from './criteria/edge-probe.js';
+export { judgeStoredCapture, type StoredCaptureInput, type StoredCaptureOutcome, type StoredCaptureVerdict } from './visual-evaluator.js';
+export { judgedFrameTokens, type JudgeSpend, type JudgedTokens } from './judge-spend.js';
+

package/src/evaluation/ink-extent.ts

@@ -0,0 +1,200 @@
+/**
+ * The ink extent of a judge screenshot (ggui#1120): how far down the frame anything was painted, read
+ * from the pixels the judge already holds. `contentHeight` is the document's scroll height, floored at
+ * the viewport by definition — it can see overflow and never under-fill, and never a blank.
+ *
+ * The reading: the region's DOMINANT colour (its most common pixel) is the ground; a pixel is ink when
+ * any channel differs from it by more than {@link INK_TOLERANCE}; `lastInkRow` is the last region row
+ * with ink and `ratio` is `(lastInkRow + 1) / region.height`. Dominant, not the corners: an opening
+ * hero band makes the top corners content, and a host panel's rounded corners expose the scrim behind
+ * it (measured on the ggui#1083 judge frames — corner sampling read a card that fills as 1.0 and a
+ * panelled page as all ink).
+ *
+ * Only the ZERO is judged (`canvas-blank`, the judge's verdict): a region with no ink is one flat
+ * colour — the tree mounted and painted nothing, the mount-path class no compile-time check can reach
+ * (ggui#1104 / #1119). Every other value is reported, never scored: the corpus does not support a
+ * dead-space threshold (#1120).
+ *
+ * A PNG reader of exactly the judge's own captures — 8-bit RGB / RGBA, non-interlaced, `node:zlib`
+ * for the IDAT stream and the five scanline filters by hand — so a published package takes no image
+ * dependency. Any other PNG reads as unmeasurable (a reason), never as blank.
+ */
+import { inflateSync } from 'node:zlib';
+
+/** A channel difference at or below this is the same colour (anti-aliasing and compositing noise). */
+export const INK_TOLERANCE = 8;
+
+export interface PixelRegion {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface InkExtent {
+  /** `(lastInkRow + 1) / region.height`, rounded to 3 places; `0` when nothing differs from the ground. */
+  readonly ratio: number;
+  /** The last region row (0-based from the region's top) carrying ink; `null` when there is none — the blank. */
+  readonly lastInkRow: number | null;
+  /** The region read, in image px. */
+  readonly region: PixelRegion;
+  /** The dominant colour the ink was read against, `[r, g, b]`. */
+  readonly ground: readonly [number, number, number];
+}
+
+/** Why a capture could not be read — reported, never mistaken for a blank. */
+export interface InkUnreadable {
+  readonly reason: string;
+}
+
+export interface DecodedImage {
+  readonly width: number;
+  readonly height: number;
+  readonly channels: 3 | 4;
+  /** Row-major, `channels` bytes per pixel, scanline filters undone. */
+  readonly pixels: Uint8Array;
+}
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const;
+
+/** The PNG subset the judge's browser writes: 8-bit RGB (colour type 2) or RGBA (6), not interlaced. */
+export function decodePng(png: Uint8Array): DecodedImage | InkUnreadable {
+  const buf = Buffer.from(png.buffer, png.byteOffset, png.byteLength);
+  if (buf.length < 8 + 25) return { reason: `not a PNG: ${buf.length} bytes` };
+  for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+    if (buf[i] !== PNG_SIGNATURE[i]) return { reason: 'not a PNG: signature mismatch' };
+  }
+  let width = 0;
+  let height = 0;
+  let channels: 3 | 4 | null = null;
+  const idat: Buffer[] = [];
+  let offset = 8;
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString('latin1', offset + 4, offset + 8);
+    const start = offset + 8;
+    if (start + length + 4 > buf.length) return { reason: `truncated PNG: ${type} chunk runs past the end` };
+    const data = buf.subarray(start, start + length);
+    if (type === 'IHDR') {
+      if (length !== 13) return { reason: `malformed IHDR: ${length} bytes` };
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      const bitDepth = data[8];
+      const colorType = data[9];
+      const interlace = data[12];
+      if (bitDepth !== 8) return { reason: `unsupported PNG: bit depth ${bitDepth}` };
+      if (interlace !== 0) return { reason: 'unsupported PNG: interlaced' };
+      if (colorType === 2) channels = 3;
+      else if (colorType === 6) channels = 4;
+      else return { reason: `unsupported PNG: colour type ${colorType}` };
+    } else if (type === 'IDAT') {
+      idat.push(data);
+    } else if (type === 'IEND') {
+      break;
+    }
+    offset = start + length + 4;
+  }
+  if (channels === null) return { reason: 'malformed PNG: no IHDR' };
+  if (width === 0 || height === 0) return { reason: `empty PNG: ${width}×${height}` };
+  if (idat.length === 0) return { reason: 'malformed PNG: no IDAT' };
+  let raw: Buffer;
+  try {
+    raw = inflateSync(Buffer.concat(idat));
+  } catch (error) {
+    return { reason: `corrupt IDAT stream: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const stride = width * channels;
+  if (raw.length !== (stride + 1) * height) {
+    return { reason: `malformed PNG: ${raw.length} raw bytes for ${width}×${height}×${channels}` };
+  }
+  const pixels = new Uint8Array(stride * height);
+  const bpp = channels;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)]!;
+    const inRow = y * (stride + 1) + 1;
+    const outRow = y * stride;
+    const prevRow = outRow - stride;
+    for (let i = 0; i < stride; i++) {
+      const x = raw[inRow + i]!;
+      const a = i >= bpp ? pixels[outRow + i - bpp]! : 0;
+      const b = y > 0 ? pixels[prevRow + i]! : 0;
+      const c = y > 0 && i >= bpp ? pixels[prevRow + i - bpp]! : 0;
+      let value: number;
+      switch (filter) {
+        case 0:
+          value = x;
+          break;
+        case 1:
+          value = x + a;
+          break;
+        case 2:
+          value = x + b;
+          break;
+        case 3:
+          value = x + ((a + b) >> 1);
+          break;
+        case 4: {
+          const p = a + b - c;
+          const pa = Math.abs(p - a);
+          const pb = Math.abs(p - b);
+          const pc = Math.abs(p - c);
+          value = x + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+          break;
+        }
+        default:
+          return { reason: `malformed PNG: scanline filter ${filter} at row ${y}` };
+      }
+      pixels[outRow + i] = value & 0xff;
+    }
+  }
+  return { width, height, channels, pixels };
+}
+
+/**
+ * The ink extent of a capture, read `insetPx` in from every edge — the judge's inset skips a host
+ * panel's gap, rounded corners and hairline ({@link JUDGE_INK_INSET_PX}); `0` reads the whole image.
+ */
+export function readInkExtent(png: Uint8Array, insetPx = 0): InkExtent | InkUnreadable {
+  const image = decodePng(png);
+  if ('reason' in image) return image;
+  const region: PixelRegion = { x: insetPx, y: insetPx, width: image.width - 2 * insetPx, height: image.height - 2 * insetPx };
+  if (insetPx < 0 || region.width <= 0 || region.height <= 0) {
+    return { reason: `an inset of ${insetPx}px leaves nothing of a ${image.width}×${image.height} image` };
+  }
+  const { channels, pixels, width } = image;
+  // The ground: the region's most common colour.
+  const counts = new Map<number, number>();
+  let ground = 0;
+  let groundCount = 0;
+  for (let y = region.y; y < region.y + region.height; y++) {
+    for (let x = region.x; x < region.x + region.width; x++) {
+      const i = (y * width + x) * channels;
+      const key = (pixels[i]! << 16) | (pixels[i + 1]! << 8) | pixels[i + 2]!;
+      const n = (counts.get(key) ?? 0) + 1;
+      counts.set(key, n);
+      if (n > groundCount) {
+        groundCount = n;
+        ground = key;
+      }
+    }
+  }
+  const gr = (ground >> 16) & 0xff;
+  const gg = (ground >> 8) & 0xff;
+  const gb = ground & 0xff;
+  let lastInkRow: number | null = null;
+  for (let y = region.y; y < region.y + region.height; y++) {
+    for (let x = region.x; x < region.x + region.width; x++) {
+      const i = (y * width + x) * channels;
+      if (
+        Math.abs(pixels[i]! - gr) > INK_TOLERANCE ||
+        Math.abs(pixels[i + 1]! - gg) > INK_TOLERANCE ||
+        Math.abs(pixels[i + 2]! - gb) > INK_TOLERANCE
+      ) {
+        lastInkRow = y - region.y;
+        break;
+      }
+    }
+  }
+  const ratio = lastInkRow === null ? 0 : Math.round(((lastInkRow + 1) / region.height) * 1000) / 1000;
+  return { ratio, lastInkRow, region, ground: [gr, gg, gb] };
+}

package/src/evaluation/judge-spend.ts

@@ -0,0 +1,48 @@
+/**
+ * ggui#1640 — one judged frame's (or one visual evaluation's) spend, summed over EVERY leg the judge reports.
+ *
+ * The judge reports its legs apart: the scoring calls' `inputTokens` / `outputTokens`, and, since ggui#1436, the
+ * report-only criteria call's `criteriaTokens`. A caller that sums only the first leg under-counts, and a dollar
+ * ceiling built on that sum stops late. {@link judgedFrameTokens} is the one sum. The two `satisfies` tables below list
+ * every `*Tokens` member of the results it reads, so a leg added to either result type fails the build here until the
+ * sum counts it.
+ */
+import type { CriteriaCallTokens, StoredCaptureVerdict, VisualEvaluationResult } from './visual-evaluator.js';
+
+/** A spend in tokens: input and output, over every leg. */
+export interface JudgeSpend {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+/** The members of `T` whose names end in `Tokens`. */
+type TokenMember<T> = { [K in keyof T]-?: K extends `${string}Tokens` ? K : never }[keyof T];
+
+/** Which leg each `*Tokens` member belongs to. A member missing here, or listed and gone, is a compile error. */
+const STORED_VERDICT_LEGS = {
+  inputTokens: 'scoring',
+  outputTokens: 'scoring',
+  criteriaTokens: 'criteria',
+} as const satisfies Record<TokenMember<StoredCaptureVerdict>, 'scoring' | 'criteria'>;
+const VISUAL_RESULT_LEGS = {
+  inputTokens: 'scoring',
+  outputTokens: 'scoring',
+  criteriaTokens: 'criteria',
+} as const satisfies Record<TokenMember<VisualEvaluationResult>, 'scoring' | 'criteria'>;
+void STORED_VERDICT_LEGS;
+void VISUAL_RESULT_LEGS;
+
+/** The legs {@link judgedFrameTokens} reads, as both result types carry them. */
+export interface JudgedTokens {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly criteriaTokens?: CriteriaCallTokens;
+}
+
+/** A judged frame's spend over every leg: the scoring calls plus the report-only criteria call, when one ran. */
+export function judgedFrameTokens(result: JudgedTokens): JudgeSpend {
+  return {
+    inputTokens: (result.inputTokens ?? 0) + (result.criteriaTokens?.inputTokens ?? 0),
+    outputTokens: (result.outputTokens ?? 0) + (result.criteriaTokens?.outputTokens ?? 0),
+  };
+}

package/src/evaluation/theme-css.ts

@@ -5,10 +5,17 @@ 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.
+ * visitor's page paints. `themeId` is the registered ladder the app's theme
+ * sits on (the runtime's base layer); an unknown id composes the default
+ * ladder. Neither given ⇒ 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 });
+export function cssTokensForAppTheme(theme: AppTheme | undefined, mode: 'light' | 'dark' = 'light', themeId?: string): string {
+  if (theme === undefined && themeId === undefined) return getCssTokens(mode);
+  return composeThemeCss({
+    layer: 'page',
+    mode: theme?.mode ?? mode,
+    ...(themeId !== undefined ? { themeId } : {}),
+    ...(theme !== undefined ? { appTheme: theme } : {}),
+  });
 }