@aura3d/debug 1.0.6

package/dist/ShaderDiagnostics.js

@@ -0,0 +1,49 @@
+import {} from "@aura3d/rendering";
+export class ShaderDiagnostics {
+    inspectSources(sources, compileLog = null) {
+        return {
+            label: sources.label,
+            marker: sources.marker,
+            markerPresentInVertex: sources.vertex.includes(sources.marker),
+            markerPresentInFragment: sources.fragment.includes(sources.marker),
+            attributes: extractNames(/\b(?:in|attribute)\s+\w+\s+(\w+)\s*;/g, `${sources.vertex}\n${sources.fragment}`),
+            uniforms: extractNames(/\buniform\s+\w+\s+(\w+)(?:\s*\[[^\]]+\])?\s*;/g, `${sources.vertex}\n${sources.fragment}`),
+            compileLog
+        };
+    }
+    inspectProgram(program, compileLog = null) {
+        return {
+            label: program.label,
+            marker: program.marker,
+            markerPresentInVertex: true,
+            markerPresentInFragment: true,
+            attributes: [...program.reflection.attributes.keys()],
+            uniforms: [...program.reflection.uniforms],
+            compileLog
+        };
+    }
+    assertMarker(report) {
+        if (!report.markerPresentInVertex || !report.markerPresentInFragment) {
+            throw new ShaderDiagnosticError("Shader marker mismatch", report);
+        }
+    }
+}
+export class ShaderDiagnosticError extends Error {
+    report;
+    constructor(message, report) {
+        super(message);
+        this.report = report;
+        this.name = "ShaderDiagnosticError";
+    }
+}
+function extractNames(pattern, source) {
+    const names = new Set();
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+        if (match[1]) {
+            names.add(match[1]);
+        }
+    }
+    return [...names];
+}
+//# sourceMappingURL=ShaderDiagnostics.js.map

