@woosh/meep-engine 3.9.0 → 3.11.0

package/src/shade/device/timing/profile/SGPT_FORMAT.md

@@ -0,0 +1,345 @@
+# The `.sgpt` container — format specification
+
+**S**hade **G**PU **P**rofile **T**race, format version 2.
+
+This document is the normative description of the file. It is written for somebody outside Company
+Named who wants to read or write one without reading the engine's source. Every integer is
+little-endian and unsigned unless stated otherwise.
+
+---
+
+## 1. What the format is for, and what it is not
+
+A capture holds **what a renderer asked a GPU to do over a run of frames, and how long each piece
+took**: pass timings, the frame graph's structure and dependencies, declared resource sizes, and
+dispatch and draw counts.
+
+It deliberately does **not** hold buffer or texture contents, shader source, or anything else that
+scales with the size of the resources it describes. That exclusion is what keeps a frame record in
+the kilobytes and makes an uncapped recording practical.
+
+### 1.1 Two properties the layout exists to provide
+
+**A truncated capture is a capture.** A recording that ended when the tab did — which is the state
+of every capture of a crash, a device loss, or a hang — must be readable up to the last intact
+record. So every record is self-framed and checksummed, symbols travel inside the record that
+introduces them, and the directory is an index over the stream rather than a prerequisite for
+reading it.
+
+**A reader may not understand everything, and must say so rather than fail.** Records carry a type
+and a length; an unrecognised type is skipped by length. This is what lets a newer writer add record
+types without a version bump, and what lets an older reader open the result and report honestly
+which parts it could not show.
+
+---
+
+## 2. File header
+
+Thirty-two bytes at offset 0.
+
+| Offset | Size | Field | Notes |
+|---|---|---|---|
+| 0 | 4 | `magic` | `0x54504753` — the ASCII bytes `S`, `G`, `P`, `T` in that order |
+| 4 | 2 | `format_version` | 2 for this document |
+| 6 | 2 | `min_reader_version` | the oldest reader that can read this file correctly |
+| 8 | 4 | `flags` | see below |
+| 12 | 4 | `header_checksum` | CRC-32 over bytes `[0, 8)` **only** |
+| 16 | 8 | `directory_offset` | absolute; **0 when there is no directory** |
+| 24 | 8 | `directory_byte_length` | 0 when absent |
+
+Records begin at offset 32.
+
+### 2.1 Flags
+
+| Bit | Name | Meaning |
+|---|---|---|
+| 0 | `CLOSED` | the writer reached `stop()` and the file is complete as intended |
+
+### 2.2 Why the checksum stops at byte 8
+
+Everything from `flags` onward is written twice: zeroed when the header is laid down, and patched
+when the session stops. A checksum covering those fields would have to be recomputed at stop — fine
+for a capture that stops, and exactly wrong for one that does not, which would then carry a checksum
+over bytes that were never written and read as corrupt.
+
+What remains under the checksum is what a reader must trust before it can do anything at all: *is
+this an `.sgpt`, and can this build read it.* Those never change after the header is written.
+
+**A reader must not treat a missing `CLOSED` flag or a zero `directory_offset` as damage.** Both are
+the normal state of an interrupted session, and such a file is fully readable by §3.
+
+### 2.3 Version handling
+
+A reader **must** refuse a file whose `min_reader_version` exceeds the highest format version it
+implements, and **must** accept anything else. `min_reader_version` is raised only when a change
+would make an older reader produce *wrong* answers rather than incomplete ones — a new record type
+it would skip is incomplete; a reordered field is wrong.
+
+Format version 2 keeps `min_reader_version` at 1: it added the `TOPO` record, which a version-1
+reader skips by length, and appended a topology reference to the end of a frame's payload, which a
+version-1 reader stops before.
+
+---
+
+## 3. Records
+
+Every record, whatever its type, is framed identically.
+
+| Offset | Size | Field |
+|---|---|---|
+| 0 | 4 | `sync` — `0x43455253`, the ASCII bytes `S`, `R`, `E`, `C` |
+| 4 | 4 | `record_type` — a four-character tag as a u32 |
+| 8 | 4 | `payload_byte_length` |
+| 12 | 4 | `payload_checksum` — CRC-32 over the payload bytes only |
+| 16 | … | payload |
+
+`payload_byte_length` is a u32 rather than a u64 because no record describes anything that scales
+with resource size (§1); four gigabytes is not a ceiling anything can approach.
+
+### 3.1 Reading, and resynchronising
+
+The canonical read is a **forward scan from offset 32**, not a walk of the directory:
+
+1. At the current offset, a record is present if — and only if — all four hold: the sync marker
+   matches, at least 16 bytes remain, the payload fits within the file, and the payload's CRC-32
+   matches `payload_checksum`.
+2. If it does, decode or skip it by type and advance past its payload.
+3. If it does not, scan forward one byte at a time for the next offset where all four hold. Report
+   the skipped bytes as damage; do not stop.
+4. If the scan reaches the end without finding another record, the stream was truncated inside a
+   record. Report it. Everything already decoded stands.
+
+**The sync marker alone is not sufficient and a reader must not treat it as such.** Four bytes of
+payload can spell `SREC` — a pass label could — and resynchronising onto a false positive
+desynchronises everything after it. The length and the checksum are what confirm a candidate.
+
+### 3.2 Record types
+
+| Tag | u32 | Payload | Cardinality |
+|---|---|---|---|
+| `META` | `0x4154454D` | §4 | 1, immediately after the header |
+| `SYMS` | `0x534D5953` | §5 | 0..n, always before the records referencing them |
+| `TOPO` | `0x4F504F54` | §6 | 0..n |
+| `FRAM` | `0x4D415246` | §7 | 0..n |
+| `CNTR` | `0x52544E43` | reserved | 0..1 |
+| `DIRE` | `0x45524944` | §8 | 0..1, last |
+
+An unrecognised tag **must** be skipped using `payload_byte_length`.
+
+### 3.3 Primitive encodings
+
+- `uintVar` — 7 bits per byte, low group first, high bit set on every byte but the last. Values are
+  limited to 2³¹−1.
+- `utf8` — a `uintVar` byte length followed by that many UTF-8 bytes.
+- `f64` — IEEE 754 binary64, little-endian.
+- **Optional index** — a value of −1 meaning "none", written as `uintVar(value + 1)`. Zero means
+  none.
+
+---
+
+## 4. `META`
+
+| Field | Type | Notes |
+|---|---|---|
+| `level` | u8 | 0 `TIMING`, 1 `STRUCTURE`, 2 `WORKLOAD`, 3 `VERBOSE` |
+| `wall_clock_start_ms` | f64 | `Date.now()` at session start; for ordering captures, not for timing |
+| `note` | utf8 | free text from whoever captured |
+| `engine_version` | utf8 | |
+| `adapter_vendor` | utf8 | from `GPUAdapterInfo`; empty where the browser withheld it |
+| `adapter_architecture` | utf8 | |
+| `adapter_device` | utf8 | |
+| `adapter_description` | utf8 | |
+| `feature_count` | uintVar | |
+| `features` | utf8 × count | `GPUFeatureName`s the device was created with |
+
+### 4.1 On timestamp resolution — a deliberate absence
+
+**There is no field here describing the device's timestamp quantum, and adding one is out of
+scope.**
+
+Browsers quantize WebGPU timestamps as a timing-attack mitigation; Chrome to 100 µs unless
+`chrome://flags/#enable-webgpu-developer-features` is set. Most passes in a real renderer run below
+that and are reported as exactly zero.
+
+Recovering the quantum from the data — a GCD over observed timestamps, or any equivalent — *is* the
+timing attack the mitigation exists to prevent, and doing it imperfectly applies a wrong correction
+to every number in the file. So a capture records what the device reported, zeros included, and says
+nothing further. A reader that wants to present this honestly should aggregate across many frames
+rather than trust any single one, and should say so where the reader will see it.
+
+---
+
+## 5. `SYMS`
+
+| Field | Type |
+|---|---|
+| `first_index` | uintVar |
+| `count` | uintVar |
+| `strings` | utf8 × count |
+
+Strings occupy one index space across the whole file; a block declares where its run begins. Every
+later reference is a `uintVar` index into that space.
+
+A `SYMS` block **always precedes** the record that references its strings. A writer must not gather
+symbols into one block at the end of the file: a capture truncated before that block would resolve
+no names at all, which is precisely the capture of the crash somebody was trying to record.
+
+---
+
+## 6. `TOPO` — frame graph structure
+
+Present at capture level `STRUCTURE` and above.
+
+| Field | Type |
+|---|---|
+| `id` | uintVar — what a frame refers to |
+| `name` | symbol index |
+| `scope_count` | uintVar |
+| **per scope** | `name` (symbol index), `parent` (optional index) |
+| `pass_count` | uintVar |
+| **per pass** | see §6.1 |
+| `resource_count` | uintVar |
+| **per resource** | see §6.2 |
+
+A scope's parent always appears at a lower index than the scope itself, so a reader resolves the
+chain in one forward pass.
+
+### 6.1 Pass
+
+| Field | Type |
+|---|---|
+| `id` | uintVar |
+| `name` | symbol index |
+| `scope` | optional index |
+| `flags` | u8 — bit 0 `CULLED`, bit 1 `HAS_SIDE_EFFECTS` |
+| `ref_count` | uintVar |
+| `reads` | uintVar count, then that many resource **node** ids |
+| `writes` | same |
+| `creates` | same |
+
+### 6.2 Resource
+
+One entry per resource **node** — that is, per version. A pass records the node it touched rather
+than the underlying resource, so a registry-keyed model would leave every reference past version 0
+dangling.
+
+| Field | Type |
+|---|---|
+| `id` | uintVar |
+| `name` | symbol index |
+| `version` | uintVar |
+| `flags` | u8 — bit 2 `TRANSIENT`, bit 3 `IMPORTED` |
+| `producer` | optional index — the pass that produced this version |
+| `kind` | u8 — 0 none, 1 buffer, 2 texture |
+| `usage` | uintVar — `GPUBufferUsage` / `GPUTextureUsage` bitmask |
+| `byte_size` | uintVar — declared bytes, §6.3 |
+| **if buffer** | `size` (uintVar) |
+| **if texture** | `width`, `height`, `depth`, `mip_level_count`, `sample_count` (uintVar each), `format`, `dimension` (symbol indices) |
+
+### 6.3 `byte_size` is declared, and is computed by the writer
+
+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.
+
+For a texture it covers the whole mip chain at the given sample count. **The writer computes it**
+rather than leaving a reader to, because working it out needs the format's block dimensions — so a
+reader never has to carry a copy of that table, and a format the reader has never heard of still
+reports a size. A writer that cannot determine a size **must** write 0.
+
+---
+
+## 7. `FRAM` — one frame
+
+| Field | Type |
+|---|---|
+| `frame_index` | uintVar — the renderer's own counter, not a position in the file |
+| `cpu_begin_ms` | f64 — `performance.now()` when encoding began |
+| `cpu_submit_ms` | f64 — `performance.now()` at submit |
+| `gpu_epoch_ns` | u64 — the earliest GPU timestamp in this frame |
+| `dropped_pass_count` | uintVar — passes that went untimed, §7.2 |
+| `span_count` | uintVar |
+| **per span** | §7.1 |
+| `topology_id` | optional index — **appended last**, absent in a format-1 file |
+
+### 7.1 Span
+
+| Field | Type |
+|---|---|
+| `label` | symbol index |
+| `kind` | u8 — 0 compute, 1 render |
+| `query_set_id` | u8 — §7.3 |
+| `t_begin_ns` | u32 — nanoseconds from `gpu_epoch_ns` |
+| `duration_ns` | uintVar |
+| `graph_pass_id` | optional index — the frame graph pass that was executing when this pass opened |
+| `has_work` | u8 — 1 if a workload block follows |
+| **if `has_work`** | `dispatch_count`, `indirect_dispatch_count`, `workgroups_x/y/z`, `draw_count`, `indirect_draw_count`, `vertex_count`, `index_count`, `instance_count` (uintVar each), `pipeline` (symbol index), `workgroup_size_x/y/z` (uintVar each) |
+
+`t_begin_ns` is a u32 of nanoseconds, holding 4.29 s — three orders of magnitude past any frame, and
+enough to survive a stall rather than wrap. A writer **must** clamp rather than wrap, and **must**
+write a duration of 0 where a device reports an end before its begin.
+
+`has_work` is per span rather than per frame because a frame genuinely mixes the two: a pass opened
+before the recorder was attached has no workload record, and a per-frame flag would have to lie
+about one of them.
+
+A `workgroup_size` of `[0, 0, 0]` means **unknown** — typically an override-expression size — and is
+not the same as zero work. A reader must not compute an invocation count from it.
+
+### 7.2 `dropped_pass_count`
+
+Passes the recorder could not time because the frame had more of them than its query set had slots.
+Carried because an untimed pass reads downstream as a free one. A reader should surface a non-zero
+value rather than presenting the frame as complete.
+
+### 7.3 `query_set_id`
+
+Which of the frame's command contexts produced this span. Timestamps from two different
+`GPUQuerySet`s are not specified to share a clock domain, and a frame ordinarily spans several.
+Carried so that an anomaly following a query-set boundary is visible rather than unfalsifiable.
+
+### 7.4 The two clocks are not one clock
+
+`cpu_*` come from `performance.now()`; `gpu_epoch_ns` and the spans come from the device. WebGPU
+exposes no calibration between them, and this format carries none. Anything that places the two on
+one axis is anchoring, not synchronising, and should say so.
+
+---
+
+## 8. `DIRE` — directory
+
+| Field | Type |
+|---|---|
+| `record_count` | uintVar |
+| **per record** | `type` (u32), `offset` (u64), `byte_length` (u32) |
+
+Written last, and does not index itself.
+
+**A reader must not require it, and must not prefer it to the records.** It exists so that a future
+reader can seek instead of scan. A capture that never reached `stop()` has none, and is not thereby
+a lesser capture.
+
+---
+
+## 9. Conformance summary
+
+A conforming **reader**:
+
+- refuses a file whose magic does not match or whose `min_reader_version` exceeds its own;
+- reads by scanning records, and does not require a directory or the `CLOSED` flag;
+- validates sync, length and checksum together before accepting a record;
+- resynchronises past damage and reports it, rather than stopping;
+- skips unrecognised record types by length and reports that it did;
+- treats `[0, 0, 0]` workgroup sizes and absent workload blocks as *unknown*, never as zero.
+
+A conforming **writer**:
+
+- emits `META` first and `DIRE` last, and patches only `flags` and the directory fields;
+- emits a `SYMS` block before any record referencing its strings;
+- never gathers symbols into a single trailing block;
+- clamps rather than wraps out-of-range span times, and writes 0 for an unknown size;
+- records what the device reported, without correcting for timestamp quantization.
+
+---
+
+*Company Named Limited (c) 2026. The format is documented for interoperability; the engine that
+writes it is proprietary and source-available under its own licence.*

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

