@aura3d/rendering 1.0.6

package/src/materials/AlphaSorting.ts

@@ -0,0 +1,30 @@
+export interface ExternalParityAlphaSortItem {
+  readonly id: string;
+  readonly depth: number;
+  readonly alphaMode: "opaque" | "mask" | "blend";
+  readonly renderOrder?: number;
+}
+
+export function sortExternalParityAlphaItems(items: readonly ExternalParityAlphaSortItem[]): readonly ExternalParityAlphaSortItem[] {
+  return [...items].sort((a, b) => {
+    const orderA = a.renderOrder ?? 0;
+    const orderB = b.renderOrder ?? 0;
+    if (orderA !== orderB) return orderA - orderB;
+    const groupA = alphaGroup(a.alphaMode);
+    const groupB = alphaGroup(b.alphaMode);
+    if (groupA !== groupB) return groupA - groupB;
+    if (a.alphaMode === "blend" || b.alphaMode === "blend") return b.depth - a.depth;
+    return a.depth - b.depth;
+  });
+}
+
+function alphaGroup(mode: ExternalParityAlphaSortItem["alphaMode"]): number {
+  switch (mode) {
+    case "opaque":
+      return 0;
+    case "mask":
+      return 1;
+    case "blend":
+      return 2;
+  }
+}

package/src/materials/MaterialExtensions.ts

@@ -0,0 +1,42 @@
+export type ExternalParityMaterialExtension =
+  | "clearcoat"
+  | "sheen"
+  | "specular"
+  | "transmission"
+  | "volume"
+  | "ior"
+  | "anisotropy"
+  | "iridescence"
+  | "emissive-strength"
+  | "texture-transform"
+  | "multi-uv";
+
+export interface ExternalParityMaterialExtensionState {
+  readonly extension: ExternalParityMaterialExtension;
+  readonly support: "supported" | "bounded" | "unsupported";
+  readonly diagnostic: string;
+}
+
+export const EXTERNAL_PARITY_MATERIAL_EXTENSION_SUPPORT: readonly ExternalParityMaterialExtensionState[] = [
+  { extension: "clearcoat", support: "bounded", diagnostic: "Clearcoat factor and roughness are modeled; layered multiple scattering remains bounded." },
+  { extension: "sheen", support: "bounded", diagnostic: "Sheen color/roughness intent is modeled for fabric review; exact renderer parity requires visual comparison." },
+  { extension: "specular", support: "bounded", diagnostic: "Specular factor/color are modeled for material diagnostics and matrix proof." },
+  { extension: "transmission", support: "bounded", diagnostic: "Transmission is approximated by the bounded transmission pass; refraction parity is not claimed." },
+  { extension: "volume", support: "bounded", diagnostic: "Volume thickness/attenuation are tracked for diagnostics; full volumetric caustics are not claimed." },
+  { extension: "ior", support: "bounded", diagnostic: "IOR is tracked and used by bounded Fresnel/transmission response." },
+  { extension: "anisotropy", support: "bounded", diagnostic: "Anisotropy intent is tracked for brushed material review; tangent-space parity requires visual evidence." },
+  { extension: "iridescence", support: "bounded", diagnostic: "Iridescence factors are tracked for diagnostics; spectral accuracy is not claimed." },
+  { extension: "emissive-strength", support: "supported", diagnostic: "Emissive strength is supported through HDR/tone-mapped material proof." },
+  { extension: "texture-transform", support: "supported", diagnostic: "Texture transforms are tracked and validated for material slots." },
+  { extension: "multi-uv", support: "bounded", diagnostic: "Multiple UV intent is tracked; fallback diagnostics are required when a shader path cannot bind the requested UV set." }
+];
+
+export function getExternalParityMaterialExtensionState(extension: ExternalParityMaterialExtension): ExternalParityMaterialExtensionState {
+  return EXTERNAL_PARITY_MATERIAL_EXTENSION_SUPPORT.find((entry) => entry.extension === extension)!;
+}
+
+export function createExternalParityMaterialExtensionDiagnostics(
+  requested: readonly ExternalParityMaterialExtension[]
+): readonly ExternalParityMaterialExtensionState[] {
+  return requested.map(getExternalParityMaterialExtensionState);
+}

