@ggui-ai/ui-gen 0.15.0 → 0.17.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 ─────────────────────────────────────────
   //
@@ -371,6 +412,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',
@@ -494,6 +536,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()}`,
@@ -591,7 +634,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 +659,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 +670,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 +738,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 +755,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 +784,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 +801,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 +855,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 +923,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 +1377,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/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

@@ -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,
@@ -35,20 +37,19 @@ 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.
- * 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**
@@ -61,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.
@@ -87,6 +88,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 = [
@@ -355,7 +379,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}`);
@@ -383,6 +410,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');
@@ -392,9 +420,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";
@@ -20,6 +21,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 +71,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 +89,9 @@ export function createHarness(input: CreateHarnessInput): Harness {
     shellType,
     screen,
     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,
@@ -112,6 +120,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 +188,10 @@ 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}`);
+  if (hasProfile(input.profile)) overrideLabels.push("profile");
 
   const id = computeHarnessId({
     classificationHash,
@@ -210,6 +223,8 @@ export function createHarness(input: CreateHarnessInput): Harness {
     id,
     name,
     classification,
+    designMode,
+    ...(input.profile !== undefined ? { profile: input.profile } : {}),
     how,
     what,
     check,