@aura3d/rendering 1.0.6

package/src/WebGPURenderToTextureProof.ts

@@ -0,0 +1,139 @@
+import {
+  type RenderDevice,
+  RenderDeviceError,
+  type RenderDeviceDiagnostics,
+  type RenderTarget
+} from "./RenderDevice";
+import { VertexFormat } from "./VertexFormat";
+
+export interface WebGPURenderToTextureProofOptions {
+  readonly width?: number;
+  readonly height?: number;
+  readonly label?: string;
+  readonly clearColor?: readonly [number, number, number, number];
+  readonly triangleColor?: readonly [number, number, number, number];
+  readonly disposeResources?: boolean;
+}
+
+export interface WebGPURenderToTextureProof {
+  readonly backend: "webgpu";
+  readonly width: number;
+  readonly height: number;
+  readonly label: string;
+  readonly renderTargetFormat: "rgba8";
+  readonly hasDepthTexture: boolean;
+  readonly drawCalls: number;
+  readonly targetPixel: readonly number[];
+  readonly presentedPixel: readonly number[];
+  readonly readbackMatchesPresentation: boolean;
+  readonly targetPixels: Uint8Array;
+  readonly diagnosticsBeforeDispose: RenderDeviceDiagnostics;
+  readonly diagnosticsAfterDispose: RenderDeviceDiagnostics;
+  readonly disposedRenderTargets: number;
+  readonly disposedTextures: number;
+}
+
+const SHADER_MARKER = "@aura3d-shader:webgpu-rtt-proof";
+
+export function runWebGPURenderToTextureProof(
+  device: RenderDevice,
+  options: WebGPURenderToTextureProofOptions = {}
+): WebGPURenderToTextureProof {
+  if (device.kind !== "webgpu") {
+    throw new RenderDeviceError("WebGPU render-to-texture proof requires a WebGPU render device.", "WEBGPU_DEVICE_REQUIRED", {
+      backend: device.kind
+    });
+  }
+
+  const width = options.width ?? 64;
+  const height = options.height ?? 64;
+  if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) {
+    throw new RenderDeviceError("WebGPU render-to-texture dimensions must be positive integers.", "INVALID_RENDER_TARGET_SIZE", {
+      width,
+      height
+    });
+  }
+
+  const label = options.label ?? "webgpu-rtt-proof";
+  const clearColor = options.clearColor ?? [0.02, 0.025, 0.035, 1];
+  const triangleColor = options.triangleColor ?? [0.1, 0.8, 0.2, 1];
+  const shouldDispose = options.disposeResources ?? true;
+  const target = device.createRenderTarget({ width, height, label, format: "rgba8", depth: "texture" });
+  const vertexBuffer = device.createBuffer("vertex", TRIANGLE_VERTICES.byteLength, TRIANGLE_VERTICES);
+  const shader = device.createShaderProgram({
+    label: `${label}-shader`,
+    marker: SHADER_MARKER,
+    vertex: `// ${SHADER_MARKER}
+in vec3 position;
+void main() {
+  gl_Position = vec4(position, 1.0);
+}`,
+    fragment: `// ${SHADER_MARKER}
+uniform vec4 u_color;
+out vec4 outColor;
+void main() {
+  outColor = u_color;
+}`
+  });
+
+  device.setRenderTarget(target);
+  device.beginFrame(width, height);
+  device.clear(clearColor);
+  device.draw({
+    label: `${label}-triangle`,
+    topology: "triangles",
+    vertexBuffer,
+    vertexFormat: VertexFormat.P3,
+    vertexCount: 3,
+    shader,
+    uniforms: new Map([["u_color", triangleColor]])
+  });
+  const sampleX = Math.floor(width / 2);
+  const sampleY = Math.floor(height / 2);
+  const targetPixel = Array.from(device.readPixels(sampleX, sampleY, 1, 1));
+  const targetPixels = device.readPixels(0, 0, width, height);
+  device.endFrame();
+  device.presentRenderTarget?.(target);
+  const presentedPixel = Array.from(device.readPixels(sampleX, sampleY, 1, 1));
+  const diagnosticsBeforeDispose = device.getDiagnostics();
+
+  if (shouldDispose) {
+    vertexBuffer.dispose();
+    shader.dispose();
+    target.dispose();
+  }
+  const diagnosticsAfterDispose = device.getDiagnostics();
+
+  return {
+    backend: "webgpu",
+    width,
+    height,
+    label,
+    renderTargetFormat: "rgba8",
+    hasDepthTexture: target.depthTexture !== undefined,
+    drawCalls: diagnosticsBeforeDispose.drawCalls,
+    targetPixel,
+    presentedPixel,
+    readbackMatchesPresentation: samePixel(targetPixel, presentedPixel),
+    targetPixels,
+    diagnosticsBeforeDispose,
+    diagnosticsAfterDispose,
+    disposedRenderTargets: diagnosticsAfterDispose.disposedRenderTargets ?? 0,
+    disposedTextures: diagnosticsAfterDispose.disposedTextures ?? 0
+  };
+}
+
+export function isWebGPURenderTarget(target: RenderTarget): boolean {
+  return target.colorTexture.format === "rgba8" && target.width > 0 && target.height > 0;
+}
+
+const TRIANGLE_VERTICES = new Float32Array([
+  -0.82, -0.82, 0,
+  0.82, -0.82, 0,
+  0, 0.82, 0
+]);
+
+function samePixel(left: readonly number[], right: readonly number[]): boolean {
+  if (left.length !== right.length) return false;
+  return left.every((value, index) => value === right[index]);
+}

package/src/advanced-runtime/AdvancedRenderer.ts

@@ -0,0 +1,73 @@
+import {
+  Renderer,
+  type CameraLike,
+  type RendererAnimationLoop,
+  type RendererFrameCapture,
+  type RendererInput,
+  type RendererOptions,
+  type RenderSource,
+  type ResizeToDisplayOptions,
+  type ResizeToDisplayResult
+} from "../Renderer";
+import type { RenderDeviceDiagnostics } from "../RenderDevice";
+import type { RenderItem } from "../ForwardPass";
+import type { Scene } from "@aura3d/scene";
+
+export type AdvancedRendererOptions = RendererOptions;
+export type AdvancedRendererSource = RendererInput | RenderSource | Iterable<RenderItem> | Scene;
+
+export class AdvancedRenderer {
+  private constructor(readonly renderer: Renderer) {}
+
+  static async create(options: AdvancedRendererOptions = {}): Promise<AdvancedRenderer> {
+    return new AdvancedRenderer(await Renderer.create(options));
+  }
+
+  get device() {
+    return this.renderer.device;
+  }
+
+  resize(width: number, height: number): void {
+    this.renderer.resize(width, height);
+  }
+
+  resizeToDisplay(options: ResizeToDisplayOptions = {}): ResizeToDisplayResult {
+    return this.renderer.resizeToDisplay(options);
+  }
+
+  startAnimationLoop(callback: (timeMs: number, renderer: AdvancedRenderer) => void): RendererAnimationLoop {
+    return this.renderer.startAnimationLoop((timeMs) => callback(timeMs, this));
+  }
+
+  render(input: RendererInput): RenderDeviceDiagnostics;
+  render(source: RenderSource | Iterable<RenderItem> | Scene, camera?: CameraLike): RenderDeviceDiagnostics;
+  render(sourceOrInput: AdvancedRendererSource, camera?: CameraLike): RenderDeviceDiagnostics {
+    return isRendererInput(sourceOrInput)
+      ? this.renderer.render(sourceOrInput)
+      : this.renderer.render(sourceOrInput, camera);
+  }
+
+  renderAsync(input: RendererInput): Promise<RenderDeviceDiagnostics>;
+  renderAsync(source: RenderSource | Iterable<RenderItem> | Scene, camera?: CameraLike): Promise<RenderDeviceDiagnostics>;
+  renderAsync(sourceOrInput: AdvancedRendererSource, camera?: CameraLike): Promise<RenderDeviceDiagnostics> {
+    return isRendererInput(sourceOrInput)
+      ? this.renderer.renderAsync(sourceOrInput)
+      : this.renderer.renderAsync(sourceOrInput, camera);
+  }
+
+  captureFrame(source?: RenderSource | Iterable<RenderItem> | Scene, camera?: CameraLike): RendererFrameCapture {
+    return this.renderer.captureFrame(source, camera);
+  }
+
+  getDiagnostics(): RenderDeviceDiagnostics {
+    return this.renderer.getDiagnostics();
+  }
+
+  dispose(): void {
+    this.renderer.dispose();
+  }
+}
+
+function isRendererInput(value: AdvancedRendererSource): value is RendererInput {
+  return typeof value === "object" && value !== null && "source" in value;
+}

package/src/advanced-runtime/index.ts

@@ -0,0 +1,9 @@
+export { AdvancedRenderer } from "./AdvancedRenderer";
+export type { AdvancedRendererOptions, AdvancedRendererSource } from "./AdvancedRenderer";
+export * from "../Renderer";
+export * from "../RenderDevice";
+export * from "../Geometry";
+export * from "../Material";
+export * from "../PBRMaterial";
+export * from "../UnlitMaterial";
+export * from "../ForwardPass";

package/src/cinematic/BloomPass.ts

@@ -0,0 +1,26 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicBloomPass {
+  readonly name: "bloom";
+  readonly threshold: number;
+  readonly intensity: number;
+  readonly radius: number;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+}
+
+export function createCinematicBloomPass(options: Partial<Omit<CinematicBloomPass, "name" | "rendererOwnedEvidence">> = {}): CinematicBloomPass {
+  return {
+    name: "bloom",
+    threshold: options.threshold ?? 0.72,
+    intensity: options.intensity ?? 0.28,
+    radius: options.radius ?? 1.35,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: "postprocess:bloom",
+      feature: "postprocess",
+      label: "Bloom/glow pass",
+      source: "renderer-postprocess",
+      sceneContent: false,
+      diagnostics: ["Bloom is a renderer postprocess pass over emissive scene content."]
+    })
+  };
+}

package/src/cinematic/CinematicDepthComposition.ts

@@ -0,0 +1,30 @@
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export interface CinematicDepthCompositionPlan {
+  readonly mode: "depth-aware" | "camera-sorted";
+  readonly depthTextureRequired: boolean;
+  readonly fallback: "camera-sorted-transparent-cards";
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createCinematicDepthCompositionPlan(options: { readonly depthTextureAvailable?: boolean } = {}): CinematicDepthCompositionPlan {
+  const depthTextureAvailable = options.depthTextureAvailable === true;
+  return {
+    mode: depthTextureAvailable ? "depth-aware" : "camera-sorted",
+    depthTextureRequired: depthTextureAvailable,
+    fallback: "camera-sorted-transparent-cards",
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: "vfx:depth-composition",
+      feature: "vfx",
+      label: "Depth-aware VFX composition",
+      source: "renderer-vfx",
+      diagnostics: [depthTextureAvailable ? "VFX can sample renderer-owned depth." : "VFX falls back to camera-sorted renderer cards/particles."]
+    }),
+    diagnostics: [
+      depthTextureAvailable
+        ? "Depth texture is available for VFX composition."
+        : "Depth texture is not declared; composition remains renderer-owned but uses camera-sorted approximations."
+    ]
+  };
+}

package/src/cinematic/CinematicEvidence.ts

@@ -0,0 +1,123 @@
+export type CinematicEvidenceFeature =
+  | "material"
+  | "lighting"
+  | "vfx"
+  | "postprocess"
+  | "camera"
+  | "timeline"
+  | "blocking"
+  | "asset"
+  | "environment";
+
+export type CinematicEvidenceSource =
+  | "renderer-scene"
+  | "renderer-material"
+  | "renderer-light"
+  | "renderer-vfx"
+  | "renderer-postprocess"
+  | "renderer-camera"
+  | "renderer-timeline"
+  | "dom-overlay"
+  | "css-overlay";
+
+export interface CinematicRendererEvidenceFlag {
+  readonly id: string;
+  readonly feature: CinematicEvidenceFeature;
+  readonly label: string;
+  readonly source: CinematicEvidenceSource;
+  readonly rendererOwned: boolean;
+  readonly sceneContent: boolean;
+  readonly domOverlay: boolean;
+  readonly satisfiesPublicCinematicGate: boolean;
+  readonly diagnostics: readonly string[];
+}
+
+export interface CinematicDomOverlayRejection {
+  readonly ok: false;
+  readonly code: "AURA_CINEMATIC_DOM_OVERLAY_EVIDENCE_REJECTED";
+  readonly missingRendererOwnedFeatures: readonly CinematicEvidenceFeature[];
+  readonly overlayOnlyFeatures: readonly CinematicEvidenceFeature[];
+  readonly diagnostics: readonly string[];
+}
+
+export interface CinematicRendererEvidenceAccepted {
+  readonly ok: true;
+  readonly rendererOwnedFeatures: readonly CinematicEvidenceFeature[];
+  readonly diagnostics: readonly string[];
+}
+
+export type CinematicRendererEvidenceValidation = CinematicRendererEvidenceAccepted | CinematicDomOverlayRejection;
+
+export function createRendererOwnedEvidenceFlag(input: {
+  readonly id: string;
+  readonly feature: CinematicEvidenceFeature;
+  readonly label: string;
+  readonly source?: Exclude<CinematicEvidenceSource, "dom-overlay" | "css-overlay">;
+  readonly sceneContent?: boolean;
+  readonly diagnostics?: readonly string[];
+}): CinematicRendererEvidenceFlag {
+  return {
+    id: input.id,
+    feature: input.feature,
+    label: input.label,
+    source: input.source ?? "renderer-scene",
+    rendererOwned: true,
+    sceneContent: input.sceneContent ?? true,
+    domOverlay: false,
+    satisfiesPublicCinematicGate: true,
+    diagnostics: input.diagnostics ?? []
+  };
+}
+
+export function createDomOverlayEvidenceFlag(input: {
+  readonly id: string;
+  readonly feature: CinematicEvidenceFeature;
+  readonly label: string;
+  readonly source?: "dom-overlay" | "css-overlay";
+  readonly diagnostics?: readonly string[];
+}): CinematicRendererEvidenceFlag {
+  return {
+    id: input.id,
+    feature: input.feature,
+    label: input.label,
+    source: input.source ?? "dom-overlay",
+    rendererOwned: false,
+    sceneContent: false,
+    domOverlay: true,
+    satisfiesPublicCinematicGate: false,
+    diagnostics: input.diagnostics ?? ["DOM/CSS overlays are diagnostic UI only and do not satisfy public cinematic scene evidence."]
+  };
+}
+
+export function validateRendererOwnedCinematicEvidence(
+  flags: readonly CinematicRendererEvidenceFlag[],
+  requiredFeatures: readonly CinematicEvidenceFeature[]
+): CinematicRendererEvidenceValidation {
+  const rendererOwnedFeatures = unique(flags.filter((flag) => flag.rendererOwned && flag.satisfiesPublicCinematicGate).map((flag) => flag.feature));
+  const overlayOnlyFeatures = requiredFeatures.filter((feature) => {
+    const featureFlags = flags.filter((flag) => flag.feature === feature);
+    return featureFlags.length > 0 && featureFlags.every((flag) => flag.domOverlay || !flag.rendererOwned);
+  });
+  const missingRendererOwnedFeatures = requiredFeatures.filter((feature) => !rendererOwnedFeatures.includes(feature));
+  if (missingRendererOwnedFeatures.length > 0 || overlayOnlyFeatures.length > 0) {
+    return {
+      ok: false,
+      code: "AURA_CINEMATIC_DOM_OVERLAY_EVIDENCE_REJECTED",
+      missingRendererOwnedFeatures,
+      overlayOnlyFeatures,
+      diagnostics: [
+        "Required cinematic proof must come from renderer-owned scene, material, lighting, VFX, postprocess, camera, timeline, or blocking data.",
+        ...overlayOnlyFeatures.map((feature) => `${feature} was represented only by DOM/CSS overlay evidence.`)
+      ]
+    };
+  }
+  return {
+    ok: true,
+    rendererOwnedFeatures,
+    diagnostics: ["All required cinematic evidence features are renderer-owned."]
+  };
+}
+
+function unique<T>(values: readonly T[]): readonly T[] {
+  return [...new Set(values)];
+}

package/src/cinematic/CinematicLightingRig.ts

@@ -0,0 +1,144 @@
+import type { EnvironmentLightingOptions } from "../ForwardPass";
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export type CinematicLightingRigId =
+  | "soft-key-fill-rim"
+  | "moody-alley"
+  | "studio-product"
+  | "warm-sunrise"
+  | "cool-moonlit";
+
+export type CinematicLightRole = "key" | "fill" | "rim" | "practical" | "ambient";
+export type CinematicLightType = "directional" | "point" | "spot" | "ambient";
+
+export interface CinematicRuntimeLight {
+  readonly id: string;
+  readonly role: CinematicLightRole;
+  readonly type: CinematicLightType;
+  readonly color: readonly [number, number, number];
+  readonly intensity: number;
+  readonly position?: readonly [number, number, number];
+  readonly direction?: readonly [number, number, number];
+  readonly castsShadow: boolean;
+}
+
+export interface CinematicLightingRig {
+  readonly id: CinematicLightingRigId;
+  readonly label: string;
+  readonly exposure: number;
+  readonly toneMap: {
+    readonly operator: "filmic" | "aces" | "reinhard";
+    readonly whitePoint: number;
+  };
+  readonly environmentLighting: EnvironmentLightingOptions;
+  readonly lights: readonly CinematicRuntimeLight[];
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly diagnostics: readonly string[];
+}
+
+export function createCinematicLightingRig(id: CinematicLightingRigId): CinematicLightingRig {
+  const rig = rigWithoutEvidence(id);
+  return {
+    ...rig,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `lighting:${id}`,
+      feature: "lighting",
+      label: rig.label,
+      source: "renderer-light",
+      diagnostics: rig.diagnostics
+    })
+  };
+}
+
+export function listCinematicLightingRigs(): readonly CinematicLightingRig[] {
+  const ids: readonly CinematicLightingRigId[] = ["soft-key-fill-rim", "moody-alley", "studio-product", "warm-sunrise", "cool-moonlit"];
+  return ids.map(createCinematicLightingRig);
+}
+
+export function selectCinematicLightingRig(tags: readonly string[]): CinematicLightingRigId {
+  const lower = tags.map((tag) => tag.toLowerCase());
+  if (lower.some((tag) => tag.includes("alley") || tag.includes("neon") || tag.includes("rain"))) return "moody-alley";
+  if (lower.some((tag) => tag.includes("studio") || tag.includes("product"))) return "studio-product";
+  if (lower.some((tag) => tag.includes("sunrise") || tag.includes("warm") || tag.includes("golden"))) return "warm-sunrise";
+  if (lower.some((tag) => tag.includes("moon") || tag.includes("night") || tag.includes("cool"))) return "cool-moonlit";
+  return "soft-key-fill-rim";
+}
+
+function rigWithoutEvidence(id: CinematicLightingRigId): Omit<CinematicLightingRig, "rendererOwnedEvidence"> {
+  switch (id) {
+    case "moody-alley":
+      return makeRig(id, "Moody alley", 1.24, [0.035, 0.045, 0.07], 0.34, [
+        light("alley-key", "key", "spot", [0.42, 0.58, 1], 2.2, [-2.4, 3.6, 2.2], [0.45, -0.72, -0.52], true),
+        light("alley-rim", "rim", "point", [0.04, 0.86, 1], 3.4, [1.8, 1.2, -1.4], undefined, true),
+        light("alley-practical-neon", "practical", "point", [1, 0.08, 0.62], 2.8, [-1.6, 1.7, -2.1], undefined, false)
+      ], ["Moody alley rig includes key, rim, and practical light metadata compiled for the renderer."]);
+    case "studio-product":
+      return makeRig(id, "Studio product", 1.08, [0.78, 0.8, 0.84], 0.54, [
+        light("studio-key", "key", "directional", [1, 0.95, 0.88], 1.8, undefined, [0.4, -0.7, -0.58], true),
+        light("studio-fill", "fill", "directional", [0.62, 0.72, 1], 0.7, undefined, [-0.5, -0.35, -0.8], false),
+        light("studio-rim", "rim", "directional", [1, 1, 1], 0.9, undefined, [0.12, -0.2, 0.97], false)
+      ], ["Studio product rig uses renderer light records, not CSS panel highlights."]);
+    case "warm-sunrise":
+      return makeRig(id, "Warm sunrise", 1.16, [0.9, 0.58, 0.32], 0.48, [
+        light("sunrise-key", "key", "directional", [1, 0.58, 0.28], 2.05, undefined, [0.62, -0.52, -0.58], true),
+        light("sunrise-fill", "fill", "ambient", [0.28, 0.36, 0.55], 0.32, undefined, undefined, false),
+        light("sunrise-rim", "rim", "directional", [1, 0.86, 0.52], 0.78, undefined, [-0.12, -0.28, 0.95], false)
+      ], ["Warm sunrise is an analytic renderer lighting preset."]);
+    case "cool-moonlit":
+      return makeRig(id, "Cool moonlit", 1.32, [0.2, 0.28, 0.48], 0.38, [
+        light("moon-key", "key", "directional", [0.48, 0.62, 1], 1.35, undefined, [0.24, -0.62, -0.74], true),
+        light("moon-fill", "fill", "ambient", [0.08, 0.12, 0.2], 0.24, undefined, undefined, false),
+        light("moon-rim", "rim", "directional", [0.62, 0.86, 1], 0.92, undefined, [-0.22, -0.14, 0.96], false)
+      ], ["Cool moonlit rig remains renderer-owned lighting evidence."]);
+    case "soft-key-fill-rim":
+      return makeRig(id, "Soft key fill rim", 1.12, [0.52, 0.58, 0.66], 0.45, [
+        light("soft-key", "key", "directional", [1, 0.92, 0.82], 1.55, undefined, [0.42, -0.62, -0.66], true),
+        light("soft-fill", "fill", "directional", [0.46, 0.58, 0.82], 0.46, undefined, [-0.46, -0.28, -0.84], false),
+        light("soft-rim", "rim", "directional", [0.7, 0.88, 1], 0.72, undefined, [0.08, -0.28, 0.96], false)
+      ], ["Soft three-point rig supplies key/fill/rim renderer lights."]);
+  }
+}
+
+function makeRig(
+  id: CinematicLightingRigId,
+  label: string,
+  exposure: number,
+  color: readonly [number, number, number],
+  intensity: number,
+  lights: readonly CinematicRuntimeLight[],
+  diagnostics: readonly string[]
+): Omit<CinematicLightingRig, "rendererOwnedEvidence"> {
+  return {
+    id,
+    label,
+    exposure,
+    toneMap: { operator: "filmic", whitePoint: id === "cool-moonlit" ? 1.05 : 1.22 },
+    environmentLighting: {
+      color,
+      intensity,
+      proceduralMap: {
+        skyColor: [color[0] * 0.9, color[1] * 0.95, Math.min(1, color[2] * 1.15)],
+        horizonColor: [Math.min(1, color[0] * 1.2), Math.min(1, color[1] * 1.1), color[2]],
+        groundColor: [0.04, 0.045, 0.05],
+        specularColor: [1, 0.95, 0.86],
+        intensity,
+        specularIntensity: Math.min(1, intensity + 0.28)
+      }
+    },
+    lights,
+    diagnostics
+  };
+}
+
+function light(
+  id: string,
+  role: CinematicLightRole,
+  type: CinematicLightType,
+  color: readonly [number, number, number],
+  intensity: number,
+  position: readonly [number, number, number] | undefined,
+  direction: readonly [number, number, number] | undefined,
+  castsShadow: boolean
+): CinematicRuntimeLight {
+  return { id, role, type, color, intensity, position, direction, castsShadow };
+}

package/src/cinematic/CinematicMaterialPresets.ts

@@ -0,0 +1,130 @@
+import { PBRMaterial, type PBRMaterialOptions } from "../PBRMaterial";
+import { createRendererOwnedEvidenceFlag, type CinematicRendererEvidenceFlag } from "./CinematicEvidence";
+
+export type CinematicMaterialPresetId =
+  | "wet-pavement"
+  | "neon-emissive"
+  | "hero-prop-glow"
+  | "rain-dark-metal"
+  | "cinematic-set-concrete";
+
+export interface CinematicMaterialPreset {
+  readonly id: CinematicMaterialPresetId;
+  readonly label: string;
+  readonly pbr: PBRMaterialOptions;
+  readonly rendererOwnedEvidence: CinematicRendererEvidenceFlag;
+  readonly approximatedFeatures: readonly string[];
+  readonly diagnostics: readonly string[];
+}
+
+const MATERIAL_PRESETS: Readonly<Record<CinematicMaterialPresetId, Omit<CinematicMaterialPreset, "rendererOwnedEvidence">>> = {
+  "wet-pavement": {
+    id: "wet-pavement",
+    label: "Wet pavement",
+    pbr: {
+      name: "cinematic/wet-pavement",
+      baseColor: [0.035, 0.04, 0.045, 1],
+      metallic: 0,
+      roughness: 0.18,
+      clearcoatFactor: 0.72,
+      clearcoatRoughnessFactor: 0.08,
+      environmentMapIntensity: 0.65,
+      environmentMapSpecularIntensity: 0.9
+    },
+    approximatedFeatures: ["screen-space puddle breakup is represented by glossy PBR response until a normal-map texture is bound"],
+    diagnostics: ["Wet pavement is renderer-owned PBR material data, not a CSS shine overlay."]
+  },
+  "neon-emissive": {
+    id: "neon-emissive",
+    label: "Neon emissive",
+    pbr: {
+      name: "cinematic/neon-emissive",
+      baseColor: [0.05, 0.78, 1, 1],
+      metallic: 0,
+      roughness: 0.22,
+      emissiveColor: [0.05, 0.78, 1],
+      emissiveStrength: 4.8
+    },
+    approximatedFeatures: [],
+    diagnostics: ["Neon proof is an emissive renderer material and can drive bloom/practical light evidence."]
+  },
+  "hero-prop-glow": {
+    id: "hero-prop-glow",
+    label: "Hero prop glow",
+    pbr: {
+      name: "cinematic/hero-prop-glow",
+      baseColor: [0.42, 0.95, 1, 1],
+      metallic: 0,
+      roughness: 0.28,
+      emissiveColor: [0.18, 0.82, 1],
+      emissiveStrength: 2.6,
+      clearcoatFactor: 0.25
+    },
+    approximatedFeatures: ["subsurface scattering is approximated with emissive PBR color"],
+    diagnostics: ["Hero prop glow is real material data and must not be replaced by a DOM halo."]
+  },
+  "rain-dark-metal": {
+    id: "rain-dark-metal",
+    label: "Rain dark metal",
+    pbr: {
+      name: "cinematic/rain-dark-metal",
+      baseColor: [0.32, 0.34, 0.36, 1],
+      metallic: 0.82,
+      roughness: 0.24,
+      clearcoatFactor: 0.48,
+      clearcoatRoughnessFactor: 0.12
+    },
+    approximatedFeatures: ["water beads require texture/normal detail from the route asset to be fully represented"],
+    diagnostics: ["Metal wetness is encoded as PBR parameters."]
+  },
+  "cinematic-set-concrete": {
+    id: "cinematic-set-concrete",
+    label: "Cinematic set concrete",
+    pbr: {
+      name: "cinematic/set-concrete",
+      baseColor: [0.23, 0.24, 0.25, 1],
+      metallic: 0,
+      roughness: 0.62,
+      environmentMapIntensity: 0.22,
+      environmentMapSpecularIntensity: 0.32
+    },
+    approximatedFeatures: [],
+    diagnostics: ["Set material is renderer-owned PBR scene content."]
+  }
+};
+
+export function listCinematicMaterialPresets(): readonly CinematicMaterialPreset[] {
+  return (Object.keys(MATERIAL_PRESETS) as CinematicMaterialPresetId[]).map(createCinematicMaterialPreset);
+}
+
+export function createCinematicMaterialPreset(id: CinematicMaterialPresetId): CinematicMaterialPreset {
+  const preset = MATERIAL_PRESETS[id];
+  return {
+    ...preset,
+    rendererOwnedEvidence: createRendererOwnedEvidenceFlag({
+      id: `material:${id}`,
+      feature: "material",
+      label: preset.label,
+      source: "renderer-material",
+      diagnostics: preset.diagnostics
+    })
+  };
+}
+
+export function createCinematicPBRMaterial(id: CinematicMaterialPresetId, overrides: PBRMaterialOptions = {}): PBRMaterial {
+  const preset = createCinematicMaterialPreset(id);
+  return new PBRMaterial({
+    ...preset.pbr,
+    ...overrides,
+    name: overrides.name ?? preset.pbr.name
+  });
+}
+
+export function resolveCinematicMaterialPresetId(tags: readonly string[]): CinematicMaterialPresetId {
+  const lower = tags.map((tag) => tag.toLowerCase());
+  if (lower.some((tag) => tag.includes("neon") || tag.includes("emissive"))) return "neon-emissive";
+  if (lower.some((tag) => tag.includes("flower") || tag.includes("hero") || tag.includes("glow"))) return "hero-prop-glow";
+  if (lower.some((tag) => tag.includes("metal") || tag.includes("robot"))) return "rain-dark-metal";
+  if (lower.some((tag) => tag.includes("wet") || tag.includes("pavement") || tag.includes("rain"))) return "wet-pavement";
+  return "cinematic-set-concrete";
+}