@@ -0,0 +1,10 @@
+/**
+ * Version of the `.sgpt` layout this build writes.
+ *
+ * Bump for any change to what a record's payload means. Adding a *new* record type is not such a
+ * change — readers skip unknown types by length — so it does not need one.
+ *
+ * @type {number}
+ */
+export const SGPT_FORMAT_VERSION: number;
+//# sourceMappingURL=SGPT_FORMAT_VERSION.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_FORMAT_VERSION.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_FORMAT_VERSION.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,kCAFU,MAAM,CAEqB"}

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

@@ -0,0 +1,9 @@
+/**
+ * Version of the `.sgpt` layout this build writes.
+ *
+ * Bump for any change to what a record's payload means. Adding a *new* record type is not such a
+ * change — readers skip unknown types by length — so it does not need one.
+ *
+ * @type {number}
+ */
+export const SGPT_FORMAT_VERSION = 2;

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

@@ -0,0 +1,17 @@
+/**
+ * Bytes the writer reserves at each frame boundary, so that {@link BinaryBuffer} growth — an
+ * allocation and a copy — happens *between* frames rather than inside one.
+ *
+ * The cost of a grow was never CPU time; it is a memcpy that may evict some cache and make the next
+ * GPU upload marginally slower, which is a rounding error against what is being measured. This
+ * keeps even that out of the interval a frame's timings are taken over.
+ *
+ * 1 MiB against a level-2 frame record of a few kilobytes is three orders of magnitude of headroom,
+ * so a reservation actually forces a grow only once every few hundred frames. That ratio holds only
+ * because resource *contents* are out of scope: nothing in a record scales with the size of the
+ * buffers and textures it describes.
+ *
+ * @type {number}
+ */
+export const SGPT_FRAME_SLACK: number;
+//# sourceMappingURL=SGPT_FRAME_SLACK.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_FRAME_SLACK.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_FRAME_SLACK.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,+BAFU,MAAM,CAE4B"}

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

