Simplify figma-transformer architecture without changing output contracts

[chubes4]

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.

[chubes4]

First-wave implementation trackers:

• Unify StaticHtmlEmitter single-page and site emission lifecycles #1077 unifies the emitter lifecycle.
• Consolidate FigmaTransformer result finalization #1078 consolidates transformer result finalization.
• Remove duplicate scenegraph glyph diagnostic compaction #1079 removes duplicate diagnostic compaction.

These scopes are independent and can run concurrently. The multi-page compiler collapse and emitter-session redesign remain sequenced behind #1077 to avoid overlapping architecture changes.

AI assistance: OpenAI gpt-5.6-sol via OpenCode structured the dependency order and drafted this update. Chris Huber is responsible for the plan.