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