@ggui-ai/ui-gen 0.25.0 → 0.26.0

package/src/evaluation/criteria/edge.ts

@@ -0,0 +1,202 @@
+/**
+ * `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. */
+export 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. */
+export 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';
+}
+
+export 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;
+}
+
+export 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;
+}
+
+const CARD = 'card';
+const same = (a: number, b: number): boolean => Math.abs(a - b) <= EDGE_TOLERANCE_PX;
+const overlaps = (a: EdgeBlock, b: EdgeBlock): boolean => a.left < b.right && b.left < a.right;
+const axis = (b: EdgeBlock): number => (b.left + b.right) / 2;
+
+/** A surface's content edge: where its first text starts (its topmost text block's edge), or undefined if it has none. */
+function contentEdge(surface: EdgeBlock, blocks: readonly EdgeBlock[]): number | undefined {
+  const texts = blocks.filter((b) => b.within === surface.id && b.kind !== 'surface' && b.role !== 'centred');
+  if (texts.length === 0) return undefined;
+  const first = texts.reduce((a, b) => (b.top < a.top ? b : a));
+  return first.textEdge ?? first.edge;
+}
+
+/** Columns among a container's direct blocks: non-surface blocks that overlap horizontally, transitively. */
+function columns(direct: readonly EdgeBlock[]): EdgeBlock[][] {
+  const all = direct.filter((b) => b.kind !== 'surface');
+  // A block that spans two columns side by side (it overlaps two blocks that do not overlap each other) belongs to
+  // their parent column, never to either (decided 2026-10-02): it must not chain them into one.
+  const bridges = (b: EdgeBlock): boolean => {
+    const under = all.filter((x) => x !== b && overlaps(x, b));
+    return under.some((x, i) => under.slice(i + 1).some((y) => !overlaps(x, y)));
+  };
+  const flow = all.filter((b) => !bridges(b));
+  const parentPool: EdgeBlock[] = all.filter((b) => bridges(b));
+  const parent = flow.map((_, i) => i);
+  const find = (i: number): number => (parent[i] === i ? i : (parent[i] = find(parent[i]!)));
+  for (let i = 0; i < flow.length; i += 1) for (let j = i + 1; j < flow.length; j += 1) if (overlaps(flow[i]!, flow[j]!)) parent[find(i)] = find(j);
+  const groups = new Map<number, EdgeBlock[]>();
+  flow.forEach((b, i) => groups.set(find(i), [...(groups.get(find(i)) ?? []), b]));
+  const cols = [...groups.values()];
+  // A surface joins the one column whose text or controls it overlaps. One that overlaps two or more columns spans
+  // them and goes to their parent, like a spanning text block; one that overlaps none stands with the other
+  // unclaimed blocks. Only flow blocks decide, so a surface never chains another surface into a column.
+  for (const s of direct.filter((b) => b.kind === 'surface')) {
+    const hit = cols.filter((c) => c.some((b) => b.kind !== 'surface' && overlaps(b, s)));
+    if (hit.length === 1) hit[0]!.push(s);
+    else parentPool.push(s);
+  }
+  // The parent's blocks and the unclaimed surfaces form columns among themselves: blocks that overlap stack.
+  const lp = parentPool.map((_, i) => i);
+  const lfind = (i: number): number => (lp[i] === i ? i : (lp[i] = lfind(lp[i]!)));
+  for (let i = 0; i < parentPool.length; i += 1) for (let j = i + 1; j < parentPool.length; j += 1) if (overlaps(parentPool[i]!, parentPool[j]!)) lp[lfind(i)] = lfind(j);
+  const lgroups = new Map<number, EdgeBlock[]>();
+  parentPool.forEach((b, i) => lgroups.set(lfind(i), [...(lgroups.get(lfind(i)) ?? []), b]));
+  cols.push(...lgroups.values());
+  return cols;
+}
+
+/** One column's check: one edge, or a stacked surface's content edge (the surface is then a ground). */
+function checkColumn(container: string, col: readonly EdgeBlock[], blocks: readonly EdgeBlock[]): EdgeOffset[] {
+  const surfaces = col.filter((b) => b.kind === 'surface');
+  const grounds = surfaces.flatMap((s) => {
+    const c = s.role === 'table' ? undefined : contentEdge(s, blocks);
+    return c === undefined ? [] : [c];
+  });
+  const flow = col.filter((b) => b.kind !== 'surface' && b.role !== 'centred' && b.role !== 'list-item');
+  const listItems = col.filter((b) => b.role === 'list-item');
+  // Every edge a flow block or a surface offers; the common edge E must sit on one of them.
+  const candidates = [...flow.flatMap((b) => [b.edge, ...(b.textEdge !== undefined ? [b.textEdge] : [])]), ...surfaces.flatMap((s) => [s.edge]), ...grounds];
+  const blockEdges = (b: EdgeBlock): number[] => [b.edge, ...(b.textEdge !== undefined ? [b.textEdge] : [])];
+  // The end edges another block of the column offers: its boxes' and its other control sets'.
+  const endEdgesBesides = (b: EdgeBlock): number[] => [...surfaces.map((s) => s.right), ...flow.filter((x) => x !== b && x.kind === 'controls').map((x) => x.right)];
+  // A column of only list items or only a centred group has no common edge to find; their own checks below still run.
+  let best: EdgeOffset[] | null = candidates.length === 0 ? [] : null;
+  for (const E of candidates) {
+    const allowed = [E, ...grounds];
+    const off: EdgeOffset[] = [];
+    for (const b of flow) {
+      if (blockEdges(b).some((x) => allowed.some((a) => same(x, a)))) continue;
+      // A control set alone on its line may END on the end edge its column's boxes or other controls share.
+      if (b.kind === 'controls' && endEdgesBesides(b).some((r) => same(b.right, r))) continue;
+      const nearest = allowed.reduce((n, a) => (Math.abs(a - b.edge) < Math.abs(n - b.edge) ? a : n));
+      off.push({ container, block: b.id, at: b.edge, nearest, offPx: Math.abs(b.edge - nearest) });
+    }
+    for (const s of surfaces) {
+      const c = s.role === 'table' ? undefined : contentEdge(s, blocks);
+      if (same(s.edge, E) || (c !== undefined && same(c, E))) continue;
+      const nearest = c !== undefined && Math.abs(c - E) < Math.abs(s.edge - E) ? c : s.edge;
+      off.push({ container, block: s.id, at: nearest, nearest: E, offPx: Math.abs(nearest - E) });
+    }
+    if (best === null || off.length < best.length || (off.length === best.length && sum(off) < sum(best))) best = off;
+    if (best.length === 0) break;
+  }
+  const offsets = best ?? [];
+  // A list inside running text: its items share an edge of their own.
+  if (listItems.length > 1) {
+    const e0 = listItems[0]!.edge;
+    for (const li of listItems.slice(1)) if (!same(li.edge, e0)) offsets.push({ container, block: li.id, at: li.edge, nearest: e0, offPx: Math.abs(li.edge - e0) });
+  }
+  // A centred group: its members share one centre axis, and it must be the whole content of its column. A column is
+  // edge-aligned or centred, never both (decided 2026-10-02).
+  const centred = col.filter((b) => b.role === 'centred');
+  // A centred group of two or more may follow a label or heading when nothing edge-aligned follows it (an empty state
+  // under its section label). One centred block among edge-aligned ones, or a column that returns to an edge after
+  // the group, fails (decided 2026-10-02).
+  const edgeAligned = col.filter((b) => b.role !== 'centred');
+  const groupTop = centred.length > 0 ? Math.min(...centred.map((c) => c.top)) : 0;
+  const groupEndsColumn = centred.length > 1 && edgeAligned.every((b) => b.top < groupTop);
+  if (centred.length > 0 && edgeAligned.some((b) => b.kind !== 'surface') && !groupEndsColumn) {
+    const E = flow[0]?.edge ?? edgeAligned[0]!.edge;
+    for (const c of centred) offsets.push({ container, block: c.id, at: c.edge, nearest: E, offPx: Math.abs(c.edge - E), reason: 'a centred block in an edge-aligned column' });
+  } else if (centred.length > 1) {
+    const a0 = axis(centred[0]!);
+    for (const c of centred.slice(1)) if (!same(axis(c), a0)) offsets.push({ container, block: c.id, at: axis(c), nearest: a0, offPx: Math.abs(axis(c) - a0) });
+  }
+  return offsets;
+}
+const sum = (o: readonly EdgeOffset[]): number => o.reduce((s, x) => s + x.offPx, 0);
+
+/**
+ * Judge one captured width. `placeholdersOnly`: the frame shows only loading placeholders, so the row is not evaluated.
+ */
+export function judgeEdges(measured: readonly EdgeBlock[], opts: { readonly placeholdersOnly?: boolean } = {}): EdgeVerdict {
+  if (opts.placeholdersOnly === true) return { verdict: 'n/a', offsets: [], evidence: 'only loading placeholders are shown; not evaluated' };
+  let blocks = measured;
+  // A placeholder (a box with nothing in it, shown while content loads) is not a block, and the rule needs two blocks to
+  // compare: with fewer than two once placeholders are set aside, the frame is not evaluated (decided 2026-10-02).
+  // The two blocks are content, text or controls: a box holds them and is not one of them for this count.
+  const kept = blocks.filter((b) => b.role !== 'placeholder');
+  const content = kept.filter((b) => b.kind !== 'surface').length;
+  if (content < 2) return { verdict: 'n/a', offsets: [], evidence: kept.length === 0 ? 'no blocks were measured' : 'fewer than two blocks once placeholders are set aside; not evaluated' };
+  blocks = kept;
+  const offsets: EdgeOffset[] = [];
+  const containers = [CARD, ...blocks.filter((b) => b.kind === 'surface' && b.role !== 'table').map((b) => b.id)];
+  for (const container of containers) {
+    const direct = blocks.filter((b) => (b.within ?? CARD) === container);
+    for (const col of columns(direct)) offsets.push(...checkColumn(container, col, blocks));
+  }
+  if (offsets.length === 0) return { verdict: 'pass', offsets, evidence: 'every column shares its edge, or sits on a stacked surface’s content edge, within 2 px' };
+  const worst = offsets.reduce((a, b) => (b.offPx > a.offPx ? b : a));
+  const lines = offsets.map((o) => `${o.block} at x${round(o.at)} is ${round(o.offPx)} px from x${round(o.nearest)} (in ${o.container}${o.reason !== undefined ? `; ${o.reason}` : ''})`);
+  return { verdict: 'fail', offsets, evidence: `${offsets.length} block(s) off the allowed edges, largest ${round(worst.offPx)} px: ${lines.join('; ')}` };
+}
+const round = (n: number): string => (Math.round(n * 10) / 10).toString();