package/src/materials/PhysicalMaterial.ts

@@ -0,0 +1,133 @@
+import {
+  createExternalParityMaterialExtensionDiagnostics,
+  type ExternalParityMaterialExtension,
+  type ExternalParityMaterialExtensionState
+} from "./MaterialExtensions";
+
+export type ExternalParityMaterialKind =
+  | "chrome"
+  | "brushed-metal"
+  | "gold"
+  | "painted-metal"
+  | "matte-plastic"
+  | "glossy-plastic"
+  | "rubber"
+  | "glass-transmission"
+  | "clearcoat-car-paint"
+  | "fabric-sheen"
+  | "emissive"
+  | "textured-ceramic-stone";
+
+export interface ExternalParityPhysicalMaterialDescriptor {
+  readonly id: ExternalParityMaterialKind;
+  readonly label: string;
+  readonly baseColor: readonly [number, number, number, number];
+  readonly metallic: number;
+  readonly roughness: number;
+  readonly emissive?: readonly [number, number, number];
+  readonly emissiveStrength?: number;
+  readonly normalScale?: number;
+  readonly occlusionStrength?: number;
+  readonly alphaMode?: "opaque" | "mask" | "blend";
+  readonly alphaCutoff?: number;
+  readonly doubleSided?: boolean;
+  readonly extensions: readonly ExternalParityMaterialExtension[];
+  readonly visualGoal: string;
+}
+
+export interface ExternalParityPhysicalMaterialAnalysis {
+  readonly descriptor: ExternalParityPhysicalMaterialDescriptor;
+  readonly extensionDiagnostics: readonly ExternalParityMaterialExtensionState[];
+  readonly reflectanceClass: "mirror-metal" | "rough-metal" | "dielectric" | "transparent" | "emissive";
+  readonly requiresIbl: boolean;
+  readonly requiresTransmissionPass: boolean;
+  readonly requiresAlphaSorting: boolean;
+  readonly warnings: readonly string[];
+}
+
+export class ExternalParityPhysicalMaterial {
+  public readonly descriptor: ExternalParityPhysicalMaterialDescriptor;
+
+  constructor(descriptor: ExternalParityPhysicalMaterialDescriptor) {
+    validateDescriptor(descriptor);
+    this.descriptor = descriptor;
+  }
+
+  analyze(): ExternalParityPhysicalMaterialAnalysis {
+    const extensionDiagnostics = createExternalParityMaterialExtensionDiagnostics(this.descriptor.extensions);
+    const reflectanceClass = classifyMaterial(this.descriptor);
+    const requiresTransmissionPass = this.descriptor.extensions.includes("transmission") || this.descriptor.id === "glass-transmission";
+    const requiresAlphaSorting = this.descriptor.alphaMode === "blend" || requiresTransmissionPass;
+    const warnings = [
+      ...extensionDiagnostics.filter((entry) => entry.support !== "supported").map((entry) => `${entry.extension}: ${entry.diagnostic}`),
+      ...(this.descriptor.metallic > 0.8 && this.descriptor.roughness < 0.2 ? [] : []),
+      ...(requiresTransmissionPass ? ["Transmission is bounded and must be compared against Three.js before release claims."] : [])
+    ];
+    return {
+      descriptor: this.descriptor,
+      extensionDiagnostics,
+      reflectanceClass,
+      requiresIbl: this.descriptor.metallic > 0 || this.descriptor.extensions.length > 0,
+      requiresTransmissionPass,
+      requiresAlphaSorting,
+      warnings
+    };
+  }
+}
+
+export const EXTERNAL_PARITY_PHYSICAL_MATERIAL_MATRIX: readonly ExternalParityPhysicalMaterialDescriptor[] = [
+  material("chrome", "Chrome", [0.92, 0.94, 0.95, 1], 1, 0.04, [], "Mirror-like metal must reflect environment directionally."),
+  material("brushed-metal", "Brushed Metal", [0.78, 0.76, 0.72, 1], 1, 0.32, ["anisotropy"], "Brushed metal must show rough directional response."),
+  material("gold", "Gold", [1, 0.72, 0.28, 1], 1, 0.18, [], "Gold must read as tinted metal, not yellow plastic."),
+  material("painted-metal", "Painted Metal", [0.8, 0.04, 0.03, 1], 0.65, 0.22, ["clearcoat"], "Painted metal must show base color plus coated highlight."),
+  material("matte-plastic", "Matte Plastic", [0.08, 0.1, 0.12, 1], 0, 0.82, [], "Matte plastic must have broad diffuse response."),
+  material("glossy-plastic", "Glossy Plastic", [0.02, 0.28, 0.9, 1], 0, 0.16, ["specular"], "Glossy plastic must show tight dielectric highlights."),
+  material("rubber", "Rubber", [0.01, 0.012, 0.014, 1], 0, 0.92, [], "Rubber must stay dark and rough without metal response."),
+  material("glass-transmission", "Glass / Transmission", [0.82, 0.96, 1, 0.34], 0, 0.02, ["transmission", "volume", "ior"], "Glass must be transparent/transmissive with honest limitations."),
+  material("clearcoat-car-paint", "Clearcoat Car Paint", [0.1, 0.02, 0.018, 1], 0.35, 0.18, ["clearcoat", "specular"], "Car paint must show layered highlight response."),
+  material("fabric-sheen", "Fabric / Sheen", [0.55, 0.28, 0.9, 1], 0, 0.72, ["sheen"], "Fabric must show soft grazing-angle sheen."),
+  material("emissive", "Emissive", [0.04, 0.04, 0.04, 1], 0, 0.45, ["emissive-strength"], "Emissive material must pass through HDR tone mapping and bloom evidence.", [1, 0.45, 0.12], 4),
+  material("textured-ceramic-stone", "Textured Ceramic / Stone", [0.62, 0.58, 0.52, 1], 0, 0.58, ["texture-transform", "multi-uv"], "Stone/ceramic must show texture, normal, and roughness detail.")
+];
+
+export function createExternalParityPhysicalMaterial(kind: ExternalParityMaterialKind): ExternalParityPhysicalMaterial {
+  const descriptor = EXTERNAL_PARITY_PHYSICAL_MATERIAL_MATRIX.find((entry) => entry.id === kind);
+  if (!descriptor) throw new Error(`Unknown ExternalParity material kind: ${kind}`);
+  return new ExternalParityPhysicalMaterial(descriptor);
+}
+
+export function analyzeExternalParityMaterialMatrix(): readonly ExternalParityPhysicalMaterialAnalysis[] {
+  return EXTERNAL_PARITY_PHYSICAL_MATERIAL_MATRIX.map((descriptor) => new ExternalParityPhysicalMaterial(descriptor).analyze());
+}
+
+function material(
+  id: ExternalParityMaterialKind,
+  label: string,
+  baseColor: readonly [number, number, number, number],
+  metallic: number,
+  roughness: number,
+  extensions: readonly ExternalParityMaterialExtension[],
+  visualGoal: string,
+  emissive?: readonly [number, number, number],
+  emissiveStrength?: number
+): ExternalParityPhysicalMaterialDescriptor {
+  return { id, label, baseColor, metallic, roughness, extensions, visualGoal, ...(emissive ? { emissive } : {}), ...(emissiveStrength ? { emissiveStrength } : {}), ...(id === "glass-transmission" ? { alphaMode: "blend" as const, doubleSided: true } : {}) };
+}
+
+function validateDescriptor(descriptor: ExternalParityPhysicalMaterialDescriptor): void {
+  if (!descriptor.id || !descriptor.label) throw new Error("ExternalParity physical material requires id and label.");
+  if (descriptor.baseColor.length !== 4 || descriptor.baseColor.some((value) => !Number.isFinite(value) || value < 0 || value > 1)) {
+    throw new Error(`ExternalParity physical material ${descriptor.id} has invalid baseColor.`);
+  }
+  if (!Number.isFinite(descriptor.metallic) || descriptor.metallic < 0 || descriptor.metallic > 1) throw new Error(`ExternalParity physical material ${descriptor.id} has invalid metallic.`);
+  if (!Number.isFinite(descriptor.roughness) || descriptor.roughness < 0 || descriptor.roughness > 1) throw new Error(`ExternalParity physical material ${descriptor.id} has invalid roughness.`);
+}
+
+function classifyMaterial(descriptor: ExternalParityPhysicalMaterialDescriptor): ExternalParityPhysicalMaterialAnalysis["reflectanceClass"] {
+  if ((descriptor.emissiveStrength ?? 0) > 0) return "emissive";
+  if (descriptor.extensions.includes("transmission")) return "transparent";
+  if (descriptor.metallic > 0.8 && descriptor.roughness < 0.18) return "mirror-metal";
+  if (descriptor.extensions.includes("clearcoat") && descriptor.metallic >= 0.3) return "rough-metal";
+  if (descriptor.metallic > 0.5) return "rough-metal";
+  return "dielectric";
+}

