---
id: PLN-0032
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Frontend structural-anchor payload propagation and anchor-aware test coverage
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
  - 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

- [x] Frontend semantic-read payloads expose structural anchors through a dedicated semantic surface.
- [x] Studio consumes structural anchors without overloading `documentSymbols`.
- [x] Exact guide positioning uses structural-anchor metadata when available.
- [x] 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.