housekeep
This commit is contained in:
+129
@@ -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.
|
||||
+124
@@ -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.
|
||||
+121
@@ -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.
|
||||
Reference in New Issue
Block a user