# @stackline/source-map-support 1.0.0

Canonical documentation: https://alexandro.net/docs/vanilla/source-map-support/
Repository: https://github.com/alexandroit/stackline-source-map-support
Registry: https://www.npmjs.com/package/@stackline/source-map-support
License: MIT, with separately retained V8 BSD-3-Clause copied-code terms
Runtime: Node.js >=14.15.1
Browser support: ES2015 UMD CommonJS/named-AMD/global plus a root-condition ESM host
Compatibility baseline: source-map-support@0.5.21
Baseline commit: 888339343236f0912ddc2f635e356e4ed9c0ddf3
Release source commit: 110450f9bac02054a152cfd9fb463283e3ce8765
Published at: 2026-08-29T02:12:43.455Z
Registry document created at: 2026-08-29T02:12:43.140Z
Registry document modified at: 2026-08-29T02:12:43.729Z
Published tarball SHA-256: d7ff4d6e01f067e595e3df603a2aa88486d783c7c11d45e4df073ed577f94adb
Direct production dependency: @jridgewell/trace-mapping@0.3.31
Exact production graph: @jridgewell/trace-mapping@0.3.31,
@jridgewell/resolve-uri@3.1.2, @jridgewell/sourcemap-codec@1.6.0
Map constructor: AnyMap, accepting regular and indexed/sectioned Source Map v3
Browser-bundled graph: the three exact @jridgewell packages above plus
path-browserify@1.0.1

## Purpose and native boundary

@stackline/source-map-support maps generated JavaScript positions to original
source positions for residual integrations that native Node source maps do not
fully replace: vm.runInThisContext, browser delivery, historical side-effect
register entries, synchronous custom retrieval, and direct mapping APIs.

Prefer native source maps for ordinary modern Node files. Native mapping avoids
a userland global stack formatter. The package intake reproduced a bounded
Node.js 26.8.1 difference: native mapping handled an ordinary generated file
but not the equivalent vm.runInThisContext frame, while the package mapped the
VM frame when given a filename and map. This does not make the package the
default choice for every Node process.

## Install and alias

Scoped dependency:
npm install @stackline/source-map-support

Lowest-change compatibility alias:
"source-map-support": "npm:@stackline/source-map-support@1.0.0"

The alias preserves root imports, source-map-support/register, historical deep
entries, and bundler or Electron externals keyed by source-map-support. Commit
the manifest and lockfile and verify the exact scoped resolution.

## CommonJS root API

The CommonJS root has exactly six enumerable functions, in order:

1. wrapCallSite
2. getErrorSource
3. mapSourcePosition
4. retrieveSourceMap
5. install
6. resetRetrieveHandlers

Requiring the root does not install hooks. The ESM host default is the same
CommonJS namespace object. ESM also exposes the six functions as named
bindings.

## Position and payload types

Position contains source:string, line:number, column:number, and optional
name:string|null. Lines are one-based. Position columns are zero-based.

SourceMapPayload contains map:string|object and optional url:string. The map
must be valid JSON text or an object accepted by AnyMap, including a regular or
indexed/sectioned Source Map v3 payload.

## install(options)

install assigns Error.prepareStackTrace once. Its options are:

- environment: auto, node, or browser. Other values throw.
- retrieveFile(path): synchronous source text provider.
- overrideRetrieveFile: clear existing file providers first.
- retrieveSourceMap(source): synchronous {map,optional url} provider.
- overrideRetrieveSourceMap: clear existing map providers first.
- hookRequire: outside browser mode, wrap Module.prototype._compile and cache
  runtime-transpiler source.
- emptyCacheBetweenOperations: replace source and map caches before stack
  formatting.
- handleUncaughtExceptions: control the Node main-thread process.emit shim;
  defaults to true on its first eligible install.

Custom providers are synchronous priority handlers. Without an override, a
new handler runs first and a nullish or empty miss falls through. Provider
exceptions are integration failures and can escape mapping work.