@@ -0,0 +1,16 @@
+/**
+ * Bytes the writer reserves at each frame boundary, so that {@link BinaryBuffer} growth — an
+ * allocation and a copy — happens *between* frames rather than inside one.
+ *
+ * The cost of a grow was never CPU time; it is a memcpy that may evict some cache and make the next
+ * GPU upload marginally slower, which is a rounding error against what is being measured. This
+ * keeps even that out of the interval a frame's timings are taken over.
+ *
+ * 1 MiB against a level-2 frame record of a few kilobytes is three orders of magnitude of headroom,
+ * so a reservation actually forces a grow only once every few hundred frames. That ratio holds only
+ * because resource *contents* are out of scope: nothing in a record scales with the size of the
+ * buffers and textures it describes.
+ *
+ * @type {number}
+ */
+export const SGPT_FRAME_SLACK = 1024 * 1024;

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

@@ -0,0 +1,16 @@
+/**
+ * Bytes the header checksum covers: the magic and the two version fields, and nothing else.
+ *
+ * It stops short of `flags` on purpose. Everything from `flags` onward is patched at
+ * {@link GPUProfileSession#stop} — the CLOSED bit and the directory pointer — and a checksum
+ * covering them would have to be recomputed then. That is fine for a capture that stops, and
+ * exactly wrong for one that does not: the file would carry a checksum over bytes that were never
+ * written, and a reader would call the recoverable case corrupt.
+ *
+ * What is left under the checksum is what a reader must trust before it can do anything at all —
+ * is this an `.sgpt`, and can this build read it. Those never change after the header is written.
+ *
+ * @type {number}
+ */
+export const SGPT_HEADER_CHECKSUM_COVERAGE: number;
+//# sourceMappingURL=SGPT_HEADER_CHECKSUM_COVERAGE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_HEADER_CHECKSUM_COVERAGE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_HEADER_CHECKSUM_COVERAGE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,4CAFU,MAAM,CAE+B"}

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

