@aura3d/rendering 1.0.6

package/src/threejs-compatibility/performance/LODSystem.ts

@@ -0,0 +1,16 @@
+export interface ThreeCompatLodLevel {
+  readonly distance: number;
+  readonly triangleRatio: number;
+}
+
+export class LODSystemThreeCompat {
+  readonly levels: readonly ThreeCompatLodLevel[] = [
+    { distance: 0, triangleRatio: 1 },
+    { distance: 35, triangleRatio: 0.5 },
+    { distance: 90, triangleRatio: 0.18 }
+  ];
+
+  select(distance: number): ThreeCompatLodLevel {
+    return [...this.levels].reverse().find((level) => distance >= level.distance) ?? this.levels[0];
+  }
+}

package/src/threejs-compatibility/performance/OcclusionCulling.ts

@@ -0,0 +1,6 @@
+import type { ThreeCompatCullingResult } from "./FrustumCulling";
+
+export function runThreeCompatOcclusionCulling(input: ThreeCompatCullingResult, occlusionRatio = 0.2): ThreeCompatCullingResult {
+  const occluded = Math.round(input.visible * occlusionRatio);
+  return { total: input.total, visible: input.visible - occluded, culled: input.culled + occluded };
+}

package/src/threejs-compatibility/performance/RaycastAcceleration.ts

@@ -0,0 +1,12 @@
+import type { BVHThreeCompat } from "./BVH";
+
+export function estimateThreeCompatAcceleratedRaycast(bvh: BVHThreeCompat, rays: number) {
+  const bruteForceTests = bvh.triangleCount * rays;
+  const acceleratedTests = Math.ceil(Math.log2(bvh.nodes.length + 1) * rays * 8);
+  return {
+    rays,
+    bruteForceTests,
+    acceleratedTests,
+    speedup: bruteForceTests / acceleratedTests
+  };
+}

package/src/threejs-compatibility/performance/RendererProfiler.ts

@@ -0,0 +1,19 @@
+export interface ThreeCompatRendererProfile {
+  readonly objectCount: number;
+  readonly instanceCount: number;
+  readonly triangleCount: number;
+  readonly drawCalls: number;
+  readonly textureMemoryBytes: number;
+  readonly cpuFrameMs: number;
+  readonly warnings: readonly string[];
+}
+
+export function createThreeCompatRendererProfile(input: Omit<ThreeCompatRendererProfile, "warnings">): ThreeCompatRendererProfile {
+  return {
+    ...input,
+    warnings: [
+      ...(input.cpuFrameMs > 16.6 ? ["CPU frame time exceeds 60fps budget."] : []),
+      ...(input.drawCalls > 500 ? ["Draw call count is high; add batching or instancing."] : [])
+    ]
+  };
+}

package/src/threejs-compatibility/performance/TextureStreaming.ts

@@ -0,0 +1,4 @@
+export class TextureStreamingThreeCompat {
+  constructor(public readonly textureCount: number, public readonly residentMipBias = 1) {}
+  get estimatedMemoryBytes(): number { return this.textureCount * 1024 * 1024 * Math.max(1, 4 - this.residentMipBias); }
+}

package/src/threejs-compatibility/performance/index.ts

@@ -0,0 +1,12 @@
+export { InstancingThreeCompat } from "./Instancing";
+export { runThreeCompatFrustumCulling } from "./FrustumCulling";
+export type { ThreeCompatCullingResult } from "./FrustumCulling";
+export { runThreeCompatOcclusionCulling } from "./OcclusionCulling";
+export { BVHThreeCompat } from "./BVH";
+export type { ThreeCompatBvhNode } from "./BVH";
+export { estimateThreeCompatAcceleratedRaycast } from "./RaycastAcceleration";
+export { LODSystemThreeCompat } from "./LODSystem";
+export type { ThreeCompatLodLevel } from "./LODSystem";
+export { TextureStreamingThreeCompat } from "./TextureStreaming";
+export { createThreeCompatRendererProfile } from "./RendererProfiler";
+export type { ThreeCompatRendererProfile } from "./RendererProfiler";

package/src/threejs-compatibility/postprocess/BloomPass.ts

@@ -0,0 +1,16 @@
+import { bloomPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class BloomPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "BloomPass";
+  readonly enabled = true;
+  constructor(public readonly strength = 0.45) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, bloom: frame.bloom + this.strength },
+      this.name,
+      (pixels, width, height) => bloomPixels(pixels, width, height, { threshold: 0.58, intensity: this.strength, radius: 2 }).pixels,
+      "bloomPixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/ColorGradingPass.ts

