Automattic / Automattic/blocks-engine

Simplify figma-transformer architecture without changing output contracts

Open
#1,076 1 comment 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.