package/src/evaluation/criteria/resolve.ts

@@ -9,9 +9,11 @@
  * a gate later reads the set.
  */
 import type { CriteriaAnswer } from '../types.js';
-import type { CriteriaBlock, CriteriaContext, CriteriaVerdict, CriterionVerdict } from '../types-public.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'>> = {
@@ -20,18 +22,37 @@ export const INSTRUMENT_BY_ID: Readonly<Record<string, 'fit' | 'fill'>> = {
   '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[][]): Read {
+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: 'not answered' };
+  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]);
@@ -51,8 +72,8 @@ function instrumentRead(kind: 'fit' | 'fill', m: CriteriaMeasurements): Read {
   return { verdict: 'n/a', evidence: `fill ${m.inkRatio.toFixed(3)} reported; no floor ruled` };
 }
 
-function readRow(row: BankRow, answers: readonly CriteriaAnswer[][], m: CriteriaMeasurements): Read {
-  if (row.evaluation === 'judge') return majority(row.id, answers);
+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];
@@ -65,14 +86,31 @@ export function resolveCriteriaBlock(args: {
   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);
-    verdicts.push({ id: row.id, severity: row.severity, method: row.evaluation, status: row.status, source: s.source, verdict: read.verdict, evidence: read.evidence });
+    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,
@@ -81,6 +119,16 @@ export function resolveCriteriaBlock(args: {
     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 } : {}),
+          },
+        }
+      : {})
   };
 }
 