@@ -0,0 +1,16 @@
+import { colorGradePixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class ColorGradingPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "ColorGradingPass";
+  readonly enabled = true;
+  constructor(public readonly contrast = 1.16, public readonly saturation = 1.08) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, contrast: frame.contrast * this.contrast, saturation: frame.saturation * this.saturation },
+      this.name,
+      (pixels, width, height) => colorGradePixels(pixels, width, height, { contrast: this.contrast, saturation: this.saturation, vibrance: 0.12, vignette: 0.1, sharpening: 0.12 }).pixels,
+      "colorGradePixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/DepthOfFieldPass.ts

@@ -0,0 +1,21 @@
+import { depthOfFieldPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, createThreeCompatDepthProxy, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class DepthOfFieldPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "DepthOfFieldPass";
+  readonly enabled = true;
+  constructor(public readonly blur = 0.35) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, blur: frame.blur + this.blur },
+      this.name,
+      (pixels, width, height) => depthOfFieldPixels(pixels, width, height, {
+        depth: frame.depth ?? createThreeCompatDepthProxy(width, height),
+        focusDepth: 0.44,
+        focusRange: 0.09,
+        maxRadius: Math.max(1, Math.round(this.blur * 6))
+      }).pixels,
+      "depthOfFieldPixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/EffectComposer.ts