@@ -0,0 +1,15 @@
+/**
+ * Bytes the header checksum covers: the magic and the two version fields, and nothing else.
+ *
+ * It stops short of `flags` on purpose. Everything from `flags` onward is patched at
+ * {@link GPUProfileSession#stop} — the CLOSED bit and the directory pointer — and a checksum
+ * covering them would have to be recomputed then. That is fine for a capture that stops, and
+ * exactly wrong for one that does not: the file would carry a checksum over bytes that were never
+ * written, and a reader would call the recoverable case corrupt.
+ *
+ * What is left under the checksum is what a reader must trust before it can do anything at all —
+ * is this an `.sgpt`, and can this build read it. Those never change after the header is written.
+ *
+ * @type {number}
+ */
+export const SGPT_HEADER_CHECKSUM_COVERAGE = 8;

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

@@ -0,0 +1,15 @@
+/**
+ * Byte offsets of the fields in an `.sgpt` file header. The header is the only fixed-layout region
+ * in the container; everything after it is records (see {@link SGPT_RECORD_OFFSET }).
+ */
+export type SGPT_HEADER_OFFSET = number;
+export namespace SGPT_HEADER_OFFSET {
+    let MAGIC: number;
+    let FORMAT_VERSION: number;
+    let MIN_READER_VERSION: number;
+    let FLAGS: number;
+    let HEADER_CHECKSUM: number;
+    let DIRECTORY_OFFSET: number;
+    let DIRECTORY_BYTE_LENGTH: number;
+}
+//# sourceMappingURL=SGPT_HEADER_OFFSET.d.ts.map

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

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

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

