Position Encoding

Position Encoding & Path Normalization Reference

Typed Span Types (verter_span crate)

All Rust span types are defined in crates/verter_span/src/lib.rs. Each type enforces a specific coordinate system at compile time:

Typed LSP / generated-TSX coordinate wrappers

Intra-process boundary newtypes (also in verter_span, no serde) used by the LSP PositionMapper and cross-file navigation stack. No From between source-side and generated-side types (no From<GeneratedByteRange> for SourceByteRange); LspPosition/TsPosition are distinct so a TSX position can never be passed where a Vue LSP position is expected.

Typed Span Rules

1. All data crossing a serialization boundary (serde, MCP, LSP custom protocol, FFI) MUST use Span (SFC-absolute). RelativeSpan, PartialGeneratedSpan, GeneratedSpan don't implement Serialize/Deserialize — putting them in a serializable struct is a compile error. Convert with to_absolute(base) before serialization.
2. Inter-crate stored types prefer Span. Analysis snapshots, host results, diagnostic structs crossing crate boundaries use Span. RelativeSpan is intra-crate only (CSS scanner, OXC binding extraction).
3. RelativeSpan is 8 bytes, same as Span. Base offset lives in context (field on parent struct, function parameter). Value is compile-time type safety, not runtime data.
4. PartialGeneratedSpan → GeneratedSpan via resolution. Use PartialGeneratedSpan for raw TSGO byte offsets. After PositionMapper resolves SFC origin, use partial.resolve(origin_span) to get GeneratedSpan. For display use generated_span.origin.
5. PositionMapper is a STRICT in-run mapper (crates/verter_lsp/src/documents/position_map.rs). tsx_to_vue(TsPosition) -> Option<SourceMapped> and vue_to_tsx(LspPosition) -> Option<GeneratedMapped> return Some only when the query lies strictly inside ONE mapped token's run (the next token on the line starts strictly after the query). No cross-token extrapolation, no snap-to-closest-preceding fallback — unmapped/synthetic content (_ctx./$setup. prefixes), gaps, or bridging into the next token return None. Within-run character precision IS preserved (in-run offset added to the run's mapped start), but only inside a single mapped run. A range maps only when BOTH endpoints resolve inside the SAME compatibility component — runs are pre-labelled at construction with a component_id; two runs share an id only when linked by an unbroken chain of runs contiguous in BOTH generated AND source space (same-line adjacency, or the multiline line-wrap equivalent). Generated-side adjacency alone is NOT sufficient: generated output relocates/repeats source (MoveOriginal, repeated v-model emission), so two generated-adjacent but source-discontiguous runs are DIFFERENT components and do not compose — runs_compatible is then an O(1) component_id comparison. Endpoints are therefore coupled (same component), never mapped independently. Guard: crates/verter_lsp/tests/cases/position_mapper_strict.rs (behavioural — including the generated-adjacent-but-source-discontiguous discriminator — + static ban_cross_token_extrapolation).

Key APIs

• Span::new(start, end) / RelativeSpan::new(start, end) / PartialGeneratedSpan::new(start, end)
• RelativeSpan::to_absolute(base: u32) -> Span — add base offset
• Span::to_relative(base: u32) -> RelativeSpan — subtract base offset
• PartialGeneratedSpan::resolve(origin: Span) -> GeneratedSpan — resolve with SFC origin
• GeneratedSpan::new(generated: Span, origin: Span) — create resolved mapping directly
• slice(&self, source: &str) -> &str — on Span, RelativeSpan, PartialGeneratedSpan
• From<oxc_span::Span> for both Span and RelativeSpan
• LspPosition::new(line, character) / TsPosition::new(line, character); SourceByteRange::new(..) / GeneratedByteRange::new(..) (typed LSP/TSX coordinate wrappers)
• No From conversions between span types, nor between source-side and generated-side coordinate wrappers — type safety enforced at compile time

CSS Variable Analysis Spans

All CSS variable span fields use SFC-absolute Span:

Spans computed as content_offset + local_offset during CSS scanning, where content_offset is SFC-absolute byte offset of <style> block content start. For script-side CssVarManipulation, spans come from OXC adjusted by script block's SFC offset.

Position Encoding Layers

Line/Column Base Rules (CRITICAL — off-by-one bugs)

• PositionResolver is 1-based (cursor/position.rs): offset_to_line_and_col() and offset_to_line_col() return (1-based line, 1-based column). Always subtract 1 before passing to source maps or LSP.
• Source maps are 0-based: VLQ segments use 0-indexed lines and columns.
• LSP is 0-based: Position { line: 0, character: 0 } is the first character.
• VS Code is 0-based: new Position(0, 0) is the first character.
• OXC/verter spans are byte offsets — no line/column, no base conversion needed.

LSP Position Encoding Negotiation

1. Server reads capabilities.general.positionEncodings from client during initialize()
2. Server picks best encoding: prefer UTF-8 (no conversion needed) > UTF-32 > UTF-16 > default UTF-16
3. Server announces selected encoding in ServerCapabilities.position_encoding
4. All LSP positions (standard and custom protocol) use the negotiated encoding

CRITICAL: The negotiated encoding MUST be used everywhere that produces LSP positions (diagnostics, hover ranges, completion positions, etc.). This includes SyncCoordinator which publishes diagnostics after typing stops — it shares the encoding via Arc<RwLock<PositionEncodingKind>> with the server. Default is UTF-16 (per LSP spec) until initialize() negotiates.

Rust-internal code should prefer UTF-8 byte offsets. LSP boundary code must convert to negotiated encoding. JS/VS Code always uses UTF-16.

Standard LSP positions (line:character): handled by LineIndex in documents/line_index.rs. Custom protocol data (analysis spans): converted at LSP boundary before serialization.

Two index shapes, one conversion implementation. verter_type_runtime::codec exposes an owning LineIndex (copies the source; for an index stored beyond the buffer's life, e.g. the per-document index in documents/mod.rs) and a borrowing SourceIndex<'a> (owns only the line-start table). Both delegate to the same private conversion core, so they cannot disagree about an encoding, a bound check, or a clamp. A caller converting more than one position against one immutable source — a diagnostic pull, a semantic-token stream, an inlay-hint or highlight batch, a rename/code-fix batch, a span's two endpoints — builds ONE SourceIndex and converts every endpoint through it; the per-call convenience functions rescan the source each time. A response whose endpoints span several target files (definition/references locations, rename and code-action edits) resolves each distinct target's content (snapshot, then disk) and indexes it once, through contents_snapshot::{with_target_index, convert_per_target}; results keep the response order.

Each index offers both conventions explicitly: clamped_position_to_offset fails OPEN (out-of-range clamps to EOF — the navigation-sentinel default) and checked_position_to_offset fails CLOSED (rejects a past-EOF line, a column past the line's end, and a column inside a surrogate pair). Edit-applying and secondary-link paths must use the checked converter; a clamped wrong offset corrupts a file or forges a bogus "see declaration" link at EOF.