@aura3d/debug 1.4.0 → 1.4.2

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@aura3d/debug",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "dependencies": {
-    "@aura3d/animation": "1.4.0",
-    "@aura3d/rendering": "1.4.0",
-    "@aura3d/physics": "1.4.0"
+    "@aura3d/animation": "1.4.2",
+    "@aura3d/physics": "1.4.2",
+    "@aura3d/rendering": "1.4.2"
   },
   "exports": {
     ".": {
@@ -14,5 +14,37 @@
     }
   },
   "main": "./dist/index.js",
-  "types": "./dist/index.d.ts"
+  "types": "./dist/index.d.ts",
+  "description": "Diagnostics helpers for rendering, materials, shaders, physics, animation, ECS, profiling, resource leaks, overlays, and report export.",
+  "keywords": [
+    "aura3d",
+    "3d",
+    "browser-3d",
+    "web-3d",
+    "typescript",
+    "debug",
+    "diagnostics",
+    "profiler",
+    "render-debug",
+    "shader-debug",
+    "overlays",
+    "telemetry"
+  ],
+  "homepage": "https://aura3d.auraone.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/auraoneai/aura3d.git",
+    "directory": "packages/debug"
+  },
+  "bugs": {
+    "url": "https://github.com/auraoneai/aura3d/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ]
 }

package/src/AnimationInspector.ts

@@ -1,71 +0,0 @@
-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

@@ -1,158 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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";
-  }
-}

package/src/PhysicsDebugAdapter.ts

@@ -1,86 +0,0 @@
-import { PhysicsDebugDraw, type DebugLine, type PhysicsWorld } from "@aura3d/physics";
-
-export type PhysicsDebugSnapshot = {
-  readonly bodyCount: number;
-  readonly colliderCount: number;
-  readonly contactCount: number;
-  readonly lines: readonly DebugLine[];
-};
-
-export type PhysicsStackEvidence = {
-  readonly bodyCount: number;
-  readonly dynamicBodyCount: number;
-  readonly contactCount: number;
-  readonly lineCount: number;
-  readonly minY: number;
-  readonly maxY: number;
-  readonly settledCount: number;
-  readonly bodyPositions: readonly {
-    readonly id: number;
-    readonly type: string;
-    readonly position: readonly [number, number, number];
-  }[];
-  readonly stableHash: string;
-};
-
-export class PhysicsDebugAdapter {
-  private readonly draw = new PhysicsDebugDraw();
-
-  buildLines(world: Pick<PhysicsWorld, "colliders" | "getBody">): readonly DebugLine[] {
-    return this.draw.buildLines(world);
-  }
-
-  snapshot(world: Pick<PhysicsWorld, "colliders" | "bodies" | "getBody" | "snapshot">): PhysicsDebugSnapshot {
-    return {
-      bodyCount: world.bodies().length,
-      colliderCount: world.colliders().length,
-      contactCount: world.snapshot().contacts.length,
-      lines: this.buildLines(world)
-    };
-  }
-
-  stackEvidence(world: Pick<PhysicsWorld, "colliders" | "bodies" | "getBody" | "snapshot">, velocityEpsilon = 0.05): PhysicsStackEvidence {
-    const snapshot = world.snapshot();
-    const lines = this.buildLines(world);
-    const bodyPositions = snapshot.bodies.map((body) => ({
-      id: body.id,
-      type: body.type,
-      position: roundVec3(body.position)
-    }));
-    const dynamicBodies = snapshot.bodies.filter((body) => body.type === "dynamic");
-    const settledCount = dynamicBodies.filter((body) => Math.hypot(body.velocity[0], body.velocity[1], body.velocity[2]) <= velocityEpsilon).length;
-    const ys = snapshot.bodies.map((body) => body.position[1]);
-    const evidenceWithoutHash = {
-      bodyCount: snapshot.stats.bodies,
-      dynamicBodyCount: dynamicBodies.length,
-      contactCount: snapshot.contacts.length,
-      lineCount: lines.length,
-      minY: roundNumber(ys.length > 0 ? Math.min(...ys) : 0),
-      maxY: roundNumber(ys.length > 0 ? Math.max(...ys) : 0),
-      settledCount,
-      bodyPositions
-    };
-    return {
-      ...evidenceWithoutHash,
-      stableHash: stableHash(evidenceWithoutHash)
-    };
-  }
-}
-
-function roundNumber(value: number, places = 6): number {
-  return Number(value.toFixed(places));
-}
-
-function roundVec3(value: readonly [number, number, number]): [number, number, number] {
-  return [roundNumber(value[0]), roundNumber(value[1]), roundNumber(value[2])];
-}
-
-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/Profiler.ts

