@ggui-ai/ui-gen 0.16.0 → 0.18.0

package/src/check/run-tier0.ts

@@ -352,6 +352,137 @@ function isGadgetExportImported(
   return false;
 }
 
+/**
+ * AST-precise detector for the compiles-but-renders-nothing class: the
+ * default-exported component's body never returns a tree.
+ *
+ * The boilerplate HANDS the model the wrapper — `base.tsx.tmpl` and
+ * `base-free.tsx.tmpl` both emit `return (` … `);` around `{{LAYOUT}}`.
+ * A model rewriting the root block can delete those two lines with it,
+ * leaving the JSX as a bare expression statement. That is legal TSX: it
+ * parses, esbuild compiles it, `typecheck()` passes it, and the
+ * component renders a blank frame. Seen once in twenty takes of the
+ * ggui#1113 A/B (`xs-chat-card`, run 2 — the judge spent a screenshot
+ * and an LLM call to report "completely blank").
+ *
+ * `compile/default-export` already guards the scaffold's
+ * `export default function` line and `types/props-interface` its
+ * `interface Props` line. The `return (` was the third scaffold line
+ * with nothing watching it.
+ *
+ * Conservative by construction — it reports ONLY when it positively
+ * identified a block-bodied default-export component:
+ *   - a concise arrow body (`export default () => <X/>`) returns by
+ *     construction → silent
+ *   - `export default memo(Component)` or any other expression it
+ *     cannot resolve to a function → silent
+ *   - a `return` inside a nested helper is not the component's own (the
+ *     walk stops at every nested function boundary), but ONE own-level
+ *     `return <value>` anywhere — an early `return null` included —
+ *     satisfies it.
+ *
+ * Returns `null` when the component returns (or could not be
+ * identified), else the 1-based line of the first bare JSX expression
+ * statement in its body — the line the fix belongs on — or `undefined`
+ * when the body has no JSX statement to point at either.
+ */
+function detectComponentNeverReturns(
+  sourceCode: string,
+): { jsxStatementLine: number | undefined } | null {
+  const sf = ts.createSourceFile(
+    'source.tsx',
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+    ts.ScriptKind.TSX,
+  );
+
+  const isFunctionLike = (n: ts.Node): boolean =>
+    ts.isFunctionDeclaration(n) ||
+    ts.isFunctionExpression(n) ||
+    ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n) ||
+    ts.isClassDeclaration(n) ||
+    ts.isClassExpression(n);
+
+  /** The top-level declaration `name` binds to, when it is a function. */
+  function resolveTopLevel(
+    name: string,
+  ): ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | undefined {
+    for (const st of sf.statements) {
+      if (ts.isFunctionDeclaration(st) && st.name?.text === name) return st;
+      if (ts.isVariableStatement(st)) {
+        for (const decl of st.declarationList.declarations) {
+          if (
+            ts.isIdentifier(decl.name) &&
+            decl.name.text === name &&
+            decl.initializer !== undefined &&
+            (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
+          ) {
+            return decl.initializer;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
+  let component:
+    | ts.FunctionDeclaration
+    | ts.FunctionExpression
+    | ts.ArrowFunction
+    | undefined;
+  for (const st of sf.statements) {
+    if (
+      ts.isFunctionDeclaration(st) &&
+      st.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
+    ) {
+      component = st;
+      break;
+    }
+    if (ts.isExportAssignment(st) && st.isExportEquals !== true) {
+      const expr = st.expression;
+      if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) component = expr;
+      else if (ts.isIdentifier(expr)) component = resolveTopLevel(expr.text);
+      break;
+    }
+  }
+  // No default export at all, or one this detector cannot resolve to a
+  // function — `compile/default-export` owns the first case and the
+  // second is not ours to guess at.
+  if (component === undefined) return null;
+
+  const body = component.body;
+  // A concise arrow body IS the returned value.
+  if (body === undefined || !ts.isBlock(body)) return null;
+
+  let returnsValue = false;
+  let jsxStatementLine: number | undefined;
+  const visit = (node: ts.Node): void => {
+    if (returnsValue) return;
+    if (ts.isReturnStatement(node)) {
+      if (node.expression !== undefined) returnsValue = true;
+      return;
+    }
+    if (
+      jsxStatementLine === undefined &&
+      ts.isExpressionStatement(node) &&
+      (ts.isJsxElement(node.expression) ||
+        ts.isJsxFragment(node.expression) ||
+        ts.isJsxSelfClosingElement(node.expression))
+    ) {
+      jsxStatementLine = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+    }
+    node.forEachChild((child) => {
+      // A helper component's own `return` is not this component's.
+      if (!isFunctionLike(child)) visit(child);
+    });
+  };
+  for (const st of body.statements) if (!isFunctionLike(st)) visit(st);
+
+  return returnsValue ? null : { jsxStatementLine };
+}
+
 /**
  * Run all tier 0 (deterministic, no-LLM) checks against component source.
  *
@@ -412,6 +543,7 @@ export async function runTier0Checks(
       tier: 0,
       result: 'fail',
       category: 'compile',
+      subcategory: 'build-error',
       severity: 'critical',
       description: `Component failed to compile:\n${errorDetail}`,
       fix: 'Fix the JSX/TypeScript syntax errors listed above',
@@ -535,6 +667,7 @@ export async function runTier0Checks(
           tier: 0,
           result: 'fail',
           category: 'imports',
+          subcategory: 'disallowed-package',
           severity: 'critical',
           description: `Import from "${pkg}" is not allowed`,
           fix: `Only import from: ${describeAllowedImports()}`,
@@ -980,6 +1113,27 @@ export async function runTier0Checks(
     });
   }
 
+  // ── Component never returns its tree ──────────────────────
+  // The scaffold hands the model `return (` … `);` around the layout.
+  // A root-block rewrite can delete them with it, and bare JSX at
+  // statement position compiles, type-checks and renders NOTHING.
+  const neverReturns = detectComponentNeverReturns(sourceCode);
+  if (neverReturns !== null) {
+    issues.push({
+      tier: 0,
+      result: 'fail',
+      category: 'compile',
+      subcategory: 'renders-nothing',
+      severity: 'critical',
+      description:
+        neverReturns.jsxStatementLine === undefined
+          ? 'The component never returns its tree — it renders a blank frame'
+          : `The component never returns its tree: the JSX at line ${neverReturns.jsxStatementLine} sits at statement position, so it is built and thrown away and the frame renders blank`,
+      fix: 'Wrap the tree in the return the boilerplate gave you: `return (` before the root element and `);` after it.',
+      ...(neverReturns.jsxStatementLine === undefined ? {} : { line: neverReturns.jsxStatementLine }),
+    });
+  }
+
   // (Controller-View checks removed — generated components use a
   // single-function pattern.)
 

package/src/contract-context.ts

@@ -26,6 +26,8 @@
  * sizing strategies and including the hint inline cuts a class of
  * "designed for fullscreen, rendered in a chat bubble" bugs.
  */
+import { STYLING_PROFILE_PRECEDENCE_NOTE } from './boilerplate/styling-profile.js';
+import type { RenderingContext as ProtocolRenderingContext } from '@ggui-ai/protocol';
 import type {
   ActionEntry,
   BlueprintVariance,
@@ -43,17 +45,11 @@ import {
 
 /**
  * Rendering context — how and where the component will be displayed.
- * Affects layout strategy, sizing, and interaction patterns. Mirrors the
- * shape cloud's harness passes through `dispatchGeneration`.
+ * Affects layout strategy, sizing, and interaction patterns. The ONE
+ * vocabulary is `@ggui-ai/protocol`'s `renderingContextSchema` (ggui#1000);
+ * this is its type, derived — never re-declared here.
  */
-export interface RenderingContext {
-  /** Device category — affects touch targets, column count, density. */
-  readonly device: 'mobile' | 'tablet' | 'desktop' | 'spatial';
-  /** Shell type — the container the component renders in. */
-  readonly shell: 'chat' | 'fullscreen' | 'partial';
-  /** Viewport dimensions in CSS pixels (optional). */
-  readonly viewport?: { readonly width: number; readonly height: number };
-}
+export type RenderingContext = ProtocolRenderingContext;
 
 const SHELL_HINTS: Record<string, string> = {
   chat: `**Chat Shell — Inline card in scrolling conversation**
@@ -66,9 +62,9 @@ const SHELL_HINTS: Record<string, string> = {
 - Width: width: 100% (fills parent bubble). Do NOT set max-width.`,
 
   fullscreen: `**Fullscreen Shell — Takes over entire viewport**
-- Container: width: 100vw, height: 100vh (100dvh on mobile for safe areas)
+- Container: the whole viewport, edge to edge — the frame stretches your root to its full height (you never set a viewport height yourself)
 - Chrome: NONE — your component IS the entire UI. You own all visual chrome.
-- Sizing: fill the viewport. Use min-height: 100vh or height: 100%. Edge-to-edge.
+- Sizing: size to content; to fill a parent that has a height use height: 100% or flex: 1. NEVER min-height: 100vh / 100dvh — the frame already stretches the root, and a viewport height only fights it (tier-0 fail).
 - Padding: component owns ALL padding. Use var(--ggui-spacing-6) or larger for breathing room.
 - Scrolling: component manages its own scroll if content exceeds viewport (overflow-y: auto)
 - Layout: can use multi-column, sidebars, headers/footers. Full creative control.
@@ -206,6 +202,19 @@ export function buildContractsContext(
         if (entry.nextStep) {
           line += `\n    Next-step hint: agent intends to call \`${entry.nextStep}\``;
         }
+        // ggui#1108: `confirm` was the one declared action field the contract
+        // renderer dropped — every other author field (label, description,
+        // example, nextStep) reaches the model and this one did not. It is
+        // rendered as INFORMATION, not as a rule: the terminal-actions section
+        // deliberately does NOT cite it, because citing it measured ZERO —
+        // two wordings, n=4 each, `save` + `confirm: true` came back armed 0/4
+        // and 0/4. The field's own doc says "whether to show confirmation
+        // BEFORE triggering", which is gravity, not one-shot-ness, and the
+        // model reads it that way. Emitted only when true, so an absent flag
+        // leaves the prompt bytes identical to before this line existed.
+        if (entry.confirm === true) {
+          line += `\n    Author flag: \`confirm\` — the author marked this action grave enough to confirm before it fires, so a second press is a mistake.`;
+        }
         return line;
       })
       .join('\n');
@@ -383,7 +392,10 @@ export function injectContracts(
  * Returns an empty string when no fields are populated so the inject
  * helper can no-op cleanly.
  */
-export function buildVarianceContext(variance: BlueprintVariance): string {
+export function buildVarianceContext(
+  variance: BlueprintVariance,
+  options?: { readonly profileDeclared?: boolean },
+): string {
   const lines: string[] = [];
   if (typeof variance.persona === 'string' && variance.persona.length > 0) {
     lines.push(`- **Persona**: ${variance.persona}`);
@@ -411,6 +423,7 @@ export function buildVarianceContext(variance: BlueprintVariance): string {
     'the visual treatment + copy register — but the contract shape (props,',
     'actions, contexts, streams) remains canonical. Variance changes HOW',
     'the UI looks and reads, not WHAT it does.',
+    ...(options?.profileDeclared === true ? [STYLING_PROFILE_PRECEDENCE_NOTE] : []),
     '',
     ...lines,
   ].join('\n');
@@ -420,9 +433,10 @@ export function buildVarianceContext(variance: BlueprintVariance): string {
 export function injectVariance(
   userPrompt: string,
   variance?: BlueprintVariance,
+  options?: { readonly profileDeclared?: boolean },
 ): string {
   if (!variance) return userPrompt;
-  const block = buildVarianceContext(variance);
+  const block = buildVarianceContext(variance, options);
   if (!block) return userPrompt;
   return userPrompt + '\n\n' + block;
 }

package/src/create-harness.ts

@@ -12,6 +12,7 @@
 // `adapters/generation-dispatch.ts` at the dispatch boundary; callers
 // that omit them get minimal defaults.
 
+import { hasProfile } from "./boilerplate/styling-profile.js";
 import type { CacheTier } from "./fragments/index.js";
 import { compose } from "./compose.js";
 import { buildSystemPrompt, generateBoilerplate } from "./boilerplate.js";
@@ -90,6 +91,7 @@ export function createHarness(input: CreateHarnessInput): Harness {
     axisDelta: composed.promptText,
     designMode,
     ...(input.canvas !== undefined ? { canvas: input.canvas } : {}),
+    ...(input.profile !== undefined ? { profile: input.profile } : {}),
   });
   const howFragments = composed.fragments.filter(
     (f) => f.promptText && f.promptText.trim().length > 0,
@@ -189,6 +191,7 @@ export function createHarness(input: CreateHarnessInput): Harness {
   // Only a non-default design mode contributes — the constrained id is
   // byte-identical to the pre-`designMode` harness.
   if (designMode !== DEFAULT_DESIGN_MODE) overrideLabels.push(`designMode:${designMode}`);
+  if (hasProfile(input.profile)) overrideLabels.push("profile");
 
   const id = computeHarnessId({
     classificationHash,
@@ -221,6 +224,7 @@ export function createHarness(input: CreateHarnessInput): Harness {
     name,
     classification,
     designMode,
+    ...(input.profile !== undefined ? { profile: input.profile } : {}),
     how,
     what,
     check,

package/src/create-ui-generator.ts

@@ -31,6 +31,7 @@
  * Callers who want a lightweight single-shot path can build it
  * themselves.
  */
+import type { SingleComponentParams } from './harness/runtime.js';
 import type {
   GadgetDescriptor,
   GenerationError,
@@ -55,6 +56,8 @@ 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 {
@@ -67,6 +70,7 @@ 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. */
@@ -89,6 +93,20 @@ 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;
   /**
@@ -208,6 +226,8 @@ export function createUiGenerator(
     enableRuntimeRender = false,
     maxAttempts,
     maxEvalRounds,
+    evaluation,
+    visualEvaluation,
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
@@ -313,6 +333,7 @@ export function createUiGenerator(
         const promptWithVariance = injectVariance(
           promptWithRendering,
           input.variance,
+          { profileDeclared: hasProfile(input.profile) },
         );
 
         // Resolve appGadgets by precedence:
@@ -335,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,
@@ -342,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 }
@@ -360,6 +396,9 @@ export function createUiGenerator(
           ...(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);

package/src/design-mode.ts

@@ -77,6 +77,16 @@ export type CanvasDisplayMode = "inline" | "fullscreen";
  * 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";
 }
@@ -177,6 +187,6 @@ export function describeCanvas(canvas: CanvasClass): string {
   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.`
+    `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
@@ -42,10 +42,11 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 | 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 |
-| container | var(--ggui-color-container) | Primary-branded containers |
-| onContainer | var(--ggui-color-onContainer) | Text on branded containers |
+| 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 |
 
@@ -54,6 +55,7 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 - 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)\`
 
@@ -172,7 +174,8 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 - **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
 

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];
+}