docs: comprehensive documentation overhaul across all crates and packages

- Fix empty @srcmap/sourcemap index.d.ts with full TypeScript definitions
- Add READMEs for generator-wasm, remapping-wasm, symbolicate-wasm, trace-mapping
- Add READMEs for srcmap-scopes and srcmap-symbolicate crates
- Improve rustdoc on SourceMap, Mapping, OriginalLocation, GeneratedLocation,
  MappedRange, ParseError, SourceMapGenerator, and generator Mapping structs
- Fix rustdoc HTML tag warning in LazySourceMap comment
- Add test coverage for codec DecodeError Display, VLQ edge cases

Author: BartWaardenburg

crates/codec/src/lib.rs

@@ -373,4 +373,47 @@ mod tests {
             assert_eq!(sequential, parallel);
         }
     }
+
+    // --- DecodeError Display tests ---
+
+    #[test]
+    fn decode_error_display_invalid_base64() {
+        let err = DecodeError::InvalidBase64 {
+            byte: b'!',
+            offset: 2,
+        };
+        assert_eq!(err.to_string(), "invalid base64 character 0x21 at offset 2");
+    }
+
+    #[test]
+    fn decode_error_display_unexpected_eof() {
+        let err = DecodeError::UnexpectedEof { offset: 5 };
+        assert_eq!(err.to_string(), "unexpected end of input at offset 5");
+    }
+
+    #[test]
+    fn decode_error_display_overflow() {
+        let err = DecodeError::VlqOverflow { offset: 10 };
+        assert_eq!(err.to_string(), "VLQ value overflow at offset 10");
+    }
+
+    // --- Decode edge case: 5-field segment with name ---
+
+    #[test]
+    fn decode_five_field_with_name_index() {
+        // Ensure the name field (5th) is decoded correctly
+        let input = "AAAAC"; // 0,0,0,0,1
+        let decoded = decode(input).unwrap();
+        assert_eq!(decoded[0][0], vec![0, 0, 0, 0, 1]);
+    }
+
+    // --- Encode edge case: encode with only 1 line ---
+
+    #[test]
+    fn encode_single_segment_one_field() {
+        let mappings = vec![vec![vec![5_i64]]];
+        let encoded = encode(&mappings);
+        let decoded = decode(&encoded).unwrap();
+        assert_eq!(decoded, mappings);
+    }
 }

crates/codec/src/vlq.rs

@@ -353,4 +353,35 @@ mod tests {
         let err = vlq_decode_unsigned(b"", 0).unwrap_err();
         assert_eq!(err, DecodeError::UnexpectedEof { offset: 0 });
     }
+
+    #[test]
+    fn unsigned_decode_non_ascii() {
+        let err = vlq_decode_unsigned(&[0xC3, 0x80], 0).unwrap_err();
+        assert_eq!(
+            err,
+            DecodeError::InvalidBase64 {
+                byte: 0xC3,
+                offset: 0
+            }
+        );
+    }
+
+    #[test]
+    fn unsigned_decode_invalid_base64_char() {
+        let err = vlq_decode_unsigned(b"!", 0).unwrap_err();
+        assert_eq!(
+            err,
+            DecodeError::InvalidBase64 {
+                byte: b'!',
+                offset: 0
+            }
+        );
+    }
+
+    #[test]
+    fn unsigned_decode_overflow() {
+        // 14 continuation chars to trigger overflow
+        let err = vlq_decode_unsigned(b"ggggggggggggggA", 0).unwrap_err();
+        assert!(matches!(err, DecodeError::VlqOverflow { .. }));
+    }
 }

crates/generator/src/lib.rs

@@ -31,18 +31,41 @@ use srcmap_scopes::ScopeInfo;
 
 // ── Public types ───────────────────────────────────────────────────
 
-/// A mapping from generated position to original position.
+/// A mapping from a generated position to an original position.
+///
+/// Used with [`SourceMapGenerator`] to define position relationships.
+/// All positions are 0-based.
 #[derive(Debug, Clone)]
 pub struct Mapping {
+    /// 0-based line in the generated output.
     pub generated_line: u32,
+    /// 0-based column in the generated output.
     pub generated_column: u32,
+    /// Source index from [`SourceMapGenerator::add_source`], or `None` for generated-only.
     pub source: Option<u32>,
+    /// 0-based line in the original source.
     pub original_line: u32,
+    /// 0-based column in the original source.
     pub original_column: u32,
+    /// Name index from [`SourceMapGenerator::add_name`], or `None`.
     pub name: Option<u32>,
 }
 
 /// Builder for creating source maps incrementally.
+///
+/// Register sources and names first (they return indices), then add mappings
+/// that reference those indices. Mappings should be added in generated-position
+/// order, though the builder does not require it.
+///
+/// Sources and names are automatically deduplicated.
+///
+/// # Workflow
+///
+/// 1. [`add_source`](Self::add_source) — register each original file
+/// 2. [`set_source_content`](Self::set_source_content) — optionally attach content
+/// 3. [`add_name`](Self::add_name) — register identifier names
+/// 4. [`add_mapping`](Self::add_mapping) / [`add_named_mapping`](Self::add_named_mapping) — add mappings
+/// 5. [`to_json`](Self::to_json) — serialize to JSON
 #[derive(Debug)]
 pub struct SourceMapGenerator {
     file: Option<String>,
@@ -1224,6 +1247,76 @@ mod tests {
         );
     }
 
