@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/tools/ui-surface/visual-validation.ts

@@ -0,0 +1,787 @@
+/**
+ * Validation for the `visual` ui_show surface: a self-contained HTML fragment
+ * rendered inside a sandboxed frame.
+ *
+ * The frame has no network access and injects a fixed vocabulary of design
+ * tokens on `:root`, so an external sub-resource silently never loads and a
+ * `var()` to
+ * anything outside that vocabulary resolves to nothing. Both failures render a
+ * blank or unthemed widget with no error anywhere, so they are caught here and
+ * reported as teaching errors the model can act on before the surface is ever
+ * emitted.
+ */
+
+/**
+ * Upper bound on fragment size. Sized to what one model response can emit
+ * with room to spare: a fragment past this cannot be produced in a single
+ * ui_show call, so the turn burns its output budget and renders nothing.
+ */
+const MAX_HTML_CHARS = 24000;
+
+const RAMP_STEPS = [
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "950",
+] as const;
+
+/** Neutral ramps carry an extra lightest step; the accents start at 100. */
+const NEUTRAL_PALETTES = ["moss", "stone"] as const;
+const ACCENT_PALETTES = ["forest", "emerald", "danger", "amber"] as const;
+
+const PALETTE_PROPERTIES: readonly string[] = [
+  ...NEUTRAL_PALETTES.flatMap((palette) =>
+    ["50", ...RAMP_STEPS].map((step) => `--color-${palette}-${step}`),
+  ),
+  ...ACCENT_PALETTES.flatMap((palette) =>
+    RAMP_STEPS.map((step) => `--color-${palette}-${step}`),
+  ),
+];
+
+/**
+ * The CSS custom properties that exist inside a widget frame. The host injects
+ * exactly these onto `:root` of the sandboxed iframe.
+ *
+ * Mirrors `WIDGET_TOKEN_PROPERTIES` in
+ * `clients/web/src/utils/widget-tokens.ts` — the two must change together.
+ */
+export const WIDGET_TOKEN_PROPERTIES: readonly string[] = [
+  // Surfaces
+  "--surface-base",
+  "--surface-lift",
+  "--surface-overlay",
+  "--surface-active",
+  "--surface-hover",
+  "--surface-sunken",
+  // Content
+  "--content-default",
+  "--content-emphasised",
+  "--content-secondary",
+  "--content-tertiary",
+  "--content-quiet",
+  "--content-strong",
+  "--content-faint",
+  "--content-disabled",
+  "--content-inset",
+  // Borders
+  "--border-base",
+  "--border-subtle",
+  "--border-element",
+  "--border-hover",
+  "--border-disabled",
+  "--border-active",
+  // System / status
+  "--system-positive-strong",
+  "--system-positive-weak",
+  "--system-negative-strong",
+  "--system-negative-weak",
+  "--system-negative-hover",
+  "--system-mid-strong",
+  "--system-mid-weak",
+  "--system-info-strong",
+  "--system-info-weak",
+  // Fonts
+  "--font-sans",
+  "--font-mono",
+  "--font-serif",
+  // Radius
+  "--radius-xs",
+  "--radius-sm",
+  "--radius-md",
+  "--radius-lg",
+  "--radius-xl",
+  "--radius-xxl",
+  "--radius-pill",
+  // Palettes
+  ...PALETTE_PROPERTIES,
+];
+
+/** Lookup form of {@link WIDGET_TOKEN_PROPERTIES}. */
+const WIDGET_TOKEN_NAMES: ReadonlySet<string> = new Set(
+  WIDGET_TOKEN_PROPERTIES,
+);
+
+/**
+ * Complete vocabulary, quoted back to the model when a fragment references a
+ * variable that does not exist. Enumerating every non-palette name (they are
+ * short) lets the first retry succeed instead of the model guessing plausible
+ * names or re-reading the skill.
+ */
+const TOKEN_FAMILY_SUMMARY =
+  WIDGET_TOKEN_PROPERTIES.filter((name) => !name.startsWith("--color-")).join(
+    ", ",
+  ) +
+  ", and the palette ramps --color-<moss|stone>-<50-950> and --color-<forest|emerald|danger|amber>-<100-950>";
+
+/**
+ * Sub-resource loads the sandbox blocks outright. Catching them here turns a
+ * silently blank widget into an actionable error.
+ */
+const EXTERNAL_RESOURCE_PATTERNS: { pattern: RegExp; what: string }[] = [
+  { pattern: /<script\b[^>]*\bsrc\s*=/i, what: "a <script src=...> tag" },
+  {
+    pattern: /<link\b[^>]*\bstylesheet\b/i,
+    what: "a <link rel=stylesheet> tag",
+  },
+  { pattern: /@import\b/i, what: "a CSS @import rule" },
+];
+
+/** Every `var(--name)` reference in the fragment. */
+const VAR_REFERENCE_PATTERN = /var\(\s*(--[a-zA-Z0-9-]+)/g;
+
+/** Every `--name:` declaration, i.e. properties the fragment defines itself. */
+const CUSTOM_PROPERTY_DECLARATION_PATTERN = /(--[a-zA-Z0-9-]+)\s*:/g;
+
+/** Properties the fragment sets from script: `setProperty('--name', …)`. */
+const SET_PROPERTY_DECLARATION_PATTERN =
+  /setProperty\(\s*["'](--[a-zA-Z0-9-]+)["']/g;
+
+/**
+ * Fragments legitimately carry `#`-prefixed identifiers that are not colours:
+ * SVG paint and filter references, in-page anchors, and numeric character
+ * references. Removing them before the colour scan keeps the check unambiguous.
+ */
+const NON_COLOR_HASH_PATTERNS: RegExp[] = [
+  /url\(\s*['"]?#[^)]*\)/gi,
+  /href\s*=\s*["']#[^"']*["']/gi,
+  /&#x?[0-9a-fA-F]+;/g,
+];
+
+/** `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`. */
+const HEX_TOKEN_PATTERN = /#([0-9a-fA-F]+)\b/g;
+const HEX_COLOR_LENGTHS = new Set([3, 4, 6, 8]);
+
+/** Functional colour notations whose first argument is a literal number. */
+const FUNCTIONAL_COLOR_PATTERN =
+  /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch)\(\s*(?:\d|\.\d|-\d)[^)]*\)/gi;
+
+/** How many offending values a teaching error quotes back. */
+const MAX_QUOTED_PROBLEMS = 5;
+
+/** Every root `<svg …>` open tag. Nested `<svg>` is not a thing we author. */
+const SVG_OPEN_TAG_PATTERN = /<svg\b[^>]*>/gi;
+
+const VIEWBOX_ATTRIBUTE_PATTERN = /\bviewBox\s*=/i;
+
+/** A `width`/`height` attribute whose value is a bare or `px` pixel count. */
+const SVG_PIXEL_SIZE_PATTERN =
+  /\b(width|height)\s*=\s*["'](\d+(?:\.\d+)?)(px)?["']/gi;
+
+/**
+ * Widest an `<svg>` can be sized in pixels before it overruns the frame. The
+ * container gives a visual about 660px of usable width, and the drawing
+ * conventions lay out against a 680-unit canvas; anything past that is only
+ * safe as a viewBox, which scales.
+ */
+const MAX_SVG_PIXEL_SIZE = 680;
+
+/**
+ * The fix for an unscalable `<svg>`, quoted verbatim so the retry lands in one
+ * call rather than guessing at a smaller pixel width.
+ */
+const VIEWBOX_FIX =
+  'Give the root svg a viewBox="0 0 W H" (W and H are the drawing\'s own coordinate extent, W 680 by convention) plus width="100%", and remove any fixed pixel width and height. ' +
+  "A viewBox is what makes a drawing scale to whatever width the frame has; a pixel-sized svg keeps its size and is silently clipped at the right edge, with no scrollbar and nothing on screen to say content is missing.";
+
+/** `<rect>` open tags, the one shape whose extent is exact from its attributes. */
+const SVG_RECT_TAG_PATTERN = /<rect\b[^>]*>/gi;
+
+/** Numbers of a `viewBox="minX minY width height"` value. */
+const VIEWBOX_VALUE_PATTERN =
+  /\bviewBox\s*=\s*["']\s*(-?[\d.]+)[\s,]+(-?[\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i;
+
+/** Sub-pixel slack, so a rounded coordinate is not reported as an overrun. */
+const VIEWBOX_BOUNDS_TOLERANCE = 0.5;
+
+function numericAttribute(tag: string, name: string): number | undefined {
+  const match = new RegExp(`\\b${name}\\s*=\\s*["'](-?[\\d.]+)`, "i").exec(tag);
+  if (!match) {
+    return undefined;
+  }
+  const value = Number(match[1]);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * Shapes drawn outside their own `viewBox`. An SVG clips at the viewBox edge,
+ * so a node placed past it is not laid out badly, it is invisible. What a
+ * reader sees is a diagram whose last box is sliced off, with nothing to
+ * indicate more was drawn.
+ */
+function collectViewBoxOverrunProblems(html: string): string[] {
+  const overruns = new Set<string>();
+
+  for (const svg of html.matchAll(SVG_OPEN_TAG_PATTERN)) {
+    const box = VIEWBOX_VALUE_PATTERN.exec(svg[0]);
+    if (!box) {
+      continue;
+    }
+    const minX = Number(box[1]);
+    const minY = Number(box[2]);
+    const maxX = minX + Number(box[3]);
+    const maxY = minY + Number(box[4]);
+
+    const bodyStart = (svg.index ?? 0) + svg[0].length;
+    const closeIndex = html.indexOf("</svg", bodyStart);
+    const body = html.slice(
+      bodyStart,
+      closeIndex === -1 ? html.length : closeIndex,
+    );
+
+    for (const rect of body.matchAll(SVG_RECT_TAG_PATTERN)) {
+      const x = numericAttribute(rect[0], "x") ?? 0;
+      const y = numericAttribute(rect[0], "y") ?? 0;
+      const width = numericAttribute(rect[0], "width");
+      const height = numericAttribute(rect[0], "height");
+      if (width !== undefined && x + width > maxX + VIEWBOX_BOUNDS_TOLERANCE) {
+        overruns.add(
+          `x=${x} width=${width} ends at ${x + width}, past ${maxX}`,
+        );
+      }
+      if (
+        height !== undefined &&
+        y + height > maxY + VIEWBOX_BOUNDS_TOLERANCE
+      ) {
+        overruns.add(
+          `y=${y} height=${height} ends at ${y + height}, past ${maxY}`,
+        );
+      }
+    }
+  }
+
+  if (overruns.size === 0) {
+    return [];
+  }
+  return [
+    `Shapes drawn outside the viewBox: ${quote([...overruns])}. ` +
+      "An SVG clips at its viewBox edge, so these render sliced off or not at all, with nothing on screen to say " +
+      "content is missing. Either move the shapes back inside the box or widen the viewBox to cover them, " +
+      "and re-check the packing math: everything has to fit between the viewBox bounds, gaps included.",
+  ];
+}
+
+/**
+ * `transform` attributes anywhere in the fragment. The layout system is built
+ * on absolute viewBox coordinates (grid slots, extent checks, label centring),
+ * and a translated group invites mixing local and absolute coordinates on its
+ * children — the classic symptom is every label rendering below or beside its
+ * box. Banning the attribute keeps one coordinate system for everything.
+ */
+function collectTransformProblems(html: string): string[] {
+  const count = [...html.matchAll(/\stransform\s*=\s*["']/g)].length;
+  if (count === 0) {
+    return [];
+  }
+  return [
+    `${count} element(s) carry a transform attribute. Every coordinate in the fragment is an absolute viewBox coordinate; ` +
+      "remove each transform and place the element directly. A node's text centres at the rect's own position: " +
+      'x = rect x + width/2 with text-anchor="middle", y = rect y + 22 for a single line (or +20 and +38 for a two-line node). ' +
+      "Translated groups mix local and absolute coordinates and put labels outside their boxes.",
+  ];
+}
+
+/**
+ * Style rules that paint a surface token as an inheritable fill. `fill`
+ * inherits from a group to its text children, so `.note{fill:var(--surface-sunken)}`
+ * declared after the text classes silently repaints every label in the tile's
+ * own background colour. A surface fill is legitimate only when the rule is
+ * scoped to shape elements.
+ */
+const SHAPE_SCOPED_SELECTOR_PATTERN =
+  /\b(?:rect|path|circle|ellipse|line|polyline|polygon)\b/;
+
+function collectSurfaceFillOnTextProblems(html: string): string[] {
+  const offenders: string[] = [];
+  for (const rule of html.matchAll(/([^{}<>]{1,120})\{([^{}]*)\}/g)) {
+    const selector = rule[1].trim();
+    const body = rule[2];
+    if (!/fill\s*:\s*var\(--surface-/.test(body)) {
+      continue;
+    }
+    if (SHAPE_SCOPED_SELECTOR_PATTERN.test(selector)) {
+      continue;
+    }
+    offenders.push(selector);
+  }
+  if (offenders.length === 0) {
+    return [];
+  }
+  return [
+    `Style rule(s) ${quote(offenders)} set fill to a surface token without scoping to a shape. ` +
+      "fill inherits to text, so a group-level surface fill repaints the labels inside it in the background colour " +
+      "and they disappear. Scope background fills to the shape (`.note rect{fill:var(--surface-sunken)}`) and keep " +
+      "text fills on content tokens or ramp stops.",
+  ];
+}
+
+/**
+ * Problems with how an `<svg>` is sized. Without a `viewBox` the drawing has no
+ * intrinsic coordinate system to scale, so it renders at its literal size and
+ * the frame crops whatever does not fit.
+ */
+function collectSvgSizingProblems(html: string): string[] {
+  const problems: string[] = [];
+  const oversized: string[] = [];
+  let missingViewBox = false;
+
+  for (const match of html.matchAll(SVG_OPEN_TAG_PATTERN)) {
+    const tag = match[0];
+    if (VIEWBOX_ATTRIBUTE_PATTERN.test(tag)) {
+      continue;
+    }
+    missingViewBox = true;
+    for (const size of tag.matchAll(SVG_PIXEL_SIZE_PATTERN)) {
+      if (Number(size[2]) > MAX_SVG_PIXEL_SIZE) {
+        oversized.push(`${size[1]}="${size[2]}${size[3] ?? ""}"`);
+      }
+    }
+  }
+
+  if (missingViewBox) {
+    problems.push(`An <svg> element has no viewBox attribute. ${VIEWBOX_FIX}`);
+  }
+  if (oversized.length > 0) {
+    problems.push(
+      `An <svg> without a viewBox is sized past the ${MAX_SVG_PIXEL_SIZE}px the frame can show: ${quote(
+        oversized,
+      )}. Everything beyond that width is cropped away. ${VIEWBOX_FIX}`,
+    );
+  }
+
+  return problems;
+}
+
+/** Every ramp-token reference, with the palette and stop split out. */
+const RAMP_TOKEN_PATTERN = new RegExp(
+  `--color-(${[...NEUTRAL_PALETTES, ...ACCENT_PALETTES].join(
+    "|",
+  )})-(50|${RAMP_STEPS.join("|")})\\b`,
+  "g",
+);
+
+/**
+ * The two ends of a ramp, the stops that only read against a fill from the
+ * opposite end. The host mirrors ramp stops under the dark scheme, so an end
+ * stop swaps sides with the theme while the page background it might be
+ * painted on does not — pairing is what keeps the relationship intact.
+ */
+const DARK_RAMP_STOPS: ReadonlySet<string> = new Set([
+  "700",
+  "800",
+  "900",
+  "950",
+]);
+const LIGHT_RAMP_STOPS: ReadonlySet<string> = new Set(["50", "100", "200"]);
+/** Fill stops light enough to carry dark ramp text. */
+const LIGHT_FILL_STOPS: ReadonlySet<string> = new Set([
+  "50",
+  "100",
+  "200",
+  "300",
+]);
+
+/** `color:` declarations, excluding `background-color:`, `stop-color:`, etc. */
+const TEXT_COLOR_DECLARATION_PATTERN = /(?<![-\w])color\s*:\s*[^;}"'>]*/gi;
+
+/** Open tags of the two SVG elements that paint glyphs. */
+const SVG_TEXT_TAG_PATTERN = /<(?:text|tspan)\b[^>]*>/gi;
+
+/** Any element's open tag, the span that carries one element's own paint. */
+const START_TAG_PATTERN = /<[a-zA-Z][^>]*>/g;
+
+/** `<g>` open and close tags, used to bound the group around a label. */
+const GROUP_BOUNDARY_PATTERN = /<g\b[^>]*>|<\/g\s*>/gi;
+
+/** Class names an element carries, used to reach the rules that paint it. */
+const CLASS_ATTRIBUTE_PATTERN = /\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+/**
+ * Style rules, used to spot the ones that paint text via `fill:`. The selector
+ * is bounded by `<`, `>`, `;` and `}` so it cannot swallow preceding markup.
+ */
+const CSS_RULE_PATTERN = /[^{};<>]*\{[^{}]*\}/g;
+const FILL_DECLARATION_PATTERN = /\bfill\s*:/i;
+const FONT_DECLARATION_PATTERN = /\bfont(?:-[a-z]+)?\s*:/i;
+const TEXT_SELECTOR_PATTERN = /(?:^|[\s,>+~])(?:text|tspan)\b/i;
+
+/**
+ * How much markup either side of a painted label counts as "beside it". A
+ * two-line SVG node — rect plus title plus subtitle — runs about 350
+ * characters, so this reaches the shape a label belongs to without reaching the
+ * rest of the drawing.
+ */
+const LOCAL_PAIRING_WINDOW = 400;
+
+/**
+ * Largest `<g>` that still reads as one paired shape. Past this a group is a
+ * layout container, and treating it as a pairing context would clear a palette
+ * for the whole drawing.
+ */
+const MAX_LOCAL_GROUP_CHARS = 2000;
+
+type SourceRange = { start: number; end: number };
+
+type CssRule = SourceRange & { selector: string; body: string };
+
+/** Every `{…}` rule in the fragment, split into selector and body. */
+function collectCssRules(html: string): CssRule[] {
+  const rules: CssRule[] = [];
+  for (const match of html.matchAll(CSS_RULE_PATTERN)) {
+    const text = match[0];
+    const start = match.index ?? 0;
+    const braceIndex = text.indexOf("{");
+    rules.push({
+      start,
+      end: start + text.length,
+      selector: text.slice(0, braceIndex),
+      body: text.slice(braceIndex),
+    });
+  }
+  return rules;
+}
+
+function collectRanges(html: string, pattern: RegExp): SourceRange[] {
+  const ranges: SourceRange[] = [];
+  for (const match of html.matchAll(pattern)) {
+    const start = match.index ?? 0;
+    ranges.push({ start, end: start + match[0].length });
+  }
+  return ranges;
+}
+
+/** Spans of balanced `<g>…</g>` pairs. Unclosed groups are ignored. */
+function collectGroupRanges(html: string): SourceRange[] {
+  const ranges: SourceRange[] = [];
+  const open: number[] = [];
+  for (const match of html.matchAll(GROUP_BOUNDARY_PATTERN)) {
+    const index = match.index ?? 0;
+    if (match[0].startsWith("</")) {
+      const start = open.pop();
+      if (start !== undefined) {
+        ranges.push({ start, end: index + match[0].length });
+      }
+    } else if (!match[0].endsWith("/>")) {
+      open.push(index);
+    }
+  }
+  return ranges;
+}
+
+/**
+ * Spans of the fragment that paint text: `color:` declarations, `<text>` and
+ * `<tspan>` open tags, and style rules whose `fill:` lands on glyphs — either
+ * because the rule also sets a font property or because its selector names a
+ * text element. A ramp token inside one of these is a text colour.
+ */
+function collectTextColorRanges(html: string, rules: CssRule[]): SourceRange[] {
+  const ranges = [
+    ...collectRanges(html, TEXT_COLOR_DECLARATION_PATTERN),
+    ...collectRanges(html, SVG_TEXT_TAG_PATTERN),
+  ];
+  for (const rule of rules) {
+    if (
+      FILL_DECLARATION_PATTERN.test(rule.body) &&
+      (FONT_DECLARATION_PATTERN.test(rule.body) ||
+        TEXT_SELECTOR_PATTERN.test(rule.selector))
+    ) {
+      ranges.push({ start: rule.start, end: rule.end });
+    }
+  }
+  return ranges;
+}
+
+function isInsideRange(index: number, ranges: SourceRange[]): boolean {
+  return ranges.some((range) => index >= range.start && index < range.end);
+}
+
+/** The tightest range containing the index, if any. */
+function innermostRange<T extends SourceRange>(
+  index: number,
+  ranges: T[],
+): T | undefined {
+  let found: T | undefined;
+  for (const range of ranges) {
+    if (index < range.start || index >= range.end) {
+      continue;
+    }
+    if (!found || range.end - range.start < found.end - found.start) {
+      found = range;
+    }
+  }
+  return found;
+}
+
+/** Whether a stop of `palette` from `allowed` is painted anywhere in `text`. */
+function hasCounterpartStop(
+  text: string,
+  palette: string,
+  allowed: ReadonlySet<string>,
+): boolean {
+  for (const match of text.matchAll(RAMP_TOKEN_PATTERN)) {
+    if (match[1] === palette && allowed.has(match[2])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The markup a directly painted label is paired against: its own open tag, the
+ * window of markup around it, the group immediately containing it, and the
+ * bodies of the rules that paint the classes named in that window.
+ */
+function localPairingContexts(
+  html: string,
+  index: number,
+  rules: CssRule[],
+  tags: SourceRange[],
+  groups: SourceRange[],
+): string[] {
+  const nearby = html.slice(
+    Math.max(0, index - LOCAL_PAIRING_WINDOW),
+    index + LOCAL_PAIRING_WINDOW,
+  );
+  const contexts = [nearby];
+
+  const tag = innermostRange(index, tags);
+  if (tag) {
+    contexts.push(html.slice(tag.start, tag.end));
+  }
+
+  const group = innermostRange(index, groups);
+  if (group && group.end - group.start <= MAX_LOCAL_GROUP_CHARS) {
+    contexts.push(html.slice(group.start, group.end));
+  }
+
+  const classNames = new Set<string>();
+  for (const match of nearby.matchAll(CLASS_ATTRIBUTE_PATTERN)) {
+    for (const name of (match[1] ?? match[2] ?? "").split(/\s+/)) {
+      if (name) {
+        classNames.add(name);
+      }
+    }
+  }
+  for (const rule of rules) {
+    if ([...classNames].some((name) => rule.selector.includes(`.${name}`))) {
+      contexts.push(rule.body);
+    }
+  }
+
+  return contexts;
+}
+
+/**
+ * The host mirrors each ramp stop onto its opposite under the dark scheme, so a
+ * ramp is theme-adaptive only relative to itself: a matched fill and text pair
+ * inverts together and stays legible, while a lone ramp label is left against
+ * the page background, which takes no part in that mirror. Ramp-coloured text
+ * therefore only reads when it sits on a matching ramp fill — and the fill has
+ * to be the one actually behind the glyphs.
+ *
+ * Pairing is therefore local. A label painted directly — an inline `style`, a
+ * `fill` attribute on `<text>` — pairs against its own element, the markup
+ * around it, the group containing it, or the rules painting the classes in that
+ * window. A label painted through a style rule pairs inside that rule, and
+ * otherwise against the fragment as a whole: which elements a selector reaches
+ * is not knowable without a DOM, so the rule's own placement carries no signal.
+ */
+function collectRampContrastProblems(html: string): string[] {
+  const rules = collectCssRules(html);
+  const textRanges = collectTextColorRanges(html, rules);
+  const tags = collectRanges(html, START_TAG_PATTERN);
+  const groups = collectGroupRanges(html);
+
+  const occurrences = [...html.matchAll(RAMP_TOKEN_PATTERN)].map((match) => ({
+    token: match[0],
+    palette: match[1],
+    stop: match[2],
+    index: match.index ?? 0,
+  }));
+
+  const fillStops = new Map<string, Set<string>>();
+  for (const occurrence of occurrences) {
+    if (isInsideRange(occurrence.index, textRanges)) {
+      continue;
+    }
+    const stops = fillStops.get(occurrence.palette) ?? new Set<string>();
+    stops.add(occurrence.stop);
+    fillStops.set(occurrence.palette, stops);
+  }
+
+  const hasFillStopIn = (
+    palette: string,
+    allowed: ReadonlySet<string>,
+  ): boolean =>
+    [...(fillStops.get(palette) ?? [])].some((stop) => allowed.has(stop));
+
+  const unpairedDark = new Set<string>();
+  const unpairedLight = new Set<string>();
+
+  for (const occurrence of occurrences) {
+    if (!isInsideRange(occurrence.index, textRanges)) {
+      continue;
+    }
+    const bucket = DARK_RAMP_STOPS.has(occurrence.stop)
+      ? unpairedDark
+      : LIGHT_RAMP_STOPS.has(occurrence.stop)
+        ? unpairedLight
+        : undefined;
+    if (!bucket) {
+      continue;
+    }
+    const counterparts =
+      bucket === unpairedDark ? LIGHT_FILL_STOPS : DARK_RAMP_STOPS;
+
+    const rule = innermostRange(occurrence.index, rules);
+    const paired = rule
+      ? hasCounterpartStop(rule.body, occurrence.palette, counterparts) ||
+        hasFillStopIn(occurrence.palette, counterparts)
+      : localPairingContexts(html, occurrence.index, rules, tags, groups).some(
+          (context) =>
+            hasCounterpartStop(context, occurrence.palette, counterparts),
+        );
+
+    if (!paired) {
+      bucket.add(occurrence.token);
+    }
+  }
+
+  const problems: string[] = [];
+  if (unpairedDark.size > 0) {
+    problems.push(
+      `Dark ramp stops used as text colour with no matching light fill behind them: ${quote(
+        [...unpairedDark],
+      )}. ` +
+        "Ramp stops mirror across their own ramp in dark mode, so a dark stop used as text flips to a " +
+        "light tint there while the page background takes no part in that mirror — a ramp-coloured " +
+        "label sitting on it has no reliable contrast in either theme. Ramp-coloured text has to sit " +
+        "on a matching light ramp " +
+        "fill (a 50–300 stop of the same palette) set on the same element, in the same style rule, or " +
+        "on the group immediately around it — or use a --content-* token for text that sits on the " +
+        "page background.",
+    );
+  }
+  if (unpairedLight.size > 0) {
+    problems.push(
+      `Light ramp stops used as text colour with no matching dark fill behind them: ${quote(
+        [...unpairedLight],
+      )}. ` +
+        "Light ramp text on the transparent widget background is invisible in light mode, and in dark " +
+        "mode the stop mirrors to the darkest end of its own ramp — invisible there too. " +
+        "Ramp-coloured text has to sit on a matching dark ramp " +
+        "fill (a 700–950 stop of the same palette) set on the same element, in the same style rule, or " +
+        "on the group immediately around it — or use a --content-* token for text that sits on the " +
+        "page background.",
+    );
+  }
+
+  return problems;
+}
+
+function collectDeclaredProperties(html: string): Set<string> {
+  const declared = new Set<string>();
+  for (const match of html.matchAll(CUSTOM_PROPERTY_DECLARATION_PATTERN)) {
+    declared.add(match[1]);
+  }
+  for (const match of html.matchAll(SET_PROPERTY_DECLARATION_PATTERN)) {
+    declared.add(match[1]);
+  }
+  return declared;
+}
+
+function collectUnknownVariables(html: string): string[] {
+  const declared = collectDeclaredProperties(html);
+  const unknown = new Set<string>();
+  for (const match of html.matchAll(VAR_REFERENCE_PATTERN)) {
+    const name = match[1];
+    if (!WIDGET_TOKEN_NAMES.has(name) && !declared.has(name)) {
+      unknown.add(name);
+    }
+  }
+  return [...unknown];
+}
+
+function collectColorLiterals(html: string): string[] {
+  let scannable = html;
+  for (const pattern of NON_COLOR_HASH_PATTERNS) {
+    scannable = scannable.replace(pattern, " ");
+  }
+
+  const literals: string[] = [];
+  for (const match of scannable.matchAll(HEX_TOKEN_PATTERN)) {
+    if (HEX_COLOR_LENGTHS.has(match[1].length)) {
+      literals.push(match[0]);
+    }
+  }
+  for (const match of scannable.matchAll(FUNCTIONAL_COLOR_PATTERN)) {
+    literals.push(match[0]);
+  }
+  return literals;
+}
+
+function quote(values: string[]): string {
+  const shown = values.slice(0, MAX_QUOTED_PROBLEMS).join(", ");
+  const extra = values.length - MAX_QUOTED_PROBLEMS;
+  return extra > 0 ? `${shown}, and ${extra} more` : shown;
+}
+
+/**
+ * Everything wrong with a `visual` fragment, as a list of problems the model
+ * can fix in one pass. Empty means the fragment is renderable.
+ */
+export function validateVisualHtml(html: string): string[] {
+  const problems: string[] = [];
+
+  if (html.length > MAX_HTML_CHARS) {
+    problems.push(
+      `The fragment is ${html.length} characters, over the ${MAX_HTML_CHARS} limit. ` +
+        "A fragment this size cannot be emitted in one call. Simplify it: cut nodes, drop subtitles, remove decorative markup, or split the idea across two visuals with prose between them.",
+    );
+  }
+
+  for (const { pattern, what } of EXTERNAL_RESOURCE_PATTERNS) {
+    if (pattern.test(html)) {
+      problems.push(
+        `The fragment contains ${what}. The sandbox has no network access, so external resources never load. ` +
+          "Inline the styles and draw charts and diagrams by hand in SVG.",
+      );
+    }
+  }
+
+  const unknown = collectUnknownVariables(html);
+  if (unknown.length > 0) {
+    problems.push(
+      `Undefined CSS variables: ${quote(
+        unknown,
+      )}. Only the injected design tokens exist inside the ` +
+        "frame — every other name resolves to nothing and the declaration is dropped. " +
+        `The vocabulary is ${TOKEN_FAMILY_SUMMARY}. ` +
+        "To use a variable of your own, declare it in the fragment's own style block first.",
+    );
+  }
+
+  const literals = collectColorLiterals(html);
+  if (literals.length > 0) {
+    problems.push(
+      `Hardcoded colour values: ${quote(
+        literals,
+      )}. Every colour — text, background, border, SVG ` +
+        "fill and stroke — comes from an injected variable, so the visual follows the user's theme. " +
+        `Replace each literal with a token from ${TOKEN_FAMILY_SUMMARY}.`,
+    );
+  }
+
+  problems.push(...collectSvgSizingProblems(html));
+  problems.push(...collectViewBoxOverrunProblems(html));
+  problems.push(...collectRampContrastProblems(html));
+  problems.push(...collectTransformProblems(html));
+  problems.push(...collectSurfaceFillOnTextProblems(html));
+
+  return problems;
+}