sourcemonkey 0.0.0-stage → 0.5.0

package/dist/script-source-url.js

@@ -0,0 +1,214 @@
+// Canonical `sourcemonkey://SourceMonkey/...` URLs the injector
+// emits as `//# sourceURL=` directives, and that the viewer matches
+// stack-trace refs against.
+//
+// Why this URL shape:
+//
+// - The `sourcemonkey:` scheme is arbitrary — it just has to be
+//   URL-shaped, unique to us (the wrapper's async-error filter
+//   greps stack frames for it), and recognizable in stack traces.
+// - The literal `SourceMonkey` host puts everything we register
+//   under a single top folder in devtools' Sources tree. Devtools
+//   strips the scheme and uses the URL's authority as the first
+//   visible folder; without the host slot, our scripts would
+//   scatter at the top level.
+// - The next folder is the script's human-readable log label
+//   (`bar`, `bar%232`, etc.) — see `script-log-id.ts`. We use the
+//   log label rather than the script's UUID because the UUID is a
+//   debug-grade hash that's useless when you're scanning the tree.
+//   Per-script artifacts (`__config.js`, the main body, each
+//   `@require`) live under that folder so they cluster together
+//   by script.
+// - Page-wide URLs (`__bridge.js`, `__gm-runtime.js`, `__prelude.js`)
+//   live directly under `SourceMonkey/`. The bridge and GM runtime
+//   are true singletons (one chrome.userScripts registration each);
+//   the prelude is inlined per-script but every inclusion uses the
+//   same `__prelude.js` URL so devtools' Sources tree dedups them
+//   into a single visible entry.
+//
+// Why we percent-encode the label: it is a *display* string
+// (`script-log-id.ts` decodes URL-derived filenames so the user sees
+// `My Script.user.js`), and several of the characters that survive
+// that decode would break a URL. A bare `#` is the fragment
+// separator, so the `#N` dedup suffix would split the path; a space
+// or a paren ends the URL run that `stack-link.ts` matches, so a
+// stack-trace ref would stop linkifying to its tab. Everything
+// outside an unreserved-character whitelist is re-encoded — devtools
+// shows the encoded form, same as it always has. The viewer's Log tab
+// decodes it back for display (`displayRefText` in `stack-link.ts`),
+// so the two disagree on purpose: devtools indexes the file under
+// `main%232`, the Log tab reads `main#2` and keeps the wire form in a
+// tooltip.
+// Exported so consumers can recognize our own URLs by the exact prefix
+// rather than by the scheme alone — the scheme is unregistered, so a
+// hostile script can put `sourcemonkey://anything/…` in a log message
+// and have it parsed as a ref.
+export const ROOT = 'sourcemonkey://SourceMonkey';
+// Strip characters that would break out of the `//# sourceURL=<url>`
+// comment these URLs are spliced into. The log label is derived from
+// the on-disk filename (`script-log-id.ts`), which is attacker-
+// controlled for an untrusted script bundle. A JS line terminator
+// (LF/CR/U+2028/U+2029) ends the single-line `//` comment, so anything
+// after it on the line would become live code in the config blob —
+// which runs at document_start, before the script's own gating. Other
+// control chars can't break the comment but have no business in a
+// devtools tree path either; replace the lot with `_`. (The @require
+// URL builder already does per-segment whitelisting; this covers the
+// main/config/prelude labels that don't go through it.)
+function sanitizeLabel(label) {
+    // eslint-disable-next-line no-control-regex
+    return label.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, '_');
+}
+// Percent-encode everything outside the URL unreserved set, so the
+// segment is safe in a path AND carries nothing that would terminate
+// the stack-trace ref pattern in `stack-link.ts`. Applied last, after
+// the `.user.js` / `#N` surgery below has matched against the literal
+// characters.
+// The `u` flag matters: without it the character class matches single
+// UTF-16 code units, so an emoji (surrogate pair — GreasyFork names
+// are full of them) would be handed to encodeURIComponent half at a
+// time and throw URIError on the lone surrogate.
+function encodeSegment(segment) {
+    return segment.replace(/[^A-Za-z0-9._~-]/gu, (c) => {
+        let enc;
+        try {
+            enc = encodeURIComponent(c);
+        }
+        catch {
+            // An UNPAIRED surrogate — `u` makes the class match it as a
+            // single code point, but there's no UTF-8 encoding for it and
+            // encodeURIComponent throws. A manifest entry is user-authored
+            // JSON, so `"\ud800.user.js"` really can reach us. Letting the
+            // throw escape would reject the whole `Promise.all` in
+            // collectActiveSpecs and register NOTHING.
+            return '_';
+        }
+        // encodeURIComponent passes `!'()*` through untouched, and parens
+        // are exactly what would truncate a `at fn (URL:L:C)` frame — so
+        // hex-encode anything it declined to. All such characters are
+        // single-byte ASCII.
+        return enc === c ? `%${c.charCodeAt(0).toString(16).toUpperCase()}` : enc;
+    });
+}
+// Folder name for a script's artifacts. Strips the conventional
+// `.user.js` extension from the log label (the folder sits ABOVE the
+// main-body file, so the `.js` looks misleading on a folder), then
+// encodes what's left — which is where the `#E4` script-number suffix
+// (or an unnumbered script's `#N`) becomes `%23E4`.
+//
+// Examples:
+//   `foo.user.js`       → `foo`
+//   `foo.user.js#E4`    → `foo%23E4`
+//   `foo.user.js#2`     → `foo%232`
+//   `My foo.user.js`    → `My%20foo`
+//   `foo`               → `foo`      (no .user.js to strip)
+function folderForLabel(label) {
+    return encodeSegment(sanitizeLabel(label).replace(/\.user\.js(?=$|#)/, ''));
+}
+// Main-body file basename for a script. Same as the folder but with
+// the suffix dropped and `.user.js` restored — so the file's name
+// reflects the script's natural filename without the disambiguator
+// (each script lives in a different folder anyway).
+//
+// Examples:
+//   `foo.user.js`       → `foo.user.js`
+//   `foo.user.js#E4`    → `foo.user.js`
+//   `foo.user.js#2`     → `foo.user.js`
+//   `foo`               → `foo.user.js`
+function mainBaseForLabel(label) {
+    // Suffix first, extension second. The other order would eat a `#2`
+    // that's part of the name itself (`Chapter #2.user.js`) — which a
+    // decoded `%23` now makes reachable.
+    const base = sanitizeLabel(label).replace(/#E?\d+$/, '').replace(/\.user\.js$/, '');
+    return encodeSegment(base) + '.user.js';
+}
+// Per-script folder root.
+function scriptRoot(logLabel) {
+    return `${ROOT}/${folderForLabel(logLabel)}`;
+}
+// Canonical URL for the main script body.
+export function buildSourceUrl(logLabel) {
+    return `${scriptRoot(logLabel)}/${mainBaseForLabel(logLabel)}`;
+}
+// Canonical URL for the per-script config blob — the tiny {code}
+// entry the injector emits as the first js[] entry.
+export function buildConfigSourceUrl(logLabel) {
+    return `${scriptRoot(logLabel)}/__config.js`;
+}
+// Canonical URL for the per-script parse-failure sentinel — the last
+// js[] entry. Distinct from the config blob's URL on purpose: devtools
+// dedups Sources-tree nodes by URL, which is safe for the prelude only
+// because every copy of it is byte-identical. The sentinel and the
+// config blob are different code, so sharing a URL would show one node
+// whose text matches just one of them.
+export function buildSealSourceUrl(logLabel) {
+    return `${scriptRoot(logLabel)}/__seal.js`;
+}
+// Canonical URL for the prelude. Bytes (WRAPPER_PRELUDE) are
+// byte-identical for every script, so every per-script inclusion
+// tags itself with this same URL — devtools' Sources tree groups
+// the N inclusions into a single visible entry alongside the
+// bridge / GM runtime at the SourceMonkey/ top level. See
+// wrapPreludeEntry in injector.ts.
+export const PRELUDE_SOURCE_URL = `${ROOT}/__prelude.js`;
+// Canonical URL for the page-wide MAIN-world bridge.
+export const BRIDGE_SOURCE_URL = `${ROOT}/__bridge.js`;
+// Canonical URL for the page-wide GM_* runtime.
+export const GM_RUNTIME_SOURCE_URL = `${ROOT}/__gm-runtime.js`;
+// Canonical URL for one of a script's `@require` entries. We map
+// the require's real fetch URL into our synthetic scheme so:
+//   - the entry clusters with its owning script in devtools, and
+//   - stack frames are honest about the fact that we stored a
+//     snapshot of the bytes (we're not re-fetching at run time).
+//
+// Shape: `sourcemonkey://SourceMonkey/<folder>/<host>/<path>` — the
+// original URL's host + path become subfolders so the user can still
+// see the provenance in the Sources tree. Query strings and fragments
+// are dropped (the cached bytes don't depend on them). Two requires
+// on the same script with the same host+path but different `?…`
+// query strings would land at the same synthetic URL. The viewer's
+// tab lookup takes the FIRST match, so a mapped stack frame from the
+// second require opens the first require's tab — the source map picks
+// the right segment, only the tab lookup is ambiguous. Rare in
+// practice; the file-loader already dedups by canonical URL with
+// query, so it'd take two legitimately different `@require` lines
+// pointing at distinct stored copies. Worth revisiting if it ever
+// shows up: including a hash of the query in the path would fix it at
+// the cost of an uglier devtools tree.
+//
+// `file://` requires (resolved local files) use the synthetic host
+// `file` so they land under `<folder>/file/<path>` rather than
+// dropping out of the tree.
+//
+// On a URL we can't parse (shouldn't happen — the file-loader
+// validates before storage) we fall back to `<folder>/require` so we
+// still emit *something* parseable.
+export function buildRequireSourceUrl(logLabel, requireUrl) {
+    let host;
+    let path;
+    try {
+        const u = new URL(requireUrl);
+        host = u.protocol === 'file:' ? 'file' : u.hostname;
+        if (!host)
+            host = u.protocol.replace(/:$/, '');
+        path = u.pathname.replace(/^\/+/, '');
+    }
+    catch {
+        return `${scriptRoot(logLabel)}/require`;
+    }
+    // Sanitize each path segment. `new URL()` above already normalized
+    // `a/../b` to `b`, so the `..` / `.` filter is belt-and-suspenders
+    // — kept in case the input ever reaches us by a path that bypasses
+    // URL parsing (it doesn't today). The real work here is the
+    // per-segment character whitelist, which keeps spaces / special
+    // chars from confusing the devtools tree.
+    const cleanPath = path
+        .split('/')
+        .map((seg) => seg.replace(/[^a-zA-Z0-9._-]/g, '_'))
+        .filter((seg) => seg && seg !== '.' && seg !== '..')
+        .join('/');
+    const safeHost = host.replace(/[^a-zA-Z0-9._-]/g, '_') || 'require';
+    return cleanPath
+        ? `${scriptRoot(logLabel)}/${safeHost}/${cleanPath}`
+        : `${scriptRoot(logLabel)}/${safeHost}/require`;
+}

package/dist/script-world.js

@@ -0,0 +1,65 @@
+// Which execution world a script runs in, from its header. Its own
+// module so the harness can ask without loading the injector.
+import { getValue, getValues } from './userscript-header.js';
+import { resolveGrants } from './gm-api-catalog.js';
+// Decide which execution world a script should run in. Like
+// Tampermonkey and Violentmonkey, every script starts in the page's own
+// world (MAIN) and leaves it only when its header asks:
+//
+//   - `@inject-into page`      → MAIN
+//   - `@inject-into content`   → USER_SCRIPT (isolated)
+//   - `@sandbox raw`           → MAIN
+//   - `@sandbox JavaScript`    → MAIN (TM's choice on Chrome too; only
+//                                Firefox has a separate world for it)
+//   - `@sandbox DOM`           → USER_SCRIPT
+//   - anything else, unset, `@inject-into auto` → MAIN
+//
+// `@inject-into` (VM's) is read first when a script has both.
+//
+// Why the page by default: scripts written against TM and VM read the
+// page's globals (its `$`, an app's state, `customElements`) without
+// `unsafeWindow`, since there they are in the page. In USER_SCRIPT world
+// those read as `undefined` and the script silently breaks. Any script
+// but a `@grant none` one still keeps its writes off the page's
+// `window`: it runs in a sandbox `window` (`runsSandboxed` below).
+//
+// What the page costs a script, and why `@inject-into content` exists:
+// see docs/injection.md, "Execution world".
+//
+// `@inject-into content` with `unsafeWindow` (by grant or by use) gets
+// that world's own `window` as `unsafeWindow`, matching Violentmonkey's
+// content mode, plus a startup-log warning; see `extractStartupLogs`.
+export function resolveWorld(header) {
+    if (!header)
+        return 'MAIN';
+    const injectInto = (getValue(header, 'inject-into') ?? '').trim().toLowerCase();
+    if (injectInto === 'page')
+        return 'MAIN';
+    if (injectInto === 'content')
+        return 'USER_SCRIPT';
+    const sandbox = (getValue(header, 'sandbox') ?? '').trim().toLowerCase();
+    if (sandbox === 'dom')
+        return 'USER_SCRIPT';
+    return 'MAIN';
+}
+// The world for a stored row, the form every production caller uses:
+// the spec build, the match index and the reload-swap world check all
+// have to agree.
+export function resolveScriptWorld(script) {
+    return resolveWorld(script.header);
+}
+// Whether the script's user program runs inside a sandbox `window`
+// (the prelude's `sandbox`): a page-world script, unless it has
+// `@grant none`. A script with no `@grant` line at all is sandboxed
+// too, as Tampermonkey 5.5.0 and Violentmonkey 2.49.0 run it
+// (measured). That's how both run a script in the page: bare names
+// reach the page's globals, but the sandbox `window` shows only the
+// browser's built-ins, and the script's own writes, a `@require`d
+// library's `window.jQuery = …` included, stay off the page's
+// `window`. A `@grant none` script gets the page's `window` itself, as
+// under both. See docs/injection.md, "The sandbox window".
+export function runsSandboxed(script) {
+    if (!script.header || resolveScriptWorld(script) !== 'MAIN')
+        return false;
+    return !resolveGrants(getValues(script.header, 'grant')).hasNone;
+}

package/dist/sm-dev-protocol.js

@@ -0,0 +1,84 @@
+// What the extension and sm-dev both use. Their own module so the
+// harness can name them without loading the claim code in
+// sm-dev-link.ts.
+/** The first argument of every event's console line. */
+export const SM_DEV_EVENT = 'sm-dev-event';
+/**
+ * Refusals of the `managed` calls (managed-changes.ts), which sm-dev
+ * also checks before asking for `--force`.
+ */
+export const RUN_COLLECTION_LOCKED = 'An sm-dev run\'s test collection is changed only by its run';
+export const LISTED_BY_LOCATION = 'This script is listed by a directory or manifest collection, so it stays there while its file does. Only a script in a container collection can be moved or uninstalled.';
+export const CONTAINER_TARGET_ONLY = 'Scripts can only be installed or moved into a container collection';
+/**
+ * Why a manual script (`@run-at context-menu`) can't be run on a tab
+ * now: `runManualScript`'s answers, which the popup logs and sm-dev
+ * prints after the script's name. See docs/manual-scripts.md.
+ */
+export const MANUAL_RUN_NOT_INSTALLED = 'This script is not installed';
+export const MANUAL_RUN_NOT_MANUAL = 'This script runs when a page loads. Only a script with @run-at context-menu is run on request.';
+export const MANUAL_RUN_SCRIPT_OFF = 'This script is turned off';
+export const MANUAL_RUN_COLLECTION_OFF = 'This script\'s collection is turned off';
+export const MANUAL_RUN_NOT_HERE = 'This script\'s @match and @include rules don\'t cover this page';
+export const MANUAL_RUN_PAGE = 'SourceMonkey can\'t run scripts on this page';
+export const MANUAL_RUN_TAB_GONE = 'The tab was closed';
+export const MANUAL_RUN_PAGE_CHANGED = 'The page changed before the script could run. Try again.';
+export const MANUAL_RUN_SM_DEV = 'The sm-dev run controlling this tab keeps this script out';
+/**
+ * The event types of the markers sm-dev puts in its browser's pages,
+ * which tell a `document-start` wrapper whether it can run without
+ * asking the extension (`smDevMarker` in userscript-prelude.js, which
+ * has its own copy). See docs/sm-dev-design.md#making-wrappers-ask.
+ * - `present`: in every page. sm-dev is connected, so any tab may be
+ *   claimed.
+ * - `vouchPrefix` + the run's id: in a tab that run claims, while its
+ *   scripts are on.
+ */
+export const SM_DEV_MARKERS = {
+    present: 'sourcemonkey-sm-dev',
+    vouchPrefix: 'sourcemonkey-sm-dev-run:',
+};
+/** The reason a skipped wrapper reports for a tab an sm-dev run controls. */
+export const SKIP_REASON_SM_DEV = 'tab controlled by sm-dev';
+/**
+ * The version of the calls and events between sm-dev and the extension,
+ * which each side has its own copy of: sm-dev from a repo's install, the
+ * extension from the person's browser. A run compares them as it
+ * connects (extension-link.ts). See CLAUDE.md for when to bump which.
+ *   - `major`: a change that needs both sides updated. A run refuses an
+ *     extension whose major differs.
+ *   - `minor`: an addition. An extension ahead is fine. An sm-dev ahead
+ *     checks the extension's minor before using what came later
+ *     (`ExtensionLink.requireMinor`).
+ */
+// 1.1: `scriptsOnTab` rows carry the script's number.
+// 1.2: `managedCollections` and `managedScripts`; `writeRunScript`
+//   takes the script's `source` file, which `managedScripts` gives back.
+// 1.3: permission prompts: `connect-prompt` events, `answerConnectPrompt`.
+// 1.4: a report event can carry `detail`: why a script had no decision.
+// 1.5: `managed`, the calls that change collections and installed
+//   scripts (`managed.setScriptEnabled` and the rest), and
+//   `managed.scriptDetails` / `managed.scriptText` (managed-changes.ts).
+// 1.6: manual scripts (`@run-at context-menu`): `runManualScript`, and
+//   the `sm:manual` report for one waiting in a new document.
+// 1.7: a script's badge status can be `UNTRACKED`: its page loaded
+//   before the extension started.
+// 2.0: wrappers no longer all ask while a claim is live; sm-dev marks
+//   the pages of its browser instead (`SM_DEV_MARKERS`), which an older
+//   sm-dev doesn't, so the extension would run scripts in its tabs.
+// 2.1: scripts run in iframes, so report and menu events now come from
+//   frames too (`topFrame: false`); `fireActionContextMenuItem` takes
+//   the command's `documentId`.
+// 2.2: `request`, `download`, `values` and a shown `notification` event
+//   carry the sending document's `documentId`, which says which frame.
+// 2.3: `managed.scriptFiles`, a script's `@require` and `@resource`
+//   files as installed.
+// 2.4: `managed.scriptIcons`, a script's `@icon` and its site icons.
+// 3.0: every script runs in the page's world unless it asks to be
+//   isolated. sm-dev works out each script's world itself, for
+//   `eval --script` and for whose error a page error could be, so an
+//   older one would look in the wrong world. On a page whose CSP
+//   `sandbox` turns off script in its own world, the page-world scripts
+//   run isolated instead, which sm-dev notes rather than warning that
+//   they can't run.
+export const SM_DEV_PROTOCOL = { major: 3, minor: 0 };

package/dist/source-map.js

@@ -0,0 +1,177 @@
+// Minimal Source Map v3 generator for the concatenated injection entry.
+//
+// Why: in Mode A (see docs/injection-modes.md) a script's `@require`
+// bodies and its own body are concatenated into ONE `js[]` entry so
+// they share a lexical scope. That's what makes a library's top-level
+// `const`/`class` visible to the main body, exactly as in TM/VM — but
+// it also means the main body's line N no longer lands at physical
+// line N, and every require loses the devtools file it used to have.
+//
+// A source map buys both back: devtools splits the single generated
+// script into the original files and reports original line numbers.
+//
+// Scope of this generator:
+//
+//   - **Line-level only.** One mapping per generated line, always at
+//     column 0. We never move code within a line, so column fidelity
+//     would be busywork; line granularity is what stack traces and
+//     breakpoints need.
+//   - **`sourcesContent` is always embedded.** Our sources are
+//     synthetic `sourcemonkey://…` URLs, which devtools cannot fetch,
+//     so embedding the text is the only way the mapped files are
+//     viewable. It is also the expensive part: the sources ship a
+//     second time, base64'd, so the entry grows by ~1.6× their size.
+//
+//     There is deliberately no size cap on this. The only constraint
+//     that actually binds is whether `chrome.userScripts.register()`
+//     accepts the payload, and that failure is already visible:
+//     `registerWithFallback` in src/extension/injector.ts drops from batch to
+//     per-script registration on rejection and records the reason
+//     against that script (which then reads REJECTED, with Chrome's
+//     wording), so an oversized script fails loudly and by name. A preemptive cap would trade that for silently degrading
+//     the feature the map exists to provide. The map does NOT touch
+//     our `chrome.storage.local` quota — it's generated at
+//     registration time from sources already stored.
+//
+// What V8 does NOT do for us: map `Error.stack` *strings*. It maps
+// source positions for the devtools UI, but `err.stack` keeps
+// generated coordinates, and SourceMonkey parses those strings for the
+// viewer's Log tab (src/stack-link.ts). `remapStackRef` below is the
+// other half — the Log tab applies the same segment list itself, so a
+// logged frame names the same file and line devtools shows. See
+// docs/script-log.md#stack-refs-are-source-mapped-first.
+// Base64 VLQ, per the Source Map v3 spec.
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+// Domain: |value| < 2^30. Above that the `<< 1` wraps negative and the
+// loop emits a single wrong digit. Every caller here passes a line or
+// source index, so this is unreachable — noted so nobody reuses the
+// function for byte offsets.
+export function encodeVlq(value) {
+    // Sign goes in the low bit, magnitude above it.
+    let vlq = value < 0 ? ((-value) << 1) | 1 : value << 1;
+    let out = '';
+    do {
+        let digit = vlq & 0b11111;
+        vlq >>>= 5;
+        // Continuation bit: more 5-bit groups follow.
+        if (vlq > 0)
+            digit |= 0b100000;
+        out += B64[digit];
+    } while (vlq > 0);
+    return out;
+}
+// Build the map object. `totalLines` is the generated entry's line
+// count; generated lines not covered by any segment (the wrap's head
+// and tail, the `;` separators) get an empty group, which devtools
+// reads as "no original position" and leaves attributed to the
+// generated file.
+//
+// `file` is deliberately the same URL as the entry's own
+// `//# sourceURL=`, which is also `sources[last]` (the script's own
+// body). Bundlers avoid that collision — devtools keys files by URL,
+// so a mapped source sharing its generated script's URL could in
+// principle show up twice, or empty. Verified in Chrome's Sources
+// panel that it doesn't: the mapped file shadows the generated one,
+// and a script with one `@require` shows exactly two entries — the
+// `.user.js` and the require nested under a `<host>/<path>` subtree —
+// both with their original text. Keeping the URLs identical is what
+// lets the Log tab's stack-ref linkification match on one string.
+export function buildSourceMap(args) {
+    const sources = args.segments.map((s) => s.url);
+    // generatedLine → {sourceIndex, originalLine}. Later segments win on
+    // overlap, which can't happen for the layouts we generate but keeps
+    // the function total.
+    const perLine = new Map();
+    args.segments.forEach((seg, srcIdx) => {
+        for (let k = 0; k < seg.lineCount; k++) {
+            perLine.set(seg.generatedLine + k, { srcIdx, origLine: k });
+        }
+    });
+    // VLQ fields after the first are deltas against the previous
+    // segment, carried across line groups (only the generated column
+    // resets per line — and ours is always 0, so it never contributes).
+    let prevSrcIdx = 0;
+    let prevOrigLine = 0;
+    const groups = [];
+    for (let gen = 0; gen < args.totalLines; gen++) {
+        const hit = perLine.get(gen);
+        if (!hit) {
+            groups.push('');
+            continue;
+        }
+        groups.push(encodeVlq(0) +
+            encodeVlq(hit.srcIdx - prevSrcIdx) +
+            encodeVlq(hit.origLine - prevOrigLine) +
+            encodeVlq(0));
+        prevSrcIdx = hit.srcIdx;
+        prevOrigLine = hit.origLine;
+    }
+    return {
+        version: 3,
+        file: args.file,
+        sources,
+        sourcesContent: args.segments.map((seg) => seg.content),
+        names: [],
+        mappings: groups.join(';'),
+    };
+}
+// Look up the original file + line for a 1-based generated line.
+// Returns null for lines no segment covers. In 1-based terms those are
+// line 1 (the wrap head), each `// @require` marker line, each `;` ASI
+// guard between requires, and the closing `});`. They are ours, not
+// the user's, so leaving them unmapped is correct — the caller drops
+// the link rather than pointing at a neighbouring line.
+export function lookupGeneratedLine(segments, generatedLine) {
+    const gen0 = generatedLine - 1;
+    for (const seg of segments) {
+        if (gen0 >= seg.generatedLine && gen0 < seg.generatedLine + seg.lineCount) {
+            return { url: seg.url, line: gen0 - seg.generatedLine + 1 };
+        }
+    }
+    return null;
+}
+// Rewrite a stack ref that points into the concatenated entry so it
+// names the original `@require` (or the body) at its own line.
+//
+// Every frame from the combined entry carries `entryUrl` — the
+// script's own `//# sourceURL=`, which V8 stamps on the whole entry
+// regardless of which concatenated file the code came from. So the
+// URL match is the test for "is this frame ours to remap"; refs to
+// anything else (the page, another userscript, `__prelude.js`) pass
+// through untouched.
+//
+// Columns pass through unchanged, and that is exact rather than
+// approximate: composition only ever moves whole lines, never code
+// within a line. A script with NO requires has no segments at all, so
+// it returns early — see the layout notes in composed-source.ts for
+// the column caveat that applies to that case.
+export function remapStackRef(ref, entryUrl, segments) {
+    if (segments.length === 0)
+        return null;
+    if (ref.url !== entryUrl)
+        return null;
+    const orig = lookupGeneratedLine(segments, ref.line);
+    if (!orig)
+        return null;
+    return { url: orig.url, line: orig.line, col: ref.col };
+}
+// UTF-8 → base64. `btoa` alone throws on any code point above U+00FF,
+// and userscripts are full of them (the script that prompted Mode A is
+// half Chinese). Encode to bytes first, then base64 the byte string.
+function base64Utf8(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    // Chunked so a large source doesn't blow the argument limit on
+    // String.fromCharCode.apply.
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+// The `//# sourceMappingURL=` line to append to the generated entry.
+// Inline data URI because a `sourcemonkey://` map URL would be no more
+// fetchable than the sources themselves.
+export function inlineSourceMapComment(map) {
+    return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64Utf8(JSON.stringify(map))}`;
+}