@ggui-ai/ui-gen 0.23.0 → 0.25.0

package/src/evaluation/axis-checks/checks/universal.ts

@@ -585,6 +585,105 @@ function runActionLabelDropped(input: AxisCheckInput): EvalIssue[] {
   );
 }
 
+// ── universal.fixture_default_echo (ggui#1285 — the fixture echo) ────────
+// The probe and the judge render the source with fixture props, the judge's
+// critique quotes what it saw, and an eval-fix turn can write that text back
+// into the source as a default, a fallback or a placeholder. The fixture is
+// judging data, not the request; a visitor then sees it whenever the agent
+// leaves the prop out (guuey#1642: a builder's system-prompt line became a
+// hello's baked copy). Rule 3 of Data Parameterization stays true — defaults
+// come from the REQUEST — so a fixture value the request (or the contract's
+// own text) states is allowed; only a fixture-only value is the echo. WARN,
+// never fail: the copy is wrong, the card is not broken. Prose-like values
+// only (≥ MIN_ECHO_CHARS and a space), so a city name or a number is never a
+// hit.
+export const MIN_ECHO_CHARS = 12;
+function collectStrings(value: unknown, out: string[]): void {
+  if (typeof value === "string") {
+    out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) collectStrings(v, out);
+  } else if (value !== null && typeof value === "object") {
+    for (const v of Object.values(value)) collectStrings(v, out);
+  }
+}
+/** The fixture's prose-like string values the request never stated, verbatim. */
+export function fixtureOnlyStrings(input: Pick<AxisCheckInput, "fixtureProps" | "originalPrompt" | "contract">): string[] {
+  if (input.fixtureProps === undefined) return [];
+  const values: string[] = [];
+  collectStrings(input.fixtureProps, values);
+  const stated = `${input.originalPrompt}\n${input.contract === undefined ? "" : JSON.stringify(input.contract)}`;
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const v of values) {
+    const t = v.trim();
+    if (t.length < MIN_ECHO_CHARS || !t.includes(" ") || seen.has(t)) continue;
+    seen.add(t);
+    if (stated.includes(t)) continue;
+    out.push(t);
+  }
+  return out;
+}
+function runFixtureDefaultEcho(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const src = input.sourceCode;
+  const issues: EvalIssue[] = [];
+  for (const value of fixtureOnlyStrings(input)) {
+    if (!src.includes(value)) continue;
+    issues.push(
+      mkIssue(
+        "universal.fixture_default_echo",
+        `A literal in the source equals a fixture value the request never stated: "${value.length > 60 ? `${value.slice(0, 57)}…` : value}". The fixture is judging data; a visitor sees this copy whenever the agent leaves the prop out.`,
+        "Take that copy from the prop it renders and drop the literal — no default, fallback or placeholder that repeats a fixture value. A default may only carry text the request itself states.",
+        "warn",
+      ),
+    );
+  }
+  return issues;
+}
+
+// ── universal.form_submit_control (ggui#1443 — a form whose buttons cannot submit it) ──
+// The design `Button` defaults to `type="button"` (the safe default: no accidental
+// submits from secondary controls), so the control that submits a `<form onSubmit>`
+// must say `type="submit"`. A generated composer rendered its Send as a type-less
+// `Button` inside the form: clicking it did nothing, only Enter submitted, and the
+// card passed quality (#1398's dumps: 5 of 9 form cells, both arms). FAIL: a form
+// with buttons and no submitting control is a control that does not work. A form
+// without any button is not this check's claim; a form without `onSubmit` is not
+// read (nothing to submit to).
+const FORM_OPEN_RX = /<form\b[^<>]*\bonSubmit\s*=[^<>]*>/g;
+const CONTROL_TAG_RX = /<(?:Button|button|input)\b[^<>]*>/g;
+const SUBMIT_TYPE_RX = /\btype\s*=\s*(?:["']submit["']|\{\s*["']submit["']\s*\})/;
+/** Every `<form … onSubmit=…>…</form>` block in the source, verbatim (up to the first `</form>` after each opening tag). */
+export function submitForms(sourceCode: string): string[] {
+  const out: string[] = [];
+  for (const m of sourceCode.matchAll(FORM_OPEN_RX)) {
+    const start = m.index ?? 0;
+    const end = sourceCode.indexOf("</form>", start + m[0].length);
+    out.push(end === -1 ? sourceCode.slice(start) : sourceCode.slice(start, end + "</form>".length));
+  }
+  return out;
+}
+function runFormSubmitControl(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const issues: EvalIssue[] = [];
+  for (const form of submitForms(input.sourceCode)) {
+    const controls = [...form.matchAll(CONTROL_TAG_RX)].map((m) => m[0]);
+    if (controls.length === 0) continue;
+    if (controls.some((tag) => SUBMIT_TYPE_RX.test(tag))) continue;
+    const named = controls.find((tag) => /<Button\b/.test(tag)) ?? controls[0]!;
+    issues.push(
+      mkIssue(
+        "universal.form_submit_control",
+        `A <form onSubmit> renders ${controls.length} control(s) and none submits it: the design Button defaults to type="button", so clicking ${named.length > 60 ? `${named.slice(0, 57)}…` : named} does nothing — only Enter in a field submits.`,
+        'Give the control that submits this form type="submit" — a Button inside a form defaults to type="button" and never submits on click; keep type="button" on the others.',
+        "fail",
+      ),
+    );
+  }
+  return issues;
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
   {
     id: "universal.icon_name_known",
@@ -622,6 +721,18 @@ export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
     values: ALL_RENDER_VALUES,
     run: runTerminalActionUnguarded,
   },
+  {
+    id: "universal.form_submit_control",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runFormSubmitControl,
+  },
+  {
+    id: "universal.fixture_default_echo",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runFixtureDefaultEcho,
+  },
   {
     id: "universal.accent_text_ink",
     axis: "render",

package/src/evaluation/axis-checks/dispatch.ts

@@ -2,7 +2,7 @@
 // whose gate matches the classification's axis vector, and accumulates
 // issues.
 
-import type { DataContract } from "@ggui-ai/protocol";
+import type { DataContract, JsonObject } from "@ggui-ai/protocol";
 import type { Classification } from "../../classifier/index.js";
 import type { EvalIssue } from "../types-public.js";
 import { REGISTRY } from "./registry.js";
@@ -20,6 +20,8 @@ export interface RunAxisChecksInput {
   designMode?: DesignMode;
   /** The canvas the source is judged for — see `AxisCheckInput.canvas` (ggui#1117); absent = no rendering context. */
   canvas?: CanvasClass;
+  /** The props the source was rendered with — see `AxisCheckInput.fixtureProps` (ggui#1285); absent = the echo check stands down. */
+  fixtureProps?: JsonObject;
 }
 
 export function runAxisChecks(
@@ -33,6 +35,7 @@ export function runAxisChecks(
     classification,
     ...(input.designMode !== undefined ? { designMode: input.designMode } : {}),
     ...(input.canvas !== undefined ? { canvas: input.canvas } : {}),
+    ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
   };
   if (input.compiledCode === null) {
     traceAxisChecksSkipped(facts, "compiledCode null — no check ran");

package/src/evaluation/criteria/bank.ts

@@ -0,0 +1,85 @@
+/**
+ * The visual criteria bank — ggui#1436 (step 1 of the founder's visual-assessment steer).
+ *
+ * The bank is DATA, never code (#1437 authors it; #1060's bar-and-judge policy): a versioned set of
+ * criteria the judge, an instrument or a person answers off the frame, split as the founder ruled —
+ * `severity` is importance, `evaluation` the method, `status` the method's readiness (the only source
+ * of an `n/a`), `scope` where a row applies ({} = every card; {kind} / {canvas} / {preset} = one). The
+ * general rows are `criteria`; a preset's own expression is a `recipes` row carrying `scope.preset`.
+ * This module is the ONE loader: a malformed bank refuses at launch with the offending path named,
+ * never mid-run. Fields the loader does not read (`examples`, `fields`, `groups`, `seed`) are page
+ * matter and are dropped here; an additive field tomorrow does not break today's loader.
+ */
+import { z } from 'zod';
+
+/** `family.property[.facet]` — `read.contrast`, `hello.field`. */
+const CRITERION_ID = /^[a-z][a-z0-9-]*(?:\.[a-zA-Z][a-zA-Z0-9-]*)+$/;
+
+/** Where a row applies; every key named must match the card's context. */
+export const criteriaScopeSchema = z.object({
+  kind: z.string().min(1).optional(),
+  canvas: z.string().min(1).optional(),
+  preset: z.string().min(1).optional(),
+});
+
+export const bankRowSchema = z.object({
+  id: z.string().regex(CRITERION_ID, 'a criterion id is family.property[.facet], lower-case family'),
+  group: z.string().optional(),
+  scope: criteriaScopeSchema.default({}),
+  /** Importance, independent of whether anything automated checks it yet. */
+  severity: z.enum(['must', 'should']),
+  /** The method that produces the verdict. */
+  evaluation: z.enum(['instrument', 'judge', 'human']),
+  /** The method's readiness — the only source of an `n/a`. */
+  status: z.enum(['live', 'reference', 'planned', 'manual']),
+  /** The question, answerable yes/no from the frame. */
+  text: z.string().min(1),
+  /** The evidence rule: what the one-sentence evidence must name (a region or element). */
+  evidence: z.string().min(1),
+  /** The templated fix line a feedback channel may consume later; never read in v1. */
+  fix: z.string().optional(),
+});
+
+export const criteriaBankSchema = z
+  .object({
+    version: z.string().min(1),
+    applies: z
+      .object({
+        /** `["*"]` = every kind. */
+        kind: z.array(z.string().min(1)).optional(),
+        canvases: z.array(z.string().min(1)).optional(),
+      })
+      .optional(),
+    criteria: z.array(bankRowSchema).min(1),
+    recipes: z.array(bankRowSchema).optional(),
+  })
+  .superRefine((bank, ctx) => {
+    const seen = new Set<string>();
+    const check = (rows: readonly { id: string }[], key: 'criteria' | 'recipes'): void => {
+      rows.forEach((c, i) => {
+        if (seen.has(c.id)) ctx.addIssue({ code: 'custom', path: [key, i, 'id'], message: `duplicate criterion id ${c.id}` });
+        seen.add(c.id);
+      });
+    };
+    check(bank.criteria, 'criteria');
+    check(bank.recipes ?? [], 'recipes');
+  });
+
+export type CriteriaBank = z.infer<typeof criteriaBankSchema>;
+export type BankRow = z.infer<typeof bankRowSchema>;
+export type CriteriaScope = z.infer<typeof criteriaScopeSchema>;
+
+/** Every row of the bank — the general criteria, then the recipes. */
+export function bankRows(bank: CriteriaBank): readonly BankRow[] {
+  return [...bank.criteria, ...(bank.recipes ?? [])];
+}
+
+/** The one door for bank data: refuses loudly, naming the path, before anything is judged. */
+export function parseCriteriaBank(raw: unknown): CriteriaBank {
+  const parsed = criteriaBankSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `${i.path.map(String).join('.') || '<root>'}: ${i.message}`).join('; ');
+    throw new Error(`criteria bank invalid — ${issues}`);
+  }
+  return parsed.data;
+}

package/src/evaluation/criteria/context.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+import type { DataContract } from '@ggui-ai/protocol';
+import type { Classification } from '../../classifier/axes.js';
+import type { GenerationProfileInput } from '../../boilerplate/styling-profile.js';
+import type { CriteriaChroma, CriteriaContext } from '../types-public.js';
+
+/** The primary at its 500 step, as the design's tokens render it (`--ggui-color-primary-500: #rrggbb;`). */
+const PRIMARY_500 = /--ggui-color-primary-500:\s*(#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6})\s*;/;
+/** Below this max−min spread (0..1) a primary reads as achromatic — an inversion, not a hue. */
+const ACHROMATIC_SPREAD = 0.08;
+
+/** Read the theme's chroma off its tokens; `unknown` when no primary is named. */
+export function chromaOfCssTokens(cssTokens: string | undefined): CriteriaChroma {
+  const m = cssTokens?.match(PRIMARY_500);
+  if (!m) return 'unknown';
+  const hex = m[1]!.slice(1);
+  const full = hex.length === 3 ? hex.split('').map((c) => c + c).join('') : hex;
+  const channels = [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16));
+  const spread = (Math.max(...channels) - Math.min(...channels)) / 255;
+  return spread < ACHROMATIC_SPREAD ? 'achromatic' : 'chromatic';
+}
+
+export 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. */
+export type CriteriaContextInput = Omit<CriteriaContext, 'canvas'>;
+
+export function criteriaContextFor(src: CriteriaContextSources): CriteriaContextInput {
+  const v = src.classification.vector;
+  const preset = src.profile?.aesthetic?.id;
+  return {
+    hasActions: Object.keys(src.contract?.actionSpec ?? {}).length > 0,
+    riskTier: src.classification.riskTier,
+    axes: { render: v.render, state: v.state, writes: v.writes, fetch: v.fetch, layout: v.layout },
+    chroma: chromaOfCssTokens(src.cssTokens),
+    profilePresent: src.profile !== undefined,
+    shell: src.shell,
+    ...(src.kind !== undefined ? { kind: src.kind } : {}),
+    ...(preset !== undefined ? { preset } : {}),
+  };
+}

package/src/evaluation/criteria/resolve.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 { CriteriaBlock, CriteriaContext, CriteriaVerdict, CriterionVerdict } from '../types-public.js';
+import { bankRows, type BankRow, type CriteriaBank } from './bank.js';
+import { CRITERIA_SELECTOR_VERSION, type CriteriaSelectionResult } from './select.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',
+};
+
+export interface CriteriaMeasurements {
+  readonly overflow: boolean;
+  readonly contentHeight: number | null;
+  readonly viewportHeight: number;
+  readonly inkRatio: number | null;
+}
+
+type Read = { verdict: CriteriaVerdict; evidence: string };
+
+function majority(id: string, answers: readonly CriteriaAnswer[][]): Read {
+  const votes = answers.flatMap((a) => a.filter((x) => x.id === id));
+  if (votes.length === 0) return { verdict: 'n/a', evidence: '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): Read {
+  if (row.evaluation === 'judge') return majority(row.id, answers);
+  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;
+}): 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 });
+  }
+  return {
+    criteriaSetId: args.selected.criteriaSetId,
+    bankVersion: args.bank.version,
+    selectorVersion: CRITERIA_SELECTOR_VERSION,
+    context: args.context,
+    selection: args.selected.selection,
+    verdicts,
+  };
+}
+
+/** 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,15 @@ export type {
   VisualEvalDetailed,
   ScreenshotAttempt,
   CanvasVisualResult,
+  CriteriaCallTokens,
   CanvasFitPolicy,
   CaptureMode,
   ScreenshotDeps,
   ScreenshotLauncher,
   ScreenshotBrowser,
   ScreenshotPage,
+  ScreenshotClip,
+  NaturalCaptureOptions,
   ChromiumProvider,
 } from './visual-evaluator.js';
 
@@ -148,3 +163,11 @@ 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_BY_ID, buildCriteriaJudgeBlock, resolveCriteriaBlock, type CriteriaMeasurements } from './criteria/resolve.js';
+export { judgeStoredCapture, type StoredCaptureInput, type StoredCaptureOutcome, type StoredCaptureVerdict } from './visual-evaluator.js';
+