@woosh/meep-engine 3.10.0 → 3.11.0

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

@@ -0,0 +1,159 @@
+/**
+ * How a resource's descriptor was recorded. `NONE` covers an imported resource whose descriptor the
+ * graph never saw, which is normal rather than a defect.
+ */
+export type GPUProfileResourceKind = number;
+export namespace GPUProfileResourceKind {
+    let NONE: number;
+    let BUFFER: number;
+    let TEXTURE: number;
+}
+/**
+ * One frame graph pass, as recorded.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfilePass {
+    /** @type {number} */
+    id: number;
+    /** @type {string} */
+    name: string;
+    /**
+     * Index into {@link GPUProfileTopology#scopes}, or -1 when recorded at the top level.
+     * @type {number}
+     */
+    scope: number;
+    /**
+     * Whether the graph culled this pass. A culled pass is still worth carrying: "why did this run"
+     * and "why did this *not* run" are the same question asked from either side.
+     * @type {boolean}
+     */
+    culled: boolean;
+    /** @type {boolean} */
+    has_side_effects: boolean;
+    /** @type {number} */
+    ref_count: number;
+    /** @type {number[]} resource node ids */
+    reads: number[];
+    /** @type {number[]} resource node ids */
+    writes: number[];
+    /** @type {number[]} resource node ids */
+    creates: number[];
+}
+/**
+ * A named recording region. Scopes nest, and the nesting is the parent chain — this is the
+ * hierarchy a flame graph needs, and the graph already has it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileScope {
+    /** @type {string} */
+    name: string;
+    /**
+     * Index into {@link GPUProfileTopology#scopes}, or -1 for a top-level scope.
+     * @type {number}
+     */
+    parent: number;
+}
+/**
+ * One resource **node** — that is, one version of one resource.
+ *
+ * Keyed by node rather than by registry entry, matching `FrameGraph.exportToJson`. A pass records
+ * the node it read or wrote, not the underlying resource, so a registry-keyed model leaves every
+ * reference past version 0 dangling.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileResource {
+    /** @type {number} */
+    id: number;
+    /** @type {string} */
+    name: string;
+    /** @type {number} */
+    version: number;
+    /** @type {boolean} */
+    transient: boolean;
+    /** @type {boolean} */
+    imported: boolean;
+    /**
+     * Id of the pass that produced this version, or -1 — an imported resource as it stood on
+     * import, or one created outside any pass.
+     * @type {number}
+     */
+    producer: number;
+    /** @type {number} one of {@link GPUProfileResourceKind} */
+    kind: number;
+    /** Bytes. Buffers only. @type {number} */
+    size: number;
+    /** `GPUBufferUsage` / `GPUTextureUsage` bitmask. @type {number} */
+    usage: number;
+    /** Texels. Textures only. @type {number[]} */
+    resolution: number[];
+    /** @type {number} */
+    mip_level_count: number;
+    /** @type {number} */
+    sample_count: number;
+    /** @type {string} */
+    format: string;
+    /** @type {string} */
+    dimension: string;
+    /**
+     * Declared bytes, computed when the capture was recorded.
+     *
+     * Computed there rather than here because working a texture's footprint out needs its format's
+     * block dimensions, and those live in the engine's format table. Carrying the number instead of
+     * the inputs means a reader never has to keep a copy of that table in step with the engine's —
+     * and a format the reader has never heard of still reports a size.
+     *
+     * Declared, not allocated: a pooled allocator may serve a larger block, and an aliasing one may
+     * serve the same block to two resources whose lifetimes do not overlap.
+     *
+     * @type {number}
+     */
+    byte_size: number;
+}
+/**
+ * The shape of one frame: its passes, its resources, and how they depend on each other.
+ *
+ * **Stored once and referenced by many frames.** A Shade frame graph is nearly identical frame to
+ * frame — the same passes over the same resources — and what varies is the timings and the cull
+ * decisions. Recording the whole structure per frame is the difference between a capture of tens
+ * of megabytes and one of a couple, so topologies are content-hashed and deduplicated, and a frame
+ * stores an id.
+ *
+ * Cull state is the exception and lives here anyway: it varies with the frame, but it varies
+ * *with the topology* — a frame in which a different set of passes was culled is a different
+ * shape, and gets its own entry.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileTopology {
+    /**
+     * Position in the capture's topology list. What a frame refers to.
+     * @type {number}
+     */
+    id: number;
+    /** @type {string} */
+    name: string;
+    /** @type {GPUProfilePass[]} */
+    passes: GPUProfilePass[];
+    /** @type {GPUProfileScope[]} */
+    scopes: GPUProfileScope[];
+    /** @type {GPUProfileResource[]} */
+    resources: GPUProfileResource[];
+    /**
+     * Declared bytes across every transient resource, as the graph asked for them.
+     *
+     * Declared, not allocated: a pooled allocator may hand back a larger block, and an aliased one
+     * may hand the same block to two resources whose lifetimes do not overlap. The gap between
+     * this and the device's real figure is the aliasing, which is the interesting number.
+     *
+     * @returns {number}
+     */
+    get declared_transient_bytes(): number;
+}
+//# sourceMappingURL=GPUProfileTopology.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileTopology.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileTopology.js"],"names":[],"mappings":";;;;qCAIU,MAAM;;;;;;AAQhB;;;;;GAKG;AACH;IACI,qBAAqB;IACrB,IADW,MAAM,CACV;IAEP,qBAAqB;IACrB,MADW,MAAM,CACP;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,QAFU,OAAO,CAEF;IAEf,sBAAsB;IACtB,kBADW,OAAO,CACO;IAEzB,qBAAqB;IACrB,WADW,MAAM,CACH;IAEd,yCAAyC;IACzC,OADW,MAAM,EAAE,CACR;IAEX,yCAAyC;IACzC,QADW,MAAM,EAAE,CACP;IAEZ,yCAAyC;IACzC,SADW,MAAM,EAAE,CACN;CAChB;AAED;;;;;;GAMG;AACH;IACI,qBAAqB;IACrB,MADW,MAAM,CACP;IAEV;;;OAGG;IACH,QAFU,MAAM,CAEJ;CACf;AAED;;;;;;;;;GASG;AACH;IACI,qBAAqB;IACrB,IADW,MAAM,CACV;IAEP,qBAAqB;IACrB,MADW,MAAM,CACP;IAEV,qBAAqB;IACrB,SADW,MAAM,CACL;IAEZ,sBAAsB;IACtB,WADW,OAAO,CACA;IAElB,sBAAsB;IACtB,UADW,OAAO,CACD;IAEjB;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd,2DAA2D;IAC3D,MADW,MAAM,CACkB;IAEnC,0CAA0C;IAC1C,MADgC,MAAM,CAC7B;IAET,mEAAmE;IACnE,OADyD,MAAM,CACrD;IAEV,8CAA8C;IAC9C,YADkC,MAAM,EAAE,CACnB;IAEvB,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,cADW,MAAM,CACA;IAEjB,qBAAqB;IACrB,QADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,WADW,MAAM,CACF;IAEf;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;CACjB;AAED;;;;;;;;;;;;;;;GAeG;AACH;IACI;;;OAGG;IACH,IAFU,MAAM,CAET;IAEP,qBAAqB;IACrB,MADW,MAAM,CACP;IAEV,+BAA+B;IAC/B,QADW,cAAc,EAAE,CACf;IAEZ,gCAAgC;IAChC,QADW,eAAe,EAAE,CAChB;IAEZ,mCAAmC;IACnC,WADW,kBAAkB,EAAE,CAChB;IAEf;;;;;;;;OAQG;IACH,uCAUC;CACJ"}

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