package/dist/ShaderDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShaderDiagnostics.js","sourceRoot":"","sources":["../../../../packages/debug/src/ShaderDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,MAAM,mBAAmB,CAAC;AAYjF,MAAM,OAAO,iBAAiB;IAC5B,cAAc,CAAC,OAAsB,EAAE,aAA4B,IAAI;QACrE,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;YAC9D,uBAAuB,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;YAClE,UAAU,EAAE,YAAY,CAAC,uCAAuC,EAAE,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC3G,QAAQ,EAAE,YAAY,CAAC,gDAAgD,EAAE,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC;YAClH,UAAU;SACX,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,OAA4B,EAAE,aAA4B,IAAI;QAC3E,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,qBAAqB,EAAE,IAAI;YAC3B,uBAAuB,EAAE,IAAI;YAC7B,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YACrD,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1C,UAAU;SACX,CAAC;IACJ,CAAC;IAED,YAAY,CAAC,MAA8B;QACzC,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,CAAC,MAAM,CAAC,uBAAuB,EAAE,CAAC;YACrE,MAAM,IAAI,qBAAqB,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAG5B;IAFlB,YACE,OAAe,EACC,MAA8B;QAE9C,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,WAAM,GAAN,MAAM,CAAwB;QAG9C,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,SAAS,YAAY,CAAC,OAAe,EAAE,MAAc;IACnD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/C,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACb,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export { DrawCallTracker } from "./DrawCallTracker.js";
+export type { DrawCallRecord, DrawCallSnapshot } from "./DrawCallTracker.js";
+export { RenderStateInspector, RenderStateLeakError } from "./RenderStateInspector.js";
+export type { RenderStateDiff, RenderStateSnapshot, RenderStateValue } from "./RenderStateInspector.js";
+export { ShaderDiagnosticError, ShaderDiagnostics } from "./ShaderDiagnostics.js";
+export type { ShaderDiagnosticReport } from "./ShaderDiagnostics.js";
+export { MaterialDiagnosticError, MaterialDiagnostics } from "./MaterialDiagnostics.js";
+export type { MaterialDiagnosticReport } from "./MaterialDiagnostics.js";
+export { PhysicsDebugAdapter } from "./PhysicsDebugAdapter.js";
+export type { PhysicsDebugSnapshot, PhysicsStackEvidence } from "./PhysicsDebugAdapter.js";
+export { AnimationInspector } from "./AnimationInspector.js";
+export type { AnimationDebugSnapshot, AnimationVisualEvidence, SkeletonDebugSnapshot } from "./AnimationInspector.js";
+export { Profiler } from "./Profiler.js";
+export type { ProfilerMarker, ProfilerSnapshot } from "./Profiler.js";
+export { GPUProfiler } from "./GPUProfiler.js";
+export type { GPUProfilerSnapshot, GPUSample, GPUProfilerTimer } from "./GPUProfiler.js";
+export { ChromeTraceExporter } from "./ChromeTraceExporter.js";
+export type { ChromeTrace, ChromeTraceEvent, ChromeTraceExportOptions } from "./ChromeTraceExporter.js";
+export { ResourceLeakError, ResourceTracker } from "./ResourceTracker.js";
+export type { ResourceLeakReport, TrackedResource } from "./ResourceTracker.js";
+export { ECSInspector } from "./ECSInspector.js";
+export type { ECSInspectorSnapshot, ECSWorldLike } from "./ECSInspector.js";
+export { DebugOverlay } from "./DebugOverlay.js";
+export type { DebugOverlayRow, DebugOverlaySection, DebugOverlaySnapshot } from "./DebugOverlay.js";
+export { DebugLineCanvasRenderer } from "./DebugLineCanvasRenderer.js";
+export type { DebugLineCanvasRendererOptions, DebugLineCanvasRenderResult, DebugRenderLine } from "./DebugLineCanvasRenderer.js";
+export { buildAxesHelper, buildBoundsHelper, buildCameraFrustumHelper, buildDirectionalLightHelper, buildGridHelper, buildSkeletonHelper } from "./SceneHelpers.js";
+export type { AxesHelperOptions, BoundsHelperOptions, CameraFrustumHelperOptions, DebugColor, DebugVec3, DirectionalLightHelperOptions, GridHelperOptions, SkeletonHelperJoint } from "./SceneHelpers.js";
+export { ReportExporter } from "./ReportExporter.js";
+export type { DebugReport } from "./ReportExporter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/debug/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACvF,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAClF,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACxF,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACtH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACjI,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,UAAU,EACV,SAAS,EACT,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+export { DrawCallTracker } from "./DrawCallTracker.js";
+export { RenderStateInspector, RenderStateLeakError } from "./RenderStateInspector.js";
+export { ShaderDiagnosticError, ShaderDiagnostics } from "./ShaderDiagnostics.js";
+export { MaterialDiagnosticError, MaterialDiagnostics } from "./MaterialDiagnostics.js";
+export { PhysicsDebugAdapter } from "./PhysicsDebugAdapter.js";
+export { AnimationInspector } from "./AnimationInspector.js";
+export { Profiler } from "./Profiler.js";
+export { GPUProfiler } from "./GPUProfiler.js";
+export { ChromeTraceExporter } from "./ChromeTraceExporter.js";
+export { ResourceLeakError, ResourceTracker } from "./ResourceTracker.js";
+export { ECSInspector } from "./ECSInspector.js";
+export { DebugOverlay } from "./DebugOverlay.js";
+export { DebugLineCanvasRenderer } from "./DebugLineCanvasRenderer.js";
+export { buildAxesHelper, buildBoundsHelper, buildCameraFrustumHelper, buildDirectionalLightHelper, buildGridHelper, buildSkeletonHelper } from "./SceneHelpers.js";
+export { ReportExporter } from "./ReportExporter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/debug/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAW3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@aura3d/debug",
+  "version": "1.0.6",
+  "type": "module",
+  "dependencies": {
+    "@aura3d/animation": "1.0.6",
+    "@aura3d/rendering": "1.0.6",
+    "@aura3d/physics": "1.0.6"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/AnimationInspector.ts

@@ -0,0 +1,71 @@
+import type { AnimationMixer, AnimationMixerSnapshot, Skeleton } from "@aura3d/animation";
+
+export type SkeletonDebugSnapshot = {
+  readonly boneCount: number;
+  readonly boneNames: readonly string[];
+  readonly paletteMatrixCount: number;
+};
+
+export type AnimationDebugSnapshot = {
+  readonly mixer: AnimationMixerSnapshot;
+  readonly skeleton?: SkeletonDebugSnapshot;
+};
+
+export type AnimationVisualEvidence = {
+  readonly actionCount: number;
+  readonly playingActionCount: number;
+  readonly sampledTargetCount: number;
+  readonly sampledTargets: readonly string[];
+  readonly skeletonBoneCount: number;
+  readonly paletteMatrixCount: number;
+  readonly paletteHash?: string;
+  readonly stableHash: string;
+};
+
+export class AnimationInspector {
+  snapshot(mixer: Pick<AnimationMixer, "snapshot">, skeleton?: Skeleton): AnimationDebugSnapshot {
+    const snapshot: AnimationDebugSnapshot = {
+      mixer: mixer.snapshot()
+    };
+    if (skeleton) {
+      return {
+        ...snapshot,
+        skeleton: {
+        boneCount: skeleton.bones.length,
+        boneNames: skeleton.bones.map((bone) => bone.name),
+        paletteMatrixCount: skeleton.matrixPalette().length
+        }
+      };
+    }
+    return snapshot;
+  }
+
+  visualEvidence(mixer: Pick<AnimationMixer, "snapshot">, skeleton?: Skeleton): AnimationVisualEvidence {
+    const snapshot = mixer.snapshot();
+    const sampledTargets = Object.keys(snapshot.values).sort();
+    const palette = skeleton?.matrixPalette();
+    const evidenceWithoutHash = {
+      actionCount: snapshot.actionCount,
+      playingActionCount: snapshot.actions.filter((action) => action.playing).length,
+      sampledTargetCount: sampledTargets.length,
+      sampledTargets,
+      skeletonBoneCount: skeleton?.bones.length ?? 0,
+      paletteMatrixCount: palette?.length ?? 0,
+      ...(palette ? { paletteHash: stableHash(palette.map((matrix) => matrix.map((value) => Number(value.toFixed(6))))) } : {})
+    };
+    return {
+      ...evidenceWithoutHash,
+      stableHash: stableHash(evidenceWithoutHash)
+    };
+  }
+}
+
+function stableHash(value: unknown): string {
+  const input = JSON.stringify(value);
+  let hash = 2166136261;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/ChromeTraceExporter.ts

@@ -0,0 +1,158 @@
+import type { ProfilerMarker, ProfilerSnapshot } from "./Profiler.js";
+import type { GPUSample, GPUProfilerSnapshot } from "./GPUProfiler.js";
+
+export interface ChromeTraceEvent {
+  readonly name: string;
+  readonly cat: string;
+  readonly ph: "M" | "X" | "C" | "i";
+  readonly ts: number;
+  readonly pid: number;
+  readonly tid: number;
+  readonly dur?: number;
+  readonly args?: Record<string, number | string | boolean | null>;
+}
+
+export interface ChromeTrace {
+  readonly traceEvents: readonly ChromeTraceEvent[];
+  readonly displayTimeUnit: "ms";
+  readonly metadata: {
+    readonly source: "aura3d-debug-chrome-trace-exporter";
+    readonly profileName: string;
+    readonly cpuMarkerCount: number;
+    readonly gpuSampleCount: number;
+    readonly claimBoundary: string;
+  };
+}
+
+export interface ChromeTraceExportOptions {
+  readonly profileName?: string;
+  readonly processId?: number;
+  readonly cpuThreadId?: number;
+  readonly gpuThreadId?: number;
+  readonly includeCounters?: boolean;
+}
+
+export class ChromeTraceExporter {
+  static create(
+    cpu: ProfilerSnapshot,
+    gpu?: GPUProfilerSnapshot,
+    options: ChromeTraceExportOptions = {}
+  ): ChromeTrace {
+    const profileName = options.profileName?.trim() || "Aura3D profile";
+    const processId = positiveInteger(options.processId, 1);
+    const cpuThreadId = positiveInteger(options.cpuThreadId, 1);
+    const gpuThreadId = positiveInteger(options.gpuThreadId, 2);
+    const events: ChromeTraceEvent[] = [
+      metadataEvent("process_name", processId, cpuThreadId, { name: "Aura3D" }),
+      metadataEvent("thread_name", processId, cpuThreadId, { name: "CPU" }),
+      metadataEvent("thread_name", processId, gpuThreadId, { name: "GPU" })
+    ];
+
+    for (const marker of cpu.markers) {
+      events.push(cpuMarkerEvent(marker, processId, cpuThreadId));
+    }
+
+    if (gpu) {
+      for (const sample of gpu.samples) {
+        events.push(gpuSampleEvent(sample, processId, gpuThreadId));
+      }
+      if (gpu.supported === false) {
+        events.push({
+          name: "gpu_timing_unavailable",
+          cat: "gpu",
+          ph: "i",
+          ts: 0,
+          pid: processId,
+          tid: gpuThreadId,
+          args: { reason: gpu.unavailableReason ?? "GPU timing unavailable" }
+        });
+      }
+    }
+
+    if (options.includeCounters !== false) {
+      events.push({
+        name: "profile_counters",
+        cat: "counters",
+        ph: "C",
+        ts: 0,
+        pid: processId,
+        tid: cpuThreadId,
+        args: {
+          cpuMarkerCount: cpu.markerCount,
+          cpuTotalDurationMs: fixed(cpu.totalDurationMs),
+          gpuSampleCount: gpu?.sampleCount ?? 0,
+          gpuSupported: gpu?.supported ?? false
+        }
+      });
+    }
+
+    return {
+      traceEvents: events,
+      displayTimeUnit: "ms",
+      metadata: {
+        source: "aura3d-debug-chrome-trace-exporter",
+        profileName,
+        cpuMarkerCount: cpu.markerCount,
+        gpuSampleCount: gpu?.sampleCount ?? 0,
+        claimBoundary: "Chrome trace export is bounded local profiling evidence; it is not Unity/Unreal profiler parity."
+      }
+    };
+  }
+
+  static toJson(trace: ChromeTrace): string {
+    return `${JSON.stringify(trace, null, 2)}\n`;
+  }
+}
+
+function metadataEvent(name: "process_name" | "thread_name", pid: number, tid: number, args: { readonly name: string }): ChromeTraceEvent {
+  return {
+    name,
+    cat: "__metadata",
+    ph: "M",
+    ts: 0,
+    pid,
+    tid,
+    args
+  };
+}
+
+function cpuMarkerEvent(marker: ProfilerMarker, pid: number, tid: number): ChromeTraceEvent {
+  return {
+    name: marker.name,
+    cat: "cpu",
+    ph: "X",
+    ts: millisecondsToMicroseconds(marker.startMs),
+    dur: millisecondsToMicroseconds(marker.durationMs),
+    pid,
+    tid,
+    args: {
+      depth: marker.depth,
+      endMs: fixed(marker.endMs)
+    }
+  };
+}
+
+function gpuSampleEvent(sample: GPUSample, pid: number, tid: number): ChromeTraceEvent {
+  return {
+    name: sample.label,
+    cat: "gpu",
+    ph: "X",
+    ts: 0,
+    dur: millisecondsToMicroseconds(sample.durationMs),
+    pid,
+    tid,
+    args: { durationMs: fixed(sample.durationMs) }
+  };
+}
+
+function millisecondsToMicroseconds(value: number): number {
+  return Math.max(0, Math.round(value * 1_000));
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
+}
+
+function fixed(value: number): number {
+  return Number(value.toFixed(4));
+}

package/src/DebugLineCanvasRenderer.ts

@@ -0,0 +1,96 @@
+export interface DebugRenderLine {
+  readonly from: readonly [number, number, number];
+  readonly to: readonly [number, number, number];
+  readonly color: readonly [number, number, number, number];
+}
+
+export interface DebugLineCanvasRendererOptions {
+  readonly scale?: number;
+  readonly origin?: readonly [number, number];
+  readonly axis?: "xy" | "xz";
+  readonly lineWidth?: number;
+}
+
+export interface DebugLineCanvasRenderResult {
+  readonly lineCount: number;
+  readonly bounds: {
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+  };
+}
+
+export class DebugLineCanvasRenderer {
+  render(
+    context: CanvasRenderingContext2D,
+    lines: readonly DebugRenderLine[],
+    options: DebugLineCanvasRendererOptions = {}
+  ): DebugLineCanvasRenderResult {
+    const scale = options.scale ?? 1;
+    if (!Number.isFinite(scale) || scale <= 0) {
+      throw new RangeError("Debug line canvas scale must be a finite positive number.");
+    }
+    const origin = options.origin ?? [0, 0];
+    const axis = options.axis ?? "xy";
+    const lineWidth = options.lineWidth ?? 1;
+    if (!Number.isFinite(lineWidth) || lineWidth <= 0) {
+      throw new RangeError("Debug line canvas width must be a finite positive number.");
+    }
+
+    const bounds = {
+      minX: Number.POSITIVE_INFINITY,
+      minY: Number.POSITIVE_INFINITY,
+      maxX: Number.NEGATIVE_INFINITY,
+      maxY: Number.NEGATIVE_INFINITY
+    };
+
+    context.save();
+    context.lineWidth = lineWidth;
+    for (const line of lines) {
+      const from = project(line.from, axis, scale, origin);
+      const to = project(line.to, axis, scale, origin);
+      include(bounds, from);
+      include(bounds, to);
+      context.strokeStyle = rgba(line.color);
+      context.beginPath();
+      context.moveTo(from[0], from[1]);
+      context.lineTo(to[0], to[1]);
+      context.stroke();
+    }
+    context.restore();
+
+    if (lines.length === 0) {
+      return { lineCount: 0, bounds: { minX: 0, minY: 0, maxX: 0, maxY: 0 } };
+    }
+    return { lineCount: lines.length, bounds };
+  }
+}
+
+function project(
+  point: readonly [number, number, number],
+  axis: "xy" | "xz",
+  scale: number,
+  origin: readonly [number, number]
+): readonly [number, number] {
+  const y = axis === "xy" ? point[1] : point[2];
+  return [origin[0] + point[0] * scale, origin[1] - y * scale];
+}
+
+function include(bounds: { minX: number; minY: number; maxX: number; maxY: number }, point: readonly [number, number]): void {
+  bounds.minX = Math.min(bounds.minX, point[0]);
+  bounds.minY = Math.min(bounds.minY, point[1]);
+  bounds.maxX = Math.max(bounds.maxX, point[0]);
+  bounds.maxY = Math.max(bounds.maxY, point[1]);
+}
+
+function rgba(color: readonly [number, number, number, number]): string {
+  const r = Math.round(clamp01(color[0]) * 255);
+  const g = Math.round(clamp01(color[1]) * 255);
+  const b = Math.round(clamp01(color[2]) * 255);
+  return `rgba(${r}, ${g}, ${b}, ${clamp01(color[3])})`;
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, Number.isFinite(value) ? value : 0));
+}

