@ggui-ai/ui-gen 0.15.0 → 0.16.0

package/src/boilerplate/free-design-prompt.ts

@@ -0,0 +1,329 @@
+// packages/ui-gen/src/boilerplate/free-design-prompt.ts
+//
+// The `designMode: 'free'` system prompt. Same skeleton contract as the
+// constrained builder — deterministic assembly from caller-supplied
+// injection fields — but the DESIGN vocabulary is relaxed: no primitive
+// prop enums, no branded-palette / 60-30-10 / aesthetic recipes, no
+// "never raw HTML" rule, no mandatory primitive catalog. Everything that
+// is a HARD contract is shared verbatim with the constrained prompt via
+// `./hard-sections.ts`:
+//   Protocol Notes · Contract surface · Defensive coding · gesture
+//   routing · Anti-patterns · Cross-reference rules · gadget catalog ·
+//   contextSpec · Data Parameterization · Component Structure · the
+//   wire-hooks reference.
+// What this file ADDS (the constraint set the free arm is given
+// explicitly): design freedom · color stays tokenized · where this
+// renders (host envelope) · the rendering canvas · budgets · imports +
+// security · the responsiveness invariant · the a11y OUTCOME bar written
+// for raw elements · the one-gesture-surface invariant restated for raw
+// elements · a regenerated quality checklist.
+
+import { consumedTokenManifest } from "@ggui-ai/design/themes";
+import { describeCanvas, type CanvasClass } from "../design-mode.js";
+import {
+  ANTI_PATTERNS,
+  COMPONENT_STRUCTURE,
+  CONTEXT_SPEC_SECTION,
+  CONTRACT_SURFACE,
+  CROSS_REFERENCE_RULES,
+  DATA_PARAMETERIZATION,
+  DEFENSIVE_CODING,
+  GESTURE_ROUTING,
+  PROTOCOL_NOTES,
+  renderGadgetCatalogSection,
+} from "./hard-sections.js";
+
+export interface FreeDesignPromptInputs {
+  readonly userRequest: string;
+  readonly canvas: CanvasClass;
+  /** Pre-rendered `## Shape Guidance` section (empty string when no axis fragments fired). */
+  readonly axisSection: string;
+  /** Pre-rendered P0/P1/P2 criteria summary (free-mode criteria). */
+  readonly criteriaBlock: string;
+  readonly wireDoc: string;
+  readonly primitivesDoc: string;
+  /** Rendered gadget-catalog table (from `formatGadgetsSection`). */
+  readonly gadgetsSection: string;
+}
+
+/**
+ * The one-gesture-surface-per-binding invariant, restated for raw
+ * elements. The constrained prompt carries the same rule in
+ * design-package vocabulary (`INTERACTIVE_TRAITS`).
+ */
+export const 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 — 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) — 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 — pick one surface.`;
+
+export const 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>\`, …), inline \`style\` props and \`<style>\` blocks — 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 — 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 — \`import { Skeleton, EmptyState, Icon } from '@ggui-ai/design'\` — 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 — next section.`;
+
+const COLOR_PREFIX = "--ggui-color-";
+
+/** Ramp families the manifest MAY carry, in the order the prompt lists them. */
+const RAMP_FAMILIES = ["primary", "neutral", "success", "warning", "error", "info"] as const;
+
+export interface ColorRamp {
+  readonly family: string;
+  /** Numeric steps present in the manifest, ascending — the WHOLE ramp. */
+  readonly steps: readonly number[];
+  /** Whether the bare `--ggui-color-<family>` token also exists. */
+  readonly bare: boolean;
+}
+
+/**
+ * Semantic (non-ramp) color roles, grouped for the prose. A group renders
+ * only the names the manifest actually carries and is dropped when none
+ * do; manifest roles not named here land under "other roles".
+ */
+const SEMANTIC_ROLES: ReadonlyArray<{ readonly names: readonly string[]; readonly role: string }> = [
+  { 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 — floats above a container" },
+  { names: ["sunken", "onSunken"], role: "wells, inputs at rest, code blocks + secondary text" },
+  { names: ["ground-subtle", "ground-gradient"], role: "quiet canvas fills" },
+  { names: ["onPrimary"], role: "text on the brand color" },
+  { names: ["outline", "outlineVariant"], role: "borders + dividers" },
+  { names: ["onError"], role: "text on an error fill" },
+];
+
+/** Split the manifest's `--ggui-color-*` names into ramps (family + numeric steps) and semantic roles. */
+export function colorVocabularyFromManifest(manifest: readonly string[]): {
+  readonly ramps: readonly ColorRamp[];
+  readonly roles: readonly string[];
+} {
+  const colors = manifest.filter((t) => t.startsWith(COLOR_PREFIX)).map((t) => t.slice(COLOR_PREFIX.length));
+  const ramps: ColorRamp[] = [];
+  const claimed = new Set<string>();
+  for (const family of RAMP_FAMILIES) {
+    const steps: number[] = [];
+    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: ColorRamp): string {
+  return `\`${r.family}-${r.steps.join("/")}\`${r.bare ? ` (plus bare \`${r.family}\`)` : ""}`;
+}
+
+/**
+ * The one hard styling rule of the free arm, with the color vocabulary
+ * rendered FROM the closed consumed-token manifest (the same set
+ * `tokens:off-manifest-token` checks against) — every ramp step and
+ * every role the prose names exists on `:root`; nothing is implied by a
+ * `50…800` range that the manifest does not carry step for step.
+ */
+export function renderFreeColorRule(manifest: readonly string[] = consumedTokenManifest): string {
+  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: string[] = [];
+  const named = new Set<string>();
+  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 — text, backgrounds, borders, fills, gradient stops, focus rings, shadow tints — 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\`) — 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)\` — 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 — 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 — 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 — these names and steps, exactly):
+${vocabulary}`;
+}
+
+export const FREE_COLOR_RULE = renderFreeColorRule();
+
+export const 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 — 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 — 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>\` — 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 — see "Defensive coding".
+- **Display modes**: the host advertises \`availableDisplayModes\` (\`inline\` | \`fullscreen\` | \`pip\`); \`el.requestFullscreen()\` asks the host to switch — never assume it will.
+- **Size**: the host sets the iframe's \`containerDimensions\` once per render; there is no live resize notification — 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.`;
+
+export const FREE_BUDGETS = `## Budgets (deterministic caps)
+
+- Source ≤ 50 KB and ≤ 500 lines.
+- Compiled bundle ≤ 2 MB.
+- One file, one \`export default function Component(props: Props)\`.`;
+
+export const 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 — no \`/primitives\` / \`/components\` subpaths), \`@ggui-ai/wire\`, \`@ggui-ai/gadgets\`, or a gadget package the contract declares — 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" — tier-0 \`security\` fails them and the sandbox blocks them anyway.`;
+
+export const 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\`).`;
+
+export const FREE_ACCESSIBILITY = `## Accessibility (REQUIRED)
+
+With raw elements YOU own the semantics — 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>\` — 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 — never skipped or inverted.
+6. **Busy state is announced**: \`<button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting…' : 'Submit'}</button>\`.
+7. **Stateful controls announce state**: \`role="checkbox"\` + \`aria-checked\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check mark) is never the only carrier of state.
+8. **Focus is visible** — style \`:focus-visible\` with a token color; never \`outline: none\` without a replacement.`;
+
+export const 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 — every color is a bare \`var(--ggui-color-*)\` from the manifest; no hex / rgb() / hsl() / named colors, no fallbacks — 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 — 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\`) — never style-only
+- [ ] Live/streaming regions wrapped in \`aria-live="polite"\`
+- [ ] Headings nest — one \`<h1>\`, then \`<h2>\` / \`<h3>\` — never skipped or inverted
+- [ ] No \`fetch\` / \`eval\` / \`window\` / \`document\` / \`localStorage\` / external stylesheets or fonts
+- [ ] Source ≤ 50 KB / ≤ 500 lines; wire hooks (\`useAction\`, \`useStream\`, \`useGguiContext\`) kept and consumed`;
+
+/**
+ * Note appended to the axis `## Shape Guidance` section in free mode:
+ * the fragments name design-package components as defaults; here they
+ * are optional while the behavioural rules and crash anti-patterns
+ * stay mandatory.
+ */
+export const FREE_SHAPE_GUIDANCE_NOTE =
+  "In this mode the design-package components named above (`<Stepper>`, `<Modal>`, `<Card>`, `<Row>`, `<CardGrid>`) are defaults, not requirements — 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.";
+
+interface TokenGroup {
+  readonly label: string;
+  readonly prefixes: readonly string[];
+  readonly note: string;
+}
+
+const TOKEN_GROUPS: readonly TokenGroup[] = [
+  { label: "Color (mandatory for every color)", prefixes: ["--ggui-color-"], note: "" },
+  { label: "Spacing (optional — 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: "" },
+];
+
+/**
+ * The theme token vocabulary as REFERENCE DATA — derived from the closed
+ * consumed-token manifest (the same set `tokens:off-manifest-token`
+ * checks against), so the prompt can never teach a name the runtime
+ * does not define. Grouped by prefix; anything outside the known
+ * prefixes lands under "Other".
+ */
+export function renderTokenVocabulary(manifest: readonly string[] = consumedTokenManifest): string {
+  const sorted = [...manifest].sort();
+  const claimed = new Set<string>();
+  const lines: string[] = [
+    "### Reference (optional): theme token vocabulary",
+    "",
+    "The closed manifest — 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");
+}
+
+/** Assemble the `designMode: 'free'` system prompt. */
+export function buildFreeDesignPrompt(inputs: FreeDesignPromptInputs): string {
+  const axisSection =
+    inputs.axisSection.length > 0
+      ? `${inputs.axisSection}\n${FREE_SHAPE_GUIDANCE_NOTE}\n`
+      : "";
+
+  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 — 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 — add state, helpers, styles and JSX
+3. If compilation or evaluation fails, you'll get errors to fix in the next turn
+
+${inputs.criteriaBlock}
+${axisSection}
+`;
+
+  const sections = [
+    PROTOCOL_NOTES,
+    CONTRACT_SURFACE,
+    DEFENSIVE_CODING,
+    GESTURE_ROUTING,
+    FREE_GESTURE_SURFACE,
+    ANTI_PATTERNS,
+    CROSS_REFERENCE_RULES,
+    renderGadgetCatalogSection(inputs.gadgetsSection),
+    CONTEXT_SPEC_SECTION,
+    `## Reference: Wire Hooks\n${inputs.wireDoc}`,
+    FREE_DESIGN_FREEDOM,
+    FREE_COLOR_RULE,
+    FREE_HOST_ENVELOPE,
+    FREE_BUDGETS,
+    FREE_IMPORTS_AND_SECURITY,
+    DATA_PARAMETERIZATION,
+    COMPONENT_STRUCTURE,
+    FREE_RESPONSIVE_INVARIANT,
+    FREE_ACCESSIBILITY,
+    FREE_QUALITY_CHECKLIST,
+    renderTokenVocabulary(),
+    `### Reference (optional): \`@ggui-ai/design\` component catalog\n\nOptional — import a primitive only when it helps. Raw HTML + your own CSS is a first-class choice.\n\n${inputs.primitivesDoc}`,
+  ];
+
+  return head + sections.join("\n\n") + "\n";
+}

package/src/boilerplate/generate.ts

@@ -36,6 +36,7 @@ import type {
 import { HOOK_NAME_RE, listContractGadgets } from "@ggui-ai/protocol";
 import { renderBoilerplate } from "./render.js";
 import { jsonSchemaTypeToTs } from "./json-schema-ts.js";
+import { DEFAULT_DESIGN_MODE, type DesignMode } from "../design-mode.js";
 
 /** Shell layout modes supported by the boilerplate templates. */
 export type ShellType = "chat" | "fullscreen" | "spatial";
@@ -184,6 +185,14 @@ export function generateBoilerplate(
    * point rather than an empty `useFoo()` it might delete.
    */
   appGadgets?: readonly GadgetDescriptor[],
+  /**
+   * Which base template to render. `constrained` (default) pre-imports
+   * the design surface + a per-shell layout scaffold — byte-identical to
+   * the pre-`designMode` boilerplate. `free` drops both; the Props /
+   * Action / Stream types, wire hooks, contextSpec hooks and gadget
+   * imports are emitted EXACTLY as in constrained mode.
+   */
+  designMode: DesignMode = DEFAULT_DESIGN_MODE,
 ): string {
   // ── Props interface from data contract (data only — NO action callbacks) ──
   // Contract shape (PropsSpec is ALWAYS the wrapper — never flat):
@@ -557,5 +566,5 @@ export function generateBoilerplate(
     CONTEXT_HOOKS: contextHooks,
     WIRE_HOOKS: hookBody,
     AXIS_SECTIONS: composedSections ?? "",
-  });
+  }, designMode);
 }

