HtmlCompilation has grown past the point where the transform can be reasoned about

Start by reading the #1942 contract, then trace the entry points and transform orchestration in HtmlCompilation.php and NavigationPattern.php. The decomposition is done when both entry points visibly share one transform path, the stylesheet stages are named, and the existing navigation tests still pass.

Observation

HtmlCompilation.php        10,629 lines
ArtifactCompiler.php        4,522
StyleResolver.php           3,199
NavigationPattern.php       2,399
AuthorStylesheetProjector   1,606
NavigationStyleProjector    1,553

Filing this against the concrete cost rather than the line count.

The concrete cost

HtmlCompilation is where the compiler drives the transform, and it is exactly where #1942 lives: the same document produces different blocks depending on which entry point ran, and reading the file does not reveal why. I could not answer that question from source and had to bisect by re-importing.

NavigationPattern emits core/navigation from three sites. Patching two of them and verifying through one entry point produced a merged change that does nothing in production (#1939). With 2,399 lines and 20 dedicated navigation tests, I could not predict blast radius, so "verified" degraded to "CI did not complain".

That is the real symptom: at this size, changes are validated by the test suite rather than understood by the author. It works until the suite has a hole in it, which is what #1942 is.

Suggested direction

Not a rewrite. The useful cut is wherever it makes the entry-point question answerable:

• separate the transform pipeline from the orchestration that drives it, so both entry points visibly share one path
• move the stylesheet materialisation sequence out into something that names its stages

The CSS path alone currently runs author-css → projected → editor-static-state → engine-support(before/after) → wordpress-compat, with roughly fifteen generated marker-class families. That sequence is not declared anywhere — I reconstructed it by grepping call sites.

Dependency

#1942 is the test that makes this safe to do. I would not attempt this decomposition before that contract exists.

AI assistance

Grok 4.6 via OpenCode. Written after diagnosing four defects in this codebase in one session, three of which required runtime bisection rather than source reading.