feat(core): add decompose-to-ui-kit + boolean parity verifiers (Phase 1 of #225)

[HomenShum]

Summary

Phase 1 of #225: a single-image → componentized ui_kit/ decomposition pipeline that emits a coding-agent-ready bundle, plus deterministic + vision verifiers that self-check parity using a 12-question boolean rubric and re-iterate on gaps. Uses existing userImages plumbing (PR #193) and adds three new agent tools that mirror existing patterns (done.ts / generate-image-asset.ts). Ends in the chat sidebar with a one-click trigger that fires a structured prompt, walks the agent through decompose → verify → reconcile → done, and surfaces per-decompose cost as a toast. No new prod deps, no SQLite schema change, in-memory output via the Files panel.

This PR closes the Phase 1 part of #225 only. The Phase 2 (gpt-image-2 generation in the loop) and Phase 3 (multi-page flow) cuts I committed to in the issue thread are intentionally not included.

Type of change

• New feature

Linked issue

Closes #225 (Phase 1 only — Phase 2/3 deferred per my comment)

What's in here

3 new agent tools in packages/core/src/tools/:

1. decompose-to-ui-kit.ts — orchestrator. Takes a source image (from chat context) + design brief, emits ui_kits/<slug>/{index.html, components/*.tsx, tokens.css, manifest.json, README.md} to the virtual FS. Output carries schemaVersion: 1 so downstream coding agents (Claude Code, Cursor) can evolve safely.
2. verify-ui-kit-parity.ts — deterministic verifier. 3 signals: element-count parity, visible-text coverage, token coverage. Returns a ParityReport with passCount/totalChecks derived score (no LLM in the loop, no floats).
3. verify-ui-kit-visual-parity.ts — vision-LLM judge wrapper. Takes a host-injected judgeVisualParity callback, runs a 12-check boolean rubric across 5 dimensions (layout / color / typography / content / components), returns parityScore = passCount / totalChecks and a bounded-enum status (verified | needs_review | needs_iteration | failed | unavailable).

Host wiring in apps/desktop/src/main/:

• render-ui-kit.ts — offscreen BrowserWindow.capturePage() for the rendered ui_kit
• judge-visual-parity.ts — vision-judge prompt builder + LLM dispatcher using the existing complete() provider abstraction
• Both injected into the agent via agent.ts deps interface, mirroring how generate_image_asset was wired

Renderer:

• AddMenu.tsx — new "Decompose to UI Kit" entry, disabled when no artifact / generation in flight
• Sidebar.tsx — triggerDecompose(designId, locale) action wired to the menu item
• store.ts — 3-branch toast feedback (busy / unavailable / started) + per-tool-call cost row when the visual judge resolves
• hooks/decomposePrompt.ts — locale-aware (EN/ZH) structured prompt that walks the agent through decompose → verify → reconcile → iterate (max 2) → done with HONEST cost summary

Tests — full vitest coverage in *.test.ts next to each tool:

• decompose-to-ui-kit.test.ts (263 LOC)
• verify-ui-kit-parity.test.ts (180 LOC)
• verify-ui-kit-visual-parity.test.ts (295 LOC)

i18n — 9 new keys × EN + ZH for the menu entry, toast titles/descriptions, and cost row.

Design decisions

Boolean rubric, not floats. Every visual parity check is {passed: boolean}, derived parityScore = passCount / totalChecks. The status field is a bounded enum derived from thresholds (100% → verified, ≥85% → needs_review, ≥60% → needs_iteration, <60% → failed). No LLM-fabricated confidence floats, no scoring inflation. Aligns with the project's HONEST_SCORES precedent (done.ts's verified: boolean field).

Host-injected callbacks, not framework lock-in. verify-ui-kit-visual-parity.ts doesn't import any LLM SDK or any Electron API. It takes RenderUiKitFn and JudgeVisualParityFn as deps. If the host doesn't inject them (e.g. a future headless CLI), the tool returns status: 'unavailable' honestly instead of crashing. Mirrors how generate_image_asset is keyed on deps.generateImageAsset.

In-memory output via Files panel, no schema bump. Per my open binary in the issue thread, this PR ships option (a): the ui_kits/<slug>/ lands in the design's virtual FS, surfaces in the existing Files panel, and uses the existing ZIP export for handoff to a coding agent. No SQLite migration, smallest blast radius, consistent with how polishPrompt.ts's second-pass mutates only in-memory state.

schemaVersion: 1 on the manifest. Downstream consumers (Claude Code, Cursor) need a stable contract. Adding fields requires no version bump; renaming or removing fields requires schemaVersion: 2 and a parallel-emit window.

Anti-hallucination guardrails

The deterministic verifier (verify-ui-kit-parity.ts) checks visible-text coverage on the emitted ui_kit vs the source brief — if the agent dropped any text content, it fails BEFORE the LLM judge runs. This catches data hallucination cheap. The LLM judge then handles only semantic-quality dimensions (visual hierarchy, color harmony, typography pairing, etc.).

Cost surfacing

Every verify_ui_kit_visual_parity resolution pushes a toast with passCount/totalChecks · status · $cost.NNNN. Reads defensively from result.details so future contract drift degrades silently rather than crashing the renderer. The done tool's prompt-driven summary additionally requires the agent to report total run cost, per the HONEST_STATUS precedent.

Checklist

• I read docs/VISION.md, docs/PRINCIPLES.md, and CLAUDE.md before starting
• Commits are signed with DCO (git commit -s)
• pnpm lint && pnpm typecheck && pnpm test passes locally (1026 tests pass on this branch as of d6f3a00)
• Added/updated tests for the change (738 LOC across 3 new test files)
• Added a changeset (pnpm changeset) — see .changeset/decompose-to-ui-kit.md
• Updated docs if behavior changed — BENCHMARKS.md (new), README.md + README.zh-CN.md (Decompose to UI Kit feature card + hero PNG + iter-reel GIF)

Dependency additions (if any)

None. All three new tools use only @mariozechner/pi-agent-core's AgentTool factory pattern that's already a prod dep.

Screenshots / recordings (UI changes)

Side-by-side hero — source vs agent-emitted ui_kit (e2e-opus-final run, parityScore 0.90):

4-frame reconcile reel from the e2e-nodebench-iter run (iter-0 → iter-1 with honest score drift 0.82 → 0.78 — boolean rubric exposes the regression instead of hiding it):

MP4 version for higher fidelity.

Live-recorded session demo (real Electron app, no stitching) — recording in progress, will edit this PR description when the GIF is ready. ETA same day.

Cross-tier benchmarks

BENCHMARKS.md at repo root has the full methodology + run-by-run real-data results across model tiers (Opus, Pro+Pro+iterate, Kimi+Gemini3, NodeBench iter), reproducibility instructions, honest non-claims, and research citations (WebDevJudge, Prometheus-Vision, Trust-but-Verify ICCV 2025).

Run	Decompose	Judge	parityScore	Gaps surfaced
e2e-opus-final	claude-opus-4-1	claude-opus-4-1	0.90	4
e2e-nodebench-iter (iter-0)	gemini-3-pro-preview	gemini-3-pro-preview	0.82	6
e2e-nodebench-iter (iter-1)	gemini-3-pro-preview	gemini-3-pro-preview	0.78	5
e2e-bank-kimi-gemini3	kimi-k2.6	gemini-3-pro-preview	0.78	8
e2e-nodebench-B	kimi-k2.6	gemini-3-pro-preview	0.60	7

Note the iter-0 → iter-1 regression on the same source: agent fixed some gaps but introduced new layout drift. The boolean rubric exposes this honestly rather than fudging the score upward. This is the intended behavior, not a bug.

Scope discipline notes

• PR size: ~1500 LOC of substantive change (3 tools + 3 test files + agent wiring + i18n + 1 hook). Most of the diff stat (pnpm-lock.yaml) is mechanical regen. This is over the soft 400-LOC bar in CONTRIBUTING.md, but it's been pre-discussed in [Feature]: image 2 已经够厉害了，最需要的是如何把生成好的UI 变成组件化，再到原型的过程！ #225 and the change is a single concern (one new feature path, no refactor mixed in). Happy to split into 3 PRs (per-tool) if maintainer prefers — say the word.
• What's NOT in scope (from [Feature]: image 2 已经够厉害了，最需要的是如何把生成好的UI 变成组件化，再到原型的过程！ #225 thread): multi-page flow (Phase 3, separate issue), gpt-image-2 generation step (Phase 2, separate Discussion), persistence-to-disk (option (b) from the binary I posed — staying with option (a) for blast radius)
• Three systemic dependencies surfaced during dogfood (rollback / capability-aware failover / spiral-detector): filing as separate Discussions in Ideas category, not bundling here. Each is a meaningful subsystem that deserves alignment before code.

Branch state at PR open

• 9 commits ahead of upstream/main
• 11 commits behind (mostly chore(deps) bumps including pi-agent-core 0.67.68 → 0.70.2; my branch is on 0.67.68)
• Will rebase against latest main on request — wanted to open the PR with the as-built state for clarity first. The pi-agent-core 0.70.2 bump may require small adjustments to the new tools' AgentTool shape; I'll handle that in the rebase pass.

Why this is ready to review now

• Real cross-tier benchmarks in BENCHMARKS.md, not synthetic
• Visual proof embedded above (hero + reel)
• Test coverage matches existing tools
• Pattern conformance: every new file mirrors an existing precedent
• Deliberate scope: closes Phase 1 of the issue cleanly, defers the rest visibly

Looking forward to feedback. Happy to address structural concerns first before iterating on smaller polish.

[github-actions]

Findings

• [Major] Decompose loop success can never trigger on the first clean pass — decomposePrompt.ts requires both verifiers to return verified or needs_review, but the deterministic verifier only returns ok or needs_iteration. That forces an unnecessary extra iteration even when deterministic parity already passed, which adds avoidable cost and can regress a good bundle, evidence apps/desktop/src/renderer/src/hooks/decomposePrompt.ts:67, packages/core/src/tools/verify-ui-kit-parity.ts:35, packages/core/src/tools/verify-ui-kit-parity.ts:294.
  Suggested fix:

  const deterministicPass = deterministic.status === 'ok';
  const visualPass =
    visual.status === 'unavailable' ||
    visual.status === 'verified' ||
    visual.status === 'needs_review';
  if (deterministicPass && visualPass) {
    // call done
  }

• [Major] verify_ui_kit_visual_parity({slug}) has no source image on the default runtime path — the tool defaults to source.png, but the agent FS is initialized with index.html, frames, and skills only, while preparePromptContext() keeps attachments in prompt context instead of persisting them into the virtual FS. In normal runs the visual verifier therefore degrades to unavailable instead of actually judging parity, evidence packages/core/src/tools/verify-ui-kit-visual-parity.ts:291, apps/desktop/src/main/index.ts:294, apps/desktop/src/main/index.ts:879, apps/desktop/src/main/prompt-context.ts:287.
  Suggested fix:

  const firstImage = promptContext.attachments.find((a) => a.imageDataUrl);
  if (firstImage?.imageDataUrl) {
    await fs.create('source.png', firstImage.imageDataUrl);
  }

• [Major] Judge/render failures do not fall back to a structured result — makeJudgeVisualParity() throws on empty or non-JSON model replies, and verify_ui_kit_visual_parity awaits both renderUiKit() and judgeVisualParity() without catching those failures. On a text-only model or malformed judge response, the tool errors instead of returning the advertised status: "unavailable" path, evidence apps/desktop/src/main/judge-visual-parity.ts:153, apps/desktop/src/main/judge-visual-parity.ts:197, packages/core/src/tools/verify-ui-kit-visual-parity.ts:311.
  Suggested fix:

  try {
    const candidateImg = await renderUiKit(decomposed.content, signal);
    const judgeResult = await judgeVisualParity(sourceImg, candidateImg, signal);
    // existing normalization...
  } catch (error) {
    const report = unavailableReport(
      error instanceof Error ? error.message : String(error),
    );
    return { content: [{ type: 'text', text: report.summary }], details: report };
  }

• [Major] This still looks like partial work for #225, so Closes #225 is misleading — the public PR template says to use Closes only when the issue is fully resolved, but this diff stops at emitting a ui_kits/<slug>/ handoff bundle and explicitly tells the agent not to continue into the downstream prototype flow, evidence .github/PULL_REQUEST_TEMPLATE.md:11, .changeset/decompose-to-ui-kit.md:9, apps/desktop/src/renderer/src/hooks/decomposePrompt.ts:58, packages/core/src/tools/decompose-to-ui-kit.ts:155.
  Suggested fix:

  Refs #225

Summary

• Review mode: initial
• Found 4 issues: one decompose-loop contract bug, two visual-verifier runtime gaps, and one incomplete issue-closure claim.

Testing

• Not run (automation). Suggested: add one agent-runtime integration test that seeds an image attachment into the virtual FS and asserts verify_ui_kit_visual_parity can read it, plus one unit test that judge/render failures return a structured fallback instead of throwing.

open-codesign Bot

[github-actions]

verify_ui_kit_parity never returns verified or needs_review, so the success branch described here can never fire. Even a clean deterministic pass gets forced into the iteration path and burns another full decompose cycle.

Suggested fix:

const deterministicPass = deterministic.status === 'ok';
const visualPass =
  visual.status === 'unavailable' ||
  visual.status === 'verified' ||
  visual.status === 'needs_review';

[github-actions]

This tool defaults to source.png, but nothing in the runtime seeds an attached image into the agent FS before the tool runs. On the default path that means the visual verifier returns unavailable instead of ever judging parity.

Suggested fix:

const firstImage = promptContext.attachments.find((a) => a.imageDataUrl);
if (firstImage?.imageDataUrl) {
  await fs.create('source.png', firstImage.imageDataUrl);
}

[github-actions]

The fallback described in the prompt only works for missing dependencies/files. If renderUiKit() or judgeVisualParity() throws (for example on a text-only model or malformed JSON), this tool currently errors instead of returning a structured unavailable/failed report.

Suggested fix:

try {
  const candidateImg = await renderUiKit(decomposed.content, signal);
  const judgeResult = await judgeVisualParity(sourceImg, candidateImg, signal);
} catch (error) {
  const report = unavailableReport(error instanceof Error ? error.message : String(error));
  return { content: [{ type: 'text', text: report.summary }], details: report };
}

[github-actions]

This release note says the phase is closed, but the shipped flow still stops at producing a handoff bundle and explicitly does not continue into the downstream prototype step. Per the public PR template, this should be Refs #225 unless the full issue scope is implemented here.

Suggested fix:

Refs #225

[github-actions]

Findings

• [Major] Decompose loop success can never trigger on the first clean pass — decomposePrompt.ts still requires both verifiers to return verified or needs_review, but verify_ui_kit_parity only returns ok or needs_iteration. A clean deterministic pass therefore gets forced into another full decompose cycle, which adds avoidable cost and can regress a good bundle, evidence apps/desktop/src/renderer/src/hooks/decomposePrompt.ts:72, packages/core/src/tools/verify-ui-kit-parity.ts:35, packages/core/src/tools/verify-ui-kit-parity.ts:300.
  Suggested fix:

  const deterministicPass = deterministic.status === 'ok';
  const visualPass =
    visual.status === 'unavailable' ||
    visual.status === 'verified' ||
    visual.status === 'needs_review';
  if (deterministicPass && visualPass) {
    // call done
  }

• [Major] verify_ui_kit_visual_parity({slug}) still has no source image on the default runtime path — the tool defaults to source.png, but the runtime only prepares attachment context and passes images to the model wire; it never persists an attached image into the agent FS. On the normal path the visual verifier therefore returns unavailable instead of actually judging parity, evidence packages/core/src/tools/verify-ui-kit-visual-parity.ts:291, apps/desktop/src/main/prompt-context.ts:287, apps/desktop/src/main/index.ts:914, packages/core/src/index.ts:203.
  Suggested fix:

  const firstImage = promptContext.attachments.find((a) => a.imageDataUrl);
  if (firstImage?.imageDataUrl) {
    await fs.create('source.png', firstImage.imageDataUrl);
  }

• [Major] Judge/render failures still bypass the advertised structured fallback — makeJudgeVisualParity() throws on empty or non-JSON model replies, and verify_ui_kit_visual_parity still awaits both renderUiKit() and judgeVisualParity() without catching those failures. On a text-only model or malformed judge response, the tool errors instead of returning the promised status: "unavailable" path, evidence apps/desktop/src/main/judge-visual-parity.ts:198, apps/desktop/src/main/judge-visual-parity.ts:210, packages/core/src/tools/verify-ui-kit-visual-parity.ts:312.
  Suggested fix:

  try {
    const candidateImg = await renderUiKit(decomposed.content, signal);
    const judgeResult = await judgeVisualParity(sourceImg, candidateImg, signal);
    // existing normalization...
  } catch (error) {
    const report = unavailableReport(
      error instanceof Error ? error.message : String(error),
    );
    return { content: [{ type: 'text', text: report.summary }], details: report };
  }

• [Major] The issue-closing claim is still overstated for this slice — the public PR template says to use Closes only when the issue is fully resolved, but this diff still stops at emitting a ui_kits/<slug>/ handoff bundle and explicitly tells the agent not to continue into the downstream prototype step, evidence .github/PULL_REQUEST_TEMPLATE.md:11, .changeset/decompose-to-ui-kit.md:9, apps/desktop/src/renderer/src/hooks/decomposePrompt.ts:58, packages/core/src/tools/decompose-to-ui-kit.ts:155.
  Suggested fix:

  Refs #225

Summary

• Review mode: follow-up after new commits. The new commit fixes the script/style stripping issue, but these 4 major issues are still present on the latest head.

Testing

• Not run (automation). Suggested: add one agent-runtime integration test that seeds an image attachment into the virtual FS and asserts verify_ui_kit_visual_parity can read it, plus one unit test that render/judge failures return a structured fallback instead of throwing.

open-codesign Bot

[github-actions]

verify_ui_kit_parity still never returns verified or needs_review, so this success branch can never fire. Even a clean deterministic pass gets forced into another full decompose cycle.

Suggested fix:

const deterministicPass = deterministic.status === 'ok';
const visualPass =
  visual.status === 'unavailable' ||
  visual.status === 'verified' ||
  visual.status === 'needs_review';
if (deterministicPass && visualPass) {
  // call done
}

[github-actions]

This tool still defaults to source.png, but nothing in the runtime persists an attached image into the agent FS before the tool runs. On the default path that means the visual verifier returns unavailable instead of ever judging parity.

Suggested fix:

const firstImage = promptContext.attachments.find((a) => a.imageDataUrl);
if (firstImage?.imageDataUrl) {
  await fs.create('source.png', firstImage.imageDataUrl);
}

[github-actions]

The fallback described in the prompt still only covers missing dependencies/files. If renderUiKit() or judgeVisualParity() throws (for example on a text-only model or malformed JSON), this tool errors instead of returning a structured unavailable report.

Suggested fix:

try {
  const candidateImg = await renderUiKit(decomposed.content, signal);
  const judgeResult = await judgeVisualParity(sourceImg, candidateImg, signal);
} catch (error) {
  const report = unavailableReport(error instanceof Error ? error.message : String(error));
  return { content: [{ type: 'text', text: report.summary }], details: report };
}

[github-actions]

This release note still says the phase is closed, but the shipped flow stops at producing a handoff bundle and explicitly does not continue into the downstream prototype step. Per the public PR template, this should be Refs #225 unless the full issue scope is implemented here.

Suggested fix:

Refs #225