package/src/evaluation/index.ts

@@ -129,6 +129,7 @@ export type {
   ScreenshotAttempt,
   CanvasVisualResult,
   CriteriaCallTokens,
+  VisualLegTokens,
   CanvasFitPolicy,
   CaptureMode,
   ScreenshotDeps,
@@ -168,6 +169,9 @@ export { designTreeSha256, judgeDesignIdentity, resetJudgeDesignIdentityCache, t
 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_BY_ID, buildCriteriaJudgeBlock, resolveCriteriaBlock, type CriteriaMeasurements } from './criteria/resolve.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/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/types-public.ts

@@ -20,6 +20,7 @@
 
 export type Priority = "P0" | "P1" | "P2";
 
+import type { VisionFinishReason } from '../harness/llm-router.js';
 import type { GenerationRuntimeProbeOutcome, GenerationRuntimeProbeStatus } from "@ggui-ai/mcp-server-core";
 import type { CanvasClass, DesignMode } from "../design-mode.js";
 
@@ -61,6 +62,11 @@ export interface EvalIssue {
   description: string;
   fix: string;
   line?: number;
+  /**
+   * The visual leg's provenance (ggui#1545): `judge` (the model's finding) or `instrument` (a deterministic
+   * measurement). Absent on every other leg's issues. `visualEvaluation.actOn` acts on `judge` only.
+   */
+  origin?: "judge" | "instrument";
 }
 
 /**
@@ -100,6 +106,23 @@ export interface ProbeHostLoad {
   readonly cores: number;
 }
 
+/**
+ * ggui#1398 — whether the controls the probe clicked showed they were
+ * working once their action was pending. Report-only: it is read by the
+ * benchmark and never counted into the probe's warnings or fed back to
+ * the coding loop.
+ */
+export interface ProbePendingAffordance {
+  /** Controls the pending phase marked pending: those whose click dispatched their action (click or submit wiring) and that were still in the page. `visible + missing.length === dispatched`. */
+  readonly dispatched: number;
+  /** Of those, how many visibly changed while pending (disabled, busy, text, or replaced). */
+  readonly visible: number;
+  /** The actions whose control did not visibly change, including one whose card threw while pending. */
+  readonly missing: readonly string[];
+  /** Actions whose control was no longer in the page when its turn came (the card replaced it, or blanked after a throw): never marked, not counted as dispatched. */
+  readonly gone: readonly string[];
+}
+
 /**
  * The engine's own fields on a probe's meta, beside the outcome a
  * generation's metadata reports: why a probe did not finish, its render
@@ -116,6 +139,11 @@ export interface RuntimeProbeMetaDetail {
   readonly hostLoad?: ProbeHostLoad;
   /** Time the check waited for a probe slot before it started, ms; present only when > 0 (ggui#1380 C2b). */
   readonly queuedMs?: number;
+  /**
+   * `ran` only: the pending-affordance walk (ggui#1398). Absent when no
+   * action walk ran, so "no data" and "0 of 0" read differently.
+   */
+  readonly pendingAffordance?: ProbePendingAffordance;
 }
 
 /**
@@ -334,6 +362,54 @@ export interface CanvasJudgeRecord {
   readonly sigma: number;
   /** The judge's per-canvas critique per sample — the words beside a swing. */
   readonly notes: string[];