package/src/materials/TransmissionPass.ts

@@ -0,0 +1,51 @@
+import { createExternalParityToneMappingPolicy, toneMapExternalParityHdrPixels } from "../ToneMapping";
+
+export interface ExternalParityTransmissionSample {
+  readonly baseColor: readonly [number, number, number];
+  readonly thickness: number;
+  readonly attenuationColor: readonly [number, number, number];
+  readonly attenuationDistance: number;
+  readonly ior: number;
+  readonly intensity: number;
+}
+
+export interface ExternalParityTransmissionResult {
+  readonly transmittedColor: readonly [number, number, number];
+  readonly displayColor: readonly [number, number, number];
+  readonly bounded: true;
+  readonly diagnostic: string;
+}
+
+export function evaluateExternalParityTransmission(sample: ExternalParityTransmissionSample): ExternalParityTransmissionResult {
+  validateSample(sample);
+  const attenuation = Math.exp(-sample.thickness / Math.max(0.0001, sample.attenuationDistance));
+  const fresnelScale = Math.max(0, Math.min(1, (sample.ior - 1) / (sample.ior + 1)));
+  const transmitted: [number, number, number] = [
+    sample.baseColor[0] * sample.attenuationColor[0] * attenuation * sample.intensity * (1 - fresnelScale),
+    sample.baseColor[1] * sample.attenuationColor[1] * attenuation * sample.intensity * (1 - fresnelScale),
+    sample.baseColor[2] * sample.attenuationColor[2] * attenuation * sample.intensity * (1 - fresnelScale)
+  ];
+  const toneMapped = toneMapExternalParityHdrPixels(
+    new Float32Array([transmitted[0], transmitted[1], transmitted[2], 1]),
+    1,
+    1,
+    createExternalParityToneMappingPolicy("material-review", { operator: "reinhard", exposure: 1, gamma: 1, outputColorSpace: "srgb" })
+  );
+  return {
+    transmittedColor: transmitted.map(round) as [number, number, number],
+    displayColor: [toneMapped.pixels[0]!, toneMapped.pixels[1]!, toneMapped.pixels[2]!],
+    bounded: true,
+    diagnostic: "Bounded transmission approximation for material review; full refraction/caustics parity is not claimed."
+  };
+}
+
+function validateSample(sample: ExternalParityTransmissionSample): void {
+  if (sample.baseColor.length !== 3 || sample.attenuationColor.length !== 3) throw new Error("Transmission colors must be RGB tuples.");
+  for (const value of [...sample.baseColor, ...sample.attenuationColor, sample.thickness, sample.attenuationDistance, sample.ior, sample.intensity]) {
+    if (!Number.isFinite(value) || value < 0) throw new Error("Transmission sample values must be finite and non-negative.");
+  }
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(6));
+}

