@adia-ai/adia-ui-forge 0.8.58 → 0.8.60

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -154,7 +154,13 @@ for any constant or decision lives in git and PR descriptions
 7. **Registry ↔ catalog parity.** A component in the runtime registry but
    missing from catalog schemas silently drops from generated compositions —
    `npm run check:registry-catalog-coherence` guards it; run it after catalog
-   changes.
+   changes. `packages/gen-ui/a2ui/registry.js` is Class R (ADR-0069,
+   gh#3055): never hand-edit it — a new component enters through its yaml
+   `component:`/`tag:` fields, an alias or native-element mapping through
+   `packages/gen-ui/a2ui/registry.exceptions.json`, then
+   `node scripts/build/a2ui-registry.mjs` (derived-resync regenerates it on
+   main; `check:a2ui-registry` is the advisory freshness gate,
+   `check:a2ui-registry:validate` the blocking validity gate).
 8. **Multi-turn emits A2UI `updateComponents` messages, not new compositions.**
    The chunk-refiner mutates the binding plan via four ops (`rebindSlot` /
    `appendToSlot` / `removeFromSlot` / `replacePage`); state chains via
@@ -187,6 +193,30 @@ for any constant or decision lives in git and PR descriptions
     SoT); ADR-0097 rules a fourth, `traits`, but that part is decided-not-
     yet-shipped (gh#2513) — see `primitive-authoring/references/
     yaml-contract.md` §Synthesized universal props for the full contract.
+14. **Provider "extended thinking" is a strategy-level opt-in, not a
+    global default** (gh#3516, LLD-0033). PR #3511 (gh#3477) made
+    `{ thinking, thinkingBudget }` reachable through
+    `AdiaUILLMBridge.complete()`/`stream()`, default off; two call sites
+    opt in for real, each behind its own fixed-constant budget rather than
+    a caller-threaded option: `generate-thinking.js`'s own generate call
+    (`THINKING_BUDGET_MONOLITHIC_THINKING`) and `free-form-composer/
+    index.js`'s ingredient-picker call, both its primary pick and its own
+    paraphrase-retry (`THINKING_BUDGET_FREE_FORM`), both starting at the
+    bridge's own `DEFAULT_THINKING_BUDGET` (10000). `auto` inherits
+    through the free-form picker call the moment it escalates that far -
+    `monolithic-thinking` itself is never reachable via `auto`'s own
+    escalation ladder. Every other LLM call site (`generate-pro.js`'s four
+    branches, zettel's locator/modifier/synthesizer, the shared
+    `validate-and-repair.js` repair loop) stays thinking-off deliberately,
+    a narrow first pass pending real eval numbers - do not assume a new
+    engine inherits thinking by proximity to one that has it.
+    `StubLLMAdapter` accepts and records `thinking`/`thinkingBudget` on
+    its own `calls` log for strategy-level test assertions.
+    `eval-diff.mjs` gained `--mode` (`instant`/`pro`/`thinking`), scoped
+    to `--engine mcp` only, so `--engine mcp --mode thinking` exercises
+    the opted-in path independently of the router's own default. See
+    `docs/ops/lld/lld-0033-strategy-thinking-opt-in.md` for the full
+    decision record and the conductor's D1-D5 rulings.
 
 ## Test + run commands (all verified in root package.json)
 

package/skills/component-md-authoring/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   component's states, composed children, aria behavior, or error/empty/
   loading handling changes and it already has (or should grow) a
   `component.md`, or when asked to "add component.md for X" / "write the
-  screen-reader spec for X" / "why did check:component-md-fresh fail". NOT
+  screen-reader spec for X" / "why is check:component-md-fresh warning". NOT
   the yaml prop/slot/event/token contract itself (primitive-authoring owns
   that — this skill only owns the two authored yaml fields,
   `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui
@@ -39,14 +39,16 @@ regenerated from them. This is deliberate, not incidental:
   gaps — screen-reader and behavioral judgment — get the SAME treatment:
   authored once, in yaml, transcluded everywhere else (component.md today;
   gen-ui corpus derivation once a2ui-maintenance wires it in).
-- **The freshness gate is PR-blocking, not staleness-only.** Because the
-  authored content lives in a yaml field, `component.md` is 100%
-  mechanically regenerable — `check:component-md-fresh` can do a real byte-
-  diff, the same shape as `check:reference-docs-fresh`, except PR-blocking
-  (operator ruling 2026-08-31) rather than advisory-only. A hand-edit
-  directly in `component.md` will be silently clobbered by the next
-  `npm run docs:component-md` and will fail the gate as "not fresh" — this
-  is the guard rail, not a bug.
+- **`component.md` is Class R, derived on main, not authored in the PR
+  (gh#3172, ADR-0069).** Because the authored content lives in a yaml
+  field, `component.md` is 100% mechanically regenerable — a PR commits
+  only the `screenReader`/`behavioral` yaml edit; `check:component-md-fresh`
+  runs advisory-only inside `check:pr-ready` (WARN, never fails the run)
+  and the `push: main` `derived-resync` job regenerates `component.md`
+  itself once the PR merges. A hand-edit directly in `component.md` will
+  still be silently clobbered by the next `npm run docs:component-md` or
+  by `derived-resync` on main — that's the guard rail, not a bug, even
+  though nothing blocks the PR on it.
 
 ## Authoring a component's two sections
 
@@ -79,7 +81,7 @@ regenerated from them. This is deliberate, not incidental:
    ```bash
    node scripts/build/components.mjs --validate   # schema-valid yaml
    npm run docs:component-md                      # regenerate component.md
-   npm run check:component-md-fresh                # PR-blocking gate
+   npm run check:component-md-fresh                # advisory gate (check:pr-ready); derived-resync owns main
    ```
 
 6. If this is the component's FIRST component.md (yaml previously had
@@ -110,7 +112,9 @@ defeats the point of a rollout plan).
 - `scripts/schemas/component.yaml.schema.json` — `intent`/`screenReader`/
   `behavioral` field definitions (all optional; a component with a `.yaml`
   but neither authored field simply has no `component.md` yet).
-- `scripts/verify/check-component-md-fresh.mjs` — the PR-blocking gate:
-  byte-freshness (component.md matches a fresh render) AND same-PR
-  coverage (a component.md-bearing component's source/yaml change must
-  touch component.md in the same diff).
+- `scripts/verify/check-component-md-fresh.mjs` — the freshness gate:
+  byte-freshness (component.md matches a fresh render). Advisory-only in
+  `check:pr-ready` (gh#3172, ADR-0069) — a PR commits the yaml edit alone
+  and `derived-resync` regenerates `component.md` on `push: main`; the
+  same-PR coverage check this gate used to run was removed outright
+  (LLD-0020 §1c), not demoted.

package/skills/demo-audit/SKILL.md

@@ -2,8 +2,8 @@
 name: demo-audit
 description: >-
   Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe,
-  app-shell QA, attr-quote typos, native-primitive leak, admin-shell
-  composition, card anatomy, plus an aggregated token/contrast/lifecycle
+  app-shell QA, attr-quote typos, native-primitive leak, shell (admin/chat/
+  editor) composition, card anatomy, plus an aggregated token/contrast/lifecycle
   drift battery (`npm run dogfood:status`). Use for "run a dogfood sweep",
   "find broken demos", "audit native primitive leaks". NOT for gen-UI
   gallery scoring (gen-ui-review) or authoring primitives (primitive-authoring).
@@ -33,7 +33,7 @@ below — load it before running or triaging.
 | 2 | App-shell QA — after `apps/` structural sweeps; before a release | [app-shell-pitfalls](references/app-shell-pitfalls.md) |
 | 3 | HTML attr-quote typo sweep — nested `"` broke an attribute boundary | [html-attr-sweep](references/html-attr-sweep.md) |
 | 4 | Native-primitive leak — `<button>` where `<button-ui>` exists | [native-leak-annotations](references/native-leak-annotations.md) |
-| 5 | Admin-shell composition — incomplete `<admin-shell>` anatomy | [admin-shell-anatomy](references/admin-shell-anatomy.md) |
+| 5 | Shell composition — incomplete `<admin-shell>` / `<chat-shell>` / `<editor-shell>` anatomy | [admin-shell-anatomy](references/admin-shell-anatomy.md), [chat-shell-anatomy](references/chat-shell-anatomy.md), [editor-shell-anatomy](references/editor-shell-anatomy.md) |
 | 6 | Card structure + anatomy docs coverage | [card-anatomy-sweep](references/card-anatomy-sweep.md) |
 | 7 | Token/contrast/lifecycle/yaml drift battery — independent of modes 1–6 | [mode7-status-battery](references/mode7-status-battery.md) |
 

package/skills/demo-audit/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Demo Audit"
-  short_description: "Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe, app-shell QA, attr-quote typos, native-primitive leak, admin-shell composition, card anatomy, plus an aggregated token/contrast/lifecycle drift battery (`npm run dogfood:status`)."
+  short_description: "Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe, app-shell QA, attr-quote typos, native-primitive leak, shell (admin/chat/ editor) composition, card anatomy, plus an aggregated token/contrast/lifecycle drift battery (`npm run dogfood:status`)."

package/skills/demo-audit/references/app-shell-pitfalls.md

@@ -4,7 +4,10 @@ Script: `node scripts/dev/audit-app-shells.mjs` (repo-local). Walks every
 `apps/<name>/…/<page>.html` shell headlessly and checks console errors,
 custom-element registration, collapsed heights, icon-ui presence, demo-root
 flex, and network 4xx/5xx. Flags: `--only=NAME` · `--fail-fast` ·
-`--compare-prod` (diff registered tags against the prod deploy).
+`--compare-prod` (diff registered tags against the prod deploy) ·
+`--playgrounds` (gh#3197 — also sweeps `playgrounds/<name>/app/<name>.html`,
+same shell shape; opt-in because that root carries other pre-existing,
+unaudited findings — combine with `--only=NAME` to scope to one playground).
 
 Prerequisites: `npm run dev` running (vite `:5173`); `npm run proxy` only when
 probing chat / gen-ui pages. If vite is mid dep-reoptimization the first sweep
@@ -42,6 +45,8 @@ with no console error, regardless of real content height.
 | `button-ui` (with `icon=`) | `icon-ui` |
 | `badge-ui` (with `icon=`) | `icon-ui` |
 | `menu-item-ui` | `icon-ui`, `text-ui` |
+| `admin-roster-ui` | `upload-ui`, `menu-item-ui` |
+| `table-toolbar-ui` | `search-ui`, `select-ui`, `menu-ui`, `menu-item-ui` |
 
 ## Registration diagnosis rules
 

package/skills/demo-audit/references/chat-shell-anatomy.md

@@ -0,0 +1,98 @@
+# Mode 5b — Chat-shell composition: the canonical parts
+
+Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
+`audit:shell-composition{,:strict,:all}`. Static AST walk over
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
+no browser needed; pre-commit fast. Shares one script and one output
+contract with the `<admin-shell>` census
+([admin-shell-anatomy](admin-shell-anatomy.md)) — the script's own `CHAT_PARTS`
+array is the mechanical census; this file is the human review standard.
+Canonical source: `packages/web-modules/chat/chat-shell/chat-shell.yaml`
+(the behavioral contract) and `playgrounds/chat/app/chat.contents.html`
+(the canonical rendered reference, cited by `apps/genui/PATTERNS.md`'s
+chrome-decision table as chat-shell's canonical demo).
+
+`gh#2909`/`apps/genui/PATTERNS.md:329-337` established that `apps/genui`
+(gen-ui, factory-chat) is a real `<chat-shell>` consumer that a
+`<admin-shell>`-only mode 5 sweep never scanned — this anatomy closes that
+blind spot.
+
+## The canonical parts
+
+1. `<chat-shell provider="…" model="…" proxy-url="…">` outer.
+2. `<chat-thread>` direct child — the message scroll surface. Required:
+   without it there is nowhere for the host's rendering pipeline to append
+   messages.
+3. `<chat-thread> > <chat-empty>` as (typically first) child — the
+   empty-state placeholder shown via the `[empty]` reflected attribute
+   before any message exists.
+4. `<chat-composer>` direct child — the input region.
+5. `<chat-composer> > <chat-input-ui>` (or `<input-ui>`) inner child — the
+   actual input; a composer with no primitive input inside has nothing to
+   submit.
+6. `<chat-header>` direct child — optional top chrome bar (name, status,
+   actions). When present, expected to carry `[slot="name"]` and
+   `[slot="status"]` (typically a `<chat-status>`) — a header with neither
+   is bare chrome with no identifying content.
+7. `<chat-sidebar slot="leading"|"trailing">` — optional conversation-history
+   or inspector rail.
+8. No generic layout primitive (`<col-ui>`, `<row-ui>`, `<stack-ui>`) as a
+   **direct child** of `<chat-shell>` — the shell's CSS lays out children by
+   tag selector (`chat-thread`, `chat-composer`, etc.); a generic wrapper
+   defeats that and the shell's `:has(chat-thread[streaming])` cross-cut
+   styling.
+
+## Severity mapping
+
+- **critical** — `<chat-shell>` present but missing `<chat-thread>` or
+  `<chat-composer>` (parts 2, 4). The shell can't render a usable
+  conversation surface without both.
+- **warning** — `<chat-composer>` has no inner `<chat-input-ui>`/`<input-ui>`
+  (part 5); a `<chat-header>` present but missing both `[slot="name"]` and
+  `[slot="status"]` content (part 6); a generic layout primitive
+  (`col-ui`/`row-ui`/`stack-ui`) authored as a direct child (part 8).
+- **info** — `<chat-thread>` missing its `<chat-empty>` first child (part 3;
+  a thread pre-seeded with real messages legitimately skips this);
+  `<chat-header>` absent entirely (part 6 is optional chrome);
+  `<chat-sidebar>` absent (part 7, forward-looking per the yaml — chat is
+  typically single-pane).
+
+## What the script flags (mechanical subset)
+
+| Symptom | Diagnosis |
+|---|---|
+| `<chat-shell>` with no `<chat-thread>` | critical — part 2 |
+| `<chat-shell>` with no `<chat-composer>` | critical — part 4 |
+| `<chat-composer>` with no `<chat-input-ui>`/`<input-ui>` child | warning — part 5 |
+| `<chat-header>` present, no `[slot="name"]` and no `[slot="status"]`/`<chat-status>` | warning — part 6 |
+| `<chat-shell>` direct child is `col-ui`/`row-ui`/`stack-ui` | warning — part 8 (legacy-generic-layout leak) |
+| `<chat-thread>` with no `<chat-empty>` child | info — part 3 |
+
+## Opt-out contract
+
+Same annotation mechanism as admin-shell: `<chat-shell
+data-shell-opt-out="reason">` downgrades every finding on that shell to
+info and prints the reason for reviewers.
+
+## Triage
+
+- Canonical product surface (`apps/genui` chat/factory-chat pages,
+  `playgrounds/chat/*`) → fix mandatory.
+- A narrow single-feature playground isolating one chat behavior → fix
+  optional; annotate the opt-out.
+- Never point this audit at `packages/web-modules/chat/**/*.examples.html`
+  or `packages/web-components/components/*/*.html` (single-primitive
+  spotlights) — the script's `isShowcaseDemo`/showcase-path exclusion
+  already keeps those out of scope, same as admin-shell.
+- `:strict` is the CI/publish posture; keep warn-only while iterating
+  locally.
+
+## Legacy shapes — never re-authored
+
+`chat-shell.yaml`'s own description lists the ADR-0024-retired legacy
+data-attribute shapes (`<section data-chat-messages>`, `<chat-input-ui
+data-chat-input>`, `<empty-state-ui data-chat-empty>`, `<header
+data-chat-name>`) as silently unrecognized, not merely deprecated. This
+audit does not re-detect them (a separate concern from anatomy
+completeness) — `verify:no-legacy-shell-shapes` in `npm run check` already
+covers that ground.

package/skills/demo-audit/references/editor-shell-anatomy.md

@@ -0,0 +1,109 @@
+# Mode 5c — Editor-shell composition: the canonical parts
+
+Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
+`audit:shell-composition{,:strict,:all}`. Static AST walk over
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
+no browser needed; pre-commit fast. Shares one script and one output
+contract with the `<admin-shell>` census
+([admin-shell-anatomy](admin-shell-anatomy.md)) — the script's own
+`EDITOR_PARTS` array is the mechanical census; this file is the human
+review standard. Canonical source:
+`packages/web-modules/editor/editor-shell/editor-shell.yaml` (the
+behavioral contract) and `apps/construct-canvas/app/construct-canvas.contents.html`
+(the canonical rendered reference, cited by `apps/genui/PATTERNS.md`'s
+chrome-decision table as editor-shell's canonical demo, alongside
+`apps/genui`'s own a2ui-editor consumer).
+
+`gh#2909`/`apps/genui/PATTERNS.md:329-337` established that `apps/genui`
+(a2ui-editor) is a real `<editor-shell>` consumer that a
+`<admin-shell>`-only mode 5 sweep never scanned — this anatomy closes that
+blind spot.
+
+## The canonical parts
+
+1. `<editor-shell>` outer.
+2. `<editor-canvas>` direct child — the central work surface. Required:
+   without it there is nowhere for artboards/document body/canvas content
+   to land, the editor equivalent of admin-shell's `<admin-content>`.
+3. `<editor-toolbar>` direct child — the app-scope top chrome bar (document
+   title, run/save/undo/redo, focus-mode toggle). Recommended; an editor
+   with no toolbar has no document-wide action surface.
+4. `<editor-canvas> > <editor-canvas-empty>` as (typically first) child —
+   the empty-state placeholder shown via the parent's `[empty]` reflected
+   attribute before any content exists.
+5. `<editor-canvas> > <editor-canvas-toolbar>` — optional canvas-scope
+   chrome (view-mode tabs, breadcrumbs) sticky to the canvas top edge;
+   distinct from part 3's app-scope toolbar.
+6. `<editor-statusbar>` direct child — bottom chrome bar (save/sync state,
+   zoom, cursor position). Recommended; loses the canonical status-strip
+   without it.
+7. `<editor-sidebar slot="leading"|"trailing">` — optional navigator or
+   inspector rail.
+8. When an `<editor-sidebar>` is present, it must wrap `<pane-ui
+   resizable>` (or at minimum `<pane-ui>`) — editor-sidebar is the one
+   bespoke shell child that **delegates** rather than duplicates a
+   primitive's resize behavior (per `shell-patterns.md`'s "FIRST bespoke
+   shell child that delegates" note); an editor-sidebar with no inner
+   `<pane-ui>` reimplements drag by hand instead of reusing the primitive.
+9. No bare `<header>` / `<footer>` native elements as direct children of
+   `<editor-shell>` — these are the ADR-0024-retired legacy chrome shapes
+   that `<editor-toolbar>` / `<editor-statusbar>` replaced.
+
+## Severity mapping
+
+- **critical** — `<editor-shell>` present but missing `<editor-canvas>`
+  (part 2). The shell can't render usable content without it.
+- **warning** — no `<editor-toolbar>` (part 3); no `<editor-statusbar>`
+  (part 6); an `<editor-sidebar>` present with no inner `<pane-ui>` (part
+  8); a bare native `<header>`/`<footer>` direct child (part 9, the
+  retired-legacy-shape leak).
+- **info** — `<editor-canvas>` missing its `<editor-canvas-empty>` first
+  child (part 4; a canvas pre-seeded with real content legitimately skips
+  this); no `<editor-canvas-toolbar>` (part 5, optional canvas chrome); no
+  `<editor-sidebar>` at all (part 7 — `construct-canvas`'s own comment
+  notes "no leading pane today", a legitimately sidebar-less composition).
+
+## What the script flags (mechanical subset)
+
+| Symptom | Diagnosis |
+|---|---|
+| `<editor-shell>` with no `<editor-canvas>` | critical — part 2 |
+| `<editor-shell>` with no `<editor-toolbar>` | warning — part 3 |
+| `<editor-shell>` with no `<editor-statusbar>` | warning — part 6 |
+| `<editor-sidebar>` present, no inner `<pane-ui>` | warning — part 8 (delegation contract violated) |
+| `<editor-shell>` direct child is native `<header>`/`<footer>` | warning — part 9 (retired-legacy-shape leak) |
+| `<editor-canvas>` with no `<editor-canvas-empty>` child | info — part 4 |
+
+## Opt-out contract
+
+Same annotation mechanism as admin-shell: `<editor-shell
+data-shell-opt-out="reason">` downgrades every finding on that shell to
+info and prints the reason for reviewers.
+
+## Triage
+
+- Canonical product surface (`apps/construct-canvas`, `apps/genui`'s
+  a2ui-editor) → fix mandatory.
+- A narrow single-feature playground isolating one editor behavior → fix
+  optional; annotate the opt-out.
+- Never point this audit at `packages/web-modules/editor/**/*.examples.html`
+  or `packages/web-components/components/*/*.html` (single-primitive
+  spotlights) — the script's `isShowcaseDemo`/showcase-path exclusion
+  already keeps those out of scope, same as admin-shell.
+- **Don't nest `<editor-shell>` inside `<admin-shell>`** as page chrome —
+  `editor-shell.examples.html` documents them as sibling surfaces, not
+  nested; this audit doesn't mechanically flag the nesting mistake (a
+  cross-shell structural rule, not a within-shell anatomy gap), but a
+  reviewer seeing both tags in one file should treat it as a design smell.
+- `:strict` is the CI/publish posture; keep warn-only while iterating
+  locally.
+
+## Legacy shapes — never re-authored
+
+`editor-shell.yaml`'s own description lists the ADR-0024-retired legacy
+data-attribute shapes (`<header>`, `<div data-editor-body>`, `<pane-ui
+data-left|data-right>`, `<div data-canvas>`, `<footer>`, `<span
+data-spacer>`) as silently unrecognized, not merely deprecated. Part 9
+above catches the two structural container tags (`<header>`/`<footer>`)
+mechanically; the finer-grained data-attribute forms are already covered
+by `verify:no-legacy-shell-shapes` in `npm run check`.

package/skills/gen-ui-review/scripts/gen-review-decompose.mjs

@@ -37,6 +37,16 @@ import { chromium } from 'playwright';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+// gh#3616: the shared overflow predicate, vendored (not import()able:
+// this script ships inside a published plugin package with no apps/ tree
+// in its files allowlist, see this repo's scripts/build/
+// overflow-detect-vendor.mjs for the derive-and-vendor build that keeps
+// this copy provably identical to apps/genui/app/_shared/overflow-detect.js).
+// Imported as an ordinary function and passed BY REFERENCE into
+// elementHandle.evaluate() below, which stringifies it into the browser's
+// page context, same mechanism scripts/qa/gen-review-decompose.mjs's own
+// (non-vendored, import()-able) copy uses.
+import { OVERFLOW_TAGS, detectOverflow } from './overflow-detect.generated.mjs';
 
 // The script lives inside the plugin but runs against the monorepo. All
 // monorepo paths are resolved from the working directory (the monorepo root),
@@ -259,7 +269,7 @@ for (const group of gallery.groups) {
     for (const engineKey of Object.keys(prompt.engines ?? {})) {
       const engineData = prompt.engines[engineKey];
       if (!engineData || engineData.dryRun) continue;
-      allPrompts.push({ group: group.slug, prompt: prompt.slug, engineKey, engineData });
+      allPrompts.push({ group: group.slug, prompt: prompt.slug, label: prompt.label, engineKey, engineData });
     }
   }
 }
@@ -321,7 +331,7 @@ const results = [];
 let renderFailureCount = 0;
 let idx = 0;
 
-for (const { group, prompt: promptSlug, engineKey, engineData } of allPrompts) {
+for (const { group, prompt: promptSlug, label, engineKey, engineData } of allPrompts) {
   idx++;
   const slug = `${group}-${promptSlug}-${engineKey}`;
   process.stdout.write(`  [${idx}/${allPrompts.length}] ${slug.padEnd(50)} `);
@@ -331,7 +341,10 @@ for (const { group, prompt: promptSlug, engineKey, engineData } of allPrompts) {
   // Each has a .gallery-canvas-wrap containing a canvas-ui.
   // We identify by matching the group anchor + prompt h3 text.
 
-  const promptLabel = promptSlug.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+  // gh#3249: use the gallery's real prompt.label (what the h3 actually renders), not a
+  // title-cased guess derived from the slug -- the two diverge whenever the authored label
+  // isn't the slug's mechanical title-case ("search-filters" vs "Search with Filters").
+  const promptLabel = label;
 
   // Scroll to the prompt section and wait for canvas settle
   await page.evaluate(({ groupSlug, label }) => {
@@ -407,41 +420,21 @@ for (const { group, prompt: promptSlug, engineKey, engineData } of allPrompts) {
   // canvas. Runs only when the canvas rendered (renderFailure = false).
   // Results land in decomposed.json as `overflowElements` — a non-empty array
   // is treated as P1 in Phase 4 regardless of the Phase 3 structural score.
-
-  const OVERFLOW_TAGS = new Set([
-    'text-ui', 'stat-ui', 'badge-ui', 'field-ui', 'button-ui',
-    'label', 'span', 'p', 'h1', 'h2', 'h3', 'h4',
-  ]);
+  //
+  // gh#3616: the predicate itself (both the TEXT-truncation and LAYOUT-
+  // overflow checks, plus every documented exclusion: hscroll boundary,
+  // <svg> subtree) now lives in overflow-detect.generated.mjs (vendored
+  // from apps/genui/app/_shared/overflow-detect.js), passed straight into
+  // elementHandle.evaluate() below rather than re-implemented here, so
+  // this plugin sweep and the in-repo QA script/live artifact pane provably
+  // run the same code. `canvasWrapEl` is the exact same `.gallery-canvas-
+  // wrap` element the screenshot/render-failure check above already
+  // resolved, so there's no need to re-locate it by groupSlug/label.
 
   let overflowElements = [];
 
   if (!renderFailure) {
-    overflowElements = await page.evaluate(({ groupSlug, label, overflowTags }) => {
-      const section = document.getElementById(`group-${groupSlug}`);
-      if (!section) return [];
-      const h3s = [...section.querySelectorAll('.gallery-prompt-heading')];
-      const h3 = h3s.find(h => h.textContent.trim().toLowerCase() === label.toLowerCase());
-      const wrap = h3?.closest('.gallery-prompt')?.querySelector('.gallery-canvas-wrap');
-      if (!wrap) return [];
-
-      const found = [];
-      function walk(el) {
-        const tag = el.tagName?.toLowerCase() ?? '';
-        if (overflowTags.includes(tag)) {
-          const style = getComputedStyle(el);
-          const hasHidden = style.overflow === 'hidden' || style.overflowX === 'hidden';
-          if (hasHidden && el.scrollWidth > el.clientWidth + 2) {
-            found.push({ tag, clippedWidth: true });
-          }
-          if (hasHidden && el.scrollHeight > el.clientHeight + 2) {
-            found.push({ tag, clippedHeight: true });
-          }
-        }
-        for (const child of el.children) walk(child);
-      }
-      walk(wrap);
-      return found;
-    }, { groupSlug: group, label: promptLabel, overflowTags: [...OVERFLOW_TAGS] });
+    overflowElements = await canvasWrapEl.evaluate(detectOverflow, OVERFLOW_TAGS);
   }
 
   // ── Primitive lookup + sanitize ──────────────────────────────────────────

package/skills/gen-ui-review/scripts/overflow-detect.generated.mjs

@@ -0,0 +1,101 @@
+// GENERATED, do not hand-edit. Source: apps/genui/app/_shared/overflow-detect.js
+// Rebuild: node scripts/build/overflow-detect-vendor.mjs
+// Freshness gate: node scripts/build/overflow-detect-vendor.mjs --verify (npm run check:overflow-detect-vendor-fresh)
+//
+// gh#3616: vendored so the gen-ui-review plugin's own decompose script (a
+// published package with no apps/ tree in its files allowlist) runs the
+// EXACT SAME overflow/clip predicate as the in-repo QA script and the live
+// artifact pane, instead of a hand-kept inline copy that can silently drift
+// (the gap gh#3616 closed, see that ticket for the pre-fix divergence).
+
+/**
+ * Tags the text-truncation check inspects for their own `overflow:hidden`
+ * clipping a2ui-root/canvas-ui render. Every other tag is still walked for
+ * the layout-overflow check below, which applies to any tag.
+ */
+export const OVERFLOW_TAGS = [
+  'text-ui', 'stat-ui', 'badge-ui', 'field-ui', 'button-ui',
+  'label', 'span', 'p', 'h1', 'h2', 'h3', 'h4',
+];
+
+/**
+ * Walks a rendered container and reports overflow/clip findings.
+ *
+ * Two independent clipping mechanisms (gh#3248):
+ *   - TEXT truncation: an element's own `overflow:hidden` clips its own
+ *     scrollWidth/scrollHeight (e.g. a Text node with no line-clamp room).
+ *     Checked only for `overflowTags` elements.
+ *   - LAYOUT overflow: an element's whole box lays out past the
+ *     container's edge, whether or not anything in its ancestor chain has
+ *     `overflow:hidden` (e.g. two sibling `[stretch]` buttons in a Row
+ *     each claiming full row width, one landing off-canvas). Checked for
+ *     every visible tag, horizontal only. Vertical overflow is never
+ *     flagged since the container is expected to scroll vertically (the
+ *     gallery's own `.gallery-canvas-wrap` is deliberately
+ *     `overflow-y: auto`), and a container never scrolls sideways so a
+ *     right-edge slice is always wrong.
+ *
+ * Both checks skip content inside a genuine horizontal-scroll boundary
+ * (table-ui's own scroll wrapper, swiper-ui, tabs-ui's overflow-x strip):
+ * content past the visible edge there is intentional, scrolled-to
+ * content, not a layout bug. Also skipped: content inside an `<svg>`
+ * subtree (icon-ui's glyph markup, chart-ui's rendered marks), since SVG
+ * coordinate-space geometry doesn't map onto DOM layout-box geometry the
+ * same way, confirmed via a live false positive on chart-ui's own
+ * sparkline. `<foreignObject>` re-enters normal HTML flow content inside
+ * that `<svg>` subtree (SVG spec), so the svg-exclusion resets for its
+ * own children rather than staying latched: a real HTML element nested
+ * there gets checked again.
+ *
+ * `container` itself is excluded from the horizontal-scroll-boundary test:
+ * per the CSS Overflow spec, pairing `overflow-y: auto` with the default
+ * `overflow-x: visible` computes overflow-x to `auto` too. Treating that
+ * as a real scroll boundary would mark every one of the container's own
+ * children as inside-hscroll and silently disable the layout-overflow
+ * check for the entire canvas, the opposite of what it exists to catch.
+ *
+ * @param {Element} container the rendered surface's outer boundary
+ *   (gen-review-decompose.mjs's `.gallery-canvas-wrap`; the live artifact
+ *   pane's own equivalent container).
+ * @param {string[]} overflowTags see OVERFLOW_TAGS; always pass this
+ *   explicitly (see the module-doc note on why there's no default value).
+ * @returns {Array<{tag: string, clippedWidth?: true, clippedHeight?: true, pushedPastContainer?: true}>}
+ */
+export function detectOverflow(container, overflowTags) {
+  const found = [];
+  const containerRect = container.getBoundingClientRect();
+  const TOLERANCE = 2; // matches the scrollWidth/clientWidth +2 slack below
+
+  function walk(el, insideHScroll, isContainer, insideSvg) {
+    const tag = el.tagName?.toLowerCase() ?? '';
+    const style = getComputedStyle(el);
+
+    if (overflowTags.includes(tag)) {
+      const hasHidden = style.overflow === 'hidden' || style.overflowX === 'hidden';
+      if (hasHidden && el.scrollWidth > el.clientWidth + TOLERANCE) {
+        found.push({ tag, clippedWidth: true });
+      }
+      if (hasHidden && el.scrollHeight > el.clientHeight + TOLERANCE) {
+        found.push({ tag, clippedHeight: true });
+      }
+    }
+
+    if (!insideHScroll && !insideSvg) {
+      const rect = el.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        if (rect.right > containerRect.right + TOLERANCE || rect.left < containerRect.left - TOLERANCE) {
+          found.push({ tag, pushedPastContainer: true });
+        }
+      }
+    }
+
+    const isHScrollRoot = !isContainer
+      && (style.overflowX === 'auto' || style.overflowX === 'scroll')
+      && el.scrollWidth > el.clientWidth + TOLERANCE;
+    const nowInsideSvg = tag === 'foreignobject' ? false : (insideSvg || tag === 'svg');
+    for (const child of el.children) walk(child, insideHScroll || isHScrollRoot, false, nowInsideSvg);
+  }
+
+  walk(container, false, true, false);
+  return found;
+}