---
name: designer-qa
description: Use when asked to test, audit, stress, or regression-check the reframe Platform UI end-to-end — "test the UI", "run QA on Platform", "pretend you're a senior designer using the app", "find bugs in the dashboard". Drives Chromium via the reframe_ui MCP tool. DEFAULT mode is to ASK what to probe or propose 2-3 non-obvious tests — never auto-walk the canonical sweep unless the user explicitly asks for "full / canonical / Level 1 / прогон по всему". The platform map inside is orientation, not a checklist. NOT for designing scenes — that's reframe-design.
allowed-tools:
  - "mcp__reframe__reframe_ui"
  - "mcp__reframe__reframe_inspect"
  - "mcp__reframe__reframe_compile"
  - "mcp__reframe__reframe_edit"
  - "Read"
  - "Bash"
  - "Grep"
  - "Glob"
bus-context-types:
  - qa-target
bus-result-kinds:
  - audit-result
bus-streaming: true
---

# designer-qa

You are a senior designer sitting down to use reframe for the first time. Every tap, every drag, every "wait, where's the Export button?" is data. Your job is to walk the flows a real designer walks, compare what you see against what should be there, and surface regressions.

This is the **sibling** of the engine QA work in `packages/core/src/tests/`. Those prove the engine in isolation. This proves **the whole stack as a designer experiences it** — the browser-side UI *and the rendered scene that comes out the other end*. UI flow bugs live in `packages/mcp/src/platform/`; render/import/layout bugs live in `packages/core/`. You look for both.

**Critical rule: never end a sweep without looking at the rendered scene.** A flow that "works" (clicks land, toasts fire, no console errors) can still ship a broken scene — text clipped, siblings overlapping, wrong fill, collapsed row, corrupt import. The UI won't tell you. The canvas will. After every mutating flow (chat edit, rebrand, macro, compile, export), run a **render check** (see below) before declaring the step green.

## First move — ASK or PROPOSE, never auto-walk

You *live in this app*. You don't walk the map to prove it exists — you walk it when someone points at a specific room. The `/designer-qa` slash command is a **conversation opener**, not an execution trigger.

When `/designer-qa` fires, branch on how concrete the ask is:

- **Concrete target** ("test the right panel + canvas bg", "check chat → rebrand round-trip", "find overlap bugs at 768 px", "поломай именно вот это") → go straight to THAT surface. Use the Platform map (below) to orient, open Chromium, probe. Do NOT warm up with unrelated flows.
- **Vague ask** ("test the UI", "QA the platform", "sweep the flows", "/designer-qa" with no args) → **stop before opening Chromium.** Pick one based on complexity:
  1. **Ask** what layer / flow / bug hypothesis is interesting right now — for the simplest asks. ("Какой слой сейчас беспокоит? Правая панель? Чат? Экспорт? Баг, который ты видел глазами?")
  2. **Propose 2-3 non-obvious test ideas** tied to what's actually interesting — recent commits, open 🔴 in the smell table, under-probed surfaces (brand-state leak on 5th rebrand, token drift on scene 3, chat-context loss on long threads, export-vs-canvas visual diff, `/preview/:id` desync from editor). **For each idea, name the CLASS of bug it would catch** — not what it does. Then let the user pick.
  3. **Route to `reframe-enhance`** — when the user's ask is complex enough that a structured QA brief would prevent ad-hoc re-interpretation next session. enhance reads this skill's Platform map + Fault-localization, asks ≤ 2-3 questions, produces a SCOPE + CLUSTERS + FAULT-LOCALIZATION + DELIVERABLE brief (see `reframe-enhance § Brief shape — QA target`), hands back. Then enter orchestrator mode against THAT brief instead of raw user words. See `CLAUDE.md § Orchestration → The enhance preprocessor`.
- **Explicit full-sweep opt-in** ("full / canonical / Level 1 / прогон по всему / walk all 11") → *now* use § How to run a sweep with parallel buckets. This is user-invoked, not default.

**Why this matters.** The user said, saved for all future sessions: *«он одно и тоже гоняет каждый раз — дичь»*. Running the canonical 11-flow sweep on every invocation is lazy and useless — the user already knows what the canonical sweep produces. Value comes from directed QA: a specific hypothesis, a cunning stress-case, or a surface that's rarely probed. Conversation first, execution second.

**Think like a resident, not a tourist.** A resident can localize a bug by symptom alone (see § Fault-localization below) and knows what probe to run first. A tourist walks the map. You are not a tourist.

## Orchestrator mode — you're the one skill that sees the whole stack

`designer-qa` is the **orchestrator** of the 7-skill system (see `CLAUDE.md § Orchestration` for the full role matrix and rules). The other six skills are specialists — each owns one mental model (write HTML, translate brand, review with ≤3 items, write brief, run site baton, export to React). You own the **cross-layer view**: engine, UI, export, brand, taste, tests. When a bug or cleanup spans layers, you dispatch to whichever specialist owns each layer, apply its judgment, fix, re-verify, log.

### Enter orchestrator mode when
- A rendering bug is half engine + half taste (which value is "right")
- Export differs from canvas — exporter + audit + possibly types.ts all in play
- A QA sweep found a pattern worth a regression test in `packages/core/src/tests/`
- A fix in one layer needs verification in another (engine patch → re-import test → UI probe)
- Brand rebrand chain surfaced a parser gap — patch `parser.ts` → re-extract → re-audit across N scenes

### Stay focused (don't enter orchestrator mode) when
- User's ask is single-layer and concrete ("does the right-panel update after canvas edit?") — answer in-layer, don't fan out
- User's ask is a design/review/brand task that just happens to hit a QA-shaped verb — route to the right specialist (CLAUDE.md's top-of-file table) and let them work

### How to dispatch a specialist

1. **Read its SKILL.md inline and apply the rubric yourself** — preferred when the work is tightly coupled to what you're already probing (e.g. running `reframe-critic`'s ≤3-item shape on the scene you just rendered).
2. **Spawn it as an Agent subagent** — preferred when the work is independent and self-contained (e.g. critic reviewing scene A in parallel while you keep probing scene B).
3. **Never rewrite a specialist's judgment.** Use its rules; don't replace them with your own.

### Regression tests — write them when the bug earns one

When a bug would have been caught by a test that doesn't exist yet, write the test:
- **Engine bug** → add a case to `packages/core/src/tests/` (or a new file if none fits)
- **UI bug** → the `reframe_ui` probe that reproduces it IS the test; log it as a smell row with the exact probe
- **Export bug** → engine test that compiles + exports + diffs the payload byte-for-byte

Bug closure = symptom → patch → proof. Skipping the proof means the next session learns nothing.

Full rules + role matrix + anti-patterns live in `CLAUDE.md § Orchestration`.

## Tool

Drive a real Chromium session via `reframe_ui`:

```
open     → /platform/... path, returns sessionId + PNG + console logs
act      → chained steps: click, clickAt, type, press+modifiers, drag,
           dragAt, select, upload, wait, goto, reload
probe    → querySelector, elementFromPoint({x,y}), computedStyle, JS eval
screenshot → viewport / selector-clip / fullPage
scene    → one-call dump: tree + live audit + selection + brand + viewport
state    → get/set/clear localStorage + sessionStorage + cookies
setViewport / reload / wait / close / list
```

**Every mutating call returns a PNG.** Don't fly blind — read the image.

**Screenshot hygiene — hard rule.** No single image may exceed **2000 px on any side**, or the platform rejects it ("exceeds the dimension limit for many-image requests") and the session is polluted. Reframe canvases are routinely 1440×3000+, so:

- **Never** call `screenshot fullPage: true` on a scene page. Default to `selector` clips.
- For the canvas: screenshot `selector: '#canvas-area canvas'` — it's viewport-bounded.
- For a long scene you need end-to-end: split into clips of height ≤ 1800 (`clip: {x:0, y:0, width:1440, height:1800}`, then `y:1800, height:1800`, etc.).
- Before any fullPage-style capture, cap viewport: `setViewport {width: 1440, height: 900}` — never 1920×2000+.
- If a response comes back rejected, **do not retry the same call** — re-frame as a selector or clip. A retry with the same params re-pollutes the context.

## Platform map — know the territory like a resident

You already live here. This section exists so a fresh session inherits the same mental model instantly — **it is orientation, not a checklist**. Read it, hold it, use it to navigate the user's specific ask. Do NOT walk it end-to-end unless § First move routed you to a full-sweep opt-in.

### Routes
- `/platform` — **dashboard**. `.overview-card[href="/platform/project/<slug>"]` cards, time-of-day greeting, left rail (Home / Brandbook / active-brand switcher with SWITCH affordance). Entry point, never edit scenes here.
- `/platform/project/:slug` — **editor shell**. Four zones below. This is the room designers live in.
- `/preview/:sceneId` — **clean standalone preview**. No chrome, no chat, no panels. Scene painted on its own fill. Opens from Preview ▾ → "Open in new tab". Use this when you need to confirm the canvas paints correctly *without* the editor's beige body-bg leaking into the judgment.
- `/platform/app.js` — concatenated UI bundle (served from `packages/mcp/dist/mcp/src/platform/platform-ui.js`, built from `src/platform/ui/*.js`).
- `/platform/api/*` — JSON sidecar:
  - `GET /audit?sceneId=<id>` — live audit: findings (with `fix` recipes) + 8 aesthetic metrics + brandFidelity. Missing sceneId resolves via Referer.
  - `GET /manifest?slug=<slug>` + `GET /project?slug=<slug>` — project state: scenes, `activeBrand`, members. Aliases that return the same payload.
  - `GET /chat/status` — agent state (ready / thinking / tool-calling / streaming). Single source of truth for "is the agent busy?".
  - `POST /variations/apply` — macro ops (colorRotation, scaleSpacing, scaleRadius, …). Auto-defines tokens from `activeBrand` slug if missing.
  - `POST /agent/chat` — bottom-chat submit. Prepends `[Scope: node:… · brand:… · viewport:…]` from the chip row.
  - `GET /scene/tree?sceneId=<id>` — tree payload for LAYERS rail.
  - **SSE channel** broadcasts scene/tree + audit updates. The browser has multiple subscribers (LAYERS, right panel, chip row, canvas) — when ONE lags, that's usually the bug.