package/src/DebugOverlay.ts

@@ -0,0 +1,35 @@
+export interface DebugOverlaySection {
+  readonly title: string;
+  readonly rows: readonly DebugOverlayRow[];
+}
+
+export interface DebugOverlayRow {
+  readonly label: string;
+  readonly value: string | number | boolean | null;
+}
+
+export interface DebugOverlaySnapshot {
+  readonly sections: readonly DebugOverlaySection[];
+}
+
+export class DebugOverlay {
+  private readonly sections = new Map<string, DebugOverlayRow[]>();
+
+  setSection(title: string, rows: readonly DebugOverlayRow[]): void {
+    const trimmed = title.trim();
+    if (trimmed.length === 0) {
+      throw new Error("Debug overlay section title is required");
+    }
+    this.sections.set(trimmed, rows.map((row) => ({ ...row })));
+  }
+
+  removeSection(title: string): void {
+    this.sections.delete(title);
+  }
+
+  snapshot(): DebugOverlaySnapshot {
+    return {
+      sections: [...this.sections.entries()].map(([title, rows]) => ({ title, rows: [...rows] }))
+    };
+  }
+}

package/src/DrawCallTracker.ts

@@ -0,0 +1,46 @@
+import { type DrawCommand, type RenderDeviceDiagnostics } from "@aura3d/rendering";
+
+export interface DrawCallRecord {
+  readonly label: string;
+  readonly topology: string;
+  readonly indexed: boolean;
+  readonly count: number;
+  readonly shader: string | null;
+}
+
+export interface DrawCallSnapshot {
+  readonly frame: number;
+  readonly total: number;
+  readonly records: readonly DrawCallRecord[];
+  readonly zeroDrawCallFailure: boolean;
+}
+
+export class DrawCallTracker {
+  private frame = 0;
+  private readonly records: DrawCallRecord[] = [];
+
+  beginFrame(): void {
+    this.frame += 1;
+    this.records.length = 0;
+  }
+
+  record(command: DrawCommand): void {
+    this.records.push({
+      label: command.label ?? "draw",
+      topology: command.topology,
+      indexed: command.indexBuffer !== undefined,
+      count: command.indexCount ?? command.vertexCount,
+      shader: command.shader?.label ?? null
+    });
+  }
+
+  capture(deviceDiagnostics?: RenderDeviceDiagnostics): DrawCallSnapshot {
+    const total = deviceDiagnostics?.drawCalls ?? this.records.length;
+    return {
+      frame: this.frame,
+      total,
+      records: [...this.records],
+      zeroDrawCallFailure: total === 0
+    };
+  }
+}

