prometeu-studio/discussion/workflow/plans/PLN-0036-studio-inline-hint-rendering-and-rollout.md

id	ticket	title	status	created	completed	tags
PLN-0036	studio-editor-inline-type-hints-for-let-bindings	Studio inline hint rendering and rollout	done	2026-04-03	2026-04-03	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.