127 lines
5.4 KiB
Markdown
127 lines
5.4 KiB
Markdown
---
|
|
id: PLN-0032
|
|
ticket: studio-editor-scope-guides-and-brace-anchoring
|
|
title: Frontend structural-anchor payload propagation and anchor-aware test coverage
|
|
status: review
|
|
created: 2026-04-03
|
|
completed:
|
|
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
|
|
|
|
- [ ] 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.
|