@@ -0,0 +1,202 @@
+/**
+ * How a resource's descriptor was recorded. `NONE` covers an imported resource whose descriptor the
+ * graph never saw, which is normal rather than a defect.
+ *
+ * @enum {number}
+ */
+export const GPUProfileResourceKind = {
+    NONE: 0,
+    BUFFER: 1,
+    TEXTURE: 2
+};
+
+/**
+ * One frame graph pass, as recorded.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfilePass {
+    /** @type {number} */
+    id = 0;
+
+    /** @type {string} */
+    name = "";
+
+    /**
+     * Index into {@link GPUProfileTopology#scopes}, or -1 when recorded at the top level.
+     * @type {number}
+     */
+    scope = -1;
+
+    /**
+     * Whether the graph culled this pass. A culled pass is still worth carrying: "why did this run"
+     * and "why did this *not* run" are the same question asked from either side.
+     * @type {boolean}
+     */
+    culled = false;
+
+    /** @type {boolean} */
+    has_side_effects = false;
+
+    /** @type {number} */
+    ref_count = 0;
+
+    /** @type {number[]} resource node ids */
+    reads = [];
+
+    /** @type {number[]} resource node ids */
+    writes = [];
+
+    /** @type {number[]} resource node ids */
+    creates = [];
+}
+
+/**
+ * A named recording region. Scopes nest, and the nesting is the parent chain — this is the
+ * hierarchy a flame graph needs, and the graph already has it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileScope {
+    /** @type {string} */
+    name = "";
+
+    /**
+     * Index into {@link GPUProfileTopology#scopes}, or -1 for a top-level scope.
+     * @type {number}
+     */
+    parent = -1;
+}
+
+/**
+ * One resource **node** — that is, one version of one resource.
+ *
+ * Keyed by node rather than by registry entry, matching `FrameGraph.exportToJson`. A pass records
+ * the node it read or wrote, not the underlying resource, so a registry-keyed model leaves every
+ * reference past version 0 dangling.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileResource {
+    /** @type {number} */
+    id = 0;
+
+    /** @type {string} */
+    name = "";
+
+    /** @type {number} */
+    version = 0;
+
+    /** @type {boolean} */
+    transient = false;
+
+    /** @type {boolean} */
+    imported = false;
+
+    /**
+     * Id of the pass that produced this version, or -1 — an imported resource as it stood on
+     * import, or one created outside any pass.
+     * @type {number}
+     */
+    producer = -1;
+
+    /** @type {number} one of {@link GPUProfileResourceKind} */
+    kind = GPUProfileResourceKind.NONE;
+
+    /** Bytes. Buffers only. @type {number} */
+    size = 0;
+
+    /** `GPUBufferUsage` / `GPUTextureUsage` bitmask. @type {number} */
+    usage = 0;
+
+    /** Texels. Textures only. @type {number[]} */
+    resolution = [0, 0, 0];
+
+    /** @type {number} */
+    mip_level_count = 1;
+
+    /** @type {number} */
+    sample_count = 1;
+
+    /** @type {string} */
+    format = "";
+
+    /** @type {string} */
+    dimension = "";
+
+    /**
+     * Declared bytes, computed when the capture was recorded.
+     *
+     * Computed there rather than here because working a texture's footprint out needs its format's
+     * block dimensions, and those live in the engine's format table. Carrying the number instead of
+     * the inputs means a reader never has to keep a copy of that table in step with the engine's —
+     * and a format the reader has never heard of still reports a size.
+     *
+     * Declared, not allocated: a pooled allocator may serve a larger block, and an aliasing one may
+     * serve the same block to two resources whose lifetimes do not overlap.
+     *
+     * @type {number}
+     */
+    byte_size = 0;
+}
+
+/**
+ * The shape of one frame: its passes, its resources, and how they depend on each other.
+ *
+ * **Stored once and referenced by many frames.** A Shade frame graph is nearly identical frame to
+ * frame — the same passes over the same resources — and what varies is the timings and the cull
+ * decisions. Recording the whole structure per frame is the difference between a capture of tens
+ * of megabytes and one of a couple, so topologies are content-hashed and deduplicated, and a frame
+ * stores an id.
+ *
+ * Cull state is the exception and lives here anyway: it varies with the frame, but it varies
+ * *with the topology* — a frame in which a different set of passes was culled is a different
+ * shape, and gets its own entry.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileTopology {
+    /**
+     * Position in the capture's topology list. What a frame refers to.
+     * @type {number}
+     */
+    id = 0;
+
+    /** @type {string} */
+    name = "";
+
+    /** @type {GPUProfilePass[]} */
+    passes = [];
+
+    /** @type {GPUProfileScope[]} */
+    scopes = [];
+
+    /** @type {GPUProfileResource[]} */
+    resources = [];
+
+    /**
+     * Declared bytes across every transient resource, as the graph asked for them.
+     *
+     * Declared, not allocated: a pooled allocator may hand back a larger block, and an aliased one
+     * may hand the same block to two resources whose lifetimes do not overlap. The gap between
+     * this and the device's real figure is the aliasing, which is the interesting number.
+     *
+     * @returns {number}
+     */
+    get declared_transient_bytes() {
+        let total = 0;
+
+        for (const resource of this.resources) {
+            if (resource.transient) {
+                total += resource.byte_size;
+            }
+        }
+
+        return total;
+    }
+}
+

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