+  /**
+   * ggui#1127 — the cause of each scoring sample whose answer failed to parse and was SALVAGED: its four dimensions
+   * were recovered from the closed prefix, its issues kept only as far as they closed, its critique lost. One entry
+   * per salvaged sample; absent when every sample parsed. The salvaged sample's score still counts.
+   */
+  readonly salvaged?: readonly JudgeSalvageCause[];
+  /**
+   * ggui#1127 — the criteria call's answer was salvaged. A salvage keeps no criteria, so that frame's judge rows read
+   * "not answered" with this cause rather than a clean `n/a`. Absent when the call parsed or was not asked.
+   */
+  readonly criteriaSalvaged?: JudgeSalvageCause;
+  /**
+   * ggui#1687 — the model asked for, and every model the provider said answered this canvas's calls (scoring and
+   * criteria), deduplicated. `served` is empty when no provider named one: unknown, never "the requested model".
+   */
+  readonly models?: { readonly requested: string; readonly served: readonly string[] };
+}
+
+/**
+ * ggui#1687 — what the criteria call's answer held, before resolution. A row the judge left unanswered reads `n/a`
+ * either way; this says whether the call came back empty, cut, or with entries the parser had to drop.
+ */
+export interface CriteriaAnswerCounts {
+  /** The answer carried a `criteria` array. `false`: absent or not an array, so no row was read from it. */
+  readonly array: boolean;
+  /** Entries in the array. */
+  readonly received: number;
+  /** Entries kept: an object with a string id and a verdict of pass, fail or n/a. */
+  readonly kept: number;
+  /** Entries dropped, by why. */
+  readonly dropped: { readonly notObject: number; readonly badId: number; readonly badVerdict: number };
+}
+
+/**
+ * ggui#1127 — why a judge answer that failed to parse had to be salvaged. `output-cap`: the provider reported it
+ * stopped at the output cap. `malformed`: the provider reported a normal stop, so the answer ended but did not
+ * parse. `stopped`: the provider stopped it for another reason it named (a safety stop, or one it reports as
+ * other), so it is cut, not malformed. `unknown`: the provider or route reported no stop reason. Never inferred
+ * from the answer's length.
+ */
+export type JudgeSalvageCause = "output-cap" | "malformed" | "stopped" | "unknown";
+
+/** ggui#1127 — salvaged judge answers across a canvas run, per leg, as N of M. */
+export interface JudgeSalvageCounts {
+  /** Scoring answers: `answers` = samples that parsed or were salvaged, `salvaged` = those salvaged. */
+  readonly scoring: { readonly salvaged: number; readonly answers: number };
+  /** Criteria calls: `answered` = calls that parsed or were salvaged, `salvaged` = those salvaged (criteria lost). */
+  readonly criteria: { readonly salvaged: number; readonly answered: number };
 }
 
 // ─── Visual criteria (ggui#1436) ──────────────────────────────────────────
