148 lines
6.3 KiB
Markdown
148 lines
6.3 KiB
Markdown
---
|
|
id: DEC-0014
|
|
ticket: studio-editor-scope-guides-and-brace-anchoring
|
|
title: Code Editor active container, active scope, and frontend-owned structural anchors
|
|
status: accepted
|
|
created: 2026-04-03
|
|
accepted: 2026-04-03
|
|
agenda: AGD-0017
|
|
plans:
|
|
- PLN-0030
|
|
- PLN-0031
|
|
- PLN-0032
|
|
tags:
|
|
- studio
|
|
- editor
|
|
- scope-guides
|
|
- semantic-read
|
|
- frontend-contract
|
|
- structural-anchors
|
|
---
|
|
|
|
## Decision
|
|
|
|
The Studio Code Editor SHALL keep scope indicators in the gutter.
|
|
|
|
The initial wave SHALL render at most two simultaneous structural indicators:
|
|
|
|
1. `active container`
|
|
2. `active scope`
|
|
|
|
The Studio MUST NOT render the full ancestry map or the current multi-guide stack as the default active-scope presentation.
|
|
|
|
`active scope` SHALL be defined as the smallest structural range that contains the caret.
|
|
|
|
`active container` SHALL be defined as the immediate structural ancestor of `active scope`.
|
|
|
|
The Studio SHALL determine `active container` and `active scope` locally from semantic ranges already available to the editor, provided that the rule remains language-agnostic.
|
|
|
|
The concrete visual presentation of these two indicators SHALL remain frontend-owned. The Studio contract MUST NOT normatively fix colors, stroke style, dashed versus solid rendering, or equivalent stylistic choices.
|
|
|
|
Exact guide anchoring MUST NOT rely on local textual heuristics as the final contract. Exact anchoring SHALL be backed by frontend-owned structural metadata.
|
|
|
|
That structural metadata SHALL be expressed as generic `structural anchors`, not as PBS-specific brace semantics. The contract MUST remain language-agnostic and applicable to languages that do not use `{` / `}` as primary delimiters.
|
|
|
|
Structural anchors and guide-specific structural data SHALL live in a dedicated semantic surface. They MUST NOT be folded into `documentSymbols` as an overloaded extension of the outline/navigation payload.
|
|
|
|
## Rationale
|
|
|
|
The current gutter guides already prove that structural ranges are useful, but the existing presentation is too noisy and not precise enough:
|
|
|
|
- multiple simultaneous guide columns create visual pollution;
|
|
- the current guide start/end positions are derived from symbol line ranges, not from exact structural anchors;
|
|
- the current model is good enough to identify containing ranges, but not good enough to express precise opening/closing structure.
|
|
|
|
The accepted direction separates two concerns that have different architectural weights:
|
|
|
|
- `active container` and `active scope` are local editor-state projections and can be derived from existing semantic ranges;
|
|
- exact structural anchoring is a language-owned concern and belongs in frontend metadata rather than Studio-local syntax heuristics.
|
|
|
|
Restricting the default visualization to at most two indicators preserves context without reviving the clutter of a full ancestry map.
|
|
|
|
Keeping visual styling frontend-owned preserves the existing design direction in which semantic presentation belongs to the frontend rather than to Studio-global hardcoded rendering rules.
|
|
|
|
## Technical Specification
|
|
|
|
### 1. Gutter Indicator Model
|
|
|
|
The editor gutter SHALL support exactly two semantic slots for active structural indication:
|
|
|
|
- `activeContainer`
|
|
- `activeScope`
|
|
|
|
The first implementation wave MAY omit `activeContainer` when no valid ancestor exists. It MUST NOT synthesize a non-existent container.
|
|
|
|
The editor MUST compute `activeScope` by selecting the smallest structural range that contains the caret offset.
|
|
|
|
The editor MUST compute `activeContainer` by selecting the immediate parent structural range of `activeScope`.
|
|
|
|
The editor MUST NOT promote a higher semantic owner such as function, type, or module when a nearer structural ancestor exists.
|
|
|
|
### 2. Presentation Ownership
|
|
|
|
The editor SHALL expose enough state for the presentation layer to distinguish:
|
|
|
|
- container indicator
|
|
- scope indicator
|
|
|
|
The decision intentionally leaves the following presentation properties non-normative:
|
|
|
|
- color
|
|
- opacity
|
|
- stroke thickness
|
|
- dashed versus solid treatment
|
|
- cap styling
|
|
- equivalent visual emphasis rules
|
|
|
|
Those choices SHALL remain frontend-owned or presentation-owned.
|
|
|
|
### 3. Structural Anchoring
|
|
|
|
Exact anchor positions for guide start/end SHALL come from semantic structural metadata produced by the language/frontend side.
|
|
|
|
Studio MUST treat those anchors as generic structural positions rather than brace-specific tokens.
|
|
|
|
The metadata model MUST support languages where structural delimiters are:
|
|
|
|
- braces
|
|
- keywords
|
|
- indentation-derived constructs
|
|
- mixed delimiter schemes
|
|
|
|
### 4. Semantic Surface Boundary
|
|
|
|
`documentSymbols` SHALL remain the outline/navigation surface.
|
|
|
|
Structural guide metadata SHALL be introduced as a distinct semantic surface dedicated to:
|
|
|
|
- structural ranges
|
|
- structural parent/child relationships when needed
|
|
- structural anchors used by guide rendering
|
|
|
|
Studio MUST NOT infer the final structural contract by scanning source text for likely braces inside symbol ranges.
|
|
|
|
Local heuristics MAY exist only as temporary debugging aids during development. They MUST NOT become the canonical production contract.
|
|
|
|
### 5. Propagation Targets
|
|
|
|
This decision SHALL propagate to:
|
|
|
|
- Studio editor implementation in `prometeu-studio`
|
|
- Studio-facing semantic read contracts in `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
|
|
- Code Editor presentation and interaction behavior in `docs/specs/studio/5. Code Editor Workspace Specification.md`
|
|
- frontend-produced semantic payloads that eventually expose structural anchors
|
|
- tests covering active scope selection, active container selection, and anchor-aware rendering
|
|
|
|
## Constraints
|
|
|
|
- The decision does not authorize inline indentation-column guides inside the main code text area as the primary first-wave solution.
|
|
- The decision does not authorize restoring the existing full stacked guide rendering as the default active-scope UX.
|
|
- The decision does not fix a specific visual palette or theme mapping.
|
|
- The decision does not yet define the exact serialized schema of the future structural-anchor surface; that belongs in plan/spec work derived from this decision.
|
|
- The decision does not require immediate availability of structural anchors to ship the first-wave `active container` and `active scope` gutter behavior.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-04-03: Initial draft from AGD-0017.
|
|
- 2026-04-03: Accepted and split into execution plans PLN-0030, PLN-0031, and PLN-0032.
|