@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/src/design-mode.ts

@@ -18,6 +18,8 @@
 //     blueprint-reuse shape, and brand-bearing color via the closed
 //     `--ggui-color-*` token manifest (no literals, no fallbacks).
 
+import type { CanvasClass } from "@ggui-ai/design/rendering";
+
 export const DESIGN_MODES = ["constrained", "free"] as const;
 
 export type DesignMode = (typeof DESIGN_MODES)[number];
@@ -38,15 +40,8 @@ export const DEFAULT_DESIGN_MODE: DesignMode = "constrained";
 // breakpoints. `canvasForViewportWidth` is monotonic in width per
 // display mode (pinned by `design-mode.test.ts`).
 
-export const CANVAS_CLASSES = [
-  "xs-chat-card",
-  "mobile-fullscreen-small",
-  "md",
-  "lg",
-  "xl",
-] as const;
-
-export type CanvasClass = (typeof CANVAS_CLASSES)[number];
+// The vocabulary itself lives in `@ggui-ai/design/rendering`, where the runtime reads it too.
+export { CANVAS_CLASSES, type CanvasClass } from "@ggui-ai/design/rendering";
 
 export interface CanvasViewport {
   readonly width: number;

package/src/evaluation/axis-checks/checks/state-merge.ts

@@ -12,6 +12,7 @@ import {
   getEntityCollections,
   getMutatedEntityCollections,
   mkIssue,
+  seedsFromProp,
 } from "../helpers.js";
 
 function runStateSeededFromProps(input: AxisCheckInput): EvalIssue[] {
@@ -21,10 +22,7 @@ function runStateSeededFromProps(input: AxisCheckInput): EvalIssue[] {
   const entities = getMutatedEntityCollections(input.contract, all);
   const issues: EvalIssue[] = [];
   for (const e of entities) {
-    const re = new RegExp(
-      `useState(?:<[^>]*>)?\\s*\\([\\s\\S]{0,400}?props\\.${e.name}\\b`,
-    );
-    if (re.test(src)) continue;
+    if (seedsFromProp(src, e.name)) continue;
     issues.push(
       mkIssue(
         "state.merge.seeded_from_props",

package/src/evaluation/axis-checks/checks/state-payload.ts

@@ -12,6 +12,7 @@ import {
   getInitialValuePropNames,
   getSubmitActions,
   mkIssue,
+  seedsFromProp,
 } from "../helpers.js";
 
 function runSubmitHookPresent(input: AxisCheckInput): EvalIssue[] {
@@ -79,34 +80,6 @@ function runStateCoversPayload(input: AxisCheckInput): EvalIssue[] {
   return issues;
 }
 
-/**
- * Whether a `useState` initializer reads `props.<name>`: directly, or through a local bound from
- * it (`const initial = normalize(props.initialProfile)` then `useState(initial.name)`, or a
- * destructure `const { name } = props.initialProfile ?? {}` then `useState(name)`). The property
- * this check guards is "form state is seeded from the prop", not a spelling: ggui#1261's Exp 011
- * cell re-seeded correctly through a normalized local, was refused, and spent a turn restoring
- * the literal form.
- */
-function seedsFromProp(src: string, name: string): boolean {
-  const propRef = `props\\??\\.${name}\\b`;
-  const initializerReads = (ref: string): boolean =>
-    new RegExp(`useState(?:<[^>]*>)?\\s*\\([\\s\\S]{0,400}?${ref}`).test(src);
-  if (initializerReads(propRef)) return true;
-  const locals = new Set<string>();
-  for (const m of src.matchAll(new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*(?::[^=]{1,80})?=\\s*[^;]{0,300}?${propRef}`, "g"))) {
-    const id = m[1];
-    if (id !== undefined) locals.add(id);
-  }
-  for (const m of src.matchAll(new RegExp(`(?:const|let|var)\\s*\\{([^}]{1,400})\\}\\s*=\\s*[^;]{0,300}?${propRef}`, "g"))) {
-    for (const part of (m[1] ?? "").split(",")) {
-      const id = part.split(":").pop()?.split("=")[0]?.trim();
-      if (id !== undefined && /^\w+$/.test(id)) locals.add(id);
-    }
-  }
-  for (const id of locals) if (initializerReads(`\\b${id}\\b`)) return true;
-  return false;
-}
-
 function runInitialValuesSeeded(input: AxisCheckInput): EvalIssue[] {
   if (input.compiledCode === null) return [];
   const src = input.sourceCode;

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

@@ -0,0 +1,197 @@
+// packages/ui-gen/src/evaluation/axis-checks/checks/tint.ts
+//
+// ggui#1846 — the categorical `tint` fill's usage rules, as WARNINGS. The kit
+// gives `Box` / `Card` eight theme-tracked steps (`tint-1` … `tint-8`) for DATA
+// categories. The rules (ggui-team-cdo's, taught in the system prompt) are a
+// property of the rendered card, and from source each can only be read by a
+// heuristic over names or JSX structure. A heuristic that FAILS loops a
+// generation that is correct but trips it, so these warn: the model sees the
+// repair line as feedback, nothing blocks, and the follow and false-fire rates
+// are measured. An out-of-range step fails through the prop's own type instead.
+//
+// Not checked here: "the same category bound to two steps in one card". Reading
+// that needs data flow, not the tag's text.
+
+import type { EvalIssue } from "../../types-public.js";
+import type { AxisCheck, AxisCheckInput } from "../types.js";
+import { mkIssue } from "../helpers.js";
+
+const ALL_RENDER_VALUES = [
+  "static", "list", "grid", "spatial", "timeline", "chart", "master-detail",
+] as const;
+
+/** One tinted `Box` / `Card`: the tag, the `tint` value's source text, and the JSX between its open and close tags. */
+export interface TintedElement {
+  readonly tag: "Box" | "Card";
+  readonly tint: string;
+  /** The JSX between the open and close tag; empty when self-closing. */
+  readonly inner: string;
+  /** For a self-closing element, its following siblings up to the next close tag (a swatch's label); else empty. */
+  readonly next: string;
+}
+
+interface OpenTag {
+  readonly attrs: string;
+  readonly end: number;
+  readonly selfClosing: boolean;
+}
+
+/**
+ * Read a JSX open tag whose `<Name` starts at `from`. Braces and string
+ * literals are skipped as units, so an `onClick={() => …}` arrow does not end
+ * the tag the way a `[^<>]` pattern would.
+ */
+function scanOpenTag(src: string, from: number, nameLength: number): OpenTag | null {
+  let depth = 0;
+  let quote = "";
+  for (let i = from + 1 + nameLength; i < src.length; i++) {
+    const ch = src[i];
+    if (quote !== "") {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = "";
+    } else if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+    } else if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+    } else if (ch === ">" && depth === 0) {
+      const attrs = src.slice(from + 1 + nameLength, i);
+      return { attrs, end: i + 1, selfClosing: attrs.trimEnd().endsWith("/") };
+    }
+  }
+  return null;
+}
+
+/** The value of a top-level `tint=` attribute, braces or quotes included; null when absent. */
+function readTintAttr(attrs: string): string | null {
+  let depth = 0;
+  let quote = "";
+  for (let i = 0; i < attrs.length; i++) {
+    const ch = attrs[i];
+    if (quote !== "") {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth++;
+    else if (ch === "}") depth--;
+    else if (depth === 0 && /\s/.test(attrs[i - 1] ?? " ")) {
+      const m = /^tint\s*=\s*/.exec(attrs.slice(i));
+      if (m === null) continue;
+      const v = i + m[0].length;
+      const open = attrs[v];
+      if (open === '"' || open === "'") {
+        const close = attrs.indexOf(open, v + 1);
+        return close < 0 ? null : attrs.slice(v, close + 1);
+      }
+      if (open !== "{") return null;
+      let d = 0;
+      for (let j = v; j < attrs.length; j++) {
+        if (attrs[j] === "{") d++;
+        else if (attrs[j] === "}" && --d === 0) return attrs.slice(v, j + 1);
+      }
+      return null;
+    }
+  }
+  return null;
+}
+
+/** Every tinted `Box` / `Card` in the source, with its inner JSX (empty when self-closing). */
+export function findTintedElements(sourceCode: string): TintedElement[] {
+  const found: TintedElement[] = [];
+  for (const m of sourceCode.matchAll(/<(Box|Card)\b/g)) {
+    const tag = m[1] === "Card" ? "Card" : "Box";
+    const from = m.index ?? 0;
+    const open = scanOpenTag(sourceCode, from, tag.length);
+    if (open === null) continue;
+    const tint = readTintAttr(open.attrs);
+    if (tint === null) continue;
+    if (open.selfClosing) {
+      const close = sourceCode.indexOf("</", open.end);
+      found.push({ tag, tint, inner: "", next: sourceCode.slice(open.end, close < 0 ? sourceCode.length : close) });
+      continue;
+    }
+    // Walk to the matching close tag, counting nested opens of the same name.
+    const tagRx = new RegExp(`<(/?)${tag}\\b`, "g");
+    tagRx.lastIndex = open.end;
+    let depth = 1;
+    let end = sourceCode.length;
+    for (let t = tagRx.exec(sourceCode); t !== null; t = tagRx.exec(sourceCode)) {
+      if (t[1] === "/") {
+        if (--depth === 0) {
+          end = t.index;
+          break;
+        }
+        continue;
+      }
+      const nested = scanOpenTag(sourceCode, t.index, tag.length);
+      if (nested === null) break;
+      tagRx.lastIndex = nested.end;
+      if (!nested.selfClosing) depth++;
+    }
+    found.push({ tag, tint, inner: sourceCode.slice(open.end, end), next: "" });
+  }
+  return found;
+}
+
+const STATE_WORD_RX = /\b(status|state|isLive|live|draft|signal|error|success|warning|danger|isActive|active|selected|isSelected|online|offline|pending|loading|disabled)\b/i;
+
+/** Text a reader sees inside the cell: a text primitive, a JSX expression child, or literal JSX text. */
+function hasWords(inner: string): boolean {
+  if (/<(Text|Heading|Label|Badge|Caption|Link)\b/.test(inner)) return true;
+  if (/\{[^{}]+\}/.test(inner.replace(/\b[a-zA-Z]+=\{[^{}]*\}/g, ""))) return true;
+  return />\s*[^<>{}\s][^<>{}]*</.test(`>${inner}<`);
+}
+
+function runTintStateBound(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const bound = findTintedElements(input.sourceCode).filter((e) => e.tint.startsWith("{") && STATE_WORD_RX.test(e.tint));
+  if (bound.length === 0) return [];
+  return [
+    mkIssue(
+      "universal.tint_state_bound",
+      `\`tint\` reads as bound to a state (${bound.map((e) => `\`${e.tint}\``).join(", ")}) — tints are for data categories, never for state.`,
+      "A status takes live, draft or signal, not a tint. Keep `tint` for a data category (series, lane, kind, group), and show state with its own props.",
+      "warn",
+    ),
+  ];
+}
+
+function runTintCategoryInWords(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  const tinted = findTintedElements(input.sourceCode);
+  if (tinted.length === 0) return [];
+  if (/\blegend\b/i.test(input.sourceCode)) return [];
+  if (tinted.every((e) => hasWords(e.inner) || hasWords(e.next))) return [];
+  return [
+    mkIssue(
+      "universal.tint_category_in_words",
+      "A tinted cell carries no words, and the card has no legend — colour is the only way to tell its category.",
+      "Give this cell a label, or add a legend to the card. The category is always also in words.",
+      "warn",
+    ),
+  ];
+}
+
+const MUTED_TONE_RX = /\btone\s*=\s*["'](subtle|muted)["']/;
+
+function runTintMutedText(input: AxisCheckInput): EvalIssue[] {
+  if (input.compiledCode === null) return [];
+  if (!findTintedElements(input.sourceCode).some((e) => MUTED_TONE_RX.test(e.inner))) return [];
+  return [
+    mkIssue(
+      "universal.tint_muted_text",
+      'Muted text (`tone="subtle"` / `tone="muted"`) sits on a tint — it can read under 4.5:1 there.',
+      "Text on a tint is the theme's ink only, one short line (a label, a symbol, a value). Put secondary or muted text beside the cell or in the legend.",
+      "warn",
+    ),
+  ];
+}
+
+export const TINT_CHECKS: readonly AxisCheck[] = [
+  { id: "universal.tint_state_bound", axis: "render", values: ALL_RENDER_VALUES, run: runTintStateBound },
+  { id: "universal.tint_category_in_words", axis: "render", values: ALL_RENDER_VALUES, run: runTintCategoryInWords },
+  { id: "universal.tint_muted_text", axis: "render", values: ALL_RENDER_VALUES, run: runTintMutedText },
+];

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

@@ -411,6 +411,127 @@ export function isMultiStepPrompt(prompt: string): boolean {
 // Issue factory
 // =============================================================================
 
+/**
+ * Whether a `useState` initializer reads `props.<name>`: directly, or through a local bound from
+ * it (`const initial = normalize(props.initialProfile)` then `useState(initial.name)`, or a
+ * destructure `const { name } = props.initialProfile ?? {}` then `useState(name)`). The property
+ * this check guards is "form state is seeded from the prop", not a spelling: ggui#1261's Exp 011
+ * cell re-seeded correctly through a normalized local, was refused, and spent a turn restoring
+ * the literal form. ggui#1869: a nested generic (`useState<Array<Task>>(…)`), `props?.`,
+ * destructured props and destructured component parameters are all correct seeding too, and
+ * `state.merge.seeded_from_props` — a FAIL — refused them.
+ */
+export function seedsFromProp(src: string, name: string): boolean {
+  const propRef = `props\\??\\.${name}\\b`;
+  const inits = useStateInitializers(src);
+  const anyInitReads = (rx: RegExp): boolean => inits.some((t) => rx.test(t));
+  if (anyInitReads(new RegExp(`\\b${propRef}`))) return true;
+  const locals = new Set<string>();
+  for (const m of src.matchAll(new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*(?::[^=]{1,80})?=\\s*[^;]{0,300}?\\b${propRef}`, "g"))) {
+    const id = m[1];
+    if (id !== undefined) locals.add(id);
+  }
+  // `const { a, b } = props.<name> ?? {}` — every name bound reads the prop.
+  for (const m of src.matchAll(new RegExp(`(?:const|let|var)\\s*\\{([^}]{1,400})\\}\\s*=\\s*[^;]{0,300}?\\b${propRef}`, "g"))) {
+    for (const part of (m[1] ?? "").split(",")) {
+      const id = part.split(":").pop()?.split("=")[0]?.trim();
+      if (id !== undefined && /^\w+$/.test(id)) locals.add(id);
+    }
+  }
+  // `const { <name>: alias } = props` and `export default function Component({ <name>: alias }: Props)` — only the
+  // binding of <name>, and only the component's own parameter (a helper's destructured parameter is not its props).
+  const fromProps = /(?:const|let|var)\s*\{([^}]{1,400})\}\s*(?::[^=]{1,200})?=\s*props\b(?!\s*\??\.)|export\s+default\s+function\s*\w*\s*\(\s*\{([^}]{1,400})\}/g;
+  for (const m of src.matchAll(fromProps)) {
+    for (const part of (m[1] ?? m[2] ?? "").split(",")) {
+      const [key, alias] = part.split(":");
+      if (key?.split("=")[0]?.trim() !== name) continue;
+      const id = (alias ?? key).split("=")[0]?.trim();
+      if (id !== undefined && /^\w+$/.test(id)) locals.add(id);
+    }
+  }
+  for (const id of locals) if (anyInitReads(new RegExp(`\\b${id}\\b`))) return true;
+  return seedsContextSlotFromProp(src, [new RegExp(`\\b${propRef}`), ...[...locals].map((id) => new RegExp(`\\b${id}\\b`))]);
+}
+
+/**
+ * ggui#1869 — a generated context slot is seeded without any `useState`. The boilerplate
+ * declares each slot as `const [value, setValue] = useGguiContext<T>('key')`, the runtime owns
+ * its state, and the hook takes no initial value, so a form built on slots can only pre-fill in
+ * two ways, and both count:
+ * - an effect calls a slot setter with an argument that reads the prop
+ *   (`useEffect(() => { if (p.name && !name) setName(p.name); }, [props.initialProfile])`);
+ * - a slot's value falls back to the prop (`const nameValue = name ?? props.initialProfile?.name`).
+ * A setter called from an event handler is not seeding (it runs on a click, not on mount), and a
+ * prop read that is merely near a slot is not one either.
+ */
+function seedsContextSlotFromProp(src: string, readsProp: readonly RegExp[]): boolean {
+  const reads = (text: string): boolean => readsProp.some((rx) => rx.test(text));
+  const values: string[] = [];
+  const setters: string[] = [];
+  for (const m of src.matchAll(/(?:const|let|var)\s*\[\s*(\w+)\s*,\s*(\w+)\s*\]\s*=\s*useGguiContext\b/g)) {
+    if (m[1] !== undefined) values.push(m[1]);
+    if (m[2] !== undefined) setters.push(m[2]);
+  }
+  if (values.length === 0) return false;
+  for (const v of values) {
+    for (const m of src.matchAll(new RegExp(`(?<![.\\w$])${v}\\s*\\?\\?\\s*([^;\\n]{1,200})`, "g"))) {
+      if (reads(m[1] ?? "")) return true;
+    }
+  }
+  for (const body of callArguments(src, /\buse(?:Layout)?Effect\b/g)) {
+    for (const setter of setters) {
+      for (const arg of callArguments(body, new RegExp(`\\b${setter}\\b`, "g"))) if (reads(arg)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The argument text of every `useState(...)` call. A type argument is skipped with its angle
+ * brackets balanced (`useState<Record<string, Task[]>>(…)`; an arrow's `=>` inside it is not a
+ * close), and the argument runs to its matching paren, string literals skipped as units.
+ */
+function useStateInitializers(src: string): string[] {
+  return callArguments(src, /\buseState\b/g);
+}
+
+/**
+ * The argument text of every call to a name `callee` matches (a global regex). A type argument is
+ * skipped with its angle brackets balanced, and the argument runs to its matching paren, string
+ * literals skipped as units. A match not followed by `(` is not a call and is skipped.
+ */
+function callArguments(src: string, callee: RegExp): string[] {
+  const out: string[] = [];
+  for (const m of src.matchAll(callee)) {
+    let i = (m.index ?? 0) + m[0].length;
+    while (/\s/.test(src[i] ?? "")) i++;
+    if (src[i] === "<") {
+      let depth = 0;
+      for (; i < src.length; i++) {
+        if (src[i] === "<") depth++;
+        else if (src[i] === ">" && src[i - 1] !== "=" && --depth === 0) break;
+      }
+      i++;
+      while (/\s/.test(src[i] ?? "")) i++;
+    }
+    if (src[i] !== "(") continue;
+    const start = i + 1;
+    let depth = 0;
+    let quote = "";
+    for (; i < src.length; i++) {
+      const ch = src[i];
+      if (quote !== "") {
+        if (ch === "\\") i++;
+        else if (ch === quote) quote = "";
+      } else if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+      else if (ch === "(") depth++;
+      else if (ch === ")" && --depth === 0) break;
+    }
+    out.push(src.slice(start, i));
+  }
+  return out;
+}
+
 export function mkIssue(
   subcategory: string,
   description: string,

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

@@ -5,6 +5,7 @@
 
 import type { AxisCheck } from "./types.js";
 import { UNIVERSAL_CHECKS } from "./checks/universal.js";
+import { TINT_CHECKS } from "./checks/tint.js";
 import { STATE_MERGE_CHECKS } from "./checks/state-merge.js";
 import { STATE_UI_AFFORDANCE_CHECKS } from "./checks/state-ui-affordance.js";
 import { REALTIME_CHECKS } from "./checks/realtime.js";
@@ -16,6 +17,7 @@ import { EXTRA_CHECKS } from "./extras.js";
 
 export const REGISTRY: readonly AxisCheck[] = [
   ...UNIVERSAL_CHECKS,
+  ...TINT_CHECKS,
   ...STATE_MERGE_CHECKS,
   ...STATE_UI_AFFORDANCE_CHECKS,
   ...REALTIME_CHECKS,