prometeu-studio/discussion/workflow/plans/PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md

id	ticket	title	status	created	completed	tags
PLN-0032	studio-editor-scope-guides-and-brace-anchoring	Frontend structural-anchor payload propagation and anchor-aware test coverage	review	2026-04-03		studio frontend semantic-read structural-anchors tests

Objective

Implement and validate frontend-produced structural-anchor payloads and the Studio-side test coverage required to support exact anchor-aware gutter rendering after the contract defined in DEC-0014 and its derived specs is in place.

Background

DEC-0014 splits execution into two tracks:

• a first local editor wave based on existing structural ranges;
• a later exact-anchoring wave backed by frontend-owned structural metadata delivered through a dedicated semantic surface.

This plan covers the propagation work after the semantic surface is specified.

Scope

Included

• Extend the relevant frontend semantic-read payloads to emit structural-anchor metadata.
• Extend Studio-side DTOs or semantic-read consumption models to accept the new payload.
• Add tests proving that exact anchor positions survive transport and can drive guide rendering.
• Validate language-agnostic behavior through contract-level fixtures or tests.

Excluded

• The first-wave active-container/active-scope editor behavior based only on current ranges.
• Broader presentation redesign beyond what is required to consume exact anchors.

Execution Steps

Step 1 - Extend frontend semantic-read producers with structural-anchor payloads

What: Add production of the dedicated structural-anchor surface in the relevant frontend(s).

How: For each participating frontend, emit:

• structural ranges;
• parentage or equivalent ancestry data as required by the final spec;
• anchor positions for exact guide start/end rendering.

Implementations must honor the language-agnostic contract while mapping language-specific structure into the generic anchor model.

File(s):

• frontend semantic-read producers and payload mappers, to be identified from the accepted spec work

Step 2 - Extend Studio semantic-read consumption models

What: Teach Studio DTOs and semantic-read consumption code to accept the structural-anchor surface.

How: Update DTOs, transport mapping, and editor-side analysis models so the new structural metadata can flow from semantic read results into the gutter renderer without polluting documentSymbols.

File(s):

• Studio DTO and semantic-read integration modules, to be identified after schema finalization
• prometeu-studio editor integration points that consume semantic analysis results

Step 3 - Make gutter rendering anchor-aware

What: Upgrade the gutter renderer to use exact structural anchors when available.

How: Adapt the active indicator renderer so guide start/end/cap placement uses structural-anchor metadata rather than symbol-line midpoint approximations.

The implementation must preserve the DEC-0014 rule that structural anchors are the canonical source of exact positioning.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java
• associated editor model or adapter layers introduced to consume structural anchors

Step 4 - Add anchor-aware contract and rendering tests

What: Add tests covering transport, interpretation, and rendering of structural anchors.

How: Introduce tests that prove:

• structural-anchor payloads are emitted by frontend semantic read;
• Studio receives and stores them separately from documentSymbols;
• exact opening/closing anchor positions drive rendering behavior;
• languages with non-brace structure can still map into the generic contract.

File(s):

• frontend semantic-read tests
• Studio DTO/transport tests
• editor model and renderer tests

Test Requirements

Unit Tests

• Payload schema mapping tests.
• Editor adapter/model tests for anchor interpretation.
• Renderer tests for exact start/end placement using anchor positions.

Integration Tests

• End-to-end semantic-read tests from frontend producer to Studio consumer when an existing harness supports that boundary.

Manual Verification

• Open representative nested documents after structural anchors are available.
• Confirm that guide start/end visually align with structural anchor positions rather than line midpoints.
• Confirm that the active indicator model remains limited to activeContainer and activeScope.

Acceptance Criteria

• Frontend semantic-read payloads expose structural anchors through a dedicated semantic surface.
• Studio consumes structural anchors without overloading documentSymbols.
• Exact guide positioning uses structural-anchor metadata when available.
• Tests cover payload transport, anchor interpretation, and anchor-aware rendering.

Dependencies

• Accepted decision DEC-0014-studio-editor-active-scope-and-structural-anchors.md
• Accepted spec work derived from PLN-0031
• Studio editor wave-1 implementation from PLN-0030 if shared gutter machinery is reused

Risks

• Frontend payload evolution may require coordinated versioning or backwards-compatibility handling.
• Test fixtures may become brittle if the structural-anchor schema is not stabilized before implementation starts.
• Exact rendering behavior may vary with font metrics and paragraph layout, requiring robust assertions that test semantic placement rather than pixel-perfect incidental details.