@@ -0,0 +1,90 @@
+/**
+ * What a GPU pass was asked to do, as opposed to how long it took.
+ *
+ * Aggregated per pass rather than per call. Most passes issue one dispatch, for which an aggregate
+ * *is* the value; the ones that issue many are the ones where a total is what you wanted anyway.
+ * Storing every call would multiply a frame record by the draw count, which is the wrong trade for
+ * a format meant to be left running.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileWork {
+    /**
+     * `dispatchWorkgroups` calls, direct only.
+     * @type {number}
+     */
+    dispatch_count: number;
+    /**
+     * `dispatchWorkgroupsIndirect` calls.
+     *
+     * Counted separately because their sizes live in a GPU buffer and are simply not knowable at
+     * encode time. Folding them in would make {@link workgroups} read as a total when it is a
+     * partial one.
+     *
+     * @type {number}
+     */
+    indirect_dispatch_count: number;
+    /**
+     * Workgroups summed across the direct dispatches, per axis.
+     * @type {number[]}
+     */
+    workgroups: number[];
+    /**
+     * `draw` and `drawIndexed` calls.
+     * @type {number}
+     */
+    draw_count: number;
+    /**
+     * `drawIndirect` and `drawIndexedIndirect` calls. Same caveat as
+     * {@link indirect_dispatch_count}.
+     * @type {number}
+     */
+    indirect_draw_count: number;
+    /**
+     * Vertices summed across direct draws.
+     * @type {number}
+     */
+    vertex_count: number;
+    /**
+     * Indices summed across direct indexed draws.
+     * @type {number}
+     */
+    index_count: number;
+    /**
+     * Instances summed across direct draws.
+     * @type {number}
+     */
+    instance_count: number;
+    /**
+     * Label of the pipeline this pass ran, where the pass was built through
+     * `constructComputePass` / `constructRenderPass` and one was therefore known.
+     * @type {string}
+     */
+    pipeline: string;
+    /**
+     * `@workgroup_size` of the compute entry point, or `[0, 0, 0]` when it could not be read —
+     * an override-expression size, or a pass whose pipeline was never named.
+     * @type {number[]}
+     */
+    workgroup_size: number[];
+    /**
+     * Shader invocations this pass asked for: workgroups × workgroup size.
+     *
+     * Zero when either is unknown, which is a different thing from zero work and is why
+     * {@link workgroup_size} is carried rather than assumed. The number worth looking at next to a
+     * duration — a dispatch that costs 2 ms over 300 invocations is a dispatch that is the wrong
+     * shape.
+     *
+     * @returns {number}
+     */
+    get invocation_count(): number;
+    /**
+     * Whether anything was recorded at all. A pass with nothing here either did no work, or ran at
+     * a capture level below {@link GPUProfileLevel.WORKLOAD}.
+     *
+     * @returns {boolean}
+     */
+    get is_empty(): boolean;
+}
+//# sourceMappingURL=GPUProfileWork.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProfileWork.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/GPUProfileWork.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;OAQG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;OAIG;IACH,gBAFU,MAAM,EAAE,CAES;IAE3B;;;;;;;;;OASG;IACH,+BASC;IAED;;;;;OAKG;IACH,wBAMC;CACJ"}

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