@@ -0,0 +1,14 @@
+import type { ThreeCompatPostProcessFrame, ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class EffectComposerThreeCompat {
+  readonly passes: ThreeCompatPostProcessPass[] = [];
+
+  addPass(pass: ThreeCompatPostProcessPass): this {
+    this.passes.push(pass);
+    return this;
+  }
+
+  render(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return this.passes.reduce((current, pass) => pass.enabled ? pass.apply(current) : current, frame);
+  }
+}

package/src/threejs-compatibility/postprocess/FXAAPass.ts

@@ -0,0 +1,15 @@
+import { fxaaPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class FXAAPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "FXAAPass";
+  readonly enabled = true;
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, sharpness: frame.sharpness + 0.12 },
+      this.name,
+      (pixels, width, height) => fxaaPixels(pixels, width, height, { edgeThreshold: 0.08, subpixelBlend: 0.68 }).pixels,
+      "fxaaPixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/MotionBlurPass.ts

@@ -0,0 +1,20 @@
+import { motionBlurPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, createThreeCompatVelocityProxy, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class MotionBlurPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "MotionBlurPass";
+  readonly enabled = true;
+  constructor(public readonly blur = 0.18) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, blur: frame.blur + this.blur },
+      this.name,
+      (pixels, width, height) => motionBlurPixels(pixels, width, height, {
+        velocity: frame.velocity ?? createThreeCompatVelocityProxy(width, height),
+        samples: 5,
+        scale: Math.max(0.1, this.blur * 4)
+      }).pixels,
+      "motionBlurPixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/OutlinePass.ts

@@ -0,0 +1,21 @@
+import { outlinePixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class OutlinePassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "OutlinePass";
+  readonly enabled = true;
+  constructor(public readonly strength = 0.5) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, outlines: frame.outlines + this.strength },
+      this.name,
+      (pixels, width, height) => outlinePixels(pixels, width, height, {
+        threshold: 0.08,
+        width: 2,
+        opacity: Math.min(1, 0.45 + this.strength * 0.5),
+        color: [64, 190, 255, 255]
+      }).pixels,
+      "outlinePixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/PostProcessTypes.ts

@@ -0,0 +1,169 @@
+import type { DepthTextureBinding } from "../../PostProcessPass";
+import { countChangedRgb } from "../../production-runtime/postprocess/ProductionPostProcessTypes";
+
+export interface ThreeCompatPostProcessFrame {
+  readonly label: string;
+  readonly exposure: number;
+  readonly contrast: number;
+  readonly saturation: number;
+  readonly bloom: number;
+  readonly ambientOcclusion: number;
+  readonly sharpness: number;
+  readonly blur: number;
+  readonly vignette: number;
+  readonly outlines: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly pixels?: Uint8Array;
+  readonly depth?: DepthTextureBinding;
+  readonly history?: Uint8Array;
+  readonly velocity?: Float32Array;
+  readonly visualChangedPixels?: number;
+  readonly visualPasses?: readonly string[];
+  readonly visualDiagnostics?: readonly string[];
+}
+
+export interface ThreeCompatPostProcessPass {
+  readonly name: string;
+  readonly enabled: boolean;
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame;
+}
+
+export interface ThreeCompatBaseFrameOptions {
+  readonly width?: number;
+  readonly height?: number;
+  readonly pixels?: Uint8Array;
+  readonly depth?: DepthTextureBinding;
+  readonly history?: Uint8Array;
+  readonly velocity?: Float32Array;
+}
+
+export function createThreeCompatBaseFrame(label = "source", options: ThreeCompatBaseFrameOptions = {}): ThreeCompatPostProcessFrame {
+  return {
+    label,
+    exposure: 1,
+    contrast: 1,
+    saturation: 1,
+    bloom: 0,
+    ambientOcclusion: 0,
+    sharpness: 0,
+    blur: 0,
+    vignette: 0,
+    outlines: 0,
+    ...(options.width !== undefined ? { width: options.width } : {}),
+    ...(options.height !== undefined ? { height: options.height } : {}),
+    ...(options.pixels !== undefined ? { pixels: new Uint8Array(options.pixels) } : {}),
+    ...(options.depth !== undefined ? { depth: options.depth } : {}),
+    ...(options.history !== undefined ? { history: new Uint8Array(options.history) } : {}),
+    ...(options.velocity !== undefined ? { velocity: new Float32Array(options.velocity) } : {}),
+    visualChangedPixels: 0,
+    visualPasses: [],
+    visualDiagnostics: []
+  };
+}
+
+export function createThreeCompatDemoFrame(label = "source", width = 64, height = 48): ThreeCompatPostProcessFrame {
+  const pixels = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const index = (y * width + x) * 4;
+      let red = 20 + Math.round(x * 2.1);
+      let green = 24 + Math.round(y * 2);
+      let blue = 40 + Math.round((x + y) * 0.68);
+      if (x >= width * 0.18 && x <= width * 0.36 && y >= height * 0.16 && y <= height * 0.52) {
+        red = 248;
+        green = 202;
+        blue = 90;
+      }
+      if (x >= width * 0.58 && x <= width * 0.82 && y >= height * 0.22 && y <= height * 0.64) {
+        red = 54;
+        green = 190;
+        blue = 250;
+      }
+      if ((Math.abs(x - width * 0.49) < 1.2 || Math.abs(y - height * 0.72) < 1.2) && x > width * 0.1 && x < width * 0.9) {
+        red = 248;
+        green = 248;
+        blue = 242;
+      }
+      pixels[index] = red;
+      pixels[index + 1] = green;
+      pixels[index + 2] = blue;
+      pixels[index + 3] = 255;
+    }
+  }
+  return createThreeCompatBaseFrame(label, {
+    width,
+    height,
+    pixels,
+    depth: createThreeCompatDepthProxy(width, height),
+    history: createThreeCompatHistoryProxy(pixels, width, height),
+    velocity: createThreeCompatVelocityProxy(width, height)
+  });
+}
+
+export function applyThreeCompatPixelKernel(
+  frame: ThreeCompatPostProcessFrame,
+  passName: string,
+  transform: (pixels: Uint8Array, width: number, height: number) => Uint8Array,
+  diagnostic: string
+): ThreeCompatPostProcessFrame {
+  if (!frame.pixels || !frame.width || !frame.height) {
+    return {
+      ...frame,
+      visualDiagnostics: [...(frame.visualDiagnostics ?? []), `${passName}: no pixel buffer supplied; metrics updated only.`]
+    };
+  }
+  const before = frame.pixels;
+  const after = transform(before, frame.width, frame.height);
+  const changed = countChangedRgb(before, after);
+  return {
+    ...frame,
+    pixels: after,
+    visualChangedPixels: (frame.visualChangedPixels ?? 0) + changed,
+    visualPasses: [...(frame.visualPasses ?? []), passName],
+    visualDiagnostics: [...(frame.visualDiagnostics ?? []), `${passName}: ${diagnostic}; changedPixels=${changed}`]
+  };
+}
+
+export function createThreeCompatDepthProxy(width: number, height: number): DepthTextureBinding {
+  const data = new Float32Array(width * height);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      let depth = y > height * 0.68 ? 0.58 : 0.82;
+      if (x >= width * 0.18 && x <= width * 0.36 && y >= height * 0.16 && y <= height * 0.52) depth = 0.28;
+      if (x >= width * 0.58 && x <= width * 0.82 && y >= height * 0.22 && y <= height * 0.64) depth = 0.42;
+      data[y * width + x] = depth;
+    }
+  }
+  return { label: "three-compat-postprocess-depth-proxy", width, height, format: "depth24", data };
+}
+
+export function createThreeCompatHistoryProxy(pixels: Uint8Array, width: number, height: number): Uint8Array {
+  const history = new Uint8Array(pixels.length);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const sourceX = Math.max(0, x - 2);
+      const source = (y * width + sourceX) * 4;
+      const target = (y * width + x) * 4;
+      history[target] = Math.max(0, (pixels[source] ?? 0) - 12);
+      history[target + 1] = Math.max(0, (pixels[source + 1] ?? 0) - 10);
+      history[target + 2] = Math.max(0, (pixels[source + 2] ?? 0) - 8);
+      history[target + 3] = pixels[source + 3] ?? 255;
+    }
+  }
+  return history;
+}
+
+export function createThreeCompatVelocityProxy(width: number, height: number): Float32Array {
+  const velocity = new Float32Array(width * height * 2);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if (x < width * 0.78 && y > height * 0.14 && y < height * 0.7) {
+        const index = (y * width + x) * 2;
+        velocity[index] = 1.7;
+        velocity[index + 1] = x > width * 0.48 ? -0.65 : 0.32;
+      }
+    }
+  }
+  return velocity;
+}

