@ggui-ai/ui-gen 0.17.0 → 0.19.0

package/dist/harness/types-public.d.ts

@@ -2,7 +2,7 @@ import * as _ggui_ai_protocol from '@ggui-ai/protocol';
 import { JsonValue, DataContract, JsonObject, GadgetDescriptor } from '@ggui-ai/protocol';
 import { G as GenerationProfileInput } from '../styling-profile-CxfvV48g.js';
 import { C as Classification } from '../axes-CzLEMDeB.js';
-import { E as EvalIssue, R as RuntimeProbeStatus, A as AxisCheck, c as EvalTier } from '../types-public-DVSssdc-.js';
+import { E as EvalIssue, R as RuntimeProbeStatus, A as AxisCheck, c as EvalTier } from '../types-public-DKR_h70H.js';
 import { LLMToolDef } from '../llm.js';
 import { H as HarnessFragment, a as CacheTier } from '../types-BOvHNG7K.js';
 import { ProcessMode, HarnessPolicy } from '../policy.js';
@@ -365,6 +365,13 @@ 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;
     readonly how: HowLeg;

package/dist/harness/types-public.js

@@ -65,6 +65,61 @@ function truncateSourceForTrace(source) {
 function newValidatorTraceId() {
   return Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
 }
+
+// src/design-mode.ts
+var DEFAULT_DESIGN_MODE = "constrained";
+function canvasDisplayModeForShell(shell) {
+  return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
+}
+function canvasForRendering(shellType, screen) {
+  const shell = shellType ?? "fullscreen";
+  if (canvasDisplayModeForShell(shell) === "inline") return "xs-chat-card";
+  if (shell === "spatial") return "md";
+  switch (screen ?? "universal") {
+    case "mobile":
+      return "mobile-fullscreen-small";
+    case "tablet":
+      return "md";
+    default:
+      return "lg";
+  }
+}
+var CANVAS_DESCRIPTORS = {
+  "xs-chat-card": {
+    label: "extra-small chat card",
+    minWidthPx: 320,
+    maxWidthPx: 480,
+    host: "an inline card inside a chat message bubble \u2014 the host draws the card border, shadow and rounded corners; the component fills the bubble width and takes its natural height"
+  },
+  "mobile-fullscreen-small": {
+    label: "small mobile fullscreen",
+    minWidthPx: 320,
+    maxWidthPx: 599,
+    host: "a phone-sized viewport the component owns edge to edge \u2014 single column, touch targets at least 44px, the component manages its own scroll"
+  },
+  md: {
+    label: "medium panel",
+    minWidthPx: 600,
+    maxWidthPx: 1023,
+    host: "a tablet viewport or a floating panel (spatial / picture-in-picture) \u2014 one or two columns, medium density"
+  },
+  lg: {
+    label: "large fullscreen",
+    minWidthPx: 1024,
+    maxWidthPx: 1439,
+    host: "a desktop viewport the component owns edge to edge \u2014 multi-column layouts, hover states and pointer interactions are available"
+  },
+  xl: {
+    label: "extra-large fullscreen",
+    minWidthPx: 1440,
+    maxWidthPx: 1920,
+    host: "a wide desktop viewport the component owns edge to edge \u2014 cap content width or use the extra room deliberately; never stretch a single column across the whole width"
+  }
+};
+function describeCanvas(canvas) {
+  const d = CANVAS_DESCRIPTORS[canvas];
+  return `This component renders on the \`${canvas}\` canvas (${d.label}): ${d.minWidthPx}\u2013${d.maxWidthPx}px wide, ${d.host}. Design for the whole range \u2014 the host may size the iframe anywhere inside it, and the host owns the height: size to your content, never to the viewport.`;
+}
 function axisCheckTraceEnabled() {
   return process.env["GGUI_AXIS_CHECK_TRACE"] === "1";
 }
@@ -330,7 +385,9 @@ function traceFacts(input) {
     designMode: input.designMode ?? "constrained",
     classification: input.classification.vector,
     propsSpecKeys: Object.keys(propsSpec ?? {}),
-    propsSpecPropertyKeys: Object.keys(propsSpec?.properties ?? {})
+    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 !== void 0 ? { canvas: input.canvas } : {}
   };
 }
 
@@ -368,7 +425,9 @@ async function runCheck(input) {
     contract,
     originalPrompt: prompt,
     classification: harness.classification,
-    designMode: harness.designMode
+    designMode: harness.designMode,
+    // ggui#1117: the canvas the harness was built for, when it has one — never a default.
+    ...harness.canvas !== void 0 ? { canvas: harness.canvas } : {}
   };
   const axisRun = runGatedAxisChecks(check.axisChecks, axisInput);
   issues.push(...axisRun.issues);
@@ -984,63 +1043,6 @@ function compose(classification) {
     fragments: matched
   };
 }