package/src/performance/BVH.ts

@@ -0,0 +1,18 @@
+export {
+  buildStaticBoundsBvh,
+  queryStaticBoundsBvh,
+  raycastStaticBoundsBvh,
+  updateStaticBoundsBvh
+} from "../SceneOptimization";
+export type {
+  StaticBoundsBvh,
+  StaticBoundsBvhBuildDiagnostics,
+  StaticBoundsBvhNode,
+  StaticBoundsBvhQueryOptions,
+  StaticBoundsBvhQueryResult,
+  StaticBoundsBvhRaycastHit,
+  StaticBoundsBvhRaycastResult,
+  StaticBoundsBvhTraversalDiagnostics,
+  StaticSpatialBounds,
+  StaticSpatialItem
+} from "../SceneOptimization";

package/src/performance/Batcher.ts

@@ -0,0 +1,2 @@
+export { batchStaticRenderItems } from "../SceneOptimization";
+export type { StaticBatchInput, StaticBatchOptions, StaticBatchResult } from "../SceneOptimization";

package/src/performance/FrustumCuller.ts

@@ -0,0 +1,9 @@
+import { Box3, Vector3 } from "@aura3d/math";
+import type { StaticBoundsIntersector, StaticSpatialItem } from "../SceneOptimization";
+
+export function cullStaticItems<T>(items: readonly StaticSpatialItem<T>[], frustum: StaticBoundsIntersector): readonly StaticSpatialItem<T>[] {
+  return items.filter((item) => frustum.intersectsBox(new Box3(
+    new Vector3(item.bounds.min[0], item.bounds.min[1], item.bounds.min[2]),
+    new Vector3(item.bounds.max[0], item.bounds.max[1], item.bounds.max[2])
+  )));
+}