package/src/ECSInspector.ts

@@ -0,0 +1,23 @@
+export interface ECSWorldLike {
+  entities?(): readonly unknown[];
+  query?(...args: unknown[]): Iterable<unknown>;
+  readonly entityCount?: number;
+  profiler?: { snapshot(): unknown };
+}
+
+export interface ECSInspectorSnapshot {
+  readonly entityCount: number;
+  readonly profiler?: unknown;
+}
+
+export class ECSInspector {
+  snapshot(world: ECSWorldLike): ECSInspectorSnapshot {
+    const entityCount = typeof world.entityCount === "number"
+      ? world.entityCount
+      : world.entities?.().length ?? 0;
+    return {
+      entityCount,
+      ...(world.profiler ? { profiler: world.profiler.snapshot() } : {})
+    };
+  }
+}

package/src/GPUProfiler.ts

@@ -0,0 +1,48 @@
+export interface GPUProfilerSnapshot {
+  readonly supported: boolean;
+  readonly sampleCount: number;
+  readonly samples: readonly GPUSample[];
+  readonly unavailableReason?: string;
+}
+
+export interface GPUSample {
+  readonly label: string;
+  readonly durationMs: number;
+}
+
+export interface GPUProfilerTimer {
+  end(durationMs?: number): GPUSample;
+}
+
+export class GPUProfiler {
+  private readonly samples: GPUSample[] = [];
+
+  constructor(
+    private readonly supported = false,
+    private readonly unavailableReason = "GPU timing extension unavailable"
+  ) {}
+
+  begin(label: string): GPUProfilerTimer {
+    const trimmed = label.trim();
+    if (trimmed.length === 0) {
+      throw new Error("GPU profiler sample label is required");
+    }
+    const start = performance.now();
+    return {
+      end: (durationMs = performance.now() - start) => {
+        const sample = { label: trimmed, durationMs };
+        this.samples.push(sample);
+        return sample;
+      }
+    };
+  }
+
+  snapshot(): GPUProfilerSnapshot {
+    return {
+      supported: this.supported,
+      sampleCount: this.samples.length,
+      samples: [...this.samples],
+      ...(this.supported ? {} : { unavailableReason: this.unavailableReason })
+    };
+  }
+}

