@i-scope/source-map-bridge

Part of the @i-scope/debugger SDK — one of seven leaf packages aggregated by the @i-scope/debugger meta-umbrella. Most users should install the meta (npm install @i-scope/debugger), which pulls in the DAP adapter and MCP server on top of this leaf. Install @i-scope/source-map-bridge directly only when you reuse the TS↔AJS translation in tooling that has nothing to do with a debug session — bundlers, linters, custom .ajs post-processors, language servers.

Bidirectional TypeScript ↔ AJS (Oscilloscope JScript) source-map manager.

Originally extracted from the iScope DAP adapter, where the same component serves both ends of the debug session:

• TS → AJS — translating a user-set breakpoint on a .ts line into the generated .ajs line the engine actually executes.
• AJS → TS — translating an engine-reported break / call-frame location back to its original .ts for display in the IDE.

Now packaged stand-alone so other tooling around the iScope platform (MCP servers, CLI inspectors, language-server-like helpers) can reuse the exact same translation logic.

Install

npm install @i-scope/source-map-bridge

Quick start

import { SourceMapManager } from '@i-scope/source-map-bridge';

const maps = new SourceMapManager({
    log: (msg) => console.error(msg),
});

await maps.loadFor('C:/proj/dist/bundle.ajs');

// TS -> AJS (used when installing a breakpoint)
const gen = await maps.toGenerated('C:/proj/src/app.ts', 42, 1);
// => { generatedPath: 'C:/proj/dist/bundle.ajs', line: 137, column: 1 }

// AJS -> TS (used when reporting a stack frame)
const orig = await maps.toOriginal({
    generatedPath: 'C:/proj/dist/bundle.ajs',
    line:          137,
    column:         1,
});
// => { originalPath: 'C:/proj/src/app.ts', line: 42, column: 1 }

What it understands

• Inline data URIs: //# sourceMappingURL=data:application/json;base64,...
• Sidecar maps: //# sourceMappingURL=bundle.ajs.map
• Implicit sidecars: no comment, but bundle.ajs.map next to bundle.ajs on disk.
• file:// and webpack:/// URL schemes inside sources[].
• Indexed maps (rare in practice — tsc / esbuild produce flat maps).
• Case-insensitive matching of sources[] on Windows.

Coordinate-system conventions

| Layer | Lines | Columns | |---|---|---| | DAP transport | 1-based | 1-based (when linesStartAt1=true, columnsStartAt1=true) | | Mozilla source-map library | 1-based | 0-based | | Engine (BreakHitEvent) | 1-based | 1-based (helper normalises to 1) |

This module is the choke point that converts the column convention — all public functions take and return 1-based columns. Internal calls to SourceMapConsumer are adjusted transparently.

What it does NOT do

• HMR / live reload. Maps load once per session; rebuilding the bundle mid-session requires a fresh SourceMapManager (or process restart).
• Multi-bundle re-merging. One .ajs ↔ one source map.
• IDE-side sourcesContent inlining — VS Code reads .ts from disk itself.

Related packages

This package is one of seven leaves of the @i-scope/debugger SDK meta-umbrella. The full family:

| Package | Role | |---------|------| | @i-scope/debugger | meta — one-install entry point for the whole SDK | | @i-scope/mcp-server | MCP server for AI agents (22 tools) | | @i-scope/dap-adapter | DAP server (AjsDebugSession) — embeddable + stdio | | @i-scope/iscope-bridge-client | Node JSON-RPC client to the native helper | | @i-scope/iscope-bridge | Win32 native helper binary (iScopeBridge.exe) | | @i-scope/source-map-bridge (you are here) | TS ↔ AJS source-map manager | | @i-scope/vlst-parser | Parser for VLST locals/Watch blobs | | @i-scope/com-protocol-types | TS-mirror of COM DISPID / event constants |

License

MIT — see LICENSE.

Repository

Part of the iScope Debugger monorepo: https://gitlab.com/i-scope/Debugger