@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/dist/chunk-FB7OEEAH.js

@@ -0,0 +1,1467 @@
+import { taughtTokenManifest, jsonSchemaTypeToTs, BOILERPLATE_REACT_IMPORT } from './chunk-Z3CXME3K.js';
+import { buildStylingProfileSection, withStylingProfile } from './chunk-NF6JUZWF.js';
+import { buildCodingCriteriaSummary } from './chunk-PUH4CXGZ.js';
+import { DEFAULT_DESIGN_MODE, canvasForRendering, describeCanvas } from './chunk-3T2HMTON.js';
+import { listContractGadgets, HOOK_NAME_RE, resolveAppGadgets } from '@ggui-ai/protocol';
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { GGUI_MOUNT_CANVAS_EXPORT } from '@ggui-ai/design/rendering';
+import ts from 'typescript';
+
+var __dirname$1 = dirname(fileURLToPath(import.meta.url));
+var TEMPLATE_DIRS = [
+  resolve(__dirname$1, "templates"),
+  resolve(__dirname$1, "..", "src", "boilerplate", "templates"),
+  resolve(__dirname$1, "..", "..", "src", "boilerplate", "templates"),
+  resolve(__dirname$1, "..", "..", "..", "src", "boilerplate", "templates"),
+  resolve(__dirname$1, "..", "..", "..", "..", "src", "boilerplate", "templates")
+];
+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(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 {
+      const content = readFileSync(resolve(dir, file), "utf-8");
+      baseCache.set(designMode, content);
+      return content;
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`No ${file} found`);
+}
+function loadLayout(shellType, screen) {
+  const key = `${shellType}-${screen}`;
+  if (layoutCache.has(key)) return layoutCache.get(key);
+  const candidates = [
+    `${shellType}-${screen}.tsx.tmpl`,
+    `${shellType}-universal.tsx.tmpl`,
+    `fullscreen-universal.tsx.tmpl`
+    // final fallback
+  ];
+  for (const filename of candidates) {
+    for (const dir of TEMPLATE_DIRS) {
+      try {
+        const content = readFileSync(resolve(dir, "layouts", filename), "utf-8");
+        layoutCache.set(key, content);
+        return content;
+      } catch {
+        continue;
+      }
+    }
+  }
+  throw new Error(`No layout found for ${key}`);
+}
+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);
+  }
+  return template;
+}
+var ALL_PRIMITIVES = [
+  "Container",
+  "Card",
+  "Stack",
+  "Row",
+  "Grid",
+  "Box",
+  "Divider",
+  "Spacer",
+  "Text",
+  "Heading",
+  "Button",
+  "Input",
+  "TextArea",
+  "Select",
+  "Checkbox",
+  "Toggle",
+  "RadioGroup",
+  "Slider",
+  "Badge",
+  "Spinner",
+  "Skeleton",
+  "Avatar",
+  "Alert",
+  "Progress",
+  "Image",
+  "Icon",
+  "Link",
+  "Tooltip",
+  "Table",
+  "Tabs",
+  "Toast",
+  "Accordion",
+  "MotionKeyframes",
+  "useMotion",
+  "useAnimationKey"
+].join(", ");
+var ALL_COMPONENTS = [
+  "SearchField",
+  "FormField",
+  "MenuItem",
+  "Tag",
+  "Dropdown",
+  "Autocomplete",
+  "Breadcrumb",
+  "Pagination",
+  "EmptyState",
+  "Stat",
+  "Stepper",
+  "Markdown",
+  "MarkdownInline"
+].join(", ");
+var ALL_COMPOSITIONS = [
+  "Header",
+  "Sidebar",
+  "CardGrid",
+  "CommentThread",
+  "DataTable",
+  "ChatWindow",
+  "NavigationBar",
+  "FileUploader",
+  "NotificationCenter",
+  "Modal",
+  "CommandPalette",
+  "Footer",
+  "Hero"
+].join(", ");
+var ALL_INTERACT = ["Clickable", "Hoverable", "Pressable"].join(", ");
+var ALL_DESIGN = [
+  ALL_PRIMITIVES,
+  ALL_COMPONENTS,
+  ALL_COMPOSITIONS,
+  ALL_INTERACT
+].join(", ");
+function inferTypeFromExample(example) {
+  const fields = [];
+  for (const [k, v] of Object.entries(example)) {
+    let t;
+    if (v === null || v === void 0) t = "unknown";
+    else if (typeof v === "string") t = "string";
+    else if (typeof v === "number") t = "number";
+    else if (typeof v === "boolean") t = "boolean";
+    else if (Array.isArray(v)) {
+      if (v.length === 0) t = "unknown[]";
+      else if (typeof v[0] === "string") t = "string[]";
+      else if (typeof v[0] === "number") t = "number[]";
+      else if (typeof v[0] === "object" && v[0] !== null)
+        t = `Array<${inferTypeFromExample(v[0])}>`;
+      else t = "unknown[]";
+    } else if (typeof v === "object") {
+      t = inferTypeFromExample(v);
+    } else {
+      t = "unknown";
+    }
+    fields.push(`${k}: ${t}`);
+  }
+  return `{ ${fields.join("; ")} }`;
+}
+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)) {
+    const required = entry.required === true;
+    const nullable = entry.schema.nullable === true;
+    const tsType = jsonSchemaTypeToTs(entry.schema);
+    const fullType = nullable ? `${tsType} | null` : tsType;
+    const parts = [];
+    if (entry.description) parts.push(entry.description);
+    if (entry.default !== void 0) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    if (!required) parts.push("(optional \u2014 the agent may omit it; guard or fall back)");
+    const desc = parts.length > 0 ? ` // ${parts.join(" ")}` : "";
+    propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
+  }
+  const actionTypeAliases = [];
+  const actionHookCalls = [];
+  let hasOneShotAction = false;
+  const actionsMap = contract?.actionSpec ?? {};
+  for (const [key, entry] of Object.entries(actionsMap)) {
+    const label = entry.label ?? key;
+    const desc = entry.description ?? "";
+    const tool = entry.nextStep ?? "";
+    const typeName = `Action${key.charAt(0).toUpperCase()}${key.slice(1)}Payload`;
+    let tsType = "void";
+    if (entry.schema) {
+      tsType = jsonSchemaTypeToTs(entry.schema);
+    } else if (entry.example && typeof entry.example === "object" && !Array.isArray(entry.example)) {
+      tsType = inferTypeFromExample(entry.example);
+    }
+    const toolNote = tool ? ` (label "${label}", nextStep hint \u2192 ${tool})` : "";
+    actionTypeAliases.push(
+      `/** Action payload: ${desc || label}${toolNote} \u2014 control copy: "${label}" VERBATIM */
+type ${typeName} = ${tsType};`
+    );
+    const callSig = tsType === "void" ? "() => void \u2014 fire and forget" : `(data: ${tsType}) => void`;
+    const toolHint = tool ? ` \u2192 nextStep: ${tool}` : "";
+    const onceHint = " \u2014 if this is meant ONCE, disable its control after it fires";
+    if (entry.oneShot === true) {
+      hasOneShotAction = true;
+      actionHookCalls.push(
+        `  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint} \u2014 declared oneShot: the runtime drops a second dispatch`
+      );
+      actionHookCalls.push(
+        `  const ${key}Spent = useActionSpent('${key}'); // true once fired, also after a reload \u2014 render the control from THIS: disabled={${key}Spent} and a spent label`
+      );
+    } else {
+      actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
+    }
+    actionHookCalls.push(
+      `  const ${key}Pending = useActionPending('${key}'); // true from the tap until the agent's answer repaints the card \u2014 render EVERY control that dispatches '${key}' (a Button, a Select's onChange, an Input's Enter) from THIS: disabled={${key}Pending} aria-busy={${key}Pending}, and a working label on a button; no other control carries its aria-busy`
+    );
+  }
+  const streamChannels = contract?.streamSpec ?? {};
+  const streamChannelEntries = Object.entries(streamChannels);
+  const streamTypeAliases = [];
+  const streamHookCalls = [];
+  for (const [channelName, entry] of streamChannelEntries) {
+    const desc = entry.description ?? "";
+    const typeName = `Stream${channelName.charAt(0).toUpperCase()}${channelName.slice(1)}`;
+    const tsType = entry.schema ? jsonSchemaTypeToTs(entry.schema) : "unknown";
+    streamTypeAliases.push(`/** Stream channel: ${desc} */
+type ${typeName} = ${tsType};`);
+    streamHookCalls.push(
+      `  const ${channelName} = useStream<${typeName}>('${channelName}'); // .latest: ${typeName} | null, .all: ${typeName}[]`
+    );
+  }
+  const gadgetUses = contract ? listContractGadgets(contract) : [];
+  const gadgetCatalog = /* @__PURE__ */ new Map();
+  for (const descriptor of appGadgets ?? []) {
+    for (const exp of descriptor.exports) {
+      if (exp.hook === void 0) continue;
+      gadgetCatalog.set(exp.hook, {
+        description: exp.description,
+        usage: exp.usage,
+        example: exp.example
+      });
+    }
+  }
+  const gadgetImportsByPackage = /* @__PURE__ */ new Map();
+  const gadgetHookCalls = [];
+  for (const use of gadgetUses) {
+    const exportName = use.name;
+    const pkgExports = gadgetImportsByPackage.get(use.package);
+    if (pkgExports !== void 0) pkgExports.add(exportName);
+    else gadgetImportsByPackage.set(use.package, /* @__PURE__ */ new Set([exportName]));
+    if (!HOOK_NAME_RE.test(exportName)) continue;
+    const hook = exportName;
+    const contractDesc = use.description;
+    const contractUsage = use.usage;
+    const catalog = gadgetCatalog.get(hook) ?? {};
+    const desc = contractDesc ?? catalog.description ?? hook;
+    const usage = contractUsage ?? catalog.usage;
+    const example = catalog.example;
+    let callArgs = "";
+    let exampleComment = "";
+    if (example !== void 0 && example !== null) {
+      const callLine = typeof example === "object" && !Array.isArray(example) && typeof example.call === "string" ? example.call : void 0;
+      if (callLine !== void 0) {
+        exampleComment = `
+  // EXAMPLE: ${callLine.trim()}`;
+      } else {
+        callArgs = JSON.stringify(example);
+      }
+    }
+    const usageNote = usage ? ` USE: ${usage}` : "";
+    const bindingName = hook.length > 3 ? hook.charAt(3).toLowerCase() + hook.slice(4) : hook;
+    gadgetHookCalls.push(
+      `  const ${bindingName} = ${hook}(${callArgs}); // ${desc}${usageNote}${exampleComment}`
+    );
+  }
+  const gadgetImportLine = gadgetImportsByPackage.size > 0 ? "// DO NOT EDIT \u2014 gadget imports. Each export is resolved by the iframe runtime; keep every import line and export name. self_check fails with gadget_preservation:<export> if a gadget import is removed.\n" + Array.from(gadgetImportsByPackage.entries()).sort(([a], [b]) => a.localeCompare(b)).map(
+    ([pkg, hooks]) => `import { ${Array.from(hooks).sort().join(", ")} } from '${pkg}';`
+  ).join("\n") : "";
+  const propsInterface = propsFields.length > 0 ? `// DO NOT EDIT \u2014 generated from data contract. Changing this will fail validation.
+interface Props {
+${propsFields.join("\n")}
+}` : `// DO NOT EDIT \u2014 generated from data contract.
+interface Props {
+  [key: string]: string | number | boolean | null | object;
+}`;
+  const contextSpec = contract?.contextSpec ?? {};
+  const contextSpecEntries = Object.entries(contextSpec);
+  let contextHooks = "";
+  if (contextSpecEntries.length > 0) {
+    const hookLines = [];
+    for (const [slotKey, entry] of contextSpecEntries) {
+      const valueType = entry.schema ? jsonSchemaTypeToTs(entry.schema) : "unknown";
+      const setterName = `set${slotKey.charAt(0).toUpperCase()}${slotKey.slice(1)}`;
+      hookLines.push(
+        `  const [${slotKey}, ${setterName}] = useGguiContext<${valueType}>('${slotKey}');`
+      );
+    }
+    contextHooks = `  // DO NOT EDIT \u2014 auto-generated per contextSpec slot.
+  // Read \`<slotKey>\` to render, write via \`set<SlotKey>\` to
+  // surface the change to the agent's LLM context (debounced).
+  // The runtime owns the underlying useState + Provider; you
+  // write plain JSX, no wrap.
+${hookLines.join("\n")}
+`;
+  }
+  const hasActions = actionHookCalls.length > 0;
+  const hasStream = streamHookCalls.length > 0;
+  const hasGadgetHookCalls = gadgetHookCalls.length > 0;
+  const hasContext = contextSpecEntries.length > 0;
+  const hasAnyHook = hasActions || hasStream || hasContext || hasGadgetHookCalls;
+  const hasAnyWireFromWire = hasActions || hasStream || hasContext;
+  const wireHooks = [];
+  if (hasActions) wireHooks.push("useAction");
+  if (hasOneShotAction) wireHooks.push("useActionSpent");
+  if (hasActions) wireHooks.push("useActionPending");
+  if (hasStream) wireHooks.push("useStream");
+  if (hasContext) wireHooks.push("useGguiContext");
+  const wireImport = hasAnyWireFromWire ? `import { ${wireHooks.join(", ")} } from '@ggui-ai/wire';
+` : "";
+  const gadgetImport = gadgetImportLine.length > 0 ? `${gadgetImportLine}
+` : "";
+  const reactImport = BOILERPLATE_REACT_IMPORT;
+  const hookParts = [];
+  if (hasActions) {
+    hookParts.push("  // \u2500\u2500 Actions (contract-typed, fire-and-forget to agent) \u2500\u2500");
+    hookParts.push("  // Call these to send user interactions to the agent. Types are enforced by the compiler.");
+    hookParts.push(...actionHookCalls);
+  }
+  if (hasStream) {
+    hookParts.push("");
+    hookParts.push("  // \u2500\u2500 Streams (contract-typed, real-time from agent) \u2500\u2500");
+    hookParts.push("  // .latest is the most recent event (or null). .all is the full history array.");
+    hookParts.push(...streamHookCalls);
+  }
+  if (hasGadgetHookCalls) {
+    hookParts.push("");
+    hookParts.push("  // \u2500\u2500 Gadgets (browser-capability hooks; UI-owned lifecycle) \u2500\u2500");
+    hookParts.push("  // Read .value / .status; call .start() to invoke. Surface .value through");
+    hookParts.push("  // an actionSpec payload or contextSpec slot if the agent needs to observe it.");
+    hookParts.push(...gadgetHookCalls);
+  }
+  const hookBody = hasAnyHook ? `  // DO NOT EDIT wire hooks \u2014 auto-generated from the data contract
+${hookParts.join("\n")}
+` : "";
+  const wrapTypes = (label, body) => `
+/* eslint-disable no-unused-vars */
+// DO NOT EDIT \u2014 ${label}
+${body}
+/* eslint-enable no-unused-vars */
+`;
+  const actionTypesBlock = actionTypeAliases.length > 0 ? wrapTypes("action payload types generated from action contract.", actionTypeAliases.join("\n\n")) : "";
+  const streamTypesBlock = streamTypeAliases.length > 0 ? wrapTypes("stream event types generated from stream contract.", streamTypeAliases.join("\n\n")) : "";
+  const mountCanvas = `
+
+// DO NOT EDIT \u2014 the canvas this card is composed for; the runtime reads it at mount.
+export const ${GGUI_MOUNT_CANVAS_EXPORT} = "${canvasForRendering(shellType, screen)}";`;
+  return renderBoilerplate(shellType ?? "fullscreen", screen ?? "universal", {
+    REACT_IMPORT: reactImport,
+    ALL_DESIGN,
+    WIRE_IMPORT: wireImport + gadgetImport,
+    PROPS_INTERFACE: propsInterface + mountCanvas,
+    ACTION_TYPES: actionTypesBlock,
+    STREAM_TYPES: streamTypesBlock,
+    CONTEXT_HOOKS: contextHooks,
+    WIRE_HOOKS: hookBody,
+    AXIS_SECTIONS: composedSections ?? ""
+  }, designMode);
+}
+
+// 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={setDraftText} />
+      <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={setDraftText}>\` so the agent sees the typing live (a design control's \`onChange\` hands you the value, never an event). If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
+
+**Seeding a slot from a prop.** A slot starts at the contract's default, never at a prop. When a slot must start from a prop (a form pre-filled from \`props\`), seed it with \`useLayoutEffect(() => setName(props.name ?? ''), [props.name])\` \u2014 \`useLayoutEffect\`, not \`useEffect\`: \`useEffect\` lets the first frame paint the empty default before the prop arrives. The dependency array re-seeds the slot when the agent repaints with new props.
+
+**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. Copy comes from the props. NEVER invent display text the contract does not carry \u2014 no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. **Do NOT add a caps label above the heading** \u2014 not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` \u2014 UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. A heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render, and a caps eyebrow you wrote is the most common form of it. An action's control shows the contract's \`label\` VERBATIM \u2014 every character, including \`&\`, \`/\`, \`\u2013\` and quotes \u2014 never paraphrased, shortened or re-cased (\`"Confirm & Schedule"\` is not \`"Confirm Schedule"\`).
+5. Props interface must be typed and exported.
+6. Keys on a mapped list come from the item's own identity: \`key={item.id}\` when the contract gives an id; when the items carry none (KPI tiles \`{label, value}\`, forecast days \`{day, high}\`), key by the field that names each one \u2014 \`key={item.label}\`, \`key={day.day}\` \u2014 never by the map index: a reorder or a stream merge re-keys by index and re-mounts the wrong rows, and the self-check refuses an index key.`;
+var TERMINAL_ACTIONS = `## Actions the user means once
+
+A second press is a mistake only when it would make a SECOND THING HAPPEN IN THE WORLD \u2014 a second booking, a second charge, a second order, a second application sent. If pressing again would only write the SAME STATE AGAIN \u2014 saving, updating, renaming, setting a preference, toggling \u2014 nothing is duplicated and the control stays armed.
+
+**The contract says which actions are once.** An action the contract declares \`oneShot: true\` (in the Contract block above) is guarded by the runtime \u2014 a second dispatch is dropped \u2014 and its spent state is DATA you read, never state you hold: render its control from \`const spent = useActionSpent('<name>')\`, \`disabled={spent}\`, and say so in the label or beside it ("Submitted", "Request sent") \u2014 a control that is disabled without explanation reads as broken. The hook's answer survives a reload and a second tab; \`useState(false)\` does not, so a reloaded card built on local state re-arms a control that already fired.
+
+**An action the contract does not declare \`oneShot\` stays armed.** Never guard one from a feeling about the verb \u2014 "confirm", "submit", "place" alone are not evidence. Guard it only where the request itself names a one-time commitment the contract failed to declare ("submit the application", "place the order"), and then with local state as the fallback: \`const [submitted, setSubmitted] = useState(false)\` set in the handler, \`disabled={submitted}\` with a label \u2014 knowing that this state lives with the component, not with the request, and starts fresh on a re-render with new props.
+
+**When in doubt, leave it armed.** A control the user cannot press a second time has lost them something that worked \u2014 save, edit, save again is ordinary. A control left armed is only what every interface does by default.`;
+var FRAME_SIZING = `## Sizing \u2014 the frame owns the height and the width
+
+The host sizes the iframe; the component never sizes itself to the viewport. NEVER write \`100vh\` / \`100dvh\` / \`100svh\` (or an \`h-screen\` / \`min-h-screen\` class) as a height on any element:
+- An inline card takes its natural height. A content-sized frame is measured FROM the content, so a \`100vh\` root can never shrink and grows the frame on every re-measure.
+- Under fullscreen the frame already stretches your root to its full height. Centre inside it with flex (\`display: flex; flex-direction: column; justify-content: center\`), never with a viewport height.
+- In EVERY fit (an inline card, a framed card, fullscreen) the card keeps ONE content edge: the runtime insets your root's content from the card's edge. Leave it, and never pad it back out. Only two things run edge to edge, in every fit:
+  - a \`surface="hero"\` band that is your root's FIRST child, opening the card (\`<Box surface="hero">\u2026</Box>\` directly inside the root, not wrapped in a \`Stack\`, not second);
+  - any other band that declares \`bleed\` (\`<Box surface="sunken" bleed>\u2026</Box>\`). Only a band MEANT to run edge to edge takes it: a full-width strip of rows, a closing action bar.
+  A band you paint yourself (a \`Box\` with a \`background\`) is NOT an edge-to-edge band. It sits inside the inset with the card's corners showing around it, like a box floating in the card. An opening band is always the kit's \`surface="hero"\`, never your own colour.
+- To fill a parent that has a height use \`height: 100%\` or \`flex: 1\`; a viewport unit is only ever a \`max-height\` cap on a scroll region.
+
+The width works the same way, and the mistake is the mirror image: **your outermost element FILLS the frame; a width cap belongs INSIDE it, on the column that holds text.**
+
+- Never put \`maxWidth\` (or a \`max-w-*\` class) on the element you return at the top. On a wide canvas that turns your card into a narrow strip with the frame's ground on either side of it, and on a narrow one it does nothing \u2014 the same composition reading differently at two sizes.
+- DO cap the reading measure inside: a column of prose is easiest to read at 60\u201370 characters, so wrap the TEXT in a \`<Container maxWidth="sm">\` (or your own \`max-width\`) and leave the root filling. A hero band, a toolbar, a table or an image then still uses the whole width, which is what makes a wide card look composed rather than padded.
+- Centre that inner column with the container's own centring, not by shrinking the root \u2014 and give the card ONE column: every block of the reading flow (a heading, its text, and the chips or buttons that answer it) sits in a \`<Container>\` of the same \`maxWidth\`, so their left edges line up even where a full-width band runs between them.
+- **They are two different elements.** Even when the whole card is one column of text, the root still fills and the column sits INSIDE it \u2014 \`<Box padding="lg"><Container maxWidth="sm">\u2026</Container></Box>\`, never a root that is itself the container. A centred card is centring inside a filled frame, not a shrunken frame.`;
+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: ["heroGround", "onHeroGround"], role: "a hero / greeting panel \u2014 brand-tinted on a light host, the ink pair on a dark one" },
+  { names: ["sunken", "onSunken"], role: "wells, inputs at rest, code blocks + secondary text" },
+  { names: ["link"], role: "accent TEXT \u2014 eyebrows, taglines, links, labels, inline arrows: the brand's readable ink per mode; a bare primary-300\u2026600 as a text color fails tier-0 (universal.accent_text_ink)" },
+  { 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" },
+  {
+    names: ["tint-1", "tint-2", "tint-3", "tint-4", "tint-5", "tint-6", "tint-7", "tint-8"],
+    role: "categorical fills for DATA categories only (series, lanes, kinds, element groups) \u2014 never for state, never as decoration; the text on a tint is `onContainer` only, one short line, never muted text; the category is always also in words (a label or a legend); a category keeps its tint for the life of the card (assign from the data's order, never render order); more than eight categories: group to eight, or words only"
+  }
+];
+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 = taughtTokenManifest) {
+  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**: every control that dispatches an action (a button, a select whose change dispatches, an input that sends on Enter) stays pending from \`useActionPending('<action>')\` until the agent's answer repaints the card \u2014 \`<button disabled={sendPending} aria-busy={sendPending}>{sendPending ? 'Sending\u2026' : 'Send'}</button>\`. Only a control that dispatches the action carries its busy look; while it is pending, other controls of the same record may be disabled \u2014 nothing more (controls of other records, creation controls and the action's own cancel stay enabled); busy state the card owns (\`isLoading\`) the same way.
+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 = taughtTokenManifest) {
+  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,
+    TERMINAL_ACTIONS,
+    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,
+    FRAME_SIZING,
+    COMPONENT_STRUCTURE,
+    FREE_RESPONSIVE_INVARIANT,
+    FREE_ACCESSIBILITY,
+    ...inputs.profileSection !== void 0 && inputs.profileSection.length > 0 ? [inputs.profileSection] : [],
+    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,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  allowJs: false,
+  jsx: ts.JsxEmit.ReactJSX,
+  noEmit: true,
+  esModuleInterop: true,
+  // skipLibCheck so an unresolvable wrapper-internal import (the
+  // sandbox doesn't carry the wrapper's transitive deps) doesn't abort
+  // the program before we can read the symbol's callable signature.
+  skipLibCheck: true,
+  strict: true
+};
+var callSignatureCache = /* @__PURE__ */ new Map();
+var componentPropsCache = /* @__PURE__ */ new Map();
+function buildExtractorContext(dtsContent, names) {
+  const sourceFile = ts.createSourceFile(
+    VIRTUAL_DTS_PATH,
+    dtsContent,
+    ts.ScriptTarget.ESNext,
+    /* setParentNodes */
+    true,
+    ts.ScriptKind.TS
+  );
+  const defaultLibName = ts.getDefaultLibFileName(EXTRACTOR_COMPILER_OPTIONS);
+  const host = {
+    getSourceFile(fileName) {
+      if (fileName === VIRTUAL_DTS_PATH) return sourceFile;
+      const libContent = ts.sys.readFile(
+        ts.getDefaultLibFilePath(EXTRACTOR_COMPILER_OPTIONS).replace(
+          /[^/\\]+$/,
+          fileName
+        )
+      );
+      if (libContent !== void 0) {
+        return ts.createSourceFile(
+          fileName,
+          libContent,
+          ts.ScriptTarget.ESNext,
+          true,
+          ts.ScriptKind.TS
+        );
+      }
+      return void 0;
+    },
+    getDefaultLibFileName() {
+      return defaultLibName;
+    },
+    writeFile() {
+    },
+    getCurrentDirectory() {
+      return "/";
+    },
+    getCanonicalFileName(f) {
+      return f;
+    },
+    useCaseSensitiveFileNames() {
+      return true;
+    },
+    getNewLine() {
+      return "\n";
+    },
+    fileExists(f) {
+      if (f === VIRTUAL_DTS_PATH) return true;
+      return ts.sys.fileExists(f);
+    },
+    readFile(f) {
+      if (f === VIRTUAL_DTS_PATH) return dtsContent;
+      return ts.sys.readFile(f);
+    }
+  };
+  const program = ts.createProgram(
+    [VIRTUAL_DTS_PATH],
+    EXTRACTOR_COMPILER_OPTIONS,
+    host
+  );
+  const checker = program.getTypeChecker();
+  const parsed = program.getSourceFile(VIRTUAL_DTS_PATH);
+  if (parsed === void 0) {
+    return void 0;
+  }
+  const requested = new Set(names);
+  function isWrapperLocal(symbol) {
+    const decls = symbol?.getDeclarations();
+    if (decls === void 0) return false;
+    return decls.some((d) => d.getSourceFile().fileName === VIRTUAL_DTS_PATH);
+  }
+  const MAX_DEPTH = 4;
+  function renderType(t, depth) {
+    const plain = () => checker.typeToString(t, void 0, ts.TypeFormatFlags.NoTruncation);
+    if (depth >= MAX_DEPTH) return plain();
+    if ((t.getFlags() & ts.TypeFlags.Boolean) !== 0) return "boolean";
+    if (t.isUnion()) {
+      return t.types.map((member) => renderType(member, depth)).join(" | ");
+    }
+    if (t.isIntersection()) {
+      return t.types.map((member) => renderType(member, depth)).join(" & ");
+    }
+    const symbol = t.getSymbol() ?? t.aliasSymbol;
+    const callSigs = t.getCallSignatures();
+    if (callSigs.length > 0) {
+      const cs = callSigs[0];
+      const params = cs.getParameters().map((p) => {
+        const decl = p.valueDeclaration ?? p.declarations?.[0];
+        const pType = decl !== void 0 ? checker.getTypeOfSymbolAtLocation(p, decl) : checker.getDeclaredTypeOfSymbol(p);
+        const optional = decl !== void 0 && ts.isParameter(decl) && (decl.questionToken !== void 0 || decl.initializer !== void 0);
+        return `${p.getName()}${optional ? "?" : ""}: ${renderType(pType, depth + 1)}`;
+      }).join(", ");
+      const ret = renderType(cs.getReturnType(), depth + 1);
+      return `(${params}) => ${ret}`;
+    }
+    const isObject = (t.getFlags() & ts.TypeFlags.Object) !== 0;
+    const isArrayOrTuple = checker.isArrayType(t) || checker.isTupleType(t);
+    const typeArgs = t.typeArguments;
+    if (symbol !== void 0 && isObject && !isArrayOrTuple && !isWrapperLocal(symbol) && typeArgs !== void 0 && typeArgs.length > 0) {
+      const args = typeArgs.map((a) => renderType(a, depth + 1)).join(", ");
+      return `${symbol.getName()}<${args}>`;
+    }
+    if (symbol !== void 0 && isObject && !isArrayOrTuple && isWrapperLocal(symbol)) {
+      const props = checker.getPropertiesOfType(t);
+      if (props.length > 0) {
+        const body = props.map((p) => {
+          const decl = p.valueDeclaration ?? p.declarations?.[0];
+          const pType = decl !== void 0 ? checker.getTypeOfSymbolAtLocation(p, decl) : checker.getDeclaredTypeOfSymbol(p);
+          const optional = (p.getFlags() & ts.SymbolFlags.Optional) !== 0;
+          return `${p.getName()}${optional ? "?" : ""}: ${renderType(pType, depth + 1)}`;
+        }).join("; ");
+        return `{ ${body} }`;
+      }
+    }
+    return plain();
+  }
+  const moduleSymbol = checker.getSymbolAtLocation(parsed);
+  const exportSymbols = moduleSymbol !== void 0 ? checker.getExportsOfModule(moduleSymbol) : [];
+  const signaturesByName = /* @__PURE__ */ new Map();
+  for (const symbol of exportSymbols) {
+    const name = symbol.getName();
+    if (!requested.has(name)) continue;
+    if (signaturesByName.has(name)) continue;
+    const resolved = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+    const declarations = resolved.getDeclarations();
+    if (declarations === void 0 || declarations.length === 0) continue;
+    const declaration = declarations[0];
+    const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
+    const callSignatures = type.getCallSignatures();
+    if (callSignatures.length === 0) continue;
+    signaturesByName.set(name, callSignatures);
+  }
+  return { checker, renderType, signaturesByName };
+}
+function printCallSignature(sig, ctx) {
+  const params = sig.getParameters().map((p) => {
+    const decl = p.valueDeclaration ?? p.declarations?.[0];
+    const pType = decl !== void 0 ? ctx.checker.getTypeOfSymbolAtLocation(p, decl) : ctx.checker.getDeclaredTypeOfSymbol(p);
+    const optional = decl !== void 0 && ts.isParameter(decl) && (decl.questionToken !== void 0 || decl.initializer !== void 0);
+    return `${p.getName()}${optional ? "?" : ""}: ${ctx.renderType(pType, 0)}`;
+  }).join(", ");
+  const ret = ctx.renderType(sig.getReturnType(), 0);
+  return `(${params}) => ${ret}`.trim();
+}
+function printComponentProps(sig, ctx) {
+  const params = sig.getParameters();
+  if (params.length === 0) return "{}";
+  const propsParam = params[0];
+  const decl = propsParam.valueDeclaration ?? propsParam.declarations?.[0];
+  const propsType = decl !== void 0 ? ctx.checker.getTypeOfSymbolAtLocation(propsParam, decl) : ctx.checker.getDeclaredTypeOfSymbol(propsParam);
+  const rendered = ctx.renderType(propsType, 0);
+  if (rendered.length === 0 || rendered.includes('import("')) return void 0;
+  return rendered;
+}
+function extractCallSignaturesFromDts(dtsContent, hookNames) {
+  if (hookNames.length === 0 || dtsContent.trim().length === 0) {
+    return {};
+  }
+  const cacheKey = `${dtsContent}\0${[...hookNames].sort().join(",")}`;
+  const cached = callSignatureCache.get(cacheKey);
+  if (cached !== void 0) return cached;
+  const result = {};
+  const ctx = buildExtractorContext(dtsContent, hookNames);
+  if (ctx === void 0) {
+    callSignatureCache.set(cacheKey, result);
+    return result;
+  }
+  for (const [name, signatures] of ctx.signaturesByName) {
+    const printed = signatures.map((sig) => printCallSignature(sig, ctx)).filter((s) => s.length > 0 && !s.includes('import("')).join(" | ");
+    if (printed.length > 0) {
+      result[name] = printed;
+    }
+  }
+  callSignatureCache.set(cacheKey, result);
+  return result;
+}
+function extractComponentPropsFromDts(dtsContent, componentNames) {
+  if (componentNames.length === 0 || dtsContent.trim().length === 0) {
+    return {};
+  }
+  const cacheKey = `${dtsContent}\0${[...componentNames].sort().join(",")}`;
+  const cached = componentPropsCache.get(cacheKey);
+  if (cached !== void 0) return cached;
+  const result = {};
+  const ctx = buildExtractorContext(dtsContent, componentNames);
+  if (ctx === void 0) {
+    componentPropsCache.set(cacheKey, result);
+    return result;
+  }
+  for (const [name, signatures] of ctx.signaturesByName) {
+    const first = signatures[0];
+    if (first === void 0) continue;
+    const props = printComponentProps(first, ctx);
+    if (props !== void 0) {
+      result[name] = props;
+    }
+  }
+  componentPropsCache.set(cacheKey, result);
+  return result;
+}
+
+// src/boilerplate/system-prompt.ts
+function isHookExport(exp) {
+  return "hook" in exp;
+}
+function isComponentExport(exp) {
+  return "component" in exp;
+}
+var SHELL_DESCRIPTIONS = {
+  chat: "inline component inside ChatShell message bubble (~400px wide, compact)",
+  fullscreen: "the full host viewport, responsive layout \u2014 the frame stretches your root to its height; size to content, never to the viewport",
+  spatial: "floating AR/VR panel (~600px, touch-friendly)"
+};
+var SCREEN_DESCRIPTIONS = {
+  mobile: "single column, large touch targets",
+  tablet: "flexible columns, medium spacing",
+  desktop: "multi-column, dense layout",
+  universal: "responsive across all breakpoints"
+};
+function formatGadgetsSection(appGadgets, gadgetTypes) {
+  if (appGadgets.length === 0) {
+    return [
+      "When the contract declares a `clientCapabilities.gadgets` entry,",
+      "the hook MUST be one the operator has registered on",
+      "`App.gadgets`. The default ggui server seeds the 7",
+      "first-party STDLIB hooks; this server has none registered (the",
+      "operator's `ggui.json#app.gadgets` is empty). Don't",
+      "declare `clientCapabilities.gadgets` until a hook is registered."
+    ].join(" ");
+  }
+  const hookExports = appGadgets.flatMap(
+    (descriptor) => descriptor.exports.filter(isHookExport).map((exp) => ({ exp, descriptor }))
+  );
+  const componentExports = appGadgets.flatMap(
+    (descriptor) => descriptor.exports.filter(isComponentExport).map((exp) => ({ exp, descriptor }))
+  );
+  const header = "When the contract declares a hook gadget on `clientCapabilities.gadgets`, the hook MUST be one of the registered hooks below. The boilerplate has already emitted a direct import per gadget package \u2014 `import { <hook>, \u2026 } from '<package>'` \u2014 above a `// DO NOT EDIT` banner. KEEP those imports exactly; they are the runtime-resolution anchor and self_check rejects the code if one disappears. Import each STDLIB hook from `@ggui-ai/gadgets`; import each third-party hook from the package named in the `Package` column. DO NOT invent your own import paths. Available registered hooks:";
+  const tableHead = [
+    "| Hook                  | Package (import from here)         | Permission         | What it does                                |",
+    "| --------------------- | ---------------------------------- | ------------------ | ------------------------------------------- |"
+  ];
+  const rows = hookExports.map(({ exp, descriptor }) => {
+    const hookCol = `\`${exp.hook}\``.padEnd(21, " ");
+    const pkgCol = `\`${descriptor.package}\``.padEnd(34, " ");
+    const permCol = exp.permission ? `\`${exp.permission}\``.padEnd(18, " ") : "(none)".padEnd(18, " ");
+    const what = (exp.usage ?? exp.description ?? "").replace(/\s+/g, " ").trim().slice(0, 80);
+    return `| ${hookCol} | ${pkgCol} | ${permCol} | ${what.padEnd(43, " ")} |`;
+  });
+  const typeLines = [];
+  if (gadgetTypes !== void 0) {
+    for (const { exp, descriptor } of hookExports) {
+      const dts = gadgetTypes[descriptor.package];
+      if (dts === void 0) continue;
+      const signatures = extractCallSignaturesFromDts(dts, [exp.hook]);
+      const sig = signatures[exp.hook];
+      if (sig === void 0) continue;
+      typeLines.push(`- \`${exp.hook}\`: \`${sig}\``);
+    }
+  }
+  const typeBlock = typeLines.length > 0 ? [
+    "",
+    "**Type** (third-party gadgets \u2014 call signature from the wrapper's published `.d.ts`):",
+    "",
+    ...typeLines
+  ] : [];
+  const hookSection = hookExports.length > 0 ? [header, "", ...tableHead, ...rows, ...typeBlock].join("\n") : "";
+  const componentRows = componentExports.map(({ exp, descriptor }) => {
+    const compCol = `\`${exp.component}\``.padEnd(21, " ");
+    const pkgCol = `\`${descriptor.package}\``.padEnd(34, " ");
+    const what = (exp.usage ?? exp.description ?? "").replace(/\s+/g, " ").trim().slice(0, 80);
+    return `| ${compCol} | ${pkgCol} | ${what.padEnd(53, " ")} |`;
+  });
+  const componentPropsLines = [];
+  if (gadgetTypes !== void 0) {
+    for (const { exp, descriptor } of componentExports) {
+      const dts = gadgetTypes[descriptor.package];
+      if (dts === void 0) continue;
+      const propsMap = extractComponentPropsFromDts(dts, [exp.component]);
+      const props = propsMap[exp.component];
+      if (props === void 0) continue;
+      componentPropsLines.push(`- \`${exp.component}\`: \`${props}\``);
+    }
+  }
+  const componentPropsBlock = componentPropsLines.length > 0 ? [
+    "",
+    "**Props** (third-party component gadgets \u2014 prop shape from the wrapper's published `.d.ts`):",
+    "",
+    ...componentPropsLines
+  ] : [];
+  const componentSection = componentExports.length > 0 ? [
+    "When the contract declares a component gadget on `clientCapabilities.gadgets`, the export is a COMPONENT \u2014 RENDER it as a JSX element (`<X \u2026 />`) in the tree you return. Do NOT call it like a hook. The boilerplate has already emitted a direct import per gadget package \u2014 `import { <Component>, \u2026 } from '<package>'` \u2014 above a `// DO NOT EDIT` banner. KEEP those imports exactly; they are the runtime-resolution anchor and self_check rejects the code if one disappears. Import each component from the package named in the `Package` column. Available registered components:",
+    "",
+    "| Component             | Package (import from here)         | What it does                                          |",
+    "| --------------------- | ---------------------------------- | ----------------------------------------------------- |",
+    ...componentRows,
+    ...componentPropsBlock
+  ].join("\n") : "";
+  return [hookSection, componentSection].filter((section) => section.length > 0).join("\n\n");
+}
+function buildSystemPrompt(inputs) {
+  const shell = inputs.shellType ?? "fullscreen";
+  const scr = inputs.screen ?? "universal";
+  const shellDesc = SHELL_DESCRIPTIONS[shell] ?? SHELL_DESCRIPTIONS.fullscreen;
+  const screenDesc = SCREEN_DESCRIPTIONS[scr] ?? SCREEN_DESCRIPTIONS.universal;
+  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 ?? "";
+  const wireDoc = inputs.wireDoc ?? "";
+  const gadgetsSection = formatGadgetsSection(
+    resolveAppGadgets(inputs.appGadgets),
+    inputs.gadgetTypes
+  );
+  const profileSection = buildStylingProfileSection(inputs.profile);
+  const axisSection = inputs.axisDelta && inputs.axisDelta.trim().length > 0 ? `
+## 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,
+      profileSection
+    });
+  }
+  return `You are ggui's UI builder. You receive a typed boilerplate and fill it in using apply_changes.
+
+## Your Task
+${inputs.userRequest}
+
+## Rendering Context
+- **Shell**: \`${shell}\` \u2014 ${shellDesc}
+- **Screen**: \`${scr}\` \u2014 ${screenDesc}
+
+## How It Works
+1. Read the boilerplate \u2014 typed Props, wire hooks, and layout container are pre-configured
+2. Respond with one apply_changes call \u2014 add state, helpers, and JSX
+3. If compilation or evaluation fails, you'll get errors to fix in the next turn
+
+${criteriaBlock}
+${axisSection}
+` + [
+    PROTOCOL_NOTES,
+    CONTRACT_SURFACE,
+    DEFENSIVE_CODING,
+    GESTURE_ROUTING,
+    TERMINAL_ACTIONS,
+    INTERACTIVE_TRAITS,
+    ANTI_PATTERNS,
+    CROSS_REFERENCE_RULES,
+    renderGadgetCatalogSection(gadgetsSection),
+    CONTEXT_SPEC_SECTION
+  ].join("\n\n") + `
+
+${pitfallsBlock}
+
+## Reference: Wire Hooks
+${wireDoc}
+
+${withStylingProfile(DESIGN_SYSTEM_GUIDANCE, profileSection)}
+
+### CSS Token Documentation
+${designSystemDocs}
+
+### Component Reference
+${primitivesDoc}
+`;
+}
+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.
+
+Available primitives (all from \`@ggui-ai/design\`):
+- Layout: Box, Container, Stack, Row, Grid, Spacer, Divider
+- Typography: Heading, Text, Link
+- Form: Button, Input, TextArea, Checkbox, Toggle, RadioGroup, Select, Slider
+- Display: Card, Alert, Badge, Avatar, Image, Icon, Progress, Spinner, Skeleton, Tooltip
+- Composite: Accordion, Tabs, Table, Toast
+
+Available compound components (all from \`@ggui-ai/design\`):
+- Autocomplete, Breadcrumb, Dropdown, EmptyState, FormField, Markdown, MarkdownInline, MenuItem, Pagination, SearchField, Stat, Stepper, Tag
+
+**Choosing between similar components** \u2014 pick by intent, don't guess:
+- **Pick from options**: one value from a short fixed list (a form field) \u2192 \`Select\`. Type-to-filter a long list, then pick \u2192 \`Autocomplete\`. A menu of actions off a button (edit / delete / \u2026) \u2192 \`Dropdown\`. A search box that filters displayed content \u2192 \`SearchField\`.
+- **Tabular data** \u2192 \`Table\`. Reach for \`DataTable\` ONLY when you need built-in sorting / pagination / row-selection.
+- **Messaging**: an inline message in the layout flow \u2192 \`Alert\`. A transient popup \u2192 \`Toast\`. A panel listing many notifications \u2192 \`NotificationCenter\`.
+- **Step progress**: a wizard's step indicator \u2192 \`Stepper\`. NOT \`Tabs\` (implies free navigation), NOT \`Progress\` (continuous bar), NOT \`Breadcrumb\` (hierarchy).
+- **Containers**: width-constrain a page region \u2192 \`Container\`. A visually-contained surface (background + shadow + border) \u2192 \`Card\`. Plain grouping / spacing with no chrome \u2192 \`Box\`.
+
+EXACT primitive prop values (other values are silently ignored \u2014 the design system maps them to defaults):
+- \`<Text size="...">\` \u2014 ONLY \`xs | sm | base | lg | xl | 2xl | 3xl | 4xl\`. For a HUGE number/temperature, use \`<Text size="4xl" weight="bold">\`. \`caps\` uppercases with letter-spacing \u2014 the eyebrow/overline label look is \`<Text size="xs" weight="semibold" caps tone="muted">\`.
+- \`<Text weight="...">\` \u2014 \`normal | medium | semibold | bold\`.
+- \`<Text tone="...">\` \u2014 typed semantic slot. \`default | muted | subtle | emphasized | loud | success | warning | error | info | inverse | inherit\`. The theme decides what each tone LOOKS like \u2014 \`muted\` is a quiet warm grey on Claudic, a cool slate on Indigo. \`tone\` is the ONLY way to set Text color; the legacy \`color="..."\` prop has been removed.
+- \`<Heading level={1|2|3|4|5|6}>\` \u2014 sizes are preset by level (h1 = 4xl bold, h2 = 3xl bold, h3 = 2xl semibold). Pass a number, not \`level="h1"\`. Heading uses the same \`tone\` slot vocabulary as Text.
+- \`<Icon name="..." tone="...">\` / \`<Spinner tone="...">\` / \`<Link href="..." tone="...">\` / \`<Divider tone="...">\` \u2014 same \`tone\` vocabulary as Text. Default = \`currentColor\` (Icon), primary-tinted (Spinner / Link), outlineVariant (Divider). Use \`tone="inherit"\` when you want the element to track the parent's foreground color (e.g. an Icon next to muted text).
+- \`<Button variant="...">\` \u2014 \`primary | secondary | outline | ghost | danger\`. Sizes \`xs | sm | md | lg\`. Use \`primary\` for the main action \u2014 renders in the brand color automatically.
+- \`<Card padding="lg" shadow="md" radius="lg" surface="default">\` \u2014 shadow \`none|sm|md|lg|xl\`, radius \`none|sm|md|lg|xl\`. \`surface\` slot picks the fill: \`default | elevated | sunken | accent | inverted | hero | transparent\`. Use \`inverted\` for dark testimonial-style cards on a light theme; \`accent\` for branded fills; \`hero\` for the one hero / greeting panel (the theme's hero ground: brand-tinted on a light host, the ink pair on a dark one). \`inverted\` and \`hero\` OWN their ground \u2014 never set \`background\` in their \`style\` (tier-0 fails it); the surface paints it.
+- \`<Box surface="...">\` \u2014 same surface slots as Card. \`surface\` (layout slots) and \`tint\` (data categories) are the ONLY theme-tracking background props; the legacy \`background="..."\` prop has been removed. To colour by a DATA CATEGORY (series, lanes, kinds, tags, element groups), use \`tint="tint-1"\`\u2026\`"tint-8"\` (see "Categorical tint" below). For non-theme-mapped brand colors (a partner's exact brand hex like Stripe purple), use the typed escape \`<Box assetColor="#635BFF" assetSemantic="stripe-brand-purple">\` \u2014 both props are required, and \`assetSemantic\` MUST be a non-empty human-readable label. Tier-0 self-check rejects every other hex / rgba on Box.
+- \`<Stack gap="...">\` / \`<Row gap="...">\` \u2014 \`gap\` takes the **spacing scale** (next bullet). \`align\` (cross-axis) is ONLY \`start | center | end | stretch\` and \`justify\` (main-axis) is ONLY \`start | center | end | between | around | evenly\` \u2014 NEVER the raw CSS values \`flex-start\` / \`flex-end\` / \`space-between\`, which are type errors.
+- **Spacing scale** \u2014 \`gap\` (Stack / Row / Grid) and \`padding\` (Card / Box / Container) take a t-shirt size: \`none | xs | sm | md | lg | xl | 2xl\`. Each resolves to a \`--ggui-spacing-*\` token (xs\u22484px, sm\u22488px, md\u224816px, lg\u224824px, xl\u224832px, 2xl\u224848px). A bare number is treated as pixels. NEVER pass a raw CSS length such as \`gap="8px"\` \u2014 it is silently dropped by the browser and the gap collapses to 0; use the scale name (\`gap="sm"\`).
+- **One content edge per card** \u2014 on \`Card\` and \`Box\`, \`padding\` sets the VERTICAL rhythm; the card owns the horizontal inset. Every block's content sits on the card's one left edge, and a filled or bordered surface steps its own content in by exactly one inset. So never use \`paddingX\` to push content sideways or a padded unstyled wrapper to indent a list. A badge, date or action on the right of a line belongs in a \`<Row justify="between">\` with content on its left, never alone on its own line.
+- \`<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 | 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'\`).
+
+**Asset-color escape (Box only).** When you genuinely need a non-theme color \u2014 a partner's exact brand hex (Stripe purple \`#635BFF\`, Slack aubergine \`#4A154B\`), a fixed product surface \u2014 use \`<Box assetColor="#635BFF" assetSemantic="stripe-brand-purple">\u2026</Box>\`. The \`assetSemantic\` is REQUIRED and MUST be a non-empty human-readable label that documents intent. Tier-0 allows hex inside this typed pair; one without the other fails the check. Reach for \`surface\` first \u2014 \`assetColor\` is rare.
+
+**Categorical tint (data categories).** When cells, rows or swatches must be told apart by a data category \u2014 element groups in a periodic table, lanes on a board, series in a chart legend, tags \u2014 set \`tint="tint-1"\` \u2026 \`tint="tint-8"\` on the Box or Card. The eight steps are theme colours: they follow the operator's theme in light and dark, and the tinted surface sets its own readable text colour. Rules:
+- Tints are for **data categories only** \u2014 never for state (a status takes live, draft or signal, not a tint) and never as decoration.
+- The category is **always also in words** \u2014 a label in the cell or a legend on the card. Colour is never the only way to tell categories apart.
+- **Text on a tint is the theme's ink only, one short line** \u2014 a label, a symbol or a value, never \`tone="subtle"\` or muted text. Secondary or muted text sits beside the cell or in the legend, never on the tint.
+- **A category keeps its tint for the life of the card.** Assign tints deterministically from the data, in the order the categories are first listed or sorted, never by render order, so an update or repaint never recolours a category.
+- **More than eight categories:** group them to eight before assigning, or show the category in words only.
+- Never put a theme colour through \`assetColor\` \u2014 that escape is only for an exact external brand hex.
+
+## Accessibility (REQUIRED)
+
+The design-system primitives are accessible by construction \u2014 they emit their own roles, labels, keyboard handlers, and error wiring. Your job is to USE them correctly, NOT to re-declare ARIA on top of them.
+
+1. **Form inputs** \u2014 give every \`Input\` / \`TextArea\` / \`Select\` a \`label\` prop. The primitive renders its own \`<label htmlFor>\`, and exposes \`aria-invalid\` + \`aria-describedby\` for errors. Do NOT add a separate \`<Text>\` label or your own \`htmlFor\` \u2014 that double-labels the field.
+   \`\`\`tsx
+   <Input label="Email" value={email} onChange={setEmail} type="email" />
+   \`\`\`
+2. **Don't re-declare built-in ARIA.** \`Progress\`, \`RadioGroup\`, \`Tabs\`, \`Toggle\`, \`Slider\`, \`Spinner\`, \`Alert\`, \`Accordion\` already carry the correct \`role\` / \`aria-*\`. \`Card as={Clickable}\` already adds \`role="button"\` + keyboard activation. Adding your own is redundant and often wrong.
+3. **Icons are decorative by default** \u2014 \`<Icon name="check" />\` is hidden from screen readers, which is correct for an icon sitting next to text. Add \`aria-label\` ONLY for a standalone, meaning-bearing icon with no adjacent text. Icon-only \`Button\`s still need \`aria-label\` on the **Button** itself.
+4. **Live & streaming data** \u2014 wrap any region whose content updates on its own (a \`useStream\` \`.latest\` value, a live clock, an "N new" counter, a flashing price) in an element with \`aria-live="polite"\` so screen readers announce the change.
+5. **Headings nest** \u2014 one \`<Heading level={1}>\` per screen, \`level={2}\` for sections, \`level={3}\` for subsections. Never skip or invert levels.
+6. **Buttons** \u2014 descriptive text content; icon-only buttons need \`aria-label\`. Announce busy state. EVERY control that dispatches an action \u2014 a Button, a Select whose change dispatches, an Input that sends on Enter \u2014 stays pending from that action's \`useActionPending\` until the agent's answer repaints the card: with \`const sendPending = useActionPending('send');\`, write \`<Button disabled={sendPending} aria-busy={sendPending} onClick={() => send({ text })}>{sendPending ? 'Sending\u2026' : 'Send'}</Button>\`, and give a dispatching Select or Input the same \`disabled={sendPending} aria-busy={sendPending}\`. Only a control that dispatches the action carries its \`aria-busy\` and a working label. While it is pending, other controls of the SAME record may be \`disabled\` \u2014 nothing more; controls of other records, creation controls and the action's own cancel stay enabled. Busy state the card owns (a local \`isLoading\`) is announced the same way.
+7. **Stateful controls announce their state.** Toggleable / selectable / expandable things use the primitive that carries the semantics (\`Checkbox\`, \`Toggle\`, \`Tabs\`, \`Accordion\`) \u2014 never a styled \`Box\`/\`Icon\` that only *looks* checked. When you hand-roll one with \`as={Clickable}\`, \`Clickable\` adds button + keyboard semantics but NOT state \u2014 add it yourself: \`role="checkbox"\` + \`aria-checked={done}\` 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 icon) must never be the only carrier of state.
+
+## Design System Usage (CRITICAL)
+
+EVERY color, spacing, typography, shadow, and radius value MUST come from design-system CSS variables. The runtime injects them on \`:root\`.
+
+MANDATORY:
+1. NEVER use hardcoded hex colors like \`#7c3aed\` \u2014 ONLY \`var(--ggui-color-*)\` tokens.
+2. NEVER use CSS gradients with custom colors. If you need a gradient: \`linear-gradient(to bottom, var(--ggui-color-primary-500), var(--ggui-color-primary-700))\`.
+3. NEVER invent your own palette. The system provides primary, neutral, success, warning, error, and info \u2014 use ONLY these.
+4. NEVER include literal fallback values in ANY token reference \u2014 colors, spacing, typography, radius, shadows alike. Write \`var(--ggui-spacing-4)\` bare, never \`var(--ggui-spacing-4, 16px)\`; \`var(--ggui-color-primary-600)\` bare, never \`var(--ggui-color-primary-600, #0284c7)\`. The runtime injects every token; a literal fallback paints the wrong value exactly when the operator's theme matters most.
+5. NEVER set an inline \`border\`, \`borderColor\`, \`borderWidth\` or \`borderStyle\` on a kit control \u2014 \`Button\`, \`Input\`, \`Select\`, \`TextArea\`, \`Checkbox\`, \`RadioGroup\`, \`Toggle\`, \`SearchField\`. The control draws its own boundary, and it clears 3:1 on its surface in every theme: an outline chip is \`<Button variant="outline">\` exactly as it comes (its edge is \`controlAccentOutline\`). Where you draw a control-like edge on your own element, use \`var(--ggui-color-controlOutline)\`. A ramp step such as \`primary-200\` as a control's border is nearly invisible (about 1.1:1). Its ink and fill are the variant's too: NEVER set an inline \`color\`, \`background\` or \`backgroundColor\` on a kit control, a token as much as a literal \u2014 pick the variant that carries the look.
+
+Token categories:
+- Brand fills: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
+- Accent text: \`var(--ggui-color-link)\` \u2014 eyebrows, taglines, links, labels; readable per mode (never a bare \`primary-<stop>\` as a text color)
+- Text: \`var(--ggui-color-onContainer)\`, \`var(--ggui-color-onSunken)\`
+- Backgrounds: \`var(--ggui-color-container)\`, \`var(--ggui-color-sunken)\`
+- Borders: \`var(--ggui-color-outline)\` \u2014 dividers and the edges of non-interactive boxes; a control's edge is the kit's (rule 5)
+- Spacing: \`var(--ggui-spacing-4)\`, \`var(--ggui-spacing-6)\`
+- Typography: \`var(--ggui-font-size-sm)\`, \`var(--ggui-font-weight-semibold)\`
+- Shadows: \`var(--ggui-shape-shadow-sm)\`, \`var(--ggui-shape-shadow-md)\`, \`var(--ggui-shape-shadow-lg)\`
+- Radius: \`var(--ggui-shape-radius-md)\`, \`var(--ggui-shape-radius-lg)\`
+
+Prefer primitives' built-in styling props over inline styles when possible.
+
+### Branded Color Strategy
+
+Use the FULL primary palette throughout the component \u2014 NOT only on submit buttons. A well-themed component feels distinctly branded, not gray-with-one-colored-button.
+
+| Element | Token | Purpose |
+|---------|-------|---------|
+| Section headers, hero areas, highlight strips | \`primary-50\` / \`primary-100\` | Subtle branded backgrounds |
+| Dividers, section rules, edges of non-interactive boxes | \`primary-200\` / \`primary-300\` | Branded structure \u2014 never a control's border (rule 5) |
+| Accent TEXT \u2014 eyebrows, taglines, links, labels, inline arrows | \`link\` (\`var(--ggui-color-link)\`) or \`<Text tone="emphasized">\` | The brand's READABLE ink, derived per mode to clear 4.5:1 \u2014 a bare \`primary-300\u2026600\` as a text color fails tier-0 |
+| Icon fills, badges, active indicators | \`primary-500\` / \`primary-600\` | Core accent fill |
+| 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 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
+
+Components MUST be theme-agnostic \u2014 they reference CSS variables but NEVER assume a specific style. The theme decides what \`primary-600\` looks like.
+
+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; 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
+- Don't hardcode gradients tuned for a specific theme
+- Don't use fixed shadow values
+
+Visual hierarchy via tokens:
+- Elevated sections: \`var(--ggui-shape-shadow-md)\` + \`var(--ggui-shape-radius-lg)\`
+- Highlighted regions: \`var(--ggui-color-primary-50)\` background
+- Active/selected: \`var(--ggui-color-primary-100)\` background
+- Section headers / eyebrows: \`var(--ggui-color-link)\` text, or a \`var(--ggui-color-primary-600)\` border-bottom
+
+## Responsive Design (CRITICAL)
+
+Generated components become reusable blueprints \u2014 the same blueprint serves phones, tablets, desktops, spatial headsets. Design for ALL screen sizes:
+
+1. Design tokens for ALL spacing \u2014 never hardcode pixel values for padding/margins/gaps. Use the named spacing scale on props (\`gap="md"\`, \`padding="lg"\`); for inline \`style\` use \`var(--ggui-spacing-*, \u2026)\`.
+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.`;
+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
+
+A polished UI has ONE hero that dominates. Everything else supports it. Bad layouts have everything at similar sizes \u2014 the eye has nowhere to land. The rule:
+
+**Hero metric vs supporting text must have a 2\u20133\xD7 size gap.** If the hero is the temperature, score, count, status, price \u2014 it's ENORMOUS. Use \`<Text size="4xl" weight="bold">\` \u2014 the largest \`size\` the type allows (\`4xl\` = 36px). Pair it with a small supporting label (\`size="sm"\`, ~14px) so the gap reads as 2\u20133\xD7. The hero number should feel oversized compared to the location/title around it. \`size\` accepts ONLY \`xs | sm | base | lg | xl | 2xl | 3xl | 4xl\` \u2014 \`5xl\` / \`6xl\` are NOT valid and fail tier-0 type-check.
+
+\`\`\`tsx
+// BAD \u2014 temperature is the same size as the location heading
+<Heading level={1}>Seoul, South Korea</Heading>
+<Text size="lg" weight="bold">18\xB0C</Text>
+
+// GOOD \u2014 temperature dominates (4xl), location supports it (sm)
+<Text size="sm" tone="muted">Seoul, South Korea</Text>
+<Text size="4xl" weight="bold">18\xB0C</Text>
+<Text size="lg" tone="muted">Partly Cloudy \xB7 Feels like 16\xB0C</Text>
+\`\`\`
+
+### Color discipline \u2014 the 60/30/10 rule
+
+Don't paint everything in primary. Use:
+- **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 \`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
+<Heading tone="emphasized">Title</Heading>
+<Text tone="emphasized">42</Text>
+<Text tone="emphasized">all body text</Text>
+
+// GOOD \u2014 hero pops, body is neutral, primary is reserved
+<Heading>Title</Heading>  {/* defaults to onContainer */}
+<Text size="4xl" weight="bold" tone="emphasized">42</Text>
+<Text tone="muted">all body text</Text>
+\`\`\`
+
+### Visual rhythm \u2014 vary your card treatments
+
+A row of identical flat tiles feels monotone. Use card-treatment variation to create rhythm:
+- **Hero card**: \`<Card surface="hero" padding="xl" shadow="lg" radius="xl">\` \u2014 the theme's hero ground (brand-tinted on a light host, the ink pair on a dark one); anchors the eye.
+- **Stat tiles**: \`<Card padding="md" shadow="sm" radius="md">\` with surface bg \u2014 secondary
+- **Inline rows / list items**: no card chrome at all, just \`<Stack gap="sm">\` with dividers \u2014 tertiary
+
+The hero should literally have higher elevation than the supporting tiles. If everything has \`shadow="md"\`, nothing does.
+
+### Iconography \u2014 emoji + Icon are visual weight on the cheap
+
+Don't render text-only metrics. A weather widget without a sun/cloud, a stock card without an arrow, a status panel without a colored dot \u2014 all feel undersold. Pair every hero metric with an icon or emoji at large size:
+
+\`\`\`tsx
+<Row gap="md" align="center">
+  <Text size="3xl">\u2600\uFE0F</Text>
+  <Stack gap="xs">
+    <Text size="4xl" weight="bold">18\xB0C</Text>
+    <Text size="sm" tone="muted">Sunny \xB7 feels like 16\xB0</Text>
+  </Stack>
+</Row>
+\`\`\`
+
+Use \`<Icon name="..." />\` for line icons \u2014 ONLY the design system's curated set renders (~200 kebab-case Lucide names); a name OUTSIDE it renders an empty box and fails the check. On a single-pass render you cannot look the set up, so use ONLY a name you are sure is in it. Safe common names: \`check\` \`x\` \`plus\` \`minus\` \`search\` \`settings\` \`user\` \`users\` \`calendar\` \`clock\` \`arrow-right\` \`arrow-left\` \`chevron-right\` \`chevron-down\` \`trash-2\` \`edit\` \`info\` \`alert-circle\` \`bell\` \`home\` \`file\` \`file-text\` \`star\` \`heart\` \`mail\` \`send\` \`download\` \`upload\` \`external-link\` \`filter\` \`check-circle\`. The numbered variants (\`edit-2\`, \`edit-3\`) and synonyms (\`pencil\`, \`pen\`, \`trash\`, \`x-circle\`) are NOT in the set \u2014 use \`edit\` and \`trash-2\`. If the icon you want is not clearly one of these, OMIT it: a card with no icon beats one with an empty box. Emoji render directly for status/weather/mood. For per-stat tiny accents, use a small icon next to the label.
+
+### Spacing \u2014 generosity beats compactness
+
+Hero sections should feel airy. Use \`padding="xl"\` (32px) on the main card, not \`padding="md"\`. Whitespace IS design. A cramped polished card looks worse than a roomy plain one.
+
+### Concrete recipes
+
+- **Hero metric card** (weather, stock, score): hero number at \`size="4xl"\` (the max), icon/emoji at \`size="3xl"\` next to it (use \`<Row gap="md">\`), supporting label at \`size="sm"\` muted, branded gradient bg, \`shadow="lg"\`, \`padding="xl"\`.
+- **Stat grid** (3\u20136 quick metrics): \`<Grid columns={3} gap="md">\` of \`<Stat>\` \u2014 each \`<Stat label="\u2026" value="\u2026" delta="\u2026" trend="\u2026" />\` handles the label-on-top / value-below / trend-coloured-delta layout for you. Wrap each in a \`<Card padding="md" shadow="sm">\` if you want tile chrome.
+- **List item** (forecast day, todo, message): no card per item, use \`<Stack gap="md">\` with each row as \`<Row gap="md">\` of icon + content + meta. Add \`<Divider>\` between rows.
+- **Multi-step wizard** (survey, onboarding, checkout): \`<Stepper steps={STEPS} current={step} />\` at the top, the current step's fields below, Next/Back buttons that move \`step\`. Don't hand-roll a "2 of 4" indicator.
+- **Key-value rows** (specs, order summary, flight details): \`<Stack gap="sm">\` of \`<Row justify="between">\` \u2014 label as \`<Text size="sm" tone="muted">\`, value as \`<Text size="sm" weight="medium">\`.
+- **Section header**: \`<Heading level={2}>\` left-aligned, optional \`<Badge>\` to its right for count/status, optional muted caption below.
+- **CTA section**: ONE primary button. Other actions as ghost/outline. Don't stack three primary buttons.
+
+## Quality Checklist (verify before returning)
+
+- [ ] Imports ONLY from: react, @ggui-ai/design, @ggui-ai/wire
+- [ ] No raw HTML elements (\`<button>\`, \`<input>\`, \`<div>\` for layout) \u2014 uses primitives
+- [ ] ZERO hardcoded hex colors \u2014 every color is a bare \`var(--ggui-color-*)\`, no literal fallback
+- [ ] No raw pixel values for spacing \u2014 all via \`var(--ggui-spacing-*)\` tokens
+- [ ] Primary palette used throughout (headers, borders, icons) \u2014 not just buttons
+- [ ] Typed Props interface exported; request-specific data is a prop with default
+- [ ] Every Input/TextArea/Select has a \`label\` prop (no separate \`<Text>\` label)
+- [ ] Icon-only buttons have \`aria-label\`; no redundant \`role\`/\`aria-*\` on primitives
+- [ ] Toggleable/selected/expanded 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 \`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,
+  FRAME_SIZING,
+  COMPONENT_STRUCTURE,
+  DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST
+].join("\n\n");
+
+export { buildSystemPrompt, generateBoilerplate };
+//# sourceMappingURL=chunk-FB7OEEAH.js.map
+//# sourceMappingURL=chunk-FB7OEEAH.js.map