package/src/MaterialDiagnostics.ts

@@ -0,0 +1,59 @@
+import {
+  MaterialBinding,
+  MaterialBindingError,
+  type Material,
+  type MaterialInstance,
+  type RenderShaderProgram
+} from "@aura3d/rendering";
+
+export interface MaterialDiagnosticReport {
+  readonly materialName: string;
+  readonly shaderLabel: string;
+  readonly valid: boolean;
+  readonly diagnostics: readonly string[];
+  readonly uniforms: readonly string[];
+}
+
+export class MaterialDiagnostics {
+  inspect(material: Material | MaterialInstance, shader: RenderShaderProgram): MaterialDiagnosticReport {
+    const binding = new MaterialBinding();
+    const materialName = "baseMaterial" in material ? material.baseMaterial.name : material.name;
+    try {
+      const result = binding.bind(material, shader);
+      return {
+        materialName,
+        shaderLabel: shader.label,
+        valid: true,
+        diagnostics: [],
+        uniforms: [...result.uniforms.keys()]
+      };
+    } catch (error) {
+      if (error instanceof MaterialBindingError) {
+        return {
+          materialName,
+          shaderLabel: shader.label,
+          valid: false,
+          diagnostics: error.diagnostics,
+          uniforms: []
+        };
+      }
+      throw error;
+    }
+  }
+
+  assertValid(report: MaterialDiagnosticReport): void {
+    if (!report.valid) {
+      throw new MaterialDiagnosticError("Material diagnostics reported invalid binding", report);
+    }
+  }
+}
+
+export class MaterialDiagnosticError extends Error {
+  constructor(
+    message: string,
+    public readonly report: MaterialDiagnosticReport
+  ) {
+    super(message);
+    this.name = "MaterialDiagnosticError";
+  }
+}