@@ -1,77 +0,0 @@
-export interface ProfilerMarker {
-  readonly name: string;
-  readonly startMs: number;
-  readonly endMs: number;
-  readonly durationMs: number;
-  readonly depth: number;
-}
-
-export interface ProfilerSnapshot {
-  readonly markerCount: number;
-  readonly totalDurationMs: number;
-  readonly markers: readonly ProfilerMarker[];
-}
-
-interface ActiveMarker {
-  readonly name: string;
-  readonly startMs: number;
-  readonly depth: number;
-}
-
-export class Profiler {
-  private readonly active: ActiveMarker[] = [];
-  private readonly markers: ProfilerMarker[] = [];
-
-  constructor(private readonly now: () => number = () => performance.now()) {}
-
-  begin(name: string): void {
-    const trimmed = name.trim();
-    if (trimmed.length === 0) {
-      throw new Error("Profiler marker name is required");
-    }
-    this.active.push({ name: trimmed, startMs: this.now(), depth: this.active.length });
-  }
-
-  end(name?: string): ProfilerMarker {
-    const active = this.active.pop();
-    if (!active) {
-      throw new Error("Cannot end profiler marker because no marker is active");
-    }
-    if (name !== undefined && active.name !== name) {
-      throw new Error(`Profiler marker mismatch: expected ${active.name}, received ${name}`);
-    }
-    const endMs = this.now();
-    const marker: ProfilerMarker = {
-      name: active.name,
-      startMs: active.startMs,
-      endMs,
-      durationMs: endMs - active.startMs,
-      depth: active.depth
-    };
-    this.markers.push(marker);
-    return marker;
-  }
-
-  measure<T>(name: string, fn: () => T): T {
-    this.begin(name);
-    try {
-      return fn();
-    } finally {
-      this.end(name);
-    }
-  }
-
-  snapshot(): ProfilerSnapshot {
-    const markers = [...this.markers];
-    return Object.freeze({
-      markerCount: markers.length,
-      totalDurationMs: markers.reduce((total, marker) => total + marker.durationMs, 0),
-      markers
-    });
-  }
-
-  reset(): void {
-    this.active.length = 0;
-    this.markers.length = 0;
-  }
-}

package/src/RenderStateInspector.ts

@@ -1,45 +0,0 @@
-export type RenderStateValue = string | number | boolean | null;
-export type RenderStateSnapshot = ReadonlyMap<string, RenderStateValue>;
-
-export interface RenderStateDiff {
-  readonly key: string;
-  readonly before: RenderStateValue | undefined;
-  readonly after: RenderStateValue | undefined;
-}
-
-export class RenderStateInspector {
-  capture(source: { captureState(): RenderStateSnapshot }): RenderStateSnapshot {
-    return new Map(source.captureState());
-  }
-
-  diff(before: RenderStateSnapshot, after: RenderStateSnapshot): readonly RenderStateDiff[] {
-    const keys = new Set([...before.keys(), ...after.keys()]);
-    const diffs: RenderStateDiff[] = [];
-    for (const key of keys) {
-      const beforeValue = before.get(key);
-      const afterValue = after.get(key);
-      if (beforeValue !== afterValue) {
-        diffs.push({ key, before: beforeValue, after: afterValue });
-      }
-    }
-    return diffs;
-  }
-
-  assertNoLeak(before: RenderStateSnapshot, after: RenderStateSnapshot, ignoredKeys: readonly string[] = []): void {
-    const ignored = new Set(ignoredKeys);
-    const leaks = this.diff(before, after).filter((diff) => !ignored.has(diff.key));
-    if (leaks.length > 0) {
-      throw new RenderStateLeakError("Render state leak detected", leaks);
-    }
-  }
-}
-
-export class RenderStateLeakError extends Error {
-  constructor(
-    message: string,
-    public readonly leaks: readonly RenderStateDiff[]
-  ) {
-    super(message);
-    this.name = "RenderStateLeakError";
-  }
-}

package/src/ReportExporter.ts

@@ -1,32 +0,0 @@
-export interface DebugReport {
-  readonly generatedAt: string;
-  readonly name: string;
-  readonly data: unknown;
-}
-
-export class ReportExporter {
-  constructor(private readonly now: () => Date = () => new Date()) {}
-
-  create(name: string, data: unknown): DebugReport {
-    const trimmed = name.trim();
-    if (trimmed.length === 0) {
-      throw new Error("Report name is required");
-    }
-    return {
-      generatedAt: this.now().toISOString(),
-      name: trimmed,
-      data
-    };
-  }
-
-  toJson(report: DebugReport): string {
-    return `${JSON.stringify(report, sortKeys, 2)}\n`;
-  }
-}
-
-function sortKeys(_key: string, value: unknown): unknown {
-  if (value === null || Array.isArray(value) || typeof value !== "object") {
-    return value;
-  }
-  return Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)));
-}

