@ggui-ai/ui-gen 0.24.0 → 0.26.0

package/src/evaluation/__fixtures__/png.ts

@@ -0,0 +1,100 @@
+/**
+ * A PNG writer for tests (ggui#1120): 8-bit RGB / RGBA, non-interlaced, one scanline filter for the
+ * whole image — the shapes the judge's browser writes, so `decodePng` is exercised on every filter it
+ * must undo. Test-only: nothing in `src` imports it.
+ */
+import { crc32, deflateSync } from 'node:zlib';
+
+export type Rgb = readonly [number, number, number];
+
+export interface PngSpec {
+  readonly width: number;
+  readonly height: number;
+  readonly channels: 3 | 4;
+  /** The colour at (x, y). */
+  readonly pixel: (x: number, y: number) => Rgb;
+  /** The scanline filter applied to every row (0 none, 1 sub, 2 up, 3 average, 4 paeth). */
+  readonly filter?: 0 | 1 | 2 | 3 | 4;
+  /** Overrides for the malformed cases. */
+  readonly bitDepth?: number;
+  readonly colorType?: number;
+  readonly interlace?: number;
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, 'latin1');
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(data, crc32(Buffer.from(type, 'latin1'))) >>> 0, 0);
+  return Buffer.concat([head, data, crc]);
+}
+
+export function encodePng(spec: PngSpec): Buffer {
+  const { width, height, channels } = spec;
+  const filter = spec.filter ?? 0;
+  const stride = width * channels;
+  const rows: number[][] = [];
+  for (let y = 0; y < height; y++) {
+    const row: number[] = [];
+    for (let x = 0; x < width; x++) {
+      const [r, g, b] = spec.pixel(x, y);
+      row.push(r, g, b);
+      if (channels === 4) row.push(255);
+    }
+    rows.push(row);
+  }
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = filter;
+    for (let i = 0; i < stride; i++) {
+      const x = rows[y]![i]!;
+      const a = i >= channels ? rows[y]![i - channels]! : 0;
+      const b = y > 0 ? rows[y - 1]![i]! : 0;
+      const c = y > 0 && i >= channels ? rows[y - 1]![i - channels]! : 0;
+      let out: number;
+      switch (filter) {
+        case 0:
+          out = x;
+          break;
+        case 1:
+          out = x - a;
+          break;
+        case 2:
+          out = x - b;
+          break;
+        case 3:
+          out = 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);
+          out = x - (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+          break;
+        }
+      }
+      raw[y * (stride + 1) + 1 + i] = out & 0xff;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = spec.bitDepth ?? 8;
+  ihdr[9] = spec.colorType ?? (channels === 4 ? 6 : 2);
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = spec.interlace ?? 0;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw)),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/** One flat colour — the blank. */
+export function flatPng(width: number, height: number, colour: Rgb, channels: 3 | 4 = 3, filter: PngSpec['filter'] = 0): Buffer {
+  return encodePng({ width, height, channels, pixel: () => colour, filter });
+}

package/src/evaluation/axis-checks/checks/state-merge.ts

@@ -108,7 +108,7 @@ function runMapKeyIsId(input: AxisCheckInput): EvalIssue[] {
       mkIssue(
         "render.map_key_is_id",
         `Array key uses index variable "${key}" — reorders and stream merges will break React reconciliation.`,
-        `Replace key={${key}} with key={item.id} (or item.symbol / whatever the entity id field is).`,
+        `Replace key={${key}} with key={item.id} — or, when the items carry no id, with the field that names each one (item.label / item.symbol / item.name).`,
       ),
     );
   }

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/cost-tracker.ts

@@ -31,15 +31,54 @@ function resolveRegistryId(model: string): ModelId | null {
   return keys.find((id) => id.endsWith(`/${undated}`)) ?? null;
 }
 
+/**
+ * ggui#1524 — the largest cache-WRITE premium any registry model states (`cacheWritePer1M / inputPer1M`), never
+ * below 1. A cost CAP errs toward over-counting, so a model that states no write rate is priced at this bound
+ * times its input rate: a write costs a premium over input wherever one is charged, and pricing it at the bare
+ * input rate would slip that premium under the cap. Derived from the registry, so it moves with it.
+ */
+export const CACHE_WRITE_PREMIUM_BOUND: number = Math.max(
+  1,
+  ...Object.values(MODEL_REGISTRY).flatMap(({ costs }) =>
+    costs.cacheWritePer1M !== undefined && costs.inputPer1M > 0 ? [costs.cacheWritePer1M / costs.inputPer1M] : [],
+  ),
+);
+
+/** Per-1K USD for each kind of token a call can spend. */
+export interface PricePer1k {
+  readonly input: number;
+  readonly output: number;
+  /** Cache reads: the model's stated rate, else its input rate — over-counts a read, the safe side for a cap. */
+  readonly cacheRead: number;
+  /** Cache writes: the model's stated rate, else its input rate × {@link CACHE_WRITE_PREMIUM_BOUND}. */
+  readonly cacheWrite: number;
+}
+
 /** Fallback when a model has no registry entry — Sonnet-class rates. */
-const FALLBACK_PER_1K = { input: 0.003, output: 0.015 };
+const FALLBACK_PER_1K: PricePer1k = {
+  input: 0.003,
+  output: 0.015,
+  cacheRead: 0.003,
+  cacheWrite: 0.003 * CACHE_WRITE_PREMIUM_BOUND,
+};
 
-/** Per-1K input/output USD for a bare wire model id. */
-export function pricePer1k(model: string): { input: number; output: number } {
+/** Per-1K USD for a bare wire model id: input, output, and the two cache kinds. */
+export function pricePer1k(model: string): PricePer1k {
   const id = resolveRegistryId(model);
   if (id === null) return FALLBACK_PER_1K;
   const { costs } = MODEL_REGISTRY[id];
-  return { input: costs.inputPer1M / 1000, output: costs.outputPer1M / 1000 };
+  return {
+    input: costs.inputPer1M / 1000,
+    output: costs.outputPer1M / 1000,
+    cacheRead: (costs.cacheReadPer1M ?? costs.inputPer1M) / 1000,
+    cacheWrite: (costs.cacheWritePer1M ?? costs.inputPer1M * CACHE_WRITE_PREMIUM_BOUND) / 1000,
+  };
+}
+
+/** ggui#1524 — the cache tokens a call spent, as its provider reported them; absent = unreported. */
+export interface CacheSpend {
+  readonly read?: number;
+  readonly write?: number;
 }
 
 export class CostTracker {
@@ -47,9 +86,18 @@ export class CostTracker {
 
   constructor(private maxBudget: number | null) {}
 
-  record(model: string, inputTokens: number, outputTokens: number): number {
+  /**
+   * Record one call. `inputTokens` is the provider's UNCACHED input; a call that read or wrote the prompt cache
+   * passes those counts in `cache` (ggui#1524), priced at the cache rates — until then a turn with a long cached
+   * prefix cost the cap almost nothing while the provider billed its reads and writes.
+   */
+  record(model: string, inputTokens: number, outputTokens: number, cache: CacheSpend = {}): number {
     const prices = pricePer1k(model);
-    const cost = (inputTokens / 1000) * prices.input + (outputTokens / 1000) * prices.output;
+    const cost =
+      (inputTokens / 1000) * prices.input +
+      (outputTokens / 1000) * prices.output +
+      ((cache.read ?? 0) / 1000) * prices.cacheRead +
+      ((cache.write ?? 0) / 1000) * prices.cacheWrite;
     this.totalCost += cost;
     return cost;
   }

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 } : {}),
+  };
+}