@woosh/meep-engine 3.10.0 → 3.11.0

package/src/shade/device/timing/profile/SGPTHeader.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The decoded 32-byte head of an `.sgpt` stream.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTHeader {
+    /**
+     * @type {number}
+     */
+    format_version: number;
+    /**
+     * @type {number}
+     */
+    min_reader_version: number;
+    /**
+     * {@link SGPT_FLAG} bitmask.
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * Absolute offset of the directory record, or 0 when the session never stopped.
+     * @type {number}
+     */
+    directory_offset: number;
+    /**
+     * @type {number}
+     */
+    directory_byte_length: number;
+    /**
+     * Whether the writer reached `stop()`. A capture without this is readable and honest; it is
+     * simply shorter than the session that produced it.
+     *
+     * @returns {boolean}
+     */
+    get is_closed(): boolean;
+}
+//# sourceMappingURL=SGPTHeader.d.ts.map

package/src/shade/device/timing/profile/SGPTHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SGPTHeader.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPTHeader.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACI;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;OAEG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;OAKG;IACH,yBAEC;CACJ"}

package/src/shade/device/timing/profile/SGPTHeader.js

@@ -0,0 +1,46 @@
+import { SGPT_FLAG } from "./SGPT_FLAG.js";
+
+/**
+ * The decoded 32-byte head of an `.sgpt` stream.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTHeader {
+    /**
+     * @type {number}
+     */
+    format_version = 0;
+
+    /**
+     * @type {number}
+     */
+    min_reader_version = 0;
+
+    /**
+     * {@link SGPT_FLAG} bitmask.
+     * @type {number}
+     */
+    flags = 0;
+
+    /**
+     * Absolute offset of the directory record, or 0 when the session never stopped.
+     * @type {number}
+     */
+    directory_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    directory_byte_length = 0;
+
+    /**
+     * Whether the writer reached `stop()`. A capture without this is readable and honest; it is
+     * simply shorter than the session that produced it.
+     *
+     * @returns {boolean}
+     */
+    get is_closed() {
+        return (this.flags & SGPT_FLAG.CLOSED) !== 0;
+    }
+}

package/src/shade/device/timing/profile/SGPTRecordRef.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Where one record sits in the stream, and what it claims to be. Produced by
+ * {@link sgpt_read_records}; the payload is left where it lies and decoded on demand.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTRecordRef {
+    /**
+     * @param {number} type
+     * @param {number} offset
+     * @param {number} payload_offset
+     * @param {number} payload_byte_length
+     */
+    constructor(type: number, offset: number, payload_offset: number, payload_byte_length: number);
+    /**
+     * One of {@link SGPT_RECORD_TYPE}. Not validated against that enum — an unrecognised type is a
+     * record a newer writer produced, and skipping it by length is the whole point of the framing.
+     * @type {number}
+     */
+    type: number;
+    /**
+     * Offset of the record's framing.
+     * @type {number}
+     */
+    offset: number;
+    /**
+     * Offset of the first payload byte.
+     * @type {number}
+     */
+    payload_offset: number;
+    /**
+     * @type {number}
+     */
+    payload_byte_length: number;
+}
+//# sourceMappingURL=SGPTRecordRef.d.ts.map

package/src/shade/device/timing/profile/SGPTRecordRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SGPTRecordRef.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPTRecordRef.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IAyBI;;;;;OAKG;IACH,kBALW,MAAM,UACN,MAAM,kBACN,MAAM,uBACN,MAAM,EAOhB;IAnCD;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,qBAFU,MAAM,CAEQ;CAc3B"}

package/src/shade/device/timing/profile/SGPTRecordRef.js

@@ -0,0 +1,45 @@
+/**
+ * Where one record sits in the stream, and what it claims to be. Produced by
+ * {@link sgpt_read_records}; the payload is left where it lies and decoded on demand.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTRecordRef {
+    /**
+     * One of {@link SGPT_RECORD_TYPE}. Not validated against that enum — an unrecognised type is a
+     * record a newer writer produced, and skipping it by length is the whole point of the framing.
+     * @type {number}
+     */
+    type = 0;
+
+    /**
+     * Offset of the record's framing.
+     * @type {number}
+     */
+    offset = 0;
+
+    /**
+     * Offset of the first payload byte.
+     * @type {number}
+     */
+    payload_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    payload_byte_length = 0;
+
+    /**
+     * @param {number} type
+     * @param {number} offset
+     * @param {number} payload_offset
+     * @param {number} payload_byte_length
+     */
+    constructor(type, offset, payload_offset, payload_byte_length) {
+        this.type = type;
+        this.offset = offset;
+        this.payload_offset = payload_offset;
+        this.payload_byte_length = payload_byte_length;
+    }
+}

