Document that source maps are off by default in 5.4, and how to turn them on

[kriszyp]

Documents that Harper v5.4.0 no longer enables source maps by default, and how to turn them on. Companion to HarperFast/harper#3072, which turns them off to save several megabytes of heap per thread.

⊙ Problem

After HarperFast/harper#3072, stack traces from Harper's core point at the compiled dist/*.js files unless source maps are enabled. Nothing in the docs says source maps exist, so an operator who upgrades sees different stack traces with no explanation.

🤔 Where operators look

The note sits on the debugging page next to the inspector settings. Should it also appear in the logging docs?

💡 Solution

A "Source Maps in Stack Traces" section tells operators how to turn source maps on (NODE_OPTIONS=--enable-source-maps), what it costs, and which stack traces it changes. It also says what Fabric users get, and the 5.4 release note points to it.

🤔 No opt-in on hosted Fabric

--enable-source-maps is a Node.js flag, not a V8 flag, so threads.v8Flags cannot carry it. A Harper config key (the main thread calling process.setSourceMapsEnabled(true), which workers already inherit) would give Fabric users a way in. That is a core change; this PR documents today's behavior.

🔧 Changes

• debugging.md: a "Source Maps in Stack Traces" section (changed in v5.4.0). It leads with how to turn them on (NODE_OPTIONS=--enable-source-maps), then the memory cost. It scopes the effect to modules Node.js loads itself: Harper's core, natively loaded application code, and natively loaded npm packages. Harper's VM-based loaders were never mapped.
• What Fabric users get: NODE_OPTIONS cannot be set on Fabric clusters that Harper hosts. Application code on the default loader is unaffected; only core and natively loaded package frames stay unmapped. Look hardest here.
• overview.md: the See Also entry for Worker Thread Debugging mentions source maps.
• 5.4.md: a "Smaller Per-Thread Baseline" note: idle heap drops from about 58 MB to 35 MB, some dependencies load on first use, and source maps are off by default.

✅ Verification

Not observable end-to-end in this repository; prettier is clean on the changed files. The behavior described was checked against HarperFast/harper#3072 on a running server: source maps are off in the main thread and workers by default, and on in all of them with NODE_OPTIONS=--enable-source-maps. Loader scoping was read from Harper's security/jsLoader.ts and server/threads/manageThreads.js. That no Fabric control sets NODE_OPTIONS was checked by searching the Fabric repos, not confirmed with the Fabric team.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.}

Related PRs: #671 independent, #709 overlaps (also adds a 5.4 release note), #712 overlaps (also adds a 5.4 release note), #710 overlaps (merged; also edits the 5.4 release notes, merges cleanly), #727 overlaps (also edits the 5.4 release notes; keep both sections on rebase), #720 overlaps (merged; its 5.4 agent section sits beside this one), #715 independent
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse,muse; rounds=4; full=1 @ 5d79e30}

_{Review-Attention: skim ~2m (decisions: release-note-placement, opt-in-surface, no-production-recommendation) @ 5d79e30}

[gemini-code-assist]

Code Review

This pull request updates the documentation and release notes for Harper v5.4.0 to reflect changes in memory management and source map handling. Specifically, it documents that source maps are no longer enabled by default to reduce per-thread memory usage, and provides instructions on how to re-enable them using the NODE_OPTIONS=--enable-source-maps environment variable. It also highlights a 40% reduction in idle JavaScript heap usage due to optimized compiled code and lazy-loading of specific dependencies. No review comments were provided, so there is no additional feedback.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-714

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-714

This preview will update automatically when you push new commits.

[dawsontoth]

If most people are running Harper on Fabric, how do they enable it? NODE_OPTIONS is not a great example for that use case.

[kriszyp]

Good question. On Fabric clusters that Harper hosts there is no way to turn them on today:

• NODE_OPTIONS: users don't control the process environment, and I found no Fabric control (central-manager, host-manager, studio) that sets it.
• threads.v8Flags: --enable-source-maps is a Node.js flag, not a V8 flag, so it can't be passed this way.

What this costs a Fabric user is smaller than it looks. Application code on the default vm-current-context loader was never source-mapped. Harper strips TypeScript types there without moving code, so those stack traces are unchanged. What stays unmapped is frames from Harper's core and from npm packages Harper loads natively. The section now says this (debugging.md), and the release note limits NODE_OPTIONS to environments you control.

If we want Fabric users to have a way in, a small core change would do it: a Harper config key that makes the main thread call process.setSourceMapsEnabled(true) at startup. Workers already inherit that (manageThreads.js passes --enable-source-maps whenever process.sourceMapsEnabled is true). I left this thread open in case you'd like that before this merges, or know of a Fabric env-var control I missed.

— Claude Opus 5.5

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-714

This preview will update automatically when you push new commits.