Studio with hint decorators

This commit is contained in:
2026-04-03 11:20:08 +01:00
parent f368ed94d2
commit e8ec9973cd
4 changed files with 306 additions and 1 deletions
@@ -0,0 +1,160 @@
---
id: DEC-0015
ticket: studio-editor-inline-type-hints-for-let-bindings
title: Studio Editor Inline Type Hints Contract and Rendering Model
status: accepted
created: 2026-04-03
accepted: 2026-04-03
agenda: AGD-0018
plans: [PLN-0033, PLN-0034, PLN-0035, PLN-0036]
tags: [studio, editor, inline-hints, inlay-hints, lsp, frontend-contract, type-inference]
---
## Decision
O Studio SHALL support inline type hints as a first-class editor capability rather than as a PBS-only exception.
The ownership model for the capability is normatively locked as follows:
- the frontend MUST define which hints exist, where they anchor, and what semantic payload they carry;
- the LSP MUST define and enforce the transport contract for those hints and MUST transport frontend-produced hint data to the Studio consumer;
- the Studio MUST render transported hints and MUST NOT invent frontend hint content on its own.
The final user-visible form of the feature MUST be real inline rendering inside the editor flow.
Any approximate visual solution MAY be used only as a transitional implementation stage and MUST be explicitly treated as an intermediate rollout step rather than as the final contract.
Inline hints produced under this capability MUST be decorative only.
Inline hints MUST NOT:
- mutate document text;
- participate as document content in copy/paste;
- redefine selection semantics;
- redefine caret movement semantics;
- become part of the persisted file model.
When analysis is partially degraded, the Studio MUST preserve and render hint spans that remain valid under the transported contract rather than disabling all hints for the whole document.
The host policy for what receives hints is frontend-owned.
If a frontend publishes valid hints under the LSP contract, the Studio MUST render them.
If a frontend does not publish a hint for a construct, the Studio MUST NOT synthesize one.
## Rationale
This decision separates semantic ownership from host rendering responsibility in the same disciplined way already adopted for frontend semantic presentation.
The chosen split avoids two failure modes:
1. Studio-owned hint content, which would duplicate frontend semantics and make the editor a second semantic authority;
2. frontend-specific rendering logic inside the Studio host, which would make the editor harder to generalize and maintain.
The decision also prevents a common product regression: shipping an approximate overlay and silently letting it become the permanent implementation.
By locking inline real rendering as the required final state, the repository preserves the intended UX target while still allowing phased execution.
Decorative-only hints keep the document model stable and avoid corrupting editing semantics.
Partial degradation tolerance follows the same operational direction already desired for editor highlighting: valid local semantic signal should survive even when the full-document analysis path is degraded.
## Technical Specification
### 1. Capability Model
The editor hint system MUST be implemented as a host capability named conceptually equivalent to inline or inlay hints.
That capability MUST be host-generic and MUST NOT be modeled as a PBS-only feature.
### 2. Ownership Boundary
Frontend responsibilities:
- define whether a hint exists;
- define the semantic meaning of the hint;
- define the anchor location or anchor span;
- define the payload required for rendering, including display text and any semantic category needed by the contract.
LSP responsibilities:
- define the DTO and transport contract consumed by the Studio;
- validate and transport frontend-produced hint payloads;
- preserve enough anchoring information for deterministic host rendering;
- avoid inventing host-owned semantic meaning not present in frontend-produced hint data.
Studio responsibilities:
- render transported hints;
- apply host styling and layout behavior;
- keep hints visually separate from document text;
- preserve editor document semantics and editing behavior.
### 3. Content Policy
The Studio MUST treat hint presence as frontend-authoritative.
The Studio MUST render valid transported hints regardless of the frontend that produced them.
The Studio MUST NOT hardcode rules such as:
- hint all `let` declarations by host policy;
- suppress frontend-provided hints because the host prefers a different policy;
- create fallback semantic hints not present in the contract.
### 4. Rendering Model
The feature is only considered complete when hints are rendered inline in the editor flow as non-textual host decorations attached to document positions.
An approximate visual stage MAY exist temporarily if needed to de-risk delivery, but:
- it MUST be documented as transitional;
- it MUST NOT redefine the final contract;
- subsequent plans MUST converge explicitly to real inline rendering.
### 5. Interaction Model
Hints are decorative only.
Therefore the implementation MUST ensure:
- persisted source text remains unchanged;
- selection ranges are computed over document text only;
- caret movement is computed over document text only;
- copy/paste operates on document text only;
- hint visibility does not alter the canonical file buffer.
### 6. Partial Degradation
When semantic analysis yields only partial valid hint data:
- valid hint spans MUST continue to render;
- invalid or missing spans MAY be omitted locally;
- the Studio MUST NOT disable all hints for the entire document solely because some hint spans could not be produced.
### 7. Initial Scope
This decision is initiated by the PBS need to show inferred type hints for local bindings such as `let`.
However, this decision does not lock hint eligibility to `let`.
Eligibility remains frontend-owned under the contract above.
### 8. Propagation Targets
This decision MUST be propagated to:
- Studio editor specifications covering editor rendering and semantic read surfaces;
- LSP specifications or contracts covering semantic transport payloads;
- implementation plans for frontend hint payload production, LSP transport, and Studio rendering;
- tests covering decorative behavior, anchor stability, partial degradation, and frontend-owned hint policy.
## Constraints
- No implementation plan may reinterpret Studio as semantic owner of hint content.
- No implementation plan may treat an approximate overlay as the final shipped architecture.
- No implementation plan may allow hints to become part of the editable document text model.
- If a later plan discovers that the current editor substrate cannot support inline real rendering cleanly, that plan MUST surface the substrate limitation explicitly and propose the required editor primitive or migration path rather than silently downgrading the final requirement.
## Revision Log
- 2026-04-03: Initial accepted decision from AGD-0018.