-
-// src/design-mode.ts
-var DEFAULT_DESIGN_MODE = "constrained";
-function canvasDisplayModeForShell(shell) {
-  return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
-}
-function canvasForRendering(shellType, screen) {
-  const shell = shellType ?? "fullscreen";
-  if (canvasDisplayModeForShell(shell) === "inline") return "xs-chat-card";
-  if (shell === "spatial") return "md";
-  switch (screen ?? "universal") {
-    case "mobile":
-      return "mobile-fullscreen-small";
-    case "tablet":
-      return "md";
-    default:
-      return "lg";
-  }
-}
-var CANVAS_DESCRIPTORS = {
-  "xs-chat-card": {
-    label: "extra-small chat card",
-    minWidthPx: 320,
-    maxWidthPx: 480,
-    host: "an inline card inside a chat message bubble \u2014 the host draws the card border, shadow and rounded corners; the component fills the bubble width and takes its natural height"
-  },
-  "mobile-fullscreen-small": {
-    label: "small mobile fullscreen",
-    minWidthPx: 320,
-    maxWidthPx: 599,
-    host: "a phone-sized viewport the component owns edge to edge \u2014 single column, touch targets at least 44px, the component manages its own scroll"
-  },
-  md: {
-    label: "medium panel",
-    minWidthPx: 600,
-    maxWidthPx: 1023,
-    host: "a tablet viewport or a floating panel (spatial / picture-in-picture) \u2014 one or two columns, medium density"
-  },
-  lg: {
-    label: "large fullscreen",
-    minWidthPx: 1024,
-    maxWidthPx: 1439,
-    host: "a desktop viewport the component owns edge to edge \u2014 multi-column layouts, hover states and pointer interactions are available"
-  },
-  xl: {
-    label: "extra-large fullscreen",
-    minWidthPx: 1440,
-    maxWidthPx: 1920,
-    host: "a wide desktop viewport the component owns edge to edge \u2014 cap content width or use the extra room deliberately; never stretch a single column across the whole width"
-  }
-};
-function describeCanvas(canvas) {
-  const d = CANVAS_DESCRIPTORS[canvas];
-  return `This component renders on the \`${canvas}\` canvas (${d.label}): ${d.minWidthPx}\u2013${d.maxWidthPx}px wide, ${d.host}. Design for the whole range \u2014 the host may size the iframe anywhere inside it, and the host owns the height: size to your content, never to the viewport.`;
-}
-
-// src/boilerplate/render.ts
 var __dirname$1 = dirname(fileURLToPath(import.meta.url));
 var TEMPLATE_DIRS = [
   resolve(__dirname$1, "templates"),
@@ -1312,7 +1314,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);
@@ -1645,14 +1648,35 @@ Rules:
 1. All request-specific data \u2192 props with defaults. City names, tickers, user names, dates, counts.
 2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
 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.
+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. **Do NOT add a caps label above the heading** \u2014 not \`<Text caps>LET'S BEGIN</Text>\`, not \`WELCOME\`, not a section kicker like \`GETTING STARTED\` or \`OVERVIEW\` \u2014 UNLESS a prop supplies that exact text (\`<Text caps>{props.section}</Text>\`). When the request asks for a heading and a line, render the heading and the line and NOTHING above the heading. 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, and a caps eyebrow you wrote is the most common form of it.
 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.
@@ -1864,6 +1888,7 @@ ${axisSection}
     CONTRACT_SURFACE,
     DEFENSIVE_CODING,
     GESTURE_ROUTING,
+    TERMINAL_ACTIONS,
     FREE_GESTURE_SURFACE,
     ANTI_PATTERNS,
     CROSS_REFERENCE_RULES,
@@ -2262,6 +2287,7 @@ ${axisSection}
     CONTRACT_SURFACE,
     DEFENSIVE_CODING,
     GESTURE_ROUTING,
+    TERMINAL_ACTIONS,
     INTERACTIVE_TRAITS,
     ANTI_PATTERNS,
     CROSS_REFERENCE_RULES,
@@ -2469,7 +2495,7 @@ Don't render text-only metrics. A weather widget without a sun/cloud, a stock ca
 </Row>
 \`\`\`
 
-Use \`<Icon name="..." />\` for line icons \u2014 ONLY the curated Lucide subset renders (call \`get_available_icons\` for the exact kebab-case names; a name outside it renders an empty box and fails the check); emoji directly for status/weather/mood. Both are valid. For per-stat tiny accents, use a small icon next to the label.
+Use \`<Icon name="..." />\` for line icons \u2014 ONLY the design system's curated set renders (~200 kebab-case Lucide names); a name OUTSIDE it renders an empty box and fails the check. On a single-pass render you cannot look the set up, so use ONLY a name you are sure is in it. Safe common names: \`check\` \`x\` \`plus\` \`minus\` \`search\` \`settings\` \`user\` \`users\` \`calendar\` \`clock\` \`arrow-right\` \`arrow-left\` \`chevron-right\` \`chevron-down\` \`trash-2\` \`edit\` \`info\` \`alert-circle\` \`bell\` \`home\` \`file\` \`file-text\` \`star\` \`heart\` \`mail\` \`send\` \`download\` \`upload\` \`external-link\` \`filter\` \`check-circle\`. The numbered variants (\`edit-2\`, \`edit-3\`) and synonyms (\`pencil\`, \`pen\`, \`trash\`, \`x-circle\`) are NOT in the set \u2014 use \`edit\` and \`trash-2\`. If the icon you want is not clearly one of these, OMIT it: a card with no icon beats one with an empty box. Emoji render directly for status/weather/mood. For per-stat tiny accents, use a small icon next to the label.
 
 ### Spacing \u2014 generosity beats compactness
 
@@ -2856,6 +2882,7 @@ function createHarness(input) {
     name,
     classification,
     designMode,
+    ...input.canvas !== void 0 ? { canvas: input.canvas } : {},
     ...input.profile !== void 0 ? { profile: input.profile } : {},
     how,
     what,