@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/dist/chunk-VTC263LT.js

@@ -0,0 +1,256 @@
+import { propsSpecToTypeScript } from './chunk-FWJIMKFZ.js';
+import { STYLING_PROFILE_PRECEDENCE_NOTE } from './chunk-NF6JUZWF.js';
+import { canvasDisplayModeForShell, canvasForViewportWidth } from './chunk-3T2HMTON.js';
+import { listContractGadgets, HOOK_NAME_RE } from '@ggui-ai/protocol';
+
+var SHELL_HINTS = {
+  chat: `**Chat Shell \u2014 Inline card in scrolling conversation**
+- Container: width varies (60-80% of viewport), height: auto (natural content height)
+- Chrome: parent provides card border + shadow + rounded corners \u2014 do NOT add your own box-shadow or outer border-radius
+- Sizing: target 300-600px natural height. Do NOT use min-height: 100vh. No full-viewport designs.
+- Padding: use var(--ggui-spacing-2) for inner elements, var(--ggui-spacing-4) for sections. Tight.
+- Scrolling: parent scrolls (chat feed) \u2014 component should NOT have internal scroll
+- Layout: single column, compact. No sidebar. Stack everything vertically.
+- Width: the root is width: 100% (fills the bubble) \u2014 never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width; the chips or buttons that answer the prose sit in a Container of the same maxWidth, so they share its left edge.`,
+  fullscreen: `**Fullscreen Shell \u2014 Takes over entire viewport**
+- Container: the whole viewport, edge to edge \u2014 the frame stretches your root to its full height (you never set a viewport height yourself)
+- Chrome: NONE \u2014 your component IS the entire UI. You own all visual chrome.
+- Sizing: size to content; to fill a parent that has a height use height: 100% or flex: 1. NEVER min-height: 100vh / 100dvh \u2014 the frame already stretches the root, and a viewport height only fights it (tier-0 fail).
+- Padding: component owns ALL padding. Use var(--ggui-spacing-6) or larger for breathing room.
+- Scrolling: component manages its own scroll if content exceeds viewport (overflow-y: auto)
+- Layout: can use multi-column, sidebars, headers/footers. Full creative control.
+- Navigation: swipe left/right between pages is handled by the shell \u2014 don't implement it.
+- DO NOT add outer margins or max-width containers. Fill the space.`,
+  partial: `**Partial Shell \u2014 Embedded panel in a larger page**
+- Container: width constrained by parent (could be 400px sidebar or 800px main area)
+- Chrome: parent may or may not have border \u2014 add your own Card/shadow if needed
+- Sizing: width: 100% to fill parent. Use max-width if you want to center content.
+- Padding: use standard spacing (var(--ggui-spacing-4) to var(--ggui-spacing-6))
+- Scrolling: can scroll internally (overflow-y: auto) \u2014 parent does NOT scroll for you
+- Layout: responsive within the container. Flex-wrap for variable parent widths.
+- Context: other UI around you (nav, sidebar) \u2014 don't duplicate page-level chrome.`
+};
+var DEVICE_HINTS = {
+  mobile: `**Mobile:** Single column. Touch targets 44px+. Compact padding. Stack all sections vertically.`,
+  tablet: `**Tablet:** 1-2 columns adaptive. Medium touch targets. Side-by-side where space allows.`,
+  desktop: `**Desktop:** Multi-column. Hover states. Dense layouts. Keyboard shortcuts. Pointer interactions.`,
+  spatial: `**Spatial:** Fixed-size floating panel (~600x400). High contrast. Large text. No hover (gaze/hand input).`
+};
+function canvasForRenderingContext(ctx) {
+  const mode = canvasDisplayModeForShell(ctx.shell);
+  if (mode === "inline") return "xs-chat-card";
+  if (ctx.viewport) return canvasForViewportWidth(mode, ctx.viewport.width);
+  switch (ctx.device) {
+    case "mobile":
+      return "mobile-fullscreen-small";
+    case "tablet":
+    case "spatial":
+      return "md";
+    case "desktop":
+      return ctx.shell === "partial" ? "md" : "lg";
+  }
+}
+function buildRenderingContext(ctx) {
+  const parts = [
+    "## Rendering Context",
+    `- Device: ${ctx.device}`,
+    ctx.viewport ? `- Viewport: ${ctx.viewport.width}\xD7${ctx.viewport.height}px` : "",
+    `- Shell: ${ctx.shell}`,
+    "",
+    DEVICE_HINTS[ctx.device] || "",
+    SHELL_HINTS[ctx.shell] || ""
+  ].filter(Boolean);
+  return parts.join("\n");
+}
+function injectRenderingContext(userPrompt, rendering) {
+  if (!rendering) return userPrompt;
+  return userPrompt + "\n\n" + buildRenderingContext(rendering);
+}
+function buildContractsContext(contract, appGadgets) {
+  const parts = [];
+  if (contract.propsSpec) {
+    const propsSpec = contract.propsSpec;
+    const requiredFields = Object.entries(propsSpec.properties || {}).filter(([, e]) => e.required).map(([k]) => k);
+    const optionalFields = Object.entries(propsSpec.properties || {}).filter(([, e]) => !e.required).map(([k]) => k);
+    const tsInterface = propsSpecToTypeScript(propsSpec);
+    const fieldInfo = [];
+    if (requiredFields.length > 0) fieldInfo.push(`Required: ${requiredFields.join(", ")}`);
+    if (optionalFields.length > 0) fieldInfo.push(`Optional: ${optionalFields.join(", ")}`);
+    parts.push(
+      `## Props Contract (MUST use these exact prop names and types)
+
+` + (fieldInfo.length > 0 ? fieldInfo.join("\n") + "\n\n" : "") + `\`\`\`typescript
+interface Props ${tsInterface}
+\`\`\``
+    );
+  }
+  if (contract.actionSpec && Object.keys(contract.actionSpec).length > 0) {
+    const actions = Object.entries(contract.actionSpec).map(([id, entry]) => {
+      let line = `  - ${id}: "${entry.label ?? id}"${entry.description ? ` \u2014 ${entry.description}` : ""}`;
+      if (entry.example !== void 0) {
+        line += `
+    Example payload: \`${JSON.stringify(entry.example)}\``;
+      }
+      if (entry.nextStep) {
+        line += `
+    Next-step hint: agent intends to call \`${entry.nextStep}\``;
+      }
+      if (entry.confirm === true) {
+        line += `
+    Author flag: \`confirm\` \u2014 the author marked this action as one to confirm with the user before it fires.`;
+      }
+      return line;
+    }).join("\n");
+    parts.push(`## Action Contract (wire these callbacks)
+${actions}`);
+  }
+  if (contract.streamSpec && Object.keys(contract.streamSpec).length > 0) {
+    const channels = Object.entries(contract.streamSpec).map(([name, entry]) => {
+      const bits = [`  - ${name}`];
+      if (entry.description) bits.push(`\u2014 ${entry.description}`);
+      if (entry.source?.tool) {
+        bits.push(`(source tool: \`${entry.source.tool}\`)`);
+      }
+      return bits.join(" ");
+    }).join("\n");
+    parts.push(
+      `## Stream Contract (real-time channels via \`useStream(name)\`)
+${channels}
+
+Payload schemas:
+\`\`\`json
+${JSON.stringify(contract.streamSpec, null, 2)}
+\`\`\``
+    );
+  }
+  const agentTools = contract.agentCapabilities?.tools;
+  if (agentTools && Object.keys(agentTools).length > 0) {
+    const tools = Object.entries(agentTools).map(([name, entry]) => {
+      const bits = [`  - **\`${name}\`**`];
+      if (entry.toolInfo?.description) bits.push(`\u2014 ${entry.toolInfo.description}`);
+      if (entry.usage) bits.push(`(usage: ${entry.usage})`);
+      return bits.join(" ");
+    }).join("\n");
+    parts.push(
+      `## AgentTools Catalog (tools the contract references)
+${tools}
+
+These are referenced via \`actionSpec[*].nextStep\` (the tool the agent SHOULD call next after the action fires) and \`streamSpec[*].source.tool\` (the tool feeding a channel). The agent OWNS the call \u2014 your component does not invoke these directly.
+
+Schemas:
+\`\`\`json
+${JSON.stringify(agentTools, null, 2)}
+\`\`\``
+    );
+  }
+  const clientCapabilities = contract.clientCapabilities?.gadgets;
+  const gadgetUses = listContractGadgets(contract);
+  if (gadgetUses.length > 0) {
+    const caps = gadgetUses.map((use) => {
+      const bits = [`  - **\`${use.name}\`**`];
+      bits.push(
+        HOOK_NAME_RE.test(use.name) ? `via direct-imported hook \`${use.name}\` from \`${use.package}\` (call it)` : `via direct-imported component \`<${use.name} />\` from \`${use.package}\` (render as JSX)`
+      );
+      if (use.description) bits.push(`\u2014 ${use.description}`);
+      return bits.join(" ");
+    }).join("\n");
+    parts.push(
+      `## ClientCapabilities Contract (browser-capability gadgets the UI mounts)
+${caps}
+
+Hook entries are imported + called; component entries are imported + rendered as JSX. Capability values reach the agent only when the UI threads them into an actionSpec payload or contextSpec slot.
+
+Declarations:
+\`\`\`json
+${JSON.stringify(clientCapabilities, null, 2)}
+\`\`\``
+    );
+  }
+  const uiRequirements = [];
+  if (contract.propsSpec?.properties) {
+    for (const [name, entry] of Object.entries(contract.propsSpec.properties)) {
+      const required = entry.required === true;
+      if (required) {
+        uiRequirements.push(
+          `- **Required prop \`${name}\`** must appear somewhere in rendered DOM (display the value, or use it to drive a label/aria/key).`
+        );
+      } else {
+        uiRequirements.push(
+          `- **Optional prop \`${name}\`** may be ABSENT at runtime \u2014 the component must render without it (guard the access or apply its default) and must display it when it IS provided.`
+        );
+      }
+    }
+  }
+  if (contract.actionSpec) {
+    for (const [name, entry] of Object.entries(contract.actionSpec)) {
+      const label = entry.label ?? name;
+      uiRequirements.push(
+        `- **Action \`${name}\`** ("${label}") needs an interactive control that fires it (Button click, form submit, key press, etc.).`
+      );
+    }
+  }
+  if (contract.streamSpec) {
+    for (const name of Object.keys(contract.streamSpec)) {
+      uiRequirements.push(
+        `- **Stream \`${name}\`** must mirror into local state via \`useEffect\` and render the resulting state \u2014 \`useStream\` alone never re-renders the DOM.`
+      );
+    }
+  }
+  for (const use of gadgetUses) {
+    const exportName = use.name;
+    const pkg = use.package;
+    uiRequirements.push(
+      HOOK_NAME_RE.test(exportName) ? `- **ClientCapability \`${exportName}\`** \u2014 the boilerplate has direct-imported \`${exportName}\` from \`${pkg}\` above a \`// DO NOT EDIT\` banner; keep that import, call \`${exportName}\` inside the component, and thread the resulting value into a context slot or action payload if the agent needs to observe it.` : `- **ClientCapability \`${exportName}\`** \u2014 the boilerplate has direct-imported \`${exportName}\` from \`${pkg}\` above a \`// DO NOT EDIT\` banner; keep that import and RENDER \`<${exportName} \u2026 />\` as a JSX element in the tree you return.`
+    );
+  }
+  if (uiRequirements.length > 0) {
+    parts.push(
+      `## Required UI Surfaces (derived from contract \u2014 every surface below MUST have visible UI, eval will fail if any is missing)
+` + uiRequirements.join("\n")
+    );
+  }
+  return parts.join("\n\n");
+}
+function injectContracts(userPrompt, contract, appGadgets) {
+  if (!contract) return userPrompt;
+  const ctx = buildContractsContext(contract);
+  if (!ctx) return userPrompt;
+  return userPrompt + "\n\n" + ctx;
+}
+function buildVarianceContext(variance, options) {
+  const lines = [];
+  if (typeof variance.persona === "string" && variance.persona.length > 0) {
+    lines.push(`- **Persona**: ${variance.persona}`);
+  }
+  if (typeof variance.aesthetic === "string" && variance.aesthetic.length > 0) {
+    lines.push(`- **Aesthetic**: ${variance.aesthetic}`);
+  }
+  if (typeof variance.seedPrompt === "string" && variance.seedPrompt.length > 0) {
+    lines.push(`- **Seed prompt**: ${variance.seedPrompt}`);
+  }
+  if (variance.context !== void 0 && variance.context !== null && typeof variance.context === "object" && !Array.isArray(variance.context) && Object.keys(variance.context).length > 0) {
+    lines.push(`- **Context**: ${JSON.stringify(variance.context)}`);
+  }
+  if (lines.length === 0) return "";
+  return [
+    "## Variance (apply to styling, not contract shape)",
+    "",
+    "The agent (or operator) declared these variant signals. Honor them in",
+    "the visual treatment + copy register \u2014 but the contract shape (props,",
+    "actions, contexts, streams) remains canonical. Variance changes HOW",
+    "the UI looks and reads, not WHAT it does.",
+    ...options?.profileDeclared === true ? [STYLING_PROFILE_PRECEDENCE_NOTE] : [],
+    "",
+    ...lines
+  ].join("\n");
+}
+function injectVariance(userPrompt, variance, options) {
+  if (!variance) return userPrompt;
+  const block = buildVarianceContext(variance, options);
+  if (!block) return userPrompt;
+  return userPrompt + "\n\n" + block;
+}
+
+export { buildContractsContext, buildRenderingContext, buildVarianceContext, canvasForRenderingContext, injectContracts, injectRenderingContext, injectVariance };
+//# sourceMappingURL=chunk-VTC263LT.js.map
+//# sourceMappingURL=chunk-VTC263LT.js.map