+    #[test]
+    fn set_source_content_out_of_bounds() {
+        let mut builder = SourceMapGenerator::new(None);
+        // No sources added, index 0 is out of bounds
+        builder.set_source_content(0, "content".to_string());
+        // Should silently do nothing
+        let json = builder.to_json();
+        assert!(!json.contains("content"));
+    }
+
+    #[test]
+    fn add_to_ignore_list_dedup() {
+        let mut builder = SourceMapGenerator::new(None);
+        let idx = builder.add_source("vendor.js");
+        builder.add_to_ignore_list(idx);
+        builder.add_to_ignore_list(idx); // duplicate - should be deduped
+        let json = builder.to_json();
+        // Should only appear once in ignoreList
+        let sm = srcmap_sourcemap::SourceMap::from_json(&json).unwrap();
+        assert_eq!(sm.ignore_list, vec![0]);
+    }
+
+    #[test]
+    fn to_decoded_map_with_source_root() {
+        let mut builder = SourceMapGenerator::new(None);
+        builder.set_source_root("src/".to_string());
+        let src = builder.add_source("app.ts");
+        builder.add_mapping(0, 0, src, 0, 0);
+        let sm = builder.to_decoded_map();
+        // Sources should be prefixed with source_root
+        assert_eq!(sm.sources, vec!["src/app.ts"]);
+    }
+
+    #[test]
+    fn json_escaping_special_chars() {
+        let mut builder = SourceMapGenerator::new(None);
+        let src = builder.add_source("a.js");
+        // Content with special chars: quotes, backslash, newline, carriage return, tab, control char
+        builder.set_source_content(src, "line1\nline2\r\ttab\\\"\x01end".to_string());
+        builder.add_mapping(0, 0, src, 0, 0);
+        let json = builder.to_json();
+        // Verify it's valid JSON by parsing
+        let sm = srcmap_sourcemap::SourceMap::from_json(&json).unwrap();
+        assert_eq!(
+            sm.sources_content,
+            vec![Some("line1\nline2\r\ttab\\\"\x01end".to_string())]
+        );
+    }
+
+    #[test]
+    fn json_escaping_in_names() {
+        let mut builder = SourceMapGenerator::new(None);
+        let src = builder.add_source("a.js");
+        let name = builder.add_name("func\"with\\special");
+        builder.add_named_mapping(0, 0, src, 0, 0, name);
+        let json = builder.to_json();
+        let sm = srcmap_sourcemap::SourceMap::from_json(&json).unwrap();
+        assert_eq!(sm.names[0], "func\"with\\special");
+    }
+
+    #[test]
+    fn json_escaping_in_sources() {
+        let mut builder = SourceMapGenerator::new(None);
+        let src = builder.add_source("path/with\"quotes.js");
+        builder.add_mapping(0, 0, src, 0, 0);
+        let json = builder.to_json();
+        let sm = srcmap_sourcemap::SourceMap::from_json(&json).unwrap();
+        assert_eq!(sm.sources[0], "path/with\"quotes.js");
+    }
+
     #[cfg(feature = "parallel")]
     mod parallel_tests {
         use super::*;

crates/scopes/README.md

@@ -0,0 +1,71 @@
+# srcmap-scopes
+
+[![crates.io](https://img.shields.io/crates/v/srcmap-scopes.svg)](https://crates.io/crates/srcmap-scopes)
+[![docs.rs](https://docs.rs/srcmap-scopes/badge.svg)](https://docs.rs/srcmap-scopes)
+
+Scopes and variables decoder/encoder for source maps ([ECMA-426](https://tc39.es/ecma426/)).
+
+Implements the "Scopes" proposal for source maps, enabling debuggers to reconstruct original scope trees, variable bindings, and inlined function call sites from generated code.
+
+## Usage
+
+```rust
+use srcmap_scopes::{
+    decode_scopes, encode_scopes, Binding, GeneratedRange,
+    OriginalScope, Position, ScopeInfo,
+};
+
+// Build scope info
+let info = ScopeInfo {
+    scopes: vec![Some(OriginalScope {
+        start: Position { line: 0, column: 0 },
+        end: Position { line: 5, column: 0 },
+        name: None,
+        kind: Some("global".to_string()),
+        is_stack_frame: false,
+        variables: vec!["x".to_string()],
+        children: vec![],
+    })],
+    ranges: vec![GeneratedRange {
+        start: Position { line: 0, column: 0 },
+        end: Position { line: 5, column: 0 },
+        is_stack_frame: false,
+        is_hidden: false,
+        definition: Some(0),
+        call_site: None,
+        bindings: vec![Binding::Expression("_x".to_string())],
+        children: vec![],
+    }],
+};
+
+// Encode to VLQ
+let mut names = vec!["global".to_string(), "x".to_string(), "_x".to_string()];
+let encoded = encode_scopes(&info, &mut names);
+
+// Decode back
+let decoded = decode_scopes(&encoded, &names, 1).unwrap();
+assert_eq!(decoded.scopes.len(), 1);
+```
+
+## Key types
+
+| Type | Description |
+|------|-------------|
+| `ScopeInfo` | Top-level container: original scopes + generated ranges |
+| `OriginalScope` | A scope in authored source code (tree structure) |
+| `GeneratedRange` | A range in generated output mapped to an original scope |
+| `Binding` | Variable binding: expression, unavailable, or sub-range bindings |
+| `CallSite` | Inlined function call site in original source |
+| `Position` | 0-based line/column pair |
+
+## How it works
+
+The scopes format uses tag-based VLQ encoding where each item is prefixed with a tag byte identifying the item type (scope start, scope end, range start, etc.) followed by flags and VLQ-encoded values. This enables efficient serialization of tree-structured scope and range data into a single flat string.
+
+## Part of [srcmap](https://github.com/BartWaardenburg/srcmap)
+
+Used by `srcmap-sourcemap` (decode) and `srcmap-generator` (encode). See the [main repo](https://github.com/BartWaardenburg/srcmap) for the full source map SDK.
+
+## License
+
+MIT