package/src/shade/device/timing/profile/SGPTWriteStream.d.ts

@@ -0,0 +1,103 @@
+/**
+ * A forward-only writer for an `.sgpt` stream, plus the symbol interning that goes with it.
+ *
+ * Open-ended by construction. There is no cap and no ring: everything written is kept until
+ * {@link finish}, because the point of a capture is the whole history, and a ring buffer's
+ * complexity buys nothing for the way these are actually used.
+ *
+ * **Nothing here depends on the stream being finished.** Records are self-framed and checksummed,
+ * so a reader can recover the entire contents by scanning. The directory {@link finish} appends is
+ * an index over that, never a prerequisite for it — which is what makes a capture that ended when
+ * the tab did still a capture.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTWriteStream {
+    /**
+     * Fires after each frame is committed, with the byte total so far.
+     *
+     * A session is uncapped, so this is how an application shows what it is accumulating rather
+     * than finding out when the tab dies.
+     *
+     * @readonly
+     * @type {Signal<number>}
+     */
+    readonly onBytesWritten: any;
+    /**
+     * Bytes committed so far, header included.
+     *
+     * @returns {number}
+     */
+    get bytes_written(): number;
+    /**
+     * How many records have been committed.
+     *
+     * @returns {number}
+     */
+    get record_count(): number;
+    /**
+     * Index of `value` in the capture's symbol space, interning it if it is new.
+     *
+     * Strings are written once and referenced by index thereafter, which is what keeps a repeating
+     * pass name from costing its length every frame.
+     *
+     * @param {string} value
+     * @returns {number}
+     */
+    intern(value: string): number;
+    /**
+     * Append one record, flushing any symbols it interned first.
+     *
+     * @template T
+     * @param {number} type one of {@link SGPT_RECORD_TYPE}
+     * @param {function(BinaryBuffer, T): void} write_payload
+     * @param {T} [data]
+     * @returns {void}
+     */
+    write_record<T>(type: number, write_payload: (arg0: BinaryBuffer, arg1: T) => void, data?: T): void;
+    /**
+     * Reserve headroom for the frame about to be recorded.
+     *
+     * Call at a frame boundary, never inside one. {@link BinaryBuffer} grows by reallocating and
+     * copying, and while that costs little — we are measuring GPU time, and the worst of it is a
+     * cache eviction that makes the next upload marginally slower — there is no reason for it to
+     * land in the middle of the interval whose timings we are taking. One reservation per frame
+     * moves it to the boundary, where it is invisible.
+     *
+     * @returns {void}
+     */
+    reserve_frame(): void;
+    /**
+     * Announce the current byte total. Called once per frame, after the frame's records land.
+     *
+     * @returns {void}
+     */
+    notify_frame_committed(): void;
+    /**
+     * The stream as it stands, without ending it.
+     *
+     * Carries no directory and no CLOSED flag, which is not a defect — it is the same shape a
+     * capture has when the tab is killed part-way through, and it reads back exactly the same way.
+     * That is what makes this useful for more than tests: a long session can persist a snapshot
+     * periodically and lose at most the frames since the last one, rather than everything.
+     *
+     * Pending symbols are flushed first, so a snapshot always resolves every name it references.
+     *
+     * @returns {ArrayBuffer}
+     */
+    snapshot(): ArrayBuffer;
+    /**
+     * Append the directory, mark the header closed, and hand back the bytes.
+     *
+     * The two header patches are the only backward writes in the whole format. Both are in fields
+     * the header checksum deliberately does not cover, so patching them cannot invalidate it — and
+     * a capture that never gets here is not damaged, it simply has neither.
+     *
+     * @returns {ArrayBuffer}
+     */
+    finish(): ArrayBuffer;
+    #private;
+}
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=SGPTWriteStream.d.ts.map