@@ -0,0 +1,115 @@
+/**
+ * What a GPU pass was asked to do, as opposed to how long it took.
+ *
+ * Aggregated per pass rather than per call. Most passes issue one dispatch, for which an aggregate
+ * *is* the value; the ones that issue many are the ones where a total is what you wanted anyway.
+ * Storing every call would multiply a frame record by the draw count, which is the wrong trade for
+ * a format meant to be left running.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUProfileWork {
+    /**
+     * `dispatchWorkgroups` calls, direct only.
+     * @type {number}
+     */
+    dispatch_count = 0;
+
+    /**
+     * `dispatchWorkgroupsIndirect` calls.
+     *
+     * Counted separately because their sizes live in a GPU buffer and are simply not knowable at
+     * encode time. Folding them in would make {@link workgroups} read as a total when it is a
+     * partial one.
+     *
+     * @type {number}
+     */
+    indirect_dispatch_count = 0;
+
+    /**
+     * Workgroups summed across the direct dispatches, per axis.
+     * @type {number[]}
+     */
+    workgroups = [0, 0, 0];
+
+    /**
+     * `draw` and `drawIndexed` calls.
+     * @type {number}
+     */
+    draw_count = 0;
+
+    /**
+     * `drawIndirect` and `drawIndexedIndirect` calls. Same caveat as
+     * {@link indirect_dispatch_count}.
+     * @type {number}
+     */
+    indirect_draw_count = 0;
+
+    /**
+     * Vertices summed across direct draws.
+     * @type {number}
+     */
+    vertex_count = 0;
+
+    /**
+     * Indices summed across direct indexed draws.
+     * @type {number}
+     */
+    index_count = 0;
+
+    /**
+     * Instances summed across direct draws.
+     * @type {number}
+     */
+    instance_count = 0;
+
+    /**
+     * Label of the pipeline this pass ran, where the pass was built through
+     * `constructComputePass` / `constructRenderPass` and one was therefore known.
+     * @type {string}
+     */
+    pipeline = "";
+
+    /**
+     * `@workgroup_size` of the compute entry point, or `[0, 0, 0]` when it could not be read —
+     * an override-expression size, or a pass whose pipeline was never named.
+     * @type {number[]}
+     */
+    workgroup_size = [0, 0, 0];
+
+    /**
+     * Shader invocations this pass asked for: workgroups × workgroup size.
+     *
+     * Zero when either is unknown, which is a different thing from zero work and is why
+     * {@link workgroup_size} is carried rather than assumed. The number worth looking at next to a
+     * duration — a dispatch that costs 2 ms over 300 invocations is a dispatch that is the wrong
+     * shape.
+     *
+     * @returns {number}
+     */
+    get invocation_count() {
+        const [wx, wy, wz] = this.workgroups;
+        const [sx, sy, sz] = this.workgroup_size;
+
+        if (sx === 0) {
+            return 0;
+        }
+
+        return wx * sx * Math.max(wy, 1) * Math.max(sy, 1) * Math.max(wz, 1) * Math.max(sz, 1);
+    }
+
+    /**
+     * Whether anything was recorded at all. A pass with nothing here either did no work, or ran at
+     * a capture level below {@link GPUProfileLevel.WORKLOAD}.
+     *
+     * @returns {boolean}
+     */
+    get is_empty() {
+        return this.dispatch_count === 0
+            && this.indirect_dispatch_count === 0
+            && this.draw_count === 0
+            && this.indirect_draw_count === 0
+            && this.pipeline === "";
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * @param {number} code one of {@link SGPT_DEFECT}
+ * @returns {string}
+ */
+export function sgpt_defect_name(code: number): string;
+/**
+ * One thing wrong with an `.sgpt` stream.
+ *
+ * Collected rather than thrown. A capture of the moment a GPU fell over is a capture that ends
+ * mid-record, and a reader that refuses it outright discards the only evidence of what happened.
+ * The reader gathers defects, returns everything it could decode alongside them, and lets the
+ * inspector say plainly what it is showing and what it could not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTDefect {
+    /**
+     * @param {number} code one of {@link SGPT_DEFECT}
+     * @param {string} detail
+     * @param {number} [offset]
+     */
+    constructor(code: number, detail: string, offset?: number);
+    /**
+     * One of {@link SGPT_DEFECT}.
+     * @type {number}
+     */
+    code: number;
+    /**
+     * @type {string}
+     */
+    detail: string;
+    /**
+     * Byte offset in the stream where the problem was found, or -1 when it is not about one place.
+     * @type {number}
+     */
+    offset: number;
+    /**
+     * @returns {string}
+     */
+    toString(): string;
+}
+//# sourceMappingURL=SGPTDefect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPTDefect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPTDefect.js"],"names":[],"mappings":"AAoDA;;;GAGG;AACH,uCAHW,MAAM,GACJ,MAAM,CAUlB;AA9DD;;;;;;;;;;GAUG;AACH;IAkBI;;;;OAIG;IACH,kBAJW,MAAM,UACN,MAAM,WACN,MAAM,EAMhB;IA1BD;;;OAGG;IACH,MAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAaZ;;OAEG;IACH,YAFa,MAAM,CAMlB;CACJ"}

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

