fix(browser): keep initiator callsites out of script coordinate guidance (#1096)

observe_web_execution also derives callsites from a request's reported
initiator, such as an image the parser found in HTML or a module import,
with an empty script_id. Those positions point into the initiating
resource, not a script, so the "script's enclosing resource" wording and
source-map conversion did not apply to them. Describe the coordinates as
relative to the resource named by url, explain empty script IDs, and
limit the documented conversion to positions with a script_id.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

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 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. `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, and has no script position. `trace_web_source_location` takes one-based, script-relative lines and zero-based UTF-16 columns.
 
-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.
+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.
 
 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

@@ -16,7 +16,12 @@ describe("web runtime coordinate contract", () => {
     const location = properties(webRuntimeLocationSchema);
     expect(location.line_number).toMatchObject({
       description: expect.stringContaining(
-        "Zero-based line in the script's enclosing resource",
+        "Zero-based line in the resource named by url",
+      ),
+    });
+    expect(location.script_id).toMatchObject({
+      description: expect.stringContaining(
+        "empty for a position taken from a request initiator",
       ),
     });
     expect(location.column_number).toMatchObject({

src/domain/webRuntime.ts

@@ -6,15 +6,19 @@ import {
 import { browserVersionSchema } from "./browserObservationSchemas.js";
 import { jsonObjectSchema } from "./jsonValue.js";
 
-// CDP positions are zero-based and relative to the script's enclosing
-// resource: the script file for an external script, or the HTML document for
-// an inline script. trace_web_source_location takes one-based,
+// 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.
+const SCRIPT_ID =
+  "CDP session script ID; empty for a position taken from a request initiator rather than a script call frame.";
 const RESOURCE_LINE =
-  "Zero-based line in the script's enclosing resource (the script file for an external script, or the HTML document for an inline script), as reported by CDP.";
+  "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.";
 const RESOURCE_COLUMN =
-  "Zero-based UTF-16 column on that line of the enclosing resource, as reported by CDP.";
+  "Zero-based UTF-16 column on that line of the resource named by url, as reported by CDP.";
 const START_LINE =
   "Zero-based line where the script text starts in its enclosing resource (the HTML document for an inline script).";
 const START_COLUMN =
@@ -63,7 +67,7 @@ export type WebRuntimeSource = z.infer<typeof webRuntimeSourceSchema>;
 
 /** Producer callsite coordinates are zero-based resource lines and UTF-16 columns. */
 export const webRuntimeLocationSchema = z.object({
-  script_id: z.string(),
+  script_id: z.string().describe(SCRIPT_ID),
   url: z.string().nullable(),
   line_number: z.number().int().min(0).describe(RESOURCE_LINE),
   column_number: z.number().int().min(0).nullable().describe(RESOURCE_COLUMN),