package/src/ResourceTracker.ts

@@ -1,59 +0,0 @@
-export interface TrackedResource {
-  readonly id: string;
-  readonly type: string;
-  readonly disposed: boolean;
-}
-
-export interface ResourceLeakReport {
-  readonly total: number;
-  readonly leaked: number;
-  readonly resources: readonly TrackedResource[];
-  readonly leaks: readonly TrackedResource[];
-}
-
-export class ResourceTracker {
-  private readonly resources = new Map<string, TrackedResource>();
-
-  track(id: string, type: string): void {
-    if (this.resources.has(id)) {
-      throw new Error(`Resource already tracked: ${id}`);
-    }
-    this.resources.set(id, { id, type, disposed: false });
-  }
-
-  dispose(id: string): void {
-    const resource = this.resources.get(id);
-    if (!resource) {
-      throw new Error(`Unknown resource: ${id}`);
-    }
-    this.resources.set(id, { ...resource, disposed: true });
-  }
-
-  report(): ResourceLeakReport {
-    const resources = [...this.resources.values()].sort((a, b) => a.id.localeCompare(b.id));
-    const leaks = resources.filter((resource) => !resource.disposed);
-    return {
-      total: resources.length,
-      leaked: leaks.length,
-      resources,
-      leaks
-    };
-  }
-
-  assertNoLeaks(): void {
-    const report = this.report();
-    if (report.leaked > 0) {
-      throw new ResourceLeakError("Resource leaks detected", report);
-    }
-  }
-}
-
-export class ResourceLeakError extends Error {
-  constructor(
-    message: string,
-    public readonly report: ResourceLeakReport
-  ) {
-    super(message);
-    this.name = "ResourceLeakError";
-  }
-}

package/src/SceneHelpers.ts