package/src/boilerplate/hard-sections.ts

@@ -0,0 +1,242 @@
+// packages/ui-gen/src/boilerplate/hard-sections.ts
+//
+// The HARD-CONTRACT sections of the coding-agent system prompt — the
+// text that is identical in every `designMode`. Both prompt builders
+// (`buildSystemPrompt` for `constrained`, `buildFreeDesignPrompt` for
+// `free`) assemble from these constants, so the wire / contract / host /
+// gadget / blueprint-reuse teaching cannot drift between the two arms.
+//
+// These strings were extracted VERBATIM from the pre-`designMode`
+// `buildSystemPrompt` template; `design-mode.pin.test.ts` pins the
+// constrained assembly byte-for-byte against the pre-extraction digest.
+// Edit them here and both arms move together.
+
+/** Wire-hook preservation rules (`wire_preservation` / `wire_undeclared`). */
+export const 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 — 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 — your job is to honor what's declared.
+
+Renaming a binding is fine — the wiring is the string-literal argument, not the identifier.`;
+
+/** The four specs + two catalogs, the actions-vs-context placement rule and the data-vs-behavior split. */
+export const CONTRACT_SURFACE = `## Contract surface — 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 → UI (one-shot)     | Initial render values delivered once at \`ggui_render\`              |
+| \`streamSpec\`        | agent → UI (many)          | Typed channels for live updates via \`ggui_emit\`                    |
+| \`actionSpec\`        | UI → agent (events)        | Discrete events driving the agent's next turn (consumed via \`ggui_consume\`) |
+| \`contextSpec\`       | UI → 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 — all component code, never contract fields.`;
+
+/** Guarding absent / late-arriving props, streams and context slots. */
+export const 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 — 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 — 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 — 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 — 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 — 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 — \`useEffect(() => setCount(props.count ?? 0), [props.count])\` — 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 — 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="…" description="…" />\` — 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" — a regression class the runtime can't recover from.`;
+
+/** Which wire surface each user gesture maps to (actions, context, gadgets, links, fullscreen). */
+export const GESTURE_ROUTING = `## Picking the right primitive for user gestures
+
+Choose by what the user is DOING, not where the result goes — 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 — 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 → agent — 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 — 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.`;
+
+/** `as={Trait}` mechanics + the never-nest-two-interactive-elements rule in design-package vocabulary (constrained mode only — `free` mode restates the invariant for raw elements). */
+export const INTERACTIVE_TRAITS = `## Making a primitive interactive — \`as={Trait}\`
+
+Structural primitives (\`Box\`, \`Stack\`, \`Row\`, \`Card\`) have NO \`onClick\` by default. Add interactivity with the \`as\` prop — a trait, not a wrapper:
+
+\`\`\`tsx
+<Card as={Clickable} onClick={() => dispatch('select', { id })}
+      hoverStyle={{ boxShadow: 'var(--ggui-shape-shadow-lg)' }}>…</Card>
+\`\`\`
+
+- \`as={Clickable}\` → \`onClick\` + keyboard activation (Enter/Space) + \`role="button"\` + \`hoverStyle\`/\`activeStyle\`/\`cursor\`.
+- \`as={Hoverable}\` → \`hoverStyle\` only (no click). \`as={Pressable}\` → \`onPress\` + \`pressStyle\`.
+
+\`as={Trait}\` is a PROP — it does NOT re-nest the JSX. Never write \`<Clickable>…</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 — the boilerplate already imports them.
+
+**Semantic components are already interactive** — \`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 — a gesture on the inner control bubbles to the outer one and fires BOTH handlers (one user click → 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}\`) — 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\` — 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 …", do ONE of these — 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>}
+\`\`\``;
+
+/** Retired contract identifiers the linter rejects. */
+export const ANTI_PATTERNS = `## Anti-patterns — 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\` — retired hooks. Replace with \`useAction\` (events) and the named hook from \`@ggui-ai/gadgets\` (browser capabilities).
+- \`dispatch: { kind: 'tool', tool: '...' }\` / \`dispatch: { kind: 'agent', intendedTool: '...' }\` — retired discriminated-union. Use the flat optional \`nextStep?: '<tool>'\` instead.
+- \`mode: 'host-routed'\` / \`mode: 'tool'\` — retired \`mode\` field. Same fix: flat \`nextStep?\`.
+- \`broadcast: {...}\` on the contract — retired top-level field. Use \`streamSpec[channel].source: {tool, args?}\` to declare a tool-fed channel.
+- \`wiredTools\` / \`agentTools\` (top-level) — retired catalog names. Use \`agentCapabilities.tools\`.
+- \`clientTools\` / \`clientCapabilities.capabilities\` — retired catalog shapes. Use \`clientCapabilities.gadgets\` (entries declare hooks, not RPC).
+- \`@ggui-ai/client-tools\` — retired package name. Import gadget hooks from \`@ggui-ai/gadgets\`.
+- \`intendedTool\` — retired. Use \`nextStep\` (flat).
+- \`props: { properties: {...} }\` as a CONTRACT field — retired. The contract field is \`propsSpec\` (the wire \`props\` field on render / update still carries VALUES).`;
+
+/** `nextStep` / `source.tool` catalog cross-refs. */
+export const CROSS_REFERENCE_RULES = `## Cross-reference rules
+
+When you declare a reference, also declare the catalog entry it points at:
+
+- \`actionSpec[X].nextStep = 'fetch_inbox'\` → \`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'\` → \`agentCapabilities.tools.list_messages\` MUST exist. Cross-ref code: \`CTR_REF_STREAM_SOURCE\`.
+- The catalog entry's schemas MUST be a superset of the referencing spec's schema. Cross-ref code: \`CTR_SCHEMA_INCOMPAT\`.`;
+
+/** `clientCapabilities` — the registered gadget catalog table (rendered per app). */
+export function renderGadgetCatalogSection(gadgetsSection: string): string {
+  return `## clientCapabilities — registered catalog
+
+${gadgetsSection}
+
+Each hook conforms to \`GadgetHook<TOutput, TOptions>\`: call \`start(opts?)\` to fire, read \`{value, status, error, stop?}\`. \`status\` walks through \`idle → prompting → active|completed\` or routes to \`denied\` / \`error\` on failure.
+
+3rd-party plugins (Leaflet maps, Mapbox, Stripe, Chart.js, …) 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 — render validation rejects hooks not in this catalog with \`gadget_not_registered\`.`;
+}
+
+/** `contextSpec` — auto-generated `useGguiContext` slots, one-way client → agent. */
+export const 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 — **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 — do not remove or rename:
+  const [currentStep, setCurrentStep] = useGguiContext<number>('currentStep');
+  const [draftText, setDraftText] = useGguiContext<string>('draftText');
+
+  // Plain JSX. No Provider wrap. The runtime already wrapped your
+  // component in nested SingleSlotProviders before this code ran.
+  return (
+    <Container>
+      <Text>Step {currentStep}</Text>
+      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
+      <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
+    </Container>
+  );
+}
+\`\`\`
+
+For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
+- **Read** the value to render: \`<Text>Step {currentStep}</Text>\`
+- **Write** via the setter: \`setCurrentStep(s => s + 1)\` (in callbacks, effects, anywhere)
+
+Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms — adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state — drafts, current step, hover, selection — without you calling any API.
+
+**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
+
+**When NOT to use it.** Local UI state the contract did NOT declare — \`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 → 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\` — 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.`;
+
+/** Blueprint-reuse contract — request data as defaulted props, exported typed `Props`. Identical in both modes. */
+export const 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 — hardcoded, only works for Tokyo
+const city = "Tokyo";
+const temp = 18;
+
+// GOOD — 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 → props with defaults. City names, tickers, user names, dates, counts.
+2. Layout and styling are universal. Colors, spacing, structure — these are the reusable part.
+3. Default values come from the current request — so the component renders correctly standalone.
+4. Props interface must be typed and exported.`;
+
+/** Helper-component structure guidance (JSX depth 3–5, helpers above `Component`). Identical in both modes. */
+export const COMPONENT_STRUCTURE = `## Component Structure
+
+Keep JSX nesting depth to 3–5 levels. When deeper, extract repeated/complex sections into helper components — 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">…</Card>;
+}
+
+export default function GeneratedComponent({ onSubmit }: Props) {
+  return (
+    <Container>
+      {items.map((item) => <ItemCard key={item.id} item={item} onEdit={handleEdit} />)}
+    </Container>
+  );
+}
+\`\`\``;