package/src/shade/device/timing/profile/SGPTWriteStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SGPTWriteStream.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPTWriteStream.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;GAcG;AACH;IAoCI;;;;;;;;OAQG;IACH,6BAA8B;IAM9B;;;;OAIG;IACH,4BAEC;IAED;;;;OAIG;IACH,2BAEC;IAED;;;;;;;;OAQG;IACH,cAHW,MAAM,GACJ,MAAM,CAiBlB;IAkDD;;;;;;;;OAQG;IACH,sBALW,MAAM,wBACG,YAAY,cAAM,IAAI,aAE7B,IAAI,CAUhB;IAED;;;;;;;;;;OAUG;IACH,iBAFa,IAAI,CAMhB;IAED;;;;OAIG;IACH,0BAFa,IAAI,CAMhB;IAED;;;;;;;;;;;OAWG;IACH,YAFa,WAAW,CAQvB;IAED;;;;;;;;OAQG;IACH,UAFa,WAAW,CA2CvB;;CACJ;6BA7R4B,yCAAyC"}

package/src/shade/device/timing/profile/SGPTWriteStream.js

@@ -0,0 +1,287 @@
+import { assert } from "../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { Signal } from "../../../../core/events/signal/Signal.js";
+import { SGPT_FLAG } from "./SGPT_FLAG.js";
+import { SGPT_FRAME_SLACK } from "./SGPT_FRAME_SLACK.js";
+import { SGPT_HEADER_OFFSET } from "./SGPT_HEADER_OFFSET.js";
+import { SGPT_RECORD_TYPE } from "./SGPT_RECORD_TYPE.js";
+import { sgpt_write_header } from "./sgpt_write_header.js";
+import { sgpt_write_record } from "./sgpt_write_record.js";
+
+/**
+ * A forward-only writer for an `.sgpt` stream, plus the symbol interning that goes with it.
+ *
+ * Open-ended by construction. There is no cap and no ring: everything written is kept until
+ * {@link finish}, because the point of a capture is the whole history, and a ring buffer's
+ * complexity buys nothing for the way these are actually used.
+ *
+ * **Nothing here depends on the stream being finished.** Records are self-framed and checksummed,
+ * so a reader can recover the entire contents by scanning. The directory {@link finish} appends is
+ * an index over that, never a prerequisite for it — which is what makes a capture that ended when
+ * the tab did still a capture.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTWriteStream {
+
+    /**
+     * @type {BinaryBuffer}
+     */
+    #buffer = new BinaryBuffer();
+
+    /**
+     * Strings already written into some {@link SGPT_RECORD_TYPE.SYMS} block, and the index each was
+     * given.
+     *
+     * @type {Map<string, number>}
+     */
+    #symbols = new Map();
+
+    /**
+     * Interned this frame but not yet written out. Flushed as one `SYMS` record immediately before
+     * the record that references them, so that record never refers forward to something a
+     * truncated file does not contain.
+     *
+     * @type {string[]}
+     */
+    #pending_symbols = [];
+
+    /**
+     * `{type, offset, byte_length}` per record, for the directory.
+     *
+     * @type {{type: number, offset: number, byte_length: number}[]}
+     */
+    #index = [];
+
+    /**
+     * @type {boolean}
+     */
+    #finished = false;
+
+    /**
+     * Fires after each frame is committed, with the byte total so far.
+     *
+     * A session is uncapped, so this is how an application shows what it is accumulating rather
+     * than finding out when the tab dies.
+     *
+     * @readonly
+     * @type {Signal<number>}
+     */
+    onBytesWritten = new Signal();
+
+    constructor() {
+        sgpt_write_header(this.#buffer);
+    }
+
+    /**
+     * Bytes committed so far, header included.
+     *
+     * @returns {number}
+     */
+    get bytes_written() {
+        return this.#buffer.position;
+    }
+
+    /**
+     * How many records have been committed.
+     *
+     * @returns {number}
+     */
+    get record_count() {
+        return this.#index.length;
+    }
+
+    /**
+     * Index of `value` in the capture's symbol space, interning it if it is new.
+     *
+     * Strings are written once and referenced by index thereafter, which is what keeps a repeating
+     * pass name from costing its length every frame.
+     *
+     * @param {string} value
+     * @returns {number}
+     */
+    intern(value) {
+        assert.isString(value, 'value');
+
+        const existing = this.#symbols.get(value);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const id = this.#symbols.size;
+
+        this.#symbols.set(value, id);
+        this.#pending_symbols.push(value);
+
+        return id;
+    }
+
+    /**
+     * Emit any symbols interned since the last flush, as one `SYMS` record.
+     *
+     * Called for you by {@link write_record}. Symbols travel *ahead of* the record that needs them
+     * rather than being gathered into one table at the end: a tail table makes a truncated capture
+     * resolve no names at all, which is precisely the capture of the crash somebody was trying to
+     * record.
+     *
+     * @returns {void}
+     */
+    #flush_symbols() {
+        const pending = this.#pending_symbols;
+
+        if (pending.length === 0) {
+            return;
+        }
+
+        const first_index = this.#symbols.size - pending.length;
+
+        this.#commit(SGPT_RECORD_TYPE.SYMS, (buffer) => {
+            buffer.writeUintVar(first_index);
+            buffer.writeUintVar(pending.length);
+
+            for (const value of pending) {
+                buffer.writeUTF8String(value);
+            }
+        });
+
+        pending.length = 0;
+    }
+
+    /**
+     * @template T
+     * @param {number} type
+     * @param {function(BinaryBuffer, T): void} write_payload
+     * @param {T} [data]
+     * @returns {void}
+     */
+    #commit(type, write_payload, data) {
+        const buffer = this.#buffer;
+
+        const offset = buffer.position;
+
+        const byte_length = sgpt_write_record(buffer, type, data, write_payload);
+
+        this.#index.push({ type, offset, byte_length });
+    }
+
+    /**
+     * Append one record, flushing any symbols it interned first.
+     *
+     * @template T
+     * @param {number} type one of {@link SGPT_RECORD_TYPE}
+     * @param {function(BinaryBuffer, T): void} write_payload
+     * @param {T} [data]
+     * @returns {void}
+     */
+    write_record(type, write_payload, data) {
+        assert.notOk(this.#finished, 'stream already finished');
+        assert.isInteger(type, 'type');
+        assert.isFunction(write_payload, 'write_payload');
+
+        this.#flush_symbols();
+
+        this.#commit(type, write_payload, data);
+    }
+
+    /**
+     * Reserve headroom for the frame about to be recorded.
+     *
+     * Call at a frame boundary, never inside one. {@link BinaryBuffer} grows by reallocating and
+     * copying, and while that costs little — we are measuring GPU time, and the worst of it is a
+     * cache eviction that makes the next upload marginally slower — there is no reason for it to
+     * land in the middle of the interval whose timings we are taking. One reservation per frame
+     * moves it to the boundary, where it is invisible.
+     *
+     * @returns {void}
+     */
+    reserve_frame() {
+        assert.notOk(this.#finished, 'stream already finished');
+
+        this.#buffer.ensureCapacity(this.#buffer.position + SGPT_FRAME_SLACK);
+    }
+
+    /**
+     * Announce the current byte total. Called once per frame, after the frame's records land.
+     *
+     * @returns {void}
+     */
+    notify_frame_committed() {
+        if (this.onBytesWritten.hasHandlers()) {
+            this.onBytesWritten.send1(this.#buffer.position);
+        }
+    }
+
+    /**
+     * The stream as it stands, without ending it.
+     *
+     * Carries no directory and no CLOSED flag, which is not a defect — it is the same shape a
+     * capture has when the tab is killed part-way through, and it reads back exactly the same way.
+     * That is what makes this useful for more than tests: a long session can persist a snapshot
+     * periodically and lose at most the frames since the last one, rather than everything.
+     *
+     * Pending symbols are flushed first, so a snapshot always resolves every name it references.
+     *
+     * @returns {ArrayBuffer}
+     */
+    snapshot() {
+        assert.notOk(this.#finished, 'stream already finished');
+
+        this.#flush_symbols();
+
+        return this.#buffer.raw_bytes.slice(0, this.#buffer.position).buffer;
+    }
+
+    /**
+     * Append the directory, mark the header closed, and hand back the bytes.
+     *
+     * The two header patches are the only backward writes in the whole format. Both are in fields
+     * the header checksum deliberately does not cover, so patching them cannot invalidate it — and
+     * a capture that never gets here is not damaged, it simply has neither.
+     *
+     * @returns {ArrayBuffer}
+     */
+    finish() {
+        assert.notOk(this.#finished, 'stream already finished');
+
+        this.#flush_symbols();
+
+        const buffer = this.#buffer;
+
+        const directory_offset = buffer.position;
+
+        const index = this.#index;
+
+        this.#commit(SGPT_RECORD_TYPE.DIRE, (out) => {
+            out.writeUintVar(index.length);
+
+            for (const entry of index) {
+                out.writeUint32(entry.type);
+                // u64 rather than the compact uintVar: `writeUintVar` refuses anything above
+                // 2^31-1, and an assertion at `finish` would destroy the very capture it was asked
+                // to hand over. Sixteen bytes a record is nothing against that.
+                out.writeUint64(BigInt(entry.offset));
+                out.writeUint32(entry.byte_length);
+            }
+        });
+
+        const end = buffer.position;
+
+        buffer.position = SGPT_HEADER_OFFSET.FLAGS;
+        const flags = buffer.readUint32();
+
+        buffer.position = SGPT_HEADER_OFFSET.FLAGS;
+        buffer.writeUint32(flags | SGPT_FLAG.CLOSED);
+
+        buffer.position = SGPT_HEADER_OFFSET.DIRECTORY_OFFSET;
+        buffer.writeUint64(BigInt(directory_offset));
+        buffer.writeUint64(BigInt(end - directory_offset));
+
+        buffer.position = end;
+
+        this.#finished = true;
+
+        return buffer.raw_bytes.slice(0, end).buffer;
+    }
+}

package/src/shade/device/timing/profile/SGPT_DEFECT.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which invariant of an `.sgpt` stream was violated. The `detail` string carries the specifics.
+ *
+ * Mirrors the {@link VGEO_DEFECT } convention: a defect is reported as data rather than thrown as a
+ * bare `Error`, because a profile capture is frequently damaged in ways worth *reporting to the
+ * reader* rather than refusing outright — a session killed mid-record is the normal outcome of
+ * capturing a crash.
+ */
+export type SGPT_DEFECT = number;
+export namespace SGPT_DEFECT {
+    let HEADER: number;
+    let CHECKSUM: number;
+    let FRAMING: number;
+    let RESYNC: number;
+    let PAYLOAD: number;
+    let DIRECTORY: number;
+    let TRUNCATED: number;
+}
+//# sourceMappingURL=SGPT_DEFECT.d.ts.map

package/src/shade/device/timing/profile/SGPT_DEFECT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_DEFECT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_DEFECT.js"],"names":[],"mappings":";;;;;;;;0BAQU,MAAM"}

package/src/shade/device/timing/profile/SGPT_DEFECT.js

@@ -0,0 +1,26 @@
+/**
+ * Which invariant of an `.sgpt` stream was violated. The `detail` string carries the specifics.
+ *
+ * Mirrors the {@link VGEO_DEFECT} convention: a defect is reported as data rather than thrown as a
+ * bare `Error`, because a profile capture is frequently damaged in ways worth *reporting to the
+ * reader* rather than refusing outright — a session killed mid-record is the normal outcome of
+ * capturing a crash.
+ *
+ * @enum {number}
+ */
+export const SGPT_DEFECT = {
+    /** Not an `.sgpt` file, or a header too short or too new to read. */
+    HEADER: 0,
+    /** A checksum did not match the bytes it covers. */
+    CHECKSUM: 1,
+    /** A record's framing is self-inconsistent — length runs past the end of the data. */
+    FRAMING: 2,
+    /** Bytes between records that are not a record. Recovered by scanning; reported, not fatal. */
+    RESYNC: 3,
+    /** A record's payload does not decode as its type says it should. */
+    PAYLOAD: 4,
+    /** The directory disagrees with the records actually present. */
+    DIRECTORY: 5,
+    /** The stream ends inside a record. Expected for a capture that never stopped. */
+    TRUNCATED: 6
+};

package/src/shade/device/timing/profile/SGPT_FLAG.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Header flag bits.
+ */
+export type SGPT_FLAG = number;
+export namespace SGPT_FLAG {
+    let CLOSED: number;
+}
+//# sourceMappingURL=SGPT_FLAG.d.ts.map

package/src/shade/device/timing/profile/SGPT_FLAG.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_FLAG.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_FLAG.js"],"names":[],"mappings":";;;wBAGU,MAAM"}

package/src/shade/device/timing/profile/SGPT_FLAG.js

@@ -0,0 +1,15 @@
+/**
+ * Header flag bits.
+ *
+ * @enum {number}
+ */
+export const SGPT_FLAG = {
+    /**
+     * The writer reached {@link GPUProfileSession.stop} and the file is complete as intended.
+     *
+     * Its absence is not an error — see {@link SGPT_HEADER_OFFSET.DIRECTORY_OFFSET}. It is how a
+     * reader knows to say "this capture was cut short" rather than silently presenting a partial
+     * session as a whole one.
+     */
+    CLOSED: 1 << 0
+};