Merge pull request #1097 from morluto/fix/web-runtime-script-initiators

fix(browser): treat module-import initiator positions as script positions

docs/web-runtime.md

@@ -20,9 +20,9 @@ Results retain:
 - The selected target, frame and document loader identity; local armed/end timestamps and separate backend monotonic coverage timestamps.
 - Every admitted producer function/block range, exclusive end offset and execution count in UTF-16 code units, with verified bounds when exact text is available. Nested/overlapping counts are preserved and must not be summed.
 - Main-document script inventory, exact session script IDs, resource start coordinates, sourceURL/source-map declarations, producer hash and independently computed UTF-8 text digest.
-- Armed-window requests from the selected main frame and selected origins, complete reported initiator objects (including stack hierarchy/descriptions), derived callsites, exact script-ID associations and unresolved async parent IDs. Source association does not establish UI causality. Callsite and listener `line_number`/`column_number` values are CDP's zero-based lines and UTF-16 columns in the resource named by `url`. With a `script_id`, that is the script's enclosing resource: the script file for an external script, or the HTML document for an inline script. `resource_start` is where the script text starts in that resource. A callsite with an empty `script_id` comes from the request's reported initiator rather than a script call frame, such as markup that the parser read in a document, and has no script position. `trace_web_source_location` takes one-based, script-relative lines and zero-based UTF-16 columns.
+- Armed-window requests from the selected main frame and selected origins, complete reported initiator objects (including stack hierarchy/descriptions), derived callsites, exact script-ID associations and unresolved async parent IDs. Source association does not establish UI causality. Callsite and listener `line_number`/`column_number` values are CDP's zero-based lines and UTF-16 columns in the resource named by `url`. With a `script_id`, that is the script's enclosing resource: the script file for an external script, or the HTML document for an inline script. `resource_start` is where the script text starts in that resource. A callsite with an empty `script_id` comes from the request's reported initiator rather than a script call frame, such as markup that the parser read in a document or a module import in a script file. It still locates a position in `url`, but has no session-script association, so it cannot be joined to captured source or `resource_start`. `trace_web_source_location` takes one-based, script-relative lines and zero-based UTF-16 columns.
 
-These conversions apply only to positions with a nonempty `script_id`. For an external script, use `line = line_number + 1` and keep `column = column_number`. For an inline script, use `line = line_number - resource_start.line_number + 1`. Subtract `resource_start.column_number` from `column_number` only when `line_number === resource_start.line_number`; keep the reported column on later lines. Columns remain zero-based. This conversion requires known source-start and column coordinates; preserve unavailable coordinates as unknown.
+For an external script, where `url` is the script file, use `line = line_number + 1` and keep `column = column_number`; this also applies to an empty-`script_id` initiator position in a script file. For an inline script, which requires a `script_id` and its `resource_start`, use `line = line_number - resource_start.line_number + 1`. Subtract `resource_start.column_number` from `column_number` only when `line_number === resource_start.line_number`; keep the reported column on later lines. Columns remain zero-based. This conversion requires known source-start and column coordinates; preserve unavailable coordinates as unknown.
 
 The coverage counter interval starts at backend acceptance before the armed receipt and ends at the resetting sample after the local timer. Counts may include execution during these command intervals; request events are restricted to the locally armed window. The result retains both backend timestamps and the distinct local clock.
 

src/domain/webRuntime.test.ts

@@ -20,9 +20,7 @@ describe("web runtime coordinate contract", () => {
       ),
     });
     expect(location.script_id).toMatchObject({
-      description: expect.stringContaining(
-        "empty for a position taken from a request initiator",
-      ),
+      description: expect.stringContaining("no session-script association"),
     });
     expect(location.column_number).toMatchObject({
       description: expect.stringContaining("Zero-based UTF-16 column"),

src/domain/webRuntime.ts

@@ -8,15 +8,17 @@ import { jsonObjectSchema } from "./jsonValue.js";
 
 // CDP positions are zero-based and relative to the resource named by url.
 // With a script ID that is the script's enclosing resource: the script file,
-// or the HTML document for an inline script. An empty script ID marks the
-// position a request's initiator reported, such as parser markup, which has
-// no script to convert. trace_web_source_location takes one-based,
-// script-relative lines, so the advertised units keep callers from passing a
-// position off by one or by the inline script's offset.
+// or the HTML document for an inline script. An empty script ID marks a
+// position a request initiator reported, such as parser markup or a module
+// import in a script file; it still locates url, but has no session-script
+// association to join captured source or resource_start.
+// trace_web_source_location takes one-based, script-relative lines, so the
+// advertised units keep callers from passing a position off by one or by an
+// inline script's offset.
 const SCRIPT_ID =
-  "CDP session script ID; empty for a position taken from a request initiator rather than a script call frame.";
+  "CDP session script ID; empty for a position a request initiator reported, which has no session-script association for joining captured source or resource_start.";
 const RESOURCE_LINE =
-  "Zero-based line in the resource named by url, as reported by CDP. With a script_id this is the script's enclosing resource (the script file, or the HTML document for an inline script); with an empty script_id it is the request initiator's reported position, such as parser markup in a document.";
+  "Zero-based line in the resource named by url, as reported by CDP: the script file for an external script (including a module-import initiator), or the HTML document for an inline script or parser markup.";
 const RESOURCE_COLUMN =
   "Zero-based UTF-16 column on that line of the resource named by url, as reported by CDP.";
 const START_LINE =