@ggui-ai/ui-gen 0.14.0 → 0.16.0

package/dist/harness/types-public.js

@@ -2,6 +2,7 @@ import { resolveAppGadgets, listContractGadgets, HOOK_NAME_RE } from '@ggui-ai/p
 import { readFileSync } from 'fs';
 import { dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { consumedTokenManifest } from '@ggui-ai/design/themes';
 import ts from 'typescript';
 import { createHash } from 'crypto';
 
@@ -93,7 +94,8 @@ async function runCheck(input) {
     compiledCode,
     contract,
     originalPrompt: prompt,
-    classification: harness.classification
+    classification: harness.classification,
+    designMode: harness.designMode
   };
   let axisIssueCount = 0;
   const seenAxisIds = /* @__PURE__ */ new Set();
@@ -644,6 +646,63 @@ function compose(classification) {
     fragments: matched
   };
 }
+
+// src/design-mode.ts
+var DEFAULT_DESIGN_MODE = "constrained";
+function canvasDisplayModeForShell(shell) {
+  return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
+}
+function canvasForRendering(shellType, screen) {
+  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";
+  }
+}
+var CANVAS_DESCRIPTORS = {
+  "xs-chat-card": {
+    label: "extra-small chat card",
+    minWidthPx: 320,
+    maxWidthPx: 480,
+    host: "an inline card inside a chat message bubble \u2014 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 \u2014 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) \u2014 one or two columns, medium density"
+  },
+  lg: {
+    label: "large fullscreen",
+    minWidthPx: 1024,
+    maxWidthPx: 1439,
+    host: "a desktop viewport the component owns edge to edge \u2014 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 \u2014 cap content width or use the extra room deliberately; never stretch a single column across the whole width"
+  }
+};
+function describeCanvas(canvas) {
+  const d = CANVAS_DESCRIPTORS[canvas];
+  return `This component renders on the \`${canvas}\` canvas (${d.label}): ${d.minWidthPx}\u2013${d.maxWidthPx}px wide, ${d.host}. Design for the whole range \u2014 the host may size the iframe anywhere inside it.`;
+}
+
+// src/boilerplate/render.ts
 var __dirname$1 = dirname(fileURLToPath(import.meta.url));
 var TEMPLATE_DIRS = [
   resolve(__dirname$1, "templates"),
@@ -652,19 +711,31 @@ var TEMPLATE_DIRS = [
   resolve(__dirname$1, "..", "..", "..", "src", "boilerplate", "templates"),
   resolve(__dirname$1, "..", "..", "..", "..", "src", "boilerplate", "templates")
 ];
-var baseCache = null;
+var BASE_TEMPLATE_FILE = {
+  constrained: "base.tsx.tmpl",
+  free: "base-free.tsx.tmpl"
+};
+var FREE_LAYOUT = [
+  "    <div style={{ width: '100%' }}>",
+  "      {/* implement your UI here */}",
+  "    </div>"
+].join("\n");
+var baseCache = /* @__PURE__ */ new Map();
 var layoutCache = /* @__PURE__ */ new Map();
-function loadBase() {
-  if (baseCache) return baseCache;
+function loadBase(designMode) {
+  const cached = baseCache.get(designMode);
+  if (cached !== void 0) return cached;
+  const file = BASE_TEMPLATE_FILE[designMode];
   for (const dir of TEMPLATE_DIRS) {
     try {
-      baseCache = readFileSync(resolve(dir, "base.tsx.tmpl"), "utf-8");
-      return baseCache;
+      const content = readFileSync(resolve(dir, file), "utf-8");
+      baseCache.set(designMode, content);
+      return content;
     } catch {
       continue;
     }
   }
-  throw new Error("No base.tsx.tmpl found");
+  throw new Error(`No ${file} found`);
 }
 function loadLayout(shellType, screen) {
   const key = `${shellType}-${screen}`;
@@ -688,9 +759,9 @@ function loadLayout(shellType, screen) {
   }
   throw new Error(`No layout found for ${key}`);
 }
-function renderBoilerplate(shellType, screen, markers) {
-  let template = loadBase();
-  const layout = loadLayout(shellType, screen);
+function renderBoilerplate(shellType, screen, markers, designMode = DEFAULT_DESIGN_MODE) {
+  let template = loadBase(designMode);
+  const layout = designMode === "free" ? FREE_LAYOUT : loadLayout(shellType, screen);
   template = template.replace("{{LAYOUT}}", layout);
   for (const [key, value] of Object.entries(markers)) {
     template = template.replaceAll(`{{${key}}}`, value);
@@ -867,7 +938,7 @@ function inferTypeFromExample(example) {
   }
   return `{ ${fields.join("; ")} }`;
 }
-function generateBoilerplate(_userPrompt, contract, shellType, screen, composedSections, appGadgets) {
+function generateBoilerplate(_userPrompt, contract, shellType, screen, composedSections, appGadgets, designMode = DEFAULT_DESIGN_MODE) {
   const propsFields = [];
   const propsProperties = contract?.propsSpec?.properties ?? {};
   for (const [key, entry] of Object.entries(propsProperties)) {
@@ -1049,7 +1120,7 @@ ${body}
     CONTEXT_HOOKS: contextHooks,
     WIRE_HOOKS: hookBody,
     AXIS_SECTIONS: composedSections ?? ""
-  });
+  }, designMode);
 }
 
 // src/evaluation/types-public.ts
@@ -1230,14 +1301,45 @@ Intentional custom colors (status indicators) are acceptable when no semantic to
 Only list ACTUAL violations. Use 'fail' only for pervasive violations.`
   }
 ];
-function getCriteriaByPriority(priority) {
-  return CRITERIA.filter((c) => c.priority === priority);
+var FREE_DESIGN_CRITERIA_OVERRIDES = [
+  {
+    id: "tokens",
+    name: "Color tokens",
+    priority: "P1",
+    tier: 0,
+    failOutcome: "warn",
+    codingGuidance: "Every color is a bare var(--ggui-color-*) from the token manifest \u2014 no hex, rgb()/hsl(), CSS named colors or literal fallbacks, in style props and <style> blocks alike. Spacing, typography, radius and shadow geometry may be literals.",
+    evalInstruction: "Flag hardcoded hex colors, rgba/hsl functions, CSS named colors, and literal fallbacks inside var(--ggui-*) references. Do NOT flag literal spacing, font sizes, radii or pixel values \u2014 they are allowed in this mode."
+  },
+  {
+    id: "visual",
+    name: "Visual composition",
+    priority: "P2",
+    tier: 2,
+    failOutcome: "warn",
+    codingGuidance: "Compose deliberately: one clear focal point, consistent spacing rhythm, a coherent theme-token palette, a fit to the rendering canvas.",
+    evalInstruction: `Evaluate VISUAL COMPOSITION: Is the component composed deliberately for its canvas?
+
+Judge: visual hierarchy (one clear focal point, headings distinct from body text), consistent spacing rhythm and alignment, a coherent palette drawn from the theme tokens, fit to the canvas (fluid width, no fixed widths, nothing cramped or stretched).
+Do NOT reward or penalise the use of design-system primitives \u2014 raw HTML with inline CSS is a first-class choice here. Literal spacing / typography / radius values are fine.
+
+Only list ACTUAL composition problems. Use 'fail' only for a fundamentally incoherent composition.`
+  }
+];
+function criteriaFor(designMode = "constrained") {
+  if (designMode === "constrained") return CRITERIA;
+  return CRITERIA.map(
+    (c) => FREE_DESIGN_CRITERIA_OVERRIDES.find((o) => o.id === c.id) ?? c
+  );
 }
-function buildCodingCriteriaSummary() {
+function getCriteriaByPriority(priority, designMode = "constrained") {
+  return criteriaFor(designMode).filter((c) => c.priority === priority);
+}
+function buildCodingCriteriaSummary(designMode = "constrained") {
   const lines = ["## Priority (P0 first, then P1, then P2)", ""];
   for (const priority of ["P0", "P1", "P2"]) {
     const label = priority === "P0" ? "Must (compile + complete)" : priority === "P1" ? "Should (safety)" : "Nice (quality)";
-    const criteria = getCriteriaByPriority(priority);
+    const criteria = getCriteriaByPriority(priority, designMode);
     lines.push(`**${priority} \u2014 ${label}:**`);
     for (const c of criteria) {
       lines.push(`- ${c.codingGuidance}`);
@@ -1246,6 +1348,427 @@ function buildCodingCriteriaSummary() {
   }
   return lines.join("\n");
 }
+
+// src/boilerplate/hard-sections.ts
+var PROTOCOL_NOTES = `## Protocol Notes
+The boilerplate pre-declares every wire hook the contract requires (\`useAction\`, \`useStream\`, \`useGguiContext\`, plus capability hooks from \`@ggui-ai/gadgets\` when the contract declares \`clientCapabilities\`). Three rules:
+1. **Do NOT delete any pre-declared hook.** \`self_check\` fails with \`wire_preservation:<kind>:<name>\` if you remove one.
+2. **Consume every hook binding** somewhere in the component \u2014 in JSX, a callback, or an effect. Unused bindings fail lint with \`no-unused-vars\`.
+3. **Do NOT invent new wire calls.** Every \`useAction('X')\`, \`useStream('X')\`, \`useGguiContext('X')\` etc. MUST correspond to a declared entry on the contract. Calling one that isn't declared fails \`self_check\` with \`wire_undeclared:<kind>:<name>\` because the runtime has no Context/registration for it and would throw at first paint. If you need a new wire surface, that's a contract authoring step the agent owns \u2014 your job is to honor what's declared.
+
+Renaming a binding is fine \u2014 the wiring is the string-literal argument, not the identifier.`;
+var CONTRACT_SURFACE = `## Contract surface \u2014 four specs + two catalogs
+
+A \`DataContract\` declares everything a GguiSession exchanges with the outside world. **Four typed specs** for the four data-flow directions, **two reference catalogs** for tool / hook lookups:
+
+| Surface              | Direction                  | Role                                                                 |
+| -------------------- | -------------------------- | -------------------------------------------------------------------- |
+| \`propsSpec\`         | server \u2192 UI (one-shot)     | Initial render values delivered once at \`ggui_render\`              |
+| \`streamSpec\`        | agent \u2192 UI (many)          | Typed channels for live updates via \`ggui_emit\`                    |
+| \`actionSpec\`        | UI \u2192 agent (events)        | Discrete events driving the agent's next turn (consumed via \`ggui_consume\`) |
+| \`contextSpec\`       | UI \u2192 server (state mirror) | UI state the agent observes between turns                            |
+| \`agentCapabilities.tools\`     | catalog                    | Tools the contract references via \`actionSpec[*].nextStep\` and \`streamSpec[*].source.tool\` |
+| \`clientCapabilities.gadgets\` | catalog                    | Browser-capability gadget hooks the component code mounts (e.g., \`useGeolocation\`) |
+
+**Placement rule for inbound specs**: actions drive turns; context observes state. There is no third category.
+
+**Data vs behavior**: the contract describes data flow; the component code describes behavior. Scroll, focus, toast, animation, clipboard write \u2014 all component code, never contract fields.`;
+var DEFENSIVE_CODING = `## Defensive coding for absent / late-arriving data
+
+Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
+
+- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY \u2014 the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
+- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
+- **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
+- **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
+- **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives \u2014 guard before reading \`.foo\`.
+- **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed \u2014 your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list \u2014 and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
+- **Props re-sync on repaint**: props the agent owns are the source of truth for display \u2014 prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change \u2014 \`useEffect(() => setCount(props.count ?? 0), [props.count])\` \u2014 or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
+- **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders \u2014 never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
+- **Empty state**: when a list or results array is empty, render \`<EmptyState title="\u2026" description="\u2026" />\` \u2014 a region that renders nothing when empty looks broken to the user.
+
+Unhandled \`Cannot read properties of undefined\` errors trip the iframe error boundary and the user sees "Something went wrong" \u2014 a regression class the runtime can't recover from.`;
+var GESTURE_ROUTING = `## Picking the right primitive for user gestures
+
+Choose by what the user is DOING, not where the result goes \u2014 the runtime handles the routing.
+
+| Gesture intent | LLM writes | Notes |
+| -------------- | ---------- | ----- |
+| Fire a server-side action | \`useAction(name)\` + call \`dispatch(name, payload)\` | Every action is agent-routed. The runtime emits an event on \`ggui_consume\`; the agent reacts on its next turn. If the contract entry declares \`nextStep: 'X'\`, that names the tool the agent SHOULD call next \u2014 advisory hint forwarded as event metadata. |
+| Surface state to the agent's context | the auto-generated \`setSlotName\` setter (from the boilerplate's \`useGguiContext\` line) | The runtime owns useState + Provider; the boilerplate emits one \`const [slot, setSlot] = useGguiContext<T>('slot')\` line per declared \`contextSpec\` slot. Write plain JSX, no \`useState\`, no Provider wrap. Every value change auto-flows to the host LLM (debounced). One-way client \u2192 agent \u2014 see "Observable state via \`contextSpec\`" below. |
+| Use a browser capability (camera, mic, geolocation, clipboard, file picker, notifications) | call the hook the contract declared, e.g., \`const loc = useGeolocation();\` and \`await loc.start()\` | The contract's \`clientCapabilities.gadgets\` declares which gadget exports the UI uses. The hook implementations live in \`@ggui-ai/gadgets\` (or a third-party package named in the \`Package\` column). Read \`status\` ("idle" / "prompting" / "active" / "completed" / "denied" / "error") to gate UI, and thread the resolved \`value\` into a contextSpec slot or actionSpec payload if the agent needs to see it. |
+| Open external link | Plain \`<a href="https://...">\` (or \`target="_blank"\`) | External cross-origin clicks are intercepted and routed through the host (security warnings, app-internal navigation, audit). Same-origin links and \`#fragment\` jumps stay native. |
+| Toggle fullscreen / chrome | Plain \`el.requestFullscreen()\` / \`document.exitFullscreen()\` | The native browser API is intercepted; the host adjusts iframe chrome accordingly. Returns a resolved promise so \`.then()\` / \`await\` chains don't break. |
+
+Every gesture fires a uniform server-side audit envelope (\`ggui_runtime_submit_action\`) so operators see all three patterns in RenderInspector with the same shape.
+
+**Don't import wire hooks for link / display-mode.** \`useAction\` is the only wire hook for user gestures; links and fullscreen use plain HTML / browser APIs.
+
+**All actions are agent-routed.** Every action emits an event the agent reacts to on its next turn via \`ggui_consume\`. The optional \`nextStep: '<tool>'\` field on an \`actionSpec\` entry is a HINT naming the tool the agent SHOULD call next \u2014 the contract author's recommendation, NOT a binding directive. The agent decides whether to honor it. If you want to declare a tool catalog entry the contract references, add it to \`agentCapabilities.tools[<name>]\` with input/output schemas; the cross-ref linter rejects dangling \`nextStep\` values that don't resolve to a declared catalog entry.`;
+var INTERACTIVE_TRAITS = `## Making a primitive interactive \u2014 \`as={Trait}\`
+
+Structural primitives (\`Box\`, \`Stack\`, \`Row\`, \`Card\`) have NO \`onClick\` by default. Add interactivity with the \`as\` prop \u2014 a trait, not a wrapper:
+
+\`\`\`tsx
+<Card as={Clickable} onClick={() => dispatch('select', { id })}
+      hoverStyle={{ boxShadow: 'var(--ggui-shape-shadow-lg)' }}>\u2026</Card>
+\`\`\`
+
+- \`as={Clickable}\` \u2192 \`onClick\` + keyboard activation (Enter/Space) + \`role="button"\` + \`hoverStyle\`/\`activeStyle\`/\`cursor\`.
+- \`as={Hoverable}\` \u2192 \`hoverStyle\` only (no click). \`as={Pressable}\` \u2192 \`onPress\` + \`pressStyle\`.
+
+\`as={Trait}\` is a PROP \u2014 it does NOT re-nest the JSX. Never write \`<Clickable>\u2026</Clickable>\` around a primitive; put \`as={Clickable}\` on the primitive itself. The trait carries the keyboard + ARIA wiring, so don't hand-write \`onKeyDown\` / \`role\`. Trait components (\`Clickable\`, \`Hoverable\`, \`Pressable\`) import from \`@ggui-ai/design\` like everything else \u2014 the boilerplate already imports them.
+
+**Semantic components are already interactive** \u2014 \`Button\` (\`onClick\`), \`Link\` (\`href\`), \`Input\` / \`Select\` (\`onChange\`). Use their own props; never put \`as\` on them. \`Text\` picks its element with \`is\` (\`<Text is="label">\`), not \`as\`.
+
+**Never nest two interactive elements.** Interactive content MUST NOT contain other interactive content \u2014 a gesture on the inner control bubbles to the outer one and fires BOTH handlers (one user click \u2192 the action dispatched twice). Do NOT put a \`Button\`, \`Checkbox\`, \`Input\`, \`Select\`, \`Link\`, or another \`as={Clickable}\` primitive inside a \`Card\` / \`Box\` / \`Row\` / \`Stack\` that is itself \`as={Clickable}\`. Wire each \`useAction\` callback to exactly ONE surface: EITHER the whole card is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container, no \`as={Clickable}\`) \u2014 never both. A row with a checkbox: put the action on the \`Checkbox onChange\` and leave the row plain.
+
+**\`Text\` / \`Heading\` accept NO event handlers and NO \`as\` \u2014 only \`style\` / \`className\` plus their own typed props.** \`onClick\`, \`onDoubleClick\`, \`as={Clickable}\`, \`color\` are all type errors on \`Text\`. When the request says a label is "clickable", "editable", "edit on click / double-click", or "tap to \u2026", do ONE of these \u2014 never put the handler on \`Text\`:
+
+\`\`\`tsx
+// Click-to-edit a label: wrap the Text in a Clickable structural primitive.
+<Box as={Clickable} onClick={() => setEditingId(task.id)}
+     style={{ cursor: 'pointer' }}>
+  <Text weight="semibold">{task.title}</Text>
+</Box>
+
+// Or pair the label with an explicit edit Button (clearer affordance).
+<Row gap="xs" align="center">
+  <Text weight="semibold">{task.title}</Text>
+  <Button variant="ghost" size="xs" aria-label="Edit title"
+          onClick={() => setEditingId(task.id)}>Edit</Button>
+</Row>
+
+// In edit mode, swap the Text for an Input.
+{editingId === task.id
+  ? <Input value={draftTitle} onChange={setDraftTitle} label="Task title" />
+  : <Text weight="semibold">{task.title}</Text>}
+\`\`\``;
+var ANTI_PATTERNS = `## Anti-patterns \u2014 DO NOT WRITE
+
+The following identifiers / shapes are RETIRED from the contract surface as of 2026-05-11. Pre-2026-05-11 examples in your training data may include them; do not reproduce. The linter / CI grep gate rejects:
+
+- \`useWiredTool\`, \`useClientTool\` \u2014 retired hooks. Replace with \`useAction\` (events) and the named hook from \`@ggui-ai/gadgets\` (browser capabilities).
+- \`dispatch: { kind: 'tool', tool: '...' }\` / \`dispatch: { kind: 'agent', intendedTool: '...' }\` \u2014 retired discriminated-union. Use the flat optional \`nextStep?: '<tool>'\` instead.
+- \`mode: 'host-routed'\` / \`mode: 'tool'\` \u2014 retired \`mode\` field. Same fix: flat \`nextStep?\`.
+- \`broadcast: {...}\` on the contract \u2014 retired top-level field. Use \`streamSpec[channel].source: {tool, args?}\` to declare a tool-fed channel.
+- \`wiredTools\` / \`agentTools\` (top-level) \u2014 retired catalog names. Use \`agentCapabilities.tools\`.
+- \`clientTools\` / \`clientCapabilities.capabilities\` \u2014 retired catalog shapes. Use \`clientCapabilities.gadgets\` (entries declare hooks, not RPC).
+- \`@ggui-ai/client-tools\` \u2014 retired package name. Import gadget hooks from \`@ggui-ai/gadgets\`.
+- \`intendedTool\` \u2014 retired. Use \`nextStep\` (flat).
+- \`props: { properties: {...} }\` as a CONTRACT field \u2014 retired. The contract field is \`propsSpec\` (the wire \`props\` field on render / update still carries VALUES).`;
+var CROSS_REFERENCE_RULES = `## Cross-reference rules
+
+When you declare a reference, also declare the catalog entry it points at:
+
+- \`actionSpec[X].nextStep = 'fetch_inbox'\` \u2192 \`agentCapabilities.tools.fetch_inbox = { toolInfo: { inputSchema, description?, outputSchema? }, usage?, example? }\` MUST exist. Cross-ref code: \`CTR_REF_NEXT_STEP\`.
+- \`streamSpec[X].source.tool = 'list_messages'\` \u2192 \`agentCapabilities.tools.list_messages\` MUST exist. Cross-ref code: \`CTR_REF_STREAM_SOURCE\`.
+- The catalog entry's schemas MUST be a superset of the referencing spec's schema. Cross-ref code: \`CTR_SCHEMA_INCOMPAT\`.`;
+function renderGadgetCatalogSection(gadgetsSection) {
+  return `## clientCapabilities \u2014 registered catalog
+
+${gadgetsSection}
+
+Each hook conforms to \`GadgetHook<TOutput, TOptions>\`: call \`start(opts?)\` to fire, read \`{value, status, error, stop?}\`. \`status\` walks through \`idle \u2192 prompting \u2192 active|completed\` or routes to \`denied\` / \`error\` on failure.
+
+3rd-party plugins (Leaflet maps, Mapbox, Stripe, Chart.js, \u2026) are registered via \`createGguiGadget\` from \`@ggui-ai/gadgets\` and surface in this same table when the operator has added them to \`App.gadgets\`. Reference any registered hook by name \u2014 render validation rejects hooks not in this catalog with \`gadget_not_registered\`.`;
+}
+var CONTEXT_SPEC_SECTION = `## Observable state via \`contextSpec\`
+
+When the contract declares \`contextSpec\`, the boilerplate auto-generates one \`useGguiContext\` call per slot at the top of your component. The runtime owns the underlying \`useState\` and the Provider tree \u2014 **you do NOT write \`useState\` or any \`<Provider>\` wrap yourself**:
+
+\`\`\`tsx
+import { useGguiContext } from '@ggui-ai/wire';
+
+export default function Component(props: Props) {
+  // AUTO-GENERATED \u2014 do not remove or rename:
+  const [currentStep, setCurrentStep] = useGguiContext<number>('currentStep');
+  const [draftText, setDraftText] = useGguiContext<string>('draftText');
+
+  // Plain JSX. No Provider wrap. The runtime already wrapped your
+  // component in nested SingleSlotProviders before this code ran.
+  return (
+    <Container>
+      <Text>Step {currentStep}</Text>
+      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
+      <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
+    </Container>
+  );
+}
+\`\`\`
+
+For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
+- **Read** the value to render: \`<Text>Step {currentStep}</Text>\`
+- **Write** via the setter: \`setCurrentStep(s => s + 1)\` (in callbacks, effects, anywhere)
+
+Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms \u2014 adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state \u2014 drafts, current step, hover, selection \u2014 without you calling any API.
+
+**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
+
+**When NOT to use it.** Local UI state the contract did NOT declare \u2014 \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
+
+**\`contextSpec\` direction is one-way: client \u2192 agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` \u2014 there is no return path.
+
+**Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.`;
+var DATA_PARAMETERIZATION = `## Data Parameterization (CRITICAL)
+
+Generated components are CACHED blueprints reused across requests. NEVER hardcode request-specific data (names, cities, numbers, dates) into the component body. Define data as default prop values so the blueprint works for ANY similar request:
+
+\`\`\`tsx
+// BAD \u2014 hardcoded, only works for Tokyo
+const city = "Tokyo";
+const temp = 18;
+
+// GOOD \u2014 parameterized via props with defaults from the request
+interface Props {
+  city?: string;
+  temperature?: number;
+}
+export default function WeatherCard({ city = "Tokyo", temperature = 18 }: Props) {
+  // A controller can override for Seoul, Paris, etc.
+}
+\`\`\`
+
+Rules:
+1. All request-specific data \u2192 props with defaults. City names, tickers, user names, dates, counts.
+2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
+3. Default values come from the current request \u2014 so the component renders correctly standalone.
+4. Props interface must be typed and exported.`;
+var COMPONENT_STRUCTURE = `## Component Structure
+
+Keep JSX nesting depth to 3\u20135 levels. When deeper, extract repeated/complex sections into helper components \u2014 named functions defined above the main Component in the same file. Helpers take data + callbacks via props; they don't own state.
+
+\`\`\`tsx
+import { useState } from 'react';
+import { Container, Card, Stack, Text, Button, Input } from '@ggui-ai/design';
+
+interface Props {
+  onSubmit?: (data: unknown) => void;
+}
+
+function ItemCard({ item, onEdit }: { item: Item; onEdit: (id: string) => void }) {
+  return <Card padding="md">\u2026</Card>;
+}
+
+export default function GeneratedComponent({ onSubmit }: Props) {
+  return (
+    <Container>
+      {items.map((item) => <ItemCard key={item.id} item={item} onEdit={handleEdit} />)}
+    </Container>
+  );
+}
+\`\`\``;
+
+// src/boilerplate/free-design-prompt.ts
+var FREE_GESTURE_SURFACE = `## One gesture surface per action binding
+
+Every \`useAction\` binding is wired to exactly ONE interactive surface. Interactive content MUST NOT contain other interactive content that dispatches the same binding \u2014 a click on the inner control bubbles to the outer handler and the action fires TWICE, so a toggle-style action silently reverts the user's change. Concretely: never put a \`<button>\`, \`<a>\`, \`<input>\`, \`<select>\`, an element with \`role="button"\`, or any element with its own \`onClick\`, inside a \`<div>\` / \`<li>\` / \`<tr>\` / \`<Card>\` whose own \`onClick\` calls the same binding. EITHER the whole row is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container) \u2014 never both. Tier-0 fails the nested shape with \`double-wired-action:certain\`. A row with a checkbox: put the action on the checkbox's \`onChange\` and leave the row plain. \`stopPropagation\` is not a fix \u2014 pick one surface.`;
+var FREE_DESIGN_FREEDOM = `## Design freedom
+
+You are not required to compose from the \`@ggui-ai/design\` primitives. Compose with raw HTML elements (\`<div>\`, \`<section>\`, \`<button>\`, \`<input>\`, \`<ul>\`, \`<table>\`, \u2026), inline \`style\` props and \`<style>\` blocks \u2014 regular CSS, \`@media\` and \`@container\` queries, \`@keyframes\`, \`:hover\` / \`:focus-visible\` (the host CSP permits \`'unsafe-inline'\` styles). Any layout: CSS grid, flexbox, absolute positioning, sticky headers. The runtime injects NO Tailwind and NO reset stylesheet \u2014 a raw element renders unstyled until your CSS styles it, so bring the CSS you need. Use class selectors in \`<style>\` blocks (an \`#id\` selector that reads as hex digits trips the color check).
+
+\`@ggui-ai/design\` stays importable \u2014 \`import { Skeleton, EmptyState, Icon } from '@ggui-ai/design'\` \u2014 use a primitive when it saves work, skip it when it constrains you. Its props are documented in the optional catalog at the end of this prompt.
+
+Spacing, typography, radius, shadow geometry and layout values MAY be literals: \`padding: '20px'\`, \`fontSize: 'clamp(1rem, 2vw, 1.5rem)'\`, \`borderRadius: 12\`, \`gap: '0.75rem'\`, \`boxShadow: '0 8px 24px var(--ggui-color-outlineVariant)'\`. Color is the one exception \u2014 next section.`;
+var COLOR_PREFIX = "--ggui-color-";
+var RAMP_FAMILIES = ["primary", "neutral", "success", "warning", "error", "info"];
+var SEMANTIC_ROLES = [
+  { names: ["ground", "onGround"], role: "the page / chat canvas behind everything + its text" },
+  { names: ["container", "onContainer"], role: "a card, a bubble, a panel + body text on it" },
+  { names: ["elevated", "onElevated"], role: "popover, menu, modal, toast \u2014 floats above a container" },
+  { names: ["sunken", "onSunken"], role: "wells, inputs at rest, code blocks + secondary text" },
+  { names: ["ground-subtle", "ground-gradient"], role: "quiet canvas fills" },
+  { names: ["onPrimary"], role: "text on the brand color" },
+  { names: ["outline", "outlineVariant"], role: "borders + dividers" },
+  { names: ["onError"], role: "text on an error fill" }
+];
+function colorVocabularyFromManifest(manifest) {
+  const colors = manifest.filter((t) => t.startsWith(COLOR_PREFIX)).map((t) => t.slice(COLOR_PREFIX.length));
+  const ramps = [];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const family of RAMP_FAMILIES) {
+    const steps = [];
+    for (const name of colors) {
+      const m = new RegExp(`^${family}-(\\d+)$`).exec(name);
+      if (m) {
+        steps.push(Number(m[1]));
+        claimed.add(name);
+      }
+    }
+    if (steps.length === 0) continue;
+    steps.sort((a, b) => a - b);
+    const bare = colors.includes(family);
+    if (bare) claimed.add(family);
+    ramps.push({ family, steps, bare });
+  }
+  const roles = colors.filter((n) => !claimed.has(n)).sort();
+  return { ramps, roles };
+}
+function renderRamp(r) {
+  return `\`${r.family}-${r.steps.join("/")}\`${r.bare ? ` (plus bare \`${r.family}\`)` : ""}`;
+}
+function renderFreeColorRule(manifest = consumedTokenManifest) {
+  const { ramps, roles } = colorVocabularyFromManifest(manifest);
+  const brand = ramps.filter((r) => r.family === "primary" || r.family === "neutral");
+  const state = ramps.filter((r) => r.family !== "primary" && r.family !== "neutral");
+  const roleLines = [];
+  const named = /* @__PURE__ */ new Set();
+  for (const g of SEMANTIC_ROLES) {
+    const present = g.names.filter((n) => roles.includes(n));
+    if (present.length === 0) continue;
+    for (const n of present) named.add(n);
+    roleLines.push(`${present.map((n) => `\`${n}\``).join(" / ")} (${g.role})`);
+  }
+  const other = roles.filter((n) => !named.has(n));
+  if (other.length > 0) roleLines.push(`other roles: ${other.map((n) => `\`${n}\``).join(", ")}`);
+  const vocabulary = [
+    roleLines.length > 0 ? `- Semantic roles cover most needs: ${roleLines.join("; ")}.` : "",
+    brand.length > 0 ? `- Brand + neutral ramps (every step that exists, nothing else): ${brand.map(renderRamp).join(", ")}.` : "",
+    state.length > 0 ? `- State ramps (every step that exists, nothing else): ${state.map(renderRamp).join(", ")}.` : "",
+    "- A step not listed does not exist and renders unset; pick the nearest listed step."
+  ].filter((l) => l.length > 0).join("\n");
+  return `## Color stays tokenized (the one hard styling rule)
+
+Brand-bearing color \u2014 text, backgrounds, borders, fills, gradient stops, focus rings, shadow tints \u2014 comes ONLY from the closed \`--ggui-color-*\` token manifest, referenced BARE: \`color: 'var(--ggui-color-onContainer)'\`, \`background: 'var(--ggui-color-primary-50)'\`, \`border: '1px solid var(--ggui-color-outline)'\`, \`linear-gradient(135deg, var(--ggui-color-primary-500), var(--ggui-color-primary-700))\`.
+
+- No hex (\`#7c3aed\`), no \`rgb()\` / \`rgba()\` / \`hsl()\` / \`hsla()\`, no CSS named colors (\`red\`, \`slategray\`) \u2014 anywhere in the file, including \`<style>\` blocks and shadows. Tier-0 fails them (\`tokens:hex-color\`, \`tokens:hardcoded-color-fn\`, \`tokens:named-color\`). \`transparent\`, \`currentColor\` and \`inherit\` are fine.
+- No literal fallback inside ANY token reference: \`var(--ggui-color-primary-600)\` bare, never \`var(--ggui-color-primary-600, #0284c7)\` \u2014 the runtime injects every token on \`:root\`, and a fallback paints the wrong brand exactly when the operator's theme matters (\`tokens:token-fallback\`). This holds for every \`--ggui-*\` token you reference, not only colors.
+- Only names from the manifest (listed at the end of this prompt) exist \u2014 an invented \`--ggui-color-*\` name renders unset (\`tokens:off-manifest-token\`).
+- Shadows: \`var(--ggui-shape-shadow-sm|md|lg|xl)\`, or a literal offset/blur whose color is a token \u2014 never an \`rgba()\` tint.
+- Why: the operator switches the whole app's theme (light, dark, branded) by redefining these variables. A component that reads them is on-brand everywhere; one that hardcodes color is off-brand everywhere but the default.
+
+The color vocabulary (rendered from the manifest \u2014 these names and steps, exactly):
+${vocabulary}`;
+}
+var FREE_COLOR_RULE = renderFreeColorRule();
+var FREE_HOST_ENVELOPE = `## Where this renders
+
+The compiled component is loaded into a sandboxed iframe by an MCP Apps host (chat clients, the ggui console, embedded panels):
+
+- **Sandbox**: \`allow-scripts allow-forms\`, no same-origin. The only channel to the outside is \`postMessage\` through the wire hooks \u2014 the component never talks to a server itself.
+- **No network from the component**: \`fetch\`, \`XMLHttpRequest\`, \`WebSocket\`, dynamic \`import()\` fail tier-0 and the CSP (\`connect-src 'none'\` on spec hosts). No \`<link rel="stylesheet">\`, no \`@import url()\`, no CDN scripts, no web fonts from a CDN \u2014 use \`var(--ggui-font-family-sans)\` / \`var(--ggui-font-family-mono)\` (system stacks) or a generic family.
+- **No host document access**: \`window.*\`, \`document.*\` (other than the intercepted \`requestFullscreen\` / \`exitFullscreen\`), \`localStorage\`, \`sessionStorage\`, \`navigator\`, \`location\`, \`history\`, \`innerHTML\` / \`dangerouslySetInnerHTML\`, \`<script>\` \u2014 all rejected.
+- **Props arrive through \`_meta["ai.ggui/render"]\`** on the host side and reach you as \`props\`; later repaints (\`ggui_amend\`) update the SAME mounted component \u2014 see "Defensive coding".
+- **Display modes**: the host advertises \`availableDisplayModes\` (\`inline\` | \`fullscreen\` | \`pip\`); \`el.requestFullscreen()\` asks the host to switch \u2014 never assume it will.
+- **Size**: the host sets the iframe's \`containerDimensions\` once per render; there is no live resize notification \u2014 a resize is a re-render, so layout must be fluid (\`width: 100%\`, \`max-width\`, no fixed width) and hold at any width inside the canvas range above.`;
+var FREE_BUDGETS = `## Budgets (deterministic caps)
+
+- Source \u2264 50 KB and \u2264 500 lines.
+- Compiled bundle \u2264 2 MB.
+- One file, one \`export default function Component(props: Props)\`.`;
+var FREE_IMPORTS_AND_SECURITY = `## Imports & security (what you may import, what you may not call)
+
+Import ONLY from: \`react\`, \`react-dom\`, \`@ggui-ai/design\` (single barrel \u2014 no \`/primitives\` / \`/components\` subpaths), \`@ggui-ai/wire\`, \`@ggui-ai/gadgets\`, or a gadget package the contract declares \u2014 never \`@ggui-ai/wire/internal\`. The iframe runtime rewrites exactly these specifiers to in-bundle shims; ANY other import fails at module evaluation and blanks the iframe (tier-0 \`imports\` fail). No \`require()\`.
+
+Never call \`eval()\`, \`Function()\`, \`fetch()\` or the host-document APIs listed under "Where this renders" \u2014 tier-0 \`security\` fails them and the sandbox blocks them anyway.`;
+var FREE_RESPONSIVE_INVARIANT = `## Responsive invariant
+
+The component must fit the host-supplied iframe width at every point of the canvas range: \`width: 100%\` (plus \`max-width\` where you want to cap), never a fixed width, no horizontal scroll. Use \`@media\` / \`@container\` queries, \`clamp()\`, \`minmax()\`, \`auto-fit\` grids and \`flex-wrap\` freely. Compact chrome on \`xs-chat-card\` (the host draws the card border and shadow); own the chrome on the fullscreen canvases (\`mobile-fullscreen-small\`, \`md\`, \`lg\`, \`xl\`).`;
+var FREE_ACCESSIBILITY = `## Accessibility (REQUIRED)
+
+With raw elements YOU own the semantics \u2014 nothing is accessible by construction unless you import a \`@ggui-ai/design\` primitive (those carry their own roles / labels / keyboard handling; don't re-declare ARIA on them).
+
+1. **Interactive = a real control.** A click target is a \`<button type="button">\` or an \`<a href>\` \u2014 never a bare \`<div onClick>\`. If a non-button element must be clickable, add \`role="button"\`, \`tabIndex={0}\` and an \`onKeyDown\` handling Enter/Space.
+2. **Form inputs have labels.** \`<label htmlFor={id}>\` paired with the input's \`id\`, or \`aria-label\`; errors via \`aria-invalid\` + \`aria-describedby\`.
+3. **Images have \`alt\`** (\`alt=""\` for decorative). Icon-only buttons need \`aria-label\`; decorative icons and emoji are \`aria-hidden="true"\`.
+4. **Live & streaming data** (a \`useStream\` \`.latest\` value, counters, clocks, flashing prices) sits in an \`aria-live="polite"\` (or \`role="status"\`) region so screen readers announce the change.
+5. **Headings nest**: one \`<h1>\` per screen, \`<h2>\` for sections, \`<h3>\` below \u2014 never skipped or inverted.
+6. **Busy state is announced**: \`<button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting\u2026' : 'Submit'}</button>\`.
+7. **Stateful controls announce state**: \`role="checkbox"\` + \`aria-checked\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check mark) is never the only carrier of state.
+8. **Focus is visible** \u2014 style \`:focus-visible\` with a token color; never \`outline: none\` without a replacement.`;
+var FREE_QUALITY_CHECKLIST = `## Quality Checklist (verify before returning)
+
+- [ ] Imports ONLY from: react, react-dom, @ggui-ai/design, @ggui-ai/wire, @ggui-ai/gadgets (+ contract gadget packages)
+- [ ] ZERO literal colors \u2014 every color is a bare \`var(--ggui-color-*)\` from the manifest; no hex / rgb() / hsl() / named colors, no fallbacks \u2014 in \`style\` props AND \`<style>\` blocks
+- [ ] Fluid width (\`width: 100%\`, \`max-width\`), holds across the whole canvas range, no horizontal scroll
+- [ ] Typed Props interface exported; request-specific data is a prop with default
+- [ ] Every \`useAction\` binding is wired to exactly ONE gesture surface \u2014 no handler on both a parent and a child
+- [ ] Real controls (\`<button>\`, \`<a>\`, \`<input>\` + \`<label>\`), \`alt\` on images, \`aria-label\` on icon-only buttons
+- [ ] State is ARIA-expressed (\`aria-checked\` / \`aria-pressed\` / \`aria-selected\` / \`aria-expanded\`) \u2014 never style-only
+- [ ] Live/streaming regions wrapped in \`aria-live="polite"\`
+- [ ] Headings nest \u2014 one \`<h1>\`, then \`<h2>\` / \`<h3>\` \u2014 never skipped or inverted
+- [ ] No \`fetch\` / \`eval\` / \`window\` / \`document\` / \`localStorage\` / external stylesheets or fonts
+- [ ] Source \u2264 50 KB / \u2264 500 lines; wire hooks (\`useAction\`, \`useStream\`, \`useGguiContext\`) kept and consumed`;
+var FREE_SHAPE_GUIDANCE_NOTE = "In this mode the design-package components named above (`<Stepper>`, `<Modal>`, `<Card>`, `<Row>`, `<CardGrid>`) are defaults, not requirements \u2014 any composition that satisfies the behavioural rule (track the step index in state, a close affordance + focus trap, `key={item.id}`, no horizontal scroll) is acceptable. The crash anti-patterns are mandatory.";
+var TOKEN_GROUPS = [
+  { label: "Color (mandatory for every color)", prefixes: ["--ggui-color-"], note: "" },
+  { label: "Spacing (optional \u2014 literals are fine)", prefixes: ["--ggui-spacing-"], note: "" },
+  { label: "Typography (optional)", prefixes: ["--ggui-font-"], note: "" },
+  { label: "Radius (optional)", prefixes: ["--ggui-shape-radius-"], note: "" },
+  { label: "Shadow (optional)", prefixes: ["--ggui-shape-shadow-"], note: "" }
+];
+function renderTokenVocabulary(manifest = consumedTokenManifest) {
+  const sorted = [...manifest].sort();
+  const claimed = /* @__PURE__ */ new Set();
+  const lines = [
+    "### Reference (optional): theme token vocabulary",
+    "",
+    "The closed manifest \u2014 the ONLY `--ggui-*` names the runtime defines on `:root`. Color names are mandatory for color; the rest are optional conveniences.",
+    ""
+  ];
+  for (const group of TOKEN_GROUPS) {
+    const names = sorted.filter((t) => group.prefixes.some((p) => t.startsWith(p)));
+    if (names.length === 0) continue;
+    for (const n of names) claimed.add(n);
+    lines.push(`- **${group.label}**: ${names.map((n) => `\`${n}\``).join(", ")}`);
+  }
+  const other = sorted.filter((t) => !claimed.has(t));
+  if (other.length > 0) {
+    lines.push(`- **Other**: ${other.map((n) => `\`${n}\``).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function buildFreeDesignPrompt(inputs) {
+  const axisSection = inputs.axisSection.length > 0 ? `${inputs.axisSection}
+${FREE_SHAPE_GUIDANCE_NOTE}
+` : "";
+  const head = `You are ggui's UI builder. You receive a typed boilerplate and fill it in using apply_changes.
+
+## Your Task
+${inputs.userRequest}
+
+## Rendering canvas
+${describeCanvas(inputs.canvas)}
+
+## How It Works
+1. Read the boilerplate \u2014 typed Props and wire hooks are pre-configured; the JSX body and its styling are yours to compose
+2. Respond with one apply_changes call \u2014 add state, helpers, styles and JSX
+3. If compilation or evaluation fails, you'll get errors to fix in the next turn
+
+${inputs.criteriaBlock}
+${axisSection}
+`;
+  const sections = [
+    PROTOCOL_NOTES,
+    CONTRACT_SURFACE,
+    DEFENSIVE_CODING,
+    GESTURE_ROUTING,
+    FREE_GESTURE_SURFACE,
+    ANTI_PATTERNS,
+    CROSS_REFERENCE_RULES,
+    renderGadgetCatalogSection(inputs.gadgetsSection),
+    CONTEXT_SPEC_SECTION,
+    `## Reference: Wire Hooks
+${inputs.wireDoc}`,
+    FREE_DESIGN_FREEDOM,
+    FREE_COLOR_RULE,
+    FREE_HOST_ENVELOPE,
+    FREE_BUDGETS,
+    FREE_IMPORTS_AND_SECURITY,
+    DATA_PARAMETERIZATION,
+    COMPONENT_STRUCTURE,
+    FREE_RESPONSIVE_INVARIANT,
+    FREE_ACCESSIBILITY,
+    FREE_QUALITY_CHECKLIST,
+    renderTokenVocabulary(),
+    `### Reference (optional): \`@ggui-ai/design\` component catalog
+
+Optional \u2014 import a primitive only when it helps. Raw HTML + your own CSS is a first-class choice.
+
+${inputs.primitivesDoc}`
+  ];
+  return head + sections.join("\n\n") + "\n";
+}
 var VIRTUAL_DTS_PATH = "/__gadget__.d.ts";
 var EXTRACTOR_COMPILER_OPTIONS = {
   target: ts.ScriptTarget.ESNext,
@@ -1568,7 +2091,8 @@ function buildSystemPrompt(inputs) {
   const scr = inputs.screen ?? "universal";
   const shellDesc = SHELL_DESCRIPTIONS[shell] ?? SHELL_DESCRIPTIONS.fullscreen;
   const screenDesc = SCREEN_DESCRIPTIONS[scr] ?? SCREEN_DESCRIPTIONS.universal;
-  const criteriaBlock = inputs.criteriaBlock ?? buildCodingCriteriaSummary();
+  const designMode = inputs.designMode ?? DEFAULT_DESIGN_MODE;
+  const criteriaBlock = inputs.criteriaBlock ?? buildCodingCriteriaSummary(designMode);
   const pitfallsBlock = inputs.pitfallsBlock ?? "";
   const designSystemDocs = inputs.designSystemDocs ?? "";
   const primitivesDoc = inputs.primitivesDoc ?? "";
@@ -1581,6 +2105,17 @@ function buildSystemPrompt(inputs) {
 ## Shape Guidance
 ${inputs.axisDelta}
 ` : "";
+  if (designMode === "free") {
+    return buildFreeDesignPrompt({
+      userRequest: inputs.userRequest,
+      canvas: inputs.canvas ?? canvasForRendering(inputs.shellType, inputs.screen),
+      axisSection,
+      criteriaBlock,
+      wireDoc,
+      primitivesDoc,
+      gadgetsSection
+    });
+  }
   return `You are ggui's UI builder. You receive a typed boilerplate and fill it in using apply_changes.
 
 ## Your Task
@@ -1597,172 +2132,17 @@ ${inputs.userRequest}
 
 ${criteriaBlock}
 ${axisSection}
-## Protocol Notes
-The boilerplate pre-declares every wire hook the contract requires (\`useAction\`, \`useStream\`, \`useGguiContext\`, plus capability hooks from \`@ggui-ai/gadgets\` when the contract declares \`clientCapabilities\`). Three rules:
-1. **Do NOT delete any pre-declared hook.** \`self_check\` fails with \`wire_preservation:<kind>:<name>\` if you remove one.
-2. **Consume every hook binding** somewhere in the component \u2014 in JSX, a callback, or an effect. Unused bindings fail lint with \`no-unused-vars\`.
-3. **Do NOT invent new wire calls.** Every \`useAction('X')\`, \`useStream('X')\`, \`useGguiContext('X')\` etc. MUST correspond to a declared entry on the contract. Calling one that isn't declared fails \`self_check\` with \`wire_undeclared:<kind>:<name>\` because the runtime has no Context/registration for it and would throw at first paint. If you need a new wire surface, that's a contract authoring step the agent owns \u2014 your job is to honor what's declared.
-
-Renaming a binding is fine \u2014 the wiring is the string-literal argument, not the identifier.
-
-## Contract surface \u2014 four specs + two catalogs
-
-A \`DataContract\` declares everything a GguiSession exchanges with the outside world. **Four typed specs** for the four data-flow directions, **two reference catalogs** for tool / hook lookups:
-
-| Surface              | Direction                  | Role                                                                 |
-| -------------------- | -------------------------- | -------------------------------------------------------------------- |
-| \`propsSpec\`         | server \u2192 UI (one-shot)     | Initial render values delivered once at \`ggui_render\`              |
-| \`streamSpec\`        | agent \u2192 UI (many)          | Typed channels for live updates via \`ggui_emit\`                    |
-| \`actionSpec\`        | UI \u2192 agent (events)        | Discrete events driving the agent's next turn (consumed via \`ggui_consume\`) |
-| \`contextSpec\`       | UI \u2192 server (state mirror) | UI state the agent observes between turns                            |
-| \`agentCapabilities.tools\`     | catalog                    | Tools the contract references via \`actionSpec[*].nextStep\` and \`streamSpec[*].source.tool\` |
-| \`clientCapabilities.gadgets\` | catalog                    | Browser-capability gadget hooks the component code mounts (e.g., \`useGeolocation\`) |
-
-**Placement rule for inbound specs**: actions drive turns; context observes state. There is no third category.
-
-**Data vs behavior**: the contract describes data flow; the component code describes behavior. Scroll, focus, toast, animation, clipboard write \u2014 all component code, never contract fields.
-
-## Defensive coding for absent / late-arriving data
-
-Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
-
-- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY \u2014 the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
-- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
-- **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
-- **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
-- **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives \u2014 guard before reading \`.foo\`.
-- **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed \u2014 your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list \u2014 and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
-- **Props re-sync on repaint**: props the agent owns are the source of truth for display \u2014 prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change \u2014 \`useEffect(() => setCount(props.count ?? 0), [props.count])\` \u2014 or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
-- **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders \u2014 never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
-- **Empty state**: when a list or results array is empty, render \`<EmptyState title="\u2026" description="\u2026" />\` \u2014 a region that renders nothing when empty looks broken to the user.
-
-Unhandled \`Cannot read properties of undefined\` errors trip the iframe error boundary and the user sees "Something went wrong" \u2014 a regression class the runtime can't recover from.
-
-## Picking the right primitive for user gestures
-
-Choose by what the user is DOING, not where the result goes \u2014 the runtime handles the routing.
-
-| Gesture intent | LLM writes | Notes |
-| -------------- | ---------- | ----- |
-| Fire a server-side action | \`useAction(name)\` + call \`dispatch(name, payload)\` | Every action is agent-routed. The runtime emits an event on \`ggui_consume\`; the agent reacts on its next turn. If the contract entry declares \`nextStep: 'X'\`, that names the tool the agent SHOULD call next \u2014 advisory hint forwarded as event metadata. |
-| Surface state to the agent's context | the auto-generated \`setSlotName\` setter (from the boilerplate's \`useGguiContext\` line) | The runtime owns useState + Provider; the boilerplate emits one \`const [slot, setSlot] = useGguiContext<T>('slot')\` line per declared \`contextSpec\` slot. Write plain JSX, no \`useState\`, no Provider wrap. Every value change auto-flows to the host LLM (debounced). One-way client \u2192 agent \u2014 see "Observable state via \`contextSpec\`" below. |
-| Use a browser capability (camera, mic, geolocation, clipboard, file picker, notifications) | call the hook the contract declared, e.g., \`const loc = useGeolocation();\` and \`await loc.start()\` | The contract's \`clientCapabilities.gadgets\` declares which gadget exports the UI uses. The hook implementations live in \`@ggui-ai/gadgets\` (or a third-party package named in the \`Package\` column). Read \`status\` ("idle" / "prompting" / "active" / "completed" / "denied" / "error") to gate UI, and thread the resolved \`value\` into a contextSpec slot or actionSpec payload if the agent needs to see it. |
-| Open external link | Plain \`<a href="https://...">\` (or \`target="_blank"\`) | External cross-origin clicks are intercepted and routed through the host (security warnings, app-internal navigation, audit). Same-origin links and \`#fragment\` jumps stay native. |
-| Toggle fullscreen / chrome | Plain \`el.requestFullscreen()\` / \`document.exitFullscreen()\` | The native browser API is intercepted; the host adjusts iframe chrome accordingly. Returns a resolved promise so \`.then()\` / \`await\` chains don't break. |
-
-Every gesture fires a uniform server-side audit envelope (\`ggui_runtime_submit_action\`) so operators see all three patterns in RenderInspector with the same shape.
-
-**Don't import wire hooks for link / display-mode.** \`useAction\` is the only wire hook for user gestures; links and fullscreen use plain HTML / browser APIs.
-
-**All actions are agent-routed.** Every action emits an event the agent reacts to on its next turn via \`ggui_consume\`. The optional \`nextStep: '<tool>'\` field on an \`actionSpec\` entry is a HINT naming the tool the agent SHOULD call next \u2014 the contract author's recommendation, NOT a binding directive. The agent decides whether to honor it. If you want to declare a tool catalog entry the contract references, add it to \`agentCapabilities.tools[<name>]\` with input/output schemas; the cross-ref linter rejects dangling \`nextStep\` values that don't resolve to a declared catalog entry.
-
-## Making a primitive interactive \u2014 \`as={Trait}\`
-
-Structural primitives (\`Box\`, \`Stack\`, \`Row\`, \`Card\`) have NO \`onClick\` by default. Add interactivity with the \`as\` prop \u2014 a trait, not a wrapper:
-
-\`\`\`tsx
-<Card as={Clickable} onClick={() => dispatch('select', { id })}
-      hoverStyle={{ boxShadow: 'var(--ggui-shape-shadow-lg)' }}>\u2026</Card>
-\`\`\`
-
-- \`as={Clickable}\` \u2192 \`onClick\` + keyboard activation (Enter/Space) + \`role="button"\` + \`hoverStyle\`/\`activeStyle\`/\`cursor\`.
-- \`as={Hoverable}\` \u2192 \`hoverStyle\` only (no click). \`as={Pressable}\` \u2192 \`onPress\` + \`pressStyle\`.
-
-\`as={Trait}\` is a PROP \u2014 it does NOT re-nest the JSX. Never write \`<Clickable>\u2026</Clickable>\` around a primitive; put \`as={Clickable}\` on the primitive itself. The trait carries the keyboard + ARIA wiring, so don't hand-write \`onKeyDown\` / \`role\`. Trait components (\`Clickable\`, \`Hoverable\`, \`Pressable\`) import from \`@ggui-ai/design\` like everything else \u2014 the boilerplate already imports them.
-
-**Semantic components are already interactive** \u2014 \`Button\` (\`onClick\`), \`Link\` (\`href\`), \`Input\` / \`Select\` (\`onChange\`). Use their own props; never put \`as\` on them. \`Text\` picks its element with \`is\` (\`<Text is="label">\`), not \`as\`.
-
-**Never nest two interactive elements.** Interactive content MUST NOT contain other interactive content \u2014 a gesture on the inner control bubbles to the outer one and fires BOTH handlers (one user click \u2192 the action dispatched twice). Do NOT put a \`Button\`, \`Checkbox\`, \`Input\`, \`Select\`, \`Link\`, or another \`as={Clickable}\` primitive inside a \`Card\` / \`Box\` / \`Row\` / \`Stack\` that is itself \`as={Clickable}\`. Wire each \`useAction\` callback to exactly ONE surface: EITHER the whole card is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container, no \`as={Clickable}\`) \u2014 never both. A row with a checkbox: put the action on the \`Checkbox onChange\` and leave the row plain.
-
-**\`Text\` / \`Heading\` accept NO event handlers and NO \`as\` \u2014 only \`style\` / \`className\` plus their own typed props.** \`onClick\`, \`onDoubleClick\`, \`as={Clickable}\`, \`color\` are all type errors on \`Text\`. When the request says a label is "clickable", "editable", "edit on click / double-click", or "tap to \u2026", do ONE of these \u2014 never put the handler on \`Text\`:
-
-\`\`\`tsx
-// Click-to-edit a label: wrap the Text in a Clickable structural primitive.
-<Box as={Clickable} onClick={() => setEditingId(task.id)}
-     style={{ cursor: 'pointer' }}>
-  <Text weight="semibold">{task.title}</Text>
-</Box>
-
-// Or pair the label with an explicit edit Button (clearer affordance).
-<Row gap="xs" align="center">
-  <Text weight="semibold">{task.title}</Text>
-  <Button variant="ghost" size="xs" aria-label="Edit title"
-          onClick={() => setEditingId(task.id)}>Edit</Button>
-</Row>
-
-// In edit mode, swap the Text for an Input.
-{editingId === task.id
-  ? <Input value={draftTitle} onChange={setDraftTitle} label="Task title" />
-  : <Text weight="semibold">{task.title}</Text>}
-\`\`\`
-
-## Anti-patterns \u2014 DO NOT WRITE
-
-The following identifiers / shapes are RETIRED from the contract surface as of 2026-05-11. Pre-2026-05-11 examples in your training data may include them; do not reproduce. The linter / CI grep gate rejects:
-
-- \`useWiredTool\`, \`useClientTool\` \u2014 retired hooks. Replace with \`useAction\` (events) and the named hook from \`@ggui-ai/gadgets\` (browser capabilities).
-- \`dispatch: { kind: 'tool', tool: '...' }\` / \`dispatch: { kind: 'agent', intendedTool: '...' }\` \u2014 retired discriminated-union. Use the flat optional \`nextStep?: '<tool>'\` instead.
-- \`mode: 'host-routed'\` / \`mode: 'tool'\` \u2014 retired \`mode\` field. Same fix: flat \`nextStep?\`.
-- \`broadcast: {...}\` on the contract \u2014 retired top-level field. Use \`streamSpec[channel].source: {tool, args?}\` to declare a tool-fed channel.
-- \`wiredTools\` / \`agentTools\` (top-level) \u2014 retired catalog names. Use \`agentCapabilities.tools\`.
-- \`clientTools\` / \`clientCapabilities.capabilities\` \u2014 retired catalog shapes. Use \`clientCapabilities.gadgets\` (entries declare hooks, not RPC).
-- \`@ggui-ai/client-tools\` \u2014 retired package name. Import gadget hooks from \`@ggui-ai/gadgets\`.
-- \`intendedTool\` \u2014 retired. Use \`nextStep\` (flat).
-- \`props: { properties: {...} }\` as a CONTRACT field \u2014 retired. The contract field is \`propsSpec\` (the wire \`props\` field on render / update still carries VALUES).
-
-## Cross-reference rules
-
-When you declare a reference, also declare the catalog entry it points at:
-
-- \`actionSpec[X].nextStep = 'fetch_inbox'\` \u2192 \`agentCapabilities.tools.fetch_inbox = { toolInfo: { inputSchema, description?, outputSchema? }, usage?, example? }\` MUST exist. Cross-ref code: \`CTR_REF_NEXT_STEP\`.
-- \`streamSpec[X].source.tool = 'list_messages'\` \u2192 \`agentCapabilities.tools.list_messages\` MUST exist. Cross-ref code: \`CTR_REF_STREAM_SOURCE\`.
-- The catalog entry's schemas MUST be a superset of the referencing spec's schema. Cross-ref code: \`CTR_SCHEMA_INCOMPAT\`.
-
-## clientCapabilities \u2014 registered catalog
-
-${gadgetsSection}
-
-Each hook conforms to \`GadgetHook<TOutput, TOptions>\`: call \`start(opts?)\` to fire, read \`{value, status, error, stop?}\`. \`status\` walks through \`idle \u2192 prompting \u2192 active|completed\` or routes to \`denied\` / \`error\` on failure.
-
-3rd-party plugins (Leaflet maps, Mapbox, Stripe, Chart.js, \u2026) are registered via \`createGguiGadget\` from \`@ggui-ai/gadgets\` and surface in this same table when the operator has added them to \`App.gadgets\`. Reference any registered hook by name \u2014 render validation rejects hooks not in this catalog with \`gadget_not_registered\`.
-
-## Observable state via \`contextSpec\`
-
-When the contract declares \`contextSpec\`, the boilerplate auto-generates one \`useGguiContext\` call per slot at the top of your component. The runtime owns the underlying \`useState\` and the Provider tree \u2014 **you do NOT write \`useState\` or any \`<Provider>\` wrap yourself**:
-
-\`\`\`tsx
-import { useGguiContext } from '@ggui-ai/wire';
-
-export default function Component(props: Props) {
-  // AUTO-GENERATED \u2014 do not remove or rename:
-  const [currentStep, setCurrentStep] = useGguiContext<number>('currentStep');
-  const [draftText, setDraftText] = useGguiContext<string>('draftText');
-
-  // Plain JSX. No Provider wrap. The runtime already wrapped your
-  // component in nested SingleSlotProviders before this code ran.
-  return (
-    <Container>
-      <Text>Step {currentStep}</Text>
-      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
-      <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
-    </Container>
-  );
-}
-\`\`\`
-
-For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
-- **Read** the value to render: \`<Text>Step {currentStep}</Text>\`
-- **Write** via the setter: \`setCurrentStep(s => s + 1)\` (in callbacks, effects, anywhere)
-
-Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms \u2014 adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state \u2014 drafts, current step, hover, selection \u2014 without you calling any API.
-
-**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
-
-**When NOT to use it.** Local UI state the contract did NOT declare \u2014 \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
-
-**\`contextSpec\` direction is one-way: client \u2192 agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` \u2014 there is no return path.
-
-**Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.
+` + [
+    PROTOCOL_NOTES,
+    CONTRACT_SURFACE,
+    DEFENSIVE_CODING,
+    GESTURE_ROUTING,
+    INTERACTIVE_TRAITS,
+    ANTI_PATTERNS,
+    CROSS_REFERENCE_RULES,
+    renderGadgetCatalogSection(gadgetsSection),
+    CONTEXT_SPEC_SECTION
+  ].join("\n\n") + `
 
 ${pitfallsBlock}
 
@@ -1778,7 +2158,7 @@ ${designSystemDocs}
 ${primitivesDoc}
 `;
 }
-var DESIGN_SYSTEM_GUIDANCE = `## Imports & Component Surface
+var DESIGN_SYSTEM_GUIDANCE_SURFACE_AND_TOKENS = `## Imports & Component Surface
 
 Import ONLY from: \`react\`, \`@ggui-ai/design\`, \`@ggui-ai/wire\`. The ENTIRE design system \u2014 every primitive, component, composition and trait \u2014 is exported from the single \`@ggui-ai/design\` entry: \`import { Card, Grid, Stack, Modal, Clickable } from '@ggui-ai/design'\`. There are NO subpaths (\`/primitives\`, \`/components\`, \u2026) \u2014 never import from them. Use the design components \u2014 DO NOT use raw HTML elements (\`<button>\`, \`<input>\`, \`<div>\` for layout) or Tailwind classes; those render unstyled in the iframe runtime.
 
@@ -1813,7 +2193,7 @@ EXACT primitive prop values (other values are silently ignored \u2014 the design
 - \`<Grid columns={N} gap="md">\` \u2014 2-D layout (rows AND columns). Reach for it for card galleries, stat grids and dashboards \u2014 NEVER hand-roll \`style={{ display: 'grid' }}\`. When the request names exact per-breakpoint counts ("3 per row on desktop, 1 on mobile"), pass a map: \`<Grid columns={{ base: 1, md: 3 }}>\` (breakpoints \`sm\`/\`md\`/\`lg\`/\`xl\`; the design system emits the media queries). For an open-ended gallery where any column count is fine, use \`<Grid minColumnWidth={220}>\` \u2014 it fits as many equal columns as the width allows. \`radius\` (Card / Box / Image) takes the scale \`none | sm | md | lg | xl\`.
 - \`<Stat label="\u2026" value="\u2026" delta="+12%" trend="up">\` \u2014 KPI display (label + big value + trend-coloured delta + optional \`icon\`). \`trend\` is \`up | down | neutral\` (delta renders green / red / muted). Reach for it for any "show a number" UI; drop several into a \`<Grid>\` for a stat grid instead of hand-building label+value pairs.
 - \`<Stepper steps={STEPS} current={step} />\` \u2014 display-only step indicator for wizards/checkouts. \`steps\` is a top-level \`const\` array of labels; \`current\` is YOUR zero-indexed \`useState\` value; \`orientation\` is \`horizontal | vertical\`; optional \`onStepClick={(i) => \u2026}\` makes steps clickable. Stepper never owns navigation state \u2014 your Next/Back handlers move \`current\`.
-- \`<Badge variant="...">\` \u2014 \`default | primary | secondary | success | warning | error | info\` for colored pills. Great for status/condition labels. There is NO \`neutral\` variant \u2014 use \`default\` (or \`secondary\`) for an un-tinted pill.
+- \`<Badge variant="...">\` \u2014 \`default | primary | secondary | tertiary | success | warning | error | info\` for colored pills. Great for status/condition labels. There is NO \`neutral\` variant \u2014 use \`default\` (or \`secondary\`) for an un-tinted pill.
 
 **Color choice rule of thumb.** Reach for typed slots first: Button \`variant\`, Badge \`variant\`, Alert \`variant\`, Text/Heading/Icon/Spinner/Link/Divider \`tone\`, Box/Card \`surface\`. NEVER hardcode hex \`#XXXXXX\`, rgba, or hsl \u2014 tier-0 self-check rejects them with \`tokens:hex-color\` / \`tokens:hardcoded-color-fn\` and the LLM must remediate. Hardcoded colors break the operator's theme switch (Indigo \u2192 Claudic \u2192 Cyberpunk preset has zero effect on a card hardcoded with \`background: '#000'\`).
 
@@ -1846,8 +2226,8 @@ MANDATORY:
 
 Token categories:
 - Brand: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
-- Text: \`var(--ggui-color-onSurface)\`, \`var(--ggui-color-onSurfaceVariant)\`
-- Backgrounds: \`var(--ggui-color-surface)\`, \`var(--ggui-color-surfaceVariant)\`
+- Text: \`var(--ggui-color-onContainer)\`, \`var(--ggui-color-onSunken)\`
+- Backgrounds: \`var(--ggui-color-container)\`, \`var(--ggui-color-sunken)\`
 - Borders: \`var(--ggui-color-outline)\`
 - Spacing: \`var(--ggui-spacing-4)\`, \`var(--ggui-spacing-6)\`
 - Typography: \`var(--ggui-font-size-sm)\`, \`var(--ggui-font-weight-semibold)\`
@@ -1868,7 +2248,7 @@ Use the FULL primary palette throughout the component \u2014 NOT only on submit
 | Buttons, CTAs, filled interactive elements | \`primary-600\` / \`primary-700\` | Primary actions |
 | Headings on light primary backgrounds | \`primary-800\` / \`primary-900\` | High-contrast branded text |
 
-Use semantic tokens (\`onSurface\`, \`onSurfaceVariant\`) for body text and secondary info. NEVER use raw \`neutral-*\` or \`gray-*\` for body text \u2014 they break in dark themes.
+Use the layering roles' inks (\`onContainer\` for body text on a card, \`onSunken\` for secondary text, captions, labels) \u2014 never raw neutrals. NEVER use raw \`neutral-*\` or \`gray-*\` for body text \u2014 they break in dark themes.
 
 ### Theme-Agnostic Design
 
@@ -1877,7 +2257,7 @@ Components MUST be theme-agnostic \u2014 they reference CSS variables but NEVER
 DO:
 - Use \`var(--ggui-color-primary-*)\` for brand elements \u2014 the theme controls what "primary" means
 - Use \`var(--ggui-shape-shadow-*)\` for depth, \`var(--ggui-shape-radius-*)\` for corners
-- Use semantic color roles: primary for brand, surface/onSurface for structure, success/error/warning for state
+- Use semantic color roles: primary for brand; the layering roles (ground / container / elevated / sunken + their on* inks) for structure; success/error/warning for state
 
 DON'T:
 - Don't assume primary is blue \u2014 could be red, green, purple
@@ -1898,59 +2278,8 @@ Generated components become reusable blueprints \u2014 the same blueprint serves
 2. Relative/fluid units \u2014 prefer \`%\`, \`em\`, \`rem\`, \`min()\`, \`max()\`, \`clamp()\` over fixed \`px\`.
 3. Fluid widths \u2014 \`max-width\` with \`width: 100%\`. Never set a fixed width.
 4. Compact padding \u2014 components are embedded in containers that provide their own chrome.
-5. No raw \`@media\` queries in component code \u2014 for a layout that must change by breakpoint, use \`<Grid columns={{ base: 1, md: 3 }}>\` (the design system emits the media queries for you) or a fluid \`minColumnWidth\` grid.
-
-## Data Parameterization (CRITICAL)
-
-Generated components are CACHED blueprints reused across requests. NEVER hardcode request-specific data (names, cities, numbers, dates) into the component body. Define data as default prop values so the blueprint works for ANY similar request:
-
-\`\`\`tsx
-// BAD \u2014 hardcoded, only works for Tokyo
-const city = "Tokyo";
-const temp = 18;
-
-// GOOD \u2014 parameterized via props with defaults from the request
-interface Props {
-  city?: string;
-  temperature?: number;
-}
-export default function WeatherCard({ city = "Tokyo", temperature = 18 }: Props) {
-  // A controller can override for Seoul, Paris, etc.
-}
-\`\`\`
-
-Rules:
-1. All request-specific data \u2192 props with defaults. City names, tickers, user names, dates, counts.
-2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
-3. Default values come from the current request \u2014 so the component renders correctly standalone.
-4. Props interface must be typed and exported.
-
-## Component Structure
-
-Keep JSX nesting depth to 3\u20135 levels. When deeper, extract repeated/complex sections into helper components \u2014 named functions defined above the main Component in the same file. Helpers take data + callbacks via props; they don't own state.
-
-\`\`\`tsx
-import { useState } from 'react';
-import { Container, Card, Stack, Text, Button, Input } from '@ggui-ai/design';
-
-interface Props {
-  onSubmit?: (data: unknown) => void;
-}
-
-function ItemCard({ item, onEdit }: { item: Item; onEdit: (id: string) => void }) {
-  return <Card padding="md">\u2026</Card>;
-}
-
-export default function GeneratedComponent({ onSubmit }: Props) {
-  return (
-    <Container>
-      {items.map((item) => <ItemCard key={item.id} item={item} onEdit={handleEdit} />)}
-    </Container>
-  );
-}
-\`\`\`
-
-## Aesthetic Guidance (READ CAREFULLY \u2014 this is what separates "polished" from "ok")
+5. No raw \`@media\` queries in component code \u2014 for a layout that must change by breakpoint, use \`<Grid columns={{ base: 1, md: 3 }}>\` (the design system emits the media queries for you) or a fluid \`minColumnWidth\` grid.`;
+var DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST = `## Aesthetic Guidance (READ CAREFULLY \u2014 this is what separates "polished" from "ok")
 
 ### Visual hierarchy \u2014 the SCALE GAP rule
 
@@ -1972,11 +2301,11 @@ A polished UI has ONE hero that dominates. Everything else supports it. Bad layo
 ### Color discipline \u2014 the 60/30/10 rule
 
 Don't paint everything in primary. Use:
-- **60% surface** (\`var(--ggui-color-surface)\` / \`onSurface\`) \u2014 body text, default backgrounds, structure
-- **30% surfaceVariant + onSurfaceVariant** \u2014 secondary text, captions, labels, dividers
+- **60% container** (\`var(--ggui-color-container)\` / \`onContainer\`) \u2014 body text, default backgrounds, structure
+- **30% sunken + onSunken** \u2014 wells, secondary text, captions, labels, dividers
 - **10% primary** \u2014 hero number, ONE highlight element, CTAs, brand accent
 
-If your component is 100% purple text on purple backgrounds, you've lost the eye. Headings can be \`onSurface\` (dark neutral) \u2014 they'll still feel weighty. Save the primary palette for one or two STAR moments.
+If your component is 100% purple text on purple backgrounds, you've lost the eye. Headings can be \`onContainer\` (the card's ink) \u2014 they'll still feel weighty. Save the primary palette for one or two STAR moments.
 
 \`\`\`tsx
 // BAD \u2014 everything purple, eye has no anchor
@@ -1985,7 +2314,7 @@ If your component is 100% purple text on purple backgrounds, you've lost the eye
 <Text tone="emphasized">all body text</Text>
 
 // GOOD \u2014 hero pops, body is neutral, primary is reserved
-<Heading>Title</Heading>  {/* defaults to onSurface */}
+<Heading>Title</Heading>  {/* defaults to onContainer */}
 <Text size="4xl" weight="bold" tone="emphasized">42</Text>
 <Text tone="muted">all body text</Text>
 \`\`\`
@@ -2043,6 +2372,12 @@ Hero sections should feel airy. Use \`padding="xl"\` (32px) on the main card, no
 - [ ] Live/streaming regions wrapped in \`aria-live="polite"\`
 - [ ] Headings nest \u2014 one \`level={1}\`, then \`level={2}\`/\`{3}\` \u2014 never skipped or inverted
 - [ ] Wire hooks (\`useAction\`, \`useStream\`) imported from \`@ggui-ai/wire\` and consumed`;
+var DESIGN_SYSTEM_GUIDANCE = [
+  DESIGN_SYSTEM_GUIDANCE_SURFACE_AND_TOKENS,
+  DATA_PARAMETERIZATION,
+  COMPONENT_STRUCTURE,
+  DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST
+].join("\n\n");
 
 // src/tools.ts
 var APPLY_CHANGES_TOOL = {
@@ -2283,13 +2618,16 @@ function countCacheTiers(fragments) {
 function createHarness(input) {
   const { classification, contract, prompt, shellType, screen, overrides } = input;
   const ctx = { classification, contract, prompt };
+  const designMode = input.designMode ?? DEFAULT_DESIGN_MODE;
   const composed = compose(classification);
   const systemPromptBuilder = input.systemPromptBuilder ?? buildSystemPrompt;
   const systemPrompt = systemPromptBuilder({
     userRequest: prompt,
     shellType,
     screen,
-    axisDelta: composed.promptText
+    axisDelta: composed.promptText,
+    designMode,
+    ...input.canvas !== void 0 ? { canvas: input.canvas } : {}
   });
   const howFragments = composed.fragments.filter(
     (f) => f.promptText && f.promptText.trim().length > 0
@@ -2307,7 +2645,8 @@ function createHarness(input) {
     shellType,
     screen,
     composed.boilerplateSections,
-    input.appGadgets
+    input.appGadgets,
+    designMode
   );
   const whatFragments = composed.fragments.filter(
     (f) => f.boilerplateMarker && f.boilerplateMarker.trim().length > 0
@@ -2358,6 +2697,7 @@ function createHarness(input) {
   if (overrides?.process) overrideLabels.push("process");
   if (overrides?.label) overrideLabels.push(`label:${overrides.label}`);
   if (!isDefaultHarnessPolicy(policy)) overrideLabels.push("policy");
+  if (designMode !== DEFAULT_DESIGN_MODE) overrideLabels.push(`designMode:${designMode}`);
   const id = computeHarnessId({
     classificationHash,
     howVersion: how.version,
@@ -2385,6 +2725,7 @@ function createHarness(input) {
     id,
     name,
     classification,
+    designMode,
     how,
     what,
     check,