@ifc-lite/load-trace 0.0.0-stage → 0.2.0

package/dist/messages.d.ts

@@ -0,0 +1,43 @@
+import { type PerfCounterRegistry } from './counters.js';
+/**
+ * Worker message accounting (#6957): the ONE wrapper every loader worker
+ * boundary goes through. It patches the worker's `postMessage` (main -> worker,
+ * `out`) and listens for its messages (worker -> main, `in`), adding per label:
+ *
+ *   msg.<label>.<dir>.count          messages
+ *   msg.<label>.<dir>.cloneBytes     estimated structured-clone payload
+ *   msg.<label>.out.transferBytes    ArrayBuffers in the transfer list (moved, not copied)
+ *   msg.<label>.in.bufferBytes       ArrayBuffers received: the receiver cannot
+ *                                    tell a transferred buffer from a cloned one
+ *   msg.<label>.<dir>.sharedBytes    SharedArrayBuffers (shared, never copied)
+ *
+ * With counters off at wrap time it returns the worker untouched, so the
+ * production path keeps the native `postMessage`. Load-trace control messages
+ * are not counted (they exist only while tracing).
+ */
+export interface MessageEndpoint {
+    postMessage(message: unknown, transfer?: unknown): void;
+    /** Absent on a bare port double: then only the outbound side is counted. */
+    addEventListener?(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+export interface CloneEstimate {
+    cloneBytes: number;
+    transferBytes: number;
+    sharedBytes: number;
+}
+/**
+ * Estimate what structured clone serialises for `value`. Typed-array views
+ * count their WHOLE backing buffer once (clone copies the buffer, not the
+ * view's window); strings count one byte per code unit; numbers 8. Iterative,
+ * so a deep payload cannot overflow the stack.
+ */
+export declare function estimateCloneBytes(value: unknown, transferred?: (buffer: ArrayBuffer) => boolean): CloneEstimate;
+export declare function accountWorkerMessages<W extends MessageEndpoint>(worker: W, label: string | (() => string), registry?: PerfCounterRegistry): W;
+/** Attach sender-side accounting once tracing is enabled in a worker (#6993).
+ * Publish increments before each output: the host may terminate this realm
+ * immediately on receipt of a terminal message. Trace-control posts bypass
+ * accounting and flushing, so publishing counters cannot recurse. */
+export declare function accountWorkerOutput(endpoint: MessageEndpoint, registry: PerfCounterRegistry, flush: () => void): void;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxD,4EAA4E;IAC5E,gBAAgB,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACxF;AAED,MAAM,WAAW,aAAa;IAAG,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AAYjG;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EAAE,WAAW,GAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAqB,GAC1E,aAAa,CA+Bf;AAED,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,eAAe,EAC7D,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAAE,QAAQ,GAAE,mBAAkC,GACtF,CAAC,CAkCH;AAED;;;qEAGqE;AACrE,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,IAAI,GAC1E,IAAI,CASN"}

package/dist/messages.js

@@ -0,0 +1,137 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { perfCounters } from './counters.js';
+const isTraceControl = (message) => {
+    const type = message?.type;
+    return typeof type === 'string' && type.startsWith('load-trace:');
+};
+function transferSet(arg) {
+    const list = Array.isArray(arg) ? arg : arg?.transfer;
+    return new Set(list ?? []);
+}
+/**
+ * Estimate what structured clone serialises for `value`. Typed-array views
+ * count their WHOLE backing buffer once (clone copies the buffer, not the
+ * view's window); strings count one byte per code unit; numbers 8. Iterative,
+ * so a deep payload cannot overflow the stack.
+ */
+export function estimateCloneBytes(value, transferred = () => false) {
+    const out = { cloneBytes: 0, transferBytes: 0, sharedBytes: 0 };
+    const seen = new Set();
+    const stack = [value];
+    while (stack.length > 0) {
+        const v = stack.pop();
+        switch (typeof v) {
+            case 'string':
+                out.cloneBytes += v.length;
+                continue;
+            case 'number':
+            case 'bigint':
+                out.cloneBytes += 8;
+                continue;
+            case 'boolean':
+                out.cloneBytes += 1;
+                continue;
+            case 'object': break;
+            default: continue;
+        }
+        if (v === null || seen.has(v))
+            continue;
+        seen.add(v);
+        if (ArrayBuffer.isView(v)) {
+            stack.push(v.buffer);
+            continue;
+        }
+        if (typeof SharedArrayBuffer !== 'undefined' && v instanceof SharedArrayBuffer) {
+            out.sharedBytes += v.byteLength;
+            continue;
+        }
+        if (v instanceof ArrayBuffer) {
+            if (transferred(v))
+                out.transferBytes += v.byteLength;
+            else
+                out.cloneBytes += v.byteLength;
+            continue;
+        }
+        if (Array.isArray(v)) {
+            for (let i = 0; i < v.length; i++)
+                stack.push(v[i]);
+            continue;
+        }
+        if (v instanceof Map) {
+            for (const [k, e] of v)
+                stack.push(k, e);
+            continue;
+        }
+        if (v instanceof Set) {
+            for (const e of v)
+                stack.push(e);
+            continue;
+        }
+        if (v instanceof Date) {
+            out.cloneBytes += 8;
+            continue;
+        }
+        for (const key of Object.keys(v)) {
+            out.cloneBytes += key.length;
+            stack.push(v[key]);
+        }
+    }
+    return out;
+}
+export function accountWorkerMessages(worker, label, registry = perfCounters) {
+    if (!registry.enabled)
+        return worker;
+    // A pooled worker (#7036) changes role between loads, so it passes a getter.
+    const prefixOf = typeof label === 'function' ? () => `msg.${label()}` : () => `msg.${label}`;
+    const nativePost = worker.postMessage.bind(worker);
+    const counted = (message, transfer) => {
+        if (!isTraceControl(message)) {
+            const list = transferSet(transfer);
+            const est = estimateCloneBytes(message, (b) => list.has(b));
+            // A transfer list can move a buffer that is not reachable from the
+            // payload. Count the list itself before postMessage detaches it (#6993).
+            let transferBytes = 0;
+            for (const value of list)
+                if (value instanceof ArrayBuffer)
+                    transferBytes += value.byteLength;
+            const prefix = prefixOf();
+            registry.add(`${prefix}.out.count`);
+            registry.add(`${prefix}.out.cloneBytes`, est.cloneBytes);
+            registry.add(`${prefix}.out.transferBytes`, transferBytes);
+            registry.add(`${prefix}.out.sharedBytes`, est.sharedBytes);
+        }
+        nativePost(message, transfer);
+    };
+    worker.postMessage = counted;
+    worker.addEventListener?.('message', ({ data }) => {
+        if (isTraceControl(data))
+            return;
+        // A received ArrayBuffer may have been transferred or cloned; this side
+        // cannot tell, so every buffer lands in bufferBytes, the rest in cloneBytes.
+        const est = estimateCloneBytes(data, () => true);
+        const prefix = prefixOf();
+        registry.add(`${prefix}.in.count`);
+        registry.add(`${prefix}.in.cloneBytes`, est.cloneBytes);
+        registry.add(`${prefix}.in.bufferBytes`, est.transferBytes);
+        registry.add(`${prefix}.in.sharedBytes`, est.sharedBytes);
+    });
+    return worker;
+}
+/** Attach sender-side accounting once tracing is enabled in a worker (#6993).
+ * Publish increments before each output: the host may terminate this realm
+ * immediately on receipt of a terminal message. Trace-control posts bypass
+ * accounting and flushing, so publishing counters cannot recurse. */
+export function accountWorkerOutput(endpoint, registry, flush) {
+    const nativePost = endpoint.postMessage.bind(endpoint);
+    const port = accountWorkerMessages({
+        postMessage(message, transfer) {
+            if (!isTraceControl(message))
+                flush();
+            nativePost(message, transfer);
+        },
+    }, 'worker', registry);
+    endpoint.postMessage = port.postMessage;
+}
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"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"}

package/dist/perf-sink.d.ts

@@ -0,0 +1,15 @@
+import type { TraceAttrValue } from './types.js';
+/** Namespace for every User Timing entry this package writes. */
+export declare const MEASURE_PREFIX = "ifc:";
+/** Where finished spans are mirrored (the browser's User Timing buffer by default). */
+export interface PerfSink {
+    measure(name: string, start: number, end: number, detail: Record<string, TraceAttrValue>): void;
+}
+/**
+ * Mirror spans into `performance.measure`. Prefers the instance method but
+ * falls back to `Performance.prototype.measure`: the viewer's DEV bootstrap
+ * deliberately nulls the INSTANCE property so React's dev render tracker stays
+ * off (apps/viewer/AGENTS.md), and the prototype is untouched by that.
+ */
+export declare function createPerfSink(perf?: Performance | undefined): PerfSink | null;
+//# sourceMappingURL=perf-sink.d.ts.map

package/dist/perf-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-sink.d.ts","sourceRoot":"","sources":["../src/perf-sink.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,iEAAiE;AACjE,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC,uFAAuF;AACvF,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI,CAAC;CACjG;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,WAAW,GAAG,SAAkC,GAAG,QAAQ,GAAG,IAAI,CAqBtG"}

package/dist/perf-sink.js

@@ -0,0 +1,37 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/** Namespace for every User Timing entry this package writes. */
+export const MEASURE_PREFIX = 'ifc:';
+/**
+ * Mirror spans into `performance.measure`. Prefers the instance method but
+ * falls back to `Performance.prototype.measure`: the viewer's DEV bootstrap
+ * deliberately nulls the INSTANCE property so React's dev render tracker stays
+ * off (apps/viewer/AGENTS.md), and the prototype is untouched by that.
+ */
+export function createPerfSink(perf = globalThis.performance) {
+    if (!perf)
+        return null;
+    const proto = typeof Performance !== 'undefined' ? Performance.prototype : undefined;
+    const instance = perf;
+    const measure = typeof instance.measure === 'function' ? instance.measure : proto?.measure;
+    if (typeof measure !== 'function')
+        return null;
+    let warned = false;
+    return {
+        measure(name, start, end, detail) {
+            // User Timing rejects negative timestamps and end < start.
+            const s = Math.max(0, start);
+            try {
+                measure.call(perf, name, { start: s, end: Math.max(s, end), detail });
+            }
+            catch (err) {
+                if (!warned) {
+                    warned = true;
+                    console.warn('[load-trace] performance.measure failed; span tree still recorded', err);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=perf-sink.js.map

package/dist/perf-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-sink.js","sourceRoot":"","sources":["../src/perf-sink.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAI/D,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AASrC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgC,UAAU,CAAC,WAAW;IACnF,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,KAAK,GAAG,OAAO,WAAW,KAAK,WAAW,CAAC,CAAC,CAAE,WAAW,CAAC,SAAgD,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7H,MAAM,QAAQ,GAAG,IAA0C,CAAC;IAC5D,MAAM,OAAO,GAAG,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC;IAC3F,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,OAAO;QACL,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM;YAC9B,2DAA2D;YAC3D,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC7B,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,GAAG,IAAI,CAAC;oBACd,OAAO,CAAC,IAAI,CAAC,mEAAmE,EAAE,GAAG,CAAC,CAAC;gBACzF,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tree.d.ts

@@ -0,0 +1,11 @@
+import type { LoadTraceSnapshot, TraceSpan } from './types.js';
+export interface SpanTreeNode {
+    span: TraceSpan;
+    children: SpanTreeNode[];
+}
+/**
+ * Nest a snapshot's flat span list by `parentId`. Returns the root's direct
+ * children, each list ordered by start time (ties keep recording order).
+ */
+export declare function buildSpanTree(snapshot: LoadTraceSnapshot): SpanTreeNode[];
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,YAAY,EAAE,CAczE"}

package/dist/tree.js

@@ -0,0 +1,25 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Nest a snapshot's flat span list by `parentId`. Returns the root's direct
+ * children, each list ordered by start time (ties keep recording order).
+ */
+export function buildSpanTree(snapshot) {
+    const nodes = new Map();
+    for (const span of snapshot.spans)
+        nodes.set(span.id, { span, children: [] });
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = node.span.parentId === null ? undefined : nodes.get(node.span.parentId);
+        (parent ? parent.children : roots).push(node);
+    }
+    const order = (list) => {
+        list.sort((a, b) => a.span.start - b.span.start || a.span.id - b.span.id);
+        for (const n of list)
+            order(n.children);
+    };
+    order(roots);
+    return roots;
+}
+//# sourceMappingURL=tree.js.map

package/dist/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAS/D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAA2B;IACvD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK;QAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvF,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,IAAoB,EAAQ,EAAE;QAC3C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1E,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC,CAAC;IACF,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,70 @@
+import type { FrameSummary } from './frames.js';
+/** Attribute values that survive structured clone, JSON and the User Timing `detail`. */
+export type TraceAttrValue = string | number | boolean;
+export type TraceAttrs = Readonly<Record<string, TraceAttrValue>>;
+/**
+ * Per-load attributes (charter #6954). `journey` is the charter journey id
+ * (`J1` cold open, `J2` warm/cache open, `J4` federated add, ...).
+ */
+export interface LoadTraceAttributes {
+    journey?: string;
+    modelKind?: 'primary' | 'federated';
+    cacheTier?: string;
+    loadPath?: string;
+    workerCount?: number;
+    [key: string]: TraceAttrValue | undefined;
+}
+/**
+ * One span on the load timeline. Times are milliseconds on the MAIN thread's
+ * `performance.now()` clock; worker spans are shifted onto it at merge time.
+ */
+export interface TraceSpan {
+    id: number;
+    name: string;
+    /** `main`, or the worker label given to `enableWorkerTrace` (e.g. `geom-0`). */
+    thread: string;
+    start: number;
+    /** `null` while the span is still open. */
+    end: number | null;
+    /** Parent span id; `null` means the load root. */
+    parentId: number | null;
+    /** Milestones start at the load root, so their duration is time-to-milestone. */
+    milestone?: true;
+    attrs?: Record<string, TraceAttrValue>;
+}
+/** JSON-safe copy of one load's span tree (`spans` is flat; `parentId` links it). */
+export interface LoadTraceSnapshot {
+    loadId: string;
+    attrs: LoadTraceAttributes;
+    /** Main-thread `performance.timeOrigin`, so absolute times can be recovered. */
+    timeOrigin: number;
+    start: number;
+    end: number | null;
+    spans: TraceSpan[];
+    /**
+     * Structural counters (#6957) moved while this load was the latest one:
+     * from its start until the next load starts (or the snapshot is taken),
+     * plus every counter its workers posted back. Absent when counters are off.
+     */
+    counters?: Record<string, number>;
+    /** The worker share of `counters`, per worker thread label. */
+    workerCounters?: Record<string, Record<string, number>>;
+    /** Long-frame summary over the same window; absent without a frame monitor. */
+    mainThread?: FrameSummary;
+}
+/** A finished span recorded inside a worker, on that worker's own clock. */
+export interface WorkerSpan {
+    name: string;
+    start: number;
+    end: number;
+    attrs?: Record<string, TraceAttrValue>;
+}
+/** What a worker posts back: its spans plus the clock origin needed to align them. */
+export interface WorkerTracePayload {
+    thread: string;
+    timeOrigin: number;
+    spans: WorkerSpan[];
+    /** Counter increments in the worker since its previous payload (#6957). */
+    counters?: Record<string, number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,yFAAyF;AACzF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iFAAiF;IACjF,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACxC;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,mBAAmB,CAAC;IAC3B,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,+EAA+E;IAC/E,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACxC;AAED,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;+DAE+D"}

package/dist/worker-phases.d.ts

@@ -0,0 +1,44 @@
+import type { TraceAttrs } from './types.js';
+import { type PerfCounterRegistry } from './counters.js';
+import { type MessageEndpoint } from './messages.js';
+import { type TraceSpansMessage } from './worker.js';
+/**
+ * Spans for the phases INSIDE one long worker handler (#6979), where
+ * `createWorkerTraceHost`'s one-span-per-message is too coarse. The parser
+ * worker runs a whole parse in a single `parse` message and the host
+ * terminates it the moment `complete` arrives, so a span posted after the
+ * handler settles would die with the worker: `flush()` posts what has
+ * finished so far, and the worker calls it before any message after which it
+ * may be terminated.
+ *
+ * Enabled by the same `enableWorkerTrace` request as the host. Until then
+ * every method is a null check, so an untraced load pays nothing measurable.
+ */
+export interface WorkerPhaseTrace {
+    readonly enabled: boolean;
+    /** Feed each inbound message first; `true` = it was the enable request (consumed). */
+    accept(data: unknown): boolean;
+    /** Open a span; `-1` when disabled. */
+    begin(name: string, attrs?: TraceAttrs): number;
+    end(token: number, attrs?: TraceAttrs): void;
+    /** Time `fn`; a returned promise ends the span when it settles. Returns `fn`'s result unchanged. */
+    span<T>(name: string, fn: () => T, attrs?: TraceAttrs): T;
+    /**
+     * Sequential phases: end the previous `step` span and open `name` (or just
+     * end it, for `null`). A repeated name keeps the open span, so a progress
+     * callback that reports one phase many times can drive this directly.
+     */
+    step(name: string | null): void;
+    /** Post every finished span now (nothing when there are none). */
+    flush(): void;
+}
+export interface WorkerPhaseTraceOptions {
+    post: (message: TraceSpansMessage) => void;
+    now?: () => number;
+    timeOrigin?: number;
+    counters?: PerfCounterRegistry;
+    /** Worker global; sender accounting starts only after the enable request. */
+    endpoint?: () => MessageEndpoint;
+}
+export declare function createWorkerPhaseTrace(options: WorkerPhaseTraceOptions): WorkerPhaseTrace;
+//# sourceMappingURL=worker-phases.d.ts.map

package/dist/worker-phases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-phases.d.ts","sourceRoot":"","sources":["../src/worker-phases.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,sFAAsF;IACtF,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC/B,uCAAuC;IACvC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAChD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7C,oGAAoG;IACpG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC;IAC1D;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAChC,kEAAkE;IAClE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC3C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,eAAe,CAAC;CAClC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CA2DzF"}

package/dist/worker-phases.js

@@ -0,0 +1,78 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { perfCounters } from './counters.js';
+import { accountWorkerOutput } from './messages.js';
+import { createWorkerSpanRecorder, TRACE_ENABLE_MESSAGE, TRACE_SPANS_MESSAGE, } from './worker.js';
+export function createWorkerPhaseTrace(options) {
+    let recorder = null;
+    let stepName = null;
+    let stepToken = -1;
+    const counters = options.counters ?? perfCounters;
+    let countedEndpoint;
+    const trace = {
+        get enabled() { return recorder !== null; },
+        accept(data) {
+            if (data?.type !== TRACE_ENABLE_MESSAGE)
+                return false;
+            const thread = data.thread;
+            recorder = createWorkerSpanRecorder(typeof thread === 'string' ? thread : 'worker', options.now, options.timeOrigin);
+            stepName = null;
+            stepToken = -1;
+            counters.enable();
+            counters.drain();
+            const endpoint = options.endpoint?.();
+            if (endpoint && endpoint !== countedEndpoint) {
+                accountWorkerOutput(endpoint, counters, () => trace.flush());
+                countedEndpoint = endpoint;
+            }
+            return true;
+        },
+        begin: (name, attrs) => recorder?.begin(name, attrs) ?? -1,
+        end: (token, attrs) => { if (token >= 0)
+            recorder?.end(token, attrs); },
+        span(name, fn, attrs) {
+            if (!recorder)
+                return fn();
+            const token = recorder.begin(name, attrs);
+            let result;
+            try {
+                result = fn();
+            }
+            catch (err) {
+                trace.end(token, { error: true });
+                throw err;
+            }
+            if (isThenable(result)) {
+                // Observes settlement only; the caller still owns the returned promise.
+                result.then(() => trace.end(token), () => trace.end(token, { error: true }));
+            }
+            else {
+                trace.end(token);
+            }
+            return result;
+        },
+        step(name) {
+            if (!recorder || name === stepName)
+                return;
+            trace.end(stepToken);
+            stepName = name;
+            stepToken = name === null ? -1 : recorder.begin(name);
+        },
+        flush() {
+            if (!recorder)
+                return;
+            const payload = recorder.drain();
+            const moved = counters.drain();
+            if (!payload && !moved)
+                return;
+            const out = payload ?? { thread: recorder.thread, timeOrigin: options.timeOrigin ?? performance.timeOrigin, spans: [] };
+            options.post({ type: TRACE_SPANS_MESSAGE, payload: moved ? { ...out, counters: moved } : out });
+        },
+    };
+    return trace;
+}
+function isThenable(value) {
+    return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}
+//# sourceMappingURL=worker-phases.js.map

package/dist/worker-phases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-phases.js","sourceRoot":"","sources":["../src/worker-phases.ts"],"names":[],"mappings":"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"}

package/dist/worker.d.ts

@@ -0,0 +1,72 @@
+import { type PerfCounterRegistry } from './counters.js';
+import { type MessageEndpoint } from './messages.js';
+import type { LoadTrace } from './load-trace.js';
+import type { TraceAttrs, WorkerTracePayload } from './types.js';
+/** Main -> worker: start recording, labelling spans with `thread`. */
+export declare const TRACE_ENABLE_MESSAGE = "load-trace:enable";
+/** Worker -> main: finished spans, see `WorkerTracePayload`. */
+export declare const TRACE_SPANS_MESSAGE = "load-trace:spans";
+export interface TraceEnableMessage {
+    type: typeof TRACE_ENABLE_MESSAGE;
+    thread: string;
+}
+export interface TraceSpansMessage {
+    type: typeof TRACE_SPANS_MESSAGE;
+    payload: WorkerTracePayload;
+}
+export interface WorkerSpanRecorder {
+    readonly thread: string;
+    begin(name: string, attrs?: TraceAttrs): number;
+    end(token: number, attrs?: TraceAttrs): void;
+    /** Finish named work before publishing an event that makes the host terminate us. */
+    endNamed(name: string): void;
+    /** Finished spans since the last drain, or `null` when there are none. */
+    drain(): WorkerTracePayload | null;
+}
+/**
+ * Records spans on the worker's own clock. `timeOrigin` travels with every
+ * drained payload so the main thread can shift the spans onto its clock: a
+ * worker's `performance.now()` is relative to the WORKER's creation time.
+ */
+export declare function createWorkerSpanRecorder(thread: string, now?: () => number, timeOrigin?: number): WorkerSpanRecorder;
+export interface WorkerTraceHostOptions {
+    /** Request message `type` -> span name. Unlisted types are never traced. */
+    spanNames: Readonly<Record<string, string>>;
+    /** Types traced only on their first occurrence (e.g. the first geometry chunk). */
+    onceTypes?: readonly string[];
+    post: (message: TraceSpansMessage) => void;
+    now?: () => number;
+    timeOrigin?: number;
+    /**
+     * This worker's counter registry (#6957), switched on with tracing. Its
+     * increments ride back with the spans after every handler, so per-chunk
+     * work (wasm copies, ...) reaches the load even for untraced message types.
+     */
+    counters?: PerfCounterRegistry;
+    /** Worker global, resolved lazily after tracing is enabled. Counts actual
+     * outbound transfer lists as msg.worker.out.* in this thread's counters. */
+    endpoint?: () => MessageEndpoint;
+}
+/**
+ * Wrap a worker's message dispatch. Until the main thread sends
+ * `TRACE_ENABLE_MESSAGE` the wrapper is one null check and a direct call, so
+ * an untraced load pays nothing measurable. Once enabled, each listed message
+ * type becomes one span, posted back as soon as its handler settles, and any
+ * handler that moved a counter posts those increments (#6957).
+ */
+/**
+ * The wrapped dispatch, plus `flush()`: post what is pending NOW. A worker the
+ * main thread terminates on a message it is about to send (the pre-pass
+ * worker on its final event) calls it first, or the counters die with it.
+ */
+export type WorkerTraceHost = ((data: unknown, run: () => Promise<void>) => Promise<void>) & {
+    /** Drain finished work; optionally finish all open spans with the given name before a terminal event. */
+    flush(completedSpan?: string): void;
+};
+export declare function createWorkerTraceHost(options: WorkerTraceHostOptions): WorkerTraceHost;
+/** Ask `worker` to record spans for `trace` (no-op when tracing is off). Returns `worker`. */
+export declare function enableWorkerTrace<W extends {
+    postMessage(message: unknown): void;
+}>(worker: W, trace: LoadTrace, thread: string): W;
+export declare function isTraceSpansMessage(message: unknown): message is TraceSpansMessage;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAc,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE7E,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AACxD,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IAAG,IAAI,EAAE,OAAO,oBAAoB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACzF,MAAM,WAAW,iBAAiB;IAAG,IAAI,EAAE,OAAO,mBAAmB,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE;AAEpG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAChD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7C,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,KAAK,IAAI,kBAAkB,GAAG,IAAI,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAM,MAAgC,EAC3C,UAAU,GAAE,MAA+B,GAC1C,kBAAkB,CAkCpB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5C,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC3C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,eAAe,CAAC;CAClC;AAED;;;;;;GAMG;AACH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG;IAC3F,yGAAyG;IACzG,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAgDtF;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,EACjF,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAC1C,CAAC,CAGH;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,iBAAiB,CAElF"}