@ggui-ai/ui-gen 0.17.0 → 0.18.0

package/dist/adapters/generation-dispatch.js

@@ -9,7 +9,7 @@ import { contentHash } from '@ggui-ai/protocol/content-hash';
 import { createRequire } from 'module';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { runSandboxed } from '@ggui-ai/sandbox';
-import ts2 from 'typescript';
+import ts6 from 'typescript';
 import path, { dirname, resolve, join, basename } from 'path';
 import { Linter } from 'eslint';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
@@ -2933,53 +2933,53 @@ var init_render_check_host = __esm({
   }
 });
 function extractWireCallSites(code) {
-  const sf = ts2.createSourceFile(
+  const sf = ts6.createSourceFile(
     "component.tsx",
     code,
-    ts2.ScriptTarget.Latest,
+    ts6.ScriptTarget.Latest,
     /*setParentNodes*/
     true,
-    ts2.ScriptKind.TSX
+    ts6.ScriptKind.TSX
   );
   const sites = [];
   function visit(node) {
-    if (ts2.isCallExpression(node)) {
+    if (ts6.isCallExpression(node)) {
       const callee = node.expression;
-      if (ts2.isIdentifier(callee)) {
+      if (ts6.isIdentifier(callee)) {
         const kind = HOOK_TO_KIND[callee.text];
         if (kind) {
           const firstArg = node.arguments[0];
-          if (firstArg && ts2.isStringLiteral(firstArg)) {
+          if (firstArg && ts6.isStringLiteral(firstArg)) {
             sites.push({ kind, name: firstArg.text });
           }
         }
       }
     }
-    ts2.forEachChild(node, visit);
+    ts6.forEachChild(node, visit);
   }
   visit(sf);
   return sites;
 }
 function extractWireImports(code) {
-  const sf = ts2.createSourceFile(
+  const sf = ts6.createSourceFile(
     "component.tsx",
     code,
-    ts2.ScriptTarget.Latest,
+    ts6.ScriptTarget.Latest,
     /*setParentNodes*/
     true,
-    ts2.ScriptKind.TSX
+    ts6.ScriptKind.TSX
   );
   const imported = /* @__PURE__ */ new Set();
   for (const stmt of sf.statements) {
-    if (!ts2.isImportDeclaration(stmt)) continue;
+    if (!ts6.isImportDeclaration(stmt)) continue;
     const moduleSpecifier = stmt.moduleSpecifier;
-    if (!ts2.isStringLiteral(moduleSpecifier)) continue;
+    if (!ts6.isStringLiteral(moduleSpecifier)) continue;
     if (moduleSpecifier.text !== "@ggui-ai/wire") continue;
     const clause = stmt.importClause;
     if (!clause) continue;
     const bindings = clause.namedBindings;
     if (!bindings) continue;
-    if (!ts2.isNamedImports(bindings)) continue;
+    if (!ts6.isNamedImports(bindings)) continue;
     for (const el of bindings.elements) {
       imported.add(el.name.text);
     }
@@ -3057,11 +3057,11 @@ var init_extract_wire_calls = __esm({
   }
 });
 function extractPropsInterface(code) {
-  const sf = ts2.createSourceFile("component.tsx", code, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  const sf = ts6.createSourceFile("component.tsx", code, ts6.ScriptTarget.Latest, true, ts6.ScriptKind.TSX);
   const props = [];
   function visitMembers(members) {
     for (const member of members) {
-      if (ts2.isPropertySignature(member) && member.name) {
+      if (ts6.isPropertySignature(member) && member.name) {
         const name = member.name.getText(sf);
         const type = member.type ? member.type.getText(sf) : "unknown";
         const optional = !!member.questionToken;
@@ -3070,17 +3070,17 @@ function extractPropsInterface(code) {
     }
   }
   function visit(node) {
-    if (ts2.isInterfaceDeclaration(node) && node.name.text === "Props") {
+    if (ts6.isInterfaceDeclaration(node) && node.name.text === "Props") {
       visitMembers(node.members);
       return;
     }
-    if (ts2.isTypeAliasDeclaration(node) && node.name.text === "Props") {
-      if (ts2.isTypeLiteralNode(node.type)) {
+    if (ts6.isTypeAliasDeclaration(node) && node.name.text === "Props") {
+      if (ts6.isTypeLiteralNode(node.type)) {
         visitMembers(node.type.members);
       }
       return;
     }
-    ts2.forEachChild(node, visit);
+    ts6.forEachChild(node, visit);
   }
   visit(sf);
   return props.length > 0 ? props : null;
@@ -3293,12 +3293,12 @@ function generateFix(code, message, sourceLine) {
   }
 }
 function parseAndStore(vfs, virtualPath, content) {
-  const sourceFile = ts2.createSourceFile(
+  const sourceFile = ts6.createSourceFile(
     virtualPath,
     content,
-    ts2.ScriptTarget.ES2020,
+    ts6.ScriptTarget.ES2020,
     true,
-    virtualPath.endsWith(".tsx") ? ts2.ScriptKind.TSX : ts2.ScriptKind.TS
+    virtualPath.endsWith(".tsx") ? ts6.ScriptKind.TSX : ts6.ScriptKind.TS
   );
   vfs.set(virtualPath, { content, sourceFile });
 }
@@ -3440,12 +3440,12 @@ function resolveModuleName(vfs, name, containingFile) {
   return { resolvedModule: void 0 };
 }
 function createVfsHost(vfs, componentCode) {
-  const componentFile = ts2.createSourceFile(
+  const componentFile = ts6.createSourceFile(
     "Component.tsx",
     componentCode,
-    ts2.ScriptTarget.ES2020,
+    ts6.ScriptTarget.ES2020,
     true,
-    ts2.ScriptKind.TSX
+    ts6.ScriptKind.TSX
   );
   const host = {
     getSourceFile(fileName) {
@@ -3500,7 +3500,7 @@ function resolved(resolvedFileName) {
     resolvedModule: {
       resolvedFileName,
       isExternalLibraryImport: true,
-      extension: ts2.Extension.Dts
+      extension: ts6.Extension.Dts
     }
   };
 }
@@ -3522,18 +3522,18 @@ async function typecheck(code, dtsMap) {
   const prefixedCode = SYNTHETIC_PREFIX + code;
   const lineOffset = SYNTHETIC_PREFIX.split("\n").length - 1;
   const host = createVfsHost(effectiveVfs, prefixedCode);
-  const program = ts2.createProgram(["Component.tsx"], COMPILER_OPTIONS, host);
-  const diagnostics = ts2.getPreEmitDiagnostics(program);
+  const program = ts6.createProgram(["Component.tsx"], COMPILER_OPTIONS, host);
+  const diagnostics = ts6.getPreEmitDiagnostics(program);
   const errors = [];
   const warnings = [];
   for (const diag of diagnostics) {
     if (diag.file && diag.file.fileName !== "Component.tsx") continue;
     if (!diag.file) continue;
-    const diagLine = ts2.getLineAndCharacterOfPosition(diag.file, diag.start ?? 0).line;
+    const diagLine = ts6.getLineAndCharacterOfPosition(diag.file, diag.start ?? 0).line;
     if (diagLine < lineOffset) continue;
-    const rawLine = diag.file ? ts2.getLineAndCharacterOfPosition(diag.file, diag.start ?? 0).line + 1 : 0;
+    const rawLine = diag.file ? ts6.getLineAndCharacterOfPosition(diag.file, diag.start ?? 0).line + 1 : 0;
     const line = Math.max(1, rawLine - lineOffset);
-    const message = ts2.flattenDiagnosticMessageText(diag.messageText, "\n");
+    const message = ts6.flattenDiagnosticMessageText(diag.messageText, "\n");
     const code_ = diag.code;
     const sourceLines = diag.file.text.split("\n");
     const sourceLine = rawLine >= 1 && rawLine <= sourceLines.length ? sourceLines[rawLine - 1]?.trim() ?? "" : "";
@@ -3580,8 +3580,8 @@ var init_type_checker = __esm({
     ]);
     vfsCache = null;
     COMPILER_OPTIONS = {
-      target: ts2.ScriptTarget.ES2020,
-      module: ts2.ModuleKind.ESNext,
+      target: ts6.ScriptTarget.ES2020,
+      module: ts6.ModuleKind.ESNext,
       // Classic React JSX mode. The synthetic prefix (SYNTHETIC_PREFIX)
       // supplies `import React from 'react'` plus a `declare global` JSX
       // namespace shim: `@types/react` v19 removed the *global* `JSX`
@@ -3589,8 +3589,8 @@ var init_type_checker = __esm({
       // for `JSX.IntrinsicElements` and the `key`/`ref` carve-out. Without
       // the shim, `<div>` degrades to `any` and every typed component
       // falsely rejects the intrinsic `key` prop.
-      jsx: ts2.JsxEmit.React,
-      moduleResolution: ts2.ModuleResolutionKind.Bundler,
+      jsx: ts6.JsxEmit.React,
+      moduleResolution: ts6.ModuleResolutionKind.Bundler,
       strict: false,
       strictNullChecks: true,
       // Catch undefined.foo() errors that cause runtime crashes
@@ -3732,17 +3732,17 @@ var init_react_linter = __esm({
   }
 });
 function stripComments(code) {
-  const scanner = ts2.createScanner(
-    ts2.ScriptTarget.Latest,
+  const scanner = ts6.createScanner(
+    ts6.ScriptTarget.Latest,
     /* skipTrivia */
     false,
-    ts2.LanguageVariant.JSX,
+    ts6.LanguageVariant.JSX,
     code
   );
   let out = "";
-  for (let token = scanner.scan(); token !== ts2.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+  for (let token = scanner.scan(); token !== ts6.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
     const text = scanner.getTokenText();
-    out += token === ts2.SyntaxKind.SingleLineCommentTrivia || token === ts2.SyntaxKind.MultiLineCommentTrivia ? text.replace(/[^\n]/g, " ") : text;
+    out += token === ts6.SyntaxKind.SingleLineCommentTrivia || token === ts6.SyntaxKind.MultiLineCommentTrivia ? text.replace(/[^\n]/g, " ") : text;
   }
   return out;
 }
@@ -3765,20 +3765,20 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode
     "Link"
   ]);
   const HANDLER_ATTRS = ["onClick", "onChange", "onPress", "onSelect"];
-  const sf = ts2.createSourceFile(
+  const sf = ts6.createSourceFile(
     "source.tsx",
     sourceCode,
-    ts2.ScriptTarget.Latest,
+    ts6.ScriptTarget.Latest,
     /* setParentNodes */
     true,
-    ts2.ScriptKind.TSX
+    ts6.ScriptKind.TSX
   );
   function tagNameText(node) {
-    return ts2.isIdentifier(node.tagName) ? node.tagName.text : void 0;
+    return ts6.isIdentifier(node.tagName) ? node.tagName.text : void 0;
   }
   function attrExpression(node, attrName) {
     for (const attr of node.attributes.properties) {
-      if (ts2.isJsxAttribute(attr) && ts2.isIdentifier(attr.name) && attr.name.text === attrName && attr.initializer !== void 0 && ts2.isJsxExpression(attr.initializer)) {
+      if (ts6.isJsxAttribute(attr) && ts6.isIdentifier(attr.name) && attr.name.text === attrName && attr.initializer !== void 0 && ts6.isJsxExpression(attr.initializer)) {
         return attr.initializer.expression;
       }
     }
@@ -3790,19 +3790,19 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode
     if (anyElementIsInteractive) return true;
     if (!TRAIT_HOST_TAGS.has(tag)) return false;
     const asExpr = attrExpression(node, "as");
-    return asExpr !== void 0 && ts2.isIdentifier(asExpr) && TRAITS_THAT_FIRE.has(asExpr.text);
+    return asExpr !== void 0 && ts6.isIdentifier(asExpr) && TRAITS_THAT_FIRE.has(asExpr.text);
   }
   function extractCalleeName(expr) {
     if (expr === void 0) return void 0;
-    if (ts2.isIdentifier(expr)) return expr.text;
-    if (ts2.isArrowFunction(expr) || ts2.isFunctionExpression(expr)) {
+    if (ts6.isIdentifier(expr)) return expr.text;
+    if (ts6.isArrowFunction(expr) || ts6.isFunctionExpression(expr)) {
       const body = expr.body;
-      if (ts2.isCallExpression(body) && ts2.isIdentifier(body.expression)) {
+      if (ts6.isCallExpression(body) && ts6.isIdentifier(body.expression)) {
         return body.expression.text;
       }
-      if (ts2.isBlock(body)) {
+      if (ts6.isBlock(body)) {
         for (const stmt of body.statements) {
-          if (ts2.isExpressionStatement(stmt) && ts2.isCallExpression(stmt.expression) && ts2.isIdentifier(stmt.expression.expression)) {
+          if (ts6.isExpressionStatement(stmt) && ts6.isCallExpression(stmt.expression) && ts6.isIdentifier(stmt.expression.expression)) {
             return stmt.expression.expression.text;
           }
         }
@@ -3814,7 +3814,7 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode
     let found;
     function walk(node) {
       if (found !== void 0) return;
-      const opening = ts2.isJsxElement(node) ? node.openingElement : ts2.isJsxSelfClosingElement(node) ? node : void 0;
+      const opening = ts6.isJsxElement(node) ? node.openingElement : ts6.isJsxSelfClosingElement(node) ? node : void 0;
       if (opening !== void 0) {
         const tag = tagNameText(opening);
         if (tag !== void 0 && (anyElementIsInteractive || INTERACTIVE_DESCENDANTS.has(tag))) {
@@ -3830,13 +3830,13 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode
           }
         }
       }
-      ts2.forEachChild(node, walk);
+      ts6.forEachChild(node, walk);
     }
-    ts2.forEachChild(outer, walk);
+    ts6.forEachChild(outer, walk);
     return found;
   }
   function visit(node) {
-    if (ts2.isJsxElement(node) && isTraitHostWithFiringAs(node.openingElement)) {
+    if (ts6.isJsxElement(node) && isTraitHostWithFiringAs(node.openingElement)) {
       const outerCallee = extractCalleeName(attrExpression(node.openingElement, "onClick")) ?? extractCalleeName(attrExpression(node.openingElement, "onPress"));
       if (outerCallee !== void 0 && bindings.has(outerCallee)) {
         const match = findMatchingInteractiveDescendant(node, outerCallee);
@@ -3857,7 +3857,7 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode
         }
       }
     }
-    ts2.forEachChild(node, visit);
+    ts6.forEachChild(node, visit);
   }
   visit(sf);
   return issues;
@@ -3876,6 +3876,63 @@ function isGadgetExportImported(source, pkg, exportName) {
   }
   return false;
 }
+function detectComponentNeverReturns(sourceCode) {
+  const sf = ts6.createSourceFile(
+    "source.tsx",
+    sourceCode,
+    ts6.ScriptTarget.Latest,
+    /* setParentNodes */
+    true,
+    ts6.ScriptKind.TSX
+  );
+  const isFunctionLike = (n) => ts6.isFunctionDeclaration(n) || ts6.isFunctionExpression(n) || ts6.isArrowFunction(n) || ts6.isMethodDeclaration(n) || ts6.isClassDeclaration(n) || ts6.isClassExpression(n);
+  function resolveTopLevel(name) {
+    for (const st of sf.statements) {
+      if (ts6.isFunctionDeclaration(st) && st.name?.text === name) return st;
+      if (ts6.isVariableStatement(st)) {
+        for (const decl of st.declarationList.declarations) {
+          if (ts6.isIdentifier(decl.name) && decl.name.text === name && decl.initializer !== void 0 && (ts6.isArrowFunction(decl.initializer) || ts6.isFunctionExpression(decl.initializer))) {
+            return decl.initializer;
+          }
+        }
+      }
+    }
+    return void 0;
+  }
+  let component;
+  for (const st of sf.statements) {
+    if (ts6.isFunctionDeclaration(st) && st.modifiers?.some((m) => m.kind === ts6.SyntaxKind.DefaultKeyword)) {
+      component = st;
+      break;
+    }
+    if (ts6.isExportAssignment(st) && st.isExportEquals !== true) {
+      const expr = st.expression;
+      if (ts6.isArrowFunction(expr) || ts6.isFunctionExpression(expr)) component = expr;
+      else if (ts6.isIdentifier(expr)) component = resolveTopLevel(expr.text);
+      break;
+    }
+  }
+  if (component === void 0) return null;
+  const body = component.body;
+  if (body === void 0 || !ts6.isBlock(body)) return null;
+  let returnsValue = false;
+  let jsxStatementLine;
+  const visit = (node) => {
+    if (returnsValue) return;
+    if (ts6.isReturnStatement(node)) {
+      if (node.expression !== void 0) returnsValue = true;
+      return;
+    }
+    if (jsxStatementLine === void 0 && ts6.isExpressionStatement(node) && (ts6.isJsxElement(node.expression) || ts6.isJsxFragment(node.expression) || ts6.isJsxSelfClosingElement(node.expression))) {
+      jsxStatementLine = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+    }
+    node.forEachChild((child) => {
+      if (!isFunctionLike(child)) visit(child);
+    });
+  };
+  for (const st of body.statements) if (!isFunctionLike(st)) visit(st);
+  return returnsValue ? null : { jsxStatementLine };
+}
 async function runTier0Checks(sourceCode, contract, buildErrors, gadgetTypes, designMode = DEFAULT_DESIGN_MODE) {
   const issues = [];
   const lines = sourceCode.split("\n");
@@ -4295,6 +4352,19 @@ ${errorDetail}`,
       fix: "Add export default function Component(props: Props) { ... }"
     });
   }
+  const neverReturns = detectComponentNeverReturns(sourceCode);
+  if (neverReturns !== null) {
+    issues.push({
+      tier: 0,
+      result: "fail",
+      category: "compile",
+      subcategory: "renders-nothing",
+      severity: "critical",
+      description: neverReturns.jsxStatementLine === void 0 ? "The component never returns its tree \u2014 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 === void 0 ? {} : { line: neverReturns.jsxStatementLine }
+    });
+  }
   if (contract) {
     try {
       const contractIssues = validateAllContracts(sourceCode, contract);
@@ -10855,6 +10925,50 @@ function runViewportSized(input) {
     )
   ];
 }
+var TERMINAL_WORDS = /* @__PURE__ */ new Set([
+  "submit",
+  "confirm",
+  "approve",
+  "schedule",
+  "reserve",
+  "book",
+  "pay",
+  "checkout",
+  "purchase",
+  "order"
+]);
+var TERMINAL_LABEL_RX = /\b(submit|confirm|approve|schedule|reserve|book|pay|checkout|purchase|place\s+order)\b/i;
+var GUARD_RX = /\b(disabled|aria-disabled)\s*=/;
+function nameWords(name) {
+  return name.split(/(?=[A-Z])|[_\-\s]+/).map((w) => w.toLowerCase()).filter((w) => w.length > 0);
+}
+function findUnguardedTerminalControls(sourceCode) {
+  if (GUARD_RX.test(sourceCode)) return [];
+  const names = /* @__PURE__ */ new Set();
+  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);
+  }
+  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) {
+  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 \u2014 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 \u2014 sending a message, adding an item \u2014 leave it armed and ignore this.',
+      "warn"
+    )
+  ];
+}
 var UNIVERSAL_CHECKS = [
   {
     id: "universal.icon_name_known",
@@ -10874,6 +10988,12 @@ var UNIVERSAL_CHECKS = [
     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",
@@ -12739,7 +12859,8 @@ type ${typeName} = ${tsType};`
     );
     const callSig = tsType === "void" ? "() => void \u2014 fire and forget" : `(data: ${tsType}) => void`;
     const toolHint = tool ? ` \u2192 nextStep: ${tool}` : "";
-    actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}`);
+    const onceHint = " \u2014 if this is meant ONCE, disable its control after it fires";
+    actionHookCalls.push(`  const ${key} = useAction<${typeName}>('${key}'); // ${callSig}${toolHint}${onceHint}`);
   }
   const streamChannels = contract?.streamSpec ?? {};
   const streamChannelEntries = Object.entries(streamChannels);
@@ -13085,12 +13206,33 @@ Rules:
 3. Default values come from the current request \u2014 so the component renders correctly standalone.
 4. Copy comes from the props. NEVER invent display text the contract does not carry \u2014 no eyebrow / kicker / overline (a \`<Text caps>\` label), no helper line, no status text, no tagline. 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.`;
-var FRAME_SIZING = `## Sizing \u2014 the frame owns the height
+var TERMINAL_ACTIONS = `## Actions the user means once
+
+A second press is a mistake only when it would make a SECOND THING HAPPEN IN THE WORLD \u2014 a second booking, a second charge, a second order, a second application sent. If pressing again would only write the SAME STATE AGAIN \u2014 saving, updating, renaming, setting a preference, toggling \u2014 nothing is duplicated and the control stays armed.
+
+Guard a control only where you have evidence, not a feeling about the verb: the request itself names a one-time commitment \u2014 "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 \u2014 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") \u2014 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 \u2014 not how final the word sounds.`;
+var FRAME_SIZING = `## Sizing \u2014 the frame owns the height and the width
 
 The host sizes the iframe; the component never sizes itself to the viewport. NEVER write \`100vh\` / \`100dvh\` / \`100svh\` (or an \`h-screen\` / \`min-h-screen\` class) as a height on any element:
 - An inline card takes its natural height. A content-sized frame is measured FROM the content, so a \`100vh\` root can never shrink and grows the frame on every re-measure.
 - Under fullscreen the frame already stretches your root to its full height. Centre inside it with flex (\`display: flex; flex-direction: column; justify-content: center\`), never with a viewport height.
-- 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 \u2014 the same composition reading differently at two sizes.
+- DO cap the reading measure inside: a column of prose is easiest to read at 60\u201370 characters, so wrap the TEXT in a \`<Container maxWidth="sm">\` (or your own \`max-width\`) and leave the root filling. A hero band, a toolbar, a table or an image then still uses the whole width, which is what makes a wide card look composed rather than padded.
+- Centre that inner column with the container's own centring, not by shrinking the root.
+- **They are two different elements.** Even when the whole card is one column of text, the root still fills and the column sits INSIDE it \u2014 \`<Box padding="lg"><Container maxWidth="sm">\u2026</Container></Box>\`, never a root that is itself the container. A centred card is centring inside a filled frame, not a shrunken frame.`;
 var COMPONENT_STRUCTURE = `## Component Structure
 
 Keep JSX nesting depth to 3\u20135 levels. When deeper, extract repeated/complex sections into helper components \u2014 named functions defined above the main Component in the same file. Helpers take data + callbacks via props; they don't own state.
@@ -13302,6 +13444,7 @@ ${axisSection}
     CONTRACT_SURFACE,
     DEFENSIVE_CODING,
     GESTURE_ROUTING,
+    TERMINAL_ACTIONS,
     FREE_GESTURE_SURFACE,
     ANTI_PATTERNS,
     CROSS_REFERENCE_RULES,
@@ -13332,11 +13475,11 @@ ${inputs.primitivesDoc}`
 }
 var VIRTUAL_DTS_PATH = "/__gadget__.d.ts";
 var EXTRACTOR_COMPILER_OPTIONS = {
-  target: ts2.ScriptTarget.ESNext,
-  module: ts2.ModuleKind.ESNext,
-  moduleResolution: ts2.ModuleResolutionKind.Bundler,
+  target: ts6.ScriptTarget.ESNext,
+  module: ts6.ModuleKind.ESNext,
+  moduleResolution: ts6.ModuleResolutionKind.Bundler,
   allowJs: false,
-  jsx: ts2.JsxEmit.ReactJSX,
+  jsx: ts6.JsxEmit.ReactJSX,
   noEmit: true,
   esModuleInterop: true,
   // skipLibCheck so an unresolvable wrapper-internal import (the
@@ -13348,31 +13491,31 @@ var EXTRACTOR_COMPILER_OPTIONS = {
 var callSignatureCache = /* @__PURE__ */ new Map();
 var componentPropsCache = /* @__PURE__ */ new Map();
 function buildExtractorContext(dtsContent, names) {
-  const sourceFile = ts2.createSourceFile(
+  const sourceFile = ts6.createSourceFile(
     VIRTUAL_DTS_PATH,
     dtsContent,
-    ts2.ScriptTarget.ESNext,
+    ts6.ScriptTarget.ESNext,
     /* setParentNodes */
     true,
-    ts2.ScriptKind.TS
+    ts6.ScriptKind.TS
   );
-  const defaultLibName = ts2.getDefaultLibFileName(EXTRACTOR_COMPILER_OPTIONS);
+  const defaultLibName = ts6.getDefaultLibFileName(EXTRACTOR_COMPILER_OPTIONS);
   const host = {
     getSourceFile(fileName) {
       if (fileName === VIRTUAL_DTS_PATH) return sourceFile;
-      const libContent = ts2.sys.readFile(
-        ts2.getDefaultLibFilePath(EXTRACTOR_COMPILER_OPTIONS).replace(
+      const libContent = ts6.sys.readFile(
+        ts6.getDefaultLibFilePath(EXTRACTOR_COMPILER_OPTIONS).replace(
           /[^/\\]+$/,
           fileName
         )
       );
       if (libContent !== void 0) {
-        return ts2.createSourceFile(
+        return ts6.createSourceFile(
           fileName,
           libContent,
-          ts2.ScriptTarget.ESNext,
+          ts6.ScriptTarget.ESNext,
           true,
-          ts2.ScriptKind.TS
+          ts6.ScriptKind.TS
         );
       }
       return void 0;
@@ -13396,14 +13539,14 @@ function buildExtractorContext(dtsContent, names) {
     },
     fileExists(f) {
       if (f === VIRTUAL_DTS_PATH) return true;
-      return ts2.sys.fileExists(f);
+      return ts6.sys.fileExists(f);
     },
     readFile(f) {
       if (f === VIRTUAL_DTS_PATH) return dtsContent;
-      return ts2.sys.readFile(f);
+      return ts6.sys.readFile(f);
     }
   };
-  const program = ts2.createProgram(
+  const program = ts6.createProgram(
     [VIRTUAL_DTS_PATH],
     EXTRACTOR_COMPILER_OPTIONS,
     host
@@ -13421,9 +13564,9 @@ function buildExtractorContext(dtsContent, names) {
   }
   const MAX_DEPTH2 = 4;
   function renderType(t, depth) {
-    const plain = () => checker.typeToString(t, void 0, ts2.TypeFormatFlags.NoTruncation);
+    const plain = () => checker.typeToString(t, void 0, ts6.TypeFormatFlags.NoTruncation);
     if (depth >= MAX_DEPTH2) return plain();
-    if ((t.getFlags() & ts2.TypeFlags.Boolean) !== 0) return "boolean";
+    if ((t.getFlags() & ts6.TypeFlags.Boolean) !== 0) return "boolean";
     if (t.isUnion()) {
       return t.types.map((member) => renderType(member, depth)).join(" | ");
     }
@@ -13437,13 +13580,13 @@ function buildExtractorContext(dtsContent, names) {
       const params = cs.getParameters().map((p) => {
         const decl = p.valueDeclaration ?? p.declarations?.[0];
         const pType = decl !== void 0 ? checker.getTypeOfSymbolAtLocation(p, decl) : checker.getDeclaredTypeOfSymbol(p);
-        const optional = decl !== void 0 && ts2.isParameter(decl) && (decl.questionToken !== void 0 || decl.initializer !== void 0);
+        const optional = decl !== void 0 && ts6.isParameter(decl) && (decl.questionToken !== void 0 || decl.initializer !== void 0);
         return `${p.getName()}${optional ? "?" : ""}: ${renderType(pType, depth + 1)}`;
       }).join(", ");
       const ret = renderType(cs.getReturnType(), depth + 1);
       return `(${params}) => ${ret}`;
     }
-    const isObject = (t.getFlags() & ts2.TypeFlags.Object) !== 0;
+    const isObject = (t.getFlags() & ts6.TypeFlags.Object) !== 0;
     const isArrayOrTuple = checker.isArrayType(t) || checker.isTupleType(t);
     const typeArgs = t.typeArguments;
     if (symbol !== void 0 && isObject && !isArrayOrTuple && !isWrapperLocal(symbol) && typeArgs !== void 0 && typeArgs.length > 0) {
@@ -13456,7 +13599,7 @@ function buildExtractorContext(dtsContent, names) {
         const body = props.map((p) => {
           const decl = p.valueDeclaration ?? p.declarations?.[0];
           const pType = decl !== void 0 ? checker.getTypeOfSymbolAtLocation(p, decl) : checker.getDeclaredTypeOfSymbol(p);
-          const optional = (p.getFlags() & ts2.SymbolFlags.Optional) !== 0;
+          const optional = (p.getFlags() & ts6.SymbolFlags.Optional) !== 0;
           return `${p.getName()}${optional ? "?" : ""}: ${renderType(pType, depth + 1)}`;
         }).join("; ");
         return `{ ${body} }`;
@@ -13471,7 +13614,7 @@ function buildExtractorContext(dtsContent, names) {
     const name = symbol.getName();
     if (!requested.has(name)) continue;
     if (signaturesByName.has(name)) continue;
-    const resolved2 = (symbol.flags & ts2.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+    const resolved2 = (symbol.flags & ts6.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
     const declarations = resolved2.getDeclarations();
     if (declarations === void 0 || declarations.length === 0) continue;
     const declaration = declarations[0];
@@ -13486,7 +13629,7 @@ function printCallSignature(sig, ctx) {
   const params = sig.getParameters().map((p) => {
     const decl = p.valueDeclaration ?? p.declarations?.[0];
     const pType = decl !== void 0 ? ctx.checker.getTypeOfSymbolAtLocation(p, decl) : ctx.checker.getDeclaredTypeOfSymbol(p);
-    const optional = decl !== void 0 && ts2.isParameter(decl) && (decl.questionToken !== void 0 || decl.initializer !== void 0);
+    const optional = decl !== void 0 && ts6.isParameter(decl) && (decl.questionToken !== void 0 || decl.initializer !== void 0);
     return `${p.getName()}${optional ? "?" : ""}: ${ctx.renderType(pType, 0)}`;
   }).join(", ");
   const ret = ctx.renderType(sig.getReturnType(), 0);
@@ -13700,6 +13843,7 @@ ${axisSection}
     CONTRACT_SURFACE,
     DEFENSIVE_CODING,
     GESTURE_ROUTING,
+    TERMINAL_ACTIONS,
     INTERACTIVE_TRAITS,
     ANTI_PATTERNS,
     CROSS_REFERENCE_RULES,
@@ -15091,7 +15235,7 @@ var HOST_CLICK_TAGS = /* @__PURE__ */ new Set(["button", "a", "div", "span", "li
 var HOST_CHANGE_TAGS = /* @__PURE__ */ new Set(["select", "input", "textarea"]);
 function findWiring(input) {
   const { sourceCode, hookName, hookArg } = input;
-  const sf = ts2.createSourceFile("Component.tsx", sourceCode, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  const sf = ts6.createSourceFile("Component.tsx", sourceCode, ts6.ScriptTarget.Latest, true, ts6.ScriptKind.TSX);
   const hookBindings = findHookBindings(sf, hookName, hookArg);
   if (hookBindings.length === 0) {
     return {
@@ -15114,7 +15258,7 @@ function findWiring(input) {
   const customPropElements = [];
   const submitButton = { found: false };
   function visit(node) {
-    if (ts2.isJsxAttribute(node) && node.initializer) {
+    if (ts6.isJsxAttribute(node) && node.initializer) {
       const attrName = node.name.getText(sf);
       const initRefs = findReferencedNames(node.initializer, callableNames);
       if (initRefs.size > 0) {
@@ -15152,19 +15296,19 @@ function findWiring(input) {
         }
       }
     }
-    if (ts2.isJsxOpeningLikeElement(node)) {
+    if (ts6.isJsxOpeningLikeElement(node)) {
       const tag = getTagName(node);
       if ((tag ?? "").toLowerCase() === "button") {
         const typeAttr = node.attributes.properties.find(
-          (p) => ts2.isJsxAttribute(p) && p.name.getText(sf) === "type"
+          (p) => ts6.isJsxAttribute(p) && p.name.getText(sf) === "type"
         );
-        if (typeAttr && ts2.isJsxAttribute(typeAttr) && typeAttr.initializer) {
+        if (typeAttr && ts6.isJsxAttribute(typeAttr) && typeAttr.initializer) {
           const v = typeAttr.initializer.getText(sf).toLowerCase();
           if (v.includes("submit")) submitButton.found = true;
         }
       }
     }
-    ts2.forEachChild(node, visit);
+    ts6.forEachChild(node, visit);
   }
   visit(sf);
   if (sawClickOnHost) {
@@ -15201,32 +15345,32 @@ function findWiring(input) {
 function findHookBindings(sf, hookName, hookArg) {
   const bindings = [];
   function visit(node) {
-    if (ts2.isVariableDeclaration(node) && node.initializer && ts2.isCallExpression(node.initializer)) {
+    if (ts6.isVariableDeclaration(node) && node.initializer && ts6.isCallExpression(node.initializer)) {
       const call = node.initializer;
       const callee = call.expression.getText(sf);
       if (callee !== hookName) {
-        ts2.forEachChild(node, visit);
+        ts6.forEachChild(node, visit);
         return;
       }
       const firstArg = call.arguments[0];
-      if (!firstArg || !ts2.isStringLiteral(firstArg)) {
-        ts2.forEachChild(node, visit);
+      if (!firstArg || !ts6.isStringLiteral(firstArg)) {
+        ts6.forEachChild(node, visit);
         return;
       }
       if (firstArg.text !== hookArg) {
-        ts2.forEachChild(node, visit);
+        ts6.forEachChild(node, visit);
         return;
       }
-      if (ts2.isIdentifier(node.name)) {
+      if (ts6.isIdentifier(node.name)) {
         bindings.push(node.name.text);
-      } else if (ts2.isObjectBindingPattern(node.name)) {
+      } else if (ts6.isObjectBindingPattern(node.name)) {
         for (const elem of node.name.elements) {
           const target = elem.name;
-          if (ts2.isIdentifier(target)) bindings.push(target.text);
+          if (ts6.isIdentifier(target)) bindings.push(target.text);
         }
       }
     }
-    ts2.forEachChild(node, visit);
+    ts6.forEachChild(node, visit);
   }
   visit(sf);
   return bindings;
@@ -15234,24 +15378,24 @@ function findHookBindings(sf, hookName, hookArg) {
 function expandAliases(sf, bindings) {
   const all = new Set(bindings);
   function visit(node) {
-    if (ts2.isVariableDeclaration(node) && node.initializer && ts2.isIdentifier(node.name)) {
+    if (ts6.isVariableDeclaration(node) && node.initializer && ts6.isIdentifier(node.name)) {
       const newName = node.name.text;
       const init = node.initializer;
-      if (ts2.isIdentifier(init) && all.has(init.text)) {
+      if (ts6.isIdentifier(init) && all.has(init.text)) {
         all.add(newName);
       }
-      if (ts2.isArrowFunction(init) || ts2.isFunctionExpression(init)) {
+      if (ts6.isArrowFunction(init) || ts6.isFunctionExpression(init)) {
         if (bodyReferences(init.body, all)) {
           all.add(newName);
         }
       }
-      if (ts2.isCallExpression(init)) {
+      if (ts6.isCallExpression(init)) {
         if (bodyReferences(init, all)) {
           all.add(newName);
         }
       }
     }
-    ts2.forEachChild(node, visit);
+    ts6.forEachChild(node, visit);
   }
   visit(sf);
   return all;
@@ -15260,11 +15404,11 @@ function bodyReferences(body, names) {
   let found = false;
   function walk(n) {
     if (found) return;
-    if (ts2.isIdentifier(n) && names.has(n.text)) {
+    if (ts6.isIdentifier(n) && names.has(n.text)) {
       found = true;
       return;
     }
-    ts2.forEachChild(n, walk);
+    ts6.forEachChild(n, walk);
   }
   walk(body);
   return found;
@@ -15272,16 +15416,16 @@ function bodyReferences(body, names) {
 function findReferencedNames(node, names) {
   const found = /* @__PURE__ */ new Set();
   function walk(n) {
-    if (ts2.isIdentifier(n) && names.has(n.text)) {
+    if (ts6.isIdentifier(n) && names.has(n.text)) {
       found.add(n.text);
     }
-    ts2.forEachChild(n, walk);
+    ts6.forEachChild(n, walk);
   }
   walk(node);
   return found;
 }
 function getTagName(el) {
-  if (ts2.isJsxOpeningLikeElement(el)) {
+  if (ts6.isJsxOpeningLikeElement(el)) {
     return el.tagName.getText();
   }
   return null;