sourcemonkey 0.0.0-stage → 0.5.0

package/dist/version-compare.js

@@ -0,0 +1,141 @@
+// `@version` ordering.
+//
+// Userscript versions are not semver — managers accept whatever the
+// author writes. Tampermonkey compares them as dot-separated segments
+// with an optional `-prerelease` tail, and that's what we implement:
+// enough structure to order the versions real scripts use, with a
+// deterministic answer for the ones that don't fit.
+//
+// Pure module — no DOM, no chrome.*, no fetching. The only consumer
+// that needs a verdict rather than an ordering is the UI, which uses
+// `versionRelation`.
+// Splits `1.2.3-beta.4` into `{ main: ['1','2','3'], pre: ['beta','4'] }`.
+// Only the FIRST `-` starts the prerelease tail, so `1.0-rc-2` has a
+// two-segment-free prerelease of `rc-2` rather than nesting further.
+//
+// A `+build` tail is dropped first, per semver: build metadata carries
+// no precedence. Without this, `1.0+b2` vs `1.0` would compare its last
+// main segment as `0+b2` vs `0` and report the metadata-only change as
+// a newer version — a false OUTDATED.
+function splitVersion(v) {
+    const plus = v.indexOf('+');
+    const trimmed = (plus < 0 ? v : v.slice(0, plus)).trim();
+    const dash = trimmed.indexOf('-');
+    const mainPart = dash < 0 ? trimmed : trimmed.slice(0, dash);
+    const prePart = dash < 0 ? '' : trimmed.slice(dash + 1);
+    return {
+        main: mainPart.split('.'),
+        pre: prePart ? prePart.split('.') : [],
+    };
+}
+const NUMERIC_RE = /^\d+$/;
+// Compare one segment pair. Numeric-vs-numeric compares as numbers so
+// `10` beats `9`; anything else falls back to code-unit order, which
+// happens to put digits below letters — the same direction semver
+// specifies for a numeric-vs-alphanumeric identifier.
+//
+// A consequence worth knowing: `1.0-beta` sorts *below* `1.0` (the
+// prerelease rule) but `1.0.beta` sorts *above* it (padded `'0'` vs
+// `'b'` here). Both follow from the rules as stated; only the `-` form
+// is a prerelease.
+function compareSegment(a, b) {
+    if (NUMERIC_RE.test(a) && NUMERIC_RE.test(b)) {
+        const x = Number(a);
+        const y = Number(b);
+        return x < y ? -1 : x > y ? 1 : 0;
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+// Missing trailing segments read as `0`, so `1.2` and `1.2.0` are the
+// same version. Authors bump `1.2` → `1.2.1` all the time and expect
+// exactly that.
+function compareMain(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const cmp = compareSegment(a[i] ?? '0', b[i] ?? '0');
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+// Prerelease tails follow semver's precedence rules: a release outranks
+// any prerelease of the same main version (`1.0` > `1.0-rc1`), and
+// between two prereleases the one that runs out of segments first is
+// lower (`1.0-rc` < `1.0-rc.2`).
+function comparePre(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const sa = a[i];
+        const sb = b[i];
+        if (sa === undefined)
+            return -1;
+        if (sb === undefined)
+            return 1;
+        const cmp = compareSegment(sa, sb);
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+// Total order over version strings. Always returns an ordering — there
+// is no "incomparable" verdict, because every caller ultimately has to
+// pick newer / older / same and a null would just push the arbitrary
+// choice up a layer. An empty string sorts below every non-empty one.
+export function compareVersions(a, b) {
+    const ta = a.trim();
+    const tb = b.trim();
+    if (!ta || !tb) {
+        if (ta === tb)
+            return 0;
+        return ta ? 1 : -1;
+    }
+    const va = splitVersion(ta);
+    const vb = splitVersion(tb);
+    const main = compareMain(va.main, vb.main);
+    if (main !== 0)
+        return main;
+    return comparePre(va.pre, vb.pre);
+}
+// The prerelease tag a local copy's `@version` carries: `13.2` copied
+// for editing becomes `13.2-local`. Lives here, next to the comparison
+// that has to recognise it — see `versionRelation`.
+export const LOCAL_EDIT_TAG = 'local';
+// The `@version` a local copy is given: the original with `-local`
+// appended. Always a plain append — `splitVersion` keys on the FIRST
+// `-`, so `1.0-beta` becomes `1.0-beta-local`, whose single prerelease
+// segment `beta-local` string-compares above `beta` and stays below
+// the `1.0` release. That copy therefore reads as newer than its
+// source, the ordinary "local edit running ahead" case; only a source
+// with no tail needs the `edited` relation below.
+export function localEditVersion(version) {
+    return `${version.trim()}-${LOCAL_EDIT_TAG}`;
+}
+// True when `version` is a local edit per `localEditVersion`: any
+// prerelease segment that is, or ends in, `-local`.
+export function isLocalEditVersion(version) {
+    const { pre } = splitVersion(version.trim());
+    return pre.some((seg) => seg === LOCAL_EDIT_TAG || seg.endsWith(`-${LOCAL_EDIT_TAG}`));
+}
+export function versionRelation(loaded, other) {
+    if (!loaded?.trim() || !other?.trim())
+        return 'unknown';
+    const cmp = compareVersions(other, loaded);
+    if (cmp > 0)
+        return isEditOf(loaded, other) ? 'edited' : 'newer';
+    if (cmp < 0)
+        return 'older';
+    return 'same';
+}
+// `loaded` is a local edit of `other`: same main segments, `other` has
+// no prerelease tail, and ours is a `-local` one.
+function isEditOf(loaded, other) {
+    const vl = splitVersion(loaded.trim());
+    const vo = splitVersion(other.trim());
+    return vo.pre.length === 0 && compareMain(vl.main, vo.main) === 0 && isLocalEditVersion(loaded);
+}

package/dist/version-probe.js

@@ -0,0 +1,120 @@
+// Update probes: "what `@version` does the script's upstream claim?"
+//
+// A probe is deliberately NOT a refresh. A refresh fetches the bytes we
+// actually run, from the URL the user installed from, and can change a
+// script's status. A probe fetches somebody else's copy, reads one
+// header line out of it, and changes nothing but a display annotation.
+// Keeping them apart is the whole design: a `@downloadURL` pointing at
+// an origin the user never approved must never become an update
+// channel, and an unreachable probe host must never disable a working
+// script.
+//
+// What gets probed: only `@updateURL` / `@downloadURL` values that
+// differ from the URL we load the script from. We already auto-update
+// from our own collection — local files via the scan's size+mtime check,
+// http(s) via a conditional GET — so probing it would be a slower way
+// to learn what the refresh that just ran already established.
+//
+// That leaves exactly the interesting case: a copy whose official home
+// is somewhere we don't fetch from. We can't update it automatically,
+// so all we can do is say so. See [docs/updates.md].
+import { getValue } from './userscript-header.js';
+import { versionRelation } from './version-compare.js';
+// How long a recorded probe stays fresh. Probes hit third-party hosts
+// on somebody else's page load, and an upstream release is a
+// once-in-weeks event, so this is deliberately hours rather than the
+// seconds the collection-refresh gate uses.
+export const PROBE_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+// Canonical form for comparing a probe URL against the script's own
+// location. Returns null for anything that isn't an absolute http(s)
+// URL: a relative `@updateURL` has no meaning (updates come from a
+// fixed home, not from wherever this copy happens to sit), and a
+// `file://` one would turn a header line into a host-file read.
+function canonicalProbeUrl(raw) {
+    if (!raw?.trim())
+        return null;
+    try {
+        const u = new URL(raw.trim());
+        return u.protocol === 'http:' || u.protocol === 'https:' ? u.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The distinct upstream URLs worth asking about, in `update`-first
+// order. Deduped by canonical URL, so the common GreasyFork shape
+// (`@downloadURL` = the `.user.js` we installed from, `@updateURL` =
+// the sibling `.meta.js`) yields one target, not two.
+export function probeTargets(header, fileUrl) {
+    if (!header)
+        return [];
+    // A `file://` script canonicalizes to null and simply never matches
+    // an http(s) target, which is the right answer.
+    const own = canonicalProbeUrl(fileUrl);
+    const byUrl = new Map();
+    for (const kind of ['update', 'download']) {
+        const url = canonicalProbeUrl(getValue(header, `${kind}URL`));
+        if (!url || url === own)
+            continue;
+        const existing = byUrl.get(url);
+        if (existing)
+            existing.kinds.push(kind);
+        else
+            byUrl.set(url, { url, kinds: [kind] });
+    }
+    return [...byUrl.values()];
+}
+// Whether the stored probes still stand in for a fresh check. Stale in
+// either direction, because both mean the stored set no longer
+// describes what the script declares:
+//
+//   - a target with no row, or a row aged past the interval — the
+//     normal case, and what makes a newly-added `@updateURL` get
+//     probed on the next check rather than in six hours;
+//   - a row whose URL is no longer a target — the script dropped that
+//     header, and leaving the row would keep reporting OUTDATED
+//     against a URL it no longer names.
+export function probesAreFresh(probes, targets, now) {
+    const stored = probes ?? [];
+    if (targets.length === 0)
+        return stored.length === 0;
+    const targetUrls = new Set(targets.map((t) => t.url));
+    if (stored.some((p) => !targetUrls.has(p.url)))
+        return false;
+    const byUrl = new Map(stored.map((p) => [p.url, p]));
+    return targets.every((t) => {
+        const probe = byUrl.get(t.url);
+        return probe !== undefined && now - probe.checkedAt < PROBE_MIN_INTERVAL_MS;
+    });
+}
+// The probe that says our copy is behind, or null when none does.
+// Picks the highest version among those ahead of us, so a script whose
+// update and download URLs disagree is judged against the further-ahead
+// one — being told about the smaller gap would understate it.
+export function outdatedProbe(loadedVersion, probes) {
+    let furthestAhead = null;
+    for (const probe of probes ?? []) {
+        if (versionRelation(loadedVersion, probe.version) !== 'newer')
+            continue;
+        if (!furthestAhead || versionRelation(furthestAhead.version, probe.version) === 'newer') {
+            furthestAhead = probe;
+        }
+    }
+    return furthestAhead;
+}
+// Row label for a probe: "update URL" or "download URL".
+//
+// When ONE url is named by both headers the label says "update URL"
+// rather than spelling out both. `@updateURL` is the header that means
+// "check here for a new version", so it is the accurate name for what
+// we did; `@downloadURL` naming the same file is a detail of the
+// script's headers, not of the check. Spelling out both made the
+// longest label in the panel, for a distinction the reader can't act
+// on — the row's tooltip carries the URL either way.
+//
+// No ambiguity with a plain update probe: the combined form only
+// exists when the two headers resolve to the same URL, and two probes
+// for one URL is exactly what it's collapsing.
+export function probeLabel(kinds) {
+    return kinds.includes('update') ? 'update URL' : 'download URL';
+}

package/lib/build-info.json

@@ -0,0 +1 @@
+{"source":"/home/jshute/dev/SourceMonkey3"}

package/lib/bytes.d.ts

@@ -0,0 +1,3 @@
+export declare function sha256Hex(data: string | ArrayBuffer | Uint8Array<ArrayBuffer>): Promise<string>;
+export declare function base64ToBytes(base64: string): ArrayBuffer;
+export declare function bytesToBase64(bytes: Uint8Array): string;

package/lib/bytes.js

@@ -0,0 +1,37 @@
+// Small byte / crypto helpers shared across modules so the SHA-256 and
+// binary→base64 logic lives in one place (script content hashes in
+// script-store, @require/@resource byte hashes + transport in
+// external-files, GM_xmlhttpRequest response transport in gm-xhr).
+// SHA-256 → lowercase hex. Accepts a string (UTF-8 encoded first) or
+// bytes. Async because SubtleCrypto has no sync form on the web
+// platform.
+export async function sha256Hex(data) {
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    let out = '';
+    for (const b of new Uint8Array(digest))
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+// base64→binary. The inverse of `bytesToBase64`, used on the receiving
+// end of message hops that can't carry an ArrayBuffer, and to rebuild a
+// stored `@resource` body when a conditional GET answers 304 and the
+// server sends no bytes of its own.
+export function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes.buffer;
+}
+// Chunked binary→base64. `String.fromCharCode(...hugeArray)` throws
+// "Maximum call stack size exceeded" past ~125k args in V8, so we walk
+// the buffer in 32 KiB slices and concatenate. Linear and bounded.
+export function bytesToBase64(bytes) {
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}

package/lib/channel-placeholder.d.ts

@@ -0,0 +1 @@
+export declare const CHANNEL_KEY_PLACEHOLDER = "__SM_KEY__";

package/lib/channel-placeholder.js

@@ -0,0 +1,5 @@
+// The stand-in for the channel key in the static wrapper files
+// (src/extension/channel.ts swaps the real key in when it registers
+// them). Its own module so the harness, which loads a wrapper under
+// Node, can call the registry gate with it.
+export const CHANNEL_KEY_PLACEHOLDER = '__SM_KEY__';

package/lib/collection-scan.d.ts

@@ -0,0 +1,8 @@
+export interface FoundScript {
+    name: string;
+    relativePath: string;
+    size?: number;
+    mtime?: number;
+}
+export declare const MAX_SCAN_DEPTH = 2;
+export declare const MANIFEST_FILENAME = "script_manifest.json";

package/lib/collection-scan.js

@@ -0,0 +1,17 @@
+// Shared scan primitives used by every collection-kind scanner.
+//
+// Lives in its own module because both `directories.ts` (local
+// directory / manifest scanner) and `github-provider.ts` (Contents-API
+// scanner) need them — importing them directly between the two
+// scanner modules would create a runtime ES-module cycle, since
+// `directories.ts` also imports the github dispatcher from
+// `github-provider.ts`.
+// How many subdirectory levels below the root a scanner walks before
+// stopping. Applies to local directory collections AND GitHub directory
+// collections (the cost model is different but the cap keeps both
+// bounded).
+export const MAX_SCAN_DEPTH = 2;
+// The one and only filename SourceMonkey recognises as a userscript
+// manifest. Lives here (not in `directories.ts`) so `github-provider.ts`
+// can import it without forming a runtime cycle with `directories.ts`.
+export const MANIFEST_FILENAME = 'script_manifest.json';

package/lib/composed-source.d.ts

@@ -0,0 +1,28 @@
+import type { StoredScript } from './script-build.js';
+import type { MappedSegment } from './source-map.js';
+export interface ComposedSource {
+    text: string;
+    segments: MappedSegment[];
+    lineCount: number;
+    mainStart: number;
+}
+export interface ComposeOptions {
+    requireUrls?: readonly string[];
+    mainUrl?: string;
+    startLine?: number;
+}
+export declare const USER_SOURCE_START_LINE = 1;
+export declare function composeSource(script: StoredScript, opts?: ComposeOptions): ComposedSource;
+export interface StackLayout {
+    entryUrl: string;
+    segments: readonly MappedSegment[];
+    lineCount: number;
+}
+export declare function stackLayout(script: StoredScript, logLabel: string): StackLayout;
+export declare function composeRequiredBody(script: StoredScript): string;
+export interface ParseCheckSource {
+    text: string;
+    segments: MappedSegment[];
+    lineCount: number;
+}
+export declare function buildParseCheckSource(script: StoredScript): ParseCheckSource;

package/lib/composed-source.js

@@ -0,0 +1,205 @@
+// ---------- Concatenated user source (requires + body) ----------
+//
+// Every prefetched `@require` body, in declaration order, in front of
+// the **full on-disk script source** (leadingText + headerText +
+// bodyText). This is the single arrangement every run path uses:
+//
+//   - the default registration (`wrapCombinedEntry` → one js[] entry);
+//   - the reload-fast-path swap eval (`buildSwapEvalBody`), where
+//     `handleCheckPending` in background.ts sends the same text as the
+//     run-new body.
+//
+// Concatenation IS the feature, not an implementation detail: one
+// script means one lexical scope, so a library's top-level
+// `const`/`let`/`class` is simply visible to the main body — the same
+// thing TM/VM get by concatenating into one IIFE. See
+// docs/injection-modes.md for what the separate-entries arrangement
+// cost us instead.
+//
+// A `;\n` separator between segments guards the seam against ASI
+// (Automatic Semicolon Insertion). ASI won't fire when the next line
+// could continue the previous statement, so a library ending in an
+// expression followed by a body opening with `(`, `[`, `` ` ``, `+`,
+// `-` or `/` would parse as a single statement. Each file was fine on
+// its own; concatenation is what creates the hazard.
+//
+// The leading `// @require <url>` per require makes the concatenated
+// code easier to scan when no source map is applied. Line comment (not
+// block) so URLs with `*/` in their path don't prematurely close it.
+//
+// ---------- Why this lives in its own module ----------
+//
+// Several callers need to agree on the layout, and they live in
+// different extension contexts:
+//
+//   - `src/extension/injector.ts` (service worker) emits the registered entry
+//     and its source map.
+//   - `background.ts`'s swap path emits the same text for `(0,eval)`.
+//   - `src/extension/userscript.ts` (the viewer page) re-derives the SAME
+//     segment list to map `Error.stack` line numbers in the Log tab
+//     back to the original file — V8 leaves `err.stack` in generated
+//     coordinates even when it has the map. See docs/script-log.md.
+//
+// The viewer recomputes rather than reading a persisted map because
+// the inputs are already on the `StoredScript` row it has loaded, and
+// a persisted copy would be one more thing to invalidate. Sharing this
+// one function is what keeps "where line N came from" a single answer
+// instead of two that can drift.
+import { joinFullSource } from './userscript-header.js';
+import { buildRequireSourceUrl, buildSourceUrl } from './script-source-url.js';
+// ---------- The two layouts, and why the viewer can tell them apart ----------
+//
+// **With `@require`s.** The preamble (GM bindings, prelude, wrap head)
+// occupies generated line 0 on its own and the concatenated user
+// source starts at `USER_SOURCE_START_LINE`. Line numbers shift, so
+// the entry carries a source map and the viewer remaps stack refs
+// through the segment list.
+//
+// **Without `@require`s.** Nothing is concatenated, so nothing may
+// shift: the body's first line SHARES generated line 0 with the
+// preamble, making generated line N equal original line N. No map is
+// emitted and the viewer passes refs through untouched.
+//
+// The viewer distinguishes the two by whether there are segments at
+// all — `composeSource` returns none for a script without requires —
+// so it never has to know which run path produced the code. That only
+// holds while `wrapCombinedEntry` and `buildSwapEvalBody` agree on
+// BOTH layouts. They are the only two producers; keep them in step.
+//
+// The no-require layout costs one thing, deliberately: the body's
+// first line shares a physical line with the preamble, so a frame
+// reported at line 1 carries a column offset by the preamble's length.
+// Line 1 of a userscript is its `// ==UserScript==` marker, so this
+// has never been observed; the code view suppresses the column accent
+// there rather than showing a wrong one.
+export const USER_SOURCE_START_LINE = 1;
+export function composeSource(script, opts = {}) {
+    const mainSource = joinFullSource(script.leadingText ?? '', script.headerText ?? '', script.bodyText);
+    const requires = script.requires ?? [];
+    const startLine = opts.startLine ?? 0;
+    if (requires.length === 0) {
+        return {
+            text: mainSource,
+            segments: [],
+            lineCount: countLines(mainSource),
+            mainStart: 0,
+        };
+    }
+    // Build the text incrementally and derive every line number from
+    // what has ACTUALLY been emitted, rather than adding up expected
+    // line counts alongside a `join()`. The two drift: a require whose
+    // source ends in a lone `\r` fuses with a joining `\n` into a single
+    // CRLF, so one terminator appears where the arithmetic assumed two
+    // and every mapping from that seam onward — including the whole user
+    // body — shifts by a line. CR-only line endings are exactly the
+    // population `\r` is in `LINE_TERMINATORS` for, and nothing
+    // normalizes newlines on the way in (file-loader stores the decoded
+    // bytes verbatim).
+    const segments = [];
+    let text = '';
+    // 0-based generated line that the NEXT character appended will land
+    // on. `countLines('')` is 1, so an empty buffer is line 0.
+    const nextLine = () => startLine + countLines(text) - 1;
+    for (const [i, r] of requires.entries()) {
+        text += `// @require ${r.url}\n`;
+        const url = opts.requireUrls?.[i];
+        if (url) {
+            segments.push({
+                url,
+                content: r.source,
+                generatedLine: nextLine(),
+                lineCount: countLines(r.source),
+            });
+        }
+        // The trailing-`\r` guard: append the extra `\n` here so the
+        // source's own last line stays a line of its own, instead of being
+        // swallowed by the separator that follows.
+        text += r.source.endsWith('\r') ? `${r.source}\n` : r.source;
+        // Terminate the source's last line, then the `;` seam guard on a
+        // line of its own.
+        text += '\n;\n';
+    }
+    if (opts.mainUrl) {
+        segments.push({
+            url: opts.mainUrl,
+            content: mainSource,
+            generatedLine: nextLine(),
+            lineCount: countLines(mainSource),
+        });
+    }
+    const mainStart = text.length;
+    text += mainSource;
+    return { text, segments, lineCount: countLines(text), mainStart };
+}
+export function stackLayout(script, logLabel) {
+    const entryUrl = buildSourceUrl(logLabel);
+    const { segments, lineCount } = composeSource(script, {
+        requireUrls: (script.requires ?? []).map((r) => buildRequireSourceUrl(logLabel, r.url)),
+        mainUrl: entryUrl,
+        startLine: USER_SOURCE_START_LINE,
+    });
+    return { entryUrl, segments, lineCount };
+}
+// Count lines the way V8 does, which is what the source map has to
+// agree with. Counting only `\n` silently shifts every mapping after
+// the offending character:
+//
+//   - a lone `\r` is a line terminator (files with mangled endings);
+//   - so are U+2028 / U+2029, and V8 counts a RAW U+2028 as a break
+//     even inside a string literal (legal since ES2019, and minified
+//     CDN bundles do embed them).
+//
+// `\r\n` must count as one, hence the alternation order.
+const LINE_TERMINATORS = /\r\n|[\n\r\u2028\u2029]/g;
+// `buildParseCheckSource` below measures its own preamble with it: a
+// parse-check line offset that counted terminators differently from the
+// segment list it is compared against would misattribute every error in
+// the file.
+function countLines(text) {
+    if (text === '')
+        return 1;
+    const matches = text.match(LINE_TERMINATORS);
+    return matches ? matches.length + 1 : 1;
+}
+// Public entry point for the swap-eval path, which needs the text only.
+export function composeRequiredBody(script) {
+    return composeSource(script).text;
+}
+export function buildParseCheckSource(script) {
+    // A blank first line of our own, so the user's first line is never at
+    // offset 0: a `#!` hashbang is legal only there, so it stays the
+    // syntax error it also is in the real injected entry (which wraps the
+    // source), and the location probes can't be handed a source that
+    // parses as a shebang script. Blank, not a statement, so a leading
+    // `"use strict"` still applies, as in the injected entry (see
+    // USER_SCOPE_OPEN in injector.ts). The offset below is derived from it rather than
+    // assumed to be 1 — the same discipline `composeSource` applies
+    // internally, and for the same reason: assumed line counts drift
+    // from emitted ones.
+    const preamble = '\n';
+    const startLine = countLines(preamble) - 1;
+    const requires = script.requires ?? [];
+    const composed = composeSource(script, {
+        requireUrls: requires.map((r) => r.url),
+        mainUrl: script.relativePath,
+        startLine,
+    });
+    return {
+        text: preamble + composed.text,
+        // `composeSource` emits no segments for a script with no
+        // `@require`s — the viewer keys "pass stack refs through unmapped"
+        // off exactly that, so it stays as it is. Here the opposite is
+        // wanted: one segment for the body means every reported line
+        // resolves through the same lookup, with no second code path for
+        // the majority of scripts.
+        segments: composed.segments.length > 0
+            ? composed.segments
+            : [{
+                    url: script.relativePath,
+                    content: composed.text,
+                    generatedLine: startLine,
+                    lineCount: composed.lineCount,
+                }],
+        lineCount: startLine + composed.lineCount,
+    };
+}

package/lib/debug-log.d.ts

@@ -0,0 +1,9 @@
+export declare const DEBUG_LOGGING_KEY = "smDebugLogging";
+export declare function isDebugLoggingEnabled(): boolean;
+export declare function _setDebugLoggingForTests(value: boolean): void;
+export declare function loadDebugLoggingFlag(): Promise<void>;
+export declare function debugLoggingPending(): boolean;
+export declare function debugLoggingSettled(): Promise<boolean>;
+export declare function installDebugLoggingListener(): void;
+export declare function dlog(...args: unknown[]): void;
+export declare function dwarn(...args: unknown[]): void;

package/lib/debug-log.js

@@ -0,0 +1,75 @@
+// Debug-only console logging gate.
+//
+// Several lifecycle messages (per-navigation match list, per-refresh
+// "update check" / "no change") are useful when diagnosing matcher or
+// updater behavior but far too noisy for normal use — they fire on
+// every click. They're off by default and gated through `dlog` /
+// `dwarn`. Flip on by setting `chrome.storage.local`'s
+// `smDebugLogging` key to `true` (e.g. from the SW DevTools console:
+// `chrome.storage.local.set({ smDebugLogging: true })`).
+export const DEBUG_LOGGING_KEY = 'smDebugLogging';
+let enabled = false;
+export function isDebugLoggingEnabled() {
+    return enabled;
+}
+// Test/debug hook. Production callers should toggle the storage key
+// instead so the change persists and is observed via onChanged.
+export function _setDebugLoggingForTests(value) {
+    enabled = value;
+}
+// Settles once the setting has been read in this context.
+let loading = null;
+let loaded = false;
+export function loadDebugLoggingFlag() {
+    loading = (async () => {
+        try {
+            const got = await chrome.storage.local.get(DEBUG_LOGGING_KEY);
+            enabled = got[DEBUG_LOGGING_KEY] === true;
+        }
+        catch {
+            enabled = false;
+        }
+        loaded = true;
+    })();
+    return loading;
+}
+// Whether the setting is still being read: a line about work done before
+// then can wait for `debugLoggingSettled` rather than be dropped.
+export function debugLoggingPending() {
+    return loading !== null && !loaded;
+}
+// Whether debug logging is on, once the setting has been read (at once
+// in a context that never reads it).
+export async function debugLoggingSettled() {
+    await loading;
+    return enabled;
+}
+// Idempotent, matching `match-index.ts`'s storage listener. Several
+// contexts install this (the worker and the extension pages), and a
+// context that called twice would double every flag update.
+let listenerInstalled = false;
+export function installDebugLoggingListener() {
+    if (listenerInstalled)
+        return;
+    listenerInstalled = true;
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+        if (areaName !== 'local')
+            return;
+        const change = changes[DEBUG_LOGGING_KEY];
+        if (!change)
+            return;
+        enabled = change.newValue === true;
+    });
+}
+export function dlog(...args) {
+    if (enabled)
+        console.log(...args);
+}
+export function dwarn(...args) {
+    // console.info (not console.warn / .error) — see background.ts sm:error
+    // handler for the rationale: Chrome surfaces SW warn+error into the
+    // chrome://extensions/?errors panel, which should be reserved for
+    // actual extension bugs, not SourceMonkey's own diagnostic chatter.
+    if (enabled)
+        console.info(...args);
+}