@@ -228,8 +228,118 @@ Environment metadata for source maps. The proposal is minimal at Stage 1 — tra
228228
229229---
230230
231+ ## Ecosystem Adoption
232+
233+ Based on integration testing across 21 projects. Prioritized by impact and dependency chains.
234+
235+ ### Adoption Phase 1: Ship What Already Works
236+
237+ ** Commit accumulated bug fixes** found during outreach testing:
238+ - Path normalization (` normalizePath() ` ) — matches jridgewell's ` resolve-uri ` behavior
239+ - WASM source name resolution through ` resolvedSources ` in ` originalPositionFor `
240+ - ` generatedPositionFor ` bias handling (GLB/LUB) and same-line constraint
241+ - ` allGeneratedPositionsFor ` LUB semantics and result sorting
242+ - Reverse index tie-breaking by generated position
243+ - Decoded mappings stride fix (6→7 for ` is_range_mapping ` )
244+ - ` SectionedSourceMapInput ` type and callable ` AnyMap ` type signature
245+ - Dual CJS/ESM exports for ` @srcmap/trace-mapping `
246+
247+ ** Publish ` @srcmap/trace-mapping ` v0.3.0** , then open PRs:
248+
249+ | Project | Stars | Downloads/wk | Test Results | Effort |
250+ | ---------| -------| -------------| --------------| --------|
251+ | v8-to-istanbul | 220 | ~ 8M (via c8/Jest) | 3/3 files, all snapshots match | ` package.json ` swap |
252+ | Jest | 44k | ~ 30M | 0 regressions (28 pre-existing) | ` package.json ` swap |
253+ | Vitest | 14k | ~ 10M | 600/600 files, 6582 tests | Swap + externalize WASM in 3 Rollup configs |
254+
255+ ### Adoption Phase 2: Wrapper Packages
256+
257+ Three wrapper packages unlock 10+ major projects:
258+
259+ ** ` @srcmap/source-map ` ** — Mozilla ` source-map ` v0.6 synchronous API compat
260+ - Already prototyped and validated (source-map-support: 33/33 tests pass)
261+ - ` SourceMapConsumer ` : constructor, ` originalPositionFor ` , ` generatedPositionFor ` , ` eachMapping ` , ` sourceContentFor `
262+ - Unlocks: ** Next.js** (130k), ** PostCSS** (29k), ** Terser** (9k), ** source-map-support** (3.3k)
263+
264+ ** ` @srcmap/remapping ` ** — ` @ampproject/remapping ` API compat
265+ - Default export accepting ` (input, loader) ` where input is string, object, or array
266+ - Unlocks: ** Vite** (71k), ** Angular CLI** (27k), ** Babel** (43k, also needs gen-mapping)
267+
268+ ** ` @srcmap/gen-mapping ` ** — ` @jridgewell/gen-mapping ` API compat
269+ - ` GenMapping ` constructor, ` maybeAddMapping ` , ` toEncodedMap ` , ` toDecodedMap ` , ` setSourceContent `
270+ - Unlocks: ** Babel** (43k)
271+
272+ ```
273+ trace-mapping v0.3 ──→ Jest PR (44k⭐)
274+ │ Vitest PR (14k⭐)
275+ │ v8-to-istanbul PR (220⭐, 8M dl/wk)
276+ │
277+ ├─→ @srcmap/source-map ──→ Next.js (130k⭐)
278+ │ Terser (9k⭐)
279+ │ source-map-support (3.3k⭐)
280+ │ PostCSS (29k⭐, needs applySourceMap too)
281+ │
282+ ├─→ @srcmap/remapping ───→ Vite (71k⭐)
283+ │ Angular CLI (27k⭐)
284+ │ Babel (43k⭐, needs gen-mapping too)
285+ │
286+ └─→ @srcmap/gen-mapping ─→ Babel (43k⭐)
287+ ```
288+
289+ Total ecosystem reach with Phase 1+2: ** ~ 434k GitHub stars** across 10 projects.
290+
291+ ### Adoption Phase 3: Rust Performance Gaps
292+
293+ These block adoption in Rust-native tools:
294+
295+ | Gap | Severity | Impact | Details |
296+ | -----| ----------| --------| ---------|
297+ | VLQ encoding 1.8x slower | High | OXC, SWC, Lightning CSS | Profile + optimize ` encode_vlq ` , consider SIMD/lookup-table |
298+ | Serialization 2.25x slower | Medium | Rspack | Pre-allocate output buffer, avoid intermediate allocations |
299+ | Composition 8x slower | High | Rolldown | Missing lookup table API for O(1) line/column access |
300+ | No structured SourceMap output | Medium | OXC | Export ` SourceMap ` struct with typed fields |
301+
302+ ### Adoption Phase 4: Extended APIs
303+
304+ | API | Effort | Unlocks |
305+ | -----| --------| ---------|
306+ | ` ConcatSourceMapBuilder ` (Rust) | Medium | OXC (13k) |
307+ | ` from_data_url() ` / ` to_data_url() ` (Rust) | Small | Lightning CSS (7k) |
308+ | ` fromSourceMap() ` / ` applySourceMap() ` (JS) | Medium | PostCSS (29k) |
309+ | WASM browser target (` --target web ` ) | Medium | Vitest browser, all browser tools |
310+
311+ ### Adoption Phase 5: Long-Term Strategic
312+
313+ | Target | Approach | Stars |
314+ | --------| ----------| -------|
315+ | Sentry CLI | Contribute improvements upstream to ` rust-sourcemap ` , or position for symbolicator | 2k |
316+ | Node.js runtime | Publish benchmarks → contribute algorithm improvements → WASM vendoring proposal | 110k |
317+ | Webpack | Add streaming API matching ` StreamChunksOfCombinedSourceMap ` pattern | 65k |
318+ | Metro | Low priority — needs multiple wrappers for custom source map extensions | 5.2k |
319+
320+ ### Adoption Priority Matrix
321+
322+ | Priority | Item | Effort | Impact |
323+ | ----------| ------| --------| --------|
324+ | ** P0** | Commit bug fixes + publish trace-mapping v0.3 | S | — |
325+ | ** P0** | PRs to Jest, Vitest, v8-to-istanbul | S | 58k⭐, 48M dl/wk |
326+ | ** P1** | ` @srcmap/source-map ` wrapper | M | 171k⭐ |
327+ | ** P1** | ` @srcmap/remapping ` wrapper | M | 141k⭐ |
328+ | ** P1** | WASM browser target | M | All browser tools |
329+ | ** P2** | ` @srcmap/gen-mapping ` wrapper | M | 43k⭐ |
330+ | ** P2** | VLQ encoding optimization | M | OXC+SWC+LightningCSS |
331+ | ** P2** | Data URL utilities | S | Lightning CSS (7k⭐) |
332+ | ** P3** | Serialization performance | M | Rspack (12k⭐) |
333+ | ** P3** | Composition performance + lookup table | L | Rolldown (20k⭐) |
334+ | ** P3** | Structured SourceMap type + ConcatBuilder | M | OXC (13k⭐) |
335+ | ** P3** | ` fromSourceMap ` /` applySourceMap ` | M | PostCSS (29k⭐) |
336+ | ** P4** | Node.js benchmarks, Webpack streaming, Metro, Sentry | L | Long-term |
337+
338+ Effort: ** S** = days, ** M** = 1-2 weeks, ** L** = 2+ weeks
339+
340+ ---
341+
231342## Non-goals
232343
233- - Full compatibility with the ` mozilla/source-map ` API surface
234344- Source map v1/v2 format support
235345- Tight coupling to any specific bundler or compiler
0 commit comments