113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
---
|
|
id: PLN-0031
|
|
ticket: studio-editor-scope-guides-and-brace-anchoring
|
|
title: Structural anchor semantic surface specification for Studio semantic read
|
|
status: done
|
|
created: 2026-04-03
|
|
completed: 2026-04-03
|
|
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
|
|
|
|
- [x] The semantic-read spec defines a dedicated structural-anchor surface separate from `documentSymbols`.
|
|
- [x] The Code Editor spec reflects the two-indicator gutter model and frontend-owned presentation.
|
|
- [x] The contract is language-agnostic and does not assume braces as the only structural delimiter.
|
|
- [x] 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.
|