@@ -0,0 +1,65 @@
+import { SGPT_DEFECT } from "./SGPT_DEFECT.js";
+
+/**
+ * One thing wrong with an `.sgpt` stream.
+ *
+ * Collected rather than thrown. A capture of the moment a GPU fell over is a capture that ends
+ * mid-record, and a reader that refuses it outright discards the only evidence of what happened.
+ * The reader gathers defects, returns everything it could decode alongside them, and lets the
+ * inspector say plainly what it is showing and what it could not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SGPTDefect {
+    /**
+     * One of {@link SGPT_DEFECT}.
+     * @type {number}
+     */
+    code = SGPT_DEFECT.HEADER;
+
+    /**
+     * @type {string}
+     */
+    detail = '';
+
+    /**
+     * Byte offset in the stream where the problem was found, or -1 when it is not about one place.
+     * @type {number}
+     */
+    offset = -1;
+
+    /**
+     * @param {number} code one of {@link SGPT_DEFECT}
+     * @param {string} detail
+     * @param {number} [offset]
+     */
+    constructor(code, detail, offset = -1) {
+        this.code = code;
+        this.detail = detail;
+        this.offset = offset;
+    }
+
+    /**
+     * @returns {string}
+     */
+    toString() {
+        const where = this.offset >= 0 ? ` at byte ${this.offset}` : '';
+
+        return `${sgpt_defect_name(this.code)}${where}: ${this.detail}`;
+    }
+}
+
+/**
+ * @param {number} code one of {@link SGPT_DEFECT}
+ * @returns {string}
+ */
+export function sgpt_defect_name(code) {
+    for (const name in SGPT_DEFECT) {
+        if (SGPT_DEFECT[name] === code) {
+            return name;
+        }
+    }
+
+    return `UNKNOWN(${code})`;
+}