Docs rewrite

content/docs/internals/position-mapping.mdx

@@ -0,0 +1,31 @@
+---
+title: Position Mapping
+description: Bidirectional mapping between Mist source positions and Rust output positions for error remapping and LSP features.
+icon: Map
+---
+
+Mist maintains a bidirectional mapping between Mist source positions and Rust output positions. This is essential for:
+
+1. **Error remapping** — Rust compiler errors point to the correct Mist source location
+2. **LSP features** — Go-to-definition, hover, and completion work from Mist source
+
+### Data Structure
+
+The mapping is stored as pairs:
+
+```rust
+pub struct Mapping {
+    pub mist_path: PathBuf,
+    pub map: HashSet<(RustMap, MistMap)>,
+}
+```
+
+- `RustMap(usize, usize)` — line/column in generated Rust
+- `MistMap(usize, usize)` — line/column in original Mist
+
+### Mapping Lifecycle
+
+1. **Codegen** — Each `Spanned<T>` AST node records its Mist position and the current Rust position in the codegen output buffer via `GenSpanTranslation`
+2. **Persistence** — The mapping is serialized to `<output>.map.json` alongside the transpiled `.rs` output
+3. **Build-time remapping** — The builder reads `.map.json` to remap `cargo` diagnostics back to Mist positions
+4. **LSP remapping** — Both Mist→Rust and Rust→Mist direction queries are supported via `find()` and `find_by_mist()`