@@ -393,6 +469,19 @@ export interface CriterionVerdict {
   source: CriteriaSource;
   verdict: CriteriaVerdict;
   evidence: string;
+  /**
+   * ggui#1663 — a measured reading beside a judge row, REPORT-ONLY: the row's `verdict` stays the judge's, so this
+   * changes no verdict, score or bar. Present only on rows an instrument answers beside the judge (`space.edge`).
+   */
+  instrument?: { verdict: CriteriaVerdict; evidence: string };
+}
+/** ggui#1687 — the criteria call as it came back: its answer's counts, ids it answered outside the bank, its stop. */
+export interface CriteriaCallRecord {
+  readonly answer: CriteriaAnswerCounts;
+  /** Kept entries whose id names no row of the bank. */
+  readonly unknownIds: number;
+  /** The provider's normalized stop reason (`length` = the output cap); absent when it reported none. */
+  readonly finishReason?: VisionFinishReason;
 }
 export interface CriteriaBlock {
   /** sha256(bank version | selector version | canonical context), 16 hex — the block's own digest. */
@@ -402,6 +491,8 @@ export interface CriteriaBlock {
   context: CriteriaContext;
   selection: CriteriaSelection[];
   verdicts: CriterionVerdict[];
+  /** ggui#1687 — the call that answered this block, when one did. Absent for a block resolved with no call. */
+  call?: CriteriaCallRecord;
 }
 /** The roll-up across canvases; a `must` at `n/a` is listed, never counted as a pass. */
 export interface CriteriaRollup {

package/src/evaluation/types.ts

@@ -1,3 +1,4 @@
+import type { CriteriaAnswerCounts } from './types-public.js';
 // packages/ui-gen/src/evaluation/types.ts
 
 /**
@@ -28,6 +29,13 @@ export interface EvaluationIssue {
   severity: 'critical' | 'major' | 'minor';
   /** Suggested fix for the agent to apply */
   fix: string;
+  /**
+   * Who produced it, on the visual leg (ggui#1545): `judge` for the model's own findings, `instrument` for a
+   * deterministic measurement (fit, overflow, blank). Absent on issues from other evaluators. The loop's
+   * `visualEvaluation.actOn` acts on `judge` findings only, so a new instrument check never joins the treatment
+   * by accident: it has to say it is a judge finding, and absence reads as "not acted on".
+   */
+  origin?: 'judge' | 'instrument';
 }
 
 /**
@@ -57,6 +65,8 @@ export interface EvaluationResult {
   outputTokens?: number;
   /** ggui#1436 — the judge's criteria answers, when the prompt asked for them; never part of the score. */
   criteriaAnswers?: CriteriaAnswer[];
+  /** ggui#1687 — what the answer's criteria array held and what the parser dropped; set whenever the answer parsed. */
+  criteriaCounts?: CriteriaAnswerCounts;
 }
 
 /**