package/src/performance/LOD.ts

@@ -0,0 +1,20 @@
+export interface PerformanceLodLevel {
+  readonly id: string;
+  readonly maxDistance: number;
+  readonly triangleBudget: number;
+}
+
+export function selectPerformanceLodLevel(levels: readonly PerformanceLodLevel[], distance: number): PerformanceLodLevel {
+  if (levels.length === 0) throw new Error("selectPerformanceLodLevel requires at least one LOD level.");
+  const sorted = [...levels].sort((a, b) => a.maxDistance - b.maxDistance);
+  return sorted.find((level) => distance <= level.maxDistance) ?? sorted[sorted.length - 1]!;
+}
+
+export function createDefaultPerformanceLodLevels(baseTriangles: number): readonly PerformanceLodLevel[] {
+  const triangles = Math.max(1, Math.floor(baseTriangles));
+  return [
+    { id: "lod0", maxDistance: 8, triangleBudget: triangles },
+    { id: "lod1", maxDistance: 20, triangleBudget: Math.max(1, Math.floor(triangles * 0.45)) },
+    { id: "lod2", maxDistance: Number.POSITIVE_INFINITY, triangleBudget: Math.max(1, Math.floor(triangles * 0.16)) }
+  ];
+}

package/src/performance/Octree.ts

@@ -0,0 +1,10 @@
+import type { StaticSpatialBounds, StaticSpatialItem } from "../SceneOptimization";
+
+export interface OctreeNode<T = unknown> {
+  readonly bounds: StaticSpatialBounds;
+  readonly items: readonly StaticSpatialItem<T>[];
+}
+
+export function createFlatOctree<T>(bounds: StaticSpatialBounds, items: readonly StaticSpatialItem<T>[]): OctreeNode<T> {
+  return { bounds, items };
+}

package/src/performance/RenderItemSorting.ts

