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
@@ -1,137 +0,0 @@
---
id: PLN-0030
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Wave 1 editor implementation for active container and active scope gutter indicators
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
- studio
- editor
- scope-guides
- gutter
- active-scope
---
## Objective
Implement the first Studio editor wave mandated by DEC-0014: a gutter-based active-structure indicator that renders at most two simultaneous states, `activeContainer` and `activeScope`, computed locally from existing structural ranges.
## Background
The current editor renders a stacked multi-guide gutter model derived from document symbols. DEC-0014 replaces that default with a constrained active-state presentation:
- keep scope indicators in the gutter;
- compute `activeScope` as the smallest structural range containing the caret;
- compute `activeContainer` as the immediate ancestor of `activeScope`;
- render at most two indicators;
- keep concrete styling frontend-owned.
This plan intentionally covers only the editor-local behavior that can ship without structural-anchor metadata.
## Scope
### Included
- Replace the default stacked guide presentation with an active-state model in `prometeu-studio`.
- Extend the editor scope guide model so it can resolve `activeScope` and `activeContainer` from the caret offset.
- Update gutter rendering to draw no more than two structural indicators.
- Expose semantic slots or equivalent rendering states that allow presentation to distinguish container versus scope.
- Add tests for active-scope selection and active-container selection.
### Excluded
- Exact anchor positioning from structural metadata.
- Changes to frontend payload schemas.
- Changes to semantic read transport contracts outside what the editor already consumes.
## Execution Steps
### Step 1 - Refactor the local scope-guide model around structural containment
**What:** Introduce a model capable of resolving structural containment from caret position and expressing the two active semantic states.
**How:** Update `EditorDocumentScopeGuideModel` so it retains enough structural information to:
- map paragraph and caret offsets back to containing structural ranges;
- select the smallest containing range as `activeScope`;
- select the immediate parent as `activeContainer`;
- expose a paragraph-level view suitable for rendering only the relevant two indicators.
Avoid any logic that promotes higher semantic owners such as function or type when a nearer ancestor exists.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModel.java`
- supporting editor model classes if extraction improves clarity
### Step 2 - Bind caret movement to active-state recomputation
**What:** Recompute active structural state as the caret moves.
**How:** Update `EditorWorkspace` to observe caret position changes from the `CodeArea`, resolve the current active structural state through the model, and refresh paragraph graphics when the active state changes.
The implementation must remain language-agnostic and rely only on structural ranges already available through the semantic read result.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
### Step 3 - Replace stacked guide rendering with a two-slot gutter renderer
**What:** Redesign the gutter renderer so the default active-state UX shows at most `activeContainer` and `activeScope`.
**How:** Update `EditorDocumentScopeGuideGraphicFactory` to consume the active-state data and render:
- no indicator when no structural range contains the caret;
- one indicator when only `activeScope` exists;
- two distinguishable indicators when both `activeContainer` and `activeScope` exist.
Do not hardcode semantic color contracts into decision logic. The renderer may expose separate style classes, paint roles, or equivalent slots so that presentation styling remains decoupled from the semantic model.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- related editor presentation stylesheet hooks if necessary
### Step 4 - Update editor tests for the new active-state behavior
**What:** Replace tests that validate the old stacked guide model as the default expectation.
**How:** Add or update tests that cover:
- smallest-containing-range selection for `activeScope`;
- immediate-parent selection for `activeContainer`;
- omission of `activeContainer` when no parent exists;
- rendering behavior constrained to at most two semantic indicators.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/EditorDocumentScopeGuideModelTest.java`
- renderer tests or workspace tests if such coverage exists or needs to be introduced
## Test Requirements
### Unit Tests
- Model tests for nested ranges and caret placement transitions.
- Tests that prove immediate-parent selection rather than semantic-owner promotion.
- Tests that prove no more than two semantic gutter indicators are active at once.
### Integration Tests
- Editor workspace tests that move the caret through nested structures and validate gutter state transitions if an existing JavaFX/editor harness is available.
### Manual Verification
- Open a frontend-backed document with nested scopes.
- Move the caret across siblings, parent blocks, and root-level declarations.
- Confirm that the gutter shows only `activeScope` and optional `activeContainer`.
- Confirm that no full ancestry stack is shown by default.
## Acceptance Criteria
- [x] The default editor gutter no longer renders the old full stacked active-scope presentation.
- [x] `activeScope` is selected as the smallest structural range containing the caret.
- [x] `activeContainer` is selected as the immediate structural ancestor of `activeScope`.
- [x] The editor renders at most two active semantic indicators in the gutter.
- [x] The implementation remains language-agnostic and uses only existing structural ranges.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Existing semantic range payloads already consumed by `EditorWorkspace`
## Risks
- Paragraph-graphic refreshes may become visually noisy or too expensive if caret updates are not throttled or diffed.
- Existing tests may encode the previous stacked-gutter behavior and need coordinated updates.
- The current model may need deeper refactoring than expected if it stores only per-line segments and not enough structural identity information.
@@ -1,112 +0,0 @@
---
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.
@@ -1,126 +0,0 @@
---
id: PLN-0032
ticket: studio-editor-scope-guides-and-brace-anchoring
title: Frontend structural-anchor payload propagation and anchor-aware test coverage
status: done
created: 2026-04-03
completed: 2026-04-03
tags:
- studio
- frontend
- semantic-read
- structural-anchors
- tests
---
## Objective
Implement and validate frontend-produced structural-anchor payloads and the Studio-side test coverage required to support exact anchor-aware gutter rendering after the contract defined in DEC-0014 and its derived specs is in place.
## Background
DEC-0014 splits execution into two tracks:
- a first local editor wave based on existing structural ranges;
- a later exact-anchoring wave backed by frontend-owned structural metadata delivered through a dedicated semantic surface.
This plan covers the propagation work after the semantic surface is specified.
## Scope
### Included
- Extend the relevant frontend semantic-read payloads to emit structural-anchor metadata.
- Extend Studio-side DTOs or semantic-read consumption models to accept the new payload.
- Add tests proving that exact anchor positions survive transport and can drive guide rendering.
- Validate language-agnostic behavior through contract-level fixtures or tests.
### Excluded
- The first-wave active-container/active-scope editor behavior based only on current ranges.
- Broader presentation redesign beyond what is required to consume exact anchors.
## Execution Steps
### Step 1 - Extend frontend semantic-read producers with structural-anchor payloads
**What:** Add production of the dedicated structural-anchor surface in the relevant frontend(s).
**How:** For each participating frontend, emit:
- structural ranges;
- parentage or equivalent ancestry data as required by the final spec;
- anchor positions for exact guide start/end rendering.
Implementations must honor the language-agnostic contract while mapping language-specific structure into the generic anchor model.
**File(s):**
- frontend semantic-read producers and payload mappers, to be identified from the accepted spec work
### Step 2 - Extend Studio semantic-read consumption models
**What:** Teach Studio DTOs and semantic-read consumption code to accept the structural-anchor surface.
**How:** Update DTOs, transport mapping, and editor-side analysis models so the new structural metadata can flow from semantic read results into the gutter renderer without polluting `documentSymbols`.
**File(s):**
- Studio DTO and semantic-read integration modules, to be identified after schema finalization
- `prometeu-studio` editor integration points that consume semantic analysis results
### Step 3 - Make gutter rendering anchor-aware
**What:** Upgrade the gutter renderer to use exact structural anchors when available.
**How:** Adapt the active indicator renderer so guide start/end/cap placement uses structural-anchor metadata rather than symbol-line midpoint approximations.
The implementation must preserve the DEC-0014 rule that structural anchors are the canonical source of exact positioning.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorDocumentScopeGuideGraphicFactory.java`
- associated editor model or adapter layers introduced to consume structural anchors
### Step 4 - Add anchor-aware contract and rendering tests
**What:** Add tests covering transport, interpretation, and rendering of structural anchors.
**How:** Introduce tests that prove:
- structural-anchor payloads are emitted by frontend semantic read;
- Studio receives and stores them separately from `documentSymbols`;
- exact opening/closing anchor positions drive rendering behavior;
- languages with non-brace structure can still map into the generic contract.
**File(s):**
- frontend semantic-read tests
- Studio DTO/transport tests
- editor model and renderer tests
## Test Requirements
### Unit Tests
- Payload schema mapping tests.
- Editor adapter/model tests for anchor interpretation.
- Renderer tests for exact start/end placement using anchor positions.
### Integration Tests
- End-to-end semantic-read tests from frontend producer to Studio consumer when an existing harness supports that boundary.
### Manual Verification
- Open representative nested documents after structural anchors are available.
- Confirm that guide start/end visually align with structural anchor positions rather than line midpoints.
- Confirm that the active indicator model remains limited to `activeContainer` and `activeScope`.
## Acceptance Criteria
- [x] Frontend semantic-read payloads expose structural anchors through a dedicated semantic surface.
- [x] Studio consumes structural anchors without overloading `documentSymbols`.
- [x] Exact guide positioning uses structural-anchor metadata when available.
- [x] Tests cover payload transport, anchor interpretation, and anchor-aware rendering.
## Dependencies
- Accepted decision `DEC-0014-studio-editor-active-scope-and-structural-anchors.md`
- Accepted spec work derived from `PLN-0031`
- Studio editor wave-1 implementation from `PLN-0030` if shared gutter machinery is reused
## Risks
- Frontend payload evolution may require coordinated versioning or backwards-compatibility handling.
- Test fixtures may become brittle if the structural-anchor schema is not stabilized before implementation starts.
- Exact rendering behavior may vary with font metrics and paragraph layout, requiring robust assertions that test semantic placement rather than pixel-perfect incidental details.
@@ -1,103 +0,0 @@
---
id: PLN-0033
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Inline hint specification and contract propagation
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [studio, editor, specs, inline-hints, lsp, frontend-contract]
---
## Objective
Propagate DEC-0015 into the normative specification surfaces that define editor responsibilities, LSP semantic-read transport, and compiler/frontend contract authority for inline hints.
## Background
DEC-0015 locks inline hints as a host-generic editor capability with frontend-defined payloads, LSP-enforced transport, Studio rendering, decorative-only interaction, and partial-degradation preservation. No implementation plan may weaken those rules by inference.
The repository already has normative surfaces for editor behavior, semantic-read transport, and frontend-owned semantic contracts. Those surfaces must be updated before implementation splits across LSP, PBS, and Studio code.
## Scope
### Included
- Propagate DEC-0015 to Studio editor specs.
- Propagate DEC-0015 to integrated semantic-read specs.
- Extend compiler/frontend contract language where needed so frontend-owned hint metadata has a stable authority surface.
- Define the normative distinction between transitional approximation and final inline rendering.
### Excluded
- LSP DTO implementation.
- PBS hint payload production.
- Studio rendering code.
## Execution Steps
### Step 1 - Update the Code Editor workspace specification for inline hint rendering
**What:** Add normative editor requirements for decorative inline hints, host responsibilities, and inline-real final rendering.
**How:** Update the Studio Code Editor specification to state that:
- inline hints are host-generic editor capabilities;
- hint content remains frontend-owned;
- the editor renders but does not invent hints;
- hints are decorative only and do not alter text, selection, caret movement, or persistence;
- a transitional approximate stage may exist only as an explicit rollout step;
- the final completed capability is real inline rendering.
**File(s):**
- `docs/specs/studio/5. Code Editor Workspace Specification.md`
### Step 2 - Update the semantic-read phase specification for inline hint transport
**What:** Define inline hint transport as part of the semantic-read contract.
**How:** Update the semantic-read specification so it normatively states:
- inline/inlay hints are frontend-owned semantic payloads transported through `prometeu-lsp`;
- LSP owns the DTO and transport contract but not hint semantics;
- valid hint spans must survive partial degradation;
- the transport must preserve deterministic anchor information needed by Studio rendering.
**File(s):**
- `docs/specs/studio/7. Integrated LSP Semantic Read Phase Specification.md`
### Step 3 - Update compiler/frontend contract authority for frontend-owned hint metadata
**What:** Extend the compiler/frontend contract language so frontend-owned editor hint metadata has an explicit authority surface parallel to semantic presentation.
**How:** Update the compiler entrypoint/frontend contract specification to state that `FrontendSpec` or an equivalent accepted frontend-owned semantic contract surface remains the canonical source for static hint contract metadata when such metadata is required by downstream consumers.
The text must not imply Studio-owned or LSP-owned semantic hint policy.
**File(s):**
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
## Test Requirements
### Unit Tests
- Not applicable for this spec-only plan.
### Integration Tests
- Not applicable for this spec-only plan.
### Manual Verification
- Review the updated specs against DEC-0015 and confirm all normative points are represented.
- Confirm the final-state requirement still says inline real rendering.
- Confirm the specs do not give Studio authority over hint existence or content.
## Acceptance Criteria
- [x] Studio editor specs define inline hints as decorative, host-generic, and final-state inline real.
- [x] Semantic-read specs define frontend-owned hint transport and partial-degradation preservation.
- [x] Compiler/frontend contract language preserves frontend ownership of hint semantics.
- [x] The specification set is sufficient for code plans without reopening DEC-0015.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- Existing Studio and compiler specifications.
## Risks
- Under-specifying the contract may force DTO churn later.
- Overloading existing semantic presentation wording may blur the distinction between static presentation metadata and dynamic hint payload transport.
@@ -1,107 +0,0 @@
---
id: PLN-0034
ticket: studio-editor-inline-type-hints-for-let-bindings
title: LSP inline hint transport contract
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [lsp, studio, editor, inline-hints, dto, transport]
---
## Objective
Implement the LSP transport contract that enforces and delivers frontend-owned inline hint payloads to Studio consumers.
## Background
DEC-0015 requires the LSP to fix and transport the inline hint contract while preserving frontend ownership of hint content and anchor semantics. The Studio must consume transported hints mechanically, and valid spans must survive partial degradation.
Current LSP surfaces carry diagnostics, symbols, structural anchors, and semantic highlighting, but no dedicated inline hint payload.
## Scope
### Included
- Add a dedicated inline hint DTO/message surface to `prometeu-lsp-api`.
- Extend semantic session and analyze-result transport to include inline hint payloads.
- Ensure partial valid hints survive transport even when analysis is partially degraded.
- Add LSP tests for contract shape and partial preservation.
### Excluded
- Frontend production of hint payloads.
- Studio rendering.
- Final editor substrate changes.
## Execution Steps
### Step 1 - Define public DTOs for inline hint payloads
**What:** Add public API DTOs/messages for inline hint transport.
**How:** Introduce explicit payload shapes in `prometeu-lsp-api` that cover at minimum:
- anchor location or anchor span;
- display text;
- optional semantic category/styling fields if required by the contract;
- enough information for decorative-only host rendering.
The contract must remain frontend-content-preserving and must not encode Studio-owned hint policy.
**File(s):**
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/dtos/`
- `prometeu-lsp/prometeu-lsp-api/src/main/java/p/studio/lsp/messages/`
### Step 2 - Extend semantic session construction and analyze responses
**What:** Make `prometeu-lsp-v1` collect and return inline hints in the semantic-read result.
**How:** Update semantic session building and analyze-result assembly so inline hints are returned alongside diagnostics, symbols, structural anchors, and semantic highlights.
Transport must preserve valid hint payloads even if some hint production fails locally elsewhere in the same document.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticReadPhase.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/LspSemanticAnalyseService.java`
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/messages/`
### Step 3 - Add transport contract tests
**What:** Lock the LSP contract behavior with focused tests.
**How:** Add tests that verify:
- analyze responses can carry inline hints;
- hint payloads preserve anchors and text deterministically;
- valid hints survive partial degradation;
- no host-owned inference is inserted by the LSP when the frontend does not publish hints.
**File(s):**
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/`
- `prometeu-lsp/prometeu-lsp-api/src/test/java/` if DTO/API conformance tests are needed
## Test Requirements
### Unit Tests
- DTO invariants for inline hint payloads.
- Session/result assembly tests for non-empty and empty hint payloads.
### Integration Tests
- Analyze-document tests covering partial valid hints under degraded analysis.
### Manual Verification
- Inspect serialized/analyzed LSP results for a PBS document with inferred `let` types.
- Confirm no hint appears when the frontend publishes none.
## Acceptance Criteria
- [x] `prometeu-lsp-api` exposes a dedicated inline hint transport contract.
- [x] `prometeu-lsp-v1` returns inline hints through analyze results without inventing content.
- [x] Partial valid hints survive transport under degraded analysis.
- [x] Tests lock the contract shape and preservation rules.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
## Risks
- DTO under-design may force churn once Studio rendering starts.
- Folding inline hints into an existing message surface without clear boundaries may create avoidable API ambiguity.
@@ -1,110 +0,0 @@
---
id: PLN-0035
ticket: studio-editor-inline-type-hints-for-let-bindings
title: PBS inline type hint payload production
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [compiler, pbs, inline-hints, type-inference, lsp]
---
## Objective
Produce frontend-owned inline hint payloads for PBS inferred local bindings, starting with `let` bindings whose types are omitted in source.
## Background
DEC-0015 explicitly leaves hint eligibility frontend-owned. The initial user need comes from PBS inferred `let` bindings, and PBS already computes the inferred type during flow analysis. That semantic fact now needs to be surfaced as frontend-produced hint payload rather than remaining internal-only analysis state.
## Scope
### Included
- Surface PBS-produced inline type hints for inferred `let` bindings.
- Reuse existing flow-analysis type information rather than adding parallel inference.
- Preserve valid hints under partial degradation wherever the frontend can still produce them.
- Add PBS/LSP-facing tests for hint eligibility and payload correctness.
### Excluded
- Host rendering policy.
- Non-PBS frontend hint production.
- Hint categories not chosen by PBS.
## Execution Steps
### Step 1 - Identify stable anchor and payload sources in PBS analysis
**What:** Determine the exact PBS semantic source for inferred binding type and anchor location.
**How:** Trace `let` analysis through the PBS flow-analysis pipeline and identify:
- where inferred local binding type becomes stable;
- how to render that type as display text;
- which source position should anchor the hint;
- what happens when the binding has explicit type text and therefore should not receive an inferred-type hint.
This step must avoid recomputing types outside the existing semantic pipeline.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/`
### Step 2 - Emit frontend-owned hint payloads for eligible bindings
**What:** Make PBS produce inline hint payloads for eligible inferred bindings.
**How:** Extend the PBS semantic-read production path so it emits frontend-owned hint entries for `let` bindings with omitted type syntax and stable inferred type results.
The production path must:
- suppress hints when PBS does not want one;
- avoid emitting hints for explicitly typed bindings;
- preserve valid hints even if unrelated parts of the document degrade.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/`
- any accepted frontend semantic contract surface used by `prometeu-lsp`
### Step 3 - Add PBS-focused hint production tests
**What:** Lock PBS hint policy and payload behavior with tests.
**How:** Add tests for:
- inferred `let` bindings receiving hints;
- explicit `let name: Type = ...` bindings receiving no inferred-type hint;
- payload text stability for scalar, struct, optional, result, tuple, or other supported type forms chosen by PBS;
- partial-degradation cases where unaffected bindings still produce hints.
**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/`
- `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/` where end-to-end analyze assertions are required
## Test Requirements
### Unit Tests
- PBS semantic tests for inferred binding hint eligibility.
- Type-surface formatting tests if payload display text is factored into a helper.
### Integration Tests
- LSP analyze tests verifying PBS-produced hints appear in transported results.
- Partial-degradation tests preserving unaffected hints.
### Manual Verification
- Open a PBS document with inferred `let` bindings and inspect the LSP analyze payload.
- Confirm no hints appear for explicit type annotations.
## Acceptance Criteria
- [ ] PBS produces frontend-owned inline hint payloads for eligible inferred `let` bindings.
- [ ] Explicitly typed bindings do not receive inferred-type hints.
- [ ] Valid hints survive unrelated local degradation when PBS can still analyze those bindings.
- [ ] Tests lock the frontend-owned eligibility policy.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
- `PLN-0034-lsp-inline-hint-transport-contract.md`
## Risks
- If inferred-type display text is not normalized, hint output may become unstable across equivalent semantic forms.
- If hint production is attached too late in the pipeline, degraded documents may lose more valid hints than necessary.
@@ -1,127 +0,0 @@
---
id: PLN-0036
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Studio inline hint rendering and rollout
status: done
created: 2026-04-03
completed: 2026-04-03
tags: [studio, editor, inline-hints, rendering, rollout, richtextfx]
---
## Objective
Implement the Studio host rendering path for transported inline hints, including any explicit transitional stage and convergence to real inline rendering.
## Background
DEC-0015 requires the final user-visible capability to be real inline rendering in the editor flow. A transitional approximate stage is allowed only if explicitly treated as a rollout stage and not as the final architecture. Hints must remain decorative and must survive partial valid spans under degraded analysis.
The current editor uses `CodeArea` with `StyleSpans`, gutter graphics, and semantic overlays, which is sufficient for color and gutter behavior but not obviously sufficient for true inline non-text decorations without substrate work.
## Scope
### Included
- Add a Studio host rendering path for transported inline hints.
- Preserve decorative-only behavior.
- Preserve valid hints under partial degradation.
- If needed, implement an explicit transitional rendering wave and a follow-up convergence step to real inline rendering.
- Add editor tests for rendering behavior and document-model isolation.
### Excluded
- Frontend hint eligibility policy.
- LSP transport contract design.
- Non-editor consumers of hint payloads.
## Execution Steps
### Step 1 - Evaluate and choose the editor substrate for real inline rendering
**What:** Determine the exact editor primitive needed to support true inline hint rendering.
**How:** Evaluate the current `CodeArea`-based surface and decide whether real inline hints can be supported by extension or require a migration to a richer editor substrate.
This step must explicitly document:
- why the chosen substrate can satisfy the decision;
- whether a transitional approximation is required;
- what migration path exists if the current substrate is insufficient.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- any editor utility or custom rendering surfaces introduced by the chosen approach
### Step 2 - Implement decorative host rendering for transported hints
**What:** Render LSP-transported hints in the editor without mutating document text.
**How:** Add a host rendering layer that:
- consumes inline hint payloads from analyze results;
- renders them at deterministic anchors;
- keeps them out of the persisted text model;
- keeps caret, selection, copy/paste, and editing semantics text-only.
If a transitional approximation is required, it must be explicitly isolated and labeled as wave 1 rather than as final architecture.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/`
- `prometeu-studio/src/main/resources/themes/` if hint-specific host styling is needed
### Step 3 - Converge to real inline rendering if wave 1 is approximate
**What:** Ensure the implementation reaches the decision-mandated final state.
**How:** If step 2 introduces an approximate rendering wave, add the explicit follow-up work needed to move to true inline rendering and retire the approximation.
This convergence work must not be left implicit.
**File(s):**
- the same editor rendering surfaces chosen in steps 1 and 2
### Step 4 - Add Studio rendering and interaction tests
**What:** Lock decorative behavior and partial-degradation rendering in Studio tests.
**How:** Add tests that verify:
- hints render when transported;
- hints do not modify the text buffer;
- hints do not become part of copy/paste semantics;
- valid hints remain visible even when only some hint spans are available;
- the final path uses real inline rendering once the convergence step is complete.
**File(s):**
- `prometeu-studio/src/test/java/p/studio/workspaces/editor/`
## Test Requirements
### Unit Tests
- Rendering-layer tests for anchor mapping and decorative-only behavior.
- Tests ensuring text buffer content remains unchanged.
### Integration Tests
- Editor tests consuming analyze results with inline hints.
- Partial-degradation tests preserving valid hint spans.
- Convergence tests for the final inline-real path if a transitional wave exists.
### Manual Verification
- Open a PBS file with inferred `let` bindings and confirm hints render next to the binding without entering the file text.
- Confirm cursor movement and copy/paste ignore hint text.
- Confirm partially valid hints remain visible when some bindings fail analysis.
## Acceptance Criteria
- [ ] Studio can render transported inline hints without mutating document text.
- [ ] Decorative-only interaction rules are enforced.
- [ ] Partial valid hints remain visible under degraded analysis.
- [ ] If a transitional approximation exists, the path to real inline rendering is explicitly implemented and not left as implied follow-up.
## Dependencies
- Accepted decision `DEC-0015-studio-editor-inline-type-hints-contract-and-rendering-model.md`
- `PLN-0033-inline-hint-spec-and-contract-propagation.md`
- `PLN-0034-lsp-inline-hint-transport-contract.md`
- `PLN-0035-pbs-inline-type-hint-payload-production.md`
## Risks
- The current editor substrate may not support inline-real rendering cleanly without deeper refactoring.
- A temporary approximation may linger unless the convergence step is explicitly tracked and executed.
- Decorative behavior may be accidentally violated if the rendering layer leaks into text model operations.
@@ -1,175 +0,0 @@
---
id: PLN-0040
discussion: DSC-0021
decision: DEC-0019
ticket: studio-frontend-editor-write-and-save-wave
title: Implement the frontend editor write and save wave through VFS ownership
status: done
created: 2026-04-04
updated: 2026-04-04
owner: studio
tags: [studio, editor, frontend, write, save, vfs, lsp, pbs, access-policy]
---
## Briefing
Implement the accepted frontend write wave for the Studio Code Editor.
Frontend editing and frontend save must be released together, must remain owned by `prometeu-vfs`, and must be consumed by Studio UI without introducing a new immediate LSP implementation wave.
## Objective
Move frontend-scoped supported files from hard `read-only` to VFS-owned editable/saveable documents while preserving the current boundary:
- `prometeu-vfs` owns document state and persistence;
- `prometeu-lsp` remains a semantic consumer of VFS-backed snapshots;
- Studio UI remains a policy consumer.
## Dependencies
- `DEC-0019` Enable Frontend Editing and Save in the Studio Code Editor
- existing `prometeu-vfs` editable snapshot and save model for non-frontend textual documents
- existing Studio editor consumption of VFS access mode and save behavior
- existing semantic-read seam where `prometeu-lsp` reads VFS-backed frontend snapshots
## Scope
- propagate the new FE write/save contract into Studio and VFS specs
- extend `prometeu-vfs` so frontend-scoped supported files become editable/saveable
- keep FE writable snapshots, dirty tracking, and save ownership inside VFS
- update Studio editor behavior to consume FE editability from VFS
- update FE write/save tests in VFS and Studio
## Non-Goals
- any new LSP feature implementation wave
- per-file FE access policy
- partial FE draft mode without save
- moving persistence logic into Studio UI
- moving persistence logic into `prometeu-lsp`
## Execution Method
### 1. Propagate the accepted contract into specs
Update the Studio specs that still describe FE files as hard `read-only` so they now describe the new FE write/save wave and preserve VFS ownership plus semantic-consumer-only LSP ownership.
Targets:
- `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`
### 2. Change FE access policy in `prometeu-vfs`
Update the filesystem-backed VFS classification so frontend-scoped supported files become `EDITABLE` rather than `READ_ONLY`, while preserving frontend classification itself.
What changes:
- document kind classification for FE files
- VFS acceptance of FE `updateDocument`
- VFS save/save-all behavior for FE snapshots
- FE dirty tracking semantics under the same VFS owner model already used for editable non-frontend documents
Targets:
- `prometeu-vfs/prometeu-vfs-v1/src/main/java/p/studio/vfs/FilesystemVfsProjectDocument.java`
- any supporting VFS API contracts if required by the implementation
Dependency ordering:
- this step must land before Studio editor UX changes so the UI can consume the new policy rather than invent it.
### 3. Update VFS tests for FE edit/save behavior
Replace tests that assert FE hard `read-only` behavior with tests that assert:
1. FE documents open as frontend documents with `EDITABLE` access mode;
2. FE documents accept `updateDocument`;
3. FE documents save correctly through `saveDocument`;
4. FE documents participate correctly in `saveAllDocuments`.
Targets:
- `prometeu-vfs/prometeu-vfs-v1/src/test/java/p/studio/vfs/FilesystemVfsProjectDocumentTest.java`
### 4. Propagate FE editability into the Studio editor
Update the Studio editor to consume the new FE access mode from VFS exactly as it already does for editable non-frontend documents.
What changes:
- FE tabs become editable when VFS reports `EDITABLE`
- FE warning surfaces that are specific to hard `read-only` FE behavior must be revised or removed
- editor save/save-all enablement must work for dirty FE buffers through the existing VFS-backed flow
- no FE-local persistence path may be introduced
Targets:
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorWorkspace.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/editor/EditorStatusBar.java`
- any FE-warning or editor-session support classes affected by access-mode transition
Dependency ordering:
- this step depends on VFS access-mode propagation from Step 2.
### 5. Keep LSP integration stable without opening new implementation scope
Verify that the existing editor and semantic-read flow still calls `prometeu-lsp` as a consumer of FE snapshots, but do not introduce a new LSP implementation wave.
What changes:
- only compatibility adjustments that are strictly necessary because FE snapshots are now editable may be made;
- no new semantic features, refresh model, or ownership expansion is authorized here.
Targets:
- only the minimum compatibility surface if compilation or existing tests require it
Dependency ordering:
- this is verification-oriented and should follow the VFS/editor write changes.
### 6. Update Studio tests for FE editable/saveable behavior
Add or revise editor tests so they assert FE files are no longer treated as permanently hard `read-only` once VFS grants FE `EDITABLE` access mode.
Targets:
- Studio editor tests under `prometeu-studio/src/test/java/p/studio/workspaces/editor/...`
- any session/editor tests affected by FE access-mode transition
## Acceptance Criteria
1. Frontend-scoped supported files open through VFS with `EDITABLE` access mode.
2. Frontend-scoped supported files can be updated and saved through VFS-owned snapshots.
3. Studio editor FE tabs become editable only because VFS reports them as editable.
4. FE save and save-all route through the same VFS owner path used by other editable documents.
5. No new persistence or access-policy ownership moves into Studio UI.
6. No new persistence or access-policy ownership moves into `prometeu-lsp`.
7. Specs no longer describe FE files as hard `read-only` for the current wave.
## Tests
- VFS tests for FE access mode, update, save, and save-all
- Studio editor tests for FE editable/saveable behavior
- regression tests that confirm non-frontend editable documents still behave correctly
- compile/test verification that existing LSP consumer seams still pass without opening new LSP feature scope
## Affected Artifacts
- `discussion/workflow/decisions/DEC-0019-studio-frontend-editor-write-and-save-wave.md`
- `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/...`
- Studio editor tests
## Risks
- existing specs and tests currently encode the old hard `read-only` FE contract and will fail until all propagation lands coherently
- FE warning/UI surfaces may assume old read-only semantics in more than one place
- LSP snapshot consumption could reveal hidden assumptions about FE immutability even without opening a new LSP scope
- if implementation order is reversed and Studio is changed before VFS policy, UI code may drift into local heuristics