@ggui-ai/ui-gen 0.25.0 → 0.26.0

package/package.json

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

package/src/adapters/generation-dispatch.ts

@@ -126,6 +126,8 @@ export interface GenerationDispatchParams {
     /** ggui#1436 — see `SingleComponentParams.visualEvaluation.criteriaBank`. */
     criteriaBank?: CriteriaBank;
     criteriaKind?: string;
+    /** ggui#1542 — see `SingleComponentParams.visualEvaluation.actOn`. */
+    actOn?: "critical" | "major";
   };
   /** Quality config controlling eval tiers and improvement behavior */
   qualityConfig?: QualityConfig;

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

@@ -18,7 +18,7 @@
 // for raw elements · the one-gesture-surface invariant restated for raw
 // elements · a regenerated quality checklist.
 
-import { consumedTokenManifest } from "@ggui-ai/design/themes";
+import { taughtTokenManifest } from "../taught-tokens.js";
 import { describeCanvas, type CanvasClass } from "../design-mode.js";
 import {
   ANTI_PATTERNS,
@@ -136,7 +136,7 @@ function renderRamp(r: ColorRamp): string {
  * every role the prose names exists on `:root`; nothing is implied by a
  * `50…800` range that the manifest does not carry step for step.
  */
-export function renderFreeColorRule(manifest: readonly string[] = consumedTokenManifest): string {
+export function renderFreeColorRule(manifest: readonly string[] = taughtTokenManifest): string {
   const { ramps, roles } = colorVocabularyFromManifest(manifest);
   const brand = ramps.filter((r) => r.family === "primary" || r.family === "neutral");
   const state = ramps.filter((r) => r.family !== "primary" && r.family !== "neutral");
@@ -260,7 +260,7 @@ const TOKEN_GROUPS: readonly TokenGroup[] = [
  * does not define. Grouped by prefix; anything outside the known
  * prefixes lands under "Other".
  */
-export function renderTokenVocabulary(manifest: readonly string[] = consumedTokenManifest): string {
+export function renderTokenVocabulary(manifest: readonly string[] = taughtTokenManifest): string {
   const sorted = [...manifest].sort();
   const claimed = new Set<string>();
   const lines: string[] = [

package/src/boilerplate/hard-sections.ts

@@ -257,7 +257,7 @@ The width works the same way, and the mistake is the mirror image: **your outerm
 
 - Never put \`maxWidth\` (or a \`max-w-*\` class) on the element you return at the top. On a wide canvas that turns your card into a narrow strip with the frame's ground on either side of it, and on a narrow one it does nothing — the same composition reading differently at two sizes.
 - DO cap the reading measure inside: a column of prose is easiest to read at 60–70 characters, so wrap the TEXT in a \`<Container maxWidth="sm">\` (or your own \`max-width\`) and leave the root filling. A hero band, a toolbar, a table or an image then still uses the whole width, which is what makes a wide card look composed rather than padded.
-- Centre that inner column with the container's own centring, not by shrinking the root.
+- Centre that inner column with the container's own centring, not by shrinking the root — and give the card ONE column: every block of the reading flow (a heading, its text, and the chips or buttons that answer it) sits in a \`<Container>\` of the same \`maxWidth\`, so their left edges line up even where a full-width band runs between them.
 - **They are two different elements.** Even when the whole card is one column of text, the root still fills and the column sits INSIDE it — \`<Box padding="lg"><Container maxWidth="sm">…</Container></Box>\`, never a root that is itself the container. A centred card is centring inside a filled frame, not a shrunken frame.`;
 
 /** Helper-component structure guidance (JSX depth 3–5, helpers above `Component`). Identical in both modes. */

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

@@ -3,5 +3,7 @@
           provides the chrome, so add no shadow or outer radius of your own.
           Compact and natural height; stack vertically. This root fills the
           bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
-          measure (inert at bubble width, composed on a wider frame). */}
+          measure (inert at bubble width, composed on a wider frame), and put
+          the chips or buttons that answer it in a Container of the same
+          maxWidth, so every block keeps one left edge. */}
     </Box>

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

@@ -3,5 +3,7 @@
           provides the chrome, so add no shadow or outer radius of your own.
           Compact and natural height; stack vertically. This root fills the
           bubble — wrap PROSE in <Container maxWidth="sm"> to cap the reading
-          measure (inert at bubble width, composed on a wider frame). */}
+          measure (inert at bubble width, composed on a wider frame), and put
+          the chips or buttons that answer it in a Container of the same
+          maxWidth, so every block keeps one left edge. */}
     </Box>

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

@@ -1,5 +1,7 @@
     <Box padding="lg">
       {/* implement your UI here — this root FILLS the frame.
           Bands, toolbars, tables and images use the whole width;
-          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure,
+          and put the chips or buttons that answer it in a Container of the
+          same maxWidth, so every block keeps one left edge. */}
     </Box>

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

@@ -1,5 +1,7 @@
     <Box padding="lg">
       {/* implement your UI here — this root FILLS the frame.
           Bands, toolbars, tables and images use the whole width;
-          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure. */}
+          wrap PROSE in <Container maxWidth="sm"> to cap the reading measure,
+          and put the chips or buttons that answer it in a Container of the
+          same maxWidth, so every block keeps one left edge. */}
     </Box>

package/src/check/run-tier0.ts

@@ -17,6 +17,7 @@ import type { DataContract } from '@ggui-ai/protocol';
 import { HOOK_NAME_RE, listContractGadgets } from '@ggui-ai/protocol';
 import { consumedTokenManifest } from '@ggui-ai/design/themes';
 import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
+import { taughtTokenManifest } from '../taught-tokens.js';
 import { validateAllContracts, type ContractIssue } from './contract-validation.js';
 import { typecheck } from './type-checker.js';
 import { lintReactHooks, type ReactLintDiagnostic } from './react-linter.js';
@@ -315,7 +316,9 @@ const RETIRED_TOKEN_SUCCESSORS: ReadonlyMap<string, string> = new Map([
  * (`--ggui-motion-duration-normal` → fast, base, slow); otherwise the names
  * sharing any of its segments of four letters or more
  * (`--ggui-duration-slow` → the motion durations). Empty when nothing is
- * near, so the hint falls back to the manifest's general shape.
+ * near, so the hint falls back to the manifest's general shape. A hint
+ * teaches, so it draws only on the names the model may be taught
+ * (`taughtTokenManifest`); the closed-set check above admits the full manifest.
  */
 export function suggestManifestTokens(name: string): readonly string[] {
   const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
@@ -328,7 +331,7 @@ export function suggestManifestTokens(name: string): readonly string[] {
   const own = name.endsWith('-') ? segments.length : segments.length - 1;
   for (let n = own; n >= 2; n--) {
     const prefix = `--${segments.slice(0, n).join('-')}-`;
-    const family = consumedTokenManifest.filter((token) => token.startsWith(prefix));
+    const family = taughtTokenManifest.filter((token) => token.startsWith(prefix));
     if (family.length > 0) return wordHitsFirst(name, rolesFirst(family));
   }
   const words = new Set(
@@ -338,7 +341,7 @@ export function suggestManifestTokens(name: string): readonly string[] {
       .map((segment) => segment.toLowerCase()),
   );
   return rolesFirst(
-    consumedTokenManifest.filter((token) =>
+    taughtTokenManifest.filter((token) =>
       token.split('-').some((segment) => words.has(segment.toLowerCase())),
     ),
   );

package/src/contract-context.ts

@@ -59,7 +59,7 @@ const SHELL_HINTS: Record<string, string> = {
 - Padding: use var(--ggui-spacing-2) for inner elements, var(--ggui-spacing-4) for sections. Tight.
 - Scrolling: parent scrolls (chat feed) — component should NOT have internal scroll
 - Layout: single column, compact. No sidebar. Stack everything vertically.
-- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width.`,
+- Width: the root is width: 100% (fills the bubble) — never cap the ROOT. A prose column inside it carries the reading cap (<Container maxWidth="sm">), which is inert at bubble width; the chips or buttons that answer the prose sit in a Container of the same maxWidth, so they share its left edge.`,
 
   fullscreen: `**Fullscreen Shell — Takes over entire viewport**
 - Container: the whole viewport, edge to edge — the frame stretches your root to its full height (you never set a viewport height yourself)

package/src/evaluation/cost-tracker.ts

@@ -31,15 +31,54 @@ function resolveRegistryId(model: string): ModelId | null {
   return keys.find((id) => id.endsWith(`/${undated}`)) ?? null;
 }
 
+/**
+ * ggui#1524 — the largest cache-WRITE premium any registry model states (`cacheWritePer1M / inputPer1M`), never
+ * below 1. A cost CAP errs toward over-counting, so a model that states no write rate is priced at this bound
+ * times its input rate: a write costs a premium over input wherever one is charged, and pricing it at the bare
+ * input rate would slip that premium under the cap. Derived from the registry, so it moves with it.
+ */
+export const CACHE_WRITE_PREMIUM_BOUND: number = Math.max(
+  1,
+  ...Object.values(MODEL_REGISTRY).flatMap(({ costs }) =>
+    costs.cacheWritePer1M !== undefined && costs.inputPer1M > 0 ? [costs.cacheWritePer1M / costs.inputPer1M] : [],
+  ),
+);
+
+/** Per-1K USD for each kind of token a call can spend. */
+export interface PricePer1k {
+  readonly input: number;
+  readonly output: number;
+  /** Cache reads: the model's stated rate, else its input rate — over-counts a read, the safe side for a cap. */
+  readonly cacheRead: number;
+  /** Cache writes: the model's stated rate, else its input rate × {@link CACHE_WRITE_PREMIUM_BOUND}. */
+  readonly cacheWrite: number;
+}
+
 /** Fallback when a model has no registry entry — Sonnet-class rates. */
-const FALLBACK_PER_1K = { input: 0.003, output: 0.015 };
+const FALLBACK_PER_1K: PricePer1k = {
+  input: 0.003,
+  output: 0.015,
+  cacheRead: 0.003,
+  cacheWrite: 0.003 * CACHE_WRITE_PREMIUM_BOUND,
+};
 
-/** Per-1K input/output USD for a bare wire model id. */
-export function pricePer1k(model: string): { input: number; output: number } {
+/** Per-1K USD for a bare wire model id: input, output, and the two cache kinds. */
+export function pricePer1k(model: string): PricePer1k {
   const id = resolveRegistryId(model);
   if (id === null) return FALLBACK_PER_1K;
   const { costs } = MODEL_REGISTRY[id];
-  return { input: costs.inputPer1M / 1000, output: costs.outputPer1M / 1000 };
+  return {
+    input: costs.inputPer1M / 1000,
+    output: costs.outputPer1M / 1000,
+    cacheRead: (costs.cacheReadPer1M ?? costs.inputPer1M) / 1000,
+    cacheWrite: (costs.cacheWritePer1M ?? costs.inputPer1M * CACHE_WRITE_PREMIUM_BOUND) / 1000,
+  };
+}
+
+/** ggui#1524 — the cache tokens a call spent, as its provider reported them; absent = unreported. */
+export interface CacheSpend {
+  readonly read?: number;
+  readonly write?: number;
 }
 
 export class CostTracker {
@@ -47,9 +86,18 @@ export class CostTracker {
 
   constructor(private maxBudget: number | null) {}
 
-  record(model: string, inputTokens: number, outputTokens: number): number {
+  /**
+   * Record one call. `inputTokens` is the provider's UNCACHED input; a call that read or wrote the prompt cache
+   * passes those counts in `cache` (ggui#1524), priced at the cache rates — until then a turn with a long cached
+   * prefix cost the cap almost nothing while the provider billed its reads and writes.
+   */
+  record(model: string, inputTokens: number, outputTokens: number, cache: CacheSpend = {}): number {
     const prices = pricePer1k(model);
-    const cost = (inputTokens / 1000) * prices.input + (outputTokens / 1000) * prices.output;
+    const cost =
+      (inputTokens / 1000) * prices.input +
+      (outputTokens / 1000) * prices.output +
+      ((cache.read ?? 0) / 1000) * prices.cacheRead +
+      ((cache.write ?? 0) / 1000) * prices.cacheWrite;
     this.totalCost += cost;
     return cost;
   }

package/src/evaluation/criteria/edge-probe.ts

@@ -0,0 +1,286 @@
+/**
+ * `space.edge`'s measurement (#1663): the expression a capture evaluates in the page to produce {@link EdgeBlock}s for
+ * {@link judgeEdges}. It runs where the screenshot is taken, on the same DOM at the same width, so the rule reads what
+ * the judge's frame shows. It only reads layout; it never writes to the page.
+ *
+ * What it measures, under `#root`, in CSS px from the card's left edge:
+ *
+ * - **Text blocks.** Text is grouped by its nearest non-inline element. A block's edge is its first visible character
+ *   in ink: text in a transparent colour, private-use icon-font glyphs and formatting characters are not characters of
+ *   the block. Its extent is the union of its inked line boxes. A marker before the text (an icon or image that paints,
+ *   or a number or bullet on the same line) makes it a hanging marker: `edge` is the marker's, `textEdge` the text's.
+ * - **Control groups.** Native and ARIA controls, and bounded boxes the visitor clicks (a pointer cursor or a tab stop,
+ *   holding no control of their own), group by their parent and are measured at the first control: the border box
+ *   when bounded, else its text. A control's contents are never blocks of the enclosing column.
+ * - **Surfaces.** A non-inline box with a border on at least three sides, its own fill different from what it sits on,
+ *   or a shadow. A table is a surface measured at its rule and not descended into. A box with no text, control, image
+ *   or icon inside (a loading bar) is a `placeholder`, which is not a block.
+ * - **Roles.** A list item is `list-item` when its list follows a paragraph; text centred in a box wider than it, or
+ *   controls in a centring row, are `centred`.
+ * - **Rows, first, read by geometry.** Items set on one line, however the CSS lays them out: an item after another
+ *   measured item on its line that holds one block (a text, a control, or a box holding at most one text) belongs to
+ *   the row and is not measured. An item with a stack inside it is a column.
+ * - **Ornaments:** text with no letters or digits is not measured.
+ *
+ * Hidden elements (through any ancestor), zero-size ones and transparent text are skipped. What the rows and ornament
+ * rules set aside is counted. A frame with no text in ink is reported as placeholders only. The expression returns a
+ * JSON value; {@link parseEdgeProbe} is its typed read. *
+ * **Validated instrument (#1663, 2026-10-02):** this file as of `cec465319` (with `7bb4da13e`) passed a fresh sealed
+ * blind draw at the registered bar (27/30, κ 0.76), stricter than the design lead's reading on its disagreements. Any
+ * later change to what this file measures or decides is a new instrument until another fresh sealed draw.
+ */
+import type { EdgeBlock } from './edge.js';
+
+/** What the probe returns: the measured blocks, and whether the frame showed nothing to evaluate. */
+export interface EdgeProbe {
+  readonly blocks: readonly EdgeBlock[];
+  readonly placeholdersOnly: boolean;
+  /** What the probe saw and did not measure, by rule, so a dropped block is counted rather than silent. */
+  readonly skipped: { readonly rowItems: number; readonly ornaments: number };
+}
+
+// Plain ES2020 for the page: no imports, no template literals, no helpers a bundler might rename.
+export const EDGE_BLOCKS_EXPRESSION = String.raw`(() => {
+  const root = document.getElementById('root');
+  if (!root) return null;
+  const rootBox = root.getBoundingClientRect();
+  const x0 = rootBox.left;
+  const px = (v) => Math.round((v - x0) * 2) / 2;
+  const CONTROL = 'button,input,select,textarea,[role="button"],[role="tab"],[role="switch"],[role="checkbox"],[role="radio"],[role="option"],[role="link"],a[href]';
+  const ALNUM = /[\p{L}\p{N}]/u;
+  const css = (el) => getComputedStyle(el);
+  const clear = (c) => !c || c === 'transparent' || /rgba\([^)]*,\s*0(\.0+)?\)$/.test(c);
+  // Visible through every ancestor (an ancestor at opacity 0 or visibility hidden hides it), and not degenerate.
+  const shown = (el) => {
+    const s = css(el);
+    if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) === 0) return false;
+    if (typeof el.checkVisibility === 'function' && !el.checkVisibility({ opacityProperty: true, visibilityProperty: true })) return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 1 && r.height > 1;
+  };
+  const inline = (s) => /^inline/.test(s.display) && s.display !== 'inline-block' && s.display !== 'inline-flex' && s.display !== 'inline-grid';
+  const groundOf = (el) => {
+    for (let p = el.parentElement; p; p = p.parentElement) { const b = css(p).backgroundColor; if (!clear(b)) return b; }
+    return 'rgb(255, 255, 255)';
+  };
+  const sides = (s) => ['Top', 'Right', 'Bottom', 'Left'].filter((k) => parseFloat(s['border' + k + 'Width']) > 0 && s['border' + k + 'Style'] !== 'none' && !clear(s['border' + k + 'Color'])).length;
+  const bounded = (el) => { const s = css(el); return sides(s) >= 1 || (!clear(s.backgroundColor) && s.backgroundColor !== groundOf(el)); };
+  // A control: a native or ARIA one, or a bounded box the visitor clicks (a pointer cursor or a tab stop) that holds no
+  // control of its own and is not the whole card. Its contents are not blocks of the column (decided 2026-10-02).
+  const isControl = (el) => {
+    const s = css(el);
+    if (inline(s)) return false;
+    if (el.matches(CONTROL)) return true;
+    if (el === root) return false;
+    const clickable = s.cursor === 'pointer' || (el.hasAttribute('tabindex') && el.tabIndex >= 0);
+    if (!clickable || !bounded(el) || el.querySelector(CONTROL)) return false;
+    const r = el.getBoundingClientRect();
+    return r.width * r.height < 0.6 * rootBox.width * rootBox.height;
+  };
+  const isTable = (el) => el.matches('table,[role="table"],[role="grid"]');
+  const isSurface = (el) => {
+    if (el === root || isControl(el)) return false;
+    const s = css(el);
+    if (/^inline/.test(s.display) || s.display === 'contents') return false;
+    if (isTable(el)) return true;
+    return sides(s) >= 3 || (!clear(s.backgroundColor) && s.backgroundColor !== groundOf(el)) || (s.boxShadow && s.boxShadow !== 'none');
+  };
+  const path = (el) => {
+    const parts = [];
+    for (let e = el; e && e !== root && parts.length < 4; e = e.parentElement) {
+      const i = e.parentElement ? Array.prototype.indexOf.call(e.parentElement.children, e) + 1 : 1;
+      parts.unshift(e.tagName.toLowerCase() + ':' + i);
+    }
+    return parts.join('>');
+  };
+  const label = (el) => { const t = (el.innerText || '').replace(/\s+/g, ' ').trim(); return path(el) + (t ? ' "' + t.slice(0, 24) + '"' : ''); };
+  const surfaces = [];
+  const surfaceOf = (el, self) => { for (let p = self ? el : el.parentElement; p && p !== root; p = p.parentElement) if (surfaces.indexOf(p) >= 0) return p; return null; };
+  const inTable = (el) => { for (let p = el.parentElement; p && p !== root; p = p.parentElement) if (isTable(p)) return true; return false; };
+  const inControl = (el) => { for (let p = el; p && p !== root; p = p.parentElement) if (isControl(p)) return p; return null; };
+  const all = Array.prototype.slice.call(root.querySelectorAll('*')).filter(shown);
+  for (const el of all) if (isSurface(el) && !inTable(el) && !inControl(el)) surfaces.push(el);
+  const ids = new Map();
+  const idOf = (el) => { if (!ids.has(el)) ids.set(el, label(el)); return ids.get(el); };
+  const blocks = [];
+  // Per block: the element it stands for and its first line's box, for rows.
+  const owners = [];
+  const lines = [];
+  // Per block: its raw line boxes and left, so a row reads the line two items share, not a wrapped item's widest line.
+  const rects = [];
+  const rawLeft = [];
+  const words = [];
+  const within = (el, self) => { const s = surfaceOf(el, self); return s ? { within: idOf(s) } : {}; };
+  for (const s of surfaces) {
+    const r = s.getBoundingClientRect();
+    owners.push(s); lines.push({ top: r.top, bottom: r.bottom }); rects.push([r]); rawLeft.push(r.left); words.push('');
+    // A placeholder: a box with no text, no control and no image or icon inside it (a loading bar). Not a block.
+    const holds = Array.prototype.some.call(s.querySelectorAll('*'), (el) => shown(el) && (el.matches(CONTROL) || el.tagName === 'IMG' || el.tagName.toLowerCase() === 'svg')) || ALNUM.test(s.innerText || '');
+    blocks.push(Object.assign({ id: idOf(s), kind: 'surface', edge: px(r.left), left: px(r.left), right: px(r.right), top: Math.round(r.top) }, within(s, false), isTable(s) ? { role: 'table' } : holds ? {} : { role: 'placeholder' }));
+  }
+  const blockOf = (node) => { for (let p = node.parentElement; p && p !== root; p = p.parentElement) if (!inline(css(p))) return p; return root; };
+  const groups = new Map();
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    if (!/\S/.test(n.data) || !n.parentElement || n.parentElement.closest('style,script,noscript,template') || !shown(n.parentElement) || inControl(n.parentElement) || inTable(n.parentElement)) continue;
+    const b = blockOf(n);
+    if (!groups.has(b)) groups.set(b, []);
+    groups.get(b).push(n);
+  }
+  // Ink: text whose own colour is not transparent. The edge is the first visible character in ink (decided 2026-10-02):
+  // leading invisible text, private-use icon-font glyphs and formatting characters are not characters of the block,
+  // while a currency sign or a quotation mark is.
+  const inked = (n) => !clear(css(n.parentElement).color) && ALNUM.test(n.data);
+  const textRects = (nodes) => {
+    const rs = [];
+    for (const n of nodes) { if (!inked(n)) continue; const range = document.createRange(); range.selectNodeContents(n); for (const r of range.getClientRects()) if (r.width > 0 && r.height > 0) rs.push(r); }
+    return rs;
+  };
+  const glyphAt = (n, i) => { const range = document.createRange(); range.setStart(n, i); range.setEnd(n, i + 1); const r = range.getClientRects()[0]; return r || null; };
+  const firstGlyph = (nodes) => {
+    for (const n of nodes) { if (!inked(n)) continue; const i = n.data.search(/[^\s\p{Co}\p{Cf}]/u); if (i < 0) continue; const r = glyphAt(n, i); if (r) return r; }
+    return null;
+  };
+  // A marker paints: a loaded image, an SVG with a filled or stroked shape, or an element with its own fill, border
+  // or visible text. An element that paints nothing is not a marker.
+  const painted = (m) => {
+    if (!shown(m)) return false;
+    if (m.tagName === 'IMG') return m.complete && m.naturalWidth > 0;
+    if (m.tagName.toLowerCase() === 'svg' || m.closest('svg')) {
+      const shapes = m.querySelectorAll('path,circle,rect,line,polyline,polygon,ellipse,use,text');
+      return Array.prototype.some.call(shapes, (sh) => { const st = css(sh); return (st.fill !== 'none' && !clear(st.fill)) || (st.stroke !== 'none' && !clear(st.stroke)); });
+    }
+    const s = css(m);
+    if (!clear(s.backgroundColor) || sides(s) >= 1 || ((m.textContent || '').trim().length > 0 && !clear(s.color))) return true;
+    // A wrapper that paints nothing itself is a marker when an image or icon inside it paints.
+    return Array.prototype.some.call(m.querySelectorAll('svg,img'), (k) => painted(k));
+  };
+  const markerBefore = (b, textLeft, lineTop, lineBottom) => {
+    const cands = [];
+    const consider = (m) => { if (!painted(m)) return; const r = m.getBoundingClientRect(); if (r.left < textLeft - 2 && r.bottom > lineTop && r.top < lineBottom) cands.push(r.left); };
+    for (const m of b.querySelectorAll('svg,img,[aria-hidden="true"],i')) if ((m.textContent || '').trim().length <= 2) consider(m);
+    const p = b.parentElement;
+    if (p && p !== root && /flex/.test(css(p).display) && !/column/.test(css(p).flexDirection)) for (const sib of p.children) { if (sib === b) break; if (sib.matches('svg,img,i,[aria-hidden="true"]') || !(sib.textContent || '').trim()) consider(sib); }
+    return cands.length ? Math.min.apply(null, cands) : null;
+  };
+  let texts = 0;
+  let ornaments = 0;
+  for (const [b, nodes] of groups) {
+    if (!nodes.some((n) => ALNUM.test(n.data))) { ornaments += 1; continue; }
+    const rs = textRects(nodes);
+    const g = firstGlyph(nodes);
+    if (!rs.length || g === null) continue;
+    texts += 1;
+    const first = g.left;
+    const left = Math.min.apply(null, rs.map((r) => r.left));
+    const right = Math.max.apply(null, rs.map((r) => r.right));
+    const top = Math.min.apply(null, rs.map((r) => r.top));
+    const marker = markerBefore(b, first, g.top, g.bottom);
+    const s = css(b);
+    const box = b.getBoundingClientRect();
+    const parent = b.parentElement ? css(b.parentElement) : null;
+    const centredText = s.textAlign === 'center' && right - left < box.width * 0.9;
+    const centredBox = parent && /flex/.test(parent.display) && /column/.test(parent.flexDirection) && parent.alignItems === 'center';
+    const list = b.matches('li') || s.display === 'list-item' ? b.closest('ul,ol') : null;
+    const inProse = list && list.previousElementSibling && list.previousElementSibling.matches('p');
+    const block = { id: idOf(b), kind: 'text', edge: px(marker !== null ? marker : first), left: px(Math.min(left, marker !== null ? marker : left)), right: px(right), top: Math.round(top) };
+    if (marker !== null) block.textEdge = px(first);
+    if (centredText || centredBox) block.role = 'centred';
+    else if (inProse) block.role = 'list-item';
+    owners.push(b); lines.push({ top: g.top, bottom: g.bottom }); rects.push(rs); rawLeft.push(Math.min(left, marker !== null ? marker : left)); words.push(nodes.map((n) => n.data).join('').trim());
+    blocks.push(Object.assign(block, within(b, true)));
+  }
+  const ctlGroups = new Map();
+  for (const el of all) { if (!isControl(el) || inTable(el) || (el.parentElement && inControl(el.parentElement))) continue; const p = el.parentElement || root; if (!ctlGroups.has(p)) ctlGroups.set(p, []); ctlGroups.get(p).push(el); }
+  let controls = 0;
+  for (const [p, els] of ctlGroups) {
+    const rs = els.map((e) => e.getBoundingClientRect());
+    const topRow = Math.min.apply(null, rs.map((r) => r.top));
+    let firstEl = null; let firstR = null;
+    els.forEach((e, i) => { const r = rs[i]; if (r.top - topRow < r.height / 2 && (!firstR || r.left < firstR.left)) { firstEl = e; firstR = r; } });
+    let edge = firstR.left;
+    if (!bounded(firstEl)) { const tw = document.createTreeWalker(firstEl, NodeFilter.SHOW_TEXT); const ns = []; for (let n = tw.nextNode(); n; n = tw.nextNode()) ns.push(n); const g = firstGlyph(ns); if (g) edge = g.left; }
+    controls += 1;
+    const ps = css(p);
+    const centred = ps.justifyContent === 'center' || (ps.textAlign === 'center' && !/flex|grid/.test(ps.display));
+    const block = { id: idOf(p) + ' [controls]', kind: 'controls', edge: px(edge), left: px(Math.min.apply(null, rs.map((r) => r.left))), right: px(Math.max.apply(null, rs.map((r) => r.right))), top: Math.round(topRow) };
+    if (centred) block.role = 'centred';
+    owners.push(firstEl); lines.push({ top: firstR.top, bottom: firstR.bottom }); rects.push(rs); rawLeft.push(Math.min.apply(null, rs.map((r) => r.left))); words.push('');
+    blocks.push(Object.assign(block, within(firstEl, true)));
+  }
+  // Rows (decided 2026-10-01, read by geometry 2026-10-02): items set on one line, however the CSS sets them. An item
+  // after another measured item on its line that holds one block (a text, a control, or a box holding at most one
+  // text) belongs to the row and is not measured; an item with a stack inside it is a column.
+  const dropped = new Set();
+  const sameLine = (a, b) => Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) > Math.min(a.bottom - a.top, b.bottom - b.top) / 2;
+  const contains = (o, el) => o === el || o.contains(el);
+  const innerTexts = (i) => owners.map((el, k) => k).filter((k) => k !== i && blocks[k].kind !== 'surface' && contains(owners[i], owners[k]));
+  const isPill = (i) => blocks[i].kind === 'surface' && innerTexts(i).length <= 1 && !owners.some((el, k) => k !== i && blocks[k].kind === 'surface' && contains(owners[i], el));
+  const itemOf = (el, other) => { let e = el; while (e.parentElement && e.parentElement !== root && !e.parentElement.contains(other)) e = e.parentElement; return e; };
+  for (let i = 0; i < blocks.length; i += 1) {
+    if (blocks[i].kind === 'surface' && !isPill(i)) continue;
+    const before = blocks.findIndex((bj, j) => j !== i && bj.within === blocks[i].within && !(bj.kind === 'surface' && !isPill(j)) && !contains(owners[j], owners[i]) && !contains(owners[i], owners[j]) && rects[j].some((r) => sameLine(r, lines[i]) && r.right <= rawLeft[i] + 1));
+    if (before < 0) continue;
+    // A number or bullet in front of a text on its line is a hanging marker, not a row: the pair is one block with two
+    // edges, the marker's and the text's.
+    if (blocks[i].kind === 'text' && blocks[before].kind === 'text' && /^[\p{N}\p{P}\p{S}]{1,3}$/u.test(words[before])) {
+      blocks[i] = Object.assign({}, blocks[i], { edge: blocks[before].edge, left: Math.min(blocks[i].left, blocks[before].left), textEdge: blocks[i].edge });
+      delete blocks[i].role;
+      dropped.add(before);
+      continue;
+    }
+    const item = itemOf(owners[i], owners[before]);
+    const inside = owners.map((el, k) => k).filter((k) => contains(item, owners[k]) && blocks[k].kind !== 'surface');
+    const boxes = owners.map((el, k) => k).filter((k) => contains(item, owners[k]) && blocks[k].kind === 'surface' && k !== i);
+    if (blocks[i].kind === 'surface') { if (boxes.length === 0) { dropped.add(i); for (const k of innerTexts(i)) dropped.add(k); } continue; }
+    if (inside.length === 1 && boxes.length === 0) dropped.add(i);
+  }
+  const kept = blocks.filter((_, i) => !dropped.has(i));
+  // Placeholders: a frame with no text in ink shows nothing to evaluate, whatever controls or boxes it draws.
+  return { blocks: kept, placeholdersOnly: texts === 0, skipped: { rowItems: dropped.size, ornaments } };
+})()`;
+
+const KINDS: readonly EdgeBlock['kind'][] = ['text', 'controls', 'surface'];
+const ROLES: readonly NonNullable<EdgeBlock['role']>[] = ['list-item', 'table', 'centred', 'placeholder'];
+const isKind = (v: unknown): v is EdgeBlock['kind'] => KINDS.some((k) => k === v);
+const isRole = (v: unknown): v is NonNullable<EdgeBlock['role']> => ROLES.some((r) => r === v);
+const num = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const field = (o: object, key: string): unknown => Reflect.get(o, key);
+
+/**
+ * The probe's typed read: `null` when the page had no `#root` or returned something else, so a failed measurement is
+ * reported as unmeasured and never read as "no offsets". A malformed block fails the whole read for the same reason.
+ */
+export function parseEdgeProbe(value: unknown): EdgeProbe | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const raw = field(value, 'blocks');
+  const placeholdersOnly = field(value, 'placeholdersOnly');
+  if (!Array.isArray(raw) || typeof placeholdersOnly !== 'boolean') return null;
+  const skippedRaw = field(value, 'skipped');
+  if (typeof skippedRaw !== 'object' || skippedRaw === null) return null;
+  const rowItems = field(skippedRaw, 'rowItems');
+  const ornaments = field(skippedRaw, 'ornaments');
+  if (!num(rowItems) || !num(ornaments)) return null;
+  const blocks: EdgeBlock[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== 'object' || entry === null) return null;
+    const [id, kind, edge, left, right, top] = ['id', 'kind', 'edge', 'left', 'right', 'top'].map((k) => field(entry, k));
+    const [within, textEdge, role] = ['within', 'textEdge', 'role'].map((k) => field(entry, k));
+    if (typeof id !== 'string' || !isKind(kind) || !num(edge) || !num(left) || !num(right) || !num(top)) return null;
+    if (within !== undefined && typeof within !== 'string') return null;
+    if (textEdge !== undefined && !num(textEdge)) return null;
+    if (role !== undefined && !isRole(role)) return null;
+    blocks.push({
+      id,
+      kind,
+      edge,
+      left,
+      right,
+      top,
+      ...(within !== undefined ? { within } : {}),
+      ...(textEdge !== undefined ? { textEdge } : {}),
+      ...(role !== undefined ? { role } : {}),
+    });
+  }
+  return { blocks, placeholdersOnly, skipped: { rowItems, ornaments } };
+}