@@ -0,0 +1,167 @@
+export type RenderQueueBucket = "opaque" | "mask" | "transparent";
+
+export interface RenderQueueSortItem<T = unknown> {
+  readonly item: T;
+  readonly bucket: RenderQueueBucket;
+  readonly depth: number;
+  readonly pipelineKey?: string;
+  readonly batchKey?: string;
+  readonly instanceCount?: number;
+  readonly renderOrder?: number;
+}
+
+export interface RenderQueueSortOptions {
+  readonly transparentBackToFront?: boolean;
+  readonly opaqueFrontToBack?: boolean;
+  readonly groupOpaqueByPipeline?: boolean;
+}
+
+export interface RenderQueuePlan<T = unknown> {
+  readonly items: readonly T[];
+  readonly diagnostics: RenderQueueSortDiagnostics;
+}
+
+export interface RenderQueueSortDiagnostics {
+  readonly total: number;
+  readonly objectCount: number;
+  readonly estimatedDrawCalls: number;
+  readonly totalInstances: number;
+  readonly batchableGroups: number;
+  readonly largestBatch: number;
+  readonly materialSwitches: number;
+  readonly opaqueCount: number;
+  readonly maskedCount: number;
+  readonly transparentCount: number;
+  readonly pipelineTransitions: number;
+  readonly opaqueFrontToBack: boolean;
+  readonly transparentBackToFront: boolean;
+}
+
+export function sortRenderQueueItems<T>(
+  items: readonly RenderQueueSortItem<T>[],
+  options: RenderQueueSortOptions = {}
+): RenderQueuePlan<T> {
+  const opaqueFrontToBack = options.opaqueFrontToBack ?? true;
+  const transparentBackToFront = options.transparentBackToFront ?? true;
+  const groupOpaqueByPipeline = options.groupOpaqueByPipeline ?? false;
+  const decorated = items.map((entry, index) => {
+    validateRenderQueueItem(entry, index);
+    return { ...entry, index };
+  });
+
+  decorated.sort((left, right) => {
+    const orderDelta = (left.renderOrder ?? 0) - (right.renderOrder ?? 0);
+    if (orderDelta !== 0) return orderDelta;
+
+    const bucketDelta = bucketRank(left.bucket) - bucketRank(right.bucket);
+    if (bucketDelta !== 0) return bucketDelta;
+
+    if (left.bucket === "transparent" || right.bucket === "transparent") {
+      if (transparentBackToFront) {
+        const depthDelta = right.depth - left.depth;
+        if (Math.abs(depthDelta) > 1e-6) return depthDelta;
+      }
+      return left.index - right.index;
+    }
+
+    if (groupOpaqueByPipeline) {
+      const pipelineDelta = pipelineKey(left).localeCompare(pipelineKey(right));
+      if (pipelineDelta !== 0) return pipelineDelta;
+    }
+
+    if (opaqueFrontToBack) {
+      const depthDelta = left.depth - right.depth;
+      if (Math.abs(depthDelta) > 1e-6) return depthDelta;
+    }
+
+    if (!groupOpaqueByPipeline) {
+      const pipelineDelta = pipelineKey(left).localeCompare(pipelineKey(right));
+      if (pipelineDelta !== 0 && Math.abs(left.depth - right.depth) <= 1e-6) return pipelineDelta;
+    }
+
+    return left.index - right.index;
+  });
+
+  return {
+    items: decorated.map((entry) => entry.item),
+    diagnostics: buildDiagnostics(decorated, opaqueFrontToBack, transparentBackToFront)
+  };
+}
+
+export interface SortableRenderItem {
+  readonly id: string;
+  readonly materialBucket: RenderQueueBucket;
+  readonly pipelineKey: string;
+  readonly depth: number;
+}
+
+export function sortRenderItems(items: readonly SortableRenderItem[]): SortableRenderItem[] {
+  return [...sortRenderQueueItems(items.map((item) => ({
+    item,
+    bucket: item.materialBucket,
+    pipelineKey: item.pipelineKey,
+    depth: item.depth
+  })), { groupOpaqueByPipeline: true }).items];
+}
+
+function bucketRank(bucket: RenderQueueBucket): number {
+  if (bucket === "opaque") return 0;
+  if (bucket === "mask") return 1;
+  return 2;
+}
+
+function validateRenderQueueItem(item: RenderQueueSortItem, index: number): void {
+  if (!Number.isFinite(item.depth)) {
+    throw new RangeError(`Render queue item ${index} depth must be finite.`);
+  }
+  if (item.renderOrder !== undefined && !Number.isFinite(item.renderOrder)) {
+    throw new RangeError(`Render queue item ${index} renderOrder must be finite.`);
+  }
+  if (item.instanceCount !== undefined && (!Number.isInteger(item.instanceCount) || item.instanceCount <= 0)) {
+    throw new RangeError(`Render queue item ${index} instanceCount must be a positive integer.`);
+  }
+}
+
+function pipelineKey(item: RenderQueueSortItem): string {
+  return item.pipelineKey ?? "";
+}
+
+function buildDiagnostics(
+  items: readonly (RenderQueueSortItem & { readonly index: number })[],
+  opaqueFrontToBack: boolean,
+  transparentBackToFront: boolean
+): RenderQueueSortDiagnostics {
+  let pipelineTransitions = 0;
+  let previousPipeline: string | undefined;
+  const batchGroups = new Map<string, number>();
+  let totalInstances = 0;
+  for (const item of items) {
+    const key = pipelineKey(item);
+    if (previousPipeline !== undefined && previousPipeline !== key) pipelineTransitions += 1;
+    previousPipeline = key;
+    const instances = item.instanceCount ?? 1;
+    totalInstances += instances;
+    const batchKey = item.batchKey ?? key;
+    if (batchKey) {
+      batchGroups.set(batchKey, (batchGroups.get(batchKey) ?? 0) + 1);
+    }
+  }
+  const batchSizes = [...batchGroups.values()];
+  const batchableGroups = batchSizes.filter((size) => size > 1).length;
+  const largestBatch = batchSizes.length > 0 ? Math.max(...batchSizes) : 0;
+  return {
+    total: items.length,
+    objectCount: items.length,
+    estimatedDrawCalls: items.length,
+    totalInstances,
+    batchableGroups,
+    largestBatch,
+    materialSwitches: pipelineTransitions,
+    opaqueCount: items.filter((item) => item.bucket === "opaque").length,
+    maskedCount: items.filter((item) => item.bucket === "mask").length,
+    transparentCount: items.filter((item) => item.bucket === "transparent").length,
+    pipelineTransitions,
+    opaqueFrontToBack,
+    transparentBackToFront
+  };
+}