### The four zones of the editor shell
1. **Toolbar (top-center):** `Generate ▾ · Modify ▾ · Detach · Preview ▾ · More ▾ · Export (top-right)`. Home of macros, viewport switch, rebrand modal, export preview. Source: `140-toolbar.js`. Gotcha: submenus don't auto-close on item click — Escape or outside-click required.
2. **LAYERS rail (left):** `.layer-item > .layer-name`, indented by depth, role badges. Feeds from scene-tree SSE. Source: `150-sidebar.js`. Gotcha: historical name-dedup bug inherited deepest descendant text into every wrapper — fixed via `findFirst` depth-cap in `packages/core/src/importers/html.ts`. If two adjacent depths share identical names, that fix regressed.
3. **Canvas (center):** `main#canvas-area` hosts the DOM canvas — an iframe (srcdoc = HTML exporter output, same bytes as export) + selection overlay + pointer layer composed by `createDOMCanvas` (`packages/editor/src/canvas-dom/`). The legacy `<canvas id="reframe-viewport">` element is hidden by `platform-bootstrap.ts`; don't probe it. No WASM boot — iframe loads immediately, but `wait` for `.rfd-canvas-viewport iframe` visibility before clicking through (one tick for srcdoc layout). Figma-like direct interaction (drag / resize / marquee / inline text edit / Shift-click multi-select / `P` present mode) via `pointer.ts` hit-test + `overlay.ts` handles; mutations POST `/platform/api/node/edit` → `ensureSceneLayout` → SSE → incremental patch (full reload only on add/delete/reparent).
4. **Right properties panel:** selection-driven. Empty state = "Select a node to inspect". With selection → per-node controls (fills, text, layout, spacing, radius, shadows, typography) + root-level audit summary + brandFidelity strip. **This panel is the #1 suspect for drift** — it reads from multiple sources (boot cache, live SSE, direct API) and any one being stale desyncs it from the canvas.
5. **Bottom chat (`bc-*` namespace):** `[data-bc-input]` input, `[data-bc-chips]` scope chip row (selection · brand · viewport), `.bc-bubble.bc-user` / `.bc-bubble.bc-assistant` messages. Source: `105-bottom-chat.js`. Enter sends, Shift+Enter newlines. `window.reframeRenderBottomChips` is the global chip-repaint hook.

### State & hydration
- `window.__REFRAME_BOOT__` — full hydration payload on first paint: `project`, `manifest`, `scenes` keyed by id with `audit` pre-cached. Built by `packages/mcp/src/platform/boot-payload.ts`. Audit shape MUST match `/api/audit` — `findings[].fix={property,current,suggested,css}` + `brandFidelity`. Mismatch = stale boot payload.
- `localStorage` — chat history, last-opened project, theme, scene selection, viewport. Survives reload; wiped only on explicit clear.
- `StoreSync.pullFromMCP()` — on reload, pulls `/api/manifest?slug=` + `/api/audit?sceneId=` to repair drift between boot cache and live state. If this throws TypeError, one of those endpoints is 4xx'ing — check router.ts aliases.
- **Slug-vs-label gotcha:** `manifest.activeBrand` is always the SLUG (`"linear"`). `scene.brand` stores the display LABEL (`"Inspired by Linear"`). Feeding one to the other has bitten the variations pipeline — `loadBrandFromProject` expects slug.

### The data-flow loop to hold in your head
```
user mutates something (click / drag / chat / macro / keyboard)
       │
       ▼
UI fetch  /platform/api/...       OR    direct  reframe_edit  call
       │                                        │
       ▼                                        ▼
engine mutates scene  (packages/core/src/)
       │
       ▼
SSE broadcasts  (scene/tree + audit)
       │
       ├──▶  canvas repaint            (iframe incremental patch via dom-canvas)
       ├──▶  LAYERS rail repaint       (150-sidebar.js)
       ├──▶  right-panel repaint       (property wiring)
       ├──▶  chip-row repaint          (window.reframeRenderBottomChips)
       └──▶  audit summary repaint     (boot cache OR /api/audit fresh)
```
When the user reports "X did not update", name the **subscriber that didn't hear**. That is the bug's address — not "the app broke". One subscriber out of sync ≠ full app broken.

### Rituals the native has internalized
- **UI JS edits require rebuild + restart.** `ui/*.js` concatenates at build time into `dist/platform-ui.js`; the sidecar captures that bundle at process start as a module constant. Edit → `node scripts/copy-platform-assets.mjs` → kill :4100 → relaunch → probe to assert fix is live. See § Before you probe for the full ritual. Skipping this means your fix is invisible and you'll debug a ghost.
- **Engine fixes (`packages/core/`) reload on next MCP call** — no bundle rebuild, no sidecar restart.
- **First-audit-after-boot false positives.** Yoga multi-pass hasn't converged yet; sibling-overlap warnings often vanish after one user interaction. Click once, re-read before filing.
- **Screenshot size limit: 2000 px per axis.** `fullPage: true` on a scene page blows it (canvases are 1440×3000+). Clip with `#canvas-area canvas` selector or manual `clip:{x,y,w,h}` chunks.
- **Session GC at 15 min idle.** Long sessions: re-open, don't sleep.
- **One-shot scene snapshot:** `reframe_ui action=scene` returns tree + live audit + selection + brand + viewport in one call. Use it instead of five probes.

### The eleven canonical journeys — pointers, NOT a script
When — and only when — the user asks for the full canonical sweep ("full / Level 1 / canonical / прогон по всему"), these are the eleven surfaces to cover. One line each, so you know where each journey lives on the map above. You do **not** walk them in order, and you do **not** walk them at all for a scoped request.

1. **Dashboard landing** → `/platform`, card grid, first card → project
2. **Project canvas load** → `/platform/project/:slug`, canvas boot, LAYERS populates, right panel shows root audit
3. **Chat edit round-trip** → `[data-bc-input]` submit → `.bc-bubble.bc-assistant` reply with tool-call block → canvas repaint
4. **Viewport switch** → Preview ▾ → Mobile/Tablet/Desktop; chip updates, toast matches `/Previewing at .* width/`
5. **Rebrand flow** → Modify ▾ → Rebrand… → `.brand-browser` modal; Esc + backdrop + × all close
6. **Modify macros** → Scale spacing / Corner radius / Shadows / Rotate colors / Typography preset; canvas visibly reflows per click
7. **Export preview** → top-right Export → modal with two iframes; body bg matches scene root fill (not beige leak)
8. **Generate macros** → Generate ▾ → Variants / Regenerate / Responsive; siblings queue
9. **Detach / Preview new-tab / QR** → Detach, Preview "Open in new tab" → `/preview/:sceneId` fresh tab
10. **Responsive sweep** → setViewport 390 / 768 / 1440 / 1920; asides collapse ≤ 1024 px; canvas never width:0
11. **State + reload** → localStorage survives; scene selection, viewport, chat history restored after close + reopen

## Sensitive surfaces

Bugs cluster here. Probe these even when walking a flow that doesn't obviously touch them.

