Automattic / Automattic/data-liberation-agent
Reconcile responsive captures into one authoring tree
- Dominant language
- TypeScript
- Stars
- 31
- Forks
- 3
- Avg merge
- 10h 14m
- Merged PRs (30d)
- 81
Description
## Problem
When desktop and mobile body signatures differ at all, `assembleResponsiveHtml()` concatenates both complete bodies into `.data-liberation-desktop-document` and `.data-liberation-mobile-document`. This preserves portable rendering, but it also makes downstream semantic reconstruction consume two full page trees.
A seven-route responsive capture demonstrates the cost:
| Route | Desktop structural tokens | Mobile structural tokens | Shared LCS | Compiled blocks | Groups | Layout shells |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| home | 2,334 | 2,150 | 87.6% | 986 | 511 | 169 |
| contact | 948 | 948 | 90.0% | 400 | 206 | 64 |
| gallery | 490 | 490 | 83.1% | 188 | 103 | 25 |
| bio | 1,214 | 1,218 | 88.4% | 181 | 98 | 20 |
The transformer is already coalescing wrapper chains. The dominant remaining multiplier exists in the artifact before transformation: two mostly shared responsive documents become two editable block subtrees. This is the concrete capture-side instance of Automattic/blocks-engine#868.
## Architecture direction
Represent responsive captures as one shared semantic tree with bounded variant islands:
- Match stable source identities and structurally equivalent subtrees across viewports.
- Emit shared content once.
- Carry viewport-specific style differences as scoped media rules.
- Preserve genuinely different mobile/desktop components as typed variant islands with explicit media conditions.
- Keep the portable website capable of standalone responsive rendering.
- Carry geometry evidence for shared nodes and each divergent island.
Blocks Engine already accepts typed `document_variants`, but that contract composes two complete editable bodies and does not by itself satisfy the one-tree editability gate. The capture contract needs component-level reconciliation rather than only document-level packaging.
## Acceptance
- A page with mostly shared desktop/mobile DOM compiles into one shared authoring tree.
- Mobile-only navigation or other genuinely divergent components remain represented and responsive.
- Shared text, media, links, headers, and footers are not duplicated in List View.
- Geometry and selector evidence remain resolvable after reconciliation.
- The editability report measures duplicate responsive content and proves a material reduction on representative captures.
- Desktop and mobile visual parity remain independently gated.
## AI assistance
OpenAI gpt-5.6-sol via OpenCode was used to measure responsive DOM overlap, compare current artifact and block structure, locate the existing document-variant contract, and draft this issue. Chris Huber reviewed and orchestrated the investigation.
Contributor guide
Research direction
Trace assembleResponsiveHtml() and the existing document_variants contract first, then compare their artifact output on the representative responsive captures. Use the editability report and desktop/mobile visual parity gates to verify that shared content is emitted once, divergent components remain responsive, and geometry and selector evidence stay resolvable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- frontend, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100