package/src/performance/RendererStats.ts

@@ -0,0 +1,43 @@
+export interface RendererStatsInput {
+  readonly objectCount: number;
+  readonly visibleObjectCount: number;
+  readonly drawCalls: number;
+  readonly triangles?: number;
+  readonly cpuFrameMs?: number;
+  readonly gpuFrameMs?: number;
+  readonly textureMemoryBytes?: number;
+  readonly warnings?: readonly string[];
+}
+
+export interface RendererStats {
+  readonly objectCount: number;
+  readonly visibleObjectCount: number;
+  readonly culledObjectCount: number;
+  readonly drawCalls: number;
+  readonly triangles: number;
+  readonly cpuFrameMs: number;
+  readonly gpuFrameMs?: number;
+  readonly textureMemoryBytes: number;
+  readonly warnings: readonly string[];
+}
+
+export function createRendererStats(input: RendererStatsInput): RendererStats {
+  const objectCount = Math.max(0, Math.floor(input.objectCount));
+  const visibleObjectCount = Math.max(0, Math.min(objectCount, Math.floor(input.visibleObjectCount)));
+  const drawCalls = Math.max(0, Math.floor(input.drawCalls));
+  const textureMemoryBytes = Math.max(0, Math.floor(input.textureMemoryBytes ?? 0));
+  const warnings = [...(input.warnings ?? [])];
+  if (drawCalls > 500) warnings.push("draw-call-count-high");
+  if (textureMemoryBytes > 512 * 1024 * 1024) warnings.push("texture-memory-budget-high");
+  return {
+    objectCount,
+    visibleObjectCount,
+    culledObjectCount: objectCount - visibleObjectCount,
+    drawCalls,
+    triangles: Math.max(0, Math.floor(input.triangles ?? 0)),
+    cpuFrameMs: Math.max(0, input.cpuFrameMs ?? 0),
+    ...(input.gpuFrameMs === undefined ? {} : { gpuFrameMs: Math.max(0, input.gpuFrameMs) }),
+    textureMemoryBytes,
+    warnings
+  };
+}

