@ggui-ai/ui-gen 0.23.0 → 0.25.0

package/src/create-ui-generator.ts

@@ -31,66 +31,97 @@
  * Callers who want a lightweight single-shot path can build it
  * themselves.
  */
-import type { SingleComponentParams } from './harness/runtime.js';
+import type { SingleComponentParams } from "./harness/runtime.js";
 import type {
   GadgetDescriptor,
   GenerationError,
   JsonObject,
   GeneratorId,
   ModelRef,
-} from '@ggui-ai/protocol';
-import { isGeneratorId, modelRefOfRoute } from '@ggui-ai/protocol';
-import type { GadgetCatalogAdapter } from '@ggui-ai/gadgets';
+  AppGenerationProfileEffort,
+} from "@ggui-ai/protocol";
+import { isGeneratorId, modelRefOfRoute } from "@ggui-ai/protocol";
+import type { GadgetCatalogAdapter } from "@ggui-ai/gadgets";
 import type {
   GenerationMetadata,
+  GenerationRuntimeProbe,
+  GenerationRuntimeProbeOutcome,
+  GenerationRuntimeProbeRepair,
   GeneratorTier,
   LlmProvider,
   UiGenerateInput,
   UiGenerateResult,
   UiGenerator,
-} from '@ggui-ai/mcp-server-core';
+} from "@ggui-ai/mcp-server-core";
 import {
   formatGeneratorSlug,
   isValidGeneratorSlug,
   parseGeneratorSlug,
-} from '@ggui-ai/mcp-server-core';
-import { createGeneratorTools } from './adapters/index.js';
-import { dispatchGeneration } from './adapters/generation-dispatch.js';
-import { generatorBuild } from './generator-build.js';
-import { hasProfile } from './boilerplate/styling-profile.js';
-import { effortDials } from './effort.js';
-import type { ProviderName } from './adapters/types.js';
-import type { GenerationResult } from './harness/result-types.js';
+} from "@ggui-ai/mcp-server-core";
+import { createGeneratorTools } from "./adapters/index.js";
+import { dispatchGeneration, type VisualEvalAgentSpec } from "./adapters/generation-dispatch.js";
+import {
+  createRuntimeRenderCheck,
+  type RuntimeRenderProbeConfig,
+} from "./harness/check/runtime-render/adapter.js";
+import { generatorBuild } from "./generator-build.js";
+import { hasProfile } from "./boilerplate/styling-profile.js";
+import { effortDials } from "./effort.js";
+import type { ProviderName } from "./adapters/types.js";
+import type { GenerationResult } from "./harness/result-types.js";
 import {
   canvasForRenderingContext,
   injectContracts,
   injectRenderingContext,
   injectVariance,
-} from './contract-context.js';
-import type { RenderingContext } from './contract-context.js';
-import type { DesignMode } from './design-mode.js';
-import { DEFAULT_DESIGN_MODE } from './design-mode.js';
-import { resolveRoute, applyRouteToEnv } from './adapters/provider-router.js';
-import type { QualityConfig } from './evaluation/types-public.js';
-import type { EvaluationConfig } from './evaluation/types.js';
-import type { AgentConfig } from './harness/llm-router.js';
+} from "./contract-context.js";
+import type { RenderingContext } from "./contract-context.js";
+import type { DesignMode } from "./design-mode.js";
+import { DEFAULT_DESIGN_MODE } from "./design-mode.js";
+import { resolveRoute, applyRouteToEnv } from "./adapters/provider-router.js";
+import type { QualityConfig, RuntimeProbeMeta, RuntimeProbeRepair } from "./evaluation/types-public.js";
+import type { EvaluationConfig } from "./evaluation/types.js";
+import type { AgentConfig } from "./harness/llm-router.js";
 
 /** The slug for the OSS default seed generator. */
