From 20851c0958b6531061c2d52c2ad63ef621eacf3c Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 3 Apr 2026 09:57:57 +0100 Subject: [PATCH] implement PLN-0031 structural anchor semantic surface spec --- discussion/index.ndjson | 2 +- ...l-anchor-semantic-surface-specification.md | 12 +++--- .../5. Code Editor Workspace Specification.md | 37 +++++++++++++++++++ ...d LSP Semantic Read Phase Specification.md | 35 ++++++++++++++++++ 4 files changed, 79 insertions(+), 7 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 55111e4a..6e4ee852 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -14,4 +14,4 @@ {"type":"discussion","id":"DSC-0013","status":"done","ticket":"studio-editor-write-wave-supported-non-frontend-files","title":"Definir a wave inicial de edicao no Code Editor apenas para arquivos aceitos e nao relacionados ao FE","created_at":"2026-03-31","updated_at":"2026-04-02","tags":["studio","editor","workspace","write","read-only","vfs","frontend-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0013-studio-editor-write-wave-supported-non-frontend-files/LSN-0028-controlled-editor-write-wave-and-read-only-frontend-semantic-phase.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]} {"type":"discussion","id":"DSC-0014","status":"done","ticket":"studio-frontend-owned-semantic-editor-presentation","title":"Definir ownership do schema visual semantico do editor por frontend","created_at":"2026-04-02","updated_at":"2026-04-02","tags":["studio","editor","frontend","presentation","semantic-highlighting","compiler","pbs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"discussion/lessons/DSC-0014-studio-frontend-owned-semantic-editor-presentation/LSN-0029-frontend-owned-semantic-presentation-descriptor-and-host-consumption.md","status":"done","created_at":"2026-04-02","updated_at":"2026-04-02"}]} {"type":"discussion","id":"DSC-0015","status":"done","ticket":"pbs-service-facade-reserved-metadata","title":"SDK Service Bodies Calling Builtin/Intrinsic Proxies as Ordinary PBS Code","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["compiler","pbs","sdk","stdlib","lowering","service","intrinsic","sdk-interface"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0030","file":"discussion/lessons/DSC-0015-pbs-service-facade-reserved-metadata/LSN-0030-sdk-service-bodies-over-private-reserved-proxies.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"}]} -{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"review","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"review","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]} +{"type":"discussion","id":"DSC-0016","status":"open","ticket":"studio-editor-scope-guides-and-brace-anchoring","title":"Scope Guides do Code Editor com ancoragem exata em braces e destaque do escopo ativo","created_at":"2026-04-03","updated_at":"2026-04-03","tags":["studio","editor","scope-guides","braces","semantic-read","frontend-contract"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-studio-editor-scope-guides-and-brace-anchoring.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"decisions":[{"id":"DEC-0014","file":"DEC-0014-studio-editor-active-scope-and-structural-anchors.md","status":"accepted","created_at":"2026-04-03","updated_at":"2026-04-03"}],"plans":[{"id":"PLN-0030","file":"PLN-0030-studio-active-container-and-active-scope-gutter-wave-1.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0031","file":"PLN-0031-studio-structural-anchor-semantic-surface-specification.md","status":"done","created_at":"2026-04-03","updated_at":"2026-04-03"},{"id":"PLN-0032","file":"PLN-0032-frontend-structural-anchor-payloads-and-anchor-aware-tests.md","status":"review","created_at":"2026-04-03","updated_at":"2026-04-03"}],"lessons":[]} diff --git a/discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md b/discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md index 5620ae5f..4ab71092 100644 --- a/discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md +++ b/discussion/workflow/plans/PLN-0031-studio-structural-anchor-semantic-surface-specification.md @@ -2,9 +2,9 @@ id: PLN-0031 ticket: studio-editor-scope-guides-and-brace-anchoring title: Structural anchor semantic surface specification for Studio semantic read -status: review +status: done created: 2026-04-03 -completed: +completed: 2026-04-03 tags: - studio - specs @@ -96,10 +96,10 @@ If a separate schema subsection or appendix is needed, add it within the relevan ## 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. +- [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 diff --git a/docs/specs/studio/5. Code Editor Workspace Specification.md b/docs/specs/studio/5. Code Editor Workspace Specification.md index a7dae354..766b3cfd 100644 --- a/docs/specs/studio/5. Code Editor Workspace Specification.md +++ b/docs/specs/studio/5. Code Editor Workspace Specification.md @@ -21,6 +21,7 @@ This specification stabilizes: - the mixed editable and hard `read-only` file-opening model, - the responsive tab baseline, - the editor-owned composition surfaces that host save and semantic-read UX, +- the gutter-based active-structure indicator model for semantic editor scopes, - the editor-local save surfaces, - and the workspace boundary with the integrated frontend semantic-read phase. @@ -46,6 +47,7 @@ The `Code Editor` workspace must assume: - all project files remain visible in the editor workspace even when only some are frontend-relevant, - `prometeu.json` plus the selected frontend may identify source roots worth tagging, - the integrated frontend semantic-read phase may add diagnostics, symbols, outline-facing structure, definition, and highlight for frontend documents, +- the integrated frontend semantic-read phase may later add dedicated structural-anchor metadata for exact scope-indicator anchoring, - frontend semantic presentation contract data comes from frontend-owned metadata published through `FrontendSpec`, - and the current wave must not depend on semantic behavior to remain coherent. @@ -211,6 +213,7 @@ Rules: - Frontend documents remain hard `read-only` even when semantic-read capabilities are active. - Diagnostics, document symbols, workspace symbols, outline-facing structure, definition, and frontend highlight must come through the integrated LSP semantic-read phase rather than from editor-local inference. +- Exact anchor positions for semantic scope indicators must come from frontend-owned structural metadata rather than Studio-local text scanning when that metadata is available. - Opened frontend documents must be analyzed from the VFS-owned in-memory snapshot exposed through `prometeu-vfs`. - Unopened frontend documents may be analyzed from filesystem-backed state exposed through the same `prometeu-vfs` boundary. - Non-frontend highlight may remain Studio-local in this phase. @@ -220,6 +223,40 @@ Rules: - The workspace must not surface this condition as a product-facing editor error. - The workspace must not treat semantic-read over editorial snapshots as authorization for frontend save, mutation, or build participation. +## Scope Indicator Rules + +The default semantic scope-indicator surface in the Code Editor must remain the gutter. + +The first active-state wave must render at most two simultaneous semantic indicators: + +- `activeContainer` +- `activeScope` + +The editor must not restore the previous full ancestry stack as the default active-state presentation. + +`activeScope` must be selected as the smallest structural range that contains the caret. + +`activeContainer` must be selected as the immediate structural ancestor of `activeScope`. + +If no valid structural ancestor exists, the editor may omit `activeContainer`. + +The editor must not promote a higher semantic owner such as function, type, or module when a nearer structural ancestor exists. + +The concrete visual presentation of `activeContainer` and `activeScope` remains frontend-owned. This specification intentionally does not fix: + +- colors, +- stroke style, +- dashed versus solid treatment, +- opacity, +- thickness, +- or equivalent visual-emphasis details. + +The Studio editor must only preserve the semantic distinction between the two indicator roles. + +Exact guide start and end anchoring must consume the dedicated structural-anchor semantic surface defined by the integrated semantic-read specification. + +The editor must not treat local brace scanning heuristics as the final production contract for exact anchor placement. + ## Status Bar Rules The status bar must remain mostly passive in this wave. diff --git a/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md b/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md index 5bf192f7..11b9f7bf 100644 --- a/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md +++ b/docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md @@ -20,6 +20,7 @@ This specification stabilizes: - the phase boundary between semantic read and frontend editing, - the ownership relationship between `prometeu-vfs`, `prometeu-lsp`, and the Studio editor, - the minimum semantic capability set for frontend documents, +- the dedicated semantic surface used for structural anchors and guide-aware editor structure, - the packaging expectations for the public `prometeu-lsp` API surface, - and the explicit exclusions that remain outside this phase. @@ -88,6 +89,8 @@ The minimum semantic capability set of this phase must include: - go-to-definition for frontend documents; - frontend semantic highlight. +The phase may ship the dedicated structural-anchor surface after the baseline capability set is stable, but Studio and frontend implementations must treat that surface as the canonical source of exact scope-indicator anchoring once it exists. + ## Highlight Ownership Rules - frontend highlight must come from semantic information provided through `prometeu-lsp`; @@ -101,6 +104,38 @@ The minimum semantic capability set of this phase must include: - this condition must not become a product-facing Studio error and may at most produce normal development logs; - non-frontend highlight may remain on the existing Studio-local highlighting path in this phase. +## Structural Anchor Semantic Surface + +Exact structural anchoring for editor scope indicators must not be overloaded into `documentSymbols`. + +`documentSymbols` remains the outline and navigation surface. + +Guide-oriented structure must be exposed through a dedicated semantic surface for structural anchors and related guide metadata. + +That dedicated surface must be frontend-owned and language-agnostic. + +The contract must describe generic structural positions rather than PBS-specific brace semantics. + +The surface must be able to represent structures whose boundaries are expressed by: + +- braces; +- keywords; +- indentation-derived blocks; +- or mixed delimiter schemes. + +At minimum, the dedicated structural-anchor surface must be able to communicate: + +- structural ranges that can participate in active-scope selection; +- immediate parentage or equivalent information needed to recover the nearest ancestor relationship; +- exact structural anchor positions used for guide start and end placement; +- enough structural identity to distinguish the active structural range from its immediate container. + +The semantic-read contract must not require Studio to scan source text in order to discover the final structural anchor positions. + +Temporary local heuristics may exist only as development aids. They must not become the canonical production contract. + +The exact serialized schema of this dedicated surface may evolve in implementation plans, but any accepted schema must preserve the invariants above. + ## Packaging Rules The public `prometeu-lsp` API should follow flat packaging similar to `prometeu-packer-api`.