# Vue↔React 使用级 parity 对比工具 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 一个确定性 Playwright parity gate，对双框架组件用同一份 props + 同一份 slot 内容在两 harness 各渲一次，直接互比 Vue-actual ↔ React-actual，抓 slot-drop（结构残缺）与样式漂移。 **Architecture:** 复用现有两 render-verification harness（Vue 5173 = canonical SFC/light-DOM；React 5174 = `` CE/shadow-DOM）。C（可见文本+元素轮廓互比）= day-one gate、限风险集 TopBar/FormItem/PillStatus；A（计算样式互比）= baseline-first survey。slot 内容走独立 fixture（不污染 Figma-derived manifest），两 harness 各加最小注入。对比器专用 actual-vs-actual（不复用 Figma 专用的 `buildChecks`）。 **Tech Stack:** Playwright（`@playwright/test`）、Vue 3.5、React 18、TypeScript、pnpm、vitest（对比器纯函数单测）。复用 `tests/visual-verify/lib/drift-compare-core.ts` 的 `collectActual`/`normalizeHex`/`colorToHex`/`closeEnough`。 ## Global Constraints - **设计真源**：`docs/superpowers/specs/2026-07-13-vue-react-usage-parity-tool-design.md`（本 plan 实现它 = **D1 harness parity gate**；D2 单一来源 demo 另立 spec）。 - **执行前置已解除（2026-07-13 晚精化）**：初稿要求"等并行 session light-DOM 修复落地"——该修复 **不必要且未发生**（slot-drop 前提被 Step 0 证伪，见 spec §1）。**当前工作树干净、master、shadow-DOM 基线即最终基线，直接在 HEAD 建。** - **baseline 状态（Step 0 已核）**：Vue `test:render-verification` 绿；React `test:render-verification-react` 有 **8 处已知 committed FormItem-radio rootWidth 红**（`docs/internal/react-render-verification-report.md`，不在 CI、非本工具引入）。本工具**不修它**，A-broad survey 记录+triage（spec §8）。 - **implementer 不自 commit**：SDD implementer 只报 diff+stdout；controller（我）复审 + task-reviewer 过后由 controller commit（[[feedback_executor-no-self-commit]]）。commit 只 `git add` 具体文件、绝不 `-A`；push 后用 `git ls-remote` 权威确认 SHA（origin 双推 Gitea+GitHub，瞬时 rejected 常见）。 - **默认无 fixture 时两 harness 行为不变**：现有 `test:render-verification` / `test:render-verification-react` 必须**状态不变**（Vue 全绿；React 仍是上面那 8 处已知红，不新增）——slot/Logo 注入是 opt-in（仅当 manifestId 命中 fixture / == `parity-logo`）。 --- ## Task 0: 执行前置核查（无代码，gate）— 已由本 session Step 0 完成 **Files:** 只读核查，不改文件。**本 session 现实复验已做完，结论固化如下**，实现 subagent 起手快速复核即可。 - [x] **Step 1: 工作树 + 基线（Step 0 已确认）** - `git status` 干净、master、up-to-date（无并行 session 在飞）。 - `components.config.ts`：TopBar/FormItem/PillStatus **无 `shadowRoot:false`** = 默认 shadow-DOM（light-DOM 转换未发生、不必要）。 - Vue `test:render-verification` 绿；React `test:render-verification-react` = 8 处**已知 committed** FormItem-radio rootWidth 红（非本工具引入，不在 CI）。 - [x] **Step 2: slot 投影 live 确认（Step 0）**：F54 六 case 全 pass；TopBar CE live logo/menu/right-content 三具名 slot 正常投影（menu 受 `showMenu` prop 门控）。→ **slot-drop 不存在，C 作回归护栏**。 - [x] **Step 3: 车道文件当前形态已读**：`RenderHarness.tsx`（`renderComponent`/`adaptProps` L116-153，data-manifest-id 在 L237 wrapper）、`RenderHarnessPage.vue`、`components.config.ts`、`drift-compare-core.ts`（`collectActual` L181 / `closeEnough` L135 = `(a,b)=>|a-b|<=1`）已在本 session 主线读过，行号以当前 HEAD 为准。 > 实现 subagent 起手仅需 `git status`（确认仍干净）+ `pnpm build:wc` 是否需重跑（Step 0 已于 18:12 重建过 dist-wc）。**无需再等任何并行修复。** --- ## Task 1: 抽共享可序列化收集器（`collectVisibleText` + `collectElementOutline`） **Files:** - Create: `tests/parity/lib/collect-visible.ts` - Test: `tests/parity/lib/collect-visible.test.ts` **Interfaces:** - Produces: `export const collectVisibleText: () => string`（穿 open shadow root、checkVisibility 门控、`' | '` join）；`export const collectElementOutline: () => Record`（计数 nav/a/button/input/img/svg + CE tag，即含 `-` 的 tagName）。两者**必须 self-contained**（无 module 外引用），供 `page.evaluate(fn)` 序列化。 - [ ] **Step 1: 写失败单测** ```ts // tests/parity/lib/collect-visible.test.ts import { describe, it, expect } from 'vitest' import { collectVisibleText, collectElementOutline } from './collect-visible' describe('collectVisibleText', () => { it('collects visible text tokens joined by pipe', () => { document.body.innerHTML = '
AlphaBeta
' // jsdom 无 checkVisibility → 函数回退 true，全部计入 const text = collectVisibleText() expect(text).toContain('Alpha') expect(text).toContain('Beta') }) }) describe('collectElementOutline', () => { it('counts semantic + custom elements', () => { document.body.innerHTML = '' const outline = collectElementOutline() expect(outline.nav).toBe(1) expect(outline.a).toBe(1) expect(outline.button).toBe(1) expect(outline.customElement).toBe(1) }) }) ``` - [ ] **Step 2: 跑测确认失败** Run: `pnpm vitest run tests/parity/lib/collect-visible.test.ts` Expected: FAIL — 模块不存在。 - [ ] **Step 3: 实现（`collectVisibleText` 逐字移植自 `named-slot-projection.spec.ts` L35-52，新增 outline）** ```ts // tests/parity/lib/collect-visible.ts // Self-contained collectors for page.evaluate() — NO external module refs // (they are serialized into the browser context). collectVisibleText is moved // verbatim from tests/render-verification-react/named-slot-projection.spec.ts. export const collectVisibleText = (): string => { const out: string[] = [] const walk = (root: Document | ShadowRoot) => { for (const el of Array.from(root.querySelectorAll('*'))) { if ((el as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot) { walk((el as Element & { shadowRoot: ShadowRoot }).shadowRoot) } for (const n of Array.from(el.childNodes)) { if (n.nodeType === 3 && (n.textContent ?? '').trim()) { const vis = typeof (el as unknown as { checkVisibility?: (o: object) => boolean }).checkVisibility === 'function' ? (el as unknown as { checkVisibility: (o: object) => boolean }).checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }) : true if (vis) out.push((n.textContent ?? '').trim()) } } } } walk(document) return out.join(' | ') } export const collectElementOutline = (): Record => { const counts: Record = { nav: 0, a: 0, button: 0, input: 0, img: 0, svg: 0, customElement: 0 } const walk = (root: Document | ShadowRoot) => { for (const el of Array.from(root.querySelectorAll('*'))) { const tag = el.tagName.toLowerCase() if (tag in counts) counts[tag]++ if (tag.includes('-')) counts.customElement++ if ((el as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot) { walk((el as Element & { shadowRoot: ShadowRoot }).shadowRoot) } } } walk(document) return counts } ``` - [ ] **Step 4: 跑测确认通过** Run: `pnpm vitest run tests/parity/lib/collect-visible.test.ts` Expected: PASS（两 describe 全绿）。 - [ ] **Step 5: 把 `named-slot-projection.spec.ts` 的局部 `collectVisibleText` 换成 import**（去重，但保持其序列化用法） 在 `tests/render-verification-react/named-slot-projection.spec.ts` 内，删除 L35-52 的局部 `const collectVisibleText`，改从共享模块引入。⚠️ 因 `page.evaluate(fn)` 序列化要求函数体不闭包 module 引用——`collectVisibleText` 无外部引用，直接 `import { collectVisibleText } from '../parity/lib/collect-visible'` 后 `page.evaluate(collectVisibleText)` 仍成立（Playwright 序列化函数源码）。 ```ts // 顶部 import 区 import { collectVisibleText } from '../parity/lib/collect-visible' // 删除原 L35-52 局部定义；其余 CASES/for 循环不变 ``` - [ ] **Step 6: 跑 React 名 slot gate 确认仍绿** Run: `pnpm test:render-verification-react 2>&1 | tail -8` Expected: INFRA-F54 named-slot projection 6 cases 仍 PASS。 - [ ] **Step 7: 报 diff + stdout（不 commit）** --- ## Task 2: 专用 actual-vs-actual 对比器 **Files:** - Create: `tests/parity/lib/parity-compare.ts` - Test: `tests/parity/lib/parity-compare.test.ts` **Interfaces:** - Consumes: `collectActual` 的返回扁平对象（`{ width, height, paddingTop..Left, borderRadius, gap, opacity, color, backgroundColor, borderColor, borderWidth, textColor?, ... } | { missingTarget: true }`）；`normalizeHex`/`colorToHex`/`closeEnough` from `../../visual-verify/lib/drift-compare-core`。 - Produces: - `export function compareVisibleText(vue: string, react: string): { vueOnly: string[]; reactOnly: string[]; shared: string[] }` - `export function assertSlotTokensPresent(text: string, tokens: string[]): { missing: string[] }` - `export function compareComputedStyle(vue: any, react: any): { field: string; vue: unknown; react: unknown }[]`（数值 field 用 closeEnough、颜色 field 归一 hex 后比、其余字符串精确） - [ ] **Step 1: 写失败单测** ```ts // tests/parity/lib/parity-compare.test.ts import { describe, it, expect } from 'vitest' import { compareVisibleText, assertSlotTokensPresent, compareComputedStyle } from './parity-compare' describe('compareVisibleText', () => { it('splits pipe-joined text into token sets and diffs', () => { const r = compareVisibleText('Logo | Menu | Title', 'Title') expect(r.vueOnly.sort()).toEqual(['Logo', 'Menu']) expect(r.reactOnly).toEqual([]) expect(r.shared).toEqual(['Title']) }) }) describe('assertSlotTokensPresent', () => { it('reports missing slot tokens', () => { expect(assertSlotTokensPresent('Title', ['Logo', 'Menu', 'Title']).missing.sort()).toEqual(['Logo', 'Menu']) expect(assertSlotTokensPresent('Logo | Menu | Title', ['Logo', 'Menu']).missing).toEqual([]) }) }) describe('compareComputedStyle', () => { it('flags color diff by normalized hex, ignores sub-px numeric noise', () => { const vue = { width: 100.2, backgroundColor: 'rgb(255, 0, 0)', color: '#141414' } const react = { width: 100.0, backgroundColor: '#ff0000', color: 'rgb(20, 20, 20)' } const diffs = compareComputedStyle(vue, react) expect(diffs).toEqual([]) // width within closeEnough, colors equal after hex-normalize }) it('flags a real background mismatch', () => { const diffs = compareComputedStyle({ backgroundColor: '#ffffff' }, { backgroundColor: '#000000' }) expect(diffs.map(d => d.field)).toContain('backgroundColor') }) }) ``` - [ ] **Step 2: 跑测确认失败** Run: `pnpm vitest run tests/parity/lib/parity-compare.test.ts` Expected: FAIL — 模块不存在。 - [ ] **Step 3: 实现** ```ts // tests/parity/lib/parity-compare.ts import { normalizeHex, colorToHex, closeEnough } from '../../visual-verify/lib/drift-compare-core' const NUMERIC_FIELDS = new Set(['width', 'height']) const COLOR_FIELDS = new Set(['color', 'backgroundColor', 'borderColor', 'textColor']) function tokens(text: string): string[] { return text.split(' | ').map(t => t.trim()).filter(Boolean) } export function compareVisibleText(vue: string, react: string) { const v = new Set(tokens(vue)) const r = new Set(tokens(react)) return { vueOnly: [...v].filter(t => !r.has(t)), reactOnly: [...r].filter(t => !v.has(t)), shared: [...v].filter(t => r.has(t)), } } export function assertSlotTokensPresent(text: string, expected: string[]) { const have = new Set(tokens(text)) return { missing: expected.filter(t => !have.has(t)) } } export function compareComputedStyle(vue: Record, react: Record) { const diffs: { field: string; vue: unknown; react: unknown }[] = [] const fields = new Set([...Object.keys(vue), ...Object.keys(react)]) for (const field of fields) { const a = vue[field] const b = react[field] if (a === undefined || b === undefined) continue if (NUMERIC_FIELDS.has(field)) { if (!closeEnough(Number(a), Number(b))) diffs.push({ field, vue: a, react: b }) } else if (COLOR_FIELDS.has(field)) { const ah = normalizeHex(colorToHex(String(a))) const bh = normalizeHex(colorToHex(String(b))) if (ah !== bh) diffs.push({ field, vue: a, react: b }) } else { if (String(a) !== String(b)) diffs.push({ field, vue: a, react: b }) } } return diffs } ``` > ⚠️ Task 0 落地后核实 `closeEnough` 容差语义（`drift-compare-core.ts:135`）；若签名非 `(a,b)=>bool` 则 re-anchor 调用。 - [ ] **Step 4: 跑测确认通过** Run: `pnpm vitest run tests/parity/lib/parity-compare.test.ts` Expected: PASS。 - [ ] **Step 5: 报 diff + stdout（不 commit）** --- ## Task 3: slot fixture（风险集） **Files:** - Create: `tests/parity/slot-fixtures.ts` - Test: `tests/parity/slot-fixtures.test.ts` **Interfaces:** - Produces: `export type SlotFixture = { slots: Record; expectTokens: string[] }`；`export const SLOT_FIXTURES: Record`（键 = `codeComponent`）。`slots` = 具名 slot → **纯文本 token**（两侧可等价渲染的最稳形态）；`expectTokens` = C gate 断言两侧可见文本都须含的 token 集。 - [ ] **Step 1: 发现风险集组件的真实 slot 名** ```bash # TopBar slot outlets 在嵌套 BaseTopBar；canonical 只转发 grep -n " { it('covers the named-slot risk set', () => { expect(Object.keys(SLOT_FIXTURES).sort()).toEqual(['FormItem', 'PillStatus', 'TopBar']) }) it('every fixture declares non-empty slots and expectTokens', () => { for (const [name, fx] of Object.entries(SLOT_FIXTURES)) { expect(Object.keys(fx.slots).length, name).toBeGreaterThan(0) expect(fx.expectTokens.length, name).toBeGreaterThan(0) // expectTokens 必须都出现在某个 slot 值里（否则断言恒失败） const allSlotText = Object.values(fx.slots).join(' ') for (const tok of fx.expectTokens) expect(allSlotText, `${name}:${tok}`).toContain(tok) } }) }) ``` - [ ] **Step 3: 实现（slot 名用 Step 1 实测值 re-anchor）** ```ts // tests/parity/slot-fixtures.ts // Synthetic, framework-neutral slot content shared by BOTH harnesses so a // slot-drop shows up as a missing visible-text token on one side. Plain text // tokens = the most representation-stable content. Slot NAMES verified against // the post-fix canonical components (see plan Task 3 Step 1). export type SlotFixture = { slots: Record; expectTokens: string[] } export const SLOT_FIXTURES: Record = { TopBar: { slots: { logo: 'PARITY_LOGO', menu: 'PARITY_MENU', 'right-content': 'PARITY_RIGHT' }, expectTokens: ['PARITY_LOGO', 'PARITY_MENU', 'PARITY_RIGHT'], }, FormItem: { slots: { label: 'PARITY_LABEL' }, expectTokens: ['PARITY_LABEL'], }, PillStatus: { slots: { default: 'PARITY_PILL' }, expectTokens: ['PARITY_PILL'], }, } ``` > ⚠️ 若 Step 1 实测 slot 名与上表不同（如 TopBar 无 `right-content`），以实测改键；`expectTokens` 随之调整。default slot 在 React 侧 = 无 `slot` 属性的 children。 - [ ] **Step 4: 跑测确认通过** Run: `pnpm vitest run tests/parity/slot-fixtures.test.ts` Expected: PASS。 - [ ] **Step 5: 报 diff + stdout（不 commit）** --- ## Task 4: Vue harness slot 注入（`RenderHarnessPage.vue`） **Files:** - Modify: `playground/docs/pages/RenderHarnessPage.vue`（当前渲染在 L83-98；`componentAttrs` L69-72） **Interfaces:** - Consumes: `SLOT_FIXTURES` from `tests/parity/slot-fixtures`（相对路径 `../../../tests/parity/slot-fixtures`）。 - Produces: 命中 fixture 的 entry 额外渲染具名 slot 内容；未命中时渲染不变。 - [ ] **Step 1: 加 fixture 查表 computed** 在 `