Auto browser detection requires window and callable XMLHttpRequest and excludes
the historical Electron renderer shape containing window.require,
window.module, and window.process.type === renderer. Electron integrations
should set an explicit environment when they need deterministic selection.

## mapSourcePosition(position)

Finds or caches a source map for position.source, traces the generated line and
column, and resolves the mapped source against the map URL and sourceRoot. A
mapped name is returned where available.

No map, a map gap, malformed map construction, a throwing lookup, or no
original source returns the precise generated position. Malformed maps and
misses are cached. Truthy sourcesContent values are cached under resolved
source URLs for source excerpts.

## wrapCallSite(frame,state?)

Maps a V8-compatible CallSite. Native frames pass through. Normal frames can
receive mapped filename, script URL, line, column, and mapped function name.
Recognized eval origins are mapped recursively. CallSiteToString contains V8
4.3.49-derived code under BSD-3-Clause terms. State contains nullable
nextPosition and curPosition; direct callers normally omit it.

## getErrorSource(error)

Returns a mapped filename and line, source text, and caret when a recognized
frame and source content are available. It uses cached sourcesContent or a
readable local file. It returns null on a miss. It is diagnostic output, not a
redaction API.

## retrieveSourceMap(source)

Runs the synchronous map provider chain and returns its first truthy
SourceMapPayload or null. The default provider finds the final
sourceMappingURL, decodes inline base64 JSON, or resolves an external map.
Browser mode also checks SourceMap and X-SourceMap response headers.

## resetRetrieveHandlers()

Restores built-in file and map provider lists. It does not restore a prior
Error.prepareStackTrace, process.emit, or Module.prototype._compile and is not
an uninstall API.

## Supported package entries

The export map supports:

- .
- ./source-map-support
- ./source-map-support.js
- ./register
- ./register.js
- ./register-hook-require
- ./register-hook-require.js
- ./browser-source-map-support
- ./browser-source-map-support.js
- ./package.json

register calls install immediately. register-hook-require calls install with
hookRequire true immediately. The explicit browser entry is the standalone UMD
distribution. Extensionless and .js historical forms are supported. Root
browser-condition ESM import selects browser-source-map-support.mjs; root
browser CommonJS selects browser-source-map-support.js. The legacy browser
field also remaps source-map-support.js to the UMD browser implementation.

## Browser contract

browser-source-map-support.js is a self-contained ES2015 UMD artifact. It
selects CommonJS module.exports, named AMD module browser-source-map-support,
or globalThis.sourceMapSupport. Its six-function API and custom-map tracing are
tested in all three delivery forms. browser-source-map-support.mjs is a
companion ES2015 host with the same default object and named function
identities. Browser-aware root ESM imports select it, while explicit browser
deep imports remain UMD. Bundler gates verify root import and require routing.

Default browser retrieval uses synchronous XMLHttpRequest and is subject to
origin and CORS policy. A bounded preloaded custom provider avoids implicit
network reads. Automatic stack rewriting additionally depends on compatible
V8-style Error.prepareStackTrace and CallSite behavior. Direct mapping success
does not promise automatic mapping in every JavaScript engine.

Both browser artifacts resolve relative map and source paths with bundled
path-browserify code and do not require a Node process global. Malformed inline
base64 maps fail back to their generated positions instead of leaking a strict
browser atob exception.

## Preserved behavior

- final matching sourceMappingURL comment wins
- inline base64 and external maps
- regular and indexed Source Map v3, including section offsets, names and
  embedded sourcesContent through AnyMap
- sourceRoot, map-relative sources, mapped names and sourcesContent
- URL, file URL and Windows drive-path resolution
- VM-generated code with stable filename and available map
- runtime-transpiler inline maps through hookRequire
- eval, native and ordinary CallSite formatting, including current V8
  differently-named property aliases
- browser SourceMap and X-SourceMap headers
- synchronous custom retrieval ordering and override flags
- environment validation and Electron renderer auto-detection edge
- main-thread uncaught shim and worker-thread exclusion