package/dist/chunk-VTC263LT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contract-context.ts"],"names":[],"mappings":"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","file":"chunk-VTC263LT.js","sourcesContent":["/**\n * Contract + rendering-context prompt rendering.\n *\n * Surfaces every contract dimension explicitly to the LLM. A compact\n * bullet list of action / stream names is not enough — without the\n * Props shape, generation fails tier-0 on most cells with \"Props\n * interface missing required field '<name>'\".\n *\n * Renders:\n *\n *   - Props contract — required + optional field lists + a real\n *     TypeScript interface (compiled via `propsSpecToTypeScript`)\n *   - Action contract — id / label / example / nextStep hint\n *   - Stream contract — channel descriptions + payload schemas + source\n *   - AgentTools — catalog of tools the contract references (via\n *     `actionSpec[*].nextStep` and `streamSpec[*].source.tool`)\n *   - ClientCapabilities — browser-capability gadgets the UI mounts:\n *     hooks it calls (e.g. `useGeolocation` from `@ggui-ai/gadgets`)\n *     and components it renders (e.g. `<LeafletMap />`)\n *   - Required UI Surfaces — derived list of \"every contract surface\n *     must have visible UI\" so the LLM doesn't drop required props or\n *     skip rendering data sources\n *\n * Rendering context (device + shell + viewport) is layered alongside —\n * shells (`chat` / `fullscreen` / `partial`) require very different\n * sizing strategies and including the hint inline cuts a class of\n * \"designed for fullscreen, rendered in a chat bubble\" bugs.\n */\nimport { STYLING_PROFILE_PRECEDENCE_NOTE } from './boilerplate/styling-profile.js';\nimport type { RenderingContext as ProtocolRenderingContext } from '@ggui-ai/protocol';\nimport type {\n  ActionEntry,\n  BlueprintVariance,\n  GadgetDescriptor,\n  DataContract,\n  StreamChannelEntry,\n} from '@ggui-ai/protocol';\nimport { HOOK_NAME_RE, listContractGadgets } from '@ggui-ai/protocol';\nimport { propsSpecToTypeScript } from './check/index.js';\nimport {\n  canvasDisplayModeForShell,\n  canvasForViewportWidth,\n  type CanvasClass,\n} from './design-mode.js';\n\n/**\n * Rendering context — how and where the component will be displayed.\n * Affects layout strategy, sizing, and interaction patterns. The ONE\n * vocabulary is `@ggui-ai/protocol`'s `renderingContextSchema` (ggui#1000);\n * this is its type, derived — never re-declared here.\n */\nexport type RenderingContext = ProtocolRenderingContext;\n\nconst SHELL_HINTS: Record<string, string> = {\n  chat: `**Chat Shell — Inline card in scrolling conversation**\n- Container: width varies (60-80% of viewport), height: auto (natural content height)\n- Chrome: parent provides card border + shadow + rounded corners — do NOT add your own box-shadow or outer border-radius\n- Sizing: target 300-600px natural height. Do NOT use min-height: 100vh. No full-viewport designs.\n- Padding: use var(--ggui-spacing-2) for inner elements, var(--ggui-spacing-4) for sections. Tight.\n- Scrolling: parent scrolls (chat feed) — component should NOT have internal scroll\n- Layout: single column, compact. No sidebar. Stack everything vertically.\n- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth=\"sm\">), which is inert at bubble width; the chips or buttons that answer the prose sit in a Container of the same maxWidth, so they share its left edge.`,\n\n  fullscreen: `**Fullscreen Shell — Takes over entire viewport**\n- Container: the whole viewport, edge to edge — the frame stretches your root to its full height (you never set a viewport height yourself)\n- Chrome: NONE — your component IS the entire UI. You own all visual chrome.\n- Sizing: size to content; to fill a parent that has a height use height: 100% or flex: 1. NEVER min-height: 100vh / 100dvh — the frame already stretches the root, and a viewport height only fights it (tier-0 fail).\n- Padding: component owns ALL padding. Use var(--ggui-spacing-6) or larger for breathing room.\n- Scrolling: component manages its own scroll if content exceeds viewport (overflow-y: auto)\n- Layout: can use multi-column, sidebars, headers/footers. Full creative control.\n- Navigation: swipe left/right between pages is handled by the shell — don't implement it.\n- DO NOT add outer margins or max-width containers. Fill the space.`,\n\n  partial: `**Partial Shell — Embedded panel in a larger page**\n- Container: width constrained by parent (could be 400px sidebar or 800px main area)\n- Chrome: parent may or may not have border — add your own Card/shadow if needed\n- Sizing: width: 100% to fill parent. Use max-width if you want to center content.\n- Padding: use standard spacing (var(--ggui-spacing-4) to var(--ggui-spacing-6))\n- Scrolling: can scroll internally (overflow-y: auto) — parent does NOT scroll for you\n- Layout: responsive within the container. Flex-wrap for variable parent widths.\n- Context: other UI around you (nav, sidebar) — don't duplicate page-level chrome.`,\n};\n\nconst DEVICE_HINTS: Record<string, string> = {\n  mobile: `**Mobile:** Single column. Touch targets 44px+. Compact padding. Stack all sections vertically.`,\n  tablet: `**Tablet:** 1-2 columns adaptive. Medium touch targets. Side-by-side where space allows.`,\n  desktop: `**Desktop:** Multi-column. Hover states. Dense layouts. Keyboard shortcuts. Pointer interactions.`,\n  spatial: `**Spatial:** Fixed-size floating panel (~600x400). High contrast. Large text. No hover (gaze/hand input).`,\n};\n\n/**\n * Map a host rendering context onto the canvas class the `free` prompt\n * states and the visual evaluator judges at. The class is derived from\n * DISPLAY MODE + width: a `chat` shell is always the inline card\n * whatever the host viewport is (the bubble, not the window, bounds the\n * component); a known viewport width refines the fullscreen / partial\n * shells; otherwise the device category decides.\n */\nexport function canvasForRenderingContext(ctx: RenderingContext): CanvasClass {\n  const mode = canvasDisplayModeForShell(ctx.shell);\n  if (mode === 'inline') return 'xs-chat-card';\n  if (ctx.viewport) return canvasForViewportWidth(mode, ctx.viewport.width);\n  switch (ctx.device) {\n    case 'mobile':\n      return 'mobile-fullscreen-small';\n    case 'tablet':\n    case 'spatial':\n      return 'md';\n    case 'desktop':\n      return ctx.shell === 'partial' ? 'md' : 'lg';\n  }\n}\n\n/** Build rendering-context block to inject into user prompt. */\nexport function buildRenderingContext(ctx: RenderingContext): string {\n  const parts = [\n    '## Rendering Context',\n    `- Device: ${ctx.device}`,\n    ctx.viewport ? `- Viewport: ${ctx.viewport.width}×${ctx.viewport.height}px` : '',\n    `- Shell: ${ctx.shell}`,\n    '',\n    DEVICE_HINTS[ctx.device] || '',\n    SHELL_HINTS[ctx.shell] || '',\n  ].filter(Boolean);\n  return parts.join('\\n');\n}\n\n/** Append rendering context to user prompt if present. */\nexport function injectRenderingContext(\n  userPrompt: string,\n  rendering?: RenderingContext,\n): string {\n  if (!rendering) return userPrompt;\n  return userPrompt + '\\n\\n' + buildRenderingContext(rendering);\n}\n\n/**\n * Build the contract-context block. Surfaces every dimension of the\n * contract so the LLM has a complete spec rather than the user-prompt\n * narrative alone — the eval scores against the contract regardless of\n * what prose the prompt carries, so contract-first rendering closes\n * the prompt-vs-contract drift class.\n */\nexport function buildContractsContext(\n  contract: DataContract,\n  /**\n   * Operator-registered gadget catalog. When a\n   * `clientCapabilities.gadgets[*]` ref is THIN (just `{hook}` —\n   * no per-binding `package`), look the hook up here to surface the\n   * correct package in user-prompt lines like `via useLeafletMap from\n   * @ggui-samples/gadget-leaflet`. Mirrors the same plumb in\n   * `harness/prompts.ts:buildContractsContext` — both surfaces are\n   * separate copies used by different call sites (this one is for\n   * `createUiGenerator`, the other for the benchmark / dispatch path).\n   */\n  appGadgets?: readonly GadgetDescriptor[],\n): string {\n  const parts: string[] = [];\n\n  // The LLM direct-imports each hook from its own package\n  // (resolved from the per-entry `package` field). The parameter stays\n  // on the signature so the TypeScript sandbox augmentation layer can\n  // still consume it.\n  void appGadgets;\n\n  // `intent` is not a contract field; `userPrompt` already carries\n  // the agent's narrative as the prompt body, so the contract-context\n  // block focuses on the structural shape (props / actions / streams /\n  // contexts). There is no categorical `interaction` mode label: the\n  // four-spec surface (props / actions / streams / contexts) describes\n  // the wire exhaustively — actions drive turns, contexts observe\n  // state, and there is no third category.\n\n  if (contract.propsSpec) {\n    const propsSpec = contract.propsSpec;\n    const requiredFields = Object.entries(propsSpec.properties || {})\n      .filter(([, e]) => (e as { required?: boolean }).required)\n      .map(([k]) => k);\n    const optionalFields = Object.entries(propsSpec.properties || {})\n      .filter(([, e]) => !(e as { required?: boolean }).required)\n      .map(([k]) => k);\n\n    const tsInterface = propsSpecToTypeScript(propsSpec);\n    const fieldInfo: string[] = [];\n    if (requiredFields.length > 0) fieldInfo.push(`Required: ${requiredFields.join(', ')}`);\n    if (optionalFields.length > 0) fieldInfo.push(`Optional: ${optionalFields.join(', ')}`);\n\n    parts.push(\n      `## Props Contract (MUST use these exact prop names and types)\\n\\n` +\n        (fieldInfo.length > 0 ? fieldInfo.join('\\n') + '\\n\\n' : '') +\n        `\\`\\`\\`typescript\\ninterface Props ${tsInterface}\\n\\`\\`\\``,\n    );\n  }\n\n  if (contract.actionSpec && Object.keys(contract.actionSpec).length > 0) {\n    const actions = Object.entries(contract.actionSpec)\n      .map(([id, entry]: [string, ActionEntry]) => {\n        let line = `  - ${id}: \"${entry.label ?? id}\"${entry.description ? ` — ${entry.description}` : ''}`;\n        if (entry.example !== undefined) {\n          line += `\\n    Example payload: \\`${JSON.stringify(entry.example)}\\``;\n        }\n        if (entry.nextStep) {\n          line += `\\n    Next-step hint: agent intends to call \\`${entry.nextStep}\\``;\n        }\n        // ggui#1108: `confirm` was the one declared action field the contract\n        // renderer dropped — every other author field (label, description,\n        // example, nextStep) reaches the model and this one did not. It is\n        // rendered as INFORMATION, not as a rule: the terminal-actions section\n        // deliberately does NOT cite it, because citing it measured ZERO —\n        // two wordings, n=4 each, `save` + `confirm: true` came back armed 0/4\n        // and 0/4. The field's own doc says \"whether to show confirmation\n        // BEFORE triggering\", which is gravity, not one-shot-ness, and the\n        // model reads it that way. Emitted only when true, so an absent flag\n        // leaves the prompt bytes identical to before this line existed.\n        if (entry.confirm === true) {\n          line += `\\n    Author flag: \\`confirm\\` — the author marked this action as one to confirm with the user before it fires.`;\n        }\n        return line;\n      })\n      .join('\\n');\n    parts.push(`## Action Contract (wire these callbacks)\\n${actions}`);\n  }\n\n  if (contract.streamSpec && Object.keys(contract.streamSpec).length > 0) {\n    const channels = Object.entries(contract.streamSpec)\n      .map(([name, entry]: [string, StreamChannelEntry]) => {\n        const bits = [`  - ${name}`];\n        if (entry.description) bits.push(`— ${entry.description}`);\n        if (entry.source?.tool) {\n          bits.push(`(source tool: \\`${entry.source.tool}\\`)`);\n        }\n        return bits.join(' ');\n      })\n      .join('\\n');\n    parts.push(\n      `## Stream Contract (real-time channels via \\`useStream(name)\\`)\\n${channels}\\n\\n` +\n        `Payload schemas:\\n\\`\\`\\`json\\n${JSON.stringify(contract.streamSpec, null, 2)}\\n\\`\\`\\``,\n    );\n  }\n\n  const agentTools = contract.agentCapabilities?.tools;\n  if (agentTools && Object.keys(agentTools).length > 0) {\n    const tools = Object.entries(agentTools)\n      .map(([name, entry]) => {\n        const bits = [`  - **\\`${name}\\`**`];\n        if (entry.toolInfo?.description) bits.push(`— ${entry.toolInfo.description}`);\n        if (entry.usage) bits.push(`(usage: ${entry.usage})`);\n        return bits.join(' ');\n      })\n      .join('\\n');\n    parts.push(\n      `## AgentTools Catalog (tools the contract references)\\n${tools}\\n\\n` +\n        `These are referenced via \\`actionSpec[*].nextStep\\` (the tool the agent SHOULD call next ` +\n        `after the action fires) and \\`streamSpec[*].source.tool\\` (the tool feeding a channel). ` +\n        `The agent OWNS the call — your component does not invoke these directly.\\n\\n` +\n        `Schemas:\\n\\`\\`\\`json\\n${JSON.stringify(agentTools, null, 2)}\\n\\`\\`\\``,\n    );\n  }\n\n  const clientCapabilities = contract.clientCapabilities?.gadgets;\n  const gadgetUses = listContractGadgets(contract);\n  if (gadgetUses.length > 0) {\n    // The wire `clientCapabilities.gadgets` is a package-keyed\n    // two-level map; `listContractGadgets` flattens it to `GadgetUse[]`.\n    // Kind is discriminated by the export-name grammar — `use`-prefixed\n    // names are hooks (imported + CALLED), PascalCase names are\n    // components (imported + RENDERED as JSX). Both are direct-imported.\n    const caps = gadgetUses\n      .map((use) => {\n        const bits = [`  - **\\`${use.name}\\`**`];\n        bits.push(\n          HOOK_NAME_RE.test(use.name)\n            ? `via direct-imported hook \\`${use.name}\\` from \\`${use.package}\\` (call it)`\n            : `via direct-imported component \\`<${use.name} />\\` from \\`${use.package}\\` (render as JSX)`,\n        );\n        if (use.description) bits.push(`— ${use.description}`);\n        return bits.join(' ');\n      })\n      .join('\\n');\n    parts.push(\n      `## ClientCapabilities Contract (browser-capability gadgets the UI mounts)\\n${caps}\\n\\n` +\n        `Hook entries are imported + called; component entries are imported + rendered as JSX. ` +\n        `Capability values reach the agent only when the UI threads them into an actionSpec ` +\n        `payload or contextSpec slot.\\n\\n` +\n        `Declarations:\\n\\`\\`\\`json\\n${JSON.stringify(clientCapabilities, null, 2)}\\n\\`\\`\\``,\n    );\n  }\n\n  // Required-UI derivation — the architectural fix at the heart of v15.\n  // Every contract surface implies a visible UI element; eval scores\n  // against the contract regardless of what the user-prompt narrative\n  // says. Emitting the implied UI surfaces explicitly makes the contract\n  // the single source of truth for \"what must render\".\n  const uiRequirements: string[] = [];\n  if (contract.propsSpec?.properties) {\n    for (const [name, entry] of Object.entries(contract.propsSpec.properties)) {\n      // Opt-in required (`=== true`) — the wire gate's reading, ggui#528.\n      // An omitted-`required` prop is OPTIONAL: the agent may leave it\n      // out of a legitimate render, so the derived instruction must\n      // demand a presence-safe component, not unconditional display.\n      const required = (entry as { required?: boolean }).required === true;\n      if (required) {\n        uiRequirements.push(\n          `- **Required prop \\`${name}\\`** must appear somewhere in rendered DOM (display the value, or use it to drive a label/aria/key).`,\n        );\n      } else {\n        uiRequirements.push(\n          `- **Optional prop \\`${name}\\`** may be ABSENT at runtime — the component must render without it (guard the access or apply its default) and must display it when it IS provided.`,\n        );\n      }\n    }\n  }\n  if (contract.actionSpec) {\n    for (const [name, entry] of Object.entries(contract.actionSpec)) {\n      const label = (entry as ActionEntry).label ?? name;\n      uiRequirements.push(\n        `- **Action \\`${name}\\`** (\"${label}\") needs an interactive control that fires it (Button click, form submit, key press, etc.).`,\n      );\n    }\n  }\n  if (contract.streamSpec) {\n    for (const name of Object.keys(contract.streamSpec)) {\n      uiRequirements.push(\n        `- **Stream \\`${name}\\`** must mirror into local state via \\`useEffect\\` and render the resulting state — \\`useStream\\` alone never re-renders the DOM.`,\n      );\n    }\n  }\n  // agentTools entries don't imply UI on their own — they're catalog\n  // declarations the agent uses, not hooks the component invokes.\n  // The implied UI lives on the referencing actionSpec entries\n  // (already enumerated above) and streamSpec channels with `source`\n  // declarations. No per-tool UI requirement is emitted here.\n  for (const use of gadgetUses) {\n    // Hook AND component exports are direct-imported; the\n    // implied UI differs — a hook is called + its value threaded,\n    // a component is rendered as a JSX element. Kind is discriminated\n    // by the export-name grammar.\n    const exportName = use.name;\n    const pkg = use.package;\n    uiRequirements.push(\n      HOOK_NAME_RE.test(exportName)\n        ? `- **ClientCapability \\`${exportName}\\`** — the boilerplate has direct-imported \\`${exportName}\\` from \\`${pkg}\\` above a \\`// DO NOT EDIT\\` banner; keep that import, call \\`${exportName}\\` inside the component, and thread the resulting value into a context slot or action payload if the agent needs to observe it.`\n        : `- **ClientCapability \\`${exportName}\\`** — the boilerplate has direct-imported \\`${exportName}\\` from \\`${pkg}\\` above a \\`// DO NOT EDIT\\` banner; keep that import and RENDER \\`<${exportName} … />\\` as a JSX element in the tree you return.`,\n    );\n  }\n  if (uiRequirements.length > 0) {\n    parts.push(\n      `## Required UI Surfaces (derived from contract — every surface below MUST have visible UI, eval will fail if any is missing)\\n` +\n        uiRequirements.join('\\n'),\n    );\n  }\n\n  return parts.join('\\n\\n');\n}\n\n/**\n * Append the contract-context block to a user prompt if a contract is present.\n *\n * `appGadgets` forwards into `buildContractsContext` so thin contract\n * refs (`{hook}` without per-binding `package`) resolve to the\n * registered descriptor's package in the prompt-emitted \"import X from\n * Y\" lines.\n */\nexport function injectContracts(\n  userPrompt: string,\n  contract?: DataContract,\n  appGadgets?: readonly GadgetDescriptor[],\n): string {\n  if (!contract) return userPrompt;\n  const ctx = buildContractsContext(contract, appGadgets);\n  if (!ctx) return userPrompt;\n  return userPrompt + '\\n\\n' + ctx;\n}\n\n/**\n * Build the variance-context block. Surfaces the agent's declared\n * styling signals (persona, aesthetic, context, seedPrompt) so cold-gen\n * aligns the produced component with the requested variant. Each field\n * is optional; the block only renders when at least one is present.\n *\n * - `persona` names the USER mental model (e.g. \"data-analyst\",\n *   \"mobile-first reader\") — drives copy register + density choices.\n * - `aesthetic` names the VISUAL treatment (e.g. \"glassmorphic\",\n *   \"editorial\", \"brutalist\") — drives surface decoration, typographic\n *   weight, color usage.\n * - `context` is structured key-value signal alongside the persona —\n *   small JSON-safe shape, serialized verbatim into the prompt.\n * - `seedPrompt` is the operator's original natural-language steer that\n *   produced this variant in cache storage — useful as a one-line\n *   directive for cold-gen.\n *\n * Returns an empty string when no fields are populated so the inject\n * helper can no-op cleanly.\n */\nexport function buildVarianceContext(\n  variance: BlueprintVariance,\n  options?: { readonly profileDeclared?: boolean },\n): string {\n  const lines: string[] = [];\n  if (typeof variance.persona === 'string' && variance.persona.length > 0) {\n    lines.push(`- **Persona**: ${variance.persona}`);\n  }\n  if (typeof variance.aesthetic === 'string' && variance.aesthetic.length > 0) {\n    lines.push(`- **Aesthetic**: ${variance.aesthetic}`);\n  }\n  if (typeof variance.seedPrompt === 'string' && variance.seedPrompt.length > 0) {\n    lines.push(`- **Seed prompt**: ${variance.seedPrompt}`);\n  }\n  if (\n    variance.context !== undefined &&\n    variance.context !== null &&\n    typeof variance.context === 'object' &&\n    !Array.isArray(variance.context) &&\n    Object.keys(variance.context).length > 0\n  ) {\n    lines.push(`- **Context**: ${JSON.stringify(variance.context)}`);\n  }\n  if (lines.length === 0) return '';\n  return [\n    '## Variance (apply to styling, not contract shape)',\n    '',\n    'The agent (or operator) declared these variant signals. Honor them in',\n    'the visual treatment + copy register — but the contract shape (props,',\n    'actions, contexts, streams) remains canonical. Variance changes HOW',\n    'the UI looks and reads, not WHAT it does.',\n    ...(options?.profileDeclared === true ? [STYLING_PROFILE_PRECEDENCE_NOTE] : []),\n    '',\n    ...lines,\n  ].join('\\n');\n}\n\n/** Append the variance-context block to a user prompt if variance is present. */\nexport function injectVariance(\n  userPrompt: string,\n  variance?: BlueprintVariance,\n  options?: { readonly profileDeclared?: boolean },\n): string {\n  if (!variance) return userPrompt;\n  const block = buildVarianceContext(variance, options);\n  if (!block) return userPrompt;\n  return userPrompt + '\\n\\n' + block;\n}\n"]}