@@ -0,0 +1,29 @@
+/**
+ * Byte offsets of the fields in an `.sgpt` file header. The header is the only fixed-layout region
+ * in the container; everything after it is records (see {@link SGPT_RECORD_OFFSET}).
+ *
+ * @enum {number}
+ */
+export const SGPT_HEADER_OFFSET = {
+    /** u32, {@link SGPT_MAGIC} */
+    MAGIC: 0,
+    /** u16, {@link SGPT_FORMAT_VERSION} */
+    FORMAT_VERSION: 4,
+    /** u16, {@link SGPT_MIN_READER_VERSION} */
+    MIN_READER_VERSION: 6,
+    /** u32, {@link SGPT_FLAG} bitmask */
+    FLAGS: 8,
+    /** u32, crc32 over bytes `[0, 12)` — the fields above, and nothing that is patched later */
+    HEADER_CHECKSUM: 12,
+    /**
+     * u64, absolute offset of the directory record.
+     *
+     * **Zero means there is no directory**, which is the state of every capture that never reached
+     * {@link GPUProfileSession.stop} — the tab closed, the device was lost. Such a file is still
+     * fully readable by scanning records, and a reader that treats a zero here as corruption is
+     * throwing away exactly the captures worth having.
+     */
+    DIRECTORY_OFFSET: 16,
+    /** u64, byte length of the directory record including its own framing. Zero when absent. */
+    DIRECTORY_BYTE_LENGTH: 24
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Bytes occupied by the `.sgpt` file header. The first record starts here.
+ *
+ * @type {number}
+ */
+export const SGPT_HEADER_SIZE: number;
+//# sourceMappingURL=SGPT_HEADER_SIZE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_HEADER_SIZE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_HEADER_SIZE.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,+BAFU,MAAM,CAEmB"}

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

@@ -0,0 +1,6 @@
+/**
+ * Bytes occupied by the `.sgpt` file header. The first record starts here.
+ *
+ * @type {number}
+ */
+export const SGPT_HEADER_SIZE = 32;

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

@@ -0,0 +1,7 @@
+/**
+ * `'SGPT'` — Shade GPU Profile Trace — as a little-endian u32 at file offset 0.
+ *
+ * @type {number}
+ */
+export const SGPT_MAGIC: number;
+//# sourceMappingURL=SGPT_MAGIC.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_MAGIC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_MAGIC.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,yBAFU,MAAM,CAEqB"}

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

@@ -0,0 +1,6 @@
+/**
+ * `'SGPT'` — Shade GPU Profile Trace — as a little-endian u32 at file offset 0.
+ *
+ * @type {number}
+ */
+export const SGPT_MAGIC = 0x54504753;

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

@@ -0,0 +1,16 @@
+/**
+ * The oldest reader that can still make sense of what this build writes.
+ *
+ * A reader refuses a file whose `min_reader_version` exceeds its own {@link SGPT_FORMAT_VERSION},
+ * and opens anything else. Raise this only when a change makes an older reader produce *wrong*
+ * answers rather than incomplete ones — a new record type it would skip is incomplete, a reordered
+ * field is wrong.
+ *
+ * Still 1 at format version 2: the topology link was appended to the end of a frame's payload and
+ * `TOPO` is a new record type, so a version-1 reader skips one by length and stops before the other.
+ * It sees a capture with no structure, which is incomplete rather than wrong.
+ *
+ * @type {number}
+ */
+export const SGPT_MIN_READER_VERSION: number;
+//# sourceMappingURL=SGPT_MIN_READER_VERSION.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_MIN_READER_VERSION.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_MIN_READER_VERSION.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,sCAFU,MAAM,CAEyB"}

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

@@ -0,0 +1,15 @@
+/**
+ * The oldest reader that can still make sense of what this build writes.
+ *
+ * A reader refuses a file whose `min_reader_version` exceeds its own {@link SGPT_FORMAT_VERSION},
+ * and opens anything else. Raise this only when a change makes an older reader produce *wrong*
+ * answers rather than incomplete ones — a new record type it would skip is incomplete, a reordered
+ * field is wrong.
+ *
+ * Still 1 at format version 2: the topology link was appended to the end of a frame's payload and
+ * `TOPO` is a new record type, so a version-1 reader skips one by length and stops before the other.
+ * It sees a capture with no structure, which is incomplete rather than wrong.
+ *
+ * @type {number}
+ */
+export const SGPT_MIN_READER_VERSION = 1;

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

@@ -0,0 +1,7 @@
+/**
+ * Bytes of framing in front of every record's payload.
+ *
+ * @type {number}
+ */
+export const SGPT_RECORD_HEADER_SIZE: number;
+//# sourceMappingURL=SGPT_RECORD_HEADER_SIZE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_RECORD_HEADER_SIZE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_RECORD_HEADER_SIZE.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,sCAFU,MAAM,CAE0B"}

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

@@ -0,0 +1,6 @@
+/**
+ * Bytes of framing in front of every record's payload.
+ *
+ * @type {number}
+ */
+export const SGPT_RECORD_HEADER_SIZE = 16;

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

@@ -0,0 +1,13 @@
+/**
+ * Byte offsets within a record's framing. Every record in the stream carries this same 16-byte head,
+ * whatever its type, which is what makes the stream scannable by a reader that understands none of
+ * the payloads.
+ */
+export type SGPT_RECORD_OFFSET = number;
+export namespace SGPT_RECORD_OFFSET {
+    let SYNC: number;
+    let TYPE: number;
+    let PAYLOAD_BYTE_LENGTH: number;
+    let PAYLOAD_CHECKSUM: number;
+}
+//# sourceMappingURL=SGPT_RECORD_OFFSET.d.ts.map

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

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

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

@@ -0,0 +1,23 @@
+/**
+ * Byte offsets within a record's framing. Every record in the stream carries this same 16-byte head,
+ * whatever its type, which is what makes the stream scannable by a reader that understands none of
+ * the payloads.
+ *
+ * @enum {number}
+ */
+export const SGPT_RECORD_OFFSET = {
+    /** u32, {@link SGPT_RECORD_SYNC} */
+    SYNC: 0,
+    /** u32, a {@link SGPT_RECORD_TYPE} */
+    TYPE: 4,
+    /**
+     * u32, payload bytes following this head.
+     *
+     * u32 rather than u64 deliberately: a record describes one frame's control flow, and buffer and
+     * texture *contents* are a non-goal of this format, so nothing in a record scales with the size
+     * of the resources it describes. Four gigabytes is not a ceiling anything can approach.
+     */
+    PAYLOAD_BYTE_LENGTH: 8,
+    /** u32, crc32 over the payload bytes only */
+    PAYLOAD_CHECKSUM: 12
+};

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

@@ -0,0 +1,12 @@
+/**
+ * `'SREC'`, the little-endian u32 that opens every record in the stream.
+ *
+ * A reader that has lost its place — corruption, a torn write, a capture that ended when the tab
+ * did — scans forward for this and resumes. It is not a guarantee on its own: four bytes of payload
+ * can spell `SREC` by accident. It is the cheap filter, and the record's length and checksum are
+ * what actually confirm the find. See {@link sgpt_read_records}.
+ *
+ * @type {number}
+ */
+export const SGPT_RECORD_SYNC: number;
+//# sourceMappingURL=SGPT_RECORD_SYNC.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SGPT_RECORD_SYNC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/device/timing/profile/SGPT_RECORD_SYNC.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,+BAFU,MAAM,CAE2B"}