## Maintained corrections

- exact @jridgewell trace-mapping production graph replaces historical
  source-map and buffer-from dependencies; AnyMap handles regular and
  indexed/sectioned maps
- URL hosts are not treated as local path segments
- generated file content is released after unsuccessful map discovery
- malformed maps, malformed inline base64 and misses fall back and are cached
- cache dictionaries do not inherit __proto__, constructor or toString
- UTF-8 inline browser maps and relative path resolution require neither a
  Buffer polyfill nor a Node process global
- uncaught Error.cause rendering and existing nonzero exit codes are retained

These are compatibility and defense-in-depth corrections, not an assigned
vulnerability, advisory, or CVE claim.

## Global lifecycle

Error.prepareStackTrace is realm-global. The optional process.emit and
Module.prototype._compile wrappers are process-global. Install once in the
intended process or realm. Test profilers, test runners, telemetry, Electron
main and renderer processes, and any integration that captures or replaces a
stack formatter.

The package does not create an isolated mapper instance. Resetting retrieval
providers does not undo global hooks. Removing the dependency from disk does
not undo hooks in a running process; restart for rollback.

## Security boundary

Node defaults can synchronously read generated files and referenced maps.
Browser defaults can issue synchronous XHR. The package imposes no hard byte,
source-count, nesting, filesystem-root, URL, origin, network, or total-cache
limits. Callers must bound trusted providers and artifact sizes.

Maps and sourcesContent can disclose original source, filenames, paths, names,
and secrets. Review production maps separately and redact getErrorSource output
before sending it to an untrusted destination.

Malformed-input and retention regression coverage does not make arbitrary
maps free or trusted. Custom providers must catch expected errors and enforce
their own resource budget.

## TypeScript

TypeScript 3.9-compatible CommonJS namespace declarations define Position,
SourceMapPayload, InstallOptions, retrieval callbacks, CallSite, and all six
functions. Modern .d.cts and .d.mts routing provides CommonJS and ESM forms.
Register side-effect entries and the browser entry have dedicated declarations.

## License and provenance

The source-map-support runtime is Copyright (c) 2014 Evan Wallace under the
MIT License. CallSiteToString includes code copied almost verbatim from V8
4.3.49 src/messages.js and retains the V8 BSD 3-Clause terms. The exact three
@jridgewell production components and browser-bundled path-browserify@1.0.1
are MIT-licensed with all four full license texts in the documentation.

This is an independent continuation. It is not affiliated with or endorsed by
Evan Wallace, the upstream source-map-support project, V8, Google, Justin
Ridgewell, or the @jridgewell projects.

## References

README: https://alexandro.net/docs/vanilla/source-map-support/README.md
API: https://alexandro.net/docs/vanilla/source-map-support/API.md
Changelog: https://alexandro.net/docs/vanilla/source-map-support/CHANGELOG.md
Compatibility: https://alexandro.net/docs/vanilla/source-map-support/COMPATIBILITY_CONTRACT.md
Migration: https://alexandro.net/docs/vanilla/source-map-support/MIGRATION.md
Security: https://alexandro.net/docs/vanilla/source-map-support/SECURITY.md
Licenses: https://alexandro.net/docs/vanilla/source-map-support/THIRD_PARTY_LICENSES.md
CommonJS example: https://alexandro.net/docs/vanilla/source-map-support/examples/commonjs.cjs
ESM example: https://alexandro.net/docs/vanilla/source-map-support/examples/esm.mjs
VM example: https://alexandro.net/docs/vanilla/source-map-support/examples/vm.cjs
Custom-hook example: https://alexandro.net/docs/vanilla/source-map-support/examples/custom-hooks.cjs
Browser example: https://alexandro.net/docs/vanilla/source-map-support/examples/browser.html
Metadata: https://alexandro.net/docs/vanilla/source-map-support/package-meta.json