@ggui-ai/ui-gen 0.14.0 → 0.16.0

package/src/check/run-tier0.ts

@@ -16,6 +16,7 @@ import ts from 'typescript';
 import type { DataContract } from '@ggui-ai/protocol';
 import { HOOK_NAME_RE, listContractGadgets } from '@ggui-ai/protocol';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
+import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
 import { validateAllContracts, type ContractIssue } from './contract-validation.js';
 import { typecheck } from './type-checker.js';
 import { lintReactHooks, type ReactLintDiagnostic } from './react-linter.js';
@@ -95,10 +96,22 @@ function stripComments(code: string): string {
 function detectCertainDoubleWiredActions(
   sourceCode: string,
   actionBindings: readonly string[],
+  /**
+   * `constrained` keeps the design-package tag sets above. `free`
+   * retargets the SAME invariant ("one useAction binding → exactly one
+   * gesture surface") at raw elements: the outer host is ANY JSX element
+   * whose onClick/onPress calls a binding (`<div onClick>`, `<li>`,
+   * `<tr>`, `<button>`, `<a>`, `[role=button]`, a design primitive…),
+   * and the inner match is ANY descendant whose handler attribute calls
+   * the same binding. Tag names stop mattering because in free mode a
+   * raw element is a first-class gesture surface.
+   */
+  designMode: DesignMode = DEFAULT_DESIGN_MODE,
 ): EvalIssue[] {
   const issues: EvalIssue[] = [];
   if (actionBindings.length === 0) return issues;
   const bindings = new Set(actionBindings);
+  const anyElementIsInteractive = designMode === 'free';
   const TRAIT_HOST_TAGS = new Set(['Card', 'Box', 'Stack', 'Row']);
   const TRAITS_THAT_FIRE = new Set(['Clickable', 'Pressable']);
   const INTERACTIVE_DESCENDANTS = new Set([
@@ -148,7 +161,11 @@ function detectCertainDoubleWiredActions(
 
   function isTraitHostWithFiringAs(node: ts.JsxOpeningElement): boolean {
     const tag = tagNameText(node);
-    if (tag === undefined || !TRAIT_HOST_TAGS.has(tag)) return false;
+    if (tag === undefined) return false;
+    // Free mode: every element with a handler is a gesture surface —
+    // the callee check in `visit` decides whether it fires a binding.
+    if (anyElementIsInteractive) return true;
+    if (!TRAIT_HOST_TAGS.has(tag)) return false;
     const asExpr = attrExpression(node, 'as');
     return (
       asExpr !== undefined &&
@@ -206,7 +223,10 @@ function detectCertainDoubleWiredActions(
           : undefined;
       if (opening !== undefined) {
         const tag = tagNameText(opening);
-        if (tag !== undefined && INTERACTIVE_DESCENDANTS.has(tag)) {
+        if (
+          tag !== undefined &&
+          (anyElementIsInteractive || INTERACTIVE_DESCENDANTS.has(tag))
+        ) {
           for (const attrName of HANDLER_ATTRS) {
             const callee = extractCalleeName(attrExpression(opening, attrName));
             if (callee === expectedBinding) {
@@ -239,6 +259,9 @@ function detectCertainDoubleWiredActions(
           const outerLine =
             sf.getLineAndCharacterOfPosition(node.openingElement.getStart())
               .line + 1;
+          const outerLabel = anyElementIsInteractive
+            ? `<${outerTag}>`
+            : `<${outerTag} as={...}>`;
           issues.push({
             tier: 0,
             result: 'fail',
@@ -246,9 +269,11 @@ function detectCertainDoubleWiredActions(
             subcategory: 'double-wired-action:certain',
             severity: 'critical',
             description:
-              `Nested-interactive double-wire: outer <${outerTag} as={...}> at line ${outerLine} and inner <${match.tag}> at line ${match.line} both dispatch the same useAction binding '${outerCallee}'. ` +
+              `Nested-interactive double-wire: outer ${outerLabel} at line ${outerLine} and inner <${match.tag}> at line ${match.line} both dispatch the same useAction binding '${outerCallee}'. ` +
               `One user click on the inner control fires its handler AND bubbles to the outer handler — '${outerCallee}' dispatches TWICE, the action runs back-to-back, and a toggle-style action silently reverts the user's change.`,
-            fix: `Pick ONE surface for the gesture: either drop \`as={...}\` + onClick on the outer <${outerTag}> and let the inner <${match.tag}> own the gesture, OR remove the inner <${match.tag}> and let the outer <${outerTag} as={...}> own it. Don't wire both to the same useAction binding.`,
+            fix: anyElementIsInteractive
+              ? `Pick ONE gesture surface for '${outerCallee}': either remove the onClick from the outer <${outerTag}> and let the inner <${match.tag}> own the gesture, OR drop the inner <${match.tag}>'s handler and let the outer <${outerTag}> own it. Never wire both to the same useAction binding — stopPropagation is not a fix.`
+              : `Pick ONE surface for the gesture: either drop \`as={...}\` + onClick on the outer <${outerTag}> and let the inner <${match.tag}> own the gesture, OR remove the inner <${match.tag}> and let the outer <${outerTag} as={...}> own it. Don't wire both to the same useAction binding.`,
             line: outerLine,
           });
         }
@@ -346,9 +371,25 @@ export async function runTier0Checks(
    * narrowing). Standard-library-only callers omit it.
    */
   gadgetTypes?: Readonly<Record<string, string>>,
+  /**
+   * Which triad produced the source. `constrained` (default) runs every
+   * leg exactly as before. `free` gates OFF the design-VOCABULARY legs —
+   * `raw-spacing`, `raw-pixels`, `numeric-spacing-prop`, the
+   * `stack-row-*` prop checks and `clickable-wrapper` — because raw
+   * elements, inline CSS and literal spacing are first-class there. It
+   * KEEPS every contract leg: `hex-color`, `hardcoded-color-fn`,
+   * `named-color`, `token-fallback`, `off-manifest-token`,
+   * `asset-color-pair` (color stays on the closed token manifest),
+   * imports, security, Props / default-export, wire_* and gadget checks,
+   * and the double-wired-action detector (retargeted at raw elements).
+   */
+  designMode: DesignMode = DEFAULT_DESIGN_MODE,
 ): Promise<EvalIssue[]> {
   const issues: EvalIssue[] = [];
   const lines = sourceCode.split('\n');
+  // Design-vocabulary legs fire only when the prompt taught the
+  // vocabulary — see `designMode` above.
+  const enforceDesignVocabulary = designMode === 'constrained';
 
   // ── Compile check ─────────────────────────────────────────
   //
@@ -591,7 +632,7 @@ export async function runTier0Checks(
         subcategory: 'hardcoded-color-fn',
         severity: 'critical',
         description: `Hardcoded ${colorFnMatch[1]}() breaks theme switching — use design tokens.`,
-        fix: 'Replace with a primitive variant OR a semantic token: var(--ggui-color-surface), var(--ggui-color-onSurface), var(--ggui-color-outline), etc.',
+        fix: 'Replace with a primitive variant OR a layering role: var(--ggui-color-container), var(--ggui-color-onContainer), var(--ggui-color-outline), etc.',
         line: lineNum,
       });
     }
@@ -616,7 +657,7 @@ export async function runTier0Checks(
         subcategory: 'off-manifest-token',
         severity: 'critical',
         description: `Token "${name}" is not in the design system's token manifest — no theme defines it, so it renders unset.`,
-        fix: `Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onSurface), …; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
+        fix: `Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onContainer), …; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
         line: lineNum,
       });
     }
@@ -627,9 +668,11 @@ export async function runTier0Checks(
     // `#fff` defeats its colors. Only the STRING-literal form fails;
     // the numeric escape (`gap={12}`) is untouched, so a genuine
     // off-scale pixel value still has a path.
-    const rawSpacingMatch = line.match(
-      /\b(gap|padding|paddingX|paddingY|margin|radius)\s*=\s*["'][\d.]+(?:px|rem|em)["']/,
-    );
+    const rawSpacingMatch = enforceDesignVocabulary
+      ? line.match(
+          /\b(gap|padding|paddingX|paddingY|margin|radius)\s*=\s*["'][\d.]+(?:px|rem|em)["']/,
+        )
+      : null;
     if (rawSpacingMatch) {
       issues.push({
         tier: 0,
@@ -693,14 +736,16 @@ export async function runTier0Checks(
           subcategory: 'named-color',
           severity: 'critical',
           description: `Hardcoded CSS named color "${named}" breaks theme switching — use design tokens.`,
-          fix: `Replace with a typed slot (Text tone="muted" / Box surface="accent" / Badge variant="success") OR a semantic token: var(--ggui-color-onSurfaceVariant), var(--ggui-color-primary-500), etc. The keyword "${named}" maps to a fixed RGB; the operator's theme has no effect on it.`,
+          fix: `Replace with a typed slot (Text tone="muted" / Box surface="accent" / Badge variant="success") OR a semantic token: var(--ggui-color-onSunken), var(--ggui-color-primary-500), etc. The keyword "${named}" maps to a fixed RGB; the operator's theme has no effect on it.`,
           line: lineNum,
         });
       }
     }
 
     // Raw pixel values in spacing CSS properties
-    const pxMatch = line.match(/(?:padding|margin|gap|borderRadius)\s*:\s*['"]?\d+px/);
+    const pxMatch = enforceDesignVocabulary
+      ? line.match(/(?:padding|margin|gap|borderRadius)\s*:\s*['"]?\d+px/)
+      : null;
     if (pxMatch && !line.includes('var(--ggui-')) {
       issues.push({
         tier: 0,
@@ -708,14 +753,16 @@ export async function runTier0Checks(
         category: 'tokens',
         subcategory: 'raw-pixels',
         description: 'Raw pixel value in spacing — must use design tokens',
-        fix: 'Replace with var(--ggui-spacing-*, fallback)',
+        fix: 'Replace with a bare var(--ggui-spacing-*) token — no literal fallback (the runtime injects every token) — or the scale name on the primitive prop (gap="md", padding="lg")',
         line: lineNum,
       });
     }
 
     // Numeric spacing props on components (e.g., padding={24}, gap={8})
     // These bypass the design system — should use var(--ggui-spacing-*)
-    const numericSpacingMatch = line.match(/\b(padding|paddingX|paddingY|gap|margin)\s*=\s*\{?\s*(\d+)\s*\}?/);
+    const numericSpacingMatch = enforceDesignVocabulary
+      ? line.match(/\b(padding|paddingX|paddingY|gap|margin)\s*=\s*\{?\s*(\d+)\s*\}?/)
+      : null;
     if (numericSpacingMatch && !line.includes('var(--ggui-')) {
       issues.push({
         tier: 0,
@@ -735,7 +782,7 @@ export async function runTier0Checks(
   // onClick on them is a plain type error the type-checker catches — don't
   // steer those toward `as={Clickable}` (it won't compile on them).
   const clickablePattern = /<(?:Card|Box|Stack|Row)\s[^>]*onClick/;
-  for (let i = 0; i < lines.length; i++) {
+  for (let i = 0; enforceDesignVocabulary && i < lines.length; i++) {
     if (clickablePattern.test(lines[i]) && !lines[i].includes('as={Clickable}') && !lines[i].includes('as={Pressable}')) {
       issues.push({
         tier: 0, result: 'warn', category: 'contract', subcategory: 'clickable-wrapper',
@@ -752,9 +799,21 @@ export async function runTier0Checks(
   // another (the inner gesture bubbles to the outer handler). Captured
   // in scenario-07: a `Card as={Clickable} onClick` row containing a
   // `Checkbox onChange`, both calling the same action → double-toggle.
-  const actionBindings = [
-    ...sourceCode.matchAll(/(?:const|let)\s+(\w+)\s*=\s*useAction\s*\(/g),
-  ]
+  //
+  // Binding extraction. The constrained regex is the pre-`designMode`
+  // one, kept verbatim: it matches `useAction(` only, so a binding
+  // declared with the generic the boilerplate itself emits —
+  // `useAction<ActionXPayload>('x')` — is NOT collected there (a
+  // pre-existing gap, left in place because the constrained gate must
+  // stay byte-identical for the A/B; collapse the two regexes once that
+  // pin is lifted). `free` mode accepts the optional generic so the
+  // one-gesture-surface invariant actually fires on boilerplate-shaped
+  // hook lines.
+  const bindingRe =
+    designMode === 'free'
+      ? /(?:const|let)\s+(\w+)\s*=\s*useAction\s*(?:<[^>]*>)?\s*\(/g
+      : /(?:const|let)\s+(\w+)\s*=\s*useAction\s*\(/g;
+  const actionBindings = [...sourceCode.matchAll(bindingRe)]
     .map((m) => m[1])
     .filter((name): name is string => typeof name === 'string');
   for (const binding of actionBindings) {
@@ -794,7 +853,7 @@ export async function runTier0Checks(
   // CAUSE one turn earlier and prevents shipping the broken a11y nest.
   if (actionBindings.length > 0) {
     issues.push(
-      ...detectCertainDoubleWiredActions(sourceCode, actionBindings),
+      ...detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode),
     );
   }
 
@@ -862,7 +921,7 @@ export async function runTier0Checks(
   const ALIGN_VALUES = new Set(['start', 'center', 'end', 'stretch']);
   const JUSTIFY_VALUES = new Set(['start', 'center', 'end', 'between', 'around', 'evenly']);
   const tagRegex = /<(Stack|Row)\b([^>]*)>/gs;
-  for (const tag of sourceCode.matchAll(tagRegex)) {
+  for (const tag of enforceDesignVocabulary ? sourceCode.matchAll(tagRegex) : []) {
     const tagName = tag[1];
     const attrs = tag[2];
     const tagLine = sourceCode.slice(0, tag.index).split('\n').length;
@@ -1316,8 +1375,9 @@ export async function runTier0Checks(
 export async function runTier0(
   sourceCode: string,
   contract?: DataContract,
+  designMode: DesignMode = DEFAULT_DESIGN_MODE,
 ): Promise<EvalResult> {
-  const issues = await runTier0Checks(sourceCode, contract);
+  const issues = await runTier0Checks(sourceCode, contract, undefined, undefined, designMode);
   const pass: string[] = [];
 
   // Build pass list from categories that had no issues

package/src/check/type-checker.ts

@@ -316,10 +316,18 @@ async function loadVfs(): Promise<Map<string, VfsEntry>> {
 /**
  * Try to resolve a relative import within the VFS.
  * Given `containingFile` (e.g. `node_modules/@ggui-ai/design/primitives/index.d.ts`)
- * and `importPath` (e.g. `./Card`), try:
+ * and `importPath` (e.g. `./Card` or, as every published declaration says
+ * since 0.15.0, `./Card.js`), try:
  *   - <resolved>.d.ts
  *   - <resolved>/index.d.ts
  *   - <resolved>.ts
+ * A `.js` / `.mjs` / `.cjs` extension on the specifier is the ESM
+ * convention for "the module that compiles to this file" — TypeScript's
+ * NodeNext maps `./Card.js` to `./Card.d.ts`, and so does this: the
+ * extension is stripped before the candidates are tried. Without that, a
+ * `.js`-suffixed re-export resolved to nothing, the imported names typed
+ * as `any`, and the checker reported zero errors on code it must reject
+ * (ggui 0.15.0 publish-gate, type-checker.test.ts).
  */
 function resolveRelativeInVfs(
   vfs: Map<string, VfsEntry>,
@@ -329,7 +337,9 @@ function resolveRelativeInVfs(
   // Strip leading '/' from containingFile — TS may prepend getCurrentDirectory()
   const normalized = containingFile.startsWith('/') ? containingFile.slice(1) : containingFile;
   const dir = path.posix.dirname(normalized);
-  const resolved = path.posix.normalize(`${dir}/${importPath}`);
+  // `./x.js` (`.mjs`, `.cjs`) names the declaration `./x.d.ts` — strip it.
+  const specifier = importPath.replace(/\.(?:m|c)?js$/, '');
+  const resolved = path.posix.normalize(`${dir}/${specifier}`);
 
   // Try .d.ts extension
   const withDts = `${resolved}.d.ts`;

package/src/coding-agent/tools.ts

@@ -18,6 +18,7 @@ import type {
   ToolResult,
   CommitMetadata,
 } from './types';
+import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
 
 /**
  * Extract documentation for a single component from the full primitives docs.
@@ -69,6 +70,8 @@ async function autoCommit(
    * stdlib hooks unconditionally.
    */
   gadgetTypes?: Readonly<Record<string, string>>,
+  /** Which tier-0 legs fire — see `runTier0Checks`'s `designMode`. */
+  designMode: DesignMode = DEFAULT_DESIGN_MODE,
 ): Promise<ToolResult> {
   const commitStart = Date.now();
   const raw = workspace.read();
@@ -118,6 +121,7 @@ async function autoCommit(
     contract,
     buildResult.errors,
     gadgetTypes,
+    designMode,
   );
   const tier0Fails = tier0Issues.filter(i => i.result === 'fail');
   const selfCheckPassed = tier0Fails.length === 0;
@@ -196,6 +200,8 @@ export async function executeTool(
    * callers omit it.
    */
   gadgetTypes?: Readonly<Record<string, string>>,
+  /** Which tier-0 legs fire on auto-commit — see `runTier0Checks`'s `designMode`. */
+  designMode: DesignMode = DEFAULT_DESIGN_MODE,
 ): Promise<ToolResult> {
   switch (tool) {
     case 'write':
@@ -216,7 +222,7 @@ export async function executeTool(
       const message = (input.commit_message as string) || `write ${lineCount} lines`;
 
       console.log(`[coding-agent] write: ${lineCount} lines → auto-commit`);
-      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes);
+      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode);
     }
 
     case 'apply_changes': {
@@ -523,7 +529,7 @@ export async function executeTool(
       const message = (input.commit_message as string) || 'apply changes';
 
       console.log(`[coding-agent] apply_changes: ${changes.length} changes applied → auto-commit`);
-      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes);
+      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode);
     }
 
     case 'get_components_info': {

package/src/contract-context.ts

@@ -35,6 +35,11 @@ import type {
 } from '@ggui-ai/protocol';
 import { HOOK_NAME_RE, listContractGadgets } from '@ggui-ai/protocol';
 import { propsSpecToTypeScript } from './check/index.js';
+import {
+  canvasDisplayModeForShell,
+  canvasForViewportWidth,
+  type CanvasClass,
+} from './design-mode.js';
 
 /**
  * Rendering context — how and where the component will be displayed.
@@ -87,6 +92,29 @@ const DEVICE_HINTS: Record<string, string> = {
   spatial: `**Spatial:** Fixed-size floating panel (~600x400). High contrast. Large text. No hover (gaze/hand input).`,
 };
 
+/**
+ * Map a host rendering context onto the canvas class the `free` prompt
+ * states and the visual evaluator judges at. The class is derived from
+ * DISPLAY MODE + width: a `chat` shell is always the inline card
+ * whatever the host viewport is (the bubble, not the window, bounds the
+ * component); a known viewport width refines the fullscreen / partial
+ * shells; otherwise the device category decides.
+ */
+export function canvasForRenderingContext(ctx: RenderingContext): CanvasClass {
+  const mode = canvasDisplayModeForShell(ctx.shell);
+  if (mode === 'inline') return 'xs-chat-card';
+  if (ctx.viewport) return canvasForViewportWidth(mode, ctx.viewport.width);
+  switch (ctx.device) {
+    case 'mobile':
+      return 'mobile-fullscreen-small';
+    case 'tablet':
+    case 'spatial':
+      return 'md';
+    case 'desktop':
+      return ctx.shell === 'partial' ? 'md' : 'lg';
+  }
+}
+
 /** Build rendering-context block to inject into user prompt. */
 export function buildRenderingContext(ctx: RenderingContext): string {
   const parts = [

package/src/create-harness.ts

@@ -20,6 +20,7 @@ import { defaultApplyPatch } from "./patch.js";
 import { computeHarnessId, computeHarnessName, hashClassification } from "./hash.js";
 import { pickWorkflow } from "./workflows.js";
 import { DEFAULT_HARNESS_POLICY, isDefaultHarnessPolicy } from "./policy.js";
+import { DEFAULT_DESIGN_MODE } from "./design-mode.js";
 import type {
   CreateHarnessInput,
   Harness,
@@ -69,6 +70,9 @@ function countCacheTiers(fragments: readonly { cacheTier: CacheTier }[]): Record
 export function createHarness(input: CreateHarnessInput): Harness {
   const { classification, contract, prompt, shellType, screen, overrides } = input;
   const ctx: HarnessConstructionContext = { classification, contract, prompt };
+  // Which triad to materialise — reaches the HOW leg (prompt), the WHAT
+  // leg (boilerplate) and, via `harness.designMode`, every CHECK consumer.
+  const designMode = input.designMode ?? DEFAULT_DESIGN_MODE;
 
   // ── Compose fragments from classification ────────────────────────────────
   const composed = compose(classification);
@@ -84,6 +88,8 @@ export function createHarness(input: CreateHarnessInput): Harness {
     shellType,
     screen,
     axisDelta: composed.promptText,
+    designMode,
+    ...(input.canvas !== undefined ? { canvas: input.canvas } : {}),
   });
   const howFragments = composed.fragments.filter(
     (f) => f.promptText && f.promptText.trim().length > 0,
@@ -112,6 +118,7 @@ export function createHarness(input: CreateHarnessInput): Harness {
     screen,
     composed.boilerplateSections,
     input.appGadgets,
+    designMode,
   );
   const whatFragments = composed.fragments.filter(
     (f) => f.boilerplateMarker && f.boilerplateMarker.trim().length > 0,
@@ -179,6 +186,9 @@ export function createHarness(input: CreateHarnessInput): Harness {
   // Only non-default policies contribute to the harness id — preserves
   // byte-identical id across default-policy runs.
   if (!isDefaultHarnessPolicy(policy)) overrideLabels.push("policy");
+  // 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}`);
 
   const id = computeHarnessId({
     classificationHash,
@@ -210,6 +220,7 @@ export function createHarness(input: CreateHarnessInput): Harness {
     id,
     name,
     classification,
+    designMode,
     how,
     what,
     check,

package/src/create-ui-generator.ts

@@ -35,7 +35,10 @@ 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,
@@ -53,19 +56,22 @@ import {
 import { createGeneratorTools } from './adapters/index.js';
 import { dispatchGeneration } from './adapters/generation-dispatch.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 { 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 {
   /**
@@ -86,24 +92,25 @@ export interface CreateUiGeneratorOptions {
   /** 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 +170,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(
@@ -176,6 +212,8 @@ export function createUiGenerator(
     gadgetCatalog,
     disableEnvMutation = false,
     onRetry,
+    onGenerated,
+    designMode,
   } = options;
 
   const identity = resolveIdentity(options);
@@ -268,6 +306,10 @@ 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,
@@ -316,12 +358,16 @@ export function createUiGenerator(
           enableRuntimeRender,
           ...(routeOverride !== undefined ? { routeOverride } : {}),
           ...(onRetry !== undefined ? { onRetry } : {}),
+          ...(designMode !== undefined ? { designMode } : {}),
+          ...(canvas !== undefined ? { canvas } : {}),
         });
 
+        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 +408,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 +427,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 +488,7 @@ function mapRendering(
 
 function failWithoutMetadata(
   input: UiGenerateInput,
-  generatorSlug: string,
+  generatorSlug: GeneratorId,
   startedAt: number,
   error: GenerationError,
 ): UiGenerateResult {
@@ -452,7 +498,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,