package/src/threejs-compatibility/postprocess/RenderPass.ts

@@ -0,0 +1,9 @@
+import type { ThreeCompatPostProcessFrame, ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class RenderPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "RenderPass";
+  readonly enabled = true;
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return { ...frame, label: "rendered-scene" };
+  }
+}

package/src/threejs-compatibility/postprocess/SMAAPass.ts

@@ -0,0 +1,15 @@
+import { fxaaPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class SMAAPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "SMAAPass";
+  readonly enabled = true;
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, sharpness: frame.sharpness + 0.16 },
+      this.name,
+      (pixels, width, height) => fxaaPixels(pixels, width, height, { edgeThreshold: 0.06, subpixelBlend: 0.72 }).pixels,
+      "FXAA-backed compatibility antialiasing kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/SSAOPass.ts

@@ -0,0 +1,21 @@
+import { ssaoPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, createThreeCompatDepthProxy, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class SSAOPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "SSAOPass";
+  readonly enabled = true;
+  constructor(public readonly radius = 0.7) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, ambientOcclusion: frame.ambientOcclusion + this.radius },
+      this.name,
+      (pixels, width, height) => ssaoPixels(pixels, width, height, {
+        depth: frame.depth ?? createThreeCompatDepthProxy(width, height),
+        radius: Math.max(1, Math.round(this.radius * 3)),
+        intensity: Math.max(0.1, this.radius),
+        bias: 0.01
+      }).pixels,
+      "ssaoPixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/ShaderPass.ts

@@ -0,0 +1,7 @@
+import type { ThreeCompatPostProcessFrame, ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class ShaderPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly enabled = true;
+  constructor(public readonly name: string, private readonly transform: (frame: ThreeCompatPostProcessFrame) => ThreeCompatPostProcessFrame) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame { return this.transform(frame); }
+}

package/src/threejs-compatibility/postprocess/TAAPass.ts

@@ -0,0 +1,15 @@
+import { taaPixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, createThreeCompatHistoryProxy, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class TAAPassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "TAAPass";
+  readonly enabled = true;
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, sharpness: frame.sharpness + 0.18 },
+      this.name,
+      (pixels, width, height) => taaPixels(pixels, width, height, { history: frame.history ?? createThreeCompatHistoryProxy(pixels, width, height), blend: 0.22 }).pixels,
+      "taaPixels kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/VignettePass.ts

@@ -0,0 +1,16 @@
+import { colorGradePixels } from "../../PostProcessPass";
+import { applyThreeCompatPixelKernel, type ThreeCompatPostProcessFrame, type ThreeCompatPostProcessPass } from "./PostProcessTypes";
+
+export class VignettePassThreeCompat implements ThreeCompatPostProcessPass {
+  readonly name = "VignettePass";
+  readonly enabled = true;
+  constructor(public readonly amount = 0.22) {}
+  apply(frame: ThreeCompatPostProcessFrame): ThreeCompatPostProcessFrame {
+    return applyThreeCompatPixelKernel(
+      { ...frame, vignette: frame.vignette + this.amount },
+      this.name,
+      (pixels, width, height) => colorGradePixels(pixels, width, height, { vignette: this.amount, contrast: 1.02, saturation: 1 }).pixels,
+      "colorGradePixels vignette kernel"
+    );
+  }
+}

package/src/threejs-compatibility/postprocess/index.ts

@@ -0,0 +1,15 @@
+export { EffectComposerThreeCompat } from "./EffectComposer";
+export { RenderPassThreeCompat } from "./RenderPass";
+export { ShaderPassThreeCompat } from "./ShaderPass";
+export { BloomPassThreeCompat } from "./BloomPass";
+export { SSAOPassThreeCompat } from "./SSAOPass";
+export { TAAPassThreeCompat } from "./TAAPass";
+export { FXAAPassThreeCompat } from "./FXAAPass";
+export { SMAAPassThreeCompat } from "./SMAAPass";
+export { DepthOfFieldPassThreeCompat } from "./DepthOfFieldPass";
+export { MotionBlurPassThreeCompat } from "./MotionBlurPass";
+export { ColorGradingPassThreeCompat } from "./ColorGradingPass";
+export { VignettePassThreeCompat } from "./VignettePass";
+export { OutlinePassThreeCompat } from "./OutlinePass";
+export { createThreeCompatBaseFrame, createThreeCompatDemoFrame } from "./PostProcessTypes";
+export type { ThreeCompatBaseFrameOptions, ThreeCompatPostProcessFrame, ThreeCompatPostProcessPass } from "./PostProcessTypes";

package/src/threejs-compatibility/shaders/NodeMaterial.ts

@@ -0,0 +1,21 @@
+export interface ThreeCompatShaderNode {
+  readonly id: string;
+  readonly kind: "color" | "float" | "texture" | "math" | "output";
+}
+
+export class NodeMaterialThreeCompat {
+  readonly type = "NodeMaterial";
+  readonly nodes: ThreeCompatShaderNode[] = [];
+
+  addNode(node: ThreeCompatShaderNode): this {
+    this.nodes.push(node);
+    return this;
+  }
+
+  compileGraph(): { readonly nodeCount: number; readonly hasOutput: boolean } {
+    return {
+      nodeCount: this.nodes.length,
+      hasOutput: this.nodes.some((node) => node.kind === "output")
+    };
+  }
+}

package/src/threejs-compatibility/shaders/RawShaderMaterial.ts

@@ -0,0 +1,6 @@
+import { ShaderMaterialThreeCompat } from "./ShaderMaterial";
+
+export class RawShaderMaterialThreeCompat extends ShaderMaterialThreeCompat {
+  override readonly type = "RawShaderMaterial";
+  glslVersion: "300 es" | "100" = "300 es";
+}

package/src/threejs-compatibility/shaders/ShaderDiagnostics.ts

@@ -0,0 +1,17 @@
+export interface ThreeCompatShaderDiagnostic {
+  readonly pass: boolean;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export function diagnoseThreeCompatShader(vertexShader: string, fragmentShader: string): ThreeCompatShaderDiagnostic {
+  const errors = [
+    ...(!vertexShader.includes("void main") ? ["vertex shader missing void main"] : []),
+    ...(!fragmentShader.includes("void main") ? ["fragment shader missing void main"] : []),
+    ...(/gl_FragColor/.test(fragmentShader) ? ["fragment shader uses legacy gl_FragColor; use explicit output for modern targets"] : [])
+  ];
+  const warnings = [
+    ...(!/precision\s+(highp|mediump)/.test(fragmentShader) ? ["fragment shader precision is implicit"] : [])
+  ];
+  return { pass: errors.length === 0, errors, warnings };
+}

package/src/threejs-compatibility/shaders/ShaderMaterial.ts

@@ -0,0 +1,18 @@
+import { UniformsThreeCompat } from "./Uniforms";
+import { diagnoseThreeCompatShader, type ThreeCompatShaderDiagnostic } from "./ShaderDiagnostics";
+
+export class ShaderMaterialThreeCompat {
+  readonly type: string = "ShaderMaterial";
+  readonly uniforms = new UniformsThreeCompat();
+
+  constructor(public vertexShader: string, public fragmentShader: string) {}
+
+  setUniform(name: string, value: number | boolean | string | readonly number[]): this {
+    this.uniforms.set(name, value);
+    return this;
+  }
+
+  diagnose(): ThreeCompatShaderDiagnostic {
+    return diagnoseThreeCompatShader(this.vertexShader, this.fragmentShader);
+  }
+}

package/src/threejs-compatibility/shaders/ThreeCompatShaderChunks.ts

@@ -0,0 +1,6 @@
+export const SHADER_CHUNKS_THREE_COMPAT = {
+  colorManagement: "vec3 linearToOutput(vec3 color) { return pow(color, vec3(1.0 / 2.2)); }",
+  pbrLighting: "vec3 applyPbrLight(vec3 baseColor, float roughness) { return baseColor * (1.0 - roughness * 0.35); }",
+  fog: "vec3 applyFog(vec3 color, float depth) { return mix(color, vec3(0.02, 0.03, 0.05), clamp(depth, 0.0, 1.0)); }",
+  screenUv: "vec2 getScreenUv(vec2 fragCoord, vec2 resolution) { return fragCoord / resolution; }"
+} as const;

package/src/threejs-compatibility/shaders/Uniforms.ts

@@ -0,0 +1,18 @@
+export type ThreeCompatUniformValue = number | boolean | string | readonly number[];
+
+export class UniformsThreeCompat {
+  private readonly values = new Map<string, ThreeCompatUniformValue>();
+
+  set(name: string, value: ThreeCompatUniformValue): this {
+    this.values.set(name, value);
+    return this;
+  }
+
+  get(name: string): ThreeCompatUniformValue | undefined {
+    return this.values.get(name);
+  }
+
+  entries(): readonly [string, ThreeCompatUniformValue][] {
+    return [...this.values.entries()];
+  }
+}

package/src/threejs-compatibility/shaders/index.ts

@@ -0,0 +1,9 @@
+export { ShaderMaterialThreeCompat } from "./ShaderMaterial";
+export { RawShaderMaterialThreeCompat } from "./RawShaderMaterial";
+export { UniformsThreeCompat } from "./Uniforms";
+export type { ThreeCompatUniformValue } from "./Uniforms";
+export { SHADER_CHUNKS_THREE_COMPAT } from "./ThreeCompatShaderChunks";
+export { NodeMaterialThreeCompat } from "./NodeMaterial";
+export type { ThreeCompatShaderNode } from "./NodeMaterial";
+export { diagnoseThreeCompatShader } from "./ShaderDiagnostics";
+export type { ThreeCompatShaderDiagnostic } from "./ShaderDiagnostics";

package/src/threejs-compatibility/vfx/GPUPointCloud.ts

@@ -0,0 +1,7 @@
+export class GPUPointCloudThreeCompat {
+  constructor(public readonly pointCount: number, public readonly stride = 16) {}
+
+  get estimatedBytes(): number {
+    return this.pointCount * this.stride;
+  }
+}

package/src/threejs-compatibility/vfx/LineRenderer.ts

@@ -0,0 +1,13 @@
+export interface ThreeCompatLineSegment {
+  readonly from: readonly [number, number, number];
+  readonly to: readonly [number, number, number];
+  readonly width: number;
+}
+
+export class LineThreeCompatRenderer {
+  readonly segments: ThreeCompatLineSegment[] = [];
+
+  addSegment(segment: ThreeCompatLineSegment): void {
+    this.segments.push(segment);
+  }
+}

package/src/threejs-compatibility/vfx/ParticleSystem.ts

@@ -0,0 +1,23 @@
+export interface ThreeCompatParticle {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  readonly life: number;
+}
+
+export class ParticleSystemThreeCompat {
+  readonly particles: ThreeCompatParticle[] = [];
+
+  emit(count: number): void {
+    for (let index = 0; index < count; index++) {
+      this.particles.push({ x: index % 32, y: Math.floor(index / 32), z: 0, life: 1 });
+    }
+  }
+
+  update(delta: number): void {
+    for (let index = 0; index < this.particles.length; index++) {
+      const particle = this.particles[index];
+      this.particles[index] = { ...particle, y: particle.y + delta, life: Math.max(0, particle.life - delta * 0.1) };
+    }
+  }
+}