@@ -1,188 +0,0 @@
-import type { DebugRenderLine } from "./DebugLineCanvasRenderer.js";
-
-export type DebugVec3 = readonly [number, number, number];
-export type DebugColor = readonly [number, number, number, number];
-
-export interface AxesHelperOptions {
-  readonly size?: number;
-  readonly origin?: DebugVec3;
-}
-
-export interface GridHelperOptions {
-  readonly size?: number;
-  readonly divisions?: number;
-  readonly y?: number;
-  readonly color?: DebugColor;
-  readonly centerColor?: DebugColor;
-}
-
-export interface BoundsHelperOptions {
-  readonly min: DebugVec3;
-  readonly max: DebugVec3;
-  readonly color?: DebugColor;
-}
-
-export interface CameraFrustumHelperOptions {
-  readonly nearHalfWidth: number;
-  readonly nearHalfHeight: number;
-  readonly farHalfWidth: number;
-  readonly farHalfHeight: number;
-  readonly nearZ?: number;
-  readonly farZ?: number;
-  readonly color?: DebugColor;
-}
-
-export interface DirectionalLightHelperOptions {
-  readonly direction: DebugVec3;
-  readonly origin?: DebugVec3;
-  readonly length?: number;
-  readonly color?: DebugColor;
-}
-
-export interface SkeletonHelperJoint {
-  readonly id: string;
-  readonly parentId?: string;
-  readonly position: DebugVec3;
-}
-
-const AXIS_X: DebugColor = [1, 0.18, 0.14, 1];
-const AXIS_Y: DebugColor = [0.18, 0.86, 0.28, 1];
-const AXIS_Z: DebugColor = [0.2, 0.48, 1, 1];
-const DEFAULT_GRID: DebugColor = [0.38, 0.46, 0.58, 1];
-const DEFAULT_CENTER: DebugColor = [0.72, 0.78, 0.86, 1];
-const DEFAULT_HELPER: DebugColor = [1, 0.84, 0.28, 1];
-
-export function buildAxesHelper(options: AxesHelperOptions = {}): readonly DebugRenderLine[] {
-  const size = positive(options.size ?? 1, "Axes helper size");
-  const origin = options.origin ?? [0, 0, 0];
-  return [
-    { from: origin, to: [origin[0] + size, origin[1], origin[2]], color: AXIS_X },
-    { from: origin, to: [origin[0], origin[1] + size, origin[2]], color: AXIS_Y },
-    { from: origin, to: [origin[0], origin[1], origin[2] + size], color: AXIS_Z }
-  ];
-}
-
-export function buildGridHelper(options: GridHelperOptions = {}): readonly DebugRenderLine[] {
-  const size = positive(options.size ?? 10, "Grid helper size");
-  const divisions = integerAtLeast(options.divisions ?? 10, 1, "Grid helper divisions");
-  const y = finite(options.y ?? 0, "Grid helper y");
-  const half = size / 2;
-  const step = size / divisions;
-  const lines: DebugRenderLine[] = [];
-  for (let index = 0; index <= divisions; index += 1) {
-    const offset = -half + index * step;
-    const isCenter = Math.abs(offset) < 1e-8;
-    const color = isCenter ? options.centerColor ?? DEFAULT_CENTER : options.color ?? DEFAULT_GRID;
-    lines.push({ from: [-half, y, offset], to: [half, y, offset], color });
-    lines.push({ from: [offset, y, -half], to: [offset, y, half], color });
-  }
-  return lines;
-}
-
-export function buildBoundsHelper(options: BoundsHelperOptions): readonly DebugRenderLine[] {
-  validateVec3(options.min, "Bounds helper min");
-  validateVec3(options.max, "Bounds helper max");
-  const [minX, minY, minZ] = options.min;
-  const [maxX, maxY, maxZ] = options.max;
-  if (maxX < minX || maxY < minY || maxZ < minZ) {
-    throw new RangeError("Bounds helper max must be greater than or equal to min.");
-  }
-  const color = options.color ?? DEFAULT_HELPER;
-  const p: readonly DebugVec3[] = [
-    [minX, minY, minZ], [maxX, minY, minZ], [maxX, maxY, minZ], [minX, maxY, minZ],
-    [minX, minY, maxZ], [maxX, minY, maxZ], [maxX, maxY, maxZ], [minX, maxY, maxZ]
-  ];
-  return edges([
-    [0, 1], [1, 2], [2, 3], [3, 0],
-    [4, 5], [5, 6], [6, 7], [7, 4],
-    [0, 4], [1, 5], [2, 6], [3, 7]
-  ], p, color);
-}
-
-export function buildCameraFrustumHelper(options: CameraFrustumHelperOptions): readonly DebugRenderLine[] {
-  const nearHalfWidth = positive(options.nearHalfWidth, "Camera frustum nearHalfWidth");
-  const nearHalfHeight = positive(options.nearHalfHeight, "Camera frustum nearHalfHeight");
-  const farHalfWidth = positive(options.farHalfWidth, "Camera frustum farHalfWidth");
-  const farHalfHeight = positive(options.farHalfHeight, "Camera frustum farHalfHeight");
-  const nearZ = finite(options.nearZ ?? -0.1, "Camera frustum nearZ");
-  const farZ = finite(options.farZ ?? -1, "Camera frustum farZ");
-  if (Math.abs(nearZ - farZ) < 1e-8) {
-    throw new RangeError("Camera frustum nearZ and farZ must be distinct.");
-  }
-  const p: readonly DebugVec3[] = [
-    [-nearHalfWidth, -nearHalfHeight, nearZ],
-    [nearHalfWidth, -nearHalfHeight, nearZ],
-    [nearHalfWidth, nearHalfHeight, nearZ],
-    [-nearHalfWidth, nearHalfHeight, nearZ],
-    [-farHalfWidth, -farHalfHeight, farZ],
-    [farHalfWidth, -farHalfHeight, farZ],
-    [farHalfWidth, farHalfHeight, farZ],
-    [-farHalfWidth, farHalfHeight, farZ]
-  ];
-  return edges([
-    [0, 1], [1, 2], [2, 3], [3, 0],
-    [4, 5], [5, 6], [6, 7], [7, 4],
-    [0, 4], [1, 5], [2, 6], [3, 7]
-  ], p, options.color ?? DEFAULT_HELPER);
-}
-
-export function buildDirectionalLightHelper(options: DirectionalLightHelperOptions): readonly DebugRenderLine[] {
-  const origin = options.origin ?? [0, 0, 0];
-  const length = positive(options.length ?? 1, "Directional light helper length");
-  const direction = normalize(options.direction, "Directional light helper direction");
-  const to: DebugVec3 = [
-    origin[0] + direction[0] * length,
-    origin[1] + direction[1] * length,
-    origin[2] + direction[2] * length
-  ];
-  return [{ from: origin, to, color: options.color ?? DEFAULT_HELPER }];
-}
-
-export function buildSkeletonHelper(joints: readonly SkeletonHelperJoint[], color: DebugColor = DEFAULT_HELPER): readonly DebugRenderLine[] {
-  const byId = new Map<string, SkeletonHelperJoint>();
-  for (const joint of joints) {
-    if (!joint.id) throw new Error("Skeleton helper joints require stable ids.");
-    validateVec3(joint.position, `Skeleton helper joint ${joint.id}`);
-    byId.set(joint.id, joint);
-  }
-  const lines: DebugRenderLine[] = [];
-  for (const joint of joints) {
-    if (!joint.parentId) continue;
-    const parent = byId.get(joint.parentId);
-    if (!parent) continue;
-    lines.push({ from: parent.position, to: joint.position, color });
-  }
-  return lines;
-}
-
-function edges(indices: readonly (readonly [number, number])[], points: readonly DebugVec3[], color: DebugColor): readonly DebugRenderLine[] {
-  return indices.map(([from, to]) => ({ from: points[from]!, to: points[to]!, color }));
-}
-
-function positive(value: number, label: string): number {
-  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${label} must be finite and positive.`);
-  return value;
-}
-
-function finite(value: number, label: string): number {
-  if (!Number.isFinite(value)) throw new RangeError(`${label} must be finite.`);
-  return value;
-}
-
-function integerAtLeast(value: number, minimum: number, label: string): number {
-  if (!Number.isInteger(value) || value < minimum) throw new RangeError(`${label} must be an integer >= ${minimum}.`);
-  return value;
-}
-
-function validateVec3(value: readonly number[], label: string): void {
-  if (value.length !== 3 || value.some((component) => !Number.isFinite(component))) {
-    throw new RangeError(`${label} must contain three finite values.`);
-  }
-}
-
-function normalize(value: DebugVec3, label: string): DebugVec3 {
-  validateVec3(value, label);
-  const length = Math.hypot(value[0], value[1], value[2]);
-  if (length <= 1e-8) throw new RangeError(`${label} must be non-zero.`);
-  return [value[0] / length, value[1] / length, value[2] / length];
-}

package/src/ShaderDiagnostics.ts

@@ -1,64 +0,0 @@
-import { type RenderShaderProgram, type ShaderSources } from "@aura3d/rendering";
-
-export interface ShaderDiagnosticReport {
-  readonly label: string;
-  readonly marker: string;
-  readonly markerPresentInVertex: boolean;
-  readonly markerPresentInFragment: boolean;
-  readonly attributes: readonly string[];
-  readonly uniforms: readonly string[];
-  readonly compileLog: string | null;
-}
-
-export class ShaderDiagnostics {
-  inspectSources(sources: ShaderSources, compileLog: string | null = null): ShaderDiagnosticReport {
-    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: RenderShaderProgram, compileLog: string | null = null): ShaderDiagnosticReport {
-    return {
-      label: program.label,
-      marker: program.marker,
-      markerPresentInVertex: true,
-      markerPresentInFragment: true,
-      attributes: [...program.reflection.attributes.keys()],
-      uniforms: [...program.reflection.uniforms],
-      compileLog
-    };
-  }
-
-  assertMarker(report: ShaderDiagnosticReport): void {
-    if (!report.markerPresentInVertex || !report.markerPresentInFragment) {
-      throw new ShaderDiagnosticError("Shader marker mismatch", report);
-    }
-  }
-}
-
-export class ShaderDiagnosticError extends Error {
-  constructor(
-    message: string,
-    public readonly report: ShaderDiagnosticReport
-  ) {
-    super(message);
-    this.name = "ShaderDiagnosticError";
-  }
-}
-
-function extractNames(pattern: RegExp, source: string): readonly string[] {
-  const names = new Set<string>();
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(source)) !== null) {
-    if (match[1]) {
-      names.add(match[1]);
-    }
-  }
-  return [...names];
-}

package/src/index.ts

@@ -1,46 +0,0 @@
-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";

package/tsconfig.json

@@ -1,32 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "lib": ["ES2022", "DOM"],
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "useUnknownInCatchVariables": true,
-    "exactOptionalPropertyTypes": false,
-    "isolatedModules": true,
-    "declaration": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "paths": {
-      "@aura3d/rendering": ["../rendering/src/index.ts"],
-      "@aura3d/scene": ["../scene/src/index.ts"],
-      "@aura3d/math": ["../math/src/index.ts"],
-      "@aura3d/core": ["../core/src/index.ts"]
-    }
-  },
-  "include": [
-    "src/DrawCallTracker.ts",
-    "src/RenderStateInspector.ts",
-    "src/ShaderDiagnostics.ts",
-    "src/MaterialDiagnostics.ts",
-    "src/index.ts"
-  ]
-}