housekeep

This commit is contained in:
2026-04-06 04:39:27 +01:00
parent 770aa6a387
commit 5871243f8f
19 changed files with 390 additions and 1790 deletions
@@ -0,0 +1,129 @@
---
id: LSN-0034
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Active-Scope Gutter and Frontend-Owned Structural Anchors
created: 2026-04-06
tags: [studio, editor, scope-guides, structural-anchors, semantic-read, frontend-contract]
---
## Context
The Studio editor already exposed structural guides in the gutter, but the old behavior mixed two different concerns:
- active-scope context in the editor UI,
- and exact structural start/end anchoring.
That combination caused two failures at once:
- the default gutter became visually noisy because it rendered a stacked ancestry map,
- and the guide geometry still depended on approximate local heuristics rather than on language-owned structural metadata.
This discussion split those concerns into a simpler first-wave editor behavior plus a stable long-term semantic contract.
## Key Decisions
### Limit the Default Gutter to `activeScope` and `activeContainer`
**What:**
The default editor gutter now renders at most two active structural indicators:
- `activeScope`, defined as the smallest structural range containing the caret;
- `activeContainer`, defined as the immediate structural ancestor of `activeScope`.
**Why:**
The stacked ancestry gutter produced too much visual noise for routine editing.
The editor needs the nearest structure context, not the whole ancestry map.
**Trade-offs:**
The first wave intentionally drops persistent visibility of higher ancestors.
That loses some ambient hierarchy, but it produces a much clearer default editing signal.
### Keep Exact Anchoring Frontend-Owned Through a Dedicated Semantic Surface
**What:**
Exact guide start and end positions now belong to a dedicated structural-anchor semantic surface rather than to `documentSymbols` or Studio-local text scanning.
**Why:**
Outline/navigation structure and guide geometry are different contracts.
Exact anchoring must survive languages with braces, keywords, indentation, or mixed delimiter schemes, so the final source of truth has to be frontend-owned and language-agnostic.
**Trade-offs:**
The transport and DTO surface become richer, and Studio must consume one more semantic payload.
That cost is worth it because it prevents brace-specific heuristics from becoming the canonical editor contract.
### Keep Presentation Ownership Out of the Core Contract
**What:**
The contract distinguishes semantic roles such as `activeContainer` and `activeScope`, but concrete styling remains frontend-owned.
**Why:**
The host should know which guide is which, but it should not freeze colors, strokes, or theme details into the semantic decision.
**Trade-offs:**
Presentation choices remain distributed across frontend or theme layers.
That is preferable to coupling semantic meaning to one hardcoded Studio style.
## Final Implementation
The final implementation landed across editor behavior, semantic transport, and specs:
- `EditorDocumentScopeGuideModel` now resolves `activeScope` as the smallest containing range and `activeContainer` as the immediate parent, with structural-anchor-aware construction when that metadata is available.
- `EditorWorkspace` recomputes active guide state from caret movement and prefers transported structural anchors over approximate local ranges when the analyze result includes them.
- `EditorDocumentScopeGuideGraphicFactory` renders the constrained two-slot gutter model instead of the old stacked active ancestry presentation.
- `LspStructuralAnchorDTO` and `prometeu-lsp` now expose a dedicated structural-anchor transport surface separate from `documentSymbols`.
- `SemanticIndex` derives exact structural anchors for Studio consumption.
- Studio and semantic-read specs now define the two-indicator gutter model, the dedicated structural-anchor surface, and the frontend-owned exact-anchor contract.
- Tests now cover smallest-containing-range selection, immediate-parent selection, structural-anchor transport, and anchor-aware rendering.
## Patterns and Algorithms
### Pattern: Split Local Active State from Exact Structural Geometry
The useful decomposition is:
- derive active editor context locally from the current structural range set;
- derive exact guide geometry from frontend-owned structural anchors.
The editor can therefore ship a useful first wave without inventing the long-term anchor contract.
### Pattern: Use the Smallest Containing Range as the Active Scope
When multiple structural ranges contain the caret, the active scope must be the nearest one, not the largest semantic owner.
That keeps the editor aligned with the user's current editing neighborhood.
### Example: Anchor Upgrade Path
The resulting flow is:
1. semantic read returns structural ranges and, when available, exact structural anchors;
2. Studio computes `activeScope` and `activeContainer` from containment;
3. gutter rendering uses exact anchor positions when present;
4. no fallback contract is allowed to redefine exact anchoring through source scanning.
## Pitfalls
- Do not overload `documentSymbols` with guide-only anchor data.
- Do not restore the full stacked ancestry gutter as the default active-scope experience.
- Do not treat brace scanning as a production contract for exact anchors.
- Do not promote high-level owners such as function or type when a nearer structural ancestor exists.
- Do not hardcode theme or stroke policy into the semantic guide model.
## References
- `DEC-0014` Code Editor active container, active scope, and frontend-owned structural anchors
- `PLN-0030` Wave 1 editor implementation for active container and active scope gutter indicators
- `PLN-0031` Structural anchor semantic surface specification for Studio semantic read
- `PLN-0032` Frontend structural-anchor payload propagation and anchor-aware test coverage
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/LspStructuralAnchorDTO.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/models/SemanticIndex.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
## Takeaways
- Active structure and exact anchor geometry should be modeled as separate concerns.
- The default gutter becomes much clearer when it shows only the nearest scope context.
- Exact structural anchors belong to a frontend-owned semantic surface, not to Studio heuristics.
@@ -0,0 +1,124 @@
---
id: LSN-0035
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Frontend-Owned Inline Hints with Decorative Inline Rendering
created: 2026-04-06
tags: [studio, editor, inline-hints, lsp, compiler, pbs, type-inference, rendering]
---
## Context
The repository needed inline type hints for inferred PBS `let` bindings, but the real architectural issue was broader than one PBS feature.
Without a disciplined split, inline hints could easily drift into one of two broken designs:
- Studio invents semantic hint policy on its own,
- or LSP becomes a hidden semantic owner instead of a transport layer.
The work closed that gap by treating inline hints as a host-generic capability with frontend-owned meaning and Studio-owned decorative rendering.
## Key Decisions
### Keep Hint Existence and Meaning Frontend-Owned
**What:**
Frontends decide whether a hint exists, where it anchors, and which semantic payload it carries.
The initial PBS wave emits inferred-type hints only for eligible `let` bindings whose types are omitted in source.
**Why:**
Hint policy is semantic product behavior.
The host should render hints, not decide which language constructs deserve them.
**Trade-offs:**
Each frontend must publish and test its own hint policy explicitly.
That extra responsibility is better than growing a fake host-wide semantic rule set.
### Make LSP the Dedicated Hint Transport Bridge
**What:**
`prometeu-lsp` now exposes a dedicated inline-hint DTO surface and transports frontend-produced hints through analyze results without inventing content.
**Why:**
Hints need a stable contract boundary between frontend production and Studio rendering.
Transport ownership is necessary, but semantic authorship must remain outside the transport layer.
**Trade-offs:**
The semantic-read contract becomes richer and needs explicit tests for anchor stability and degraded-analysis preservation.
That is acceptable because it prevents hint content from leaking into host heuristics.
### Render Hints Inline but Keep Them Decorative
**What:**
Studio now renders transported hints inline in the editor flow while preserving text-only editing semantics.
Hints do not become persisted text, copy/paste content, or caret-selection content.
**Why:**
The decision required real inline rendering as the final UX rather than a permanent approximation.
At the same time, the document model had to remain stable and text-owned.
**Trade-offs:**
The editor rendering path is more complex because it must project hint text into the visible surface while protecting the canonical source buffer.
That complexity is justified because it preserves both the UX target and the text-model boundary.
## Final Implementation
The final state landed across specs, frontend production, LSP transport, and Studio rendering:
- Studio specs and semantic-read specs now define inline hints as frontend-owned, decorative-only, host-generic, and preserved under partial degradation.
- The compiler pipeline spec now states that inline hint semantics remain frontend-authored and must not move into Studio or LSP.
- PBS flow analysis now emits `PbsInlineHintSurface` values for eligible inferred `let` bindings and suppresses hints for explicitly typed bindings.
- `LspInlineHintDTO`, `SemanticSession`, `LspSemanticReadPhase`, and `LspSemanticAnalyseService` now transport inline hints as a dedicated semantic-read surface.
- `EditorDocumentInlineHintRouter`, `EditorInlineHintProjection`, and `EditorWorkspace` now render transported hints inline while stripping them back out of mutation and persistence flows.
- Tests cover DTO invariants, transport shape, partial-degradation preservation, PBS eligibility, and decorative editor behavior.
## Patterns and Algorithms
### Pattern: Separate Semantic Ownership from Rendering Ownership
The correct flow is:
1. frontend decides hint policy and payload;
2. LSP transports that payload without reinterpretation;
3. Studio renders it mechanically.
That preserves one semantic authority while still giving the host a reusable capability.
### Pattern: Project Inline Decorations Without Mutating the Source Buffer
Inline hints can be shown inside the editor flow by maintaining a display projection that includes decorations while keeping a canonical text-only source representation for editing and saving.
This gives real inline UX without making hints part of the file model.
### Pattern: Preserve Valid Local Signal Under Degradation
When some hint spans fail, the system should omit only those spans and keep valid ones.
Partial degradation is easier to reason about when hint payloads are independent entries rather than a monolithic all-or-nothing render switch.
## Pitfalls
- Do not let Studio synthesize hint content for constructs the frontend did not publish.
- Do not let LSP infer host-owned hint policy when the frontend emits no hints.
- Do not let inline hints leak into persisted text, copy/paste, or caret movement semantics.
- Do not keep an approximate overlay as the silent long-term architecture after the decision locked real inline rendering.
- Do not emit inferred-type hints for bindings that already carry explicit type syntax.
## References
- `DEC-0015` Studio Editor Inline Type Hints Contract and Rendering Model
- `PLN-0033` Inline hint specification and contract propagation
- `PLN-0034` LSP inline hint transport contract
- `PLN-0035` PBS inline type hint payload production
- `PLN-0036` Studio inline hint rendering and rollout
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsInlineHintSurface.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowBodyAnalyzer.java`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/LspInlineHintDTO.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorInlineHintProjection.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
## Takeaways
- Inline hints stay maintainable when semantic ownership remains in the frontend.
- Dedicated transport is necessary, but transport must not become semantic authorship.
- Real inline rendering is compatible with a text-only canonical buffer when the editor uses an explicit projection boundary.
@@ -0,0 +1,121 @@
---
id: LSN-0036
ticket: studio-frontend-editor-write-and-save-wave
title: VFS-Owned Frontend Edit and Save Wave
created: 2026-04-06
tags: [studio, editor, frontend, write, save, vfs, lsp, access-policy, persistence]
---
## Context
The first editor write wave had deliberately kept frontend files hard `read-only` while semantic-read support shipped through `prometeu-lsp`.
That left a controlled but incomplete product state:
- frontend documents already delivered semantic value,
- but editing and saving were still blocked,
- and the repository needed to decide whether that next wave would preserve or collapse the established ownership boundaries.
This discussion closed that transition by releasing frontend editing and save together under the existing VFS ownership model.
## Key Decisions
### Release Frontend Edit and Save in the Same Wave
**What:**
Frontend editing and frontend save now ship together rather than as separate product steps.
**Why:**
Editable-but-unsaveable frontend buffers would create a half-owned state and weaken the document boundary the repository had already stabilized.
**Trade-offs:**
The first write release has to be coherent across access mode, dirty tracking, save, UI enablement, and specs.
That is more coordinated work, but it avoids a broken intermediate product shape.
### Keep `prometeu-vfs` as the Sole Document and Persistence Owner
**What:**
`prometeu-vfs` remains the sole owner of frontend writable snapshots, access mode, dirty tracking, save, and save-all behavior.
Studio UI consumes those rights, and `prometeu-lsp` continues to consume VFS-backed snapshots for semantics.
**Why:**
The repository had already separated document ownership, semantic ownership, and UI consumption.
Releasing frontend editing should not reopen that boundary.
**Trade-offs:**
VFS carries more explicit frontend editing responsibility, and Studio must stay disciplined about consuming rather than deriving policy.
That is preferable to splitting persistence logic across UI and semantic tooling layers.
### Apply the First Write Wave to All Supported Frontend Files
**What:**
The first frontend write wave applies to all currently supported frontend-scoped files recognized by the VFS/frontend boundary.
**Why:**
The accepted decision explicitly rejected a temporary subset or per-file narrowing rule for this wave.
Once frontend editing is released, the supported frontend scope should behave coherently.
**Trade-offs:**
The wave requires confidence in the existing supported-file boundary.
That is a better constraint than introducing new ad hoc file-class heuristics during rollout.
## Final Implementation
The completed implementation propagated the decision across specs, VFS, and Studio:
- Studio specs now state that supported frontend-scoped documents may be editable when `prometeu-vfs` classifies them as editable and that semantic-read remains a consumer-only boundary.
- `FilesystemVfsProjectDocument` now classifies supported frontend documents as `EDITABLE`, accepts `updateDocument`, and persists them through `saveDocument` and `saveAllDocuments`.
- VFS tests now cover frontend editable access mode, in-memory mutation, save persistence, and save-all behavior.
- Studio editor session behavior now treats frontend editable files as ordinary VFS-authorized editable tabs rather than as hard `read-only` exceptions.
- Save and save-all continue to route through the existing VFS-owned path with no new persistence ownership in Studio UI or `prometeu-lsp`.
## Patterns and Algorithms
### Pattern: Release Mutation Together with Persistence
If a document class becomes editable, the same owner must also own save in the same release wave.
Otherwise the product creates a draft-only state that undermines the document boundary.
### Pattern: Keep UI as a Policy Consumer
The stable flow remains:
1. VFS classifies the document and exposes access context;
2. Studio enables editing and save based on that context;
3. LSP reads the same VFS-backed snapshots for semantics.
No layer needs to guess or duplicate ownership rules.
### Example: Frontend Save Path
The resulting save flow is:
1. a supported frontend file opens through VFS as `EDITABLE`;
2. Studio mutates the VFS-owned in-memory snapshot;
3. save and save-all persist through VFS;
4. LSP continues reading the VFS-backed snapshot without becoming a persistence owner.
## Pitfalls
- Do not release frontend editing without frontend save in the same wave.
- Do not move dirty tracking or persistence into Studio UI just because the editor hosts the interaction.
- Do not move access-policy or persistence ownership into `prometeu-lsp`.
- Do not introduce a narrowed temporary subset of supported frontend files without a new explicit decision.
- Do not let specs or UX surfaces keep describing frontend files as hard `read-only` after the wave has shipped.
## References
- `DEC-0019` Enable Frontend Editing and Save in the Studio Code Editor
- `PLN-0040` Implement the frontend editor write and save wave through VFS ownership
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
- `docs/specs/studio/6. Project Document VFS Specification.md`
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java`
- `prometeu-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorOpenFileSession.java`
## Takeaways
- Frontend editing is coherent only when save ownership lands in the same wave.
- VFS remains the right owner for access policy, dirty state, and persistence even for frontend documents.
- The architecture stays stable when Studio consumes policy and LSP consumes snapshots instead of either layer becoming a second document owner.