editor scope guides

This commit is contained in:
2026-04-03 09:52:04 +01:00
parent 18b1967e6d
commit e06be29f4b
10 changed files with 700 additions and 455 deletions
@@ -1,181 +0,0 @@
---
id: PLN-0029
ticket: pbs-service-facade-reserved-metadata
title: Implement Restricted Executable SDK Service Bodies for Intrinsic-Backed Public Services
status: review
created: 2026-04-03
completed:
tags: [compiler, pbs, sdk, stdlib, lowering, service, intrinsic, sdk-interface]
---
## Objective
Implement the `DEC-0013` model for restricted executable SDK service bodies so public SDK services such as `@sdk:input` compile as ordinary PBS service code while preserving host and intrinsic lowering inside imported SDK service bodies.
## Background
`DEC-0013` accepts the model where:
- `SDK_INTERFACE` remains non-executable by default;
- eligible SDK `service` methods gain a narrow executable path;
- user callsites lower as ordinary callable invocations of imported SDK service methods;
- host and intrinsic lowering continue to happen inside the imported SDK service body;
- returned reserved values preserve owner and chaining behavior;
- dedicated diagnostics replace generic unresolved-callee failures for unsupported cases.
The current compiler exposes imported SDK service signatures but does not provide an executable-body path for intrinsic-backed service wrappers such as `Input.touch()` and `Input.pad()`. The plan below closes that gap without generalizing arbitrary executable code across all interface declarations.
## Scope
### Included
- Defining and validating eligibility rules for executable SDK service methods.
- Representing eligible SDK service method bodies so imported user callsites can lower them as ordinary callable invocations.
- Lowering imported SDK service bodies under a restricted executable subset.
- Preserving owner propagation and chained reserved behavior for returned intrinsic-backed values.
- Adding dedicated diagnostics for unsupported executable SDK service bodies.
- Updating frontend and integration tests to reflect the accepted model.
### Excluded
- General executable support for arbitrary `SDK_INTERFACE` functions, globals, or unrestricted declarations.
- Public exposure of private reserved builtin roots.
- Expansion of the restricted executable subset beyond the first explicitly supported wave unless needed to satisfy `DEC-0013`.
- Editorial changes to unrelated SDK modules.
## Execution Steps
### Step 1 - Define the Executable SDK Service Eligibility Boundary
**What:** Introduce the compiler-side concept of an eligible executable SDK service method and enforce the first restricted subset accepted by `DEC-0013`.
**How:** Add validation logic that runs on `SourceKind.SDK_INTERFACE` service methods and classifies each method as either executable/importable or rejected with a dedicated diagnostic. The first supported subset must explicitly allow local bindings, ordinary returns, calls to reserved hosts, calls to reserved builtin const proxies, intrinsic-return chaining, and straightforward wrapper-style expression composition. Any construct outside that subset must fail deterministically with a dedicated diagnostic instead of reaching generic lowering failure.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/...` as needed for executable-subset validation
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSemanticsErrors.java`
### Step 2 - Expose Imported SDK Service Bodies to the Lowering Pipeline
**What:** Extend imported SDK context assembly so eligible SDK service methods are available not only as callable signatures but also as executable bodies that user modules can target.
**How:** Enrich the imported semantic/lowering context with per-method executable metadata for eligible SDK service methods, including module identity, owning service, signature shape, AST/body reference, and any lowering metadata required to compile the imported method body exactly once in a controlled way. Preserve the existing lightweight path for non-executable interface declarations.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContext.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsFrontendCompiler.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/messages/FESurfaceContext.java`
### Step 3 - Lower Public SDK Service Calls as Callable Invocations of Imported Bodies
**What:** Make user callsites such as `Input.touch()` and `Input.pad()` resolve as callable invocations of imported executable SDK service methods.
**How:** Update callable resolution and lowering metadata so eligible imported SDK service methods participate as ordinary callable targets with executable bodies rather than metadata-only surfaces. Ensure public service callsites resolve to `CALL_FUNC`-style lowering when appropriate and do not require public facade metadata or direct builtin-root identity at the callsite itself.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringService.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringModels.java`
### Step 4 - Lower Imported SDK Service Method Bodies Under the Restricted Subset
**What:** Add the executable-body lowering path for eligible imported SDK service methods so reserved host and intrinsic calls continue to lower inside the SDK method body itself.
**How:** Reuse as much of the existing executable lowering pipeline as possible, but constrain it to imported eligible SDK service methods. Ensure the lowering path supports locals, returns, reserved host calls, reserved builtin const proxy calls, and direct wrapper-style logic. Prevent accidental lowering of unsupported or non-eligible interface code.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java`
### Step 5 - Preserve Return Owner and Chaining Semantics Across SDK Service Returns
**What:** Ensure values returned by imported SDK service methods keep the same reserved owner identity and chaining behavior as the intrinsic/host-backed values produced inside the method body.
**How:** Propagate owner metadata from the lowered reserved call through the return path of the imported SDK service method so downstream user expressions such as `Input.touch().x()` and `Input.pad().a().pressed()` retain resolvable chained semantics. Add targeted validation when the compiler cannot preserve this owner chain safely.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java`
### Step 6 - Introduce Dedicated Diagnostics for Non-Lowerable SDK Service Bodies
**What:** Replace generic unresolved-callee failures with dedicated diagnostics for unsupported executable SDK service bodies.
**How:** Add explicit error codes and reporting paths for:
- non-eligible executable SDK service methods;
- unsupported constructs inside executable SDK service bodies;
- signature/body inconsistencies for imported executable SDK service methods;
- unpreservable reserved owner/chaining cases.
Wire these diagnostics so failures are emitted at validation/lowering time with stable code identity and source spans.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSemanticsErrors.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/...` diagnostic contract tests
### Step 7 - Update and Expand Tests to Match DEC-0013
**What:** Align the PBS frontend and pipeline test suite with the accepted executable SDK service body model.
**How:** Update existing `@sdk:input` tests that currently assume public callsites lower directly to intrinsics. Add coverage for:
- public `Input.touch()` and `Input.pad()` callsites lowering successfully through imported SDK service bodies;
- intrinsic lowering occurring inside those imported bodies;
- locals and intermediate processing inside SDK service bodies;
- returned owner and chained calls such as `touch.x()` and `Input.pad().a().pressed()`;
- dedicated diagnostics when an executable SDK service body violates the restricted subset.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java`
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/integration/MainProjectPipelineIntegrationTest.java`
- related diagnostic/lowering tests as needed
## Test Requirements
### Unit Tests
- Validation tests for executable SDK service method eligibility and restricted-subset rejection.
- Lowering tests for imported SDK service callsites resolving as callable invocations.
- Lowering tests for intrinsic and host operations inside imported SDK service bodies.
- Owner-propagation tests for returned reserved values and chained member calls.
- Diagnostic identity tests for each new SDK executable-service failure mode.
### Integration Tests
- Pipeline test proving `test-projects/main` compiles successfully when `@sdk:input` is expressed as a public service over a private builtin proxy.
- Integration coverage for mixed SDK modules so existing host-backed wrappers (`Log`, `Gfx`, `Assets`) continue to work unchanged alongside the new intrinsic-backed service model.
### Manual Verification
- Run the compile pipeline against the main test project with the service-based `@sdk:input` shape.
- Verify the resulting IR contains callable lowering for the public SDK service entrypoint and intrinsic lowering inside the imported SDK service body.
- Confirm unsupported SDK executable constructs emit the new dedicated diagnostics rather than `E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE`.
## Acceptance Criteria
- [ ] Eligible SDK service methods in `SDK_INTERFACE` can be imported with executable bodies while the rest of the interface surface remains non-executable by default.
- [ ] Public callsites such as `Input.touch()` and `Input.pad()` lower as callable invocations of imported SDK service methods.
- [ ] Reserved host and intrinsic calls inside imported SDK service bodies lower correctly through the existing reserved machinery.
- [ ] Returned reserved values preserve owner/chaining semantics for expressions such as `Input.touch().x()` and `Input.pad().a().pressed()`.
- [ ] Unsupported executable SDK service bodies fail with dedicated diagnostics instead of generic unresolved-callee errors.
- [ ] Existing host-backed SDK services continue to compile without regression.
- [ ] Frontend and integration tests reflect and enforce the accepted model from `DEC-0013`.
## Dependencies
- Accepted decision: `DEC-0013`.
- Existing reserved metadata and intrinsic lowering infrastructure in the PBS frontend.
- Existing imported semantic-context assembly for SDK modules.
- Existing host-backed SDK service behavior must remain as the regression baseline.
## Risks
- The executable-service exception for `SDK_INTERFACE` could accidentally broaden into support for arbitrary interface code if the eligibility boundary is not enforced centrally.
- Owner propagation across imported SDK service returns may require careful threading of metadata through call/return paths and could regress chained intrinsic resolution if partially implemented.
- Reusing ordinary executable lowering for imported SDK bodies may expose assumptions that currently only hold for project-local executable functions.
- Test expectations that currently assert direct intrinsic callsites may need careful revision to avoid preserving obsolete invariants.
@@ -0,0 +1,137 @@
---
id: PLN-0030
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Wave 1 editor implementation for active container and active scope gutter indicators
status: review
created: 2026-04-03
completed:
tags:
- studio
- editor
- scope-guides
- gutter
- active-scope
---
## Objective
Implement the first Studio editor wave mandated by DEC-0014: a gutter-based active-structure indicator that renders at most two simultaneous states, `activeContainer` and `activeScope`, computed locally from existing structural ranges.
## Background
The current editor renders a stacked multi-guide gutter model derived from document symbols. DEC-0014 replaces that default with a constrained active-state presentation:
- keep scope indicators in the gutter;
- compute `activeScope` as the smallest structural range containing the caret;
- compute `activeContainer` as the immediate ancestor of `activeScope`;
- render at most two indicators;
- keep concrete styling frontend-owned.
This plan intentionally covers only the editor-local behavior that can ship without structural-anchor metadata.
## Scope
### Included
- Replace the default stacked guide presentation with an active-state model in `prometeu-studio`.
- Extend the editor scope guide model so it can resolve `activeScope` and `activeContainer` from the caret offset.
- Update gutter rendering to draw no more than two structural indicators.
- Expose semantic slots or equivalent rendering states that allow presentation to distinguish container versus scope.
- Add tests for active-scope selection and active-container selection.
### Excluded
- Exact anchor positioning from structural metadata.
- Changes to frontend payload schemas.
- Changes to semantic read transport contracts outside what the editor already consumes.
## Execution Steps
### Step 1 - Refactor the local scope-guide model around structural containment
**What:** Introduce a model capable of resolving structural containment from caret position and expressing the two active semantic states.
**How:** Update `EditorDocumentScopeGuideModel` so it retains enough structural information to:
- map paragraph and caret offsets back to containing structural ranges;
- select the smallest containing range as `activeScope`;
- select the immediate parent as `activeContainer`;
- expose a paragraph-level view suitable for rendering only the relevant two indicators.
Avoid any logic that promotes higher semantic owners such as function or type when a nearer ancestor exists.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`
- supporting editor model classes if extraction improves clarity
### Step 2 - Bind caret movement to active-state recomputation
**What:** Recompute active structural state as the caret moves.
**How:** Update `EditorWorkspace` to observe caret position changes from the `CodeArea`, resolve the current active structural state through the model, and refresh paragraph graphics when the active state changes.
The implementation must remain language-agnostic and rely only on structural ranges already available through the semantic read result.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
### Step 3 - Replace stacked guide rendering with a two-slot gutter renderer
**What:** Redesign the gutter renderer so the default active-state UX shows at most `activeContainer` and `activeScope`.
**How:** Update `EditorDocumentScopeGuideGraphicFactory` to consume the active-state data and render:
- no indicator when no structural range contains the caret;
- one indicator when only `activeScope` exists;
- two distinguishable indicators when both `activeContainer` and `activeScope` exist.
Do not hardcode semantic color contracts into decision logic. The renderer may expose separate style classes, paint roles, or equivalent slots so that presentation styling remains decoupled from the semantic model.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- related editor presentation stylesheet hooks if necessary
### Step 4 - Update editor tests for the new active-state behavior
**What:** Replace tests that validate the old stacked guide model as the default expectation.
**How:** Add or update tests that cover:
- smallest-containing-range selection for `activeScope`;
- immediate-parent selection for `activeContainer`;
- omission of `activeContainer` when no parent exists;
- rendering behavior constrained to at most two semantic indicators.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModelTest.java`
- renderer tests or workspace tests if such coverage exists or needs to be introduced
## Test Requirements
### Unit Tests
- Model tests for nested ranges and caret placement transitions.
- Tests that prove immediate-parent selection rather than semantic-owner promotion.
- Tests that prove no more than two semantic gutter indicators are active at once.
### Integration Tests
- Editor workspace tests that move the caret through nested structures and validate gutter state transitions if an existing JavaFX/editor harness is available.
### Manual Verification
- Open a frontend-backed document with nested scopes.
- Move the caret across siblings, parent blocks, and root-level declarations.
- Confirm that the gutter shows only `activeScope` and optional `activeContainer`.
- Confirm that no full ancestry stack is shown by default.
## Acceptance Criteria
- [ ] The default editor gutter no longer renders the old full stacked active-scope presentation.
- [ ] `activeScope` is selected as the smallest structural range containing the caret.
- [ ] `activeContainer` is selected as the immediate structural ancestor of `activeScope`.
- [ ] The editor renders at most two active semantic indicators in the gutter.
- [ ] The implementation remains language-agnostic and uses only existing structural ranges.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Existing semantic range payloads already consumed by `EditorWorkspace`
## Risks
- Paragraph-graphic refreshes may become visually noisy or too expensive if caret updates are not throttled or diffed.
- Existing tests may encode the previous stacked-gutter behavior and need coordinated updates.
- The current model may need deeper refactoring than expected if it stores only per-line segments and not enough structural identity information.
@@ -0,0 +1,112 @@
---
id: PLN-0031
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Structural anchor semantic surface specification for Studio semantic read
status: review
created: 2026-04-03
completed:
tags:
- studio
- specs
- semantic-read
- structural-anchors
- frontend-contract
---
## Objective
Specify the dedicated semantic surface required by DEC-0014 for structural anchors and guide-specific structural metadata, without overloading `documentSymbols`.
## Background
DEC-0014 requires exact guide anchoring to come from frontend-owned structural metadata expressed as generic structural anchors. The decision explicitly forbids treating local text scanning as the final contract and explicitly keeps `documentSymbols` as the outline/navigation surface.
This plan covers the normative documentation and contract-shaping work needed before frontend payloads and Studio consumers can converge on a stable schema.
## Scope
### Included
- Define the semantic-read contract boundary for structural anchors in Studio specs.
- Specify a dedicated surface for structural guide metadata separate from `documentSymbols`.
- Define the normative semantics of structural ranges, parentage, and anchors in language-agnostic terms.
- Define how the Studio editor consumes that surface for exact guide start/end anchoring.
### Excluded
- Frontend implementation of the new payload.
- Studio code changes that consume the new payload.
- Theme or visual styling decisions.
## Execution Steps
### Step 1 - Update the semantic-read specification with a dedicated structural-anchor surface
**What:** Add a normative section to the Studio semantic-read specification defining a new dedicated semantic surface for guide-oriented structural metadata.
**How:** Update the semantic-read spec to state that:
- `documentSymbols` remains the outline/navigation surface;
- structural guide metadata is delivered through a separate payload or surface;
- the surface must support structural ranges, parent/child relations when required, and exact anchors for guide rendering;
- the contract is language-agnostic and must not encode brace-only assumptions.
**File(s):**
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
### Step 2 - Update the Code Editor workspace specification for active indicators and anchor consumption
**What:** Propagate DEC-0014 into the Code Editor workspace specification.
**How:** Update the editor spec so it normatively states:
- the gutter remains the primary scope-indicator surface for the initial wave;
- the editor renders at most two active indicators: `activeContainer` and `activeScope`;
- exact start/end anchoring depends on the structural-anchor semantic surface;
- concrete visual treatment remains frontend-owned.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
### Step 3 - Define the schema and semantic invariants of structural anchors
**What:** Describe the minimum schema and invariants needed for frontend and Studio implementations to interoperate safely.
**How:** Specify, at minimum:
- what a structural range represents;
- how parentage is expressed or inferred;
- what anchor positions represent;
- how the model behaves for languages with braces, keywords, indentation, or mixed delimiters;
- which invariants tests and future implementations must honor.
If a separate schema subsection or appendix is needed, add it within the relevant spec surface rather than inventing an ad hoc note.
**File(s):**
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `docs/specs/studio/5. Code Editor Workspace Specification.md` if editor-facing invariants need reiteration
## Test Requirements
### Unit Tests
- Not applicable at this spec-only stage.
### Integration Tests
- Not applicable at this spec-only stage.
### Manual Verification
- Review the spec text against DEC-0014 and confirm every normative requirement is represented.
- Confirm the spec does not overload `documentSymbols`.
- Confirm the spec speaks in generic structural anchors rather than brace-specific terms.
## Acceptance Criteria
- [ ] The semantic-read spec defines a dedicated structural-anchor surface separate from `documentSymbols`.
- [ ] The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
- [ ] The contract is language-agnostic and does not assume braces as the only structural delimiter.
- [ ] The spec text is sufficient for a frontend and Studio implementation plan without reopening DEC-0014.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Existing Studio specs in `docs/specs/studio`
## Risks
- Over-specifying serialization too early may constrain future frontends unnecessarily.
- Under-specifying parentage and anchor semantics may leave ambiguous implementation choices and force a decision revisit.
@@ -0,0 +1,126 @@
---
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.