@ggui-ai/ui-gen 0.17.0 → 0.19.0

package/src/evaluation/axis-checks/checks/universal.ts

@@ -4,7 +4,8 @@
 // component. Dispatched via a "universal" gate that matches every render
 // value.
 
-import { LUCIDE_ICON_NAMES } from "@ggui-ai/design";
+import { LUCIDE_ICON_NAMES, maxWidth as CONTAINER_MAX_WIDTH } from "@ggui-ai/design";
+import { CANVAS_VIEWPORTS, type CanvasClass } from "../../../design-mode.js";
 import type { EvalIssue } from "../../types-public.js";
 import type { AxisCheck, AxisCheckInput } from "../types.js";
 import {
@@ -333,6 +334,171 @@ function runViewportSized(input: AxisCheckInput): EvalIssue[] {
   ];
 }
 
+// ── universal.terminal_action_unguarded (ggui#1108, mitigation) ────────
+// A control whose action the user means ONCE — submit, confirm, approve,
+// schedule, reserve, book, pay, checkout, place order — that stays armed after
+// it fires is one double-click away from doing it twice. The check is a WARN,
+// deliberately: terminality lives in the request and the contract, not in a
+// name, so a static rule can suspect it and must not refuse over it. It fires
+// only when a terminal-sounding action or control exists AND the source guards
+// nothing at all (no `disabled=`, no `aria-disabled`), which is the shape with
+// no reading under which the control is safe.
+/** The words that make an action read as meant-once. Matched as WORDS, never as substrings. */
+const TERMINAL_WORDS = new Set([
+  "submit", "confirm", "approve", "schedule", "reserve", "book", "pay", "checkout", "purchase", "order",
+]);
+/** In prose (a control's label) the same words, with real boundaries. */
+const TERMINAL_LABEL_RX = /\b(submit|confirm|approve|schedule|reserve|book|pay|checkout|purchase|place\s+order)\b/i;
+const GUARD_RX = /\b(disabled|aria-disabled)\s*=/;
+
+/** `submitBooking` → ['submit','booking']; `place_order` → ['place','order']. A NAME is words, not a string to search. */
+function nameWords(name: string): string[] {
+  return name
+    .split(/(?=[A-Z])|[_\-\s]+/)
+    .map((w) => w.toLowerCase())
+    .filter((w) => w.length > 0);
+}
+
+/** The terminal-sounding action names and control labels a source carries, deduped, in order. */
+export function findUnguardedTerminalControls(sourceCode: string): string[] {
+  if (GUARD_RX.test(sourceCode)) return [];
+  const names = new Set<string>();
+  for (const m of sourceCode.matchAll(/useAction(?:<[^>]*>)?\(\s*['"`]([^'"`]+)['"`]/g)) {
+    const name = m[1] ?? "";
+    if (nameWords(name).some((w) => TERMINAL_WORDS.has(w))) names.add(name);
+  }
+  // A control's own words, taken as the plain text immediately before its close
+  // tag — attributes can carry `=>`, so a label is read from the text, never by
+  // trying to skip an attribute list with a regex.
+  for (const m of sourceCode.matchAll(/>([^<>{}]{1,60})<\/Button>/g)) {
+    const label = (m[1] ?? "").replace(/\s+/g, " ").trim();
+    if (label.length > 0 && TERMINAL_LABEL_RX.test(label)) names.add(label.slice(0, 40));
+  }
+  return [...names];
+}
+
+function runTerminalActionUnguarded(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const found = findUnguardedTerminalControls(input.sourceCode);
+  if (found.length === 0) return [];
+  const list = found.map((t) => `"${t}"`).join(", ");
+  return [
+    mkIssue(
+      "universal.terminal_action_unguarded",
+      `${list} reads as an action the user means once, and nothing in this component disables the control after it fires — a double-click sends it twice.`,
+      "Hold the fired state (`const [submitted, setSubmitted] = useState(false)`), set it in the handler, and pass `disabled={submitted}` to that control with a word that says so (\"Submitted\"). If the action IS meant to repeat — sending a message, adding an item — leave it armed and ignore this.",
+      "warn",
+    ),
+  ];
+}
+
+// ── universal.root_width_cap (ggui#1117 — the eval leg ggui#1113 left out) ─
+// FRAME_SIZING's width half: the outermost element FILLS the frame; a width
+// cap belongs INSIDE it, on the column that holds text. A cap on the root is
+// the defect on a wide canvas (the card becomes a narrow strip with the
+// frame's ground on either side) and a no-op in a chat bubble (~400 px; a
+// 480 px cap never binds) — so the check reads `input.canvas`: it stands
+// down with no canvas (never a guess) and below `md`, and fires only for a
+// cap SMALLER than the canvas. A bare `<Container>` is a cap too — its
+// default preset is `lg`, 768 px — so it binds on `lg` / `xl` and not on
+// `md`. A cap the check cannot resolve to pixels (a `max-w-*` class, `rem`,
+// `%`) is reported because the prompt forbids it on the root. WARN, not
+// fail: the prompt names the one shape never to write; whether a centred
+// column was the right composition stays the model's call.
+export interface RootWidthCap {
+  /** The outermost element's tag name as written. */
+  readonly element: string;
+  /** The cap as written (`maxWidth="sm"`, `maxWidth: '480px'`, `max-w-md`, or `lg (Container default)`). */
+  readonly cap: string;
+  /** The cap in pixels when it resolves (a Container preset, an `Npx` value); `null` otherwise. */
+  readonly px: number | null;
+}
+
+/** The opening tag of the OUTERMOST element the default export returns, as written; `null` for none or a fragment. */
+function rootOpeningTag(sourceCode: string): { readonly name: string; readonly attrs: string } | null {
+  const start = sourceCode.indexOf("export default function");
+  const body = start >= 0 ? sourceCode.slice(start) : sourceCode;
+  const ret = /\breturn\s*\(?\s*</.exec(body);
+  if (ret === null) return null;
+  const at = ret.index + ret[0].length - 1;
+  const nameMatch = /^<([A-Za-z][\w.]*)/.exec(body.slice(at));
+  if (nameMatch === null) return null;
+  let j = at + nameMatch[0].length;
+  let depth = 0;
+  let quote: string | null = null;
+  for (; j < body.length; j++) {
+    const ch = body[j]!;
+    if (quote !== null) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+    else if (ch === ">" && depth === 0) break;
+  }
+  return { name: nameMatch[1]!, attrs: body.slice(at + nameMatch[0].length, j) };
+}
+
+const CONTAINER_PRESETS: Readonly<Record<string, string>> = CONTAINER_MAX_WIDTH;
+const NOT_A_CAP = new Set(["full", "none", "100%", "unset", "initial", "inherit"]);
+
+/** `sm` → 480; `480px` → 480; `100%` / `full` → not a cap (`undefined`); anything else → a cap of unknown size (`null`). */
+function capPx(value: string): number | null | undefined {
+  const v = value.trim();
+  if (NOT_A_CAP.has(v)) return undefined;
+  const resolved = CONTAINER_PRESETS[v] ?? v;
+  if (NOT_A_CAP.has(resolved)) return undefined;
+  const px = /^(\d+(?:\.\d+)?)px$/.exec(resolved);
+  return px === null ? null : Number(px[1]);
+}
+
+/** The width cap the outermost returned element carries, or `null` when it fills the frame. */
+export function findRootWidthCap(sourceCode: string): RootWidthCap | null {
+  const root = rootOpeningTag(sourceCode);
+  if (root === null) return null;
+  const { name, attrs } = root;
+  const prop = /\bmaxWidth\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)'|(\d+(?:\.\d+)?))\s*\})/.exec(attrs);
+  if (prop !== null) {
+    const raw = prop[1] ?? prop[2] ?? prop[3] ?? prop[4] ?? `${prop[5]!}px`;
+    const px = capPx(raw);
+    return px === undefined ? null : { element: name, cap: `maxWidth="${raw}"`, px };
+  }
+  const style = /\bmaxWidth\s*:\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`|(\d+(?:\.\d+)?))/.exec(attrs);
+  if (style !== null) {
+    const raw = style[1] ?? style[2] ?? style[3] ?? `${style[4]!}px`;
+    const px = capPx(raw);
+    return px === undefined ? null : { element: name, cap: `maxWidth: '${raw}'`, px };
+  }
+  const cls = /(?<![\w-])max-w-([\w[\]%.-]+)/.exec(attrs);
+  if (cls !== null) {
+    if (cls[1] === "full" || cls[1] === "none") return null;
+    return { element: name, cap: `max-w-${cls[1]!}`, px: null };
+  }
+  if (name === "Container") return { element: name, cap: "lg (Container default)", px: capPx("lg") ?? null };
+  return null;
+}
+
+const WIDE_CANVASES: ReadonlySet<CanvasClass> = new Set<CanvasClass>(["md", "lg", "xl"]);
+
+function runRootWidthCap(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  if (input.canvas === undefined || !WIDE_CANVASES.has(input.canvas)) return [];
+  const cap = findRootWidthCap(input.sourceCode);
+  if (cap === null) return [];
+  const width = CANVAS_VIEWPORTS[input.canvas].width;
+  if (cap.px !== null && cap.px >= width) return [];
+  const sized = cap.px !== null ? `${cap.px}px on a ${width}px canvas` : `on a ${width}px canvas`;
+  return [
+    mkIssue(
+      "universal.root_width_cap",
+      `The outermost element <${cap.element}> carries a width cap (${cap.cap}, ${sized}): on this canvas the card becomes a narrow strip with the frame's ground on either side. The frame owns the width; a cap belongs INSIDE the root, on the column that holds text.`,
+      'Let the root fill the frame — drop the cap on the element you return at the top (or `maxWidth="full"`) — and put the reading measure on an inner column: `<Box padding="lg"><Container maxWidth="sm">…</Container></Box>`.',
+      "warn",
+    ),
+  ];
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
   {
     id: "universal.icon_name_known",
@@ -352,6 +518,18 @@ export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
     values: ALL_RENDER_VALUES,
     run: runViewportSized,
   },
+  {
+    id: "universal.root_width_cap",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runRootWidthCap,
+  },
+  {
+    id: "universal.terminal_action_unguarded",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runTerminalActionUnguarded,
+  },
   {
     id: "universal.accent_text_ink",
     axis: "render",

package/src/evaluation/axis-checks/dispatch.ts

@@ -9,7 +9,7 @@ import { REGISTRY } from "./registry.js";
 import { matches, type AxisCheck, type AxisCheckInput } from "./types.js";
 import { axisCheckTraceEnabled } from "./helpers.js";
 import { createHash } from "node:crypto";
-import type { DesignMode } from "../../design-mode.js";
+import type { CanvasClass, DesignMode } from "../../design-mode.js";
 
 export interface RunAxisChecksInput {
   sourceCode: string;
@@ -18,6 +18,8 @@ export interface RunAxisChecksInput {
   originalPrompt: string;
   /** Which triad produced the source — see `AxisCheckInput.designMode`. */
   designMode?: DesignMode;
+  /** The canvas the source is judged for — see `AxisCheckInput.canvas` (ggui#1117); absent = no rendering context. */
+  canvas?: CanvasClass;
 }
 
 export function runAxisChecks(
@@ -30,6 +32,7 @@ export function runAxisChecks(
     originalPrompt: input.originalPrompt,
     classification,
     ...(input.designMode !== undefined ? { designMode: input.designMode } : {}),
+    ...(input.canvas !== undefined ? { canvas: input.canvas } : {}),
   };
   if (input.compiledCode === null) {
     traceAxisChecksSkipped(facts, "compiledCode null — no check ran");
@@ -93,6 +96,8 @@ export interface AxisCheckTrace {
   readonly classification: Classification["vector"];
   readonly propsSpecKeys: readonly string[];
   readonly propsSpecPropertyKeys: readonly string[];
+  /** The canvas the verdict was built for (ggui#1117) — present only when the input carried one. */
+  readonly canvas?: CanvasClass;
   readonly matched: readonly string[];
   readonly issues: ReadonlyArray<{ readonly id: string; readonly result: EvalIssue["result"] }>;
   readonly note?: string;
@@ -107,5 +112,7 @@ function traceFacts(input: AxisTraceFacts): Omit<AxisCheckTrace, "matched" | "is
     classification: input.classification.vector,
     propsSpecKeys: Object.keys(propsSpec ?? {}),
     propsSpecPropertyKeys: Object.keys(propsSpec?.properties ?? {}),
+    // No default here, unlike designMode: an absent canvas is a fact about the caller, not a guess to paper over.
+    ...(input.canvas !== undefined ? { canvas: input.canvas } : {}),
   };
 }

package/src/evaluation/types-public.ts

@@ -280,6 +280,15 @@ export interface AxisCheckInput {
    * means `constrained`.
    */
   designMode?: DesignMode;
+  /**
+   * The rendering canvas the source is judged FOR (ggui#1117). A width cap on
+   * the outermost element is a defect on a fullscreen canvas and a no-op in a
+   * chat bubble, so a check that reads width must know the surface. Populated
+   * where the harness is built (`Harness.canvas`); ABSENT for callers with no
+   * rendering context — a check handles `undefined`, it never assumes a
+   * default (a silent `lg` would be the same guess with a nicer face).
+   */
+  canvas?: CanvasClass;
 }
 
 /**

package/src/harness/coding/generate-task-runner.ts

@@ -178,6 +178,7 @@ export function createGenerateTaskRunner(input: CreateGenerateRunnerInput): Task
           systemPrompt: session.systemPrompt,
           harness: session.harness,
           contract: params.contract,
+          originalPrompt: params.userPrompt,
           commitMeta: session.commitMeta,
           originalProps: session.originalProps,
           costTracker: session.costTracker,

package/src/harness/coding/run-coding-turn.ts

@@ -155,6 +155,13 @@ export interface CodingTurnContext {
   readonly systemPrompt: string;
   readonly harness: Harness;
   readonly contract: DataContract | undefined;
+  /**
+   * The ORIGINAL request (ggui#1122) — what the eval round has always judged
+   * against, now handed to auto-commit so the axis checks run on the serve
+   * path with the same input. Required: a caller that forgot it would silently
+   * run no axis checks on every served generation.
+   */
+  readonly originalPrompt: string;
   readonly commitMeta: Map<string, CommitMetadata>;
   readonly originalProps: string | undefined;
   readonly costTracker: CostTracker | null;
@@ -669,6 +676,13 @@ ${closingInstruction}`;
     // Which tier-0 legs fire — the design-vocabulary legs stand down in
     // `free` mode; every contract leg runs in both.
     harness.designMode,
+    // ggui#1122: the harness's pre-filtered axis checks run at auto-commit — the serve path.
+    {
+      checks: harness.check.axisChecks,
+      classification: harness.classification,
+      originalPrompt: ctx.originalPrompt,
+      ...(harness.canvas !== undefined ? { canvas: harness.canvas } : {}),
+    },
   );
   const toolMs = Date.now() - toolStart;
 

package/src/harness/types-public.ts

@@ -303,6 +303,13 @@ export interface Harness {
    * into `free`.
    */
   readonly designMode: DesignMode;
+  /**
+   * The rendering canvas this harness was built for (ggui#1117) — threaded
+   * from `CreateHarnessInput.canvas` into the HOW leg (the `free` prompt
+   * states it) and, via `run-check.ts`, onto every axis check's input.
+   * ABSENT when the caller had no rendering context; never defaulted.
+   */
+  readonly canvas?: CanvasClass;
   /** The app's generation profile in force for this harness (#991), if any. */
   readonly profile?: GenerationProfileInput;
 

package/src/run-check.ts

@@ -119,6 +119,8 @@ export async function runCheck(input: RunCheckInput): Promise<CheckResult> {
     originalPrompt: prompt,
     classification: harness.classification,
     designMode: harness.designMode,
+    // ggui#1117: the canvas the harness was built for, when it has one — never a default.
+    ...(harness.canvas !== undefined ? { canvas: harness.canvas } : {}),
   };
   // The one runner `runAxisChecks` shares (ggui#1046 trace prints here, on the served path).
   const axisRun = runGatedAxisChecks(check.axisChecks, axisInput);

package/src/tools/get-wire.ts

@@ -2,4 +2,4 @@
  * AUTO-GENERATED from @ggui-ai/wire JSDoc.
  * Do not edit manually. Run: pnpm --filter @ggui-ai/wire generate:docs
  */
-export const WIRE_DOCUMENTATION = "# ggui Wire Hooks Reference\n\n> Wire hooks connect generated UI components to agent communication.\n> They are pre-imported in the boilerplate — use them directly.\n> All hooks must be called inside a GguiWireProvider (handled automatically by the renderer).\n\nImport: `import { useAction, useStream } from '@ggui-ai/wire'`\n\n## Communication Hooks\n\n\n\nThese are the wire primitives for component-agent communication. `useWiredTool` retired 2026-05-11 — agentCapabilities.tools is a catalog the AGENT invokes, not a component hook surface; user gestures use `useAction(name)` and the optional `nextStep` field on the action entry names the tool the agent SHOULD invoke next.\n\n### useAction\n\nFire an action to the agent. Fire-and-forget — no response, no pending state.\n\nEvery action is an event: it lands on the GguiSession's consume buffer and\nthe agent receives it on its next turn (via `ggui_consume`). The action\nentry's optional `nextStep` names the tool the agent SHOULD invoke in\nresponse — advisory only; the agent owns the call decision. Component code\nis identical either way: call `useAction(name)(payload)` and treat\n`nextStep` as informational (use it to inform button labels, icons, copy).\n\nRUNTIME DEDUP (backstop, not a feature). Same-`(name, payload)` calls within\none event-loop task are coalesced — the first wins, subsequent duplicates\nare suppressed. This is the structural defense against LLM-generated\nnested-interactive components where a Checkbox `onChange` and an outer\n`Card as={Clickable}` `onClick` both wire to the same `useAction` binding;\nthe inner gesture bubbles to the outer handler, so without dedup one user\nclick would fire the action twice (a toggle would run back-to-back and the\nuser's change would disappear). **Do not rely on this as a feature** — wire\neach `useAction` callback to exactly ONE interactive surface; the dedup\nexists only because the LLM's source code can be wrong in subtle ways and\nthe runtime is the only place that can see the actual event-bubble path.\nSee `dispatch-dedup.ts` for the full failure-mode rationale.\n\nNEVER SILENT. When the dedup fires, a `console.warn` is emitted in BOTH dev\nand prod with the full diagnostic. The suppression is always visible in\nbrowser DevTools; operators investigating a \"the second click does nothing\"\nreport see the warning immediately. A structured observer also exists as\n`WireConfig.onDispatchSuppressed`, but the first-party renderers never set\nit — it is reachable only from a hand-built `WireConfig` (see its\ndocstring), so the console signal is what operators get in practice.\n\n**Signature:** `useAction<T = unknown>(actionName: string): (data: T) => void`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | Action name from the action contract |\n\n**Returns:** `(data: T) => void`\n\n**Example:**\n```tsx\nconst submitForm = useAction<{name: string; email: string}>('formSubmit');\n\n// In JSX:\n<Button onClick={() => submitForm({ name, email })}>Submit</Button>\n```\n\n\n### useStream\n\nSubscribe to deliveries on a named stream channel.\n\nHonors the channel's per-delivery `mode` ('append' vs 'replace')\nand the optional `complete` terminal marker. Channels declared\n`mode: 'replace'` on the spec typically emit every delivery with\n`mode: 'replace'` — this hook folds them into a single-latest\nvalue without accumulating history.\n\n**Signature:** `useStream<T = unknown>(channelName: string): StreamResult<T>`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| channelName | `string` | Channel name from the GguiSession's streamSpec |\n\n**Returns:** `StreamResult<T>`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| latest | `T \\| null` | Most recent payload delivered on this channel, or null if none received yet. |\n| all | `T[]` | All payloads accumulated on this channel.  - `mode: 'append'` deliveries are pushed to the tail (continuous stream). - `mode: 'replace'` deliveries collapse `all` to a single-element array   containing the latest payload — matching the channel's   \"full replacement\" semantics. |\n| isComplete | `boolean` | Truthy after the channel has delivered an envelope with `complete: true`. Subscribers flip into a \"channel closed\" rendering state based on this signal; further deliveries on a completed channel are still accumulated, since the underlying wire doesn't enforce quiescence. |\n\n**Example:**\n```tsx\nconst progress = useStream<{ percent: number; message: string }>('progress');\n\n// In JSX:\n{progress.latest && (\n  <Progress value={progress.latest.percent} />\n)}\n<Text>{progress.all.length} updates received</Text>\n```\n\n\n## Context Hooks\n\n\n\nRead-only access to render, app, and auth context.\n\n### useAuth\n\nRead-only auth context. Token excluded — auth is added server-side.\n\n**Signature:** `useAuth(): AuthInfo`\n\n**Returns:** `AuthInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| userId | `string` | userId |\n| isAuthenticated | `boolean` | isAuthenticated |\n\n**Example:**\n```tsx\nconst auth = useAuth();\n\n// In JSX:\n{auth.isAuthenticated\n  ? <Text>Welcome, user {auth.userId}</Text>\n  : <Text>Please sign in</Text>\n}\n```\n\n\n### useApp\n\nRead-only app metadata.\n\n**Signature:** `useApp(): AppInfo`\n\n**Returns:** `AppInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| appId | `string` | appId |\n| appName | `string` | appName |\n| appDescription | `string` | appDescription |\n| appIcon | `string` | appIcon |\n\n**Example:**\n```tsx\nconst app = useApp();\n\n// In JSX:\n<Heading>{app.appName}</Heading>\n{app.appDescription && <Text>{app.appDescription}</Text>}\n```\n\n\n### useRender\n\nRead-only render context with connection status.\n\n**Signature:** `useRender(): GguiSessionInfo`\n\n**Returns:** `GguiSessionInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| sessionId | `string` | sessionId |\n| isConnected | `boolean` | isConnected |\n\n**Example:**\n```tsx\nconst render = useRender();\n\n// In JSX:\n<Badge variant={render.isConnected ? 'success' : 'error'}>\n  {render.isConnected ? 'Connected' : 'Disconnected'}\n</Badge>\n```\n\n\n## Provider\n\n\n\nThe provider is set up automatically by the renderer. Generated components do not need to wrap themselves in a provider.\n\n### GguiWireProvider\n\nReact context provider that injects WireConfig for all wire hooks.\n\n**Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| config | `WireConfig` | config |\n| children | `ReactNode` | children |\n\n**Example:**\n```tsx\n<GguiWireProvider config={wireConfig}>\n  <YourComponent />\n</GguiWireProvider>\n```\n\n\n## Internal: WireConfig\n\n\n\nThis is the configuration object passed to GguiWireProvider. Generated components do not interact with this directly — it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider — the renderer inside the\niframe.\n\nEvery method is typed against the contract generic `T` so typed\ncallers get compile-time enforcement:\n  - `dispatch(name, data)` — `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` — same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases — no call-site break.\n\nThe contract's `agentCapabilities.tools` catalog declares tools the AGENT\ninvokes (not the component); user gestures fire via\n`dispatch(name, data)` and the optional `nextStep` field on the\naction entry names the tool the agent SHOULD invoke next.\n\nThe renderer mounts exactly ONE GguiSession per iframe — `render.sessionId`\nis the stable identity the WireProvider was constructed with. No\nper-item scoping factory; with a one-GguiSession-per-mount lifecycle,\n\"scope\" collapses to identity.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| app | `{     readonly appId: string;     readonly appName: string;     readonly appDescription?: string;     readonly appIcon?: string;   }` | app |\n| render | `{     readonly sessionId: string;     readonly isConnected: boolean;   }` | render |\n| auth | `{     readonly userId?: string;     readonly isAuthenticated: boolean;   }` | auth |\n| dispatch | `<N extends string>(     actionName: N,     data: WireDispatchData<T, N>,   ) => void` | Fire an action to the agent (fire-and-forget over WS). Typed callers get compile-time checked `name` + `data`; untyped callers (`T = DataContract`) keep the broad shape. |\n| subscribe | `<N extends string>(     channelName: N,     handler: (delivery: StreamDelivery<WireStreamPayload<T, N>>) => void,   ) => () => void` | Subscribe to deliveries on a named stream channel. |\n| onDispatchSuppressed | `(info: DispatchSuppressedInfo) => void` | Optional structured observability for `useAction`'s task-scoped duplicate-dispatch suppression. Fires alongside the always-on `console.warn` whenever the runtime coalesces a same-(name, payload) re-dispatch within one event-loop task — the nested- interactive double-fire backstop.  Reachability constraint: the first-party renderers do NOT set this field — `buildRootWireConfig` (`@ggui-ai/iframe-runtime`) and `<GguiRender>`'s internal config both omit it. It fires only when a host hand-builds a complete `WireConfig` and mounts `GguiWireProvider` itself. On every first-party render path the `console.warn` is the sole suppression signal. |\n";
+export const WIRE_DOCUMENTATION = "# ggui Wire Hooks Reference\n\n> Wire hooks connect generated UI components to agent communication.\n> They are pre-imported in the boilerplate — use them directly.\n> All hooks must be called inside a GguiWireProvider (handled automatically by the renderer).\n\nImport: `import { useAction, useStream } from '@ggui-ai/wire'`\n\n## Communication Hooks\n\n\n\nThese are the wire primitives for component-agent communication. `useWiredTool` retired 2026-05-11 — agentCapabilities.tools is a catalog the AGENT invokes, not a component hook surface; user gestures use `useAction(name)` and the optional `nextStep` field on the action entry names the tool the agent SHOULD invoke next.\n\n### useAction\n\nFire an action to the agent. Fire-and-forget — no response, no pending state.\n\nEvery action is an event: it lands on the GguiSession's consume buffer and\nthe agent receives it on its next turn (via `ggui_consume`). The action\nentry's optional `nextStep` names the tool the agent SHOULD invoke in\nresponse — advisory only; the agent owns the call decision. Component code\nis identical either way: call `useAction(name)(payload)` and treat\n`nextStep` as informational (use it to inform button labels, icons, copy).\n\nRUNTIME DEDUP (backstop, not a feature). Same-`(name, payload)` calls within\none event-loop task are coalesced — the first wins, subsequent duplicates\nare suppressed. This is the structural defense against LLM-generated\nnested-interactive components where a Checkbox `onChange` and an outer\n`Card as={Clickable}` `onClick` both wire to the same `useAction` binding;\nthe inner gesture bubbles to the outer handler, so without dedup one user\nclick would fire the action twice (a toggle would run back-to-back and the\nuser's change would disappear). **Do not rely on this as a feature** — wire\neach `useAction` callback to exactly ONE interactive surface; the dedup\nexists only because the LLM's source code can be wrong in subtle ways and\nthe runtime is the only place that can see the actual event-bubble path.\nSee `dispatch-dedup.ts` for the full failure-mode rationale.\n\nNEVER SILENT. When the dedup fires, a `console.warn` is emitted in BOTH dev\nand prod with the full diagnostic. The suppression is always visible in\nbrowser DevTools; operators investigating a \"the second click does nothing\"\nreport see the warning immediately. A structured observer also exists as\n`WireConfig.onDispatchSuppressed`, but the first-party renderers never set\nit — it is reachable only from a hand-built `WireConfig` (see its\ndocstring), so the console signal is what operators get in practice.\n\n**Signature:** `useAction<T = unknown>(actionName: string): (data: T) => void`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| actionName | `string` | Action name from the action contract |\n\n**Returns:** `(data: T) => void`\n\n**Example:**\n```tsx\nconst submitForm = useAction<{name: string; email: string}>('formSubmit');\n\n// In JSX:\n<Button onClick={() => submitForm({ name, email })}>Submit</Button>\n```\n\n\n### useStream\n\nSubscribe to deliveries on a named stream channel.\n\nHonors the channel's per-delivery `mode` ('append' vs 'replace')\nand the optional `complete` terminal marker. Channels declared\n`mode: 'replace'` on the spec typically emit every delivery with\n`mode: 'replace'` — this hook folds them into a single-latest\nvalue without accumulating history.\n\n**Signature:** `useStream<T = unknown>(channelName: string): StreamResult<T>`\n\n**Parameters:**\n\n| Param | Type | Description |\n|-------|------|-------------|\n| channelName | `string` | Channel name from the GguiSession's streamSpec |\n\n**Returns:** `StreamResult<T>`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| latest | `T \\| null` | Most recent payload delivered on this channel, or null if none received yet. |\n| all | `T[]` | All payloads accumulated on this channel.  - `mode: 'append'` deliveries are pushed to the tail (continuous stream). - `mode: 'replace'` deliveries collapse `all` to a single-element array   containing the latest payload — matching the channel's   \"full replacement\" semantics. |\n| isComplete | `boolean` | Truthy after the channel has delivered an envelope with `complete: true`. Subscribers flip into a \"channel closed\" rendering state based on this signal; further deliveries on a completed channel are still accumulated, since the underlying wire doesn't enforce quiescence. |\n\n**Example:**\n```tsx\nconst progress = useStream<{ percent: number; message: string }>('progress');\n\n// In JSX:\n{progress.latest && (\n  <Progress value={progress.latest.percent} />\n)}\n<Text>{progress.all.length} updates received</Text>\n```\n\n\n## Context Hooks\n\n\n\nRead-only access to render, app, and auth context.\n\n### useAuth\n\nRead-only auth context. Token excluded — auth is added server-side.\n\n**Signature:** `useAuth(): AuthInfo`\n\n**Returns:** `AuthInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| userId | `string` | userId |\n| isAuthenticated | `boolean` | isAuthenticated |\n\n**Example:**\n```tsx\nconst auth = useAuth();\n\n// In JSX:\n{auth.isAuthenticated\n  ? <Text>Welcome, user {auth.userId}</Text>\n  : <Text>Please sign in</Text>\n}\n```\n\n\n### useApp\n\nRead-only app metadata.\n\n**Signature:** `useApp(): AppInfo`\n\n**Returns:** `AppInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| appId | `string` | appId |\n| appName | `string` | appName |\n| appDescription | `string` | appDescription |\n| appIcon | `string` | appIcon |\n\n**Example:**\n```tsx\nconst app = useApp();\n\n// In JSX:\n<Heading>{app.appName}</Heading>\n{app.appDescription && <Text>{app.appDescription}</Text>}\n```\n\n\n### useRender\n\nRead-only render context with connection status.\n\n**Signature:** `useRender(): GguiSessionInfo`\n\n**Returns:** `GguiSessionInfo`\n\n| Property | Type | Description |\n|----------|------|-------------|\n| sessionId | `string` | sessionId |\n| isConnected | `boolean` | isConnected |\n\n**Example:**\n```tsx\nconst render = useRender();\n\n// In JSX:\n<Badge variant={render.isConnected ? 'success' : 'error'}>\n  {render.isConnected ? 'Connected' : 'Disconnected'}\n</Badge>\n```\n\n\n## Provider\n\n\n\nThe provider is set up automatically by the renderer. Generated components do not need to wrap themselves in a provider.\n\n### GguiWireProvider\n\nReact context provider that injects WireConfig for all wire hooks.\n\n**Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| config | `WireConfig` | config |\n| children | `ReactNode` | children |\n\n**Example:**\n```tsx\n<GguiWireProvider config={wireConfig}>\n  <YourComponent />\n</GguiWireProvider>\n```\n\n\n## Internal: WireConfig\n\n\n\nThis is the configuration object passed to GguiWireProvider. Generated components do not interact with this directly — it is provided by the renderer.\n\n### WireConfig\n\nConfiguration injected by the provider — the renderer inside the\niframe.\n\nEvery method is typed against the contract generic `T` so typed\ncallers get compile-time enforcement:\n  - `dispatch(name, data)` — `name` MUST be a declared actionSpec\n    key; `data` MUST satisfy that action's schema.\n  - `subscribe(channel, handler)` — same discipline for streamSpec.\n\nUntyped callers (`T = DataContract` default) degrade to the broad\nshape via the conditional `WireDispatchData` / `WireStreamPayload`\naliases — no call-site break.\n\nThe contract's `agentCapabilities.tools` catalog declares tools the AGENT\ninvokes (not the component); user gestures fire via\n`dispatch(name, data)` and the optional `nextStep` field on the\naction entry names the tool the agent SHOULD invoke next.\n\nThe renderer mounts exactly ONE GguiSession per iframe — `render.sessionId`\nis the stable identity the WireProvider was constructed with. No\nper-item scoping factory; with a one-GguiSession-per-mount lifecycle,\n\"scope\" collapses to identity.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| app | `{     readonly appId: string;     readonly appName: string;     readonly appDescription?: string;     readonly appIcon?: string;   }` | app |\n| render | `{     readonly sessionId: string;     readonly isConnected: boolean;   }` | render |\n| auth | `{     readonly userId?: string;     readonly isAuthenticated: boolean;   }` | auth |\n| dispatch | `<N extends string>(     actionName: N,     data: WireDispatchData<T, N>,   ) => void` | Fire an action to the agent (fire-and-forget over WS). Typed callers get compile-time checked `name` + `data`; untyped callers (`T = DataContract`) keep the broad shape. |\n| subscribe | `<N extends string>(     channelName: N,     handler: (delivery: StreamDelivery<WireStreamPayload<T, N>>) => void,   ) => () => void` | Subscribe to deliveries on a named stream channel. |\n| onDispatchSuppressed | `(info: DispatchSuppressedInfo) => void` | Optional structured observability for the runtime's two dispatch- suppression invariants — the task-scoped duplicate backstop (`reason: 'duplicate-dispatch'`, fired by `useAction`) and the render-lifetime one-shot guard (`reason: 'one-shot-spent'`, fired by the config's own `dispatch` when a declared `oneShot` action is gestured a second time, ggui#1108). Both fire ALONGSIDE the always-on `console.warn`; neither reaches the agent.  Reachability constraint: the first-party renderers do NOT set this field — `buildRootWireConfig` (`@ggui-ai/iframe-runtime`) and `<GguiRender>`'s internal config both omit it. It fires only when a host hand-builds a complete `WireConfig` (or passes `onDispatchSuppressed` to `buildWireConfig`). On every first-party render path the `console.warn` is the sole suppression signal — which is what the `oneShot` contract requires as its minimum trace. |\n";