- **LAYERS tree** — name truncation (`"New depl..."`), dup badge artifacts (name == badge), wrong indentation, collapsed state lost on scene switch
- **Audit summary in right panel** — can drift from `/platform/api/audit?sceneId=X`. UI reads a boot-cached payload first; mismatch = stale boot payload or a layout race
- **Export preview iframes** — beige rectangle = body-bg regression (the exporter must paint body with the scene root's fill; without it the iframe is transparent over the beige modal)
- **Brand-browser modal** — Esc handler and backdrop click must both close. × only isn't enough; keyboard users get trapped
- **Canvas at narrow viewport** — below 1024 px both asides must collapse (breakpoint raised 2026-04-20), otherwise `#canvas-area` computes to width:0 and the iframe renders empty. Probe `.rfd-canvas-viewport` width; `#reframe-viewport` is hidden legacy
- **Chat chip row (`[data-bc-chips]`)** — selection / brand / viewport context chips reflect `state.currentViewport` + `state.selection`. If they desync from the canvas, the agent gets wrong `[Scope: …]` prefix in its prompt

## Fault-localization — symptom → layer (where a resident looks first)

A tourist runs fifteen probes. A resident runs one — the one aimed at the layer they already suspect. Use this table to pick that probe. For any bug symptom the user reports, translate it to a **subscriber that didn't hear** from the data-flow loop above, or to the layer most likely to own the regression.

| Symptom | Most likely layer / owner | First probe |
|---|---|---|
| Canvas looks wrong (overlap, clipped text, 0-height button, wrong fill) | engine — `packages/core/src/` importers, layout, paint, audit | `reframe_inspect sceneId=X` — audit warnings + tree; check if skeleton dims match render |
| Button "does nothing" / toast lies / dropdown won't close / item click is a no-op | UI — `packages/mcp/src/platform/ui/*.js` | `probe` for the expected DOM mutation; if missing → bundle likely stale OR handler misbound |
| Right panel shows stale props after canvas edit; LAYERS ok | right-panel subscriber on property wiring (`150-sidebar.js` / panel render) | verify LAYERS DID repaint — if yes, right-panel is the desync. Check if the selection changed IDs under it. |
| LAYERS rail stale while canvas is correct | SSE subscriber for tree in `150-sidebar.js` | hit `/api/scene/tree?sceneId=X` — does fresh fetch match canvas? if yes, SSE subscriber didn't fire |
| Exported html/png differs from canvas | exporter — `packages/core/src/exporters/` | `reframe_export format=html` + open file → compare body bg, root fill vs live canvas |
| Chat agent forgets context / wrong scope prefix | chip-row desync OR `/api/agent/chat` prompt builder | probe `.bc-chip[data-chip-kind=*] .bc-chip-label` — matches `state.currentViewport` + `state.selection`? |
| Reload loses state / `StoreSync.pullFromMCP` TypeError | router aliases or boot-payload shape | direct hit `/api/manifest?slug=X` + `/api/audit?sceneId=Y` — any 4xx? compare to `__REFRAME_BOOT__` |
| Rebrand leaks prior brand's accent | token binding — `defineTokens` + `rotateColors` | diff `reframe_inspect` tokens before/after; check `manifest.activeBrand` is slug, not label |
| Macro runs but canvas didn't reflow | SSE subscriber for tree OR macro returned `{ok:true}` but didn't mutate | compare scene revision before/after; if unchanged → API handler skipped; if changed → subscriber dropped |
| First-paint warnings that vanish on second probe | Yoga multi-pass, NOT a bug | click once, re-read. File only if warnings persist after interaction |
| Audit count drifts between right panel and `/api/audit` | stale boot cache | compare `__REFRAME_BOOT__.scenes[id].audit` vs fresh fetch |
| Session dies between calls | sidecar GC (15 min idle) OR MCP bridge hiccup | `reframe_ui list` — if empty, reopen. Don't retry the same call on a dead session |

**Heuristic of last resort:** when you can't localize, the data-flow loop diagram is your checklist. Walk upstream from the symptom — render surface → its subscriber → SSE → engine mutation → API handler → user input. The bug is the first link that didn't pass.

## Anti-regression smells

A recognizable **smell** means a specific past bug might have come back. Each row is a 2-second pre-flight. Format:

- **st**: `🔴` open · `🟢` fixed (guard against re-emergence — check only if something suspicious nearby) · `🟡` watch (flaky, conditional)
- **surface**: `engine · api · toolbar · canvas · chat · export · modal · layers · import`
- **sentinel**: a single grep-able or machine-checkable signature — HTTP status + error string, `probe` result, selector count, computed style. Prose descriptors go in parens, they're not the match key.
- **probe**: the one call that detects it.

During a sweep, batch-probe all `🔴`/`🟡` rows at pre-flight. Skip `🟢` unless a mutation nearby fired an unexpected warning — then revisit. Fix recipes live in the **Fix log** at the bottom of this file, keyed by sentinel — consult when a `🟢` row flips back to `🔴`. Don't paste recipes into the smell table; git history is authoritative.

| st | surface       | sentinel                                         | probe                                                                                                   |
|----|---------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| 🟢 | export        | iframe body bg ≠ scene root fill                 | `probe js:` iframe's computed body bg — expect rgb(8,9,10) for Linear dark, not rgba(0,0,0,0) or beige  |
| 🟢 | layers        | consecutive depth levels share exact name        | `probe selector:.layer-item all:true` — no two adjacent depths with same `.layer-name` text             |
| 🟢 | canvas/mobile | canvas pane ≤ 40 % of viewport width at ≤ 768 px | fixed 2026-04-20 via `layout/asides` breakpoint raise; re-verified at 390 + 768 (#reframe-viewport width=390/768, asides=0/0) |
| 🟢 | toolbar       | Modify → Rebrand toast reads "Brand picker unavailable" | click Rebrand → `.brand-browser` attached                                                           |
| 🟢 | boot          | UI warning count ≠ `/platform/api/audit` count   | was a measurement artifact — `consumeBootSection(id,'audit')` in 010-core.js nulls the payload after first read (one-shot cache by design). Probe boot.audit BEFORE any consumer fires, or compare via raw HTML grep `"audit":{` — current render matches /api/audit score 97 / 3 info |
| 🟡 | chat/agent-latency | `.bc-send` spinner > 25 s · `.bc-bubble.bc-assistant` > 25 s (observed 55 s) | LLM backend latency on complex edits — Claude API p95 sits there. Not a code-side bug: merged into one "non-debt" row. Mitigation would live in agent.ts streaming (partial-token flush), not in QA-layer code |
| 🟢 | toolbar       | Preview → Mobile toast "Viewport → mobile" (legacy) | post-click toast text matches `/Previewing at .* width/`                                             |
| 🟢 | dashboard     | `.overview-thumb` bbox.height < 100 at 1440      | re-verified 2026-04-20 — `aspect-ratio: 16/10` on thumb holds: at vp=1440 card w=263 → thumb h=163; no regression                                                    |
| 🟢 | api/variations| POST `/variations/apply kind:colorRotation` → 400 "no tokens" | same request → 200 {ok:true} (auto-defines from activeBrand)                                   |
| 🟢 | toolbar       | Generate→Responsive click leaves bc-input empty  | probe `[data-bc-input].value` contains "responsive variants" after click                                |
| 🟢 | modal/export  | Escape on Export preview keeps modal open        | open Export → press Escape → `.export-preview` detached                                                 |
| 🟢 | core/edit     | `path:"Hero"` → UPDATE ERROR "Hero" not found    | re-verified 2026-04-20: `reframe_edit op:update path:"role:heading"` + `path:"text:shipping fast"` both return `UPDATE "h1" — characters`. `findNode` role/text prefixes (edit.ts · 2026-04-20 Fix log) remain live |
| 🟢 | compile       | re-compile file= without height drops height to default | compile file+name only, no height → new scene.height === prior scene.height                      |
| 🟢 | chip/viewport | Preview→Mobile changes canvas but chip still "desktop" | post viewport click → `.bc-chip[data-chip-kind=viewport] .bc-chip-label` matches new vp          |
| 🟢 | chat/bc-input | press Enter appends \n (value ends in `\n`)      | type + press Enter (no Shift) → `.bc-bubble.bc-user` count +1 within 500ms                              |
| 🟢 | dashboard/grouping | scenes sharing first hyphen-token collapse to one project | seed 3 scenes with distinct first tokens → 3× `/platform/project/<slug>` returns 200; with shared token only owner's 200, rest 404 |
| 🟢 | api/reload | `/platform/api/audit` → 400, `/platform/api/manifest?slug=` → 404, `/platform/api/project?slug=` → 404 | fixed 2026-04-20: router resolves missing sceneId from Referer; aliases for /manifest + /project return project payload |
| 🟢 | boot/audit | `__REFRAME_BOOT__.scenes[<id>].audit` is null/undefined while `/platform/api/audit?sceneId=<id>` returns findings | fixed 2026-04-20: `buildAuditResult` in boot-payload.ts aligns shape with /api/audit (findings[].fix, brandFidelity); silent catch now logs |
| 🟢 | layout/asides | at ≤ 1024 px both asides collapse; canvas pane = 100 % of viewport | fixed 2026-04-20 editor-shell-page.ts: media query raised to 1024 px, full `grid-template` shorthand + `!important` beats the base shorthand |
| 🟢 | toolbar/dropdown | Escape after Modify dropdown does NOT dismiss the menu/submenu | fixed 2026-04-20 140-toolbar.js `bindMacroDropdowns` — capture-phase `keydown` Escape handler closes `[data-macro-menu]` + `.macro-submenu.open`; outside-click now also closes open submenus. Re-verified: Modify→Esc, Modify→submenu→Esc both clear |
| 🟢 | toolbar/overlap | Export button overlaps More-dropdown chevron at 768 × 1024 | fixed 2026-04-20 editor-shell-page.ts 1024px media query — `.macro-dropdowns { display: none !important; }` at ≤1024. The absolute-positioned macro pill lost its side rails once sidebars collapsed; hiding it removes the collision. Generate/Modify/Preview/More remain reachable via bottom chat palette and agent prompts at mobile/tablet |
| 🟢 | docs/selector-drift | canvas lives at `main#canvas-area > canvas`, not `#reframe-viewport canvas` | already resolved in SKILL.md § Tool + screenshot hygiene (2026-04-20). Row kept as 🟢 regression guard — if anyone restores the old `#reframe-viewport canvas` selector anywhere in skill docs, this row points at the correction |
| 🟢 | export/iframe-html-bg | iframe `<html>` has no explicit bg, so when iframe content is shorter than the iframe frame, modal beige bleeds through between body and iframe edge | fixed 2026-04-20 exporters/html.ts — `rootBgForBody(root, graph)` now applied to both `html` and `body` selectors |
| 🟢 | export/fixed-child-shrink | FIXED-sized child in flex parent renders bbox.width=0 when a sibling has long wrapping text (badge vanishes under text pressure) | fixed 2026-04-20 exporters/html.ts primary-axis branch — emit `flex-shrink: 0` alongside `width: Npx` for FIXED children; default shrink:1 let browser crush the badge to 0 |
| 🟢 | layers/stale-text-name | reframe_edit updates `characters` on a TEXT node → LAYERS still shows the import-time frozen name ("Set per-person limits, ca" after shortening to "Set spending limits…") | fixed 2026-04-20 150-sidebar.js — TEXT nodes with text now display the live text (truncated to 28) as displayName instead of the frozen `node.name`; chat edits reflected immediately |
| 🟡 | boot/brand-leak | `activeBrand` persists across project switches — new/empty project inherits prior session's brand (e.g. qaa-2026 opens reporting "Active brand: Inspired by Airbnb") | **architectural, needs-pr.** Current .reframe/ dir holds ONE `project.json` with ONE `activeBrand` slot; dashboard "projects" are virtual groupings of scenes sharing that dir. Fixing requires per-virtual-project manifest shards + router resolution — out of ≤40-line fix budget. Workaround: `reframe_project set_active_brand` after every project switch |
| 🟢 | ui-session/gc | Playwright session GC'd well under the 15-min idle window (observed 30–60 s during active bucket walks) | re-verified 2026-04-20 — `ui-session.ts` `IDLE_TIMEOUT_MS = 15 * 60 * 1000` (15 min) is correct and unchanged. The "under-15-min" observation was **sidecar restart side-effect**: every rebuild (`copy-platform-assets.mjs`) kills :4100, which closes the Playwright browser, which drops all sessions. Expected, not a code bug. Lesson: after rebuild, always `reframe_ui open` fresh — don't reuse a session id from before the restart |
| 🟢 | dashboard/heading-overlap | project-card heading + description overlay the top of the dark thumb | re-verified 2026-04-20 at vp=1440 — thumb bbox ends at y=461, name bbox starts at y=475. No overlap; card structure is `<thumb>` then `<meta>` stacked vertically inside `.overview-card` (display:block). Smell was a stale observation. Separate product issue fixed same day: `.overview-name` showed scene-root INode name ("Stack", "Row") instead of project slug — added `stack/row/column/group/frame/canvas/body/html` to dashboard.ts `GENERIC_TAGS` fallback |
| 🟢 | toolbar/macro-submenu | Modify → submenu items render with bbox `{width:0, height:0}` | was a stale-probe-selector, not a real regression. Correct selector is `.macro-submenu-panel button` (inside `.macro-submenu.open`), not `.dropdown-submenu button` (class never existed). Re-verified: clicking `.macro-submenu-trigger` opens the panel with proper bbox, items respond to clicks. CSS uses `display: none → flex` on `.open`/`:hover` — working as designed |
| 🟢 | right-panel/empty-state-on-boot | after reload with no persisted selection, right panel keeps the static "Select a node to inspect" HTML placeholder — Canvas-root controls (W/H + background + audit) never render until user presses Escape or clicks empty workspace | fixed 2026-04-20 160-init.js `tryRestoreProps` — when `!state.selection.inode` on first top-level call, invoke `clearPropsPanel()` so the scene-dashboard renders as the default empty state |
| 🟢 | canvas/deep-click-to-leaf | clicking a button on canvas selected its inner TEXT leaf (e.g. `button-text` 98×18) instead of the button frame; LAYERS+chip desynced because the leaf has no `data-layer-node` entry | fixed 2026-04-20 160-init.js `reframe:canvas-select` handler — before dispatching, walk `parentId` chain via `__reframeEditor.getNode` until an ancestor with `data-layer-node` is found; promote selection to that ancestor. First-meaningful-parent UX (Figma-like). Also fires `reframeRenderBottomChips` + `reframe:ui-state-changed` so the chip/LAYERS subscribers update too |
| 🟢 | right-panel/derived-dims-stale | after changing `font-size` on a TEXT node, panel's W/H inputs kept pre-edit values even though layout bbox reflowed | fixed 2026-04-20 160-init.js — `reframe:prop-changed` listener triggers `queuePropsRefresh()` (300ms debounce) for layout-affecting props (font-size, font-family, font-weight, line-height, letter-spacing, padding*, width, height, min-/max-*, gap, itemSpacing, text, characters). Re-verified: changed font-size 40→80→48 on h1, panel H tracks canvas bbox on each change |
| 🟡 | right-panel/multi-select-gap | Shift+click in LAYERS highlights N items, right panel + chip show only last-clicked | **product gap, not debt.** Requires panel renderer to compute common-prop intersection across N nodes + chip row to render "N selected" badge. Deliberate scope-out; implement when multi-select becomes a workflow. Moved to `.reframe/product-gaps.md` (outside this table) |
| 🟢 | dashboard/thumbnail-color-drift | project card thumbnail rendered an orange/red gradient for a scene whose root fill is `#fafaf9` | was a cache/loading artifact. `/cover/<id>.svg` is an intentional DECORATIVE fallback (procedural palette from sceneId hash) shown while the real `/thumbnail/<id>.png?scale=1` is cold-rendering via CanvasKit. After PNG loads (fade in ~240ms) it replaces the cover. Re-verified: PNG shows real scene content (cream features, dark footer) — matching canvas render. Not a bug |
| 🟢 | canvas/empty-state-paints-root-frame-fill | empty-state "Background" input routed to ROOT NODE fill (`data-node="root"` · `data-prop="background"` · POST /api/node/edit). Paint leaked through as a stripe where children didn't cover full root bbox (e.g. 1440-wide Section inside a 1600-wide root → 160px dark stripe on the right). User's mental model was correct: "Canvas" in empty-state = Figma-style workspace around frames, NOT the root frame itself | fixed 2026-04-20 — 110-properties.js renames the empty-state panel to `Canvas [workspace]` with subtitle "Nothing selected — edit the canvas around your frame", input now `data-prop="canvas-bg" data-workspace-key="reframe:workspace-bg:<slug>"` (no `data-node`). 120-widgets.js `bindPropInputs` intercepts `prop === 'canvas-bg'` BEFORE node-edit path: calls `applyCanvasBg(hex)` which (a) sets `--surface-canvas` CSS var on documentElement and (b) writes `__reframeEditor.state.pageColor = {r,g,b,a:1}` + bumps sceneVersion — **both layers required** because `@open-pencil/core/constants` has a hardcoded `CANVAS_BG_COLOR = {r:.96,g:.96,b:.96}` that the SkiaRenderer paints on every frame (`canvas.clear(ck.Color4f(pageColor.r, ...))` in renderer.js:480). Without pageColor override the CSS var is invisible — beige wins. Value persisted per project slug in localStorage; 160-init.js re-applies on boot (CSS var synchronously + retries `applyCanvasBg` at 200ms intervals until editor is wired). Scene root INode fill is now never touched from the empty-state control — select the root frame explicitly in LAYERS to edit that. |
| 🟢 | engine/grid-auto-rows-ignored | Bento `grid-template-columns: repeat(6,1fr); grid-auto-rows: minmax(200px, auto)` → cells collapsed to ~159px content-height. `resolveGridTrackToken` for `minmax(Npx, auto)` fell into AUTO(0) branch — lost the 200px minimum. Root scene also stuck at default 1080, overflowing footer | fixed 2026-04-20 — 3 engine fixes + 1 parser fix, all verified by grid-stress.test.ts (8 assertions pass). See Fix log entries 2026-04-20 for `grid-auto-rows field` / `minmax auto min` / `implicit row count from spans` / `post-layout height propagation` / `parser radius bullet-list` |
| 🟢 | preview-inject/postmessage-wildcard-target | `window.parent.postMessage({...}, '*')` — if `/preview/:id` embedded cross-origin, attacker page receives every hover/click/bbox/measurement with className+text | fixed 2026-04-22 — `PARENT_ORIGIN = window.location.origin`, all `post()` calls pin targetOrigin. Probe: grep `postMessage.*'\*'` in dist/mcp/src/preview-inject.js → 0 matches |
| 🟢 | preview-inject/origin-pin-missing | inbound parent→iframe messages trusted via string-tag `data.source === 'reframe-host'` only; any sibling frame / embedder can spoof `setMode`/`measure-all` | fixed 2026-04-22 — `onMessage` rejects `event.origin !== PARENT_ORIGIN` AND `event.source !== window.parent` before tag check. Probe: grep `event\.origin !== PARENT_ORIGIN` in dist → present |
| 🟢 | http-server/legacy-dashboard-dead-code | `renderPreviewDashboard()` emitted two `<iframe>` tags for a root route that 404s since Platform UI shipped; 92 lines of unreachable iframe markup + unused `esc()` helper | removed 2026-04-22 — function + helper deleted from `http-server.ts`. Only remaining iframe call-sites: `140-toolbar.js` export modal (3 iframes, now 2 after ternary collapse) |
| 🟢 | toolbar/export-preview-ternary-dup | `isCode ? '<iframe src=' + exportUrl : '<iframe src=' + exportUrl` — identical both branches; dead developer intent never pruned | fixed 2026-04-22 — collapsed to single iframe, TSX/React served as pre-wrapped HTML by `/preview/:id.tsx` handler so iframe rendering is correct for every format |
| 🟡 | engine/audit-autofix-radius-snap-to-smallest | With brand scale `[2,4,6,8,12,22,9999]`, audit `border-radius-compliance` auto-fix snaps EVERY off-scale radius to `2` (smallest), not nearest. E.g. `6 → 2`, `999 → 2`, `12 → 2` — visually destroys the design | **needs-pr.** snap algorithm in `packages/core/src/audit.ts` picks `scale[0]` instead of `scale.reduce((nearest, s) => |v-s| < |v-nearest| ? s : nearest)`. Workaround: compile with `audit: false` to skip auto-fix when brand is loaded. Real fix requires audit-rule redesign; over 40-line budget |
| 🟡 | engine/aesthetic-whitespace-penalizes-dashboards | Dashboard scenes hit whitespace=12% Poor, alignment=50% Fair — dragging overall to 63% when hierarchy/rhythm are 100%. Metric calibrated for marketing-page genre, misrates information-dense UIs | metric tuning needs density-aware calibration. Low priority — overall score is still informative; breakdown per metric is the useful signal. No code fix |
| 🟢 | engine/inode-path-parity | MCP `reframe_edit update` and Platform UI `/api/node/edit` wrote DIFFERENT INode state for the same logical input — UI path had no clamping (opacity:2.5, width:99999, padding:-20 passed through raw), hex alpha `#RRGGBBAA` mapped to `color.a` instead of `fill.opacity`, 3/4-char hex rejected, `lineHeight`/`letterSpacing` written as `{value,unit:'PIXELS'}` object instead of plain number, `role` silently dropped, `padding` shorthand unsupported, `border-color` overwrote existing stroke weight+align | fixed 2026-04-22: both paths now flow through shared `sanitizeNodePartial` exported from `edit.ts`; CSS mapper rewritten to match MCP semantics. Regression suite `packages/mcp/src/tests/inode-path-parity.test.ts` covers 9 scenarios / 35 assertions |
| 🟢 | engine/importer-transform-flip-lost | CSS `transform: scaleX(-1)` / `scaleY(-1)` / `scale(-N,1)` / `matrix(-1,...)` silently dropped on import — `flipX`/`flipY` fields never written, so round-trip HTML→INode→HTML lost the mirror flip entirely (exporter had full flipX/flipY emission but INode was always default). Comment in `importers/html.ts` near `scale()` block said "visual-only, do not mutate width/height" — correct for layout box, WRONG for flip fields | fixed 2026-04-22 `packages/core/src/importers/html.ts` transform block: parse `scaleX/scaleY/scale(x,y)` and route negative values to `flipX`/`flipY`; extend matrix parser to detect negative-determinant on each axis via `a/|a|` sign check. Regression `packages/core/src/tests/inode-roundtrip.test.ts` 14/14 |
| 🟢 | engine/importer-mix-blend-mode-lost | CSS `mix-blend-mode: multiply\|screen\|overlay\|…` never parsed by importer — `blendMode` field stayed `'PASS_THROUGH'`, so any designer-intended blend effect collapsed to NORMAL on re-export | fixed 2026-04-22 `packages/core/src/importers/html.ts`: added `mix-blend-mode` parser after transform block, maps CSS keyword → INode enum using inverse of `exporters/html.ts` `blendModeToCSS`. Covered by the same round-trip test |
| 🟢 | engine/importer-pseudo-class-states-lost | CSS `:hover / :focus / :active / :disabled` rules NEVER parsed — `node.states` always `{}`, so HTML source that styled hover states loses them on round-trip (exporter emits state CSS correctly when `states` is set by agent, but importer never fills). | fixed 2026-04-22 `packages/core/src/importers/html.ts` — added `pseudoRules: Map<idx, [{state, properties}]>` side-channel alongside `mediaRules`. CSS-rule loop now routes selectors matching `/:(hover\|focus\|active\|disabled)\b/` into pseudoRules (stripped base selector → `querySelectorAll` → data-reframe-idx capture), parallel to `@media` extraction. At override-build time (next to the `responsive` wire-up), pseudoRules entries convert via `cssToResponsiveProps` and land in `overrides.states[<state>]`. Extended `cssToResponsiveProps` to handle `background`, `color`, `border-radius` (previously only layout + typography props) so state overrides like `.btn:hover { background: #254edb }` survive the mapper. Regression `packages/core/src/tests/pseudo-class-import.test.ts` — 10/10 covering `.class:hover/:focus/:active` + `#id:hover` + `.class:disabled` + base geometry regression guard. |
| 🟡 | engine/importer-textAlignVertical-infer | `textAlignVertical` never set by importer — exporter reads it and emits `align-items`, but importer never maps parent `align-items: center + <single text child>` to child's `textAlignVertical`. Usually handled at layout level via flex align-items on parent; only lossy when export re-emits text vertical align as a standalone rule | **needs-pr / low prio.** Inference is ambiguous (parent align-items applies to ALL children, not just text). Skip unless a concrete user scene fails because of it |
| 🟡 | engine/importer-dead-fields | `dashPattern` on node (vs on stroke), `isMask`/`maskType`, `horizontalConstraint`/`verticalConstraint`, `pointCount`/`starInnerRadius`, `strokeCap`/`strokeJoin` at node level — all readable by exporter/types but never written by HTML importer. Most are SVG/Figma-native fields with no clean CSS equivalent, so default values are acceptable for HTML round-trip | **no-fix.** These are design-surface fields for advanced shapes. Not lossy for the HTML-first design workflow the engine targets; lossy for agents porting figma exports back to HTML, which isn't a supported path |

| 🟢 | canvas/hug-collapse-on-load | Opening `/platform/project/:slug` renders a mostly-empty dashboard: 201 nodes in graph, only top bar + search + Overview title + sidebar icons visible; all HUG-sized containers collapse (main Stack 967→100, inner Stack 915→48, Overview Row 44→0, last Stack 324→0). Disk `.scene.json` has correct dims (Yoga-computed on import); dashboard thumbnail (PNG via CanvasKit raster) renders full scene. Divergence only in live canvas. | fixed 2026-04-22 `packages/editor/src/canvas/editor-shell.ts:238` — skip `@open-pencil/core`'s `computeAllLayouts` on scene load when the reframe source already has concrete dimensions. Only re-run layout if every top-level child has zero dims (fresh `.fig` import path). OP's flex engine has different HUG semantics and was collapsing reframe-imported nested HUG containers. Pre-loaded dims from disk are authoritative. |
| 🟢 | breadcrumb/generic-inode-root-name | Project-canvas top-bar breadcrumb shows "Row" / "Stack" / "div" (auto-inferred INode root name from HTML importer) instead of the project slug. Dashboard card already had `GENERIC_TAGS` fallback (2026-04-20 fix), but `router.ts` editor-shell render used raw `project.name` without it. | fixed 2026-04-22 `packages/mcp/src/platform/router.ts:381` — inline `GENERIC_ROOT_NAMES` set mirroring dashboard.ts list; fall back to `project.slug` when INode root name is generic structural tag. Requires sidecar restart to pick up (router.ts loads at process start). |
| 🟢 | canvas/hug-collapse-on-every-edit | The scene-load HUG fix (2026-04-22) was only half the bug. `platform-bootstrap.ts:354` ran `@open-pencil/core`'s `computeAllLayouts` after EVERY `reframe:prop-changed` event — that's every right-panel input change (fill, opacity, padding, text, font-size). Each edit reverted the scene to the post-OP-layout collapsed state (Stack 967→100 on one background color change). First load looked fine; any edit broke it. Server owned no layout truth because `/api/node/edit` called `graph.updateNode` without running `ensureSceneLayout`. | fixed 2026-04-22 two-part: (a) `platform-bootstrap.ts:354` no longer runs OP's `computeAllLayouts` at all after prop edits — server is single source of layout truth; (b) `packages/mcp/src/platform/api/node-edit.ts` POST `/api/node/edit` now runs `ensureSceneLayout` when `partial` contains any layout-affecting key (20-key allowlist: text, fontSize, padding*, itemSpacing, width/height, min/max-*, layoutMode/Sizing/Align/Grow, gridTemplate*, etc.). Server-stored graph stays authoritative; SSE broadcasts correct dims to canvas. Verified: 5 sequential edits (background / opacity / cornerRadius / paddingTop / fontSize) all preserve main Stack h=783. |
| 🟢 | graph-bridge/grid-fields-dropped | `@open-pencil/core`'s SceneNode has `gridTemplateColumns`/`Rows` but NOT `gridAutoRows`/`gridAutoColumns`/`gridTemplateAreas` — reframe added those 2026-04-20 for Bento support. `packages/editor/src/bridge/graph-bridge.ts` copied overrides directly onto OP nodes without routing these 3 fields through the extension side-channel, so INode→OP conversion dropped them silently. Any Bento scene with `grid-auto-rows: minmax(200px, auto)` in browser canvas would revert to default FR tracks once OP's layout ran. Not visible on dashboard (doesn't use auto-rows) but latent on stress-bento-*, editorial, any future Bento. | fixed 2026-04-22 `packages/editor/src/bridge/node-bridge.ts` — added `gridAutoRows`/`gridAutoColumns`/`gridTemplateAreas` to `ReframeExtension`, `extractExtension`, and `applyExtension`. Symmetric across INode↔OP both directions. Works because the bridge already routes OP-incompatible fields through a side-channel `Map<nodeId, ReframeExtension>` that re-merges on `toReframeGraph`. |
| 🟢 | api/mutation-endpoints-missing-layout | 7 platform API endpoints mutated the scene graph without re-running Yoga afterwards: `/api/node/add` (HUG parent doesn't grow to fit new child), `/api/node/delete` (parent stays inflated with phantom gap), `/api/node/wrap` (new Container creation, sibling positions stale), `/api/node/edit` reparent shortcut (new+old parent HUG both desync), `/api/scene/auto-fix` (batch prop fixes leave ancestors stale), `/api/node/edit/undo` single-op (reverts layout-affecting props but HUG stays at post-edit value), `/api/scene/revert-to` multi-op (same pattern at scale), `/api/audit/apply-fix` (audit auto-fix via CSS-shaped edit). Net effect: client canvas shows correct partial edits but HUG ancestors stuck at old dims → visual gap/overlap/clipping. | fixed 2026-04-22 `packages/mcp/src/platform/api/node-edit.ts` — added `ensureSceneLayout(scene.graph, scene.rootId)` call before `replaceSessionSceneGraph` in all 8 paths. For add/delete/wrap/reparent/revert-to always; for edit/auto-fix/audit-fix gated on the 20-key `LAYOUT_AFFECTING_KEYS` allowlist (same set as the main `/api/node/edit` branch). Pure-visual fixes (fill/opacity/stroke/cornerRadius) skip the Yoga pass. |
| 🟢 | engine/abs-pos-cache-not-invalidated-after-layout | `SceneGraph.absPosCache` caches `getAbsolutePosition(id)` results. `updateNode` invalidates it on geometry prop changes; `reparentNode` clears it entirely; `deleteNode` removes the deleted id. BUT: `computeAllLayouts` / `ensureSceneLayout` rewrite x/y/w/h on every node in the layout tree (Yoga + grid pass + propagateHeights) without touching the cache. Downstream readers — audit via standalone-node `absoluteBoundingBox` (sibling-overlap / no-overflow rules), resize/adapt bleed check, Canva adapter — would keep reading pre-layout coords and report false findings. | fixed 2026-04-22 `packages/core/src/engine/layout.ts` `computeAllLayouts` — append `graph.clearAbsPosCache()` at the end of the function (after propagateHeights). `ensureSceneLayout` delegates to `computeAllLayouts` so gets it for free. Keeps mutation sites free from having to remember the invalidation. All 57 existing regression assertions (grid-stress 8 + roundtrip 14 + parity 35) still pass. |
| 🟢 | engine/inode-editor-state-leak | `SceneNode` mixed four editor-state fields (`locked`, `expanded`, `autoRename`, `internalOnly`) into the design AST. These are pure UX bookkeeping (UI lock, LAYERS expand/collapse, rename heuristic, "hide from publish") with zero effect on layout/render/export, but they were serialized into `.scene.json`, round-tripped through disk / bridge / export paths, and showed up in every downstream consumer. Inherited from Figma's SceneNode shape via `@open-pencil/core` fork — appropriate for a coupled editor-storage model, wrong for reframe's "INode = AST of design" thesis. | fixed 2026-04-22 — introduced `packages/core/src/engine/editor-state.ts` with `EDITOR_STATE_KEYS` set + `stripEditorState()` helper as the single source of truth. Tagged each field in `types.ts` with an `@editorState` JSDoc block explaining rationale + long-term target (extraction into `WorkspaceState`). Dropped `locked` and `internalOnly` writes from `serializeSceneNode` unconditionally (compact path already dropped defaults; new contract drops even non-default values because editor-state doesn't belong in persistence). `expanded`/`autoRename` were already absent from the serializer output path, so they inherit the contract via the JSDoc tag alone. Updated two `serialize.test.ts` assertions (`locked` roundtrip, compact non-default `locked`) to assert the new contract (`locked === false / undefined`). Bridge (INode↔OP) keeps copying these fields because the editor runtime needs them in memory — the skip is only at serialization + export boundaries. Step 1 of 3 on the "INode → pure AST" refactor ladder; steps 2 (`NodeEditorState` type split) + 3 (immutable INode) deferred to standalone PRs. |
| 🟢 | gitignore/trailing-slash-kills-negation | `.reframe/` (with trailing slash) makes git skip traversing the directory entirely → any `!.reframe/...` negation pattern below is silently ignored. Surfaces as "the file is in working tree, gitignore has the un-ignore rule, but `git status` doesn't list it as untracked and `git add` says nothing to add". Bit Brief E during the 5-direction shipping flow. | fixed 2026-04-30 `.gitignore` — change `.reframe/` to `.reframe/*` so git traverses the dir and the negation chain (`!.reframe/brands/`, `!.reframe/brands/<id>/`, `!.reframe/brands/<id>/**`) actually applies. Verify via `git check-ignore -v <path>`: an excluded entry should match the negation rule, not the parent block rule. Pattern applies to ANY gitignore exception flow — covered-by-parent vs traversable-with-exceptions is the canonical test. Inline comment in .gitignore documents the trap to prevent regression. |

When you find a new smell: one row here (≤ ~110 chars per column), and if you fixed it, one line in the Fix log. Don't inline the recipe.

**Architectural shift 2026-04-22.** `@open-pencil/core` / CanvasKit / `packages/editor/src/bridge/` + `packages/editor/src/canvas/editor-shell.ts` were removed; the live canvas is now a DOM-iframe composed by `packages/editor/src/canvas-dom/` (dom-canvas + overlay + pointer + renderer + zoom-pan + present + webgl-present). Smell rows dated ≤ 2026-04-22 referencing `@open-pencil/core` / `graph-bridge` / `node-bridge` / `editor-shell.ts` / `SkiaRenderer` / `pageColor` describe architecture that no longer ships — treat those rows as frozen-green pattern references, not live suspicion paths. New HUG / grid / layout bugs post-removal belong in new rows against `canvas-dom` or engine.

### Fix log

Archived in [fix-log.md](fix-log.md) — ~55 entries keyed by sentinel. **Consult ONLY when a `🟢` row in the smell table above flips back to `🔴`** — then the matching entry tells you which file/symbol the fix touched. Do NOT read `fix-log.md` during a normal session; it's cold-path.

When you close a new smell: add the `🟢` row to the smell table above AND one line to `fix-log.md` with the same sentinel, date, and `file:symbol`. Format: `YYYY-MM-DD · sentinel-id · file:symbol · one-line why`. Keep the recipe in the log, never inline in the table.

## Before you probe — rebuild ritual when UI JS changed

The Platform UI JavaScript is **concatenated at build time** from `packages/mcp/src/platform/ui/*.js` into `packages/mcp/dist/mcp/src/platform/platform-ui.js`, and the sidecar reads that bundle **once at module load** (`scripts.ts → PLATFORM_JS = loadPlatformJs()` — a module constant, not a per-request read). Two silent traps follow:

1. **Source edits don't reach the browser until the bundle is rebuilt.** Editing `150-sidebar.js` or `160-init.js` and reloading the tab serves the stale bundle — your fix is invisible.
2. **Rebuilding the bundle doesn't reach the browser until the sidecar restarts.** `PLATFORM_JS` is captured on process start; a fresh bundle on disk is ignored until the process is killed and re-spawned.

Before claiming a UI fix verified, ALWAYS:

```bash
# 1. Rebuild the bundle (copies & concatenates ui/*.js → dist/platform-ui.js + rebuilds editor-bundle.js).
# The script lives at repo root, NOT in packages/mcp/scripts. Either:
npm run build --workspace=@reframe/mcp    # from repo root — tsc + asset copy
# or directly:
node /d/reframe/scripts/copy-platform-assets.mjs

# 2. Restart the sidecar. On Windows it's listening on :4100, find + kill + relaunch:
netstat -ano | grep ":4100 " | head -1           # grab the PID from column 5
taskkill //F //PID <pid>                          # Windows, bash shell syntax
node packages/mcp/dist/mcp/src/http-server.js &   # relaunch in background

# 3. In a Playwright session, session may have been closed by the sidecar death — reopen.
```

Then **confirm fix is live before testing**: `reframe_ui probe js=(window.refreshLayersTree||function(){}).toString().includes('_refreshTreeTimer')`. If `false` the sidecar is still serving the old bundle; don't proceed — restart again.

Warning signs that the old bundle is still live:
- Network panel floods with identical requests on a single user interaction (`scene/tree` ×100, `audit` ×50, etc.). If your fix was supposed to coalesce, it's still on old code.
- Browser fetches `/platform/app.js` and the response size has not changed from before your source edit.
- `ERR_INSUFFICIENT_RESOURCES` on innocuous-looking GETs — that's the browser's "too many concurrent requests" circuit breaker tripping.

## Render-scene QA — the second half of every sweep

A UI flow that completes cleanly can still produce a broken scene. Engine import / layout / paint bugs only surface when you look at the output. "Padding 120 → 72, canvas reflowed from 4400 to 4352, toast fired" is not a pass — that's **mechanics**. The designer using this app doesn't care about the number; they care whether the result looks good. Three tiers, run after every mutating flow:

### Tier 1 — Mechanics (cheap, every mutation)

Engine-measurable regressions. Takes seconds.

1. **`reframe_inspect`** on the current sceneId — read audit warnings, 8 aesthetic metrics, semantic skeleton. Warnings > 0 that weren't there pre-edit = a regression worth logging. Aesthetic metric dropping hard (alignment 0.9 → 0.4) = visible damage.
2. **Screenshot the canvas, not the page.** `reframe_ui screenshot selector: '#canvas-area canvas'`. **Never `fullPage: true` on tall scenes** — see screenshot-size gotcha below.
3. **Quick-visual sanity on the PNG** (5 sentinels, nothing more):
   - Text clipped mid-word or truncated with `…` where a full line should fit?
   - Buttons rendering without their label (swallowed by a 0-height parent)?
   - Siblings visually overlapping (not by flex gap — by actual z-stack)?
   - CTA primary lost its accent — blends into the surface?
   - Scene root painting the wrong background (beige leak, transparent)?
4. **Skeleton vs. render cross-check.** If semantic skeleton claims `[nav] 1440×84` but screenshot shows nav overlapping the hero, that's a Yoga/import mismatch — log it.

### Tier 2 — DESIGN.md fidelity (cheap, every mutation after a brand is loaded)

The brand is an **oracle, not just a seed**. Currently the skill reads DESIGN.md as input to generation and then forgets. Instead:

1. Read `.reframe/brands/<slug>/DESIGN.md` (or the prose returned by `reframe_design extract`). Pull the **hard numbers**: hero size, tracking, weights, brand accent hex, border rgba, radius scale.
2. `reframe_inspect` the scene's hero / primary CTA / card — compare the render against the prose. Hero is 48px when DESIGN.md said 72px? Tracking is 0 when DESIGN.md said -1.584? Fill is `#111` when DESIGN.md said `#08090a`? **Fidelity fail — log the delta, propose a `reframe_edit update` with the brand-correct value.**
3. Fidelity-clean scenes can still be taste-poor — pass Tier 2 is not "done". Proceed to Tier 3.

Fidelity is not taste. Fidelity catches "you wrote the wrong number"; taste catches "you wrote the right numbers but it reads dead". Both matter.

### Tier 3 — Taste (expensive, end-of-sweep only, ONCE)

Delegate to `reframe-critic`. Don't inline a competing rubric — that skill already encodes the full Behance-tier smell library (fake metrics, fake logos, 3-equal-cards, centered-hero-5-elements, gradient-glass, forgettable-failure-mode, tone-mismatch) and knows how to translate engine numbers into designer sentences.

When to invoke:
- **At the end of a QA sweep** — after all mutations + mechanics + fidelity passes.
- **Once per scene**, not per mutation (critic is gated to final review; firing it after each click produces noise, not signal).
- **When mechanics + fidelity both pass but the PNG "looks off"** — critic is the only layer that can articulate why.

Invocation: call `reframe-critic` as its own skill or read its SKILL.md and apply inline. Output: ≤ 3 concrete fixes with engine citations. Attach those to your sweep report.

### Tier 4 — Export cross-check (when an exporter is in scope)

`reframe_export` → html + png. If the PNG body is the wrong color, or the html iframe shows the beige modal bg, the **exporter** regressed — different bug, different fix path than the canvas renderer.

**Render-side smell rows** (add to the table above when you find new ones):

| Render smell | Likely engine bug | Quick probe |
|---|---|---|
| Siblings visually overlap at narrow viewport | Yoga multi-pass didn't converge OR flexBasis regression on HUG parents | `reframe_inspect` — look for `overflow` / `sibling-overlap` warnings; re-run at 1440 to confirm it's viewport-only |
| Text node rendered clipped / single line when skeleton says `690×221` | text measurement desync — font not loaded at measure time | probe `document.fonts.status`; re-screenshot after `document.fonts.ready` |
| Scene root paints transparent over page bg | import lost root fill OR exporter body-bg regression | `reframe_inspect` root node — check `fills[0]` exists and is solid |
| Grid section collapses to one column though `grid-template-columns: repeat(3, 1fr)` | linkedom grid import regression (the `data-reframe-idx` mismatch class) | re-compile the source HTML standalone, diff resulting tree |
| Button height < 44 px in render but skeleton says 44 | min-height not propagating from HUG to fixed | audit should already flag; if not, audit rule regressed |
| Full-width section renders 1440 inside a 1920 viewport | fixed-px on stretching container — taste rule broken on generation side | fix source HTML (`width: 100%` on stretch), recompile |
| Centered hero with 5+ elements | slop-signature regression from `reframe-design` | not an engine bug — log against the *generation* skill, not the engine |
| Inspect shows root CANVAS "Page 1" 100×100 while FRAME child is 1440×N | html.ts line 178-184 writes page dims but something later resets — OR `resolveScene` picks CANVAS over FRAME as rootId | `reframe_inspect sceneId=<just-compiled>` — read first line. If `(100×100)` despite compile log saying 1440×N, this regressed |
| Button with `height:48;padding:14px 22px` inside `<div style="display:grid;...">` → `<div>` (plain block) → `<button>` chain renders 100×48 with text clipped to ~56 wide | plain block `<div>` imported as VERTICAL flex w/ stretch; button loses HUG and stretches or collapses | compile `<div style="display:grid;grid-template-columns:1fr 1fr"><div><button>Start in 30 seconds</button></div><div>x</div></div>` → inspect → button should be ~213×48, not 668×48 or 100×48 |
| Old saved .scene.json files have frozen-in buggy sizes | engine fixes don't retro-apply to stored JSON | re-compile source via `reframe_compile file=...` and re-save (`reframe_project save`). Don't trust `scenes/*.json` as ground truth for current-engine behaviour |

The last row matters: designer-qa is the **only skill that sees the full stack**, so it's the right place to catch generation-side taste regressions that slip past `reframe-critic`. Don't "fix" them here — log and route.

## Known gotchas

- **Iframe first-paint is fast but not instant** — DOM canvas (~32 KB) loads immediately, no WASM boot, but iframe `srcdoc` still needs a tick to layout. Always `wait` for `.rfd-canvas-viewport iframe` visibility before clicking through. (Historical: CanvasKit stack took 2-3 s; removed 2026-04-22.)
- **Screenshot size limit: no dimension may exceed 2000 px.** The image tool rejects anything larger with "exceeds the dimension limit for many-image requests (2000px)" and pollutes the session context. Rules:
  - Never use `fullPage: true` on a scene — reframe canvases are routinely 1440×3000+.
  - Default to `selector` clips (e.g. `#reframe-viewport`, `.export-preview iframe`, a specific panel) — they're naturally bounded.
  - If you must capture the full scene, split vertically: two or three screenshots via `clip: {x, y, width, height}` with height ≤ 1800 px each.
  - For responsive sweeps, set `setViewport` to ≤ 1920 width before shooting the viewport.
  - If a shot comes back rejected, discard it — don't retry the same call — and re-take with a selector / clip.
- **`reframe_design list` needs network** — if offline (`ETIMEDOUT`), seed brands into `.reframe/brands/` manually or skip brand flows.
- **First audit after boot can false-positive sibling-overlap** — Yoga's multi-pass converges after any graph mutation. If you see N warnings on a fresh load that vanish after one click, it's this, not a real regression.
- **`.bc-bubble.bc-assistant`** is the correct streaming-reply selector (NOT `.bc-bubble-ai` or `.chat-reply`). Also `.bc-bubble.bc-user` for your side of the log.
- **Macro dropdowns don't auto-close on item click** — you have to press `Escape` or click elsewhere after selecting a macro-item. This is existing UX, not a bug.
- **Session GC at 15 min idle** — long-running QA sessions should re-open, not sleep. Every `reframe_ui.close` sibling-reclaims memory.
- **Selectors to prefer over text-match**: `[data-testid=...]` > `#id` > `[data-bc-input]`-style data-attrs > `.class:has-text("...")`. Text-match is volatile across i18n / copy changes.

## How to run a sweep

**Only enter this section if § First move routed here via explicit full-sweep opt-in.** The parallel-bucket recipe below is NOT the default mode of `/designer-qa`; the default is to ASK or PROPOSE (see § First move). This section is the operational blueprint for when the user has said "full / canonical / Level 1 / прогон по всему". In all other cases — concrete bug, specific surface, scoped hypothesis — skip the bucket machinery and go directly to the target using the Platform map.

**When full-sweep IS on:** three independent Chromium sessions, three `Agent` subagents, no communication between them. Serial mode is the fallback for stress/fuzz flows (see below) or when the user narrows scope to a single flow but still wants a canonical shape.

### Bucket assignment (fixed — do not reassign across sweeps)

Each bucket owns a distinct project slug and a distinct set of flows. Buckets are partitioned so two concurrent subagents never mutate the same disk state.

| Bucket | Slug | Flows owned | Why these |
|---|---|---|---|
| A — boot & persistence | `qaa-<ts>` | 1 Dashboard landing · 2 Project canvas load · 11 State + reload | read-mostly; verifies cold-start + round-trip survival |
| B — mutations & agent  | `qab-<ts>` | 3 Chat edit round-trip · 6 Modify macros · 8 Generate macros | mutates scene tree only |
| C — viewport & export  | `qac-<ts>` | 4 Viewport switch · 5 Rebrand · 7 Export preview · 9 Detach / new-tab · 10 Responsive sweep | mutates project-level settings (activeBrand, viewport) |

**Slug-naming rule (discovered 2026-04-20 during first parallel run).** Bucket slugs must have **distinct first tokens** (split on `-` / `_`). `qa-a-run1` + `qa-b-run1` + `qa-c-run1` all share the first token `qa`, and the dashboard's prefix-heuristic (`inferProjectKey` in `project-grouping.ts`) groups them into ONE project → only the owner's `/platform/project/<slug>` route resolves, the others 404. Use `qaa-<ts>` / `qab-<ts>` / `qac-<ts>` (or any three slugs whose first hyphen-token differs) to keep them as three distinct projects.

Split rationale: B mutates the scene tree, C mutates project-level settings. On different slugs, a rebrand in C can't corrupt a chat-edit in B. A is read-dominant and cheap, it rides along.

### Pre-flight (serial, one-shot — before spawn)

Two things MUST complete before spawning subagents, else they race on shared disk:

1. **Extract every brand any bucket will touch.** `reframe_design action=extract brand=<slug>` writes `.reframe/brands/<slug>/DESIGN.md` globally; two concurrent extracts of the same brand corrupt each other. Cache up front, post-cache reads are parallel-safe.
2. **Reserve the three slugs.** `reframe_project action=init slug=qa-a-<ts>` (and `-b`, `-c`). Confirm each exists before spawn.

### Spawn recipe

One message, three `Agent` tool calls with `subagent_type: "general-purpose"`, `run_in_background: false`. Each prompt is self-contained:

```
You are designer-qa bucket <A|B|C>. Your isolated slug is "<slug>". Do NOT
open, read, or mutate any other slug. Do NOT call reframe_design action=extract
(main skill pre-cached brands). Open reframe_ui with a fresh sessionId and walk
ONLY flows <list>. Obey screenshot size rules from SKILL.md § Tool (never
fullPage, ≤ 2000 px on any axis).

You are allowed — and expected — to FIX bugs you surface, across any layer
(engine, UI, export, tool handlers). Rules from SKILL.md § Fix in-bucket:
  • read-before-edit, ≤ 40 lines per fix, re-verify with the same probe that
    caught it, no yak-shaving adjacent code
  • rebuild + restart sidecar ONLY for changes to packages/mcp/src/platform/
    ui/*.js, platform-ui.css, or packages/mcp/src/tools/*.ts — engine fixes
    don't need the ritual
  • do NOT commit git changes; leave the diff for the main skill to review
  • do NOT edit SKILL.md smell-row states — report fix=yes, main skill flips

Return findings as structured lines, one per finding, matching smell-table
format + fix status:
  <state> · <surface> · <sentinel> · <evidence> · fix=<yes|no|conflict|needs-pr|none> · files=[...]

End with: "BUCKET <X> DONE · <N> findings · <M> fixed".
```

Wall-clock: ≈ 3-4 min parallel vs. 12-15 min serial.

### Merge

Main skill receives three finding lists, deduplicates by sentinel (same sentinel reported by two buckets = one row, evidence merged), promotes new sentinels into the smell table. If a subagent errors out or times out, its flows revert to serial — do **not** retry the same bucket in parallel (retry re-races the same shared state that failed).

### Fix in-bucket (the default — close what you catch)

Buckets are not QA robots. They are senior designers / engineers who **fix bugs as they surface**, across every layer — engine (`packages/core/src/`), UI (`packages/mcp/src/platform/`), export (`packages/core/src/exporters/`), tool handlers (`packages/mcp/src/tools/`). A sweep that logs 12 🔴 and walks away is a failed sweep.

**Rules buckets follow when they fix:**

1. **Read before edit.** Always. Edit tool requires it, but also the read prevents blind patches. If a file has changed since another bucket touched it, the Edit will mismatch — that's the conflict signal (see below).
2. **≤ 40 lines per fix.** Same rule as Level 2 bug-triage loop. Over budget = log as `needs-pr` in the finding, do NOT commit in-session. Keep moving.
3. **Re-verify with the same probe that caught the bug.** Re-open / reload / re-screenshot, run the sentinel again. If still failing, leave the 🔴 as-is and note what you tried. Don't mark `fixed: yes` unless the probe flipped.
4. **Touch only what the fix requires.** Do not yak-shave adjacent cleanup — that inflates the diff, inflates rebuild cost, and steps on sibling buckets.
5. **Rebuild + sidecar restart** is needed ONLY for changes to `packages/mcp/src/platform/ui/*.js`, `platform-ui.css`, or tool handlers (`packages/mcp/src/tools/*.ts`). Engine fixes in `packages/core/src/` reload on next MCP call. See § Before you probe.

**Conflict handling (when two buckets race the same file).**

Option one: Edit's exact-string match fails because the other bucket already changed the surrounding context. → The bucket logs `fixed: conflict`, files_touched=[...], skips the fix, moves on. The main skill's Fix phase picks it up serially after merge.

Option two: Both Edits succeeded but produced a broken combination (rare — different logical changes to the same function). → Detected at re-verify (probe still fails OR new probe fails). The later bucket logs the conflict, reverts its own change via Edit, moves on.

**Each subagent's finding line now includes fix status + touched files:**

```
<state> · <surface> · <sentinel> · <evidence> · fix=<yes|no|conflict|needs-pr|none> · files=[...]
```

- `yes` — bucket fixed it and re-verified; state flipped to 🟢.
- `no` — bucket saw the bug but didn't attempt fix (out of flow-scope time budget).
- `conflict` — attempted and raced a sibling bucket.
- `needs-pr` — scope > 40 lines; follow-up PR required.
- `none` — not a code bug (taste, doc, generation pattern).

### Fix phase (serial, after merge — only handles what buckets left on the floor)

After merge, main skill filters for findings with `fix ∈ {no, conflict}` and fixes them one at a time, serial:

1. **Partition by layer** from the finding's suspected file.
2. **Fix, re-verify, next.** ≤ 40 lines each. Over budget → log `needs-pr`, continue.
3. **Flip row state** in the smell table: 🔴 → 🟢 only when the probe reports clean. Add one line to the Fix log (`YYYY-MM-DD · sentinel-id · file:symbol · one-line why`).
4. **Rebuild + restart** only when UI JS / CSS / tool handlers changed.

### Anti-patterns for fixes (bucket OR main-skill fix phase)

- **Do not parallelize fixes across three fixer subagents in the Fix phase.** Buckets fixing in-bucket is fine (they each own a distinct slug and found their own bugs). Main-skill fix phase is strictly serial — it is reconciling leftovers, parallelism there re-introduces the race.
- **Do not fix across layers in one shot.** If a finding is "engine sends wrong payload + UI renders it wrong", fix engine first, re-verify, then revisit whether the UI fix is still needed (often it isn't).
- **Do not fix a taste smell with code.** `centered hero with 5 elements` is not a code bug; it's a generation-side pattern. Log `fix=none`, route to `reframe-design` / `reframe-enhance`.
- **Do not edit SKILL.md smell-row states from a subagent.** State flips (🔴 ↔ 🟢) are the main skill's job after merging + re-verifying. Subagents report `fix=yes`, main skill flips the row.
- **Do not commit git changes from a subagent.** Fixes stay uncommitted; main skill reviews the aggregate diff post-sweep and decides commit boundaries.

### Anti-patterns for parallel mode

- **No inter-subagent communication.** No shared doc, no "wait for sibling A", no dependency between buckets. They run blind.
- **No sessionId sharing.** Each subagent calls its own `reframe_ui open`. A single sessionId driven by two agents = undefined Playwright state.
- **No slug sharing.** Two subagents on `/platform/project/X` means SSE broadcasts cross-contaminate and `manifest.json` last-write-wins. Always distinct slugs per bucket.
- **No parallel for stress/fuzz.** Fuzz clicking for 2 min saturates the sidecar; viewport-thrash races SSE incremental-patch ordering in `dom-canvas`. These run **serial, single bucket**, after the parallel sweep reports clean.
- **No parallel on low-RAM.** Three Chromium contexts ≈ 2-3 GB. If the sidecar is co-hosting a live user session (the person asking for the sweep is IN the browser right now), the user session wins — run serial.
- **No re-extract during spawn.** If a bucket needs a brand not in the pre-flight list, the whole sweep aborts and restarts with an updated pre-flight. Do not extract mid-run.

### Complex scenarios (run after the 11 flows pass, serial, single bucket)

The 11 flows verify "buttons work". These verify "the stack doesn't fall apart":

- **Round-trip:** rebrand Stripe → `reframe_export` html → `reframe_compile file=` on the exported html → diff audit counts. Any new warning = exporter or importer regressed.
- **Viewport thrash:** `setViewport` cycling 390 → 1440 → 768 → 1920 → 390 seven times in 30 s. Canvas must never go to width:0, console must stay clean, audit count must stabilize.
- **Fuzz toolbar:** random clicks on toolbar items for 2 min with a fixed seed (reproducible). Monitor `/platform/api/chat/status` + console for unexpected errors. Known-closable modals auto-dismissed via `Escape` every 5 s.
- **Rebrand chain:** Stripe → Linear → Airbnb → Stripe, reading DESIGN.md fidelity after each hop. Accent hex, hero size, and radius scale must match the currently-active brand, not a previous one (brand-state leak regression).

Log results against the Tier 2 fidelity bar, not just "no crash".

### Emitting findings

- **Fix** — smell detected → fix in code + re-probe to verify
- **Smell Log** — unknown issue → add a row to the anti-regression table with the probe signature so next sweep catches it faster

## Deeper modes — QA by doing real design work

Level 1 (the 11 flows + parallel buckets) walks scripted mechanics — fast, structured, reproducible. But **mechanics passing ≠ stack is healthy.** Bugs that block a real designer shipping a real project — brand drift on the fifth rebrand, export→re-import losing a root fill, chat agent forgetting context on iteration 7, nav inconsistency across pages, token binding stale on scene 3 — only surface when you actually try to ship something. That's Level 2 + 3.

These modes run **serial, single session, 30-60 min** per brief. No parallel buckets — the project is one cohesive thread, splitting it defeats the point. Artifact on output: a shippable scene/site/email/brand system, not a report.

### Level 2 — Designer brief mode

You are a senior designer on Behance whose muscle memory is in canvas. You take one brief, execute it end-to-end using the **full interaction palette**, and fix whatever blocks you at the engine or UI level along the way.

**Interaction ladder — pick the lightest tool that fits the ask.** Real designers don't chat for every change; they tap when it's a tap job, drag when it's a drag job. Mixing paths IS the test — if chat + direct edit + macros don't cooperate in one project, that's the bug.

| Change kind | Right tool | Why |
|---|---|---|
| Nudge spacing 24 → 32, swap one color, toggle weight | `reframe_edit op=update` on the single prop | 1 call, deterministic, zero generation variance |
| "Make this section feel denser" / "add a testimonial row" | bottom chat in Platform UI | generation IS the point — let the agent regenerate |
| Restructure a section (3-col → bento, grid → zigzag) | edit `.reframe/src/<name>.html`, `reframe_compile file=` | chat regenerates unpredictably; source edit is precise |
| Blanket macro across scene (all radii softer, shadows flat) | toolbar → Modify → Scale radius / Shadows | one-click intent, no prompt engineering |
| Rebrand mid-project | toolbar → Modify → Rebrand, pick brand | exercises the real UI path users hit |
| Align two siblings by eye | canvas drag in viewport (via `reframe_ui act dragAt`) | the Figma muscle — tests it feels right |

**Bug-triage loop** — when a blocker hits mid-design, switch hats, fix, switch back:

```
1. Log symptom in the bug log: sentinel · surface · evidence (one line).
2. Identify layer:
     engine  → packages/core/src/ (importers, layout, paint, audit)
     UI      → packages/mcp/src/platform/ (toolbar, chat, modals, panels)
     export  → packages/core/src/exporters/
3. Read the suspected file. Fix if scope ≤ 40 lines.
   Larger → log as "needs follow-up PR", continue the brief with a workaround.
4. Re-verify by redoing the exact step that triggered it.
5. Back to the brief. Do NOT yak-shave — one fix, one verify, move on.
```

Discipline: the brief is the job, bugs are the byproduct. Don't stop executing the brief just because you found one bug — note it, work around it, keep shipping.

**Brief library — pick one, execute until shippable.** Each has audience · must-have · viewport · acceptance. User's custom brief? Map it onto this shape first (`reframe-enhance` can help if vague).

1. **Welcome email — fintech onboarding.** Header + greeting + 3 next-step cards + primary CTA + footer. 600×auto, inline styles only. Accept: renders in a 600px iframe without overflow, CTA ≥ 44 px, no external CSS.
2. **Launch banner set.** Same brand, 3 sizes: 1200×628 (Twitter), 1080×1080 (Insta), 1200×1200 (LinkedIn). Accept: same headline + CTA, brand accent identical across all three, audit clean on each.
3. **3-page marketing site.** home + pricing + 404, one brand. Accept: cross-page nav links use real slugs, `reframe_export format=site` opens clickable, brand typography + accent identical on all pages.
4. **Dashboard + empty state + error state.** One product surface, three states from one token set. Accept: visual continuity, audit clean on all three, aesthetic metric spread across the three ≤ 0.15.
5. **Editorial long-form.** Article page, 1440×6000+. Accept: typography rhythm stable top-to-bottom, PNG export ≥ 2000 px correctly uses the file-ref fallback (not inline), export html has body bg matching root fill.
6. **Rebrand-chain stress.** Same scene rebranded 4× (Stripe → Linear → Airbnb → Vercel). Accept: structure preserved across all four; no brand-state leak (brand N-1's accent must NOT appear after rebrand to brand N); `brandFidelity` ≥ 0.8 on final.
7. **Brand decomposition** → see Level 3.

### Level 3 — Brand decomposition

Pick one brand (Notion, Stripe, Linear, Apple, Vercel, Airbnb). Extract the system, build 3-4 surfaces from it in one project, verify consistency. This is the classic senior exercise — it tests whether DESIGN.md extraction + token binding + multi-scene brand fidelity hold across surfaces.

**Protocol**

1. `reframe_design action=extract brand=<slug>` — read the full DESIGN.md. Write down the **10 load-bearing numbers**: hero size, hero tracking, body size, accent hex, surface dark/light, radius scale, shadow scale, button height, nav height, grid gap.
2. Build 4 surfaces in the SAME project (same slug, same brand): landing home, pricing, signup form, email confirmation. Use the interaction ladder freely.
3. After each surface: `reframe_inspect` → diff render against your 10 numbers. Log every delta (surface N has button height 52 when brand says 48).
4. Final: `reframe_export format=site` for the 3 web surfaces + `reframe_export format=html` for the email. Open each, screenshot, eyeball: does it feel like ONE brand, or 4 surfaces sharing a color?

**Failure modes this catches that Level 1 cannot:**

- Token binding runs on scene 1 only; scenes 2-4 inherit raw values that stale after `defineTokens` re-run.
- Accent rotates correctly on rebrand but secondary accent / semantic colors don't — surface 4 has prior brand's "danger red".
- Typography preset toggled on scene 1 doesn't propagate to subsequently-compiled scenes in the same project.
- Exporter consolidates tokens per-scene, not per-project, so the site has inline hex and the email has CSS vars — two outputs, same brand, different style architecture.

Each is a different fix path. The Level-3 brief is the only way to find which one without writing a bespoke integration test.

### Which level does this request need?

- "test the UI" / "QA platform" / "sweep the flows" → **Level 1 parallel sweep** (default).
- "pretend you're a designer" / "ship something real" / "run a project" (no specific brief) → **Level 2**, you pick from the library.
- User gives an actual brief ("design a welcome email for …") → **Level 2 with their brief**, map onto the acceptance shape, execute.
- "decompose brand X" / "build a system from Y" / "can reframe hold a brand across 4 surfaces" → **Level 3**.
- "do all of it" → Level 1 first (cheap, confirms stack is alive), then Level 2 on one brief, then Level 3 if time remains. **Never** Level 3 first — if Level 1 fails, Level 3 is guaranteed to fail and you learn nothing from it.

## When NOT to use this skill

- Designing / editing a scene → `reframe-design`
- Loading a brand → `reframe-brand`
- Generating a multi-page site → `reframe-site-loop`
- Unit-testing the engine → `packages/core/src/tests/*.test.ts` via `npm test`

The scope here is interface-layer regressions. Engine bugs go through the audit + test path.