Automattic / Automattic/data-liberation-agent

Add a Next.js platform adapter for framework-owned capture residue

Open
#161 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

Static captures of Next.js sites carry framework-owned runtime residue that is meaningless as authored content: empty route-announcer live regions, hydration payloads such as `__NEXT_DATA__`, router-owned scaffolding, and framework-specific image/asset conventions. Today that residue reaches downstream consumers unnormalized, and each consumer must infer intent from raw DOM shape alone.

Automattic/blocks-engine#1559 handled one instance of this generically, by classifying empty, visually clipped ARIA live regions from observable DOM semantics. That is the correct behavior for a platform-agnostic transformer, and it deliberately encodes no framework knowledge. It also means genuinely Next.js-specific normalization has no owner.

## Proposal

Give Next.js a first-class adapter/platform in Data Liberation Agent, built on the extensible Platform API in #158, so framework knowledge lives at the source layer where platform identity is legitimate evidence.

## Scope

- Detect Next.js from bounded capture evidence and report detection confidence like other platforms.
- Normalize framework-owned runtime residue during capture rather than exporting it as page content.
- Use hydration payloads as structured discovery/metadata input where they are authoritative.
- Keep normalization declarative and inspectable, so downstream consumers can see what was removed and why.
- Leave semantic, platform-neutral decisions to downstream transformers; the adapter should not encode WordPress or block-level policy.

## Acceptance

- A Next.js capture is detected as such and exports without framework-owned scaffolding residue.
- Captures from other platforms are unaffected.
- Removal decisions are evidence-backed and covered by deterministic tests.
- No consumer needs framework knowledge to consume the export.

## References

- Depends on #158 (extensible Platform API)
- Motivating downstream fix: Automattic/blocks-engine#1559

## AI assistance

OpenAI GPT-5.6 Sol through OpenCode produced the downstream generic fix, identified that platform-specific knowledge does not belong in the transformer core, and drafted this issue. Chris Huber set the architecture boundary and directed the split.

Contributor guide

Open the contributing guide

Research direction

Start by reading the extensible Platform API in #158, then trace the capture and platform-detection entry points it defines. Add deterministic tests for bounded Next.js detection and declarative residue handling. Done means Next.js exports omit framework-owned scaffolding, other platforms are unchanged, and removal decisions remain inspectable.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
tooling, web-dev
Issue type
Feature
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.