@ggui-ai/ui-gen 0.15.0 → 0.17.0

package/src/fragments/render.ts

@@ -27,7 +27,7 @@ export const renderFragments: Record<string, HarnessFragment> = {
     value: "grid",
     cacheTier: "axisDelta",
     promptText:
-      "## Render: grid\n2D tile layout. Use <CardGrid> or CSS `display: grid` with `grid-template-columns: repeat(N, 1fr)`. If items carry row/col fields, position each tile at (row, col). Do not scroll horizontally.",
+      "## Render: grid\nTwo shapes share this axis — read the contract:\n- A TILE grid (a gallery, a stat grid, items that may carry row/col fields): `<Grid columns={N} gap=\"md\">` (or `<CardGrid>`); if items carry row/col fields, position each tile at (row, col).\n- A BOARD (a columns / lanes / stages array whose items are cards — a kanban): the columns sit SIDE BY SIDE at md and wider — `<Grid columns={{ base: 1, md: columns.length }} gap=\"md\">` wrapping the columns map, each column its own `<Stack>` of `<Card>`s with its header and count; NEVER a `<Stack>` of column sections (that is a list — tier-0 fails it).\nNever hand-roll `display: grid`. Do not scroll horizontally.",
   },
   spatial: {
     axis: "render",

package/src/harness/check/runtime-render/prepare-mockup.ts

@@ -129,6 +129,16 @@ function synthesizeFromSchema(
   hint: string,
   warnings: string[],
   depth: number,
+  /**
+   * 1-based position when the value belongs to an array element (inherited
+   * by the element's own fields). Every synthesized string inside an element
+   * carries it, so two elements never share an id or a visible label — the
+   * runtime probe's selection-identity rule ("clicking each fired the action
+   * with the same id") is undecidable on identical items and read a correct
+   * component as broken (2026-09-10, the 1.6 hello: both quick replies were
+   * `Sample Id` / `Sample Label`).
+   */
+  ordinal?: number,
 ): SynthOk | SynthFail {
   if (!schema) return { kind: "fail", reason: "no schema" };
   if (depth > MAX_DEPTH) return { kind: "fail", reason: "schema too deep" };
@@ -146,10 +156,10 @@ function synthesizeFromSchema(
 
   // Union schemas — try first branch only
   if (schema.oneOf && schema.oneOf.length > 0) {
-    return synthesizeFromSchema(schema.oneOf[0], hint, warnings, depth + 1);
+    return synthesizeFromSchema(schema.oneOf[0], hint, warnings, depth + 1, ordinal);
   }
   if (schema.anyOf && schema.anyOf.length > 0) {
-    return synthesizeFromSchema(schema.anyOf[0], hint, warnings, depth + 1);
+    return synthesizeFromSchema(schema.anyOf[0], hint, warnings, depth + 1, ordinal);
   }
 
   // Draft-07 type array (`['string','null']` — the canonical nullable
@@ -158,12 +168,7 @@ function synthesizeFromSchema(
   // above bounds the recursion.
   if (Array.isArray(schema.type)) {
     const primary = schema.type.find((t) => t !== "null") ?? "null";
-    return synthesizeFromSchema(
-      { ...schema, type: primary },
-      hint,
-      warnings,
-      depth + 1,
-    );
+    return synthesizeFromSchema({ ...schema, type: primary }, hint, warnings, depth + 1, ordinal);
   }
 
   switch (schema.type) {
@@ -184,7 +189,9 @@ function synthesizeFromSchema(
           // Use field name as a hint so it appears in DOM and prop-coverage check sees it.
           // Capitalize first letter for natural-looking placeholder.
           const cap = hint.charAt(0).toUpperCase() + hint.slice(1);
-          return { kind: "ok", value: `Sample ${cap}`, source: "schema-synth" };
+          // Inside an array element every string is distinct per element.
+          const value = ordinal === undefined ? `Sample ${cap}` : `Sample ${cap} ${ordinal}`;
+          return { kind: "ok", value, source: "schema-synth" };
         }
       }
     }
@@ -211,7 +218,7 @@ function synthesizeFromSchema(
       const items: JsonValue[] = [];
       for (let i = 0; i < 2; i++) {
         const itemHint = `${hint}Item${i + 1}`;
-        const itemSynth = synthesizeFromSchema(schema.items, itemHint, warnings, depth + 1);
+        const itemSynth = synthesizeFromSchema(schema.items, itemHint, warnings, depth + 1, i + 1);
         if (itemSynth.kind === "ok") {
           // Inject an `id` for list-key purposes if the item is an object lacking one.
           if (
@@ -233,7 +240,7 @@ function synthesizeFromSchema(
       const propsMap = schema.properties ?? {};
       const required = new Set(schema.required ?? []);
       for (const [k, sub] of Object.entries(propsMap)) {
-        const subSynth = synthesizeFromSchema(sub, k, warnings, depth + 1);
+        const subSynth = synthesizeFromSchema(sub, k, warnings, depth + 1, ordinal);
         if (subSynth.kind === "ok") {
           obj[k] = subSynth.value;
         } else if (required.has(k)) {

package/src/harness/coding/init-session.ts

@@ -168,6 +168,8 @@ export async function initSession(input: {
             originalPrompt: params.userPrompt,
             contract: params.contract,
             designContext: undefined,
+            designMode: harness.designMode,
+            profile: harness.profile,
           },
           {
             provider: mapProviderForEvaluator(evalSpec.provider),

package/src/harness/coding/run-coding-turn.ts

@@ -33,6 +33,7 @@ import {
   WRITE_PLAN_TOOL,
   type LLMToolDef,
 } from "../../tools.js";
+import { LUCIDE_ICON_NAMES } from "@ggui-ai/design";
 import { formatWithHashlines } from "../hashline.js";
 import {
   recordToolExchange,
@@ -592,20 +593,11 @@ ${closingInstruction}`;
   // Handle get_available_icons — return icon list without consuming a turn
   if (call.name === "get_available_icons") {
     if (!iconNamesCache) {
-      try {
-        // Dynamic import — resolve from design package dist
-        const iconDataPath = new URL(
-          "../../../../packages/design/dist/primitives/icon-data.js",
-          import.meta.url,
-        ).pathname;
-        const { LUCIDE_ICONS } = await import(iconDataPath);
-        iconNamesCache = Object.keys(LUCIDE_ICONS)
-          .map((n) => n.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase())
-          .join(", ");
-      } catch {
-        iconNamesCache =
-          "sun, moon, cloud, cloud-rain, heart, star, search, home, plus, minus, check, x, arrow-left, arrow-right, chevron-down, chevron-up, menu, user, settings, bell, mail, phone, shopping-cart, download, upload, edit, trash-2, save, eye, lock, globe, map-pin, calendar, clock, zap, alert-circle, info, help-circle";
-      }
+      // The one list the Icon primitive renders (ggui#1015) — the same
+      // export the check leg reads, so the tool never advertises a name
+      // the primitive does not know (the former dist-relative dynamic
+      // import fell back to a 40-name string whenever the path missed).
+      iconNamesCache = LUCIDE_ICON_NAMES.join(", ");
     }
     console.log(`[simple] turn ${turnsUsed}: get_available_icons`);
     let iconResult = `Available Lucide icon names (use with <Icon name="...">):\n${iconNamesCache}`;
@@ -674,6 +666,9 @@ ${closingInstruction}`;
     // typecheck overlays the real wrapper declarations and a generated
     // direct gadget import gets strict option/return narrowing.
     harness.what.gadgetTypes,
+    // Which tier-0 legs fire — the design-vocabulary legs stand down in
+    // `free` mode; every contract leg runs in both.
+    harness.designMode,
   );
   const toolMs = Date.now() - toolStart;
 

package/src/harness/coding/run-eval-round.ts

@@ -22,7 +22,7 @@ import { listContractGadgets } from "@ggui-ai/protocol";
 import type { Classification } from "../../classifier/index.js";
 import type { AgentWorkspace } from "../../coding-agent/workspace.js";
 import type { CostTracker } from "../../evaluation/cost-tracker.js";
-import type { EvalIssue, EvalResult, RuntimeProbeMeta } from "../../evaluation/types-public.js";
+import type { EvalIssue, EvalResult, RuntimeProbeMeta, VisualEvalSummary } from "../../evaluation/types-public.js";
 import { notApplicableCoverage } from "../../evaluation/types-public.js";
 import { mapProviderForEvaluator } from "../enforced-coding.js";
 import { runCheck } from "../index.js";
@@ -128,6 +128,9 @@ const MAX_FEEDBACK_ISSUES = 3;
  * criterion is `not-applicable` (excluded from coverage denominators),
  * not `skipped` (which would count as silent absence).
  */
+/** Why an eval result carries no criteria: the round itself threw (ggui#1110). */
+const EVAL_ROUND_THREW_REASON = "eval round threw";
+
 const LOW_RISK_BYPASS_REASON =
   "same-image low-risk bypass: axis checks clean, tier-1/2 evaluation not invoked";
 
@@ -453,6 +456,11 @@ export async function runEvalRound(
               sourceCode: currentSource,
               originalPrompt: userPrompt,
               contract,
+              // Criteria + mother prompt follow the triad that produced
+              // the source (free mode: color-only tokens, arm-neutral
+              // visual judging).
+              designMode: harness.designMode,
+              profile: harness.profile,
             },
             {
               provider: mapProviderForEvaluator(evaluationAgent.provider),
@@ -476,13 +484,25 @@ export async function runEvalRound(
         : null,
       visualMod
         ? visualMod.runVisualEval(
-            { compiledCode, originalPrompt: userPrompt },
+            {
+              compiledCode,
+              originalPrompt: userPrompt,
+              profile: harness.profile,
+              // The caller's theme, when named — the round paints what the app paints.
+              ...(visualEvaluation?.cssTokens !== undefined ? { cssTokens: visualEvaluation.cssTokens } : {}),
+            },
             {
               provider: mapProviderForEvaluator(visualEvalAgent.provider) as "claude" | "google",
               model: visualEvalAgent.model,
               passThreshold: visualThreshold,
-              sampleProps: visualEvaluation?.sampleProps,
+              // The in-loop visual round renders the same sample the runtime probe
+              // does (the caller's fixture) unless the config names its own.
+              sampleProps: visualEvaluation?.sampleProps ?? fixtureProps,
               viewport: visualEvaluation?.viewport,
+              // Per-canvas judging (arm-neutral) — absent = single shot.
+              ...(visualEvaluation?.canvases !== undefined
+                ? { canvases: visualEvaluation.canvases }
+                : {}),
               // #484/#489 — same threading as the LLM-eval leg above:
               // the visual eval's multimodal call runs inside the same
               // concurrent generation, so it needs the same routing
@@ -497,7 +517,8 @@ export async function runEvalRound(
     ]);
     evalLlmMs = Date.now() - evalLlmStart;
     llmResult = llm;
-    visualIssues = visual;
+    visualIssues = visual?.issues ?? null;
+    const visualSummary: VisualEvalSummary | undefined = visual?.summary;
 
     // Track costs from LLM eval calls
     if (llmResult) {
@@ -524,6 +545,10 @@ export async function runEvalRound(
       ...(llmResult?.criteriaCoverage !== undefined
         ? { criteriaCoverage: llmResult.criteriaCoverage }
         : {}),
+      // Per-canvas visual summary — present only when canvases were
+      // requested and the leg ran; every later re-stamp spreads this
+      // base so it survives to the assembled result.
+      ...(visualSummary !== undefined ? { visual: visualSummary } : {}),
     };
 
     // ── Log merged results, with mode-check subcategory breakdown ──
@@ -868,7 +893,23 @@ export async function runEvalRound(
       lastDiffFailed: false,
     };
   } catch (e) {
-    console.error("[simple] eval failed:", e instanceof Error ? e.message : e);
+    // The round threw. Until ggui#1110 this returned `evalResult` UNDEFINED and
+    // said so only in a console line: downstream the generation carried no
+    // evaluation at all, an offline mint exported no `eval.json`, and the bar
+    // read the missing file as "probe skipped" — a thrown evaluation and an
+    // evaluation that never ran became the same fact, with the reason lost.
+    // Now the failure IS the result: the round reports what threw, on the
+    // channel a judge reads, and can never be mistaken for a pass (`pass` is
+    // empty, the probe status is `infra-skipped`, and a bar that requires the
+    // probe still refuses — with a cause instead of a silence).
+    const message = e instanceof Error ? e.message : String(e);
+    console.error("[simple] eval failed:", message);
+    evalResult = evalResult ?? {
+      issues: [],
+      pass: [],
+      criteriaCoverage: notApplicableCoverage(`${EVAL_ROUND_THREW_REASON}: ${message}`),
+      runtimeProbe: { status: "infra-skipped", reason: `${EVAL_ROUND_THREW_REASON}: ${message}` },
+    };
     return {
       control: "break",
       evalDone: false,

package/src/harness/llm-trace-sink.ts

@@ -21,9 +21,9 @@
  * (createAgent → run-coding-turn → llm-evaluator → file-agent → …)
  * touches ~5 packages for a devtools-only surface. The OSS ggui server
  * is a single process per CLI invocation — global state has no
- * confusion-cost there. A hosted closed runtime isolates per request
- * via process-pool, so a global per-pool is also safe. If we ever
- * multi-tenant inside one process we'll thread it then.
+ * confusion-cost there. A hosted deployment isolates per request via a
+ * process pool, so a global per-pool is also safe. If we ever serve
+ * several apps inside one process we'll thread it then.
  *
  * **Default = no sink.** When unset, the router emits nothing and
  * spends no CPU formatting events. Passing `null` removes a previously

package/src/harness/result-types.ts

@@ -12,8 +12,8 @@
 import type { DataContract, JsonObject } from "@ggui-ai/protocol";
 import type { AdapterResult } from "../adapters/types.js";
 import type { RenderingContext } from "../contract-context.js";
-import type { EvaluationResult } from "../evaluation/types.js";
 import type { EvalResult } from "../evaluation/types-public.js";
+import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // =============================================================================
 // Model Roles
@@ -52,8 +52,6 @@ export type ModelRoles = Partial<Record<ModelRole, string>>;
 export interface GenerationResult extends AdapterResult {
   /** Number of generation passes the harness performed */
   passesUsed: number;
-  /** Evaluation results per round (legacy numeric scoring — backward compat) */
-  evaluations?: EvaluationResult[];
   /** Three-tier evaluation result (tier 0 + LLM tier 1+2 + visual) */
   evalResult?: EvalResult;
   /** Whether background improvement should be spawned (auto-improve mode) */
@@ -62,6 +60,20 @@ export interface GenerationResult extends AdapterResult {
   selfCheckPassed?: boolean;
   /** Which model was used for each role (for benchmark reporting) */
   modelRolesUsed?: Record<string, string>;
+  /**
+   * The triad this generation ran under — recorded ONLY when the caller
+   * set `designMode` on the dispatch (a bench arm switch, an operator
+   * option). Absent = the constrained default path, byte-identical to
+   * the pre-`designMode` result.
+   */
+  designMode?: DesignMode;
+  /**
+   * The canvas class the `free` prompt stated — the explicit `canvas`
+   * when the caller passed one, else the shell × screen derivation the
+   * prompt itself used. Absent in constrained mode (that prompt states
+   * no canvas) unless the caller passed one explicitly.
+   */
+  canvas?: CanvasClass;
   /** Phase-level timing breakdown (ms) */
   timing?: Record<string, number>;
   /** Per-turn/per-outcome breakdown for benchmark analysis.

package/src/harness/runtime.ts

@@ -24,6 +24,7 @@
 // directly to the coding agent in the system prompt — there is no
 // separate planner stage.
 
+import type { GenerationProfileInput } from "../boilerplate/styling-profile.js";
 import type { QualityConfig } from "../evaluation/types-public.js";
 import { DEFAULT_DESIGN_SYSTEM_DOCS } from "../design-system-docs.js";
 import { PRIMITIVES_DOCUMENTATION } from "../validation/index.js";
@@ -32,6 +33,7 @@ import { renderPitfallsBlock } from "./pitfalls.js";
 import type { GadgetDescriptor, DataContract, JsonObject } from "@ggui-ai/protocol";
 import { buildSystemPrompt as buildSystemPromptSkeleton } from "../boilerplate.js";
 import type { AgentConfig } from "./llm-router.js";
+import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 // Re-export the boilerplate generator so existing internal importers
 // (create-harness.ts, benchmarks/preview-boilerplate.ts) keep working.
@@ -82,6 +84,19 @@ export interface SingleComponentParams {
     passThreshold?: number;
     sampleProps?: JsonObject;
     viewport?: { width: number; height: number };
+    /**
+     * Per-canvas judging — see `VisualEvalConfig.canvases`. When set, the
+     * eval round screenshots + judges once per class and the harness
+     * stamps `EvalResult.visual` with the PNG-free summary. Unset =
+     * today's single screenshot at `viewport`.
+     */
+    canvases?: readonly CanvasClass[];
+    /**
+     * The stylesheet the in-loop visual round renders under (a caller's
+     * theme composed by `cssTokensForAppTheme`); absent = the design's
+     * default tokens. Never part of the prompt or the identity.
+     */
+    cssTokens?: string;
   };
   onProgress?: (event: unknown) => void;
   onInitialResult?: (result: {
@@ -133,6 +148,16 @@ export function buildSystemPrompt(
    * stdlib gadgets do not need one.
    */
   gadgetTypes?: Readonly<Record<string, string>>,
+  /**
+   * Which triad to teach — see `SystemPromptInputs.designMode`. Omitted
+   * (every pre-existing caller) means `constrained`, byte-identical to
+   * the pre-`designMode` prompt.
+   */
+  designMode?: DesignMode,
+  /** Rendering canvas class (`free` mode) — see `SystemPromptInputs.canvas`. */
+  canvas?: CanvasClass,
+  /** The app's generation profile (#991). */
+  profile?: GenerationProfileInput,
 ): string {
   return buildSystemPromptSkeleton({
     userRequest,
@@ -145,6 +170,9 @@ export function buildSystemPrompt(
     wireDoc: WIRE_DOCUMENTATION,
     appGadgets,
     gadgetTypes,
+    designMode,
+    canvas,
+    profile,
     // criteriaBlock left undefined — ui-gen fills default from open CRITERIA.
   });
 }

package/src/harness/types-public.ts

@@ -18,12 +18,14 @@
 // types hub for the harness module. `AxisCheck` + `AxisCheckInput` live
 // in `@ggui-ai/ui-gen/evaluation`.
 
+import type { GenerationProfileInput } from "../boilerplate/styling-profile.js";
 import type { GadgetDescriptor, DataContract, JsonValue } from "@ggui-ai/protocol";
 import type { Classification } from "../classifier/axes.js";
 import type { EvalIssue, EvalTier, AxisCheck, RuntimeProbeStatus } from "../evaluation/types-public.js";
 import type { LLMToolDef } from "../llm.js";
 import type { CacheTier, HarnessFragment } from "../fragments/index.js";
 import type { HarnessPolicy, ProcessMode } from "../policy.js";
+import type { CanvasClass, DesignMode } from "../design-mode.js";
 
 export type { ProcessMode };
 
@@ -293,6 +295,16 @@ export interface Harness {
   readonly id: HarnessId;
   readonly name: HarnessName;
   readonly classification: Classification;
+  /**
+   * Which triad this harness materialised — threaded from
+   * `CreateHarnessInput.designMode` into the HOW leg (prompt), the WHAT
+   * leg (boilerplate) and every CHECK consumer (tier-0 gate, axis
+   * checks, evaluator criteria). `constrained` unless the caller opted
+   * into `free`.
+   */
+  readonly designMode: DesignMode;
+  /** The app's generation profile in force for this harness (#991), if any. */
+  readonly profile?: GenerationProfileInput;
 
   readonly how: HowLeg;
   readonly what: WhatLeg;
@@ -383,6 +395,12 @@ export type SystemPromptBuilder = (input: {
   readonly shellType?: string;
   readonly screen?: string;
   readonly axisDelta?: string;
+  /** Which triad to teach — see `CreateHarnessInput.designMode`. */
+  readonly designMode?: DesignMode;
+  /** Rendering canvas class (`free` mode) — see `CreateHarnessInput.canvas`. */
+  readonly canvas?: CanvasClass;
+  /** The app's generation profile (#991) — see `CreateHarnessInput.profile`. */
+  readonly profile?: GenerationProfileInput;
 }) => string;
 
 export interface CreateHarnessInput {
@@ -392,6 +410,26 @@ export interface CreateHarnessInput {
   readonly shellType?: "chat" | "fullscreen" | "spatial";
   readonly screen?: "mobile" | "tablet" | "desktop" | "universal";
   readonly overrides?: HarnessOverrides;
+  /**
+   * Which triad to materialise. `constrained` (default) is today's
+   * design-system triad, byte-identical to the pre-`designMode`
+   * harness (same prompt, boilerplate, tier-0 legs, criteria and id).
+   * `free` relaxes only the design vocabulary; every hard contract
+   * stays. See `../design-mode.ts`.
+   */
+  readonly designMode?: DesignMode;
+  /**
+   * Rendering canvas class the `free` prompt states explicitly. When
+   * omitted the prompt derives it from `shellType` × `screen`. Ignored
+   * by the `constrained` prompt.
+   */
+  readonly canvas?: CanvasClass;
+  /**
+   * The app's generation profile (#991): operator-declared free text the
+   * HOW leg renders as one bounded section and every judge reads under its
+   * own frame. Absent = byte-identical prompts.
+   */
+  readonly profile?: GenerationProfileInput;
   /**
    * Pre-resolved static harness policy. When omitted, `createHarness`
    * falls back to `DEFAULT_HARNESS_POLICY` from `@ggui-ai/ui-gen/policy`.

package/src/index.ts

@@ -21,6 +21,7 @@ export {
 } from './create-ui-generator.js';
 export type { CreateUiGeneratorOptions } from './create-ui-generator.js';
 export type { ProviderRetryInfo } from './harness/llm-router.js';
+export type { GenerationResult } from './harness/result-types.js';
 
 // Generator registry seam re-export. The interface + slug helpers live
 // in `@ggui-ai/mcp-server-core`; the in-memory factory lives in
@@ -49,6 +50,31 @@ export {
   injectVariance,
 } from './contract-context.js';
 export type { RenderingContext } from './contract-context.js';
+export { canvasForRenderingContext } from './contract-context.js';
+
+// ── Design mode ──────────────────────────────────────────────────────
+//
+// `createUiGenerator({ designMode })` — `constrained` (default) or
+// `free`; the canvas vocabulary the `free` prompt states.
+export {
+  DESIGN_MODES,
+  DEFAULT_DESIGN_MODE,
+  CANVAS_CLASSES,
+  CANVAS_VIEWPORTS,
+  CANVAS_BREAKPOINTS,
+  CANVAS_DESCRIPTORS,
+  canvasDisplayModeForShell,
+  canvasForRendering,
+  canvasForViewportWidth,
+  describeCanvas,
+} from './design-mode.js';
+export type {
+  DesignMode,
+  CanvasClass,
+  CanvasViewport,
+  CanvasDisplayMode,
+  CanvasDescriptor,
+} from './design-mode.js';
 
 // ── Anthropic SDK construction ──────────────────────────────────────
 //
@@ -56,3 +82,5 @@ export type { RenderingContext } from './contract-context.js';
 // go through this helper instead of `new Anthropic(...)` so future
 // header / baseURL tweaks land in one place.
 export { createAnthropicClient } from './adapters/claude/client.js';
+export { AESTHETIC_BRIEF_MAX_CHARS, type GenerationProfileInput } from './boilerplate/styling-profile.js';
+export { EFFORT_DIALS, EFFORT_TABLE_VERSION, effortDials, type EffortDials } from './effort.js';

package/src/internal/extract-call-signatures.ts

@@ -419,7 +419,7 @@ export function extractCallSignaturesFromDts(
     return {};
   }
 
-  const cacheKey = `${dtsContent}${[...hookNames].sort().join(',')}`;
+  const cacheKey = `${dtsContent}\u0000${[...hookNames].sort().join(',')}`;
   const cached = callSignatureCache.get(cacheKey);
   if (cached !== undefined) return cached;
 
@@ -470,7 +470,7 @@ export function extractComponentPropsFromDts(
     return {};
   }
 
-  const cacheKey = `${dtsContent}${[...componentNames].sort().join(',')}`;
+  const cacheKey = `${dtsContent}\u0000${[...componentNames].sort().join(',')}`;
   const cached = componentPropsCache.get(cacheKey);
   if (cached !== undefined) return cached;
 

package/src/pin-fixtures.ts

@@ -0,0 +1,98 @@
+/**
+ * The two fixed fixtures every prompt pin renders — one action-bearing
+ * `chat`×`mobile` shell, one `fullscreen`×`desktop` board with a
+ * `contextSpec` — shared by `design-mode.pin.test.ts` (the stable prefix)
+ * and `shape-guidance.pin.test.ts` (the axis-conditioned Shape Guidance).
+ */
+import type { DataContract } from '@ggui-ai/protocol';
+
+export interface PinFixture {
+  readonly userRequest: string;
+  readonly shellType: 'chat' | 'fullscreen' | 'spatial';
+  readonly screen: 'mobile' | 'tablet' | 'desktop' | 'universal';
+  readonly contract: DataContract;
+}
+
+export const PIN_FIXTURES: readonly PinFixture[] = [
+  {
+    userRequest: 'A todo list where each item can be toggled done',
+    shellType: 'chat',
+    screen: 'mobile',
+    contract: {
+      propsSpec: {
+        properties: {
+          todos: {
+            required: true,
+            description: 'The todos to show',
+            schema: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string' },
+                  title: { type: 'string' },
+                  done: { type: 'boolean' },
+                },
+              },
+            },
+          },
+        },
+      },
+      actionSpec: {
+        toggleTodo: {
+          label: 'Toggle',
+          description: 'Flip the done state of one todo',
+          schema: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+          },
+        },
+      },
+    },
+  },
+  {
+    userRequest: 'A kanban board with live task updates and a selected card',
+    shellType: 'fullscreen',
+    screen: 'desktop',
+    contract: {
+      propsSpec: {
+        properties: {
+          columns: {
+            required: true,
+            schema: { type: 'array', items: { type: 'string' } },
+          },
+          tasks: {
+            required: false,
+            schema: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string' },
+                  column: { type: 'string' },
+                  title: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      },
+      streamSpec: {
+        taskUpdates: {
+          description: 'Task CRUD feed',
+          schema: {
+            type: 'object',
+            properties: {
+              action: { type: 'string', enum: ['create', 'move', 'edit', 'delete'] },
+              id: { type: 'string' },
+            },
+          },
+        },
+      },
+      contextSpec: {
+        selectedId: { schema: { type: 'string', nullable: true } },
+      },
+    },
+  },
+];

package/src/providers/bedrock.ts

@@ -2,13 +2,13 @@
  * Concrete AWS Bedrock `ProviderAdapter` — invokes Anthropic Claude
  * models on Bedrock via the official `@anthropic-ai/bedrock-sdk`
  * package. IAM-based auth (no API key in flight); the AWS credential
- * chain (IRSA pod token / `~/.aws/credentials` / env vars) supplies
+ * chain (a workload-identity token / `~/.aws/credentials` / env vars) supplies
  * SigV4 signatures automatically.
  *
  * ## Why this adapter exists
  *
  * Anyone running a one-shot LLM caller on an AWS-credentialed host
- * (EC2, ECS, Lambda, EKS) can target Bedrock without managing API keys: IAM is
+ * (EC2, ECS, Lambda and the like) can target Bedrock without managing API keys: IAM is
  * the auth boundary, AWS rotates host credentials automatically, and
  * a misconfigured IAM role surfaces as a clear `AccessDeniedException`
  * the SDK funnels through `mapError`. The alternative — parking a
@@ -165,8 +165,8 @@ export function bedrockEndpointFor(model: string): BedrockEndpoint {
  * Constructor options for the Bedrock adapter.
  *
  * `region` is the only required option in the common case — IAM
- * credentials come from the standard AWS chain (IRSA pod token in
- * EKS, instance role on EC2, env vars or shared credentials file
+ * credentials come from the standard AWS chain (a workload-identity token in
+ * a container cluster, instance role on EC2, env vars or shared credentials file
  * locally). Tests pass `clientFactory` to inject a mock SDK client.
  */
 export interface BedrockAdapterOptions {

package/src/run-check.ts

@@ -22,6 +22,7 @@ import {
   newValidatorTraceId,
   truncateSourceForTrace,
 } from "./harness/validator-trace-sink.js";
+import { runGatedAxisChecks, traceAxisChecksSkipped } from "./evaluation/axis-checks/dispatch.js";
 
 export interface RunCheckInput {
   readonly sourceCode: string;
@@ -66,6 +67,10 @@ export async function runCheck(input: RunCheckInput): Promise<CheckResult> {
   const startedAt = Date.now();
 
   if (compiledCode === null) {
+    traceAxisChecksSkipped(
+      { sourceCode, contract, originalPrompt: prompt, classification: harness.classification, designMode: harness.designMode },
+      "compiledCode null — no check ran",
+    );
     const result: CheckResult = {
       issues: [],
       axisIssueCount: 0,
@@ -113,17 +118,13 @@ export async function runCheck(input: RunCheckInput): Promise<CheckResult> {
     contract: contract,
     originalPrompt: prompt,
     classification: harness.classification,
+    designMode: harness.designMode,
   };
-  let axisIssueCount = 0;
-  const seenAxisIds = new Set<string>();
-  for (const axisCheck of check.axisChecks) {
-    if (seenAxisIds.has(axisCheck.id)) continue;
-    seenAxisIds.add(axisCheck.id);
-    firedIds.push(axisCheck.id);
-    const axisIssues = axisCheck.run(axisInput);
-    issues.push(...axisIssues);
-    axisIssueCount += axisIssues.length;
-  }
+  // The one runner `runAxisChecks` shares (ggui#1046 trace prints here, on the served path).
+  const axisRun = runGatedAxisChecks(check.axisChecks, axisInput);
+  issues.push(...axisRun.issues);
+  firedIds.push(...axisRun.firedIds);
+  const axisIssueCount = axisRun.issues.length;
 
   // ── Tier checks (deterministic, harness-owned) ────────────────────────
   let tierIssueCount = 0;