Automattic / Automattic/blocks-engine
Simplify figma-transformer architecture without changing output contracts
- Dominant language
- PHP
- Stars
- 14
- Forks
- 2
- Avg merge
- 2h 10m
- Merged PRs (30d)
- 561
Description
## Problem
A review of `figma-transformer` found several places where equivalent behavior is implemented through parallel pipelines or callback-heavy abstractions, increasing maintenance cost and divergence risk. The current contract suite passes, so this work should preserve emitted HTML/CSS/assets, diagnostics, result envelopes, and public APIs.
## Findings
- Multi-page compilation is implemented both in `FigmaTransformer::transformScenegraphPages()` and `StaticHtmlEmitter::emitSite()`.
- `StaticHtmlEmitter::emit()` and `emitSite()` duplicate initialization, emission finalization, asset handling, font handling, and diagnostics.
- Normal, responsive, and normalized-page transforms duplicate result-envelope finalization.
- Extracted HTML resolver classes remain coupled to the 10k-line emitter through callback injection and mutable emitter state.
- Layout and stacking analysis is repeatedly recomputed rather than represented once per node.
- Glyph diagnostic compaction has a dead duplicate implementation.
- The contract runner remains an 8.5k-line monolith despite domain contract modules.
## Delivery sequence
### Parallel first wave
- Unify single-page and site emission behind one internal lifecycle.
- Consolidate transform-result finalization.
- Remove dead duplicate diagnostic compaction.
### Sequenced follow-ups
- Route multi-page transformation through one site compiler after emitter unification lands.
- Replace callback-heavy emitter wiring with a per-transform session and one node render plan.
- Move remaining inline contract scenarios into domain contract modules.
## Acceptance criteria
- Existing `composer test` remains green after every step.
- Public result schemas and plugin helper APIs remain unchanged.
- Generated HTML, CSS, assets, diagnostics, metrics, responsive behavior, and source reports remain contract-compatible.
- Each change removes a parallel path or redundant abstraction rather than adding a compatibility layer.
## AI assistance
OpenAI `gpt-5.6-sol` via OpenCode performed the architecture review and drafted this tracking issue. Chris Huber is responsible for the scope and final changes.
Contributor guide
Research direction
Start by reading FigmaTransformer::transformScenegraphPages(), StaticHtmlEmitter::emit(), and StaticHtmlEmitter::emitSite(), then run composer test to establish the current contract baseline. Follow one delivery item at a time, beginning with the shared emission lifecycle, result finalization, or dead diagnostic compaction. Done means composer test stays green and emitted outputs, diagnostics, schemas, APIs, and metrics remain contract-compatible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- figma, php
- Domain
- testing, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100