package/src/performance/ResourceBudget.ts

@@ -0,0 +1,44 @@
+export interface ResourceBudget {
+  readonly textureBudgetBytes: number;
+  readonly geometryBudgetBytes: number;
+  readonly drawCallBudget: number;
+}
+
+export interface ResourceBudgetUsage {
+  readonly textureBytes: number;
+  readonly geometryBytes: number;
+  readonly drawCalls: number;
+}
+
+export interface ResourceBudgetReport {
+  readonly withinBudget: boolean;
+  readonly texturePercent: number;
+  readonly geometryPercent: number;
+  readonly drawCallPercent: number;
+  readonly warnings: readonly string[];
+}
+
+export function evaluateResourceBudget(
+  budget: ResourceBudget,
+  usage: ResourceBudgetUsage
+): ResourceBudgetReport {
+  const texturePercent = ratio(usage.textureBytes, budget.textureBudgetBytes);
+  const geometryPercent = ratio(usage.geometryBytes, budget.geometryBudgetBytes);
+  const drawCallPercent = ratio(usage.drawCalls, budget.drawCallBudget);
+  const warnings = [
+    ...(texturePercent > 1 ? ["texture-budget-exceeded"] : texturePercent > 0.8 ? ["texture-budget-near-limit"] : []),
+    ...(geometryPercent > 1 ? ["geometry-budget-exceeded"] : geometryPercent > 0.8 ? ["geometry-budget-near-limit"] : []),
+    ...(drawCallPercent > 1 ? ["draw-call-budget-exceeded"] : drawCallPercent > 0.8 ? ["draw-call-budget-near-limit"] : [])
+  ];
+  return {
+    withinBudget: warnings.every((warning) => !warning.endsWith("exceeded")),
+    texturePercent,
+    geometryPercent,
+    drawCallPercent,
+    warnings
+  };
+}
+
+function ratio(value: number, budget: number): number {
+  return budget <= 0 ? Number.POSITIVE_INFINITY : Math.max(0, value) / budget;
+}

package/src/postprocess/BloomPass.ts

@@ -0,0 +1,28 @@
+import { bloomFloatPixels, bloomPixels, type BloomOptions, type BloomResult, type HdrBloomResult } from "../PostProcessPass";
+
+export interface ExternalParityBloomEvidence {
+  readonly mode: "ldr" | "hdr";
+  readonly brightPixelCount: number;
+  readonly changedPixels: number;
+  readonly maxNeighborBoost: number;
+  readonly diagnostic: string;
+}
+
+export function runExternalParityBloom(
+  pixels: Uint8Array | Float32Array,
+  width: number,
+  height: number,
+  options: BloomOptions = {}
+): BloomResult | HdrBloomResult {
+  return pixels instanceof Float32Array ? bloomFloatPixels(pixels, width, height, options) : bloomPixels(pixels, width, height, options);
+}
+
+export function createExternalParityBloomEvidence(result: BloomResult | HdrBloomResult): ExternalParityBloomEvidence {
+  return {
+    mode: result.pixels instanceof Float32Array ? "hdr" : "ldr",
+    brightPixelCount: result.brightPixelCount,
+    changedPixels: result.changedPixels,
+    maxNeighborBoost: result.maxNeighborBoost,
+    diagnostic: "Bloom evidence must improve highlights without hiding poor lighting or material failures."
+  };
+}