@ggui-ai/ui-gen 0.15.0 → 0.17.0

package/src/create-ui-generator.ts

@@ -31,11 +31,15 @@
  * Callers who want a lightweight single-shot path can build it
  * themselves.
  */
+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';
 import type {
   GenerationMetadata,
@@ -52,20 +56,26 @@ import {
 } from '@ggui-ai/mcp-server-core';
 import { createGeneratorTools } from './adapters/index.js';
 import { dispatchGeneration } from './adapters/generation-dispatch.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 { 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';
 
 /** The slug for the OSS default seed generator. */
 const DEFAULT_TIER: GeneratorTier = 'default';
-const DEFAULT_MODEL = 'haiku-4-5';
+const DEFAULT_MODEL: ModelRef = 'anthropic/claude-haiku-4-5';
 
 export interface CreateUiGeneratorOptions {
   /**
@@ -83,27 +93,42 @@ export interface CreateUiGeneratorOptions {
   readonly maxAttempts?: number;
   /** Maximum evaluation rounds. */
   readonly maxEvalRounds?: number;
+  /**
+   * In-loop LLM evaluation config (ggui#1001). When set, every generation
+   * runs the evaluator tiers after the coding leg (`maxRounds` defaults to
+   * `maxEvalRounds`) and the harness result carries `evalResult` — the
+   * probe verdict a downstream judge reads. Default: none, as today —
+   * a serving deployment leaves it unset; offline minting jobs set a round.
+   */
+  readonly evaluation?: EvaluationConfig;
+  /**
+   * In-loop visual round config (per-canvas judging, a sample, the
+   * 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'];
   /** Quality config controlling eval tiers + improvement behavior. */
   readonly qualityConfig?: QualityConfig;
   /**
-   * Generator identity — registry key + parsed components.
+   * Generator identity — registry key + declared model.
    *
-   * The tier + model determine the {@link UiGenerator.slug} the
-   * factory bakes onto the returned generator. Defaults to
-   * `{tier: 'default', model: 'haiku-4-5'}` → slug
-   * `ui-gen-default-haiku-4-5`, the OSS seed.
+   * The tier alone determines the {@link UiGenerator.slug} the factory
+   * bakes onto the returned generator (`ui-gen-<tier>`); `model` is the
+   * generator's declared model field and is never part of the slug
+   * (ggui#923). Defaults to tier `'default'` → slug `ui-gen-default`,
+   * the OSS seed, with the factory's default model.
    *
    * The actual model used per request still comes from
    * `UiGenerateInput.llm.model` (operators may override via BYOK).
    * The identity here is the registry-level handle, not a runtime
    * model constraint.
    *
-   * Mutually-exclusive shortcut: pass `slug` instead and the factory
-   * parses it for you. The slug + tier/model overloads conflict; the
-   * factory throws if both are supplied.
+   * Mutually-exclusive shortcut: pass `slug` instead of `tier` and the
+   * factory parses the tier from it; `model` may accompany either form.
+   * The factory throws if `slug` and `tier` are both supplied.
    */
   readonly tier?: GeneratorTier;
-  readonly model?: string;
+  readonly model?: ModelRef;
   readonly slug?: string;
   /**
    * Per-deployment gadget descriptor source. Wired once at factory
@@ -163,6 +188,35 @@ export interface CreateUiGeneratorOptions {
    * still log via `console.warn`, just without a caller-side hook.
    */
   readonly onRetry?: AgentConfig['onRetry'];
+  /**
+   * Generation observer. Invoked once per successful `generate()` with
+   * the FULL harness result — source, compiled code, token counters,
+   * timing breakdown, evaluation rounds and (when configured) the
+   * per-canvas visual scores — before it is projected onto the
+   * `UiGenerateResult` envelope, which carries only what the protocol
+   * needs. Lets a host record or forward the complete run without
+   * re-deriving it from the envelope. Bound ONCE at construction
+   * (mirrors `onRetry`); not invoked when generation fails. An
+   * exception thrown by the observer is the caller's own and fails
+   * that generation like any other error on the path — keep it
+   * non-throwing.
+   */
+  readonly onGenerated?: (result: GenerationResult) => void;
+  /**
+   * Which generation triad to run. `constrained` (default) is the
+   * design-system triad — byte-identical to the generator's behaviour
+   * before this option existed. `free` relaxes only the design
+   * vocabulary (raw HTML, inline CSS, literal spacing / typography /
+   * radius; the design package importable but optional) while keeping
+   * every hard contract: the boilerplate-typed wire hooks, the import
+   * allowlist + security bans, the host envelope, the budgets, the
+   * blueprint-reuse shape, and brand-bearing color on the closed
+   * `--ggui-color-*` token manifest. Reaches the prompt, boilerplate,
+   * tier-0 gate, axis checks and evaluator criteria through the harness.
+   * The rendering canvas the `free` prompt states is derived from
+   * `input.rendering` (device × shell, refined by viewport width).
+   */
+  readonly designMode?: DesignMode;
 }
 
 export function createUiGenerator(
@@ -172,10 +226,14 @@ export function createUiGenerator(
     enableRuntimeRender = false,
     maxAttempts,
     maxEvalRounds,
+    evaluation,
+    visualEvaluation,
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
     onRetry,
+    onGenerated,
+    designMode,
   } = options;
 
   const identity = resolveIdentity(options);
@@ -268,9 +326,14 @@ export function createUiGenerator(
         const promptWithRendering = rendering
           ? injectRenderingContext(input.request.prompt, rendering)
           : input.request.prompt;
+        // Canvas class for the `free` prompt — TOLD, never guessed.
+        // Ignored by the constrained prompt (its shell/screen
+        // descriptors stay byte-identical).
+        const canvas = rendering ? canvasForRenderingContext(rendering) : undefined;
         const promptWithVariance = injectVariance(
           promptWithRendering,
           input.variance,
+          { profileDeclared: hasProfile(input.profile) },
         );
 
         // Resolve appGadgets by precedence:
@@ -293,6 +356,19 @@ export function createUiGenerator(
           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);
+        const effectiveMaxAttempts = dials?.maxAttempts ?? maxAttempts;
+        const effectiveMaxEvalRounds = dials?.maxEvalRounds ?? maxEvalRounds;
+        const effectiveEvaluation =
+          dials !== undefined && evaluation !== undefined ? { ...evaluation, maxRounds: dials.maxEvalRounds } : evaluation;
+        const effectiveVisualEvaluation =
+          dials !== undefined && visualEvaluation !== undefined
+            ? { ...visualEvaluation, passThreshold: dials.selfEvalPassThreshold }
+            : visualEvaluation;
+
         const result = await dispatchGeneration({
           provider,
           userPrompt,
@@ -300,8 +376,10 @@ export function createUiGenerator(
           tools,
           ...(input.contract ? { contract: input.contract } : {}),
           originalPrompt: input.request.prompt,
-          ...(maxAttempts !== undefined ? { maxAttempts } : {}),
-          ...(maxEvalRounds !== undefined ? { maxEvalRounds } : {}),
+          ...(effectiveMaxAttempts !== undefined ? { maxAttempts: effectiveMaxAttempts } : {}),
+          ...(effectiveMaxEvalRounds !== undefined ? { maxEvalRounds: effectiveMaxEvalRounds } : {}),
+          ...(effectiveEvaluation !== undefined ? { evaluation: effectiveEvaluation } : {}),
+          ...(effectiveVisualEvaluation !== undefined ? { visualEvaluation: effectiveVisualEvaluation } : {}),
           ...(qualityConfig !== undefined ? { qualityConfig } : {}),
           ...(resolvedAppGadgets !== undefined
             ? { appGadgets: resolvedAppGadgets }
@@ -316,12 +394,19 @@ export function createUiGenerator(
           enableRuntimeRender,
           ...(routeOverride !== undefined ? { routeOverride } : {}),
           ...(onRetry !== undefined ? { onRetry } : {}),
+          ...(designMode !== undefined ? { designMode } : {}),
+          ...(canvas !== undefined ? { canvas } : {}),
+          ...(input.profile !== undefined ? { profile: input.profile } : {}),
+          // Fixture props reach the in-loop probe + visual round only (never the prompt, never identity).
+          ...(input.fixtureProps !== undefined ? { fixtureProps: input.fixtureProps } : {}),
         });
 
+        onGenerated?.(result);
+
         const metadata: GenerationMetadata = {
           provider: input.llm.provider,
           generator: identity.slug,
-          model: input.llm.model,
+          model: modelRefOfRoute(input.llm),
           inputTokens: result.tokens.input,
           outputTokens: result.tokens.output,
           latencyMs: Date.now() - startedAt,
@@ -362,7 +447,7 @@ export function createUiGenerator(
           metadata: {
             provider: input.llm.provider,
             generator: identity.slug,
-            model: input.llm.model,
+            model: modelRefOfRoute(input.llm),
             inputTokens: 0,
             outputTokens: 0,
             latencyMs: Date.now() - startedAt,
@@ -381,29 +466,29 @@ export function createUiGenerator(
 }
 
 function resolveIdentity(opts: CreateUiGeneratorOptions): {
-  slug: string;
+  slug: GeneratorId;
   tier: GeneratorTier;
-  model: string;
+  model: ModelRef;
 } {
   const hasSlug = typeof opts.slug === 'string' && opts.slug.length > 0;
-  const hasTierOrModel = opts.tier !== undefined || opts.model !== undefined;
-  if (hasSlug && hasTierOrModel) {
+  if (hasSlug && opts.tier !== undefined) {
     throw new Error(
-      'createUiGenerator: pass either { slug } or { tier, model } — not both.',
+      'createUiGenerator: pass either { slug } or { tier } — not both.',
     );
   }
+  const model = opts.model ?? DEFAULT_MODEL;
   if (hasSlug) {
-    const parsed = parseGeneratorSlug(opts.slug!);
-    if (!parsed) {
+    const slug = opts.slug!;
+    const parsed = parseGeneratorSlug(slug);
+    if (!parsed || !isGeneratorId(slug)) {
       throw new Error(
-        `createUiGenerator: slug ${JSON.stringify(opts.slug)} is not a valid ui-gen-<tier>-<model> identifier.`,
+        `createUiGenerator: slug ${JSON.stringify(slug)} is not a valid ui-gen-<tier> identifier.`,
       );
     }
-    return { slug: opts.slug!, tier: parsed.tier, model: parsed.model };
+    return { slug, tier: parsed.tier, model };
   }
   const tier = opts.tier ?? DEFAULT_TIER;
-  const model = opts.model ?? DEFAULT_MODEL;
-  const slug = formatGeneratorSlug({ tier, model });
+  const slug = formatGeneratorSlug({ tier });
   if (!isValidGeneratorSlug(slug)) {
     // Unreachable: formatGeneratorSlug throws on malformed components,
     // so a slug it returns must parse. Defensive check kept to surface
@@ -442,7 +527,7 @@ function mapRendering(
 
 function failWithoutMetadata(
   input: UiGenerateInput,
-  generatorSlug: string,
+  generatorSlug: GeneratorId,
   startedAt: number,
   error: GenerationError,
 ): UiGenerateResult {
@@ -452,7 +537,7 @@ function failWithoutMetadata(
     metadata: {
       provider: input.llm.provider,
       generator: generatorSlug,
-      model: input.llm.model,
+      model: modelRefOfRoute(input.llm),
       inputTokens: 0,
       outputTokens: 0,
       latencyMs: Date.now() - startedAt,

package/src/design-mode.ts

@@ -0,0 +1,192 @@
+// packages/ui-gen/src/design-mode.ts
+//
+// The ONE definition of the `designMode` option and the rendering-canvas
+// vocabulary. Every triad surface (system prompt, boilerplate, tier-0
+// gate, axis checks, evaluator criteria) AND the visual evaluator import
+// these types from here — nothing re-declares the unions.
+//
+//   - `constrained` (default) — today's triad: the component composes
+//     from the `@ggui-ai/design` primitives, prop enums and spacing
+//     scale, and tier-0 enforces the design vocabulary. Byte-identical
+//     to the pre-`designMode` behaviour (pinned by
+//     `design-mode.pin.test.ts`).
+//   - `free` — the design vocabulary is relaxed: raw HTML elements,
+//     inline styles and `<style>` blocks are allowed; the design package
+//     is importable but optional. Every HARD contract stays: the data
+//     contract via the boilerplate-typed wire hooks, the import
+//     allowlist + security bans, the host envelope, the budgets, the
+//     blueprint-reuse shape, and brand-bearing color via the closed
+//     `--ggui-color-*` token manifest (no literals, no fallbacks).
+
+export const DESIGN_MODES = ["constrained", "free"] as const;
+
+export type DesignMode = (typeof DESIGN_MODES)[number];
+
+export const DEFAULT_DESIGN_MODE: DesignMode = "constrained";
+
+// ─── Rendering canvas ───────────────────────────────────────────────────────
+//
+// ONE canvas vocabulary shared by the prompt input (the `free` prompt
+// TELLS the agent its canvas; the `constrained` prompt keeps its
+// shell/screen descriptors byte-for-byte) and the visual evaluator (one
+// screenshot + judge score per class at `CANVAS_VIEWPORTS[class]`).
+//
+// A class is derived from DISPLAY MODE + width, never from width alone:
+// an inline chat card is `xs-chat-card` whatever the host window
+// measures (the bubble, not the window, bounds the component); a
+// fullscreen-class surface follows its width through the three
+// breakpoints. `canvasForViewportWidth` is monotonic in width per
+// display mode (pinned by `design-mode.test.ts`).
+
+export const CANVAS_CLASSES = [
+  "xs-chat-card",
+  "mobile-fullscreen-small",
+  "md",
+  "lg",
+  "xl",
+] as const;
+
+export type CanvasClass = (typeof CANVAS_CLASSES)[number];
+
+export interface CanvasViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** The viewport (CSS px) each class is rendered + judged at. */
+export const CANVAS_VIEWPORTS: Readonly<Record<CanvasClass, CanvasViewport>> = {
+  "xs-chat-card": { width: 400, height: 640 },
+  "mobile-fullscreen-small": { width: 390, height: 844 },
+  md: { width: 768, height: 1024 },
+  lg: { width: 1024, height: 768 },
+  xl: { width: 1440, height: 900 },
+};
+
+/**
+ * The two display modes the canvas derivation distinguishes. `inline`
+ * is the chat card (MCP Apps `inline` display mode / the `chat` shell);
+ * `fullscreen` is every surface the component owns edge to edge or as
+ * a panel (`fullscreen`, `pip`, the `spatial` and `partial` shells) —
+ * there the width decides the class.
+ */
+export type CanvasDisplayMode = "inline" | "fullscreen";
+
+/**
+ * Map a shell name (`chat` / `fullscreen` / `spatial` / `partial`) or an
+ * MCP Apps display mode (`inline` / `fullscreen` / `pip`) onto the
+ * canvas display mode. Only `chat` and `inline` are the inline card;
+ * everything else is width-governed.
+ */
+/**
+ * The display mode a JUDGE canvas stands for (ggui#1100): the inline chat
+ * card is `xs-chat-card`; every other canvas is a surface the component
+ * owns edge to edge, which the served runtime composes with `fit: 'fill'`
+ * — so the judge must too, or it scores a picture the user never sees.
+ */
+export function displayModeForCanvas(canvas: CanvasClass): CanvasDisplayMode {
+  return canvas === "xs-chat-card" ? "inline" : "fullscreen";
+}
+
+export function canvasDisplayModeForShell(shell: string | undefined): CanvasDisplayMode {
+  return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
+}
+
+/** Fullscreen-class breakpoints (inclusive lower bounds), CSS px. */
+export const CANVAS_BREAKPOINTS = { md: 600, lg: 1024, xl: 1440 } as const;
+
+/**
+ * Derive the canvas class from display mode + container width.
+ *
+ *   inline      → `xs-chat-card` at every width
+ *   fullscreen  → width <  600  → `mobile-fullscreen-small`
+ *                 600 – 1023    → `md`
+ *                 1024 – 1439   → `lg`
+ *                 ≥ 1440        → `xl`
+ */
+export function canvasForViewportWidth(mode: CanvasDisplayMode, width: number): CanvasClass {
+  if (mode === "inline") return "xs-chat-card";
+  if (width < CANVAS_BREAKPOINTS.md) return "mobile-fullscreen-small";
+  if (width < CANVAS_BREAKPOINTS.lg) return "md";
+  if (width < CANVAS_BREAKPOINTS.xl) return "lg";
+  return "xl";
+}
+
+/**
+ * Map today's shell × screen descriptors onto a canvas class when no
+ * width is known. `chat` is always the inline card; `spatial` is a
+ * ~600px floating panel (`md`); `fullscreen` follows the screen. Unknown
+ * values fall back to `lg` (the widest common fullscreen), matching the
+ * skeleton's `fullscreen` / `universal` defaults.
+ */
+export function canvasForRendering(
+  shellType: string | undefined,
+  screen: string | undefined,
+): CanvasClass {
+  const shell = shellType ?? "fullscreen";
+  if (canvasDisplayModeForShell(shell) === "inline") return "xs-chat-card";
+  if (shell === "spatial") return "md";
+  switch (screen ?? "universal") {
+    case "mobile":
+      return "mobile-fullscreen-small";
+    case "tablet":
+      return "md";
+    default:
+      return "lg";
+  }
+}
+
+export interface CanvasDescriptor {
+  /** Short human label. */
+  readonly label: string;
+  /** Inclusive width range the component must look right across, CSS px. */
+  readonly minWidthPx: number;
+  readonly maxWidthPx: number;
+  /** What the host draws around the component at this canvas. */
+  readonly host: string;
+}
+
+export const CANVAS_DESCRIPTORS: Readonly<Record<CanvasClass, CanvasDescriptor>> = {
+  "xs-chat-card": {
+    label: "extra-small chat card",
+    minWidthPx: 320,
+    maxWidthPx: 480,
+    host: "an inline card inside a chat message bubble — the host draws the card border, shadow and rounded corners; the component fills the bubble width and takes its natural height",
+  },
+  "mobile-fullscreen-small": {
+    label: "small mobile fullscreen",
+    minWidthPx: 320,
+    maxWidthPx: 599,
+    host: "a phone-sized viewport the component owns edge to edge — single column, touch targets at least 44px, the component manages its own scroll",
+  },
+  md: {
+    label: "medium panel",
+    minWidthPx: 600,
+    maxWidthPx: 1023,
+    host: "a tablet viewport or a floating panel (spatial / picture-in-picture) — one or two columns, medium density",
+  },
+  lg: {
+    label: "large fullscreen",
+    minWidthPx: 1024,
+    maxWidthPx: 1439,
+    host: "a desktop viewport the component owns edge to edge — multi-column layouts, hover states and pointer interactions are available",
+  },
+  xl: {
+    label: "extra-large fullscreen",
+    minWidthPx: 1440,
+    maxWidthPx: 1920,
+    host: "a wide desktop viewport the component owns edge to edge — cap content width or use the extra room deliberately; never stretch a single column across the whole width",
+  },
+};
+
+/**
+ * The explicit sentence the `free` prompt renders for a canvas — the
+ * agent is TOLD the canvas, it never guesses it.
+ */
+export function describeCanvas(canvas: CanvasClass): string {
+  const d = CANVAS_DESCRIPTORS[canvas];
+  return (
+    `This component renders on the \`${canvas}\` canvas (${d.label}): ` +
+    `${d.minWidthPx}–${d.maxWidthPx}px wide, ${d.host}. ` +
+    `Design for the whole range — the host may size the iframe anywhere inside it, and the host owns the height: size to your content, never to the viewport.`
+  );
+}

package/src/design-system-docs.ts

@@ -26,7 +26,7 @@ export const DEFAULT_DESIGN_SYSTEM_DOCS = `# Design System - Default Light Theme
 - var(--ggui-color-primary-300) - #7dd3fc
 - var(--ggui-color-primary-400) - #38bdf8
 - var(--ggui-color-primary-500) - #0ea5e9
-- var(--ggui-color-primary-600) - #0284c7 (main action color)
+- var(--ggui-color-primary-600) - #0284c7 (main action FILL — buttons, borders, icon fills; accent TEXT takes the link role below)
 - var(--ggui-color-primary-700) - #0369a1
 - var(--ggui-color-primary-800) - #075985
 - var(--ggui-color-primary-900) - #0c4a6e
@@ -36,20 +36,26 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 
 | Token | CSS Variable | Default | Role |
 |-------|-------------|---------|------|
-| surface | var(--ggui-color-surface) | Main content background |
-| onSurface | var(--ggui-color-onSurface) | Primary text on surface |
-| surfaceVariant | var(--ggui-color-surfaceVariant) | Card/panel background |
-| onSurfaceVariant | var(--ggui-color-onSurfaceVariant) | Muted/secondary text |
-| container | var(--ggui-color-container) | Primary-branded containers |
-| onContainer | var(--ggui-color-onContainer) | Text on branded containers |
+| ground | var(--ggui-color-ground) | The page / canvas behind everything |
+| onGround | var(--ggui-color-onGround) | Text on the canvas |
+| container | var(--ggui-color-container) | A card, a bubble, a panel — the unit of content |
+| onContainer | var(--ggui-color-onContainer) | Body text on a card |
+| elevated | var(--ggui-color-elevated) | Menus, popovers, modals, toasts — floats above a card |
+| onElevated | var(--ggui-color-onElevated) | Text on an elevated surface |
+| heroGround | var(--ggui-color-heroGround) | A hero / greeting panel's ground — brand-tinted on a light host, the ink pair on a dark one (Card surface="hero") |
+| onHeroGround | var(--ggui-color-onHeroGround) | Text on the hero ground |
+| sunken | var(--ggui-color-sunken) | Wells, inputs at rest, code blocks — recessed inside a card |
+| onSunken | var(--ggui-color-onSunken) | Muted / secondary text |
+| link | var(--ggui-color-link) | Accent TEXT — eyebrows, taglines, links, labels, inline arrows: the brand's readable ink, derived per mode to clear 4.5:1 on the container and the ground |
 | outline | var(--ggui-color-outline) | Borders, dividers |
 | outlineVariant | var(--ggui-color-outlineVariant) | Subtle borders |
 
 **Usage pattern:**
-- Page/section background → \`var(--ggui-color-surface)\`
-- Body text → \`var(--ggui-color-onSurface)\`
-- Card/panel background → \`var(--ggui-color-surfaceVariant)\`
-- Secondary/muted text → \`var(--ggui-color-onSurfaceVariant)\`
+- Page/section background → \`var(--ggui-color-ground)\`
+- Body text → \`var(--ggui-color-onContainer)\`
+- Card/panel background → \`var(--ggui-color-container)\`; recessed wells / inputs → \`var(--ggui-color-sunken)\`
+- Secondary/muted text → \`var(--ggui-color-onSunken)\`
+- Accent / branded text (eyebrow, tagline, link, label, inline arrow) → \`var(--ggui-color-link)\` or \`<Text tone="emphasized">\` — never a bare \`primary-<stop>\` as a text color
 - Branded section/header → \`var(--ggui-color-container)\` bg + \`var(--ggui-color-onContainer)\` text
 - Borders/dividers → \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 
@@ -66,11 +72,11 @@ Prefer the primitives' \`tone="success|warning|error|info"\` prop over hand-writ
 - **NEVER** use rgba(), hsl(), or other CSS color functions with hardcoded values.
 - **NEVER** use raw neutral-* or gray-* scale tokens (neutral-50, neutral-900, etc.) — these are internal to the theme and break in dark mode.
 - **ALWAYS** use semantic tokens for text and backgrounds:
-  - Text: \`var(--ggui-color-onSurface)\` or \`var(--ggui-color-onSurfaceVariant)\`
-  - Backgrounds: \`var(--ggui-color-surface)\` or \`var(--ggui-color-surfaceVariant)\`
+  - Text: \`var(--ggui-color-onContainer)\` or \`var(--ggui-color-onSunken)\`
+  - Backgrounds: \`var(--ggui-color-container)\` or \`var(--ggui-color-sunken)\`
   - Borders: \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 - For branded elements use \`var(--ggui-color-primary-*)\` scale tokens — these ARE safe because primary adapts per theme.
-- For card backgrounds use \`var(--ggui-color-surfaceVariant)\` or \`var(--ggui-color-primary-50)\`
+- For card backgrounds use \`var(--ggui-color-container)\` or \`var(--ggui-color-primary-50)\`
 
 ## Spacing
 
@@ -165,16 +171,17 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 \`\`\`
 
 ### Color usage guide
-- **Semantic roles** (surface, onSurface, container, outline): Use for all surface/text/border decisions — these adapt to any theme
+- **Layering roles** (ground, container, elevated, sunken + their on* inks; outline): one kind of AREA each — use them for every background/text/border decision; they adapt to any theme
 - **primary-50/100**: Section backgrounds, highlight strips, card headers
 - **primary-200/300**: Borders, dividers, focus rings, input outlines
-- **primary-500/600**: Icons, links, labels, badges, buttons, CTAs
+- **primary-500/600**: Filled buttons, CTAs, badges, icon fills, active indicators — fills and borders, NOT a text color
+- **link**: Accent TEXT — eyebrows, taglines, links, labels, inline arrows; the brand's readable ink per mode (a bare \`primary-300…600\` as a text color fails tier-0: \`universal.accent_text_ink\`)
 - **primary-700/800/900**: Headings and text on light primary backgrounds
 - **neutral-***: Only when you need a specific shade that semantic tokens don't cover
 
 The primary palette is the app's brand — use it throughout (headers, accents, borders, interactive elements), not just on the submit button.
 
-**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-surface, #fafafa)). Just use var(--ggui-color-surface) — the theme provides all values.
+**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-container, #fafafa)). Just use var(--ggui-color-container) — the theme provides all values.
 
 ## Motion & Animation
 

package/src/effort.ts

@@ -0,0 +1,48 @@
+// The `effort` reader table (ggui#1059, A2). The wire carries ONLY the level
+// name (`generation.profile.effort`, protocol #1058); this table is the
+// cold-gen READER that maps a name onto the harness's dials, versioned here
+// so a level's meaning (and its price line) can move without a wire change.
+//
+// Boundaries, stated once:
+//  - `effort` renders NO prompt text — the prompt is byte-identical under any
+//    level (`profile-cross.pin.test.ts`). Dials only.
+//  - Absent ⇒ the deployment's own options, untouched. The table is applied
+//    only when a level is named.
+//  - `selfEvalPassThreshold` is the GENERATOR's in-loop visual
+//    self-evaluation threshold (`visualEvaluation.passThreshold`). A serving
+//    layer's own acceptance bar is a different number and does not move with
+//    `effort`.
+//  - `modelTier` / `judgeTier` are REQUESTS to the deployment's router
+//    (`fast | balanced | premium`), never a model id: a deployment with one
+//    key is never promoted by a profile. The harness does not act on them;
+//    the caller that owns model selection reads them from this table.
+import type { AppGenerationProfileEffort, ModelTier } from "@ggui-ai/protocol";
+
+/** Bump when a level's meaning changes; the price line beside it follows. */
+export const EFFORT_TABLE_VERSION = 1;
+
+export interface EffortDials {
+  /** Coding-loop turn cap (`maxAttempts`). */
+  readonly maxAttempts: number;
+  /** Evaluation rounds the harness may spend (`maxEvalRounds`). */
+  readonly maxEvalRounds: number;
+  /** The generator's in-loop visual self-evaluation threshold, 0–100 — not a serving layer's acceptance bar. */
+  readonly selfEvalPassThreshold: number;
+  /** Requested coding-model tier — a request to the deployment's router, never a model id. */
+  readonly modelTier: ModelTier;
+  /** Requested judge-model tier — same nature. */
+  readonly judgeTier: ModelTier;
+}
+
+export const EFFORT_DIALS: Readonly<Record<AppGenerationProfileEffort, EffortDials>> = {
+  low: { maxAttempts: 5, maxEvalRounds: 1, selfEvalPassThreshold: 65, modelTier: "fast", judgeTier: "fast" },
+  medium: { maxAttempts: 8, maxEvalRounds: 2, selfEvalPassThreshold: 70, modelTier: "fast", judgeTier: "balanced" },
+  high: { maxAttempts: 8, maxEvalRounds: 3, selfEvalPassThreshold: 75, modelTier: "balanced", judgeTier: "balanced" },
+  xhigh: { maxAttempts: 10, maxEvalRounds: 3, selfEvalPassThreshold: 80, modelTier: "premium", judgeTier: "balanced" },
+  ultra: { maxAttempts: 12, maxEvalRounds: 4, selfEvalPassThreshold: 85, modelTier: "premium", judgeTier: "premium" },
+};
+
+/** The dials for a named level; `undefined` when no level is named (the deployment's options stand). */
+export function effortDials(effort: AppGenerationProfileEffort | undefined): EffortDials | undefined {
+  return effort === undefined ? undefined : EFFORT_DIALS[effort];
+}