128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
---
|
|
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.
|