-const DEFAULT_TIER: GeneratorTier = 'default';
-const DEFAULT_MODEL: ModelRef = 'anthropic/claude-haiku-4-5';
+const DEFAULT_TIER: GeneratorTier = "default";
+const DEFAULT_MODEL: ModelRef = "anthropic/claude-haiku-4-5";
 
 export interface CreateUiGeneratorOptions {
   /**
-   * Wire `DEFAULT_RUNTIME_RENDER_CHECK` into the harness's check leg.
-   * When `true`, every coding turn ends with a happy-dom runtime-render
-   * probe that catches contract-wiring bugs (missing `useAction()`,
-   * wrong stream channel name, etc.).
+   * Wire the runtime-render check into the harness's check leg — one
+   * instance per generator, built from `runtimeRenderProbe` (the default
+   * bounds when it is absent). When `true`, the runtime-render probe runs
+   * ONCE at the exit decision,
+   * after the coding turns, in an isolated subprocess: it mounts the
+   * compiled component against the contract and catches crash-class and
+   * contract-wiring bugs (a render that throws, a missing `useAction()`,
+   * a wrong stream channel name). It is never on the per-turn hot path.
+   *
+   * Without an `evaluation` config the round is observe + one repair turn
+   * (ggui#1380): a recoverable render crash buys exactly one repair turn
+   * and one re-probe, then the generation serves what it has; a probe that
+   * timed out, could not run, or had nothing to probe never blocks and
+   * never repairs. The probe's status and timing ride the result's
+   * metadata (`runtimeProbe`, `evalMs`). With an `evaluation` config the
+   * probe is the evaluation round's exit gate instead.
    *
-   * Default: `false` for OSS — keeps cold-start light. The probe pulls
-   * happy-dom + @testing-library on first use (~700-1500ms cold). Bench
-   * enables it via dispatch's own default for stricter quality gating.
+   * Default: `false` — keeps cold-start light. The probe pulls happy-dom
+   * + @testing-library on first use (~700-1500ms cold). A serving
+   * deployment that wants the probe's verdict on every card sets it.
    */
   readonly enableRuntimeRender?: boolean;
+  /**
+   * How the runtime-render probe runs its isolated worker (ggui#1380). A
+   * serving deployment sets the probe's wall-clock bound, worker heap and
+   * concurrency here; the defaults are the evaluation lane's (30 s, 512 MB,
+   * no concurrency cap). The generator builds ONE check from it and hands
+   * that instance to every generation it dispatches — the concurrency cap
+   * lives on the instance, so it bounds the workers this generator has
+   * live at once. Only read when `enableRuntimeRender` is on. Never part
+   * of the prompt or the identity.
+   */
+  readonly runtimeRenderProbe?: RuntimeRenderProbeConfig;
   /** Maximum coding attempts per generation pass. */
   readonly maxAttempts?: number;
   /** Maximum evaluation rounds. */
@@ -108,7 +139,14 @@ export interface CreateUiGeneratorOptions {
    * stylesheet to render under). Forwarded verbatim; never part of the
    * prompt or the identity. Default: none — the round runs as today.
    */
-  readonly visualEvaluation?: SingleComponentParams['visualEvaluation'];
+  readonly visualEvaluation?: SingleComponentParams["visualEvaluation"];
+  /**
+   * ggui#1250 — the in-loop VISUAL judge as its own agent (a vision provider, a model, and that
+   * provider's key when the caller resolves keys itself). Absent (default): the judge is the
+   * evaluation agent's provider, which on a lane without a vision path records the score half as
+   * skipped (#1248). Forwarded verbatim to the dispatch; never part of the prompt or the identity.
+   */
+  readonly visualEvalAgent?: VisualEvalAgentSpec;
   /** Quality config controlling eval tiers + improvement behavior. */
   readonly qualityConfig?: QualityConfig;
   /**
@@ -189,7 +227,7 @@ export interface CreateUiGeneratorOptions {
    * request. Absent (default) is a no-op — retries still happen and
    * still log via `console.warn`, just without a caller-side hook.
    */
-  readonly onRetry?: AgentConfig['onRetry'];
+  readonly onRetry?: AgentConfig["onRetry"];
   /**
    * Generation observer. Invoked once per successful `generate()` with
    * the FULL harness result — source, compiled code, token counters,
@@ -221,15 +259,15 @@ export interface CreateUiGeneratorOptions {
   readonly designMode?: DesignMode;
 }
 
-export function createUiGenerator(
-  options: CreateUiGeneratorOptions = {},
-): UiGenerator {
+export function createUiGenerator(options: CreateUiGeneratorOptions = {}): UiGenerator {
   const {
     enableRuntimeRender = false,
+    runtimeRenderProbe,
     maxAttempts,
     maxEvalRounds,
     evaluation,
     visualEvaluation,
+    visualEvalAgent,
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
@@ -237,6 +275,11 @@ export function createUiGenerator(
     onGenerated,
     designMode,
   } = options;
+  // ggui#1380 — ONE runtime-render check per generator: the instance owns
+  // the probe's concurrency cap, so it must outlive a single generation.
+  const runtimeRender = enableRuntimeRender
+    ? createRuntimeRenderCheck(runtimeRenderProbe)
+    : undefined;
 
   const identity = resolveIdentity(options);
 
@@ -273,9 +316,9 @@ export function createUiGenerator(
         });
       } catch (err) {
         return failWithoutMetadata(input, identity.slug, startedAt, {
-          code: 'PRODUCTION_FAILED',
+          code: "PRODUCTION_FAILED",
           message: err instanceof Error ? err.message : String(err),
-          details: { kind: 'route-resolution-failed' },
+          details: { kind: "route-resolution-failed" },
         });
       }
 
@@ -307,19 +350,22 @@ export function createUiGenerator(
       // flag is the only way the decision reaches `createAgent` /
       // `createVisionAgent` (which select the login client on it).
       const routeOverride =
-        route.auth === 'claude-code-login'
+        route.auth === "claude-code-login"
           ? { claudeCodeLogin: true }
           : disableEnvMutation
             ? {
                 apiKey:
-                  route.env['ANTHROPIC_API_KEY'] ??
-                  route.env['OPENAI_API_KEY'] ??
-                  route.env['GEMINI_API_KEY'] ??
-                  route.env['OPENROUTER_API_KEY'],
-                useBedrock: route.env['CLAUDE_CODE_USE_BEDROCK'] === '1',
+                  route.env["ANTHROPIC_API_KEY"] ??
+                  route.env["OPENAI_API_KEY"] ??
+                  route.env["GEMINI_API_KEY"] ??
+                  route.env["OPENROUTER_API_KEY"],
+                useBedrock: route.env["CLAUDE_CODE_USE_BEDROCK"] === "1",
               }
             : undefined;
 
+      // ggui#1459 — the named level whose dials this generation applied; set
+      // where the dials are resolved, read by both metadata arms below.
+      let effortRan: AppGenerationProfileEffort | undefined;
       try {
         const tools = createGeneratorTools({
           ...(input.contract ? { contract: input.contract } : {}),
@@ -342,11 +388,9 @@ export function createUiGenerator(
         // descriptors stay byte-identical).
         const canvas = rendering ? canvasForRenderingContext(rendering) : undefined;
         const shellType = harnessShellForRendering(rendering);
-        const promptWithVariance = injectVariance(
-          promptWithRendering,
-          input.variance,
-          { profileDeclared: hasProfile(input.profile) },
-        );
+        const promptWithVariance = injectVariance(promptWithRendering, input.variance, {
+          profileDeclared: hasProfile(input.profile),
+        });
 
         // Resolve appGadgets by precedence:
         //   1. input.appGadgets (caller pre-fetched, handler path)
@@ -359,23 +403,22 @@ export function createUiGenerator(
           input.appGadgets !== undefined
             ? input.appGadgets
             : gadgetCatalog !== undefined && input.appId !== undefined
-            ? await gadgetCatalog.list(input.appId)
-            : undefined;
+              ? await gadgetCatalog.list(input.appId)
+              : undefined;
 
-        const userPrompt = injectContracts(
-          promptWithVariance,
-          input.contract,
-          resolvedAppGadgets,
-        );
+        const userPrompt = injectContracts(promptWithVariance, input.contract, resolvedAppGadgets);
 
         // `effort` (ggui#1059): a named level's dials override the
         // deployment's options for THIS generation; absent ⇒ untouched.
         // Prompt bytes never move with it (dials only).
         const dials = effortDials(input.profile?.effort);
+        if (dials !== undefined) effortRan = input.profile?.effort;
         const effectiveMaxAttempts = dials?.maxAttempts ?? maxAttempts;
         const effectiveMaxEvalRounds = dials?.maxEvalRounds ?? maxEvalRounds;
         const effectiveEvaluation =
-          dials !== undefined && evaluation !== undefined ? { ...evaluation, maxRounds: dials.maxEvalRounds } : evaluation;
+          dials !== undefined && evaluation !== undefined
+            ? { ...evaluation, maxRounds: dials.maxEvalRounds }
+            : evaluation;
         const effectiveVisualEvaluation =
           dials !== undefined && visualEvaluation !== undefined
             ? { ...visualEvaluation, passThreshold: dials.selfEvalPassThreshold }
@@ -389,21 +432,22 @@ export function createUiGenerator(
           ...(input.contract ? { contract: input.contract } : {}),
           originalPrompt: input.request.prompt,
           ...(effectiveMaxAttempts !== undefined ? { maxAttempts: effectiveMaxAttempts } : {}),
-          ...(effectiveMaxEvalRounds !== undefined ? { maxEvalRounds: effectiveMaxEvalRounds } : {}),
+          ...(effectiveMaxEvalRounds !== undefined
+            ? { maxEvalRounds: effectiveMaxEvalRounds }
+            : {}),
           ...(effectiveEvaluation !== undefined ? { evaluation: effectiveEvaluation } : {}),
-          ...(effectiveVisualEvaluation !== undefined ? { visualEvaluation: effectiveVisualEvaluation } : {}),
-          ...(qualityConfig !== undefined ? { qualityConfig } : {}),
-          ...(resolvedAppGadgets !== undefined
-            ? { appGadgets: resolvedAppGadgets }
+          ...(effectiveVisualEvaluation !== undefined
+            ? { visualEvaluation: effectiveVisualEvaluation }
             : {}),
+          ...(qualityConfig !== undefined ? { qualityConfig } : {}),
+          ...(resolvedAppGadgets !== undefined ? { appGadgets: resolvedAppGadgets } : {}),
           // Forward the third-party wrapper `.d.ts` map the render
           // handler pre-fetched. Reaches both the code-gen prompt's
           // `Type:` lines and the coding-agent typecheck overlay via
           // `dispatchGeneration`.
-          ...(input.gadgetTypes !== undefined
-            ? { gadgetTypes: input.gadgetTypes }
-            : {}),
+          ...(input.gadgetTypes !== undefined ? { gadgetTypes: input.gadgetTypes } : {}),
           enableRuntimeRender,
+          ...(runtimeRender !== undefined ? { runtimeRender } : {}),
           ...(routeOverride !== undefined ? { routeOverride } : {}),
           ...(onRetry !== undefined ? { onRetry } : {}),
           ...(designMode !== undefined ? { designMode } : {}),
@@ -411,12 +455,16 @@ export function createUiGenerator(
           // ggui#1279 — the shell the declared rendering composes for (chat only; see harnessShellForRendering).
           ...(shellType !== undefined ? { shellType } : {}),
           ...(input.profile !== undefined ? { profile: input.profile } : {}),
+          // ggui#1250 — the named in-loop visual judge, when this generator was built with one.
+          ...(visualEvalAgent !== undefined ? { visualEvalAgent } : {}),
           // Fixture props reach the in-loop probe + visual round only (never the prompt, never identity).
           ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
         });
 
         onGenerated?.(result);
 
+        const runtimeProbe = metadataRuntimeProbe(result);
+        const evalMs = metadataEvalMs(result);
         const metadata: GenerationMetadata = {
           provider: input.llm.provider,
           generator: identity.slug,
@@ -428,6 +476,8 @@ export function createUiGenerator(
           attempts: result.turnsUsed,
           // ggui#1280 — the build that made this generation (template keys, never per-request).
           build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
+          // ggui#1459 — the level that ran; absent when none was applied.
+          ...(effortRan !== undefined ? { effort: effortRan } : {}),
           // Prompt-cache counters are provider-specific (Claude reports
           // them; others omit). Pass through truthfully — absent on the
           // adapter result stays absent here, never defaulted to 0.
@@ -437,6 +487,10 @@ export function createUiGenerator(
           ...(result.cacheCreationTokens !== undefined
             ? { cacheCreationTokens: result.cacheCreationTokens }
             : {}),
+          // ggui#1380 — the runtime probe's record and the eval rounds' wall,
+          // when the harness ran a round; absent stays absent.
+          ...(runtimeProbe !== undefined ? { runtimeProbe } : {}),
+          ...(evalMs !== undefined ? { evalMs } : {}),
         };
 
         return {
@@ -451,12 +505,12 @@ export function createUiGenerator(
         };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        const details: JsonObject = { kind: 'harness-failed' };
-        if (err instanceof Error && err.stack) details['stack'] = err.stack;
+        const details: JsonObject = { kind: "harness-failed" };
+        if (err instanceof Error && err.stack) details["stack"] = err.stack;
         return {
           ok: false,
           error: {
-            code: 'PRODUCTION_FAILED',
+            code: "PRODUCTION_FAILED",
             message,
             details,
           },
@@ -470,6 +524,8 @@ export function createUiGenerator(
             cacheHit: false,
             // ggui#1280 — a failed generation still names the build that failed.
             build: generatorBuild(designMode ?? DEFAULT_DESIGN_MODE),
+            // ggui#1459 — and the level it ran, when one was applied.
+            ...(effortRan !== undefined ? { effort: effortRan } : {}),
           },
         };
       } finally {
@@ -488,11 +544,9 @@ function resolveIdentity(opts: CreateUiGeneratorOptions): {
   tier: GeneratorTier;
   model: ModelRef;
 } {
-  const hasSlug = typeof opts.slug === 'string' && opts.slug.length > 0;
+  const hasSlug = typeof opts.slug === "string" && opts.slug.length > 0;
   if (hasSlug && opts.tier !== undefined) {
-    throw new Error(
-      'createUiGenerator: pass either { slug } or { tier } — not both.',
-    );
+    throw new Error("createUiGenerator: pass either { slug } or { tier } — not both.");
   }
   const model = opts.model ?? DEFAULT_MODEL;
   if (hasSlug) {
@@ -500,7 +554,7 @@ function resolveIdentity(opts: CreateUiGeneratorOptions): {
     const parsed = parseGeneratorSlug(slug);
     if (!parsed || !isGeneratorId(slug)) {
       throw new Error(
-        `createUiGenerator: slug ${JSON.stringify(slug)} is not a valid ui-gen-<tier> identifier.`,
+        `createUiGenerator: slug ${JSON.stringify(slug)} is not a valid ui-gen-<tier> identifier.`
       );
     }
     return { slug, tier: parsed.tier, model };
@@ -512,23 +566,80 @@ function resolveIdentity(opts: CreateUiGeneratorOptions): {
     // so a slug it returns must parse. Defensive check kept to surface
     // any future drift between the two helpers.
     throw new Error(
-      `createUiGenerator: formatted slug ${JSON.stringify(slug)} round-trips as invalid — formatGeneratorSlug/isValidGeneratorSlug drift.`,
+      `createUiGenerator: formatted slug ${JSON.stringify(slug)} round-trips as invalid — formatGeneratorSlug/isValidGeneratorSlug drift.`
     );
   }
   return { slug, tier, model };
 }
 
+/**
+ * ggui#1380 — one probe's meta, projected onto the metadata's outcome ARM BY
+ * ARM: the outcome fields (`status`, `verdict`, `failChecks`, `elapsedMs`)
+ * are copied; the engine's own detail (`reason`, `renderMs`, `hostLoad`)
+ * stays on the harness result. No cast — each arm is rebuilt as a literal of
+ * the target arm, so a field the metadata does not carry cannot ride along
+ * and a field the arm requires cannot be dropped. Absent stays absent.
+ */
+function metadataProbeOutcome(meta: RuntimeProbeMeta): GenerationRuntimeProbeOutcome {
+  const elapsed = {
+    ...(meta.elapsedMs !== undefined ? { elapsedMs: meta.elapsedMs } : {}),
+    ...(meta.queuedMs !== undefined ? { queuedMs: meta.queuedMs } : {}),
+  };
+  if (meta.status !== "ran") return { status: meta.status, ...elapsed };
+  if (meta.verdict === "pass") return { status: "ran", verdict: "pass", ...elapsed };
+  return { status: "ran", verdict: "fail", failChecks: meta.failChecks, ...elapsed };
+}
+
+/**
+ * ggui#1380 — the repair record, arm by arm: `compiled: false` is carried as
+ * is (no re-probe, so no after); `compiled: true` carries the re-probe's meta
+ * projected with the same function as the record's own outcome.
+ */
+function metadataProbeRepair(repair: RuntimeProbeRepair): GenerationRuntimeProbeRepair {
+  return repair.compiled
+    ? { attempted: true, compiled: true, trigger: metadataProbeOutcome(repair.trigger) }
+    : { attempted: true, compiled: false };
+}
+
+/**
+ * ggui#1380 — the harness result's probe record, projected onto the metadata
+ * a host reads. The outcome fields are the LAST probe's (the re-probe's when
+ * the repair compiled, else the pre-repair probe's — exactly what the harness
+ * stamps on `evalResult.runtimeProbe`), and `repair` is present only when a
+ * repair turn was bought. Absent when no probe ran — never a default status.
+ */
+function metadataRuntimeProbe(result: GenerationResult): GenerationRuntimeProbe | undefined {
+  const probe = result.evalResult?.runtimeProbe;
+  if (probe === undefined) return undefined;
+  const repair = result.evalResult?.runtimeProbeRepair;
+  return {
+    ...metadataProbeOutcome(probe),
+    ...(repair !== undefined ? { repair: metadataProbeRepair(repair) } : {}),
+  };
+}
+
+/**
+ * ggui#1380 — the eval rounds' wall-clock, present only when a round ran:
+ * a generation with no round has nothing to time, and the field stays
+ * absent rather than reporting a structural 0.
+ */
+function metadataEvalMs(result: GenerationResult): number | undefined {
+  const breakdown = result.breakdown;
+  if (breakdown === undefined || breakdown.evalRounds === 0) return undefined;
+  return breakdown.evalMs;
+}
+
 function mapLlmProviderToDispatchProvider(provider: LlmProvider): ProviderName {
   switch (provider) {
-    case 'anthropic':
-    case 'bedrock':
-      return 'claude';
-    case 'openai':
-      return 'openai';
-    case 'google':
-      return 'google';
-    case 'openrouter':
-      return 'openrouter';
+    case "anthropic":
+    case "bedrock":
+      return "claude";
+    case "openai":
+      return "openai";
+    case "google":
+      return "google";
+    case "openrouter":
+      return "openrouter";
   }
 }
 
@@ -542,20 +653,18 @@ function mapLlmProviderToDispatchProvider(provider: LlmProvider): ProviderName {
  * yet, so both pass no shell and those generations stay byte-identical — named
  * here rather than guessed.
  */
-function harnessShellForRendering(rendering: RenderingContext | undefined): 'chat' | undefined {
+function harnessShellForRendering(rendering: RenderingContext | undefined): "chat" | undefined {
   if (rendering === undefined) return undefined;
   switch (rendering.shell) {
-    case 'chat':
-      return 'chat';
-    case 'fullscreen':
-    case 'partial':
+    case "chat":
+      return "chat";
+    case "fullscreen":
+    case "partial":
       return undefined;
   }
 }
 
-function mapRendering(
-  rendering: UiGenerateInput['rendering'],
-): RenderingContext | undefined {
+function mapRendering(rendering: UiGenerateInput["rendering"]): RenderingContext | undefined {
   if (!rendering) return undefined;
   return {
     device: rendering.device,
@@ -568,7 +677,7 @@ function failWithoutMetadata(
   input: UiGenerateInput,
   generatorSlug: GeneratorId,
   startedAt: number,
-  error: GenerationError,
+  error: GenerationError
 ): UiGenerateResult {
   return {
     ok: false,
@@ -600,18 +709,18 @@ export function extractComponentCode(raw: string): string {
   const fences: Array<{ lang: string; body: string }> = [];
   let match: RegExpExecArray | null;
   while ((match = fencePattern.exec(raw)) !== null) {
-    const lang = (match[1] ?? '').toLowerCase();
-    const body = match[2] ?? '';
+    const lang = (match[1] ?? "").toLowerCase();
+    const body = match[2] ?? "";
     fences.push({ lang, body });
   }
 
   if (fences.length > 0) {
-    const priority = ['tsx', 'jsx', 'typescript', 'ts', 'javascript', 'js', ''];
+    const priority = ["tsx", "jsx", "typescript", "ts", "javascript", "js", ""];
     for (const preferred of priority) {
       const hit = fences.find((f) => f.lang === preferred);
       if (hit) return hit.body.trim();
     }
-    const firstBody = fences[0]?.body ?? '';
+    const firstBody = fences[0]?.body ?? "";
     return firstBody.trim();
   }
 

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).`,
       ),
     );
   }