@ggui-ai/ui-gen 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/ui-gen",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "UI generation harness for ggui — the LLM system prompt, multi-turn coding loop, and evaluation engine that turn a DataContract into a React component. Implements the UiGenerator contract from @ggui-ai/mcp-server-core; consumed by @ggui-ai/mcp-server.",
   "license": "Apache-2.0",
   "keywords": [
@@ -188,9 +188,9 @@
     "puppeteer-core": "^24.40.0 || ^25.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@ggui-ai/mcp-server-core": "0.17.0",
-    "@ggui-ai/protocol": "0.17.0",
-    "@ggui-ai/project-config": "0.17.0"
+    "@ggui-ai/mcp-server-core": "0.18.0",
+    "@ggui-ai/project-config": "0.18.0",
+    "@ggui-ai/protocol": "0.18.0"
   },
   "peerDependenciesMeta": {
     "@google/adk": {
@@ -229,11 +229,11 @@
     "openai": "^7.9.0",
     "typescript": "^5.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/sandbox": "0.17.0",
-    "@ggui-ai/gadgets": "0.17.0",
-    "@ggui-ai/design": "0.17.0",
-    "@ggui-ai/wire": "0.17.0",
-    "@ggui-ai/ui-visual-tester": "0.17.0"
+    "@ggui-ai/design": "0.18.0",
+    "@ggui-ai/sandbox": "0.18.0",
+    "@ggui-ai/ui-visual-tester": "0.18.0",
+    "@ggui-ai/wire": "0.18.0",
+    "@ggui-ai/gadgets": "0.18.0"
   },
   "devDependencies": {
     "@google/adk": "^2.0.0",
@@ -248,9 +248,9 @@
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",
     "vitest": "^3.2.6",
-    "@ggui-ai/project-config": "0.17.0",
-    "@ggui-ai/mcp-server-core": "0.17.0",
-    "@ggui-ai/protocol": "0.17.0"
+    "@ggui-ai/project-config": "0.18.0",
+    "@ggui-ai/protocol": "0.18.0",
+    "@ggui-ai/mcp-server-core": "0.18.0"
   },
   "engines": {
     "node": ">=22.0.0"

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

@@ -29,6 +29,7 @@ import {
   DATA_PARAMETERIZATION,
   DEFENSIVE_CODING,
   FRAME_SIZING,
+  TERMINAL_ACTIONS,
   GESTURE_ROUTING,
   PROTOCOL_NOTES,
   renderGadgetCatalogSection,
@@ -310,6 +311,7 @@ ${axisSection}
     CONTRACT_SURFACE,
     DEFENSIVE_CODING,
     GESTURE_ROUTING,
+    TERMINAL_ACTIONS,
     FREE_GESTURE_SURFACE,
     ANTI_PATTERNS,
     CROSS_REFERENCE_RULES,

package/src/boilerplate/generate.ts

@@ -252,7 +252,14 @@ export function generateBoilerplate(
     // Inline signature tells the LLM exactly how to call this action
     const callSig = tsType === "void" ? "() => void — fire and forget" : `(data: ${tsType}) => void`;
     const toolHint = tool ? ` → nextStep: ${tool}` : "";
-    actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}`);
+    // ggui#1108 (mitigation): the reminder sits at the EXACT site the model
+    // writes the handler. It is a hint, not the rule — the rule is the prompt's
+    // `TERMINAL_ACTIONS` section, because only the request and the contract say
+    // which actions are meant once. A site comment alone moves generation by
+    // roughly nothing (Exp 002b: adoption 1/36), which is why it is the
+    // smallest of the three legs and never the one relied on.
+    const onceHint = " — if this is meant ONCE, disable its control after it fires";
+    actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
     actionReturnFields.push(key);
   }
 

package/src/boilerplate/hard-sections.ts

@@ -216,6 +216,28 @@ Rules:
 4. Copy comes from the props. NEVER invent display text the contract does not carry — no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. A caps label exists only when a prop supplies its text (\`<Text caps>{props.section}</Text>\`); a heading's fallback is the request's own words, never a slogan of your own. Text the agent cannot change is chatter on every render.
 5. Props interface must be typed and exported.`;
 
+/**
+ * A control that fires an action the user would not mean to repeat must not
+ * stay armed (ggui#1108 MITIGATION — the fix is one-shot-ness DECLARED on the
+ * action and enforced by the runtime; this reduces exposure meanwhile). Both
+ * arms, one HARD section: the model knows from the request and the contract
+ * which actions are terminal, which no static rule of ours can infer.
+ */
+export const TERMINAL_ACTIONS = `## Actions the user means once
+
+A second press is a mistake only when it would make a SECOND THING HAPPEN IN THE WORLD — a second booking, a second charge, a second order, a second application sent. If pressing again would only write the SAME STATE AGAIN — saving, updating, renaming, setting a preference, toggling — nothing is duplicated and the control stays armed.
+
+Guard a control only where you have evidence, not a feeling about the verb: the request itself names a one-time commitment — "submit the application", "place the order", "confirm the booking".
+
+**When in doubt, leave it armed.** A control the user cannot press a second time has lost them something that worked — save, edit, save again is ordinary. A control left armed is only what every interface does by default.
+
+When you do guard one:
+- Hold a small piece of state for it and set it in the handler: \`const [submitted, setSubmitted] = useState(false)\`.
+- \`disabled={submitted}\` on the control that fires it, and say so in the label or beside it ("Submitted", "Request sent") — a control that is disabled without explanation reads as broken.
+- A card re-rendered with new props starts fresh; the state above lives with the component, not with the request.
+
+Nothing in the wire DECLARES one-shot-ness yet, which is why the test is what a second press would DO — not how final the word sounds.`;
+
 /**
  * The frame owns the height — the component never sizes itself to the
  * viewport (ggui#1075 Track A/B; receipted on #1096: 20 of 48 minted cells
@@ -223,12 +245,19 @@ Rules:
  * card told "compact"). Identical in both modes; the eval leg's tier-0
  * `universal.viewport_sized` fails what slips through.
  */
-export const FRAME_SIZING = `## Sizing — the frame owns the height
+export const FRAME_SIZING = `## Sizing — the frame owns the height and the width
 
 The host sizes the iframe; the component never sizes itself to the viewport. NEVER write \`100vh\` / \`100dvh\` / \`100svh\` (or an \`h-screen\` / \`min-h-screen\` class) as a height on any element:
 - An inline card takes its natural height. A content-sized frame is measured FROM the content, so a \`100vh\` root can never shrink and grows the frame on every re-measure.
 - Under fullscreen the frame already stretches your root to its full height. Centre inside it with flex (\`display: flex; flex-direction: column; justify-content: center\`), never with a viewport height.
-- To fill a parent that has a height use \`height: 100%\` or \`flex: 1\`; a viewport unit is only ever a \`max-height\` cap on a scroll region.`;
+- To fill a parent that has a height use \`height: 100%\` or \`flex: 1\`; a viewport unit is only ever a \`max-height\` cap on a scroll region.
+
+The width works the same way, and the mistake is the mirror image: **your outermost element FILLS the frame; a width cap belongs INSIDE it, on the column that holds text.**
+
+- Never put \`maxWidth\` (or a \`max-w-*\` class) on the element you return at the top. On a wide canvas that turns your card into a narrow strip with the frame's ground on either side of it, and on a narrow one it does nothing — the same composition reading differently at two sizes.
+- DO cap the reading measure inside: a column of prose is easiest to read at 60–70 characters, so wrap the TEXT in a \`<Container maxWidth="sm">\` (or your own \`max-width\`) and leave the root filling. A hero band, a toolbar, a table or an image then still uses the whole width, which is what makes a wide card look composed rather than padded.
+- Centre that inner column with the container's own centring, not by shrinking the root.
+- **They are two different elements.** Even when the whole card is one column of text, the root still fills and the column sits INSIDE it — \`<Box padding="lg"><Container maxWidth="sm">…</Container></Box>\`, never a root that is itself the container. A centred card is centring inside a filled frame, not a shrunken frame.`;
 
 /** Helper-component structure guidance (JSX depth 3–5, helpers above `Component`). Identical in both modes. */
 export const COMPONENT_STRUCTURE = `## Component Structure

package/src/boilerplate/system-prompt.ts

@@ -41,6 +41,7 @@ import {
   DEFENSIVE_CODING,
   FRAME_SIZING,
   GESTURE_ROUTING,
+  TERMINAL_ACTIONS,
   INTERACTIVE_TRAITS,
   PROTOCOL_NOTES,
   renderGadgetCatalogSection,
@@ -383,6 +384,7 @@ ${axisSection}
       CONTRACT_SURFACE,
       DEFENSIVE_CODING,
       GESTURE_ROUTING,
+      TERMINAL_ACTIONS,
       INTERACTIVE_TRAITS,
       ANTI_PATTERNS,
       CROSS_REFERENCE_RULES,

package/src/boilerplate/templates/layouts/fullscreen-desktop.tsx.tmpl

@@ -1,3 +1,5 @@
-    <Container maxWidth="xl" padding="lg">
-      {/* implement your UI here */}
-    </Container>
+    <Box padding="lg">
+      {/* implement your UI here — this root FILLS the frame.
+          Bands, toolbars, tables and images use the whole width;
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+    </Box>

package/src/boilerplate/templates/layouts/fullscreen-mobile.tsx.tmpl

@@ -1,3 +1,3 @@
-    <Container maxWidth="sm" padding="md">
-      {/* implement your UI here */}
-    </Container>
+    <Box padding="md">
+      {/* implement your UI here — this root FILLS the frame (a phone IS the measure). */}
+    </Box>

package/src/boilerplate/templates/layouts/fullscreen-universal.tsx.tmpl

@@ -1,3 +1,5 @@
-    <Container maxWidth="xl" padding="lg">
-      {/* implement your UI here */}
-    </Container>
+    <Box padding="lg">
+      {/* implement your UI here — this root FILLS the frame.
+          Bands, toolbars, tables and images use the whole width;
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+    </Box>

package/src/check/run-tier0.ts

@@ -352,6 +352,137 @@ function isGadgetExportImported(
   return false;
 }
 
+/**
+ * AST-precise detector for the compiles-but-renders-nothing class: the
+ * default-exported component's body never returns a tree.
+ *
+ * The boilerplate HANDS the model the wrapper — `base.tsx.tmpl` and
+ * `base-free.tsx.tmpl` both emit `return (` … `);` around `{{LAYOUT}}`.
+ * A model rewriting the root block can delete those two lines with it,
+ * leaving the JSX as a bare expression statement. That is legal TSX: it
+ * parses, esbuild compiles it, `typecheck()` passes it, and the
+ * component renders a blank frame. Seen once in twenty takes of the
+ * ggui#1113 A/B (`xs-chat-card`, run 2 — the judge spent a screenshot
+ * and an LLM call to report "completely blank").
+ *
+ * `compile/default-export` already guards the scaffold's
+ * `export default function` line and `types/props-interface` its
+ * `interface Props` line. The `return (` was the third scaffold line
+ * with nothing watching it.
+ *
+ * Conservative by construction — it reports ONLY when it positively
+ * identified a block-bodied default-export component:
+ *   - a concise arrow body (`export default () => <X/>`) returns by
+ *     construction → silent
+ *   - `export default memo(Component)` or any other expression it
+ *     cannot resolve to a function → silent
+ *   - a `return` inside a nested helper is not the component's own (the
+ *     walk stops at every nested function boundary), but ONE own-level
+ *     `return <value>` anywhere — an early `return null` included —
+ *     satisfies it.
+ *
+ * Returns `null` when the component returns (or could not be
+ * identified), else the 1-based line of the first bare JSX expression
+ * statement in its body — the line the fix belongs on — or `undefined`
+ * when the body has no JSX statement to point at either.
+ */
+function detectComponentNeverReturns(
+  sourceCode: string,
+): { jsxStatementLine: number | undefined } | null {
+  const sf = ts.createSourceFile(
+    'source.tsx',
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+    ts.ScriptKind.TSX,
+  );
+
+  const isFunctionLike = (n: ts.Node): boolean =>
+    ts.isFunctionDeclaration(n) ||
+    ts.isFunctionExpression(n) ||
+    ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n) ||
+    ts.isClassDeclaration(n) ||
+    ts.isClassExpression(n);
+
+  /** The top-level declaration `name` binds to, when it is a function. */
+  function resolveTopLevel(
+    name: string,
+  ): ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | undefined {
+    for (const st of sf.statements) {
+      if (ts.isFunctionDeclaration(st) && st.name?.text === name) return st;
+      if (ts.isVariableStatement(st)) {
+        for (const decl of st.declarationList.declarations) {
+          if (
+            ts.isIdentifier(decl.name) &&
+            decl.name.text === name &&
+            decl.initializer !== undefined &&
+            (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
+          ) {
+            return decl.initializer;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
+  let component:
+    | ts.FunctionDeclaration
+    | ts.FunctionExpression
+    | ts.ArrowFunction
+    | undefined;
+  for (const st of sf.statements) {
+    if (
+      ts.isFunctionDeclaration(st) &&
+      st.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
+    ) {
+      component = st;
+      break;
+    }
+    if (ts.isExportAssignment(st) && st.isExportEquals !== true) {
+      const expr = st.expression;
+      if (ts.isArrowFunction(expr) || ts.isFunctionExpression(expr)) component = expr;
+      else if (ts.isIdentifier(expr)) component = resolveTopLevel(expr.text);
+      break;
+    }
+  }
+  // No default export at all, or one this detector cannot resolve to a
+  // function — `compile/default-export` owns the first case and the
+  // second is not ours to guess at.
+  if (component === undefined) return null;
+
+  const body = component.body;
+  // A concise arrow body IS the returned value.
+  if (body === undefined || !ts.isBlock(body)) return null;
+
+  let returnsValue = false;
+  let jsxStatementLine: number | undefined;
+  const visit = (node: ts.Node): void => {
+    if (returnsValue) return;
+    if (ts.isReturnStatement(node)) {
+      if (node.expression !== undefined) returnsValue = true;
+      return;
+    }
+    if (
+      jsxStatementLine === undefined &&
+      ts.isExpressionStatement(node) &&
+      (ts.isJsxElement(node.expression) ||
+        ts.isJsxFragment(node.expression) ||
+        ts.isJsxSelfClosingElement(node.expression))
+    ) {
+      jsxStatementLine = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+    }
+    node.forEachChild((child) => {
+      // A helper component's own `return` is not this component's.
+      if (!isFunctionLike(child)) visit(child);
+    });
+  };
+  for (const st of body.statements) if (!isFunctionLike(st)) visit(st);
+
+  return returnsValue ? null : { jsxStatementLine };
+}
+
 /**
  * Run all tier 0 (deterministic, no-LLM) checks against component source.
  *
@@ -982,6 +1113,27 @@ export async function runTier0Checks(
     });
   }
 
+  // ── Component never returns its tree ──────────────────────
+  // The scaffold hands the model `return (` … `);` around the layout.
+  // A root-block rewrite can delete them with it, and bare JSX at
+  // statement position compiles, type-checks and renders NOTHING.
+  const neverReturns = detectComponentNeverReturns(sourceCode);
+  if (neverReturns !== null) {
+    issues.push({
+      tier: 0,
+      result: 'fail',
+      category: 'compile',
+      subcategory: 'renders-nothing',
+      severity: 'critical',
+      description:
+        neverReturns.jsxStatementLine === undefined
+          ? 'The component never returns its tree — it renders a blank frame'
+          : `The component never returns its tree: the JSX at line ${neverReturns.jsxStatementLine} sits at statement position, so it is built and thrown away and the frame renders blank`,
+      fix: 'Wrap the tree in the return the boilerplate gave you: `return (` before the root element and `);` after it.',
+      ...(neverReturns.jsxStatementLine === undefined ? {} : { line: neverReturns.jsxStatementLine }),
+    });
+  }
+
   // (Controller-View checks removed — generated components use a
   // single-function pattern.)
 

package/src/contract-context.ts

@@ -202,6 +202,19 @@ export function buildContractsContext(
         if (entry.nextStep) {
           line += `\n    Next-step hint: agent intends to call \`${entry.nextStep}\``;
         }
+        // ggui#1108: `confirm` was the one declared action field the contract
+        // renderer dropped — every other author field (label, description,
+        // example, nextStep) reaches the model and this one did not. It is
+        // rendered as INFORMATION, not as a rule: the terminal-actions section
+        // deliberately does NOT cite it, because citing it measured ZERO —
+        // two wordings, n=4 each, `save` + `confirm: true` came back armed 0/4
+        // and 0/4. The field's own doc says "whether to show confirmation
+        // BEFORE triggering", which is gravity, not one-shot-ness, and the
+        // model reads it that way. Emitted only when true, so an absent flag
+        // leaves the prompt bytes identical to before this line existed.
+        if (entry.confirm === true) {
+          line += `\n    Author flag: \`confirm\` — the author marked this action grave enough to confirm before it fires, so a second press is a mistake.`;
+        }
         return line;
       })
       .join('\n');

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

@@ -333,6 +333,64 @@ 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",
+    ),
+  ];
+}
+
 export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
   {
     id: "universal.icon_name_known",
@@ -352,6 +410,12 @@ export const UNIVERSAL_CHECKS: readonly AxisCheck[] = [
     values: ALL_RENDER_VALUES,
     run: runViewportSized,
   },
+  {
+    id: "universal.terminal_action_unguarded",
+    axis: "render",
+    values: ALL_RENDER_VALUES,
+    run: runTerminalActionUnguarded,
+  },
   {
     id: "universal.accent_text_ink",
     axis: "render",