@plasius/gpu-debug 0.2.5 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -20,6 +20,23 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
20
20
  - **Security**
21
21
  - (placeholder)
22
22
 
23
+ ## [0.2.6] - 2026-08-31
24
+
25
+ - **Added**
26
+ - Added bounded fixed-SPP renderer telemetry ingestion and summaries for ray
27
+ counts, path segments, timing evidence, timestamp-query status, and telemetry
28
+ memory without initiating GPU readbacks.
29
+ - Added `summarizeFixedSppTelemetry(...)` for compact operator evidence.
30
+
31
+ - **Changed**
32
+ - (placeholder)
33
+
34
+ - **Fixed**
35
+ - (placeholder)
36
+
37
+ - **Security**
38
+ - (placeholder)
39
+
23
40
  ## [0.2.5] - 2026-08-30
24
41
 
25
42
  - **Added**
@@ -253,3 +270,4 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
253
270
  [0.2.3]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.3
254
271
  [0.2.4]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.4
255
272
  [0.2.5]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.5
273
+ [0.2.6]: https://github.com/Plasius-LTD/gpu-debug/releases/tag/v0.2.6
package/README.md CHANGED
@@ -41,6 +41,8 @@ scene from the public `@plasius/gpu-shared` package surface, while
41
41
  supply those samples.
42
42
  - Records compact wavefront queue, hit-buffer, and termination summaries
43
43
  without dumping raw GPU buffers.
44
+ - Retains bounded fixed-SPP renderer evidence for primary/secondary rays, path
45
+ segments, GPU/render-job timing, timestamp-query status, and telemetry memory.
44
46
  - Summarizes frame-budget pressure alongside dispatch activity.
45
47
  - Accepts optional host-supplied hardware hints such as memory capacity or core
46
48
  count when a native or privileged runtime can provide them.
@@ -56,6 +58,7 @@ import {
56
58
  gpuDebugQueueClasses,
57
59
  gpuPipelinePhases,
58
60
  gpuResourceCategories,
61
+ summarizeFixedSppTelemetry,
59
62
  summarizeWavefrontTelemetry,
60
63
  } from "@plasius/gpu-debug";
61
64
 
@@ -156,9 +159,26 @@ debug.recordWavefrontTelemetry({
156
159
  ],
157
160
  });
158
161
 
162
+ // Pass statistics already resolved by @plasius/gpu-renderer. This call never
163
+ // initiates a GPU readback or enables renderer diagnostics on its own.
164
+ debug.recordFixedSppTelemetry({
165
+ owner: "wavefront",
166
+ queueClass: "render",
167
+ frameId: "frame-101",
168
+ samplesPerPixel: rendererStats.samplesPerPixel,
169
+ renderedSamplesPerPixel: rendererStats.renderedSamplesPerPixel,
170
+ primaryRays: rendererStats.primaryRays,
171
+ secondaryRays: rendererStats.secondaryRays,
172
+ totalPathSegments: rendererStats.totalPathSegments,
173
+ rayCounts: rendererStats.rayCounts,
174
+ timings: rendererStats.timings,
175
+ telemetryMemoryBytes: rendererStats.telemetryMemoryBytes,
176
+ });
177
+
159
178
  const snapshot = debug.getSnapshot();
160
179
  console.log(snapshot);
161
180
  console.log(summarizeWavefrontTelemetry(snapshot.wavefront));
181
+ console.log(summarizeFixedSppTelemetry(snapshot.fixedSpp));
162
182
  releaseParticles();
163
183
  ```
164
184
 
@@ -179,6 +199,8 @@ Portable WebGPU does not currently guarantee authoritative access to:
179
199
  - pipeline phase and snapshot-lag summaries when integrations report them,
180
200
  - wavefront queue, hit-buffer, termination, and bounce-depth summaries when
181
201
  integrations report compact telemetry,
202
+ - fixed-SPP ray, path-segment, timing, timestamp-query, and telemetry-memory
203
+ evidence when renderer integrations report already-resolved frame statistics,
182
204
  - optional hardware hints provided by the host runtime.
183
205
 
184
206
  If a native shell, browser extension, or proprietary platform layer can provide
@@ -189,6 +211,7 @@ an inferred optimization aid rather than a full hardware profiler.
189
211
 
190
212
  - `createGpuDebugSession(options?)`
191
213
  - `estimateDispatchInvocations(sample)`
214
+ - `summarizeFixedSppTelemetry(snapshot.fixedSpp)`
192
215
  - `gpuDebugQueueClasses`
193
216
  - `gpuPipelinePhases`
194
217
  - `gpuResourceCategories`
@@ -198,6 +221,13 @@ The exported constants are the docs-first enum contract for integrations that
198
221
  need to validate or surface queue classes, pipeline phases, or tracked resource
199
222
  categories without importing internal validation helpers.
200
223
 
224
+ `recordFixedSppTelemetry(sample)` accepts the fixed-SPP subset of the canonical
225
+ renderer frame statistics structurally, so `gpu-debug` does not need a runtime
226
+ dependency on the renderer. The method is a local ingestion boundary only: it
227
+ does not call a renderer, map a buffer, request timestamps, or read GPU memory.
228
+ Nullable secondary-ray, path-segment, and GPU-time values remain nullable in the
229
+ snapshot, while aggregates explicitly identify how many samples were measured.
230
+
201
231
  ## Worker and Frame Correlation
202
232
 
203
233
  When worker-based packages use `@plasius/gpu-worker`, prefer passing stable
package/dist/index.cjs CHANGED
@@ -25,6 +25,7 @@ __export(index_exports, {
25
25
  gpuDebugQueueClasses: () => gpuDebugQueueClasses,
26
26
  gpuPipelinePhases: () => gpuPipelinePhases,
27
27
  gpuResourceCategories: () => gpuResourceCategories,
28
+ summarizeFixedSppTelemetry: () => summarizeFixedSppTelemetry,
28
29
  summarizeWavefrontTelemetry: () => summarizeWavefrontTelemetry
29
30
  });
30
31
  module.exports = __toCommonJS(index_exports);
@@ -170,6 +171,7 @@ var DEFAULT_OPTIONS = Object.freeze({
170
171
  maxRetainedDependencyUnlockSamples: 240,
171
172
  maxRetainedPipelinePhaseSamples: 240,
172
173
  maxRetainedWavefrontSamples: 240,
174
+ maxRetainedFixedSppSamples: 240,
173
175
  maxRetainedFrameSamples: 240,
174
176
  maxTrackedAllocations: 512
175
177
  });
@@ -179,7 +181,32 @@ var LIMITATIONS = Object.freeze([
179
181
  "Hardware hints are optional caller-supplied metadata and may be platform-specific.",
180
182
  "Ready-lane and dependency-unlock diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
181
183
  "Pipeline phase and snapshot-lag diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
182
- "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps."
184
+ "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps.",
185
+ "Fixed-SPP ray and timing evidence is retained from caller-resolved renderer statistics; this package does not initiate GPU readbacks."
186
+ ]);
187
+ var FIXED_SPP_RAY_COUNT_STATUSES = Object.freeze([
188
+ "not-requested",
189
+ "available",
190
+ "unavailable",
191
+ "failed"
192
+ ]);
193
+ var FIXED_SPP_TIMING_STATUSES = Object.freeze([
194
+ "not-requested",
195
+ "available",
196
+ "fallback",
197
+ "unavailable",
198
+ "failed"
199
+ ]);
200
+ var FIXED_SPP_TIMESTAMP_QUERY_STATUSES = Object.freeze([
201
+ "not-recorded",
202
+ "available",
203
+ "unsupported",
204
+ "failed"
205
+ ]);
206
+ var FIXED_SPP_TIMING_SOURCES = Object.freeze([
207
+ "timestamp-query",
208
+ "queue-completion",
209
+ "cpu-submit"
183
210
  ]);
184
211
  function clampCount(value, fallback) {
185
212
  if (!value || !Number.isFinite(value) || value <= 0) {
@@ -475,6 +502,277 @@ function normalizeWavefrontTelemetrySample(sample) {
475
502
  )
476
503
  };
477
504
  }
505
+ function readNullableNonNegativeInteger(name, value) {
506
+ if (value === null) {
507
+ return null;
508
+ }
509
+ const parsed = readNonNegativeNumber(name, value);
510
+ if (parsed === void 0 || !Number.isInteger(parsed)) {
511
+ throw new Error(`${name} must be null or an integer greater than or equal to zero.`);
512
+ }
513
+ return parsed;
514
+ }
515
+ function readRequiredNonNegativeInteger(name, value) {
516
+ const parsed = readNonNegativeNumber(name, value);
517
+ if (parsed === void 0 || !Number.isInteger(parsed)) {
518
+ throw new Error(`${name} must be an integer greater than or equal to zero.`);
519
+ }
520
+ return parsed;
521
+ }
522
+ function readRequiredPositiveInteger(name, value) {
523
+ const parsed = readPositiveInteger(name, value);
524
+ if (parsed === void 0) {
525
+ throw new Error(`${name} must be an integer greater than zero.`);
526
+ }
527
+ return parsed;
528
+ }
529
+ function readRequiredNonNegativeNumber(name, value) {
530
+ const parsed = readNonNegativeNumber(name, value);
531
+ if (parsed === void 0) {
532
+ throw new Error(`${name} must be a finite number greater than or equal to zero.`);
533
+ }
534
+ return parsed;
535
+ }
536
+ function readNullableNonNegativeNumber(name, value) {
537
+ if (value === null) {
538
+ return null;
539
+ }
540
+ const parsed = readNonNegativeNumber(name, value);
541
+ if (parsed === void 0) {
542
+ throw new Error(`${name} must be null or a finite number greater than or equal to zero.`);
543
+ }
544
+ return parsed;
545
+ }
546
+ function normalizeEvidenceReason(name, value) {
547
+ if (value === null) {
548
+ return null;
549
+ }
550
+ if (typeof value !== "string" || value.trim().length === 0) {
551
+ throw new Error(`${name} must be null or a non-empty string.`);
552
+ }
553
+ return value.trim().slice(0, 240);
554
+ }
555
+ function normalizeFixedSppRayCounts(value) {
556
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
557
+ throw new Error("fixedSpp.rayCounts must be an object.");
558
+ }
559
+ if (!Array.isArray(value.bounceHistogram)) {
560
+ throw new Error("fixedSpp.rayCounts.bounceHistogram must be an array.");
561
+ }
562
+ const status = assertEnumValue(
563
+ "fixedSpp.rayCounts.status",
564
+ value.status,
565
+ FIXED_SPP_RAY_COUNT_STATUSES
566
+ );
567
+ const source = value.source === null ? null : assertEnumValue(
568
+ "fixedSpp.rayCounts.source",
569
+ value.source,
570
+ ["gpu-active-queue-readback"]
571
+ );
572
+ const expectedPrimaryRays = readNullableNonNegativeInteger(
573
+ "fixedSpp.rayCounts.expectedPrimaryRays",
574
+ value.expectedPrimaryRays
575
+ );
576
+ const observedPrimaryRays = readNullableNonNegativeInteger(
577
+ "fixedSpp.rayCounts.observedPrimaryRays",
578
+ value.observedPrimaryRays
579
+ );
580
+ const secondaryRays = readNullableNonNegativeInteger(
581
+ "fixedSpp.rayCounts.secondaryRays",
582
+ value.secondaryRays
583
+ );
584
+ const totalPathSegments = readNullableNonNegativeInteger(
585
+ "fixedSpp.rayCounts.totalPathSegments",
586
+ value.totalPathSegments
587
+ );
588
+ const bounceHistogram = Object.freeze(
589
+ value.bounceHistogram.map(
590
+ (count, index) => readRequiredNonNegativeInteger(
591
+ `fixedSpp.rayCounts.bounceHistogram[${index}]`,
592
+ count
593
+ )
594
+ )
595
+ );
596
+ const capturedRayCounts = readRequiredNonNegativeInteger(
597
+ "fixedSpp.rayCounts.capturedRayCounts",
598
+ value.capturedRayCounts
599
+ );
600
+ const expectedRayCounts = readRequiredNonNegativeInteger(
601
+ "fixedSpp.rayCounts.expectedRayCounts",
602
+ value.expectedRayCounts
603
+ );
604
+ const reason = normalizeEvidenceReason(
605
+ "fixedSpp.rayCounts.reason",
606
+ value.reason
607
+ );
608
+ if (capturedRayCounts !== bounceHistogram.length) {
609
+ throw new Error(
610
+ "fixedSpp.rayCounts.capturedRayCounts must match the bounce histogram length."
611
+ );
612
+ }
613
+ if (status === "available" && (source === null || expectedPrimaryRays === null || observedPrimaryRays === null || secondaryRays === null || totalPathSegments === null)) {
614
+ throw new Error(
615
+ "available fixedSpp.rayCounts require a source and complete ray measurements."
616
+ );
617
+ }
618
+ if (status === "available" && bounceHistogram.reduce((total, count) => total + count, 0) !== totalPathSegments) {
619
+ throw new Error(
620
+ "available fixedSpp.rayCounts bounce histogram must sum to totalPathSegments."
621
+ );
622
+ }
623
+ return Object.freeze({
624
+ status,
625
+ source,
626
+ expectedPrimaryRays,
627
+ observedPrimaryRays,
628
+ secondaryRays,
629
+ totalPathSegments,
630
+ bounceHistogram,
631
+ capturedRayCounts,
632
+ expectedRayCounts,
633
+ reason
634
+ });
635
+ }
636
+ function normalizeFixedSppTimings(value) {
637
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
638
+ throw new Error("fixedSpp.timings must be an object.");
639
+ }
640
+ const status = assertEnumValue(
641
+ "fixedSpp.timings.status",
642
+ value.status,
643
+ FIXED_SPP_TIMING_STATUSES
644
+ );
645
+ const source = value.source === null ? null : assertEnumValue(
646
+ "fixedSpp.timings.source",
647
+ value.source,
648
+ FIXED_SPP_TIMING_SOURCES
649
+ );
650
+ const timestampQueryStatus = assertEnumValue(
651
+ "fixedSpp.timings.timestampQueryStatus",
652
+ value.timestampQueryStatus,
653
+ FIXED_SPP_TIMESTAMP_QUERY_STATUSES
654
+ );
655
+ const totalGpuTimeMs = readNullableNonNegativeNumber(
656
+ "fixedSpp.timings.totalGpuTimeMs",
657
+ value.totalGpuTimeMs
658
+ );
659
+ const totalRenderJobTimeMs = readRequiredNonNegativeNumber(
660
+ "fixedSpp.timings.totalRenderJobTimeMs",
661
+ value.totalRenderJobTimeMs
662
+ );
663
+ const classificationTimeMs = readNullableNonNegativeNumber(
664
+ "fixedSpp.timings.classificationTimeMs",
665
+ value.classificationTimeMs
666
+ );
667
+ const compactionTimeMs = readNullableNonNegativeNumber(
668
+ "fixedSpp.timings.compactionTimeMs",
669
+ value.compactionTimeMs
670
+ );
671
+ const samplingTimeMs = readNullableNonNegativeNumber(
672
+ "fixedSpp.timings.samplingTimeMs",
673
+ value.samplingTimeMs
674
+ );
675
+ const reason = normalizeEvidenceReason("fixedSpp.timings.reason", value.reason);
676
+ if (timestampQueryStatus === "available" && (status !== "available" || source !== "timestamp-query" || totalGpuTimeMs === null)) {
677
+ throw new Error(
678
+ "available timestamp-query evidence requires available timestamp timing and totalGpuTimeMs."
679
+ );
680
+ }
681
+ return Object.freeze({
682
+ status,
683
+ source,
684
+ timestampQueryStatus,
685
+ totalGpuTimeMs,
686
+ totalRenderJobTimeMs,
687
+ classificationTimeMs,
688
+ compactionTimeMs,
689
+ samplingTimeMs,
690
+ reason
691
+ });
692
+ }
693
+ function normalizeFixedSppTelemetrySample(sample) {
694
+ if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
695
+ throw new Error("fixedSpp.signal must be an AbortSignal when provided.");
696
+ }
697
+ const samplesPerPixel = readRequiredPositiveInteger(
698
+ "fixedSpp.samplesPerPixel",
699
+ sample.samplesPerPixel
700
+ );
701
+ const renderedSamplesPerPixel = readRequiredPositiveInteger(
702
+ "fixedSpp.renderedSamplesPerPixel",
703
+ sample.renderedSamplesPerPixel
704
+ );
705
+ if (renderedSamplesPerPixel > samplesPerPixel) {
706
+ throw new Error(
707
+ "fixedSpp.renderedSamplesPerPixel cannot exceed fixedSpp.samplesPerPixel."
708
+ );
709
+ }
710
+ const primaryRays = readRequiredNonNegativeInteger(
711
+ "fixedSpp.primaryRays",
712
+ sample.primaryRays
713
+ );
714
+ const secondaryRays = readNullableNonNegativeInteger(
715
+ "fixedSpp.secondaryRays",
716
+ sample.secondaryRays
717
+ );
718
+ const totalPathSegments = readNullableNonNegativeInteger(
719
+ "fixedSpp.totalPathSegments",
720
+ sample.totalPathSegments
721
+ );
722
+ const rayCounts = normalizeFixedSppRayCounts(sample.rayCounts);
723
+ const timings = normalizeFixedSppTimings(sample.timings);
724
+ const telemetryMemoryBytes = readRequiredNonNegativeInteger(
725
+ "fixedSpp.telemetryMemoryBytes",
726
+ sample.telemetryMemoryBytes
727
+ );
728
+ if (secondaryRays !== rayCounts.secondaryRays) {
729
+ throw new Error(
730
+ "fixedSpp.secondaryRays must match fixedSpp.rayCounts.secondaryRays."
731
+ );
732
+ }
733
+ if (totalPathSegments !== rayCounts.totalPathSegments) {
734
+ throw new Error(
735
+ "fixedSpp.totalPathSegments must match fixedSpp.rayCounts.totalPathSegments."
736
+ );
737
+ }
738
+ if (secondaryRays === null !== (totalPathSegments === null)) {
739
+ throw new Error(
740
+ "fixedSpp.secondaryRays and fixedSpp.totalPathSegments must both be measured or both be null."
741
+ );
742
+ }
743
+ if (secondaryRays !== null && totalPathSegments !== primaryRays + secondaryRays) {
744
+ throw new Error(
745
+ "fixedSpp.totalPathSegments must equal primaryRays plus secondaryRays when measured."
746
+ );
747
+ }
748
+ if (rayCounts.expectedPrimaryRays !== null && rayCounts.expectedPrimaryRays !== primaryRays) {
749
+ throw new Error(
750
+ "fixedSpp.primaryRays must match fixedSpp.rayCounts.expectedPrimaryRays."
751
+ );
752
+ }
753
+ if (rayCounts.status === "available" && rayCounts.observedPrimaryRays !== primaryRays) {
754
+ throw new Error(
755
+ "available fixedSpp.rayCounts observedPrimaryRays must match primaryRays."
756
+ );
757
+ }
758
+ return Object.freeze({
759
+ owner: assertIdentifier("fixedSpp.owner", sample.owner),
760
+ queueClass: assertEnumValue(
761
+ "fixedSpp.queueClass",
762
+ sample.queueClass,
763
+ gpuDebugQueueClasses
764
+ ),
765
+ frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("fixedSpp.frameId", sample.frameId),
766
+ samplesPerPixel,
767
+ renderedSamplesPerPixel,
768
+ primaryRays,
769
+ secondaryRays,
770
+ totalPathSegments,
771
+ rayCounts,
772
+ timings,
773
+ telemetryMemoryBytes
774
+ });
775
+ }
478
776
  function estimateDispatchInvocations(sample) {
479
777
  const normalized = normalizeDispatchSample(sample);
480
778
  return normalized.workgroups.x * normalized.workgroups.y * normalized.workgroups.z * normalized.workgroupSize.x * normalized.workgroupSize.y * normalized.workgroupSize.z;
@@ -506,6 +804,10 @@ function createGpuDebugSession(options = {}) {
506
804
  options.maxRetainedWavefrontSamples,
507
805
  DEFAULT_OPTIONS.maxRetainedWavefrontSamples
508
806
  ),
807
+ maxRetainedFixedSppSamples: clampCount(
808
+ options.maxRetainedFixedSppSamples,
809
+ DEFAULT_OPTIONS.maxRetainedFixedSppSamples
810
+ ),
509
811
  maxRetainedFrameSamples: clampCount(
510
812
  options.maxRetainedFrameSamples,
511
813
  DEFAULT_OPTIONS.maxRetainedFrameSamples
@@ -525,6 +827,7 @@ function createGpuDebugSession(options = {}) {
525
827
  const dependencyUnlockSamples = [];
526
828
  const pipelinePhaseSamples = [];
527
829
  const wavefrontSamples = [];
830
+ const fixedSppSamples = [];
528
831
  const frameSamples = [];
529
832
  let peakTrackedBytes = 0;
530
833
  const totalTrackedBytes = () => [...allocations.values()].reduce((total, allocation) => total + allocation.sizeBytes, 0);
@@ -803,6 +1106,67 @@ function createGpuDebugSession(options = {}) {
803
1106
  byHitKind: [...byHitKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count)
804
1107
  };
805
1108
  };
1109
+ const buildFixedSppSnapshot = () => {
1110
+ const primaryRays = fixedSppSamples.map((sample) => sample.primaryRays);
1111
+ const measuredSecondaryRays = fixedSppSamples.map((sample) => sample.secondaryRays).filter((value) => value !== null);
1112
+ const measuredPathSegments = fixedSppSamples.map((sample) => sample.totalPathSegments).filter((value) => value !== null);
1113
+ const gpuTimes = fixedSppSamples.map((sample) => sample.timings.totalGpuTimeMs).filter((value) => value !== null);
1114
+ const renderJobTimes = fixedSppSamples.map(
1115
+ (sample) => sample.timings.totalRenderJobTimeMs
1116
+ );
1117
+ const classificationTimes = fixedSppSamples.map((sample) => sample.timings.classificationTimeMs).filter((value) => value !== null);
1118
+ const compactionTimes = fixedSppSamples.map((sample) => sample.timings.compactionTimeMs).filter((value) => value !== null);
1119
+ const samplingTimes = fixedSppSamples.map((sample) => sample.timings.samplingTimeMs).filter((value) => value !== null);
1120
+ const telemetryMemory = fixedSppSamples.map(
1121
+ (sample) => sample.telemetryMemoryBytes
1122
+ );
1123
+ const byRayCountStatus = /* @__PURE__ */ new Map();
1124
+ const byTimingStatus = /* @__PURE__ */ new Map();
1125
+ const byTimestampQueryStatus = /* @__PURE__ */ new Map();
1126
+ for (const sample of fixedSppSamples) {
1127
+ pushAggregate(byRayCountStatus, sample.rayCounts.status, 1);
1128
+ pushAggregate(byTimingStatus, sample.timings.status, 1);
1129
+ pushAggregate(
1130
+ byTimestampQueryStatus,
1131
+ sample.timings.timestampQueryStatus,
1132
+ 1
1133
+ );
1134
+ }
1135
+ return {
1136
+ sampleCount: fixedSppSamples.length,
1137
+ measuredRayCountSampleCount: measuredPathSegments.length,
1138
+ measuredGpuTimeSampleCount: gpuTimes.length,
1139
+ totalPrimaryRays: primaryRays.reduce((total, value) => total + value, 0),
1140
+ totalMeasuredSecondaryRays: measuredSecondaryRays.reduce(
1141
+ (total, value) => total + value,
1142
+ 0
1143
+ ),
1144
+ totalMeasuredPathSegments: measuredPathSegments.reduce(
1145
+ (total, value) => total + value,
1146
+ 0
1147
+ ),
1148
+ averagePrimaryRays: average(primaryRays),
1149
+ averageMeasuredSecondaryRays: average(measuredSecondaryRays),
1150
+ averageMeasuredPathSegments: average(measuredPathSegments),
1151
+ averageGpuTimeMs: average(gpuTimes),
1152
+ averageRenderJobTimeMs: average(renderJobTimes),
1153
+ averageClassificationTimeMs: average(classificationTimes),
1154
+ averageCompactionTimeMs: average(compactionTimes),
1155
+ averageSamplingTimeMs: average(samplingTimes),
1156
+ peakTelemetryMemoryBytes: telemetryMemory.length > 0 ? Math.max(...telemetryMemory) : 0,
1157
+ byRayCountStatus: [...byRayCountStatus.entries()].map(
1158
+ ([status, count]) => ({ status, count })
1159
+ ),
1160
+ byTimingStatus: [...byTimingStatus.entries()].map(([status, count]) => ({
1161
+ status,
1162
+ count
1163
+ })),
1164
+ byTimestampQueryStatus: [...byTimestampQueryStatus.entries()].map(
1165
+ ([status, count]) => ({ status, count })
1166
+ ),
1167
+ latest: fixedSppSamples[fixedSppSamples.length - 1]
1168
+ };
1169
+ };
806
1170
  return {
807
1171
  isEnabled() {
808
1172
  return enabled;
@@ -892,6 +1256,14 @@ function createGpuDebugSession(options = {}) {
892
1256
  trimHistory(wavefrontSamples, settings.maxRetainedWavefrontSamples);
893
1257
  return true;
894
1258
  },
1259
+ recordFixedSppTelemetry(sample) {
1260
+ if (!enabled || sample.signal?.aborted === true) {
1261
+ return false;
1262
+ }
1263
+ fixedSppSamples.push(normalizeFixedSppTelemetrySample(sample));
1264
+ trimHistory(fixedSppSamples, settings.maxRetainedFixedSppSamples);
1265
+ return true;
1266
+ },
895
1267
  recordFrame(sample) {
896
1268
  if (!enabled || sample.signal?.aborted === true) {
897
1269
  return false;
@@ -935,6 +1307,7 @@ function createGpuDebugSession(options = {}) {
935
1307
  dag: buildDagSnapshot(),
936
1308
  pipeline: buildPipelineSnapshot(),
937
1309
  wavefront: buildWavefrontSnapshot(),
1310
+ fixedSpp: buildFixedSppSnapshot(),
938
1311
  limitations: LIMITATIONS
939
1312
  };
940
1313
  return snapshot;
@@ -948,6 +1321,7 @@ function createGpuDebugSession(options = {}) {
948
1321
  dependencyUnlockSamples.splice(0, dependencyUnlockSamples.length);
949
1322
  pipelinePhaseSamples.splice(0, pipelinePhaseSamples.length);
950
1323
  wavefrontSamples.splice(0, wavefrontSamples.length);
1324
+ fixedSppSamples.splice(0, fixedSppSamples.length);
951
1325
  frameSamples.splice(0, frameSamples.length);
952
1326
  peakTrackedBytes = 0;
953
1327
  }
@@ -981,6 +1355,24 @@ function summarizeWavefrontTelemetry(snapshot) {
981
1355
  );
982
1356
  return Object.freeze(lines);
983
1357
  }
1358
+ function summarizeStatusCounts(entries) {
1359
+ return entries.length === 0 ? "none" : entries.map((entry) => `${entry.status}=${entry.count}`).join(", ");
1360
+ }
1361
+ function sampleLabel(count) {
1362
+ return count === 1 ? "sample" : "samples";
1363
+ }
1364
+ function summarizeFixedSppTelemetry(snapshot) {
1365
+ if (!snapshot || snapshot.sampleCount === 0) {
1366
+ return Object.freeze(["Fixed-SPP telemetry: no samples recorded."]);
1367
+ }
1368
+ const gpuTiming = snapshot.averageGpuTimeMs === void 0 ? "GPU unavailable from 0 samples" : `GPU avg ${snapshot.averageGpuTimeMs.toFixed(2)} ms from ${snapshot.measuredGpuTimeSampleCount} ${sampleLabel(snapshot.measuredGpuTimeSampleCount)}`;
1369
+ const renderJobTiming = snapshot.averageRenderJobTimeMs === void 0 ? "render-job unavailable from 0 samples" : `render-job avg ${snapshot.averageRenderJobTimeMs.toFixed(2)} ms from ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}`;
1370
+ return Object.freeze([
1371
+ `Fixed-SPP telemetry: ${snapshot.sampleCount} ${sampleLabel(snapshot.sampleCount)}, ${snapshot.totalPrimaryRays} primary rays, ${snapshot.totalMeasuredSecondaryRays} measured secondary rays, ${snapshot.totalMeasuredPathSegments} measured path segments.`,
1372
+ `Timing: ${gpuTiming}; ${renderJobTiming}.`,
1373
+ `Evidence: ray counts ${summarizeStatusCounts(snapshot.byRayCountStatus)}; timestamp queries ${summarizeStatusCounts(snapshot.byTimestampQueryStatus)}; peak telemetry memory ${snapshot.peakTelemetryMemoryBytes} bytes.`
1374
+ ]);
1375
+ }
984
1376
  // Annotate the CommonJS export names for ESM import in node:
985
1377
  0 && (module.exports = {
986
1378
  createGpuDebugSession,
@@ -988,6 +1380,7 @@ function summarizeWavefrontTelemetry(snapshot) {
988
1380
  gpuDebugQueueClasses,
989
1381
  gpuPipelinePhases,
990
1382
  gpuResourceCategories,
1383
+ summarizeFixedSppTelemetry,
991
1384
  summarizeWavefrontTelemetry
992
1385
  });
993
1386
  //# sourceMappingURL=index.cjs.map