PixelRosetta

High-fidelity Sketch-to-code for AI coding agents. PixelRosetta converts .sketch designs into structured DOM, Vue, React, HTML, native image assets, and traceable implementation specs through CLI, MCP, and agent plugins.

Unlike screenshot-only generators, PixelRosetta preserves the Sketch layer tree, design facts, asset relationships, and component-mapping decisions. It combines deterministic conversion with optional agent semantic tagging so forms, icons, images, slots, and reusable UI components can be represented appropriately in generated code.

Keywords: Sketch to code, design to code, Vue UI generator, React UI generator, AI coding agent, MCP server, design system mapping, high-fidelity UI.

v15.3 Vue UI delivery candidates

v15.3 adds a fail-closed production Vue compiler that creates an unsealed UI delivery candidate containing semantic Vue SFCs, shared styles, exact dependency requirements, component contracts, verification cases, Fact Ledger evidence, and read-only integration guidance. Candidate compilation never writes delivery-manifest.json and cannot report production pass; only the v15.4 mandatory gate suite and atomic sealer may do that.

Integration verification uses structured request files:

pixelrosetta verify-ui-package --request verification/verify-ui-package-request.json
pixelrosetta verify-integration --request verification/verify-integration-request.json

v15.4 Mandatory production gates

v15.4 verifies candidates in a pinned offline Vue harness. Certification requires six canonical passing reports in order: build, determinism, visual, responsive, accessibility, and evidence. Missing, skipped, malformed, or failed reports block delivery. Typed repairs are limited to three iterations and to allowlisted generated artifacts. delivery-manifest.json is written atomically and last; sealed packages can be checked without mutation through:

pixelrosetta verify-ui-package --request verification/verify-ui-package-request.json

v15.5 Evaluation release evidence

v15.5 adds deterministic public/private/format/failure/attack corpus reports, registry coverage, zero-skip CI receipts, npm allowlist and privacy scanning, dual SPDX 2.3/CycloneDX 1.6 SBOM evidence, checksums, and a strict five-report release evidence index. Every v15.5 candidate is permanently marked evaluation-only, publishable: false, with an unproven runtime matrix. Publishing and any unrestricted production claim remain exclusively owned by v15.6.

v15.6 GA evidence gate

v15.6 adds evidence-derived compatibility, locked performance SLOs, independent local-native/portable public-API E2E verification, and a terminal fail-closed GA readiness decision. The GA workflow remains an inert template until real 50-file, 200-artboard, three-release-line and signed supply-chain evidence completes the repository-owned finalization transaction.

v1 Scope

• Normalized JSON fixture importer for protocol validation.
• Sketch import support:
  • .sketch.json exports are accepted as normalized design input.
  • binary .sketch archives are read as zip files when they contain document.json and pages/*.json.
  • Sketch artboards are classified as page artboards or resource/cut artboards. Page artboards are render/codegen targets; resource artboards are associated assets for cut images and icon fallbacks.
  • when no artboard is specified, the importer selects the first page-like artboard and skips leading resource/cut sheets such as 切图.
  • artboardName, artboardId, repeated artboard selectors, and artboardSelection: all-pages|all-artboards are supported by CLI, MCP, and the programmatic API.
  • supported binary .sketch layer subset: artboard, group, text, shapeGroup, bitmap, and symbolInstance.
  • supported shapeGroup rendering includes rounded rectangles and oval/ellipse shape groups; rounded rectangle radius is preserved from either shapeGroup.fixedRadius or an inner rectangle.fixedRadius.
  • supported shapeGroup vector paths preserve simple closed straight paths as polygon clips; page/resource path vectors and safe small page-local vector/shape groups are emitted as generated PNG image assets when an asset output directory and vector rasterizer are available, with SVG kept only as a no-asset fallback preview path.
  • supported clipping masks preserve simple ellipse and rounded-rectangle masks for direct child content in the static preview.
  • supported artboards preserve explicit Sketch background colors in the static preview.
  • supported layers preserve numeric Sketch rotation in the static preview.
  • supported text layers preserve paragraph alignment in the static preview.
  • supported text layers preserve vertical alignment in the static preview.
  • supported text layers preserve kerning/letter spacing in the static preview.
  • supported text layers preserve italic font style in the static preview.
  • supported text layers preserve underline and strikethrough in the static preview.
  • supported text layers preserve multiple attributed text ranges in the static preview.
  • supported shape fills preserve simple linear and radial gradients in the static preview.
  • supported shape fills preserve multiple enabled fill layers in the static preview.
  • supported shape image fills are exported as assets and rendered in the static preview with non-repeating centered cover backgrounds.
  • supported bitmap and replacement cut assets render as centered cover image leaves in the static preview.
  • supported shape borders preserve multiple enabled border layers in the static preview.
  • supported shape borders preserve dashed border style in the static preview.
  • enabled Gaussian blur effects are preserved in the static preview.
  • supported CSS-compatible blend modes are preserved in the static preview.
  • enabled inner shadows are preserved in the static preview.
  • hidden layers and descendants of hidden groups are suppressed in the static preview.
  • parent group opacity is applied to descendants in the static preview.
  • simple local symbol instances are expanded from symbol masters, including proportional instance scaling and text string overrides.
  • Sketch tree paint order is preserved when groups are flattened for preview.
• Agent Page Spec v1 schema and runtime validation.
• Design token extraction for colors, typography, spacing, radii, shadows, borders, and opacity with source layer traceability.
• Non-color fills such as gradients and image URLs remain layout styles and are not emitted as color tokens.
• Deterministic HTML component mapping with project rules before defaults.
• Static HTML preview artifact generation from Agent Page Spec layout facts.
• CLI commands for inspect, parse, export, and validate.
• MCP tool wrappers over the same core engine.

PixelRosetta started as a traceable Agent Page Spec exporter. Current versions also emit source-traceable HTML, React, and Vue artifacts for agent handoff, with screenshot diffing and bounded repair loops layered on the same Page Spec boundary.

CLI

node src/cli.js inspect fixtures/normalized/home.json
node src/cli.js parse fixtures/normalized/home.json --out /tmp/pixelrosetta-parse
node src/cli.js export fixtures/normalized/home.json --profile default --out /tmp/pixelrosetta-export
node src/cli.js export path/to/file.sketch --profile default --out /tmp/pixelrosetta-sketch-export
node src/cli.js preview path/to/file.sketch --profile default --artboard-name 首页备份 --out /tmp/pixelrosetta-preview
node src/cli.js export path/to/file.sketch --artboard-selection all-pages --out /tmp/pixelrosetta-pages
node src/cli.js screenshot /tmp/pixelrosetta-preview/preview.html --out /tmp/pixelrosetta-screenshot --width 390 --height 844
node src/cli.js diff /tmp/pixelrosetta-screenshot/preview.png path/to/expected.png --out /tmp/pixelrosetta-diff --threshold 0.01
node src/cli.js analyze-diff /tmp/pixelrosetta-screenshot/preview.png path/to/expected.png --out /tmp/pixelrosetta-analysis --threshold 0.01
node src/cli.js generate path/to/file.sketch --target html --profile default --out /tmp/pixelrosetta-codegen
node src/cli.js generate path/to/file.sketch --target react --profile default --out /tmp/pixelrosetta-react
node src/cli.js generate path/to/file.sketch --target vue --profile default --out /tmp/pixelrosetta-vue
node src/cli.js convert path/to/file.sketch --target react --react-profile component --out /tmp/pixelrosetta-convert-react
node src/cli.js convert path/to/file.sketch --target vue --vue-profile component --component-binding-config pixelrosetta.components.json --out /tmp/pixelrosetta-vue
node src/cli.js repair-plan /tmp/pixelrosetta-export/page-spec.json /tmp/pixelrosetta-diff/report.json --out /tmp/pixelrosetta-repair
node src/cli.js repair-html /tmp/pixelrosetta-codegen /tmp/pixelrosetta-repair/repair-plan.json --max-patches 5
node src/cli.js repair-loop /tmp/pixelrosetta-codegen /tmp/pixelrosetta-export/page-spec.json path/to/expected.png --out /tmp/pixelrosetta-loop --max-iterations 3 --threshold 0.01
node src/cli.js semantic-request-design path/to/file.sketch --artboard-name 首页备份 --out /tmp/pixelrosetta-semantic
node src/cli.js semantic-request /tmp/pixelrosetta-export/page-spec.json --out /tmp/pixelrosetta-semantic
node src/cli.js semantic-validate /tmp/pixelrosetta-semantic/semantic-tagging-request.json /tmp/model-semantic-tags.json --out /tmp/pixelrosetta-semantic
node src/cli.js semantic-apply /tmp/pixelrosetta-export/page-spec.json --patch /tmp/model-semantic-tags.json --out /tmp/pixelrosetta-semantic
node src/cli.js convert path/to/file.sketch --target vue --semantic-patch /tmp/model-semantic-tags.json --out /tmp/pixelrosetta-vue-semantic
node src/cli.js validate /tmp/pixelrosetta-export/page-spec.json

The package also exposes a pixelrosetta binary when installed. export and preview write page-spec.json, diagnostics.json, and any extractable Sketch bitmap files under <out>/assets/. When --artboard-selection all-pages or all-artboards is used, they write page-spec.manifest.json plus one Page Spec per selected artboard. export, preview, generate, and convert also accept --semantic-patch <file>. The patch is validated and applied after the structured layout tree is built but before resource binding/native export and codegen decisions run, so an agent can preserve DOM for search fields or force non-replaceable icons/images to remain design assets without changing Sketch geometry, colors, text, or source ids. When supplied, PixelRosetta writes semantic-tagging-request.json, semantic-tagging-patch.json, semantic-tagging-validation.json, and page-spec.semantic.json beside the normal artifacts. Use semantic-request-design when an agent cannot pass a JavaScript semanticModelProvider: it writes a pre-binding semantic request directly from the design file, before resource binding, native export, preview, or codegen. The agent/model can fill a semantic patch from that request, then pass it to preview, generate, or convert with --semantic-patch.

Programmatic API

import {
  exportPageSpec,
  inspectDesignFile,
  parseDesignFile
} from 'pixelrosetta';

const summary = await inspectDesignFile('fixtures/normalized/home.json');
const ast = await parseDesignFile('fixtures/normalized/home.json');
const spec = await exportPageSpec('fixtures/normalized/home.json', {
  adapter: 'html',
  assetOutDir: '/tmp/pixelrosetta-export',
  semanticPatch: {
    schemaVersion: 'pixelrosetta.semantic-tagging.v1',
    tags: []
  },
  semanticModelProvider: {
    async completeJson(input) {
      return classifyDesignSemantics(input);
    }
  },
  designExportProvider: {
    available: true,
    packageName: 'sketch-native-export',
    async exportLayer(input) {
      // Return PNG bytes from a native design-tool export path for input.layerId.
      return { bytes: await exportLayerPng(input), contentType: 'image/png' };
    }
  },
  config: {
    confidenceThreshold: 0.8,
    rules: []
  }
});

designExportProvider is optional. When supplied, PixelRosetta prefers native PNG exports for complex visual groups and matched cut-resource layers before falling back to SVG/resvg vector reconstruction. This is the intended seam for Sketch App, Lanhu-style, or other design-platform exporters that can render a layer by id.

CLI and MCP callers cannot pass JavaScript functions, so they can use either a design export manifest, the automatic .sketch native export path, or the optional Sketch.app sketchtool provider.

node src/cli.js preview docs/company.sketch \
  --artboard-name "首页备份" \
  --design-export-manifest /tmp/native-exports/manifest.json \
  --out /tmp/pixelrosetta-preview

When Sketch.app is available locally, PixelRosetta defaults binary .sketch previews, exports, and codegen to safe native layer export. The CLI can use a known Sketch.app installation, PIXELROSETTA_SKETCHTOOL_PATH, or an explicit --sketchtool-path:

node src/cli.js preview docs/company.sketch \
  --artboard-name "首页备份" \
  --out /tmp/pixelrosetta-preview

For a portable package that another agent can use on a machine without Sketch.app, run native-pack on the Sketch-equipped machine. It writes the same preview artifacts plus assets/native/*.png, design-export-manifest.json, and reference-artboard.png:

pixelrosetta native-pack docs/company.sketch \
  --artboard-name "首页备份" \
  --out /tmp/pixelrosetta-native-pack

Move /tmp/pixelrosetta-native-pack together with the original .sketch file. On the machine without Sketch.app, pass the generated manifest:

pixelrosetta preview docs/company.sketch \
  --artboard-name "首页备份" \
  --design-export-manifest /tmp/pixelrosetta-native-pack/design-export-manifest.json \
  --out /tmp/pixelrosetta-preview

For designers who prefer a Sketch menu action, install the local Sketch plugin wrapper:

npm run install:sketch-plugin

Then use Plugins -> PixelRosetta -> Export Native Pack in Sketch. The local installer writes the current Node executable and this repository's src/cli.js path into the plugin resources, so the Sketch command can call the same native-pack pipeline without asking designers to assemble CLI flags. This is the local-test form; a packaged release can later bundle the PixelRosetta CLI inside the plugin.

To generate a Sketch-recognized .sketchplugin bundle instead of installing it immediately, run:

npm run package:sketch-plugin

This writes dist/PixelRosettaNativePack.sketchplugin, a directory bundle that Sketch can install. By default it embeds this machine's repo-local Node/CLI paths for temporary testing. For a package that falls back to pixelrosetta from PATH on the target machine, run:

npm run package:sketch-plugin -- --portable

For non-default flows, designExportProvider: "auto" keeps the same behavior: it first uses an explicit manifest when supplied; otherwise it enables sketchtool only when a safe local path is available. To make missing sketchtool a hard error, require it explicitly:

node src/cli.js preview docs/company.sketch \
  --artboard-name "首页备份" \
  --design-export-provider sketchtool \
  --sketchtool-path /Applications/Sketch.app/Contents/Resources/sketchtool/bin/sketchtool \
  --out /tmp/pixelrosetta-preview

MCP callers get the same .sketch default. They may still pass designExportProvider: "auto" or "sketchtool" and optional sketchtoolPath when they need explicit control. This remains optional: CI and normal tests do not require Sketch.app, and designExportManifest is still the portable path for externally generated native PNG assets. PixelRosetta asks sketchtool for cropped PNG exports so native images align with Page Spec geometry; replacement images are not restyled with the source node's DOM/codegen background, border, or shadow.

When the selected provider can export the whole artboard, preview and render_ui_preview also return referenceArtboardPath. This is a native PNG rendered by the design tool for the selected artboard, intended as the expected image for visual diff workflows against a browser screenshot of preview.html.

Manifest entries map page/resource layer ids to PNG files produced by a native design-tool exporter:

{
  "schemaVersion": "pixelrosetta.design-export-manifest.v1",
  "provider": "sketch-native-export",
  "assets": [
    {
      "pageLayerId": "page-product-card",
      "resourceLayerId": "resource-product-card",
      "path": "native/product-card.png",
      "scale": 1
    }
  ]
}

Relative path values are resolved from the manifest file. Matching prefers entries with both pageLayerId and resourceLayerId, then falls back to layerId or sourceLayerIds. PixelRosetta reads PNG dimensions from the file header; if the rendered size after scale does not match the target layer geometry, Page Spec diagnostics include designExport.dimensionMismatch while still preserving the native asset for review.

Agent API

v12.7 exposes a stable agent-facing helper surface through pixelrosetta/agent-api:

import {
  AGENT_API_SCHEMA_VERSION,
  evaluateBenchmarkGates,
  runAdapterConformance,
  inferPageResponsiveLayout,
  buildResponsiveCss,
  createReviewReport,
  summarizeFeedbackMemory,
  compileThemeStrategy,
  createSemanticTaggingRequest,
  createSemanticTaggingRequestFromDesign,
  validateSemanticTaggingPatch,
  applySemanticTagsToPageSpec,
  runSemanticTaggingLoop,
  validateCompositionAgentDecisionPatch
} from 'pixelrosetta/agent-api';

The module groups schema versions and JSON-serializable helpers for benchmark gates, adapter conformance, responsive layout/CSS reports, review report packaging, feedback memory lifecycle, theme-first strategy reports, semantic tagging request/validation/application helpers, optional provider-injected runSemanticTaggingLoop, and bounded composition agent decision patch validation. Semantic tagging lets an agent/model classify bounded roles such as search-field, icon, image, card, or button without mutating Sketch-owned geometry, text, source ids, colors, image paths, or asset metadata. The model loop accepts a caller-supplied { completeJson() } provider instead of hard-coding any model vendor. exportPageSpec() accepts both semanticPatch and semanticModelProvider, applying accepted tags before resource binding and native export decisions. Use semanticPatch when an agent has already produced a validated JSON patch; use semanticModelProvider when a host application wants PixelRosetta to request the patch during export. It does not change the package root export or execute target project code; artifact writers still require explicit caller-provided output paths. createSemanticTaggingRequestFromDesign() is the programmatic equivalent of semantic-request-design: it builds the bounded semantic request from the design tree before resource binding, so host agents can ask their own model whether a cluster should remain DOM/component/icon/asset before PixelRosetta chooses native PNG replacement or structured rendering. Semantic candidates include bounded visual facts such as fills, radius, shadows, asset metadata, direct child geometry, child text, and child styles. They do not include image bytes or executable project code, and any model echo that mutates these immutable facts is rejected by validation. Use maxCandidateTextFacts, maxChildFacts, and maxChildTextFacts in the semantic request options when a host needs tighter model-context budgets. runSemanticTaggingLoop() also returns a summary with candidate, returned tag, accepted tag, rejected tag, role/output-preference counts, and bounded uncoveredImportantCandidates. Host agents can use that coverage evidence to decide whether to retry semantic tagging before generating DOM/component code. maxUncoveredCandidates caps the uncovered-candidate summary size.

v13.5 adds runAgentWorkflow with schema pixelrosetta.agent-workflow.v1. It orchestrates local Vue generation and pixelrosetta.review.html creation under one caller-provided outDir. It does not run target project code, apply guarded repairs, install packages, or write outside that artifact directory. When semanticModelProvider is supplied, the workflow first runs the bounded semantic tagging loop, writes semantic-tagging-request.json, semantic-tagging-patch.json, semantic-tagging-validation.json, and page-spec.semantic.json, then sends the validated tagged Page Spec into Vue generation. The provider is caller-injected and must return JSON; PixelRosetta still validates model output before it can affect DOM/component/asset policy. The workflow report includes the same semantic coverage summary so plugin hosts can inspect whether key controls/cards/assets were tagged or need another model pass.

MCP Wrappers

import { callPixelRosettaTool, pixelRosettaTools } from 'pixelrosetta/mcp';

const result = await callPixelRosettaTool('export_page_spec', {
  designFile: 'fixtures/normalized/home.json',
  outDir: '/tmp/pixelrosetta-export'
});

For Sketch files with multiple artboards, agents should first call inspect_design_file, then pass artboardName or artboardId to export_page_spec, render_ui_preview, generate_ui_code, or convert_design_to_code. Use artboardSelection: "all-pages" when the agent needs all page artboards in one manifest. Resource/cut artboards are associated automatically with selected page artboards unless resourceArtboardSelection is set to "none". export_page_spec, render_ui_preview, generate_ui_code, convert_design_to_code, and convert_design_to_react accept designExportManifest to use externally generated native PNG layer exports. For binary .sketch files, these tools automatically try local Sketch.app native layer exports before falling back to SVG/resvg reconstruction. Agents can still pass designExportProvider: "auto" / "sketchtool" plus optional sketchtoolPath for explicit control. The same tools accept semanticPatch as an object or semanticPatchFile as a path; the patch is validated before it can affect preview/codegen/resource decisions, and semantic request, validation, patch, and tagged Page Spec artifacts are returned in the tool result when supplied.

Available tools:

• inspect_design_file
• parse_design_file
• export_page_spec
• render_ui_preview
• render_ui_screenshot
• compare_ui_preview
• analyze_ui_diff
• generate_ui_code
• create_repair_plan
• apply_html_repair_plan
• run_repair_loop
• convert_design_to_code
• convert_design_to_react
• apply_integration_plan
• evaluate_integration_quality
• create_agent_handoff
• create_guarded_repair_plan
• apply_guarded_repair
• validate_component_adapter
• create_semantic_tagging_request
• validate_semantic_tagging_patch
• apply_semantic_tagging_patch
• validate_page_spec

Large artifacts are written to disk and returned by path.

Agent MCP Server

When installed as a package, PixelRosetta exposes a stdio MCP server for local agent runtimes:

pixelrosetta-mcp

For local development against this repository, point the agent MCP command at:

node /absolute/path/to/PixelRosetta/src/mcp/server.js

The server exposes the same deterministic engine as the CLI and returns large artifacts by file path. It currently supports design inspection, AST export, Agent Page Spec export, static preview rendering, screenshot capture, visual diff analysis, source-traceable code generation, and bounded HTML repair.

render_ui_preview writes page-spec.json, diagnostics.json, structured preview.html, dom-fidelity-report.json, resource-bindings-report.json, and preview-layout-report.json. When the default .sketch native export path, designExportProvider: "auto", or "sketchtool" can export the selected artboard, it also writes reference-artboard.png and returns referenceArtboardPath. Pass includeDebugFlatPreview: true through MCP or --debug-flat-preview through the CLI to also write debug-flat-preview.html. The main preview.html is structured DOM evidence and is marked with data-preview-mode="structured"; the flat preview is debug-only and is marked with data-preview-mode="debug-flat". Preview command results also include fidelitySummary and fidelityDiagnostics, derived from dom-fidelity-report.json, so agents can see unsupported or approximate Sketch-to-DOM facts even when import/export diagnostics.json is empty. preview-layout-report.json records the exact preview containers promoted to flex-row or flex-column, including the source evidence and confidence, so agents can distinguish structured preview layout from regions that remain parent-relative absolute positioning. When the input is a supported binary .sketch archive, extractable bitmap images are written to assets/ and referenced from the preview. Hidden layer and group visibility is honored, replacement cut assets collapse vector children into image leaves with object-fit:cover and object-position:center, parent-relative geometry is preserved for nested DOM, clipping masks remain overflow-hidden containers without flattening their visible descendants, and Sketch tree paint order is preserved. When imported Sketch stack/autolayout hints are explicit, or when a freeform container has a safe non-overlapping row, column, or complete grid geometry, the structured preview marks the container with data-layout-strategy and renders its direct children as flex or grid items. Ambiguous, incomplete, or overlapping regions keep position:absolute as parent-relative design coordinates so visual evidence does not drift. Shape image fills render with background-size:cover, background-position:center, and background-repeat:no-repeat so imported texture/photo fills do not fall back to the browser's default tiling behavior.

When the optional @resvg/resvg-js package is available, vector-only resource matches may be emitted as generated PNG fallback assets under assets/generated/. This fallback is bounded: both the page node and resource node must be small, text-free, and safe for deterministic rasterization. Large containers, card backgrounds, and unsafe symbol-instance coordinates remain DOM, or unavailable resource-binding diagnostics rather than being silently replaced by generated images. Expanded symbol-instance wrappers may be rasterized only when they unwrap to a single same-size, text-free, non-symbol inner icon root whose geometry is safe. Nodes that depend on bitmap/image children, image fills, or clipping masks remain structured DOM because the vector raster provider cannot safely reproduce their raster content. Unavailable vector-only bindings include a rasterFallback decision explaining whether the provider was unavailable, the safety policy rejected the resource, the generation limit was reached, or the provider returned no bytes. Generic/default layer names such as 矩形, 路径, 形状, 编组, Vector, rectangle, group, or path are not used for cross-artboard resource matching by name. When such nodes are safe page-local vector/shape groups and the provider is available, they are sliced from the page node itself into generated PNG image leaves; otherwise they remain DOM/CSS/SVG fallback output. Direct page/resource vector primitive matches are rasterized to generated PNG image assets when the provider is available rather than being redrawn as public SVG output. Standalone page path-vector nodes are also deduplicated during rasterization: once a safe parent vector group is replaced by an image asset, its descendant paths are not generated as duplicate cut assets. During this internal SVG-to-PNG pass, supported Sketch Gaussian blur effects, outer shadows, and inner shadows are translated into SVG filters before rasterization so generated image slices preserve blurred glows and shadowed cards without exposing SVG in the public preview; parent group opacity is preserved in the same internal raster input. Page groups that already contain live text or other renderable descendants are recorded as render-structured bindings, so agents know the DOM subtree is the intended fallback instead of a missing cut image. Empty transparent resource matches are recorded as ignore-empty. Text layers and vector-only exact-name matches with mismatched geometry are ignored as resource bindings instead of being reported as missing cut assets.

For icon mapping, component-library icons are only appropriate when an adapter selects them with high confidence. Low-confidence icon bindings carry an assetFallback.required marker so downstream agents preserve the design source rendering or asset instead of substituting a visibly different library icon.

render_ui_screenshot and the screenshot CLI command render an existing preview.html into preview.png using a deterministic viewport. Screenshot capture requires local Playwright/browser support; unsupported environments return structured diagnostics instead of silently guessing.

compare_ui_preview, diff, and analyze-diff compare two PNG screenshots and write a machine-readable report plus diff.png. v3 adds clustered analysis so agents can distinguish no-op, localized, and global visual drift before planning repairs.

generate_ui_code and the generate CLI command create source-traceable code artifacts from Agent Page Spec. Targets currently include html, react, and vue. All targets preserve source ids for generated nodes. Absolute-profile HTML, React, and Vue output preserves the Page Spec layoutTree as nested DOM and uses parent-relative absolute CSS coordinates, matching the structured preview boundary instead of flattening every layer under the page root. Code generation consumes Page Spec output; it does not read Sketch internals directly.

convert_design_to_code and the convert CLI command provide a one-shot agent handoff: they export page-spec.json, diagnostics.json, and target code artifacts in a single call. convert_design_to_react remains available for backward compatibility. React conversion supports --react-profile absolute|component; Vue conversion supports --vue-profile absolute|component and --component-binding-config.

create_repair_plan converts clustered diff reports and Page Spec geometry into repair suggestions with sourceLayerIds, patch type, confidence, and diagnostics. apply_html_repair_plan applies only bounded, source-matched CSS repairs to generated HTML/CSS artifacts.

v3 Pixel Repair Workflow

export/preview -> screenshot -> diff/analyze -> repair-plan -> apply repair -> regenerate/verify

The workflow is deterministic at each artifact boundary:

• export or render_ui_preview creates Page Spec and preview artifacts.
• screenshot or render_ui_screenshot captures visual evidence when a local Playwright-compatible browser is available.
• diff or analyze-diff writes diff.png, changed pixel counts, and clustered visual drift analysis.
• repair-plan or create_repair_plan maps localized drift back to Page Spec source ids and emits suggestions only.
• repair-html or apply_html_repair_plan applies a configured maximum number of supported CSS patches to generated HTML/CSS.
• generate --target react emits a React MVP (App.jsx, styles.css, and generation-report.json) for agent handoff.

v4 Production Repair Loop

The v4 loop is bounded and evidence-driven:

generated HTML -> screenshot -> diff/analyze -> repair-plan -> apply repair -> repeat until valid or bounded

Use:

node src/cli.js repair-loop /tmp/generated /tmp/page-spec.json /tmp/reference.png --out /tmp/loop --max-iterations 3 --threshold 0.01

Agents can call the same flow through run_repair_loop.

React Fidelity Profiles

generate --target react supports:

• absolute: flat source-traceable React markup plus CSS.
• component: source-traceable component functions for agent handoff.

Use:

node src/cli.js convert path/to/file.sketch --target react --react-profile component --out /tmp/react

Agents can call convert_design_to_react for the same one-shot flow.

v5 Vue Component Binding

Vue generation emits App.vue, generation-report.json, and, in component profile, theme-delta-report.json and component-bindings-report.json.

The Component Binding Protocol v1 registers multiple libraries instead of a single global component library. Each source node can independently bind to project-local components, Ant Design Vue, Vant, or DOM fallback. Decisions are auditable through candidates, confidence, reasons, selected component, and fallback status.

Theme resolution order is project theme first, adapter official defaults second, then design-token delta analysis. Theme-capable deltas are reported as theme changes before any shared style override is considered. Deep selectors are not emitted by default.

Example component binding config:

{
  "componentLibraries": [
    { "id": "ant-design-vue", "priority": 80 },
    { "id": "vant", "priority": 60 }
  ],
  "threshold": 0.82
}

Agents can call convert_design_to_code with target: "vue" and vueProfile: "component" for the same one-shot flow.

v5.1 Project-Aware Binding

Vue component generation can inspect an existing Vue project without mutating it:

node src/cli.js convert path/to/file.sketch --target vue --vue-profile component --project-root /path/to/vue-project --out /tmp/pixelrosetta-vue

When projectRoot is provided, PixelRosetta writes project-context-report.json, project-component-adapter.json, theme-patch-plan.json, and shared-overrides-plan.json in addition to the v5 Vue reports. These are read-only analysis and patch suggestions; PixelRosetta does not apply them to the project.

v6 Project Integration Pack

Vue component generation can produce a dry-run Project Integration Pack for review:

node src/cli.js convert path/to/file.sketch \
  --target vue \
  --vue-profile component \
  --project-root /path/to/vue-project \
  --integration-pack \
  --out /tmp/pixelrosetta-vue

This writes review artifacts under outDir, including:

• pixelrosetta.integration-plan.json
• component-map.generated.json
• adapter-lock.generated.json
• integration-validation-report.json
• usage-notes.md
• patches/shared-overrides.generated.css

Conversion stays non-mutating. It produces review artifacts and does not modify the target project, install dependencies, or execute target project code.

Guarded apply is explicit and requires accepted action ids:

node src/cli.js apply-plan /tmp/pixelrosetta-vue/pixelrosetta.integration-plan.json \
  --project-root /path/to/vue-project \
  --accept action.styles.shared-overrides

apply-plan validates the plan, enforces path-safe writes under projectRoot, and only applies supported write-file actions whose ids were explicitly accepted with --accept.

Agents can call apply_integration_plan with planFile, projectRoot, and acceptedActionIds for the same guarded flow. Dry-run generation and guarded apply never installs dependencies or executes target project code.

v7 Quality Gate

v7 evaluates a reviewed Vue Project Integration Pack and writes a quality report plus an advisory repair plan:

node src/cli.js quality-check /tmp/pixelrosetta-vue/pixelrosetta.integration-plan.json \
  --project-root /path/to/vue-project \
  --out /tmp/pixelrosetta-quality

The command writes pixelrosetta.quality-report.json and pixelrosetta.quality-repair-plan.json. The report scores visual, component-mapping, and project-integration quality. Browserless environments still produce a report with visual.degraded: true.

Agents can call evaluate_integration_quality with planFile, projectRoot, and outDir for the same read-only flow. v7 never installs dependencies, executes target project code, or writes to the target project. Repair plan suggestions are advisory only and no repair apply command is exposed in v7.

v8 Agent Readiness Pack

v8 creates a single agent-facing handoff bundle from v6 integration-pack artifacts, v7 quality artifacts, optional visual evidence, and optional adapter validation reports:

node src/cli.js handoff /tmp/pixelrosetta-vue/pixelrosetta.integration-plan.json \
  --project-root /path/to/vue-project \
  --quality-report /tmp/pixelrosetta-quality/pixelrosetta.quality-report.json \
  --quality-repair-plan /tmp/pixelrosetta-quality/pixelrosetta.quality-repair-plan.json \
  --out /tmp/pixelrosetta-handoff

The command writes pixelrosetta.agent-handoff.json and, when visual inputs are missing, an honest degraded pixelrosetta.visual-evidence.json. The handoff is the first artifact downstream agents should read.

Adapter authors can validate declarative Vue component-library adapters:

node src/cli.js validate-adapter path/to/adapter.json --fixtures path/to/fixtures --out /tmp/pixelrosetta-adapter-validation

v8 remains read-only with respect to target projects. It does not install dependencies, run Vite, execute Vue or adapter code, or apply quality repair suggestions.

v9.1 Guarded Repair Loop

v9.1 turns a v8 handoff and v7 quality repair plan into an explicitly reviewable guarded repair plan:

node src/cli.js guarded-repair-plan /tmp/pixelrosetta-handoff/pixelrosetta.agent-handoff.json \
  --quality-repair-plan /tmp/pixelrosetta-quality/pixelrosetta.quality-repair-plan.json \
  --project-root /path/to/vue-project \
  --out /tmp/pixelrosetta-v9-repair

Apply remains guarded and requires accepted repair ids:

node src/cli.js apply-guarded-repair /tmp/pixelrosetta-v9-repair/pixelrosetta.guarded-repair-plan.json \
  --project-root /path/to/vue-project \
  --accept repair.shared-override-adjustment.1 \
  --dry-run \
  --out /tmp/pixelrosetta-v9-apply

v9.1 supports only low-risk CSS patch writes to PixelRosetta-managed patch files such as src/styles/pixelrosetta-overrides.css. It does not run Vite, install dependencies, edit business components, or edit style entry files.

v9.2 Component Map Repair

v9.2 extends the guarded repair plan with low-risk component-remap and slot-remap suggestions. These are converted into component-map-update actions and review artifacts:

• patches/component-map.repair-patch.json
• component-map.repaired.json

Create a v9.2 plan by passing the integration-pack component map and adapter lock:

node src/cli.js guarded-repair-plan /tmp/pixelrosetta-handoff/pixelrosetta.agent-handoff.json \
  --quality-repair-plan /tmp/pixelrosetta-quality/pixelrosetta.quality-repair-plan.json \
  --project-root /path/to/vue-project \
  --component-map /tmp/pixelrosetta-vue/component-map.generated.json \
  --adapter-lock /tmp/pixelrosetta-vue/adapter-lock.generated.json \
  --out /tmp/pixelrosetta-v9-repair

Accepted component-map repairs dry-run or write only component-map.generated.json inside the PixelRosetta integration pack:

node src/cli.js apply-guarded-repair /tmp/pixelrosetta-v9-repair/pixelrosetta.guarded-repair-plan.json \
  --project-root /path/to/vue-project \
  --integration-pack-dir /tmp/pixelrosetta-vue \
  --accept repair.component-map.component-remap.1 \
  --dry-run \
  --out /tmp/pixelrosetta-v9-apply

v9.2 never edits Vue SFCs, project imports, package files, or theme configuration. Project integration repairs remain v9.3 scope.

v9.3 Project Integration Repair

v9.3 extends guarded repair to explicitly accepted project integration wiring. It converts low-risk style-entry-import, library-style-import, and theme-token-adjustment suggestions into:

• style-entry-import
• library-style-import
• theme-css-write

Create a v9.3 plan by passing the integration plan, read-only project context, and theme delta evidence from the Vue integration pack:

node src/cli.js guarded-repair-plan /tmp/pixelrosetta-handoff/pixelrosetta.agent-handoff.json \
  --quality-repair-plan /tmp/pixelrosetta-quality/pixelrosetta.quality-repair-plan.json \
  --project-root /path/to/vue-project \
  --integration-plan /tmp/pixelrosetta-vue/pixelrosetta.integration-plan.json \
  --project-context /tmp/pixelrosetta-vue/project-context-report.json \
  --theme-delta-report /tmp/pixelrosetta-vue/theme-delta-report.json \
  --out /tmp/pixelrosetta-v9-repair

Accepted project integration repairs dry-run or write only allowlisted wiring files and PixelRosetta-managed CSS:

node src/cli.js apply-guarded-repair /tmp/pixelrosetta-v9-repair/pixelrosetta.guarded-repair-plan.json \
  --project-root /path/to/vue-project \
  --accept repair.project-integration.style-entry-import.1 \
  --accept repair.project-integration.theme-token-adjustment.2 \
  --dry-run \
  --out /tmp/pixelrosetta-v9-apply

Theme evidence takes priority over shared override wiring. v9.3 may add allowlisted side-effect imports in src/main.ts, src/main.js, src/main.tsx, or src/main.jsx; it may write src/styles/pixelrosetta-theme.css for theme CSS variables. It never installs packages, runs the target project, edits business Vue components, or writes package, lock, route, store, Vite config, or generated SFC files.

v10.0 High-Fidelity Evaluation

v10.0 adds a read-only highFidelity quality dimension to the existing quality gate. It maps visual evidence clusters back to source-traceable Page Spec regions and component-map evidence so agents can understand which component or layout region most likely caused drift.

The dimension is advisory: it improves diagnostics and repair-plan evidence, but does not expand guarded project writes. It does not run the target project, install dependencies, edit business Vue components, or change package/build files.

v10.1 Component Mapping Intelligence

v10.1 makes Vue component-library selection more explainable. Binding reports and component-map entries include ranking evidence such as scoreBreakdown, candidate reasons, prop keys, slot capabilities, and style policy metadata.

This improves multi-library mapping for Ant Design Vue, Vant, and project-local components without expanding guarded repair writes or executing target project code.

v10.2 Theme Style Strategy Resolver

v10.2 adds a theme-first style strategy report for Vue component generation. style-strategy-report.json explains whether each visual delta is handled by a theme token, CSS variable, shared override, or manual review.

The resolver prefers project theme evidence, then adapter defaults, then shared overrides. It reduces per-component wrapper styles when a theme token or CSS variable can solve the same visual difference, and it keeps unsupported internal styling in review-only diagnostics. It does not add new target-project write classes, install packages, or run target project code.

v10.3 Sketch Layout Hints

v10.3 preserves optional Sketch layout facts in parser and Page Spec artifacts. Binary .sketch imports can now include layoutHints for resizing constraints and simple stack layout metadata. Unsupported Sketch layout objects produce explicit diagnostics instead of silent confidence.

v15 classifies Sketch MSImmutableFreeformGroupLayout as layoutHints.layoutMode: "freeform" instead of an unsupported-layout warning. This reduces false-positive diagnostics on designer-authored files that use Sketch's default freeform grouping metadata.

This is parser/export-only source fidelity work. It does not apply project changes, install packages, or run target project code.

v10.4 Agent Workflow Packaging

v10.4 adds a concise workflowSummary to pixelrosetta.agent-handoff.json. It summarizes artifact readiness, diagnostic counts, degraded visual evidence, multi-library adapter guidance, and safe next-step hints for MCP tools and CLI subcommands. The hints are structured metadata, not shell commands, so agents still need explicit review and accepted ids before guarded apply.

Mixed-library Vue example:

{
  "componentLibraries": [
    { "id": "ant-design-vue", "priority": 90 },
    { "id": "vant", "priority": 70 }
  ],
  "threshold": 0.82
}

Adapter authors should validate new adapters with validate_component_adapter or node src/cli.js validate-adapter <adapter.json> --out <dir>. Adapter data must use componentLibraries metadata and should document props, slots, variants, and style policy. Singular componentLibrary is rejected.

v11.0 Benchmark Corpus

v11.0 adds a local benchmark corpus runner for repeatable quality checks over checked-in design fixtures. The corpus manifest lives at fixtures/evaluation/v11-corpus.json; the runner exports Page Spec artifacts under a caller-provided outDir and writes pixelrosetta.benchmark-report.json with deterministic pass/degraded/fail counts.

v12.0 adds report-level benchmark gates. A corpus manifest can declare:

{
  "thresholds": {
    "minAverageScore": 0.95,
    "maxFailCount": 0,
    "maxDiagnosticCount": 0
  }
}

The generated benchmark report includes gateStatus.status, gateStatus.passed, the normalized thresholds, and blocking benchmark.gate.* diagnostics when the summary misses a threshold. Manifests without thresholds keep permissive v11 behavior.

Run the local smoke check with:

pnpm exec node scripts/smoke-corpus.mjs

The corpus runner is local-only. It does not fetch external Sketch files, install dependencies, run Vite, execute target project code, or write outside the provided benchmark output directory.

v13.0 adds a local Vue project compatibility matrix through runVueProjectCompatibilityMatrix. Agents can pass checked-in or temporary Vue project fixtures for Ant Design Vue, Vant, and mixed-library projects. The runner calls existing Vue generation with project-aware integration-pack options, writes each case under the matrix outDir, and emits pixelrosetta.project-compatibility.v1 without running target project scripts or mutating project files.

v11.1 Adapter SDK v3 Registry

v11.1 adds a JSON-only Adapter SDK v3 registry layer for Vue component-library onboarding. v3 keeps v2 component normalization and adds a registry with plural componentLibraries, component capability matrix, slot contracts, theme surfaces, style policies, and compatibility diagnostics.

Adapter SDK v3 can describe Ant Design Vue, Vant, Element Plus, Naive UI, or internal libraries without hard-coding one selected library. Adapter payloads remain declarative JSON; executable fields such as transform, render, setup, matcher, handler, and factory are rejected, and deep selector style policies remain blocked.

v12.2 adds a pure adapter conformance suite for SDK v3 registries. Agents can run runAdapterConformance({ adapters, requiredRoles, requiredSlots }) to validate built-in or project adapters without importing component libraries. The report schema is pixelrosetta.adapter-conformance.v1 and summarizes adapter validity, role coverage, slot contract coverage, theme surface counts, and unsafe style-policy diagnostics.

v13.2 adds createAdapterAuthoringKit with schema pixelrosetta.adapter-authoring-kit.v1. It generates a JSON-only SDK v3 adapter template, starter fixtures, required role and slot checklists, and a conformance command hint for third-party Vue component libraries. Generated templates use plural componentLibraries and contain no executable adapter fields.

v12.3 adds slot-aware Vue composition for component bindings. Card-like layout nodes can infer conservative header/actions/body regions from child geometry, map those regions only to slots declared by the adapter, record slotAssignments in the binding report, and render safe Vue named slots such as <template #title> and <template #extra> in generated SFC output.

v15 also tightens Vue component-profile semantic filtering before component binding. Hidden subtrees, empty non-visual wrappers, and decorative shape/vector leaves are omitted from component-bindings-report.json decisions while the source-traceable layout tree and generated DOM remain available for rendering. Decorative shape/vector leaves are likewise kept in the Page Spec but no longer produce actionable mapping.unmapped diagnostics.

v13.3 adds createCompositionPlan and writes composition-plan-report.json during component-profile Vue generation. The report uses schema pixelrosetta.composition-plan.v1 and summarizes selected components, props, attrs, named slots, fallback entries, candidate counts, and reasons without changing generated Vue output.

v14.1 makes composition planning consume the same structured layoutTree used by preview.html. createCompositionPlan(pageSpec, options) marks source: "layoutTree", keeps plural componentLibraries, ignores singular componentLibrary with a diagnostic, preserves replacement assets as design-asset leaves, and assigns conservative header, default, footer, and icon slots from structured child names and vertical order. Debug flat preview artifacts are never accepted as a component composition source. The report also includes agentGuidance and agentReviewItems so coding agents can apply a rules-first workflow: PixelRosetta owns deterministic Sketch import, geometry, style, resource binding, and asset preservation; the agent reviews low-confidence container roles, component candidates, and slot fit without flattening the DOM or dropping source traceability. agentGuidance.decisionBoundary lists immutable rule-owned facts and reviewable agent decisions. Each agentReviewItems[] entry includes immutableFacts covering geometry, styles, text content, asset bindings, source layer ids, visibility, paint order, and child order, plus reviewableDecisions for bounded role, component, slot, and theme-strategy review. Agents must not mutate immutableFacts when choosing components or slots. The same report now includes agentDecisionContract with schema pixelrosetta.composition-agent-decision.v1. Agents may return only a structured-decision-patch for bounded actions such as confirming a rule decision, overriding a role, selecting a component, remapping slots, or keeping a DOM fallback. They must provide evidence references and must not write DOM, HTML, Vue code, target-project files, sourceLayerIds, or immutableFacts; PixelRosetta's rule compiler remains the only authority that validates the patch and generates final DOM/Vue output. Agents and hosts can call validateCompositionAgentDecisionPatch(plan, patch) before accepting a model-proposed semantic patch. The validator returns block diagnostics for invalid schemas, unsupported actions, missing or stale evidence paths, unknown slot sourceLayerIds, direct DOM/Vue source text, or attempts to write rule-owned fields.

v12.4 adds a theme-first compiler report for project-aware Vue generation. theme-compiler-report.json uses schema pixelrosetta.theme-compiler.v1 and orders styling decisions as project-theme, official-theme, shared-override, then component-local-fallback. This makes the intended priority explicit for agents: use detected project theme first, fall back to library defaults when no project theme exists, and only then consider shared or local style overrides.

v13.1 adds createThemeGuardedRepairPlan, which converts safe theme compiler CSS custom property entries into theme-token-adjustment suggestions inside a pixelrosetta.quality-repair-plan.v1 artifact. Actual project writes still go through the existing guarded repair plan and accepted-id apply flow.

v11.2 Responsive Layout Inference

v11.2 adds a read-only responsive layout analyzer for Page Spec geometry and Sketch layoutHints. Vue generation now embeds generation-report.json.responsiveLayout with a deterministic pixelrosetta.responsive-layout.v1 report tree.

The analyzer prefers Sketch stack hints, then safe non-overlapping horizontal, vertical, or complete grid geometry, then pinned constraints. Strategies include flex-row, flex-column, grid, constrained-absolute, absolute, and leaf; ambiguous, incomplete, or overlapping layouts degrade to absolute with diagnostics. This report is advisory only: it does not write to target projects, install packages, run Vite, or change the guarded repair write scope.

v12.1 can opt into generated responsive Vue CSS by passing responsiveCss: true to generateVueUi. The generated SFC then appends scoped CSS blocks for safe flex-row, flex-column, grid, and constrained-absolute strategies while preserving absolute positioning for ambiguous nodes. The generation report includes responsiveCss.enabled, responsiveCss.blockCount, and responsive.css.* diagnostics so agents can review fallback risk.

v13.4 adds inferBreakpointResponsiveLayout and an opt-in responsiveBreakpoints: true Vue generation option. The report uses schema pixelrosetta.responsive-breakpoints.v1 and summarizes mobile, tablet, and desktop responsive risk without changing generated CSS.

v11.3 Human Review Report

v11.3 adds a deterministic local HTML review artifact, pixelrosetta.review.html, generated from existing handoff, quality, component-map, and responsive layout JSON artifacts. The report is intended for humans to scan quality status, component-library choices, responsive strategy, and safe next-step ids.

JSON artifacts remain canonical for agents and automation. The HTML report is static, escapes artifact-provided text, contains no executable project commands, and writes only under the caller-provided outDir.

v12.6 upgrades the report with local filtering rows and optional theme compiler and feedback memory summaries. createReviewReport accepts themeCompilerFile and feedbackMemoryFile, embeds escaped local review data, and renders section/severity filters without external scripts, styles, fonts, network resources, or target-project commands.

v13.6 adds reviewActionsToFeedbackMemory for explicit local review decisions. The input action payload is identified by pixelrosetta.review-actions.v1, and the output is project-scoped pixelrosetta.feedback-memory.v1. PixelRosetta does not infer approval from viewing a report; only explicit accepted, approved, rejected, or pending action objects are converted.

v11.4 Feedback Memory Loop

v11.4 defines pixelrosetta.feedback-memory.v1 for project-scoped feedback records. Each project entry is keyed by projectFingerprint, and records can capture approved or rejected component mappings, slot choices, theme feedback, and style feedback.

Vue component generation accepts feedbackMemoryFile alongside the existing bindingMemoryFile path when integrationPack and projectRoot are enabled. Approved component-mapping feedback for the current projectFingerprint is converted into existing component-map binding memory, so future runs can reuse confirmed choices. Feedback from another fingerprint is ignored. Rejected records produce diagnostics but are not auto-applied as repairs.

Feedback memory writes only to explicit artifact paths chosen by the caller and does not modify target projects, install packages, or run target project code.

v12.5 adds lifecycle helpers for feedback artifacts: summarizeFeedbackMemory, pruneFeedbackMemory, and mergeFeedbackMemories. These helpers count approved/rejected/pending/stale records, detect conflicting approved component mappings, prune mismatched or stale records, and merge latest records deterministically. They remain project-scoped and do not change the rule that only matching projectFingerprint feedback can influence component binding.

Golden Updates

Run:

pnpm run golden:update

This command updates only fixtures with referenceScreenshot in the evaluation manifest. If no Playwright-compatible browser is available, it writes explicit diagnostics such as visual.browserUnavailable and does not create fake PNG baselines.

Agent Smoke Test

Run the local MCP smoke test after installation or local changes:

pnpm run smoke:agent

The smoke starts pixelrosetta-mcp, calls tools/list, render_ui_preview, render_ui_screenshot, compare_ui_preview, generate_ui_code, Vue integration-pack, quality, handoff, and guarded repair tools, then writes a concise JSON report with integrationPack, qualityGate, agentHandoff, and guardedRepair. Browserless environments are valid when they return visual.playwrightMissing or visual.browserUnavailable diagnostics.

For the optional local real-Sketch fixture, run:

pnpm run smoke:real-sketch

This reads docs/公司app.sketch when it exists locally and writes artifacts under /tmp/pixelrosetta-real-sketch-smoke-*: page-spec.json, diagnostics.json, structured preview.html, debug-only debug-flat-preview.html, dom-fidelity-report.json, and resource-bindings-report.json. It also writes composition-plan-report.json and fails if the plan omits the rules-first/agent-review decision boundary, agentDecisionContract, immutableFacts, or reviewableDecisions; it also requires non-empty design-asset, slot, text, child-order, asset-binding, and slot-candidate coverage in the generated composition plan. The smoke also runs Vue component-profile generation from the same Page Spec and fails if App.vue, generation-report.json, or component-bindings-report.json is missing, if Vue generation reports diagnostics, or if replacement design assets are not preserved as image leaves. When the fixture contains the high-signal 首页备份 artboard, the smoke targets it explicitly and fails on unsupported or approximate fidelity diagnostics, or on unavailable resource bindings. If the file is absent, the command prints a SKIP message. The fixture remains untracked unless a human explicitly decides to commit it.

Codex Plugin Packaging

PixelRosetta can be installed as a Codex-style plugin source repository, similar to Superpowers. The plugin manifest lives at .codex-plugin/plugin.json, the plugin MCP server manifest lives at .mcp.json, and the agent-facing workflow skill lives at skills/pixelrosetta/SKILL.md.

The plugin uses the existing PixelRosetta MCP server as its tool surface:

{
  "mcpServers": {
    "pixelrosetta": {
      "cwd": ".",
      "command": "node",
      "args": ["./src/mcp/server.js"]
    }
  }
}

This means PixelRosetta is distributed and updated as a plugin, while MCP stays an internal/cross-agent runtime interface rather than the product boundary.

For local Codex testing, add the repo-local marketplace and install the plugin:

codex plugin marketplace add /absolute/path/to/PixelRosetta
codex plugin add pixelrosetta@pixelrosetta-dev

Start a fresh Codex thread after reinstalling so plugin skills and MCP tools are loaded from the updated plugin cache.

Multi-Agent Plugin Packaging

PixelRosetta also ships lightweight plugin metadata for other agent hosts:

• Claude plugin metadata: .claude-plugin/plugin.json
• Claude development marketplace: .claude-plugin/marketplace.json
• Kimi plugin metadata and tool guidance: .kimi-plugin/plugin.json
• Cursor plugin metadata: .cursor-plugin/plugin.json
• OpenCode plugin entry: .opencode/plugins/pixelrosetta.js
• OpenCode install notes: .opencode/INSTALL.md
• Gemini extension metadata: gemini-extension.json
• Gemini context file: GEMINI.md
• Aurade plugin metadata: .aurade-plugin/plugin.json
• Aurade plugin manifest: plugin.json
• Aurade MCP wrapper: bin/pixelrosetta-mcp

These host files do not fork the conversion engine. They route agents toward the same PixelRosetta skill, CLI, and MCP runtime. Hosts with MCP support should use the MCP server. Hosts without direct MCP loading should use the plugin skill and local CLI.

Aurade can install this repository as a local plugin. The repository keeps a root plugin.json for compatibility and also ships .aurade-plugin/plugin.json for Aurade's metadata-directory loader. Both declare mcp_servers.pixelrosetta and the bin/pixelrosetta-mcp wrapper so Aurade can start PixelRosetta from its installed plugin directory. Aurade's Node plugin runtime normalizes plugin MCP cwd relative to the plugin root and prepends plugin bin paths before starting stdio MCP commands.

Example Aurade install command:

aurade plugins install /absolute/path/to/PixelRosetta --yes
aurade plugins list

When testing directly from the Aurade source checkout, use the Node CLI entry:

pnpm exec tsx src-node/cli/main.ts plugins install /absolute/path/to/PixelRosetta --yes
pnpm exec tsx src-node/cli/main.ts plugins list

--yes is required for unattended local testing because PixelRosetta declares an MCP server, which Aurade treats as a high-risk plugin permission. Manual copying to ~/.aurade/plugins/pixelrosetta remains a fallback for older Aurade builds, but the CLI install path should be preferred on current Aurade.

Example Codex MCP configuration:

[mcp_servers.pixelrosetta]
command = "node"
args = ["/absolute/path/to/PixelRosetta/src/mcp/server.js"]

Example Claude Desktop MCP configuration:

{
  "mcpServers": {
    "pixelrosetta": {
      "command": "node",
      "args": ["/absolute/path/to/PixelRosetta/src/mcp/server.js"]
    }
  }
}

v2 Runtime Boundaries

• Agents can call PixelRosetta through the stdio MCP server.
• Static previews are inspectable and can be rendered to screenshots when the local browser environment supports Playwright.
• Screenshot diff reports changed pixels and writes diff.png; it does not yet repair implementation code automatically.
• HTML/CSS generation is an MVP intended for traceable agent handoff, not a complete production app generator.
• Unsupported design features and unavailable browser dependencies are surfaced through diagnostics rather than silent fallbacks.

v3 Runtime Boundaries

• Repair suggestions are bounded and source-traceable; unsupported diff cases emit diagnostics.
• apply_html_repair_plan only patches generated CSS blocks with matching source-derived selectors and a caller-provided maxPatches limit.
• React generation is an MVP static component target, not a full application framework integration.
• Browser screenshots require local Playwright/browser support. When unavailable, the runtime returns diagnostics instead of claiming pixel verification.

v8 Runtime Boundaries

• Agents should start from pixelrosetta.agent-handoff.json when it exists.
• Visual evidence may be available, partial, degraded, or invalid; degraded evidence is explicit and never represented as a fake screenshot.
• Adapter validation is declarative and read-only; adapter files are parsed as data, not executed as code.
• Handoff nextActions are recommendations and not commands.

Normalized Fixture Format

A normalized design fixture contains source metadata, page/canvas information, and a rooted layer tree. Each layer preserves its source id, geometry, type, styles, optional text, optional asset reference, and children.

See fixtures/normalized/home.json for the current contract fixture.

Testing

pnpm test
pnpm run test:visual
pnpm run test:evaluation
pnpm run smoke:agent
pnpm run golden:update

The test suite uses Node's built-in test runner and has no runtime dependency installation requirement.

Evaluation fixtures live under fixtures/evaluation/. The current harness uses manifest-driven synthetic .sketch archives to verify inspect -> export -> preview -> validate across typography, image/mask, symbols, vector paths, and effects categories. Reference screenshot goldens can be added once the visual diff workflow has durable browser screenshots in the target environment. Golden visual tests live in tests/golden-visual.test.js; until reference screenshots are committed, they assert an explicit golden.noReferenceScreenshots diagnostic path.