@plasius/gpu-debug 0.2.4

package/dist/index.js

@@ -0,0 +1,961 @@
+// src/validation.ts
+var IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;
+var gpuDebugQueueClasses = Object.freeze([
+  "render",
+  "simulation",
+  "lighting",
+  "post-processing",
+  "voxel",
+  "transfer",
+  "custom"
+]);
+var gpuResourceCategories = Object.freeze([
+  "buffer",
+  "texture",
+  "bind-group",
+  "pipeline",
+  "custom"
+]);
+var gpuPipelinePhases = Object.freeze([
+  "simulation",
+  "secondary-simulation",
+  "scene-preparation",
+  "render"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertIdentifier(name, value) {
+  if (typeof value !== "string" || !IDENTIFIER_PATTERN.test(value)) {
+    throw new Error(
+      `${name} must match ${IDENTIFIER_PATTERN.toString()} and be at most 64 characters long.`
+    );
+  }
+  return value;
+}
+function assertEnumValue(name, value, allowedValues) {
+  if (typeof value !== "string" || !allowedValues.includes(value)) {
+    throw new Error(`${name} must be one of: ${allowedValues.join(", ")}.`);
+  }
+  return value;
+}
+function readPositiveNumber(name, value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a finite number greater than zero.`);
+  }
+  return value;
+}
+function readNonNegativeNumber(name, value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a finite number greater than or equal to zero.`);
+  }
+  return value;
+}
+function readPositiveInteger(name, value) {
+  const parsed = readPositiveNumber(name, value);
+  if (parsed === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`${name} must be an integer greater than zero.`);
+  }
+  return parsed;
+}
+function normalizePlainObject(name, value) {
+  if (value === void 0) {
+    return Object.freeze({});
+  }
+  if (!isRecord(value)) {
+    throw new Error(`${name} must be a plain object when provided.`);
+  }
+  return Object.freeze({ ...value });
+}
+function normalizeVector(name, value) {
+  const x = readPositiveInteger(`${name}.x`, value.x) ?? 1;
+  const y = readPositiveInteger(`${name}.y`, value.y) ?? 1;
+  const z = readPositiveInteger(`${name}.z`, value.z) ?? 1;
+  return { x, y, z };
+}
+function isAbortSignalLike(value) {
+  return typeof value === "object" && value !== null && "aborted" in value && typeof value.aborted === "boolean";
+}
+function normalizeAdapterInfo(value) {
+  if (value === void 0) {
+    return Object.freeze({});
+  }
+  const adapter = {};
+  if (value.label !== void 0) {
+    adapter.label = String(value.label).trim().slice(0, 120);
+  }
+  if (value.vendor !== void 0) {
+    adapter.vendor = String(value.vendor).trim().slice(0, 120);
+  }
+  if (value.architecture !== void 0) {
+    adapter.architecture = String(value.architecture).trim().slice(0, 120);
+  }
+  if (value.driver !== void 0) {
+    adapter.driver = String(value.driver).trim().slice(0, 120);
+  }
+  adapter.maxBufferSizeBytes = readPositiveInteger(
+    "adapter.maxBufferSizeBytes",
+    value.maxBufferSizeBytes
+  );
+  adapter.maxStorageBufferBindingSizeBytes = readPositiveInteger(
+    "adapter.maxStorageBufferBindingSizeBytes",
+    value.maxStorageBufferBindingSizeBytes
+  );
+  adapter.maxComputeInvocationsPerWorkgroup = readPositiveInteger(
+    "adapter.maxComputeInvocationsPerWorkgroup",
+    value.maxComputeInvocationsPerWorkgroup
+  );
+  adapter.maxComputeWorkgroupsPerDimension = readPositiveInteger(
+    "adapter.maxComputeWorkgroupsPerDimension",
+    value.maxComputeWorkgroupsPerDimension
+  );
+  adapter.memoryCapacityHintBytes = readPositiveInteger(
+    "adapter.memoryCapacityHintBytes",
+    value.memoryCapacityHintBytes
+  );
+  adapter.coreCountHint = readPositiveInteger(
+    "adapter.coreCountHint",
+    value.coreCountHint
+  );
+  adapter.metadata = normalizePlainObject("adapter.metadata", value.metadata);
+  return Object.freeze(adapter);
+}
+
+// src/session.ts
+var DEFAULT_OPTIONS = Object.freeze({
+  enabled: false,
+  maxRetainedDispatches: 240,
+  maxRetainedQueueSamples: 240,
+  maxRetainedReadyLaneSamples: 240,
+  maxRetainedDependencyUnlockSamples: 240,
+  maxRetainedPipelinePhaseSamples: 240,
+  maxRetainedWavefrontSamples: 240,
+  maxRetainedFrameSamples: 240,
+  maxTrackedAllocations: 512
+});
+var LIMITATIONS = Object.freeze([
+  "Tracked memory reflects only allocations reported to this debug session.",
+  "Portable WebGPU does not expose authoritative live GPU core-count or total-memory counters.",
+  "Hardware hints are optional caller-supplied metadata and may be platform-specific.",
+  "Ready-lane and dependency-unlock diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
+  "Pipeline phase and snapshot-lag diagnostics are caller-reported integration samples, not automatic WebGPU counters.",
+  "Wavefront queue, hit-buffer, and termination diagnostics are caller-reported summaries rather than full GPU buffer dumps."
+]);
+function clampCount(value, fallback) {
+  if (!value || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return Math.min(Math.round(value), 4096);
+}
+function trimHistory(items, maxEntries) {
+  while (items.length > maxEntries) {
+    items.shift();
+  }
+}
+function average(values) {
+  if (values.length === 0) {
+    return void 0;
+  }
+  return values.reduce((total, value) => total + value, 0) / values.length;
+}
+function pushAggregate(map, key, value) {
+  map.set(key, (map.get(key) ?? 0) + value);
+}
+function normalizeAllocation(allocation) {
+  if (allocation.signal !== void 0 && !isAbortSignalLike(allocation.signal)) {
+    throw new Error("allocation.signal must be an AbortSignal when provided.");
+  }
+  return {
+    id: assertIdentifier("allocation.id", allocation.id),
+    owner: assertIdentifier("allocation.owner", allocation.owner),
+    category: assertEnumValue(
+      "allocation.category",
+      allocation.category,
+      gpuResourceCategories
+    ),
+    sizeBytes: readPositiveInteger("allocation.sizeBytes", allocation.sizeBytes) ?? 1,
+    label: allocation.label === void 0 ? void 0 : String(allocation.label).trim().slice(0, 120)
+  };
+}
+function normalizeQueueSample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("queue.signal must be an AbortSignal when provided.");
+  }
+  const capacity = readPositiveInteger("queue.capacity", sample.capacity);
+  const depth = readNonNegativeNumber("queue.depth", sample.depth) ?? 0;
+  if (capacity !== void 0 && depth > capacity) {
+    throw new Error("queue.depth cannot exceed queue.capacity.");
+  }
+  return {
+    owner: assertIdentifier("queue.owner", sample.owner),
+    queueClass: assertEnumValue(
+      "queue.queueClass",
+      sample.queueClass,
+      gpuDebugQueueClasses
+    ),
+    depth,
+    capacity,
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("queue.frameId", sample.frameId)
+  };
+}
+function normalizeReadyLaneSample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("readyLane.signal must be an AbortSignal when provided.");
+  }
+  const capacity = readPositiveInteger("readyLane.capacity", sample.capacity);
+  const depth = readNonNegativeNumber("readyLane.depth", sample.depth) ?? 0;
+  if (capacity !== void 0 && depth > capacity) {
+    throw new Error("readyLane.depth cannot exceed readyLane.capacity.");
+  }
+  const priority = readNonNegativeNumber("readyLane.priority", sample.priority);
+  if (priority !== void 0 && !Number.isInteger(priority)) {
+    throw new Error("readyLane.priority must be an integer greater than or equal to zero.");
+  }
+  return {
+    owner: assertIdentifier("readyLane.owner", sample.owner),
+    queueClass: assertEnumValue(
+      "readyLane.queueClass",
+      sample.queueClass,
+      gpuDebugQueueClasses
+    ),
+    laneId: assertIdentifier("readyLane.laneId", sample.laneId),
+    priority,
+    depth,
+    capacity,
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("readyLane.frameId", sample.frameId)
+  };
+}
+function normalizeDispatchSample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("dispatch.signal must be an AbortSignal when provided.");
+  }
+  return {
+    id: sample.id === void 0 ? void 0 : assertIdentifier("dispatch.id", sample.id),
+    owner: assertIdentifier("dispatch.owner", sample.owner),
+    queueClass: assertEnumValue(
+      "dispatch.queueClass",
+      sample.queueClass,
+      gpuDebugQueueClasses
+    ),
+    jobType: assertIdentifier("dispatch.jobType", sample.jobType),
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("dispatch.frameId", sample.frameId),
+    durationMs: readNonNegativeNumber("dispatch.durationMs", sample.durationMs),
+    workgroups: normalizeVector("dispatch.workgroups", sample.workgroups),
+    workgroupSize: normalizeVector(
+      "dispatch.workgroupSize",
+      sample.workgroupSize ?? { x: 1, y: 1, z: 1 }
+    ),
+    bytesRead: readNonNegativeNumber("dispatch.bytesRead", sample.bytesRead),
+    bytesWritten: readNonNegativeNumber("dispatch.bytesWritten", sample.bytesWritten)
+  };
+}
+function normalizeFrameSample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("frame.signal must be an AbortSignal when provided.");
+  }
+  if (sample.dropped !== void 0 && typeof sample.dropped !== "boolean") {
+    throw new Error("frame.dropped must be a boolean when provided.");
+  }
+  return {
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("frame.frameId", sample.frameId),
+    frameTimeMs: readPositiveNumber("frame.frameTimeMs", sample.frameTimeMs) ?? 0,
+    targetFrameTimeMs: readPositiveNumber(
+      "frame.targetFrameTimeMs",
+      sample.targetFrameTimeMs
+    ),
+    gpuBusyMs: readNonNegativeNumber("frame.gpuBusyMs", sample.gpuBusyMs),
+    dropped: sample.dropped
+  };
+}
+function normalizeDependencyUnlockSample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("dependencyUnlock.signal must be an AbortSignal when provided.");
+  }
+  const priority = readNonNegativeNumber(
+    "dependencyUnlock.priority",
+    sample.priority
+  );
+  if (priority !== void 0 && !Number.isInteger(priority)) {
+    throw new Error(
+      "dependencyUnlock.priority must be an integer greater than or equal to zero."
+    );
+  }
+  return {
+    owner: assertIdentifier("dependencyUnlock.owner", sample.owner),
+    queueClass: assertEnumValue(
+      "dependencyUnlock.queueClass",
+      sample.queueClass,
+      gpuDebugQueueClasses
+    ),
+    sourceJobType: assertIdentifier(
+      "dependencyUnlock.sourceJobType",
+      sample.sourceJobType
+    ),
+    unlockedJobType: assertIdentifier(
+      "dependencyUnlock.unlockedJobType",
+      sample.unlockedJobType
+    ),
+    priority,
+    unlockCount: readPositiveInteger("dependencyUnlock.unlockCount", sample.unlockCount) ?? 1,
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("dependencyUnlock.frameId", sample.frameId)
+  };
+}
+function normalizePipelinePhaseSample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("pipelinePhase.signal must be an AbortSignal when provided.");
+  }
+  const snapshotAgeFrames = readNonNegativeNumber(
+    "pipelinePhase.snapshotAgeFrames",
+    sample.snapshotAgeFrames
+  );
+  if (snapshotAgeFrames !== void 0 && !Number.isInteger(snapshotAgeFrames)) {
+    throw new Error(
+      "pipelinePhase.snapshotAgeFrames must be an integer greater than or equal to zero."
+    );
+  }
+  return {
+    owner: assertIdentifier("pipelinePhase.owner", sample.owner),
+    pipeline: assertEnumValue(
+      "pipelinePhase.pipeline",
+      sample.pipeline,
+      gpuPipelinePhases
+    ),
+    stage: assertIdentifier("pipelinePhase.stage", sample.stage),
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("pipelinePhase.frameId", sample.frameId),
+    durationMs: readNonNegativeNumber(
+      "pipelinePhase.durationMs",
+      sample.durationMs
+    ),
+    snapshotFrameId: sample.snapshotFrameId === void 0 ? void 0 : assertIdentifier("pipelinePhase.snapshotFrameId", sample.snapshotFrameId),
+    snapshotAgeFrames,
+    snapshotAgeMs: readNonNegativeNumber(
+      "pipelinePhase.snapshotAgeMs",
+      sample.snapshotAgeMs
+    )
+  };
+}
+function normalizeWavefrontHitKinds(entries) {
+  if (entries === void 0) {
+    return Object.freeze([]);
+  }
+  if (!Array.isArray(entries)) {
+    throw new Error("wavefront.hitKinds must be an array when provided.");
+  }
+  return Object.freeze(
+    entries.map((entry, index) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new Error(`wavefront.hitKinds[${index}] must be an object.`);
+      }
+      return Object.freeze({
+        kind: assertIdentifier(`wavefront.hitKinds[${index}].kind`, entry.kind),
+        count: readPositiveInteger(`wavefront.hitKinds[${index}].count`, entry.count) ?? 1
+      });
+    })
+  );
+}
+function normalizeWavefrontTerminationReasons(entries) {
+  if (entries === void 0) {
+    return Object.freeze([]);
+  }
+  if (!Array.isArray(entries)) {
+    throw new Error(
+      "wavefront.terminationReasons must be an array when provided."
+    );
+  }
+  return Object.freeze(
+    entries.map((entry, index) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new Error(
+          `wavefront.terminationReasons[${index}] must be an object.`
+        );
+      }
+      return Object.freeze({
+        reason: assertIdentifier(
+          `wavefront.terminationReasons[${index}].reason`,
+          entry.reason
+        ),
+        count: readPositiveInteger(
+          `wavefront.terminationReasons[${index}].count`,
+          entry.count
+        ) ?? 1
+      });
+    })
+  );
+}
+function normalizeWavefrontTelemetrySample(sample) {
+  if (sample.signal !== void 0 && !isAbortSignalLike(sample.signal)) {
+    throw new Error("wavefront.signal must be an AbortSignal when provided.");
+  }
+  const queueCapacity = readPositiveInteger(
+    "wavefront.queueCapacity",
+    sample.queueCapacity
+  );
+  const activeRayCount = readNonNegativeNumber("wavefront.activeRayCount", sample.activeRayCount) ?? 0;
+  if (!Number.isInteger(activeRayCount)) {
+    throw new Error("wavefront.activeRayCount must be an integer greater than or equal to zero.");
+  }
+  if (queueCapacity !== void 0 && activeRayCount > queueCapacity) {
+    throw new Error(
+      "wavefront.activeRayCount cannot exceed wavefront.queueCapacity."
+    );
+  }
+  const bounceDepth = readNonNegativeNumber("wavefront.bounceDepth", sample.bounceDepth) ?? 0;
+  if (!Number.isInteger(bounceDepth)) {
+    throw new Error("wavefront.bounceDepth must be an integer greater than or equal to zero.");
+  }
+  const overflowCount = readNonNegativeNumber("wavefront.overflowCount", sample.overflowCount) ?? 0;
+  if (!Number.isInteger(overflowCount)) {
+    throw new Error("wavefront.overflowCount must be an integer greater than or equal to zero.");
+  }
+  const hitBufferCount = readNonNegativeNumber(
+    "wavefront.hitBufferCount",
+    sample.hitBufferCount
+  );
+  if (hitBufferCount !== void 0 && !Number.isInteger(hitBufferCount)) {
+    throw new Error(
+      "wavefront.hitBufferCount must be an integer greater than or equal to zero."
+    );
+  }
+  return {
+    owner: assertIdentifier("wavefront.owner", sample.owner),
+    queueClass: assertEnumValue(
+      "wavefront.queueClass",
+      sample.queueClass,
+      gpuDebugQueueClasses
+    ),
+    frameId: sample.frameId === void 0 ? void 0 : assertIdentifier("wavefront.frameId", sample.frameId),
+    bounceDepth,
+    activeRayCount,
+    queueCapacity,
+    overflowCount,
+    hitBufferCount,
+    hitKinds: normalizeWavefrontHitKinds(sample.hitKinds),
+    terminationReasons: normalizeWavefrontTerminationReasons(
+      sample.terminationReasons
+    )
+  };
+}
+function estimateDispatchInvocations(sample) {
+  const normalized = normalizeDispatchSample(sample);
+  return normalized.workgroups.x * normalized.workgroups.y * normalized.workgroups.z * normalized.workgroupSize.x * normalized.workgroupSize.y * normalized.workgroupSize.z;
+}
+function createGpuDebugSession(options = {}) {
+  const settings = {
+    enabled: options.enabled ?? DEFAULT_OPTIONS.enabled,
+    maxRetainedDispatches: clampCount(
+      options.maxRetainedDispatches,
+      DEFAULT_OPTIONS.maxRetainedDispatches
+    ),
+    maxRetainedQueueSamples: clampCount(
+      options.maxRetainedQueueSamples,
+      DEFAULT_OPTIONS.maxRetainedQueueSamples
+    ),
+    maxRetainedReadyLaneSamples: clampCount(
+      options.maxRetainedReadyLaneSamples,
+      DEFAULT_OPTIONS.maxRetainedReadyLaneSamples
+    ),
+    maxRetainedDependencyUnlockSamples: clampCount(
+      options.maxRetainedDependencyUnlockSamples,
+      DEFAULT_OPTIONS.maxRetainedDependencyUnlockSamples
+    ),
+    maxRetainedPipelinePhaseSamples: clampCount(
+      options.maxRetainedPipelinePhaseSamples,
+      DEFAULT_OPTIONS.maxRetainedPipelinePhaseSamples
+    ),
+    maxRetainedWavefrontSamples: clampCount(
+      options.maxRetainedWavefrontSamples,
+      DEFAULT_OPTIONS.maxRetainedWavefrontSamples
+    ),
+    maxRetainedFrameSamples: clampCount(
+      options.maxRetainedFrameSamples,
+      DEFAULT_OPTIONS.maxRetainedFrameSamples
+    ),
+    maxTrackedAllocations: clampCount(
+      options.maxTrackedAllocations,
+      DEFAULT_OPTIONS.maxTrackedAllocations
+    )
+  };
+  const adapter = normalizeAdapterInfo(options.adapter);
+  let enabled = settings.enabled;
+  const allocations = /* @__PURE__ */ new Map();
+  const allocationOrder = [];
+  const queueSamples = [];
+  const readyLaneSamples = [];
+  const dispatchSamples = [];
+  const dependencyUnlockSamples = [];
+  const pipelinePhaseSamples = [];
+  const wavefrontSamples = [];
+  const frameSamples = [];
+  let peakTrackedBytes = 0;
+  const totalTrackedBytes = () => [...allocations.values()].reduce((total, allocation) => total + allocation.sizeBytes, 0);
+  const updatePeakTrackedBytes = () => {
+    peakTrackedBytes = Math.max(peakTrackedBytes, totalTrackedBytes());
+  };
+  const ensureAllocationCapacity = () => {
+    while (allocationOrder.length > settings.maxTrackedAllocations) {
+      const oldestId = allocationOrder.shift();
+      if (oldestId !== void 0) {
+        allocations.delete(oldestId);
+      }
+    }
+  };
+  const buildDispatchSnapshot = () => {
+    const durations = dispatchSamples.map((sample) => sample.durationMs).filter((value) => value !== void 0);
+    const bytesRead = dispatchSamples.map((sample) => sample.bytesRead).filter((value) => value !== void 0);
+    const bytesWritten = dispatchSamples.map((sample) => sample.bytesWritten).filter((value) => value !== void 0);
+    const byQueueClass = /* @__PURE__ */ new Map();
+    let estimatedWorkgroups = 0;
+    let estimatedInvocations = 0;
+    for (const sample of dispatchSamples) {
+      const workgroupCount = sample.workgroups.x * sample.workgroups.y * sample.workgroups.z;
+      const invocationCount = workgroupCount * sample.workgroupSize.x * sample.workgroupSize.y * sample.workgroupSize.z;
+      estimatedWorkgroups += workgroupCount;
+      estimatedInvocations += invocationCount;
+      const bucket = byQueueClass.get(sample.queueClass) ?? {
+        queueClass: sample.queueClass,
+        dispatches: 0,
+        totalDurationMs: 0,
+        estimatedInvocations: 0
+      };
+      bucket.dispatches += 1;
+      bucket.totalDurationMs += sample.durationMs ?? 0;
+      bucket.estimatedInvocations += invocationCount;
+      byQueueClass.set(sample.queueClass, bucket);
+    }
+    const frameTimes = frameSamples.map((sample) => sample.frameTimeMs);
+    const totalFrameTimeMs = frameTimes.reduce((total, value) => total + value, 0);
+    const totalDurationMs = durations.reduce((total, value) => total + value, 0);
+    return {
+      sampleCount: dispatchSamples.length,
+      totalDurationMs,
+      averageDurationMs: average(durations),
+      estimatedWorkgroups,
+      estimatedInvocations,
+      averageBytesRead: average(bytesRead),
+      averageBytesWritten: average(bytesWritten),
+      busyRatio: totalFrameTimeMs > 0 ? Math.min(totalDurationMs / totalFrameTimeMs, 1) : void 0,
+      byQueueClass: [...byQueueClass.values()].sort(
+        (left, right) => right.totalDurationMs - left.totalDurationMs
+      )
+    };
+  };
+  const buildQueueSnapshot = () => {
+    const depths = queueSamples.map((sample) => sample.depth);
+    const hottestQueues = queueSamples.map((sample) => ({
+      owner: sample.owner,
+      queueClass: sample.queueClass,
+      depth: sample.depth,
+      capacity: sample.capacity,
+      utilizationRatio: sample.capacity !== void 0 ? sample.depth / sample.capacity : void 0
+    })).sort((left, right) => {
+      const leftScore = left.utilizationRatio ?? left.depth;
+      const rightScore = right.utilizationRatio ?? right.depth;
+      return rightScore - leftScore;
+    }).slice(0, 5);
+    const peakUtilizationRatio = queueSamples.reduce(
+      (peak, sample) => {
+        if (sample.capacity === void 0) {
+          return peak;
+        }
+        const nextRatio = sample.depth / sample.capacity;
+        return peak === void 0 ? nextRatio : Math.max(peak, nextRatio);
+      },
+      void 0
+    );
+    return {
+      sampleCount: queueSamples.length,
+      averageDepth: average(depths) ?? 0,
+      peakDepth: depths.length === 0 ? 0 : Math.max(...depths),
+      peakUtilizationRatio,
+      hottestQueues
+    };
+  };
+  const buildDagSnapshot = () => {
+    const laneDepths = readyLaneSamples.map((sample) => sample.depth);
+    const hottestReadyLanes = readyLaneSamples.map((sample) => ({
+      owner: sample.owner,
+      queueClass: sample.queueClass,
+      laneId: sample.laneId,
+      priority: sample.priority,
+      depth: sample.depth,
+      capacity: sample.capacity,
+      utilizationRatio: sample.capacity !== void 0 ? sample.depth / sample.capacity : void 0
+    })).sort((left, right) => {
+      const leftScore = left.utilizationRatio ?? left.depth;
+      const rightScore = right.utilizationRatio ?? right.depth;
+      return rightScore - leftScore;
+    }).slice(0, 5);
+    const peakReadyLaneUtilizationRatio = readyLaneSamples.reduce(
+      (peak, sample) => {
+        if (sample.capacity === void 0) {
+          return peak;
+        }
+        const nextRatio = sample.depth / sample.capacity;
+        return peak === void 0 ? nextRatio : Math.max(peak, nextRatio);
+      },
+      void 0
+    );
+    const bySourceJobType = /* @__PURE__ */ new Map();
+    const byUnlockedJobType = /* @__PURE__ */ new Map();
+    let totalUnlockCount = 0;
+    for (const sample of dependencyUnlockSamples) {
+      totalUnlockCount += sample.unlockCount;
+      const sourceKey = `${sample.owner}:${sample.queueClass}:${sample.sourceJobType}`;
+      const unlockedKey = `${sample.owner}:${sample.queueClass}:${sample.unlockedJobType}:${sample.priority ?? "none"}`;
+      const sourceBucket = bySourceJobType.get(sourceKey) ?? {
+        owner: sample.owner,
+        queueClass: sample.queueClass,
+        sourceJobType: sample.sourceJobType,
+        unlockCount: 0
+      };
+      sourceBucket.unlockCount += sample.unlockCount;
+      bySourceJobType.set(sourceKey, sourceBucket);
+      const unlockedBucket = byUnlockedJobType.get(unlockedKey) ?? {
+        owner: sample.owner,
+        queueClass: sample.queueClass,
+        unlockedJobType: sample.unlockedJobType,
+        priority: sample.priority,
+        unlockCount: 0
+      };
+      unlockedBucket.unlockCount += sample.unlockCount;
+      byUnlockedJobType.set(unlockedKey, unlockedBucket);
+    }
+    return {
+      readyLaneSampleCount: readyLaneSamples.length,
+      averageReadyLaneDepth: average(laneDepths) ?? 0,
+      peakReadyLaneDepth: laneDepths.length === 0 ? 0 : Math.max(...laneDepths),
+      peakReadyLaneUtilizationRatio,
+      hottestReadyLanes,
+      dependencyUnlockSampleCount: dependencyUnlockSamples.length,
+      totalUnlockCount,
+      bySourceJobType: [...bySourceJobType.values()].sort(
+        (left, right) => right.unlockCount - left.unlockCount
+      ),
+      byUnlockedJobType: [...byUnlockedJobType.values()].sort(
+        (left, right) => right.unlockCount - left.unlockCount
+      )
+    };
+  };
+  const buildPipelineSnapshot = () => {
+    const durations = pipelinePhaseSamples.map((sample) => sample.durationMs).filter((value) => value !== void 0);
+    const snapshotAgeMsValues = pipelinePhaseSamples.map((sample) => sample.snapshotAgeMs).filter((value) => value !== void 0);
+    const snapshotAgeFrameValues = pipelinePhaseSamples.map((sample) => sample.snapshotAgeFrames).filter((value) => value !== void 0);
+    const byPipeline = /* @__PURE__ */ new Map();
+    for (const sample of pipelinePhaseSamples) {
+      const bucket = byPipeline.get(sample.pipeline) ?? {
+        pipeline: sample.pipeline,
+        sampleCount: 0,
+        totalDurationMs: 0,
+        durationValues: [],
+        snapshotAgeMsValues: [],
+        snapshotAgeFramesValues: []
+      };
+      bucket.sampleCount += 1;
+      bucket.totalDurationMs += sample.durationMs ?? 0;
+      if (sample.durationMs !== void 0) {
+        bucket.durationValues.push(sample.durationMs);
+      }
+      if (sample.snapshotAgeMs !== void 0) {
+        bucket.snapshotAgeMsValues.push(sample.snapshotAgeMs);
+      }
+      if (sample.snapshotAgeFrames !== void 0) {
+        bucket.snapshotAgeFramesValues.push(sample.snapshotAgeFrames);
+      }
+      byPipeline.set(sample.pipeline, bucket);
+    }
+    const hottestStages = pipelinePhaseSamples.map((sample) => ({
+      owner: sample.owner,
+      pipeline: sample.pipeline,
+      stage: sample.stage,
+      frameId: sample.frameId,
+      durationMs: sample.durationMs,
+      snapshotFrameId: sample.snapshotFrameId,
+      snapshotAgeFrames: sample.snapshotAgeFrames,
+      snapshotAgeMs: sample.snapshotAgeMs
+    })).sort((left, right) => {
+      const leftScore = left.durationMs ?? left.snapshotAgeMs ?? left.snapshotAgeFrames ?? 0;
+      const rightScore = right.durationMs ?? right.snapshotAgeMs ?? right.snapshotAgeFrames ?? 0;
+      return rightScore - leftScore;
+    }).slice(0, 5);
+    return {
+      sampleCount: pipelinePhaseSamples.length,
+      totalDurationMs: durations.reduce((total, value) => total + value, 0),
+      averageDurationMs: average(durations),
+      averageSnapshotAgeMs: average(snapshotAgeMsValues),
+      maxSnapshotAgeMs: snapshotAgeMsValues.length > 0 ? Math.max(...snapshotAgeMsValues) : void 0,
+      maxSnapshotAgeFrames: snapshotAgeFrameValues.length > 0 ? Math.max(...snapshotAgeFrameValues) : void 0,
+      byPipeline: [...byPipeline.values()].map((bucket) => ({
+        pipeline: bucket.pipeline,
+        sampleCount: bucket.sampleCount,
+        totalDurationMs: bucket.totalDurationMs,
+        averageDurationMs: average(bucket.durationValues),
+        averageSnapshotAgeMs: average(bucket.snapshotAgeMsValues),
+        maxSnapshotAgeMs: bucket.snapshotAgeMsValues.length > 0 ? Math.max(...bucket.snapshotAgeMsValues) : void 0,
+        maxSnapshotAgeFrames: bucket.snapshotAgeFramesValues.length > 0 ? Math.max(...bucket.snapshotAgeFramesValues) : void 0
+      })).sort((left, right) => right.totalDurationMs - left.totalDurationMs),
+      hottestStages
+    };
+  };
+  const buildWavefrontSnapshot = () => {
+    const activeRayCounts = wavefrontSamples.map((sample) => sample.activeRayCount);
+    const hitBufferCounts = wavefrontSamples.map((sample) => sample.hitBufferCount).filter((value) => value !== void 0);
+    const byBounceDepth = /* @__PURE__ */ new Map();
+    const byTerminationReason = /* @__PURE__ */ new Map();
+    const byHitKind = /* @__PURE__ */ new Map();
+    const peakQueueUtilizationRatio = wavefrontSamples.reduce(
+      (peak, sample) => {
+        if (sample.queueCapacity === void 0) {
+          return peak;
+        }
+        const ratio = sample.activeRayCount / sample.queueCapacity;
+        return peak === void 0 ? ratio : Math.max(peak, ratio);
+      },
+      void 0
+    );
+    let totalOverflowCount = 0;
+    let peakOverflowCount = 0;
+    let maxBounceDepth;
+    for (const sample of wavefrontSamples) {
+      totalOverflowCount += sample.overflowCount;
+      peakOverflowCount = Math.max(peakOverflowCount, sample.overflowCount);
+      maxBounceDepth = maxBounceDepth === void 0 ? sample.bounceDepth : Math.max(maxBounceDepth, sample.bounceDepth);
+      const bucket = byBounceDepth.get(sample.bounceDepth) ?? {
+        bounceDepth: sample.bounceDepth,
+        sampleCount: 0,
+        activeRayCounts: [],
+        hitBufferCounts: [],
+        totalOverflowCount: 0
+      };
+      bucket.sampleCount += 1;
+      bucket.activeRayCounts.push(sample.activeRayCount);
+      if (sample.hitBufferCount !== void 0) {
+        bucket.hitBufferCounts.push(sample.hitBufferCount);
+      }
+      bucket.totalOverflowCount += sample.overflowCount;
+      byBounceDepth.set(sample.bounceDepth, bucket);
+      for (const reason of sample.terminationReasons) {
+        pushAggregate(byTerminationReason, reason.reason, reason.count);
+      }
+      for (const kind of sample.hitKinds) {
+        pushAggregate(byHitKind, kind.kind, kind.count);
+      }
+    }
+    return {
+      sampleCount: wavefrontSamples.length,
+      averageActiveRayCount: average(activeRayCounts) ?? 0,
+      peakActiveRayCount: activeRayCounts.length > 0 ? Math.max(...activeRayCounts) : 0,
+      peakQueueUtilizationRatio,
+      maxBounceDepth,
+      totalOverflowCount,
+      peakOverflowCount,
+      averageHitBufferCount: average(hitBufferCounts),
+      peakHitBufferCount: hitBufferCounts.length > 0 ? Math.max(...hitBufferCounts) : void 0,
+      byBounceDepth: [...byBounceDepth.values()].map((bucket) => ({
+        bounceDepth: bucket.bounceDepth,
+        sampleCount: bucket.sampleCount,
+        averageActiveRayCount: average(bucket.activeRayCounts) ?? 0,
+        peakActiveRayCount: Math.max(...bucket.activeRayCounts),
+        averageHitBufferCount: average(bucket.hitBufferCounts),
+        peakHitBufferCount: bucket.hitBufferCounts.length > 0 ? Math.max(...bucket.hitBufferCounts) : void 0,
+        totalOverflowCount: bucket.totalOverflowCount
+      })).sort((left, right) => left.bounceDepth - right.bounceDepth),
+      byTerminationReason: [...byTerminationReason.entries()].map(([reason, count]) => ({ reason, count })).sort((left, right) => right.count - left.count),
+      byHitKind: [...byHitKind.entries()].map(([kind, count]) => ({ kind, count })).sort((left, right) => right.count - left.count)
+    };
+  };
+  return {
+    isEnabled() {
+      return enabled;
+    },
+    setEnabled(nextEnabled) {
+      enabled = Boolean(nextEnabled);
+    },
+    trackAllocation(allocation) {
+      if (!enabled || allocation.signal?.aborted === true) {
+        return () => {
+        };
+      }
+      const normalized = normalizeAllocation(allocation);
+      if (!allocations.has(normalized.id)) {
+        allocationOrder.push(normalized.id);
+      }
+      allocations.set(normalized.id, normalized);
+      ensureAllocationCapacity();
+      updatePeakTrackedBytes();
+      return () => {
+        this.releaseAllocation(normalized.id);
+      };
+    },
+    releaseAllocation(id) {
+      const normalizedId = assertIdentifier("allocation.id", id);
+      const deleted = allocations.delete(normalizedId);
+      if (!deleted) {
+        return false;
+      }
+      const index = allocationOrder.indexOf(normalizedId);
+      if (index >= 0) {
+        allocationOrder.splice(index, 1);
+      }
+      return true;
+    },
+    recordQueue(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      queueSamples.push(normalizeQueueSample(sample));
+      trimHistory(queueSamples, settings.maxRetainedQueueSamples);
+      return true;
+    },
+    recordReadyLane(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      readyLaneSamples.push(normalizeReadyLaneSample(sample));
+      trimHistory(readyLaneSamples, settings.maxRetainedReadyLaneSamples);
+      return true;
+    },
+    recordDispatch(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      dispatchSamples.push(normalizeDispatchSample(sample));
+      trimHistory(dispatchSamples, settings.maxRetainedDispatches);
+      return true;
+    },
+    recordDependencyUnlock(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      dependencyUnlockSamples.push(normalizeDependencyUnlockSample(sample));
+      trimHistory(
+        dependencyUnlockSamples,
+        settings.maxRetainedDependencyUnlockSamples
+      );
+      return true;
+    },
+    recordPipelinePhase(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      pipelinePhaseSamples.push(normalizePipelinePhaseSample(sample));
+      trimHistory(
+        pipelinePhaseSamples,
+        settings.maxRetainedPipelinePhaseSamples
+      );
+      return true;
+    },
+    recordWavefrontTelemetry(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      wavefrontSamples.push(normalizeWavefrontTelemetrySample(sample));
+      trimHistory(wavefrontSamples, settings.maxRetainedWavefrontSamples);
+      return true;
+    },
+    recordFrame(sample) {
+      if (!enabled || sample.signal?.aborted === true) {
+        return false;
+      }
+      frameSamples.push(normalizeFrameSample(sample));
+      trimHistory(frameSamples, settings.maxRetainedFrameSamples);
+      return true;
+    },
+    getSnapshot() {
+      const memoryByOwner = /* @__PURE__ */ new Map();
+      const memoryByCategory = /* @__PURE__ */ new Map();
+      for (const allocation of allocations.values()) {
+        pushAggregate(memoryByOwner, allocation.owner, allocation.sizeBytes);
+        pushAggregate(memoryByCategory, allocation.category, allocation.sizeBytes);
+      }
+      const totalBytes = totalTrackedBytes();
+      const frameTimes = frameSamples.map((sample) => sample.frameTimeMs);
+      const targetFrameTimes = frameSamples.map((sample) => sample.targetFrameTimeMs).filter((value) => value !== void 0);
+      const gpuBusyTimes = frameSamples.map((sample) => sample.gpuBusyMs).filter((value) => value !== void 0);
+      const snapshot = {
+        enabled,
+        adapter,
+        memory: {
+          totalTrackedBytes: totalBytes,
+          peakTrackedBytes,
+          allocationCount: allocations.size,
+          trackedUsageRatio: adapter.memoryCapacityHintBytes !== void 0 ? totalBytes / adapter.memoryCapacityHintBytes : void 0,
+          byOwner: [...memoryByOwner.entries()].map(([owner, bytes]) => ({ owner, bytes })).sort((left, right) => right.bytes - left.bytes),
+          byCategory: [...memoryByCategory.entries()].map(([category, bytes]) => ({ category, bytes })).sort((left, right) => right.bytes - left.bytes)
+        },
+        dispatch: buildDispatchSnapshot(),
+        queues: buildQueueSnapshot(),
+        frames: {
+          sampleCount: frameSamples.length,
+          latestFrameTimeMs: frameSamples[frameSamples.length - 1]?.frameTimeMs,
+          averageFrameTimeMs: average(frameTimes),
+          averageTargetFrameTimeMs: average(targetFrameTimes),
+          droppedFrameRatio: frameSamples.length > 0 ? frameSamples.filter((sample) => sample.dropped === true).length / frameSamples.length : void 0,
+          averageGpuBusyMs: average(gpuBusyTimes)
+        },
+        dag: buildDagSnapshot(),
+        pipeline: buildPipelineSnapshot(),
+        wavefront: buildWavefrontSnapshot(),
+        limitations: LIMITATIONS
+      };
+      return snapshot;
+    },
+    reset() {
+      allocations.clear();
+      allocationOrder.splice(0, allocationOrder.length);
+      queueSamples.splice(0, queueSamples.length);
+      readyLaneSamples.splice(0, readyLaneSamples.length);
+      dispatchSamples.splice(0, dispatchSamples.length);
+      dependencyUnlockSamples.splice(0, dependencyUnlockSamples.length);
+      pipelinePhaseSamples.splice(0, pipelinePhaseSamples.length);
+      wavefrontSamples.splice(0, wavefrontSamples.length);
+      frameSamples.splice(0, frameSamples.length);
+      peakTrackedBytes = 0;
+    }
+  };
+}
+function summarizeWavefrontTelemetry(snapshot) {
+  if (!snapshot || snapshot.sampleCount === 0) {
+    return Object.freeze(["Wavefront telemetry: no samples recorded."]);
+  }
+  const lines = [
+    `Wavefront telemetry: ${snapshot.sampleCount} samples, peak ${snapshot.peakActiveRayCount} active rays, overflow ${snapshot.totalOverflowCount}, max bounce ${snapshot.maxBounceDepth ?? 0}.`
+  ];
+  if (snapshot.byTerminationReason.length > 0) {
+    lines.push(
+      `Termination reasons: ${snapshot.byTerminationReason.slice(0, 3).map((entry) => `${entry.reason}=${entry.count}`).join(", ")}.`
+    );
+  } else {
+    lines.push("Termination reasons: none recorded.");
+  }
+  if (snapshot.byHitKind.length > 0) {
+    lines.push(
+      `Hit kinds: ${snapshot.byHitKind.slice(0, 3).map((entry) => `${entry.kind}=${entry.count}`).join(", ")}.`
+    );
+  } else {
+    lines.push("Hit kinds: none recorded.");
+  }
+  lines.push(
+    `Bounce depth: ${snapshot.byBounceDepth.map(
+      (entry) => `b${entry.bounceDepth} avg=${entry.averageActiveRayCount.toFixed(1)} peak=${entry.peakActiveRayCount}`
+    ).join("; ")}.`
+  );
+  return Object.freeze(lines);
+}
+export {
+  createGpuDebugSession,
+  estimateDispatchInvocations,
+  gpuDebugQueueClasses,
+  gpuPipelinePhases,
+  gpuResourceCategories,
+  summarizeWavefrontTelemetry
+};
+//# sourceMappingURL=index.js.map