---
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.