Automattic / Automattic/data-liberation-agent

Reconcile responsive captures into one authoring tree

Open
#144 0 comments 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.