Babylon Lite — Architecture Specification (One-Shot Document)

babylon-lite/
├── GUIDANCE.md                    # Immutable core pillars & workflow (anti-amnesia)
├── package.json                   # pnpm workspace root
├── pnpm-workspace.yaml            # packages: [packages/*, apps/*]
├── tsconfig.base.json             # Shared TS config
├── vitest.config.ts               # Root test config
│
├── packages/babylon-lite/         # The engine library
│   ├── package.json               # name: "babylon-lite", type: "module"
│   ├── tsconfig.json              # extends ../../tsconfig.base.json
│   ├── vite.config.ts             # lib mode build
│   ├── src/
│   │   ├── index.ts               # Public API barrel (tree-shakable)
│   │   ├── vite-env.d.ts          # Declares ?raw WGSL imports
│   │   ├── math/                   # Math primitives
│   │   │   ├── types.ts           # Vec3, Vec4, Color3, Color4, Mat4, Quat
│   │   │   ├── vec3.ts            # Pure Vec3 functions
│   │   │   ├── mat4.ts            # Pure Mat4 functions (LH, column-major)
│   │   │   ├── observable-vec3.ts # ObservableVec3 (reactive position/target)
│   │   │   ├── observable-quat.ts # ObservableQuat (reactive rotation)
│   │   │   └── index.ts           # Math barrel
│   │   ├── engine/
│   │   │   └── engine.ts          # createEngine(), GPUDevice, swapchain, render loop
│   │   ├── scene/
│   │   │   ├── scene.ts           # createSceneContext(), flat data struct, add()
│   │   │   ├── scene-core.ts      # Core scene logic
│   │   │   ├── scene-camera.ts    # Camera management
│   │   │   ├── scene-remove.ts    # removeFromScene()
│   │   │   ├── set-parent.ts      # setParent() — parent/child transforms
│   │   │   ├── parentable.ts      # IWorldMatrixProvider, IParentable interfaces
│   │   │   ├── transform-node.ts  # TransformNode — hierarchy node without mesh
│   │   │   └── world-matrix-state.ts # Version-based world matrix propagation
│   │   ├── camera/
│   │   │   ├── camera.ts          # Camera interface
│   │   │   ├── arc-rotate.ts      # createArcRotateCamera(), ArcRotateCamera
│   │   │   ├── arc-rotate-controls.ts  # attachControl() for orbit
│   │   │   ├── free-camera.ts     # createFreeCamera(), FreeCamera
│   │   │   └── free-camera-controls.ts # attachFreeControl() for WASD/arrow
│   │   ├── light/
│   │   │   ├── light-base.ts      # Shared light base
│   │   │   ├── types.ts           # LightBase type, LightBaseInternal, MAX_LIGHTS
│   │   │   ├── light-matrix.ts    # Light view-projection for shadows
│   │   │   ├── hemispheric.ts     # createHemisphericLight()
│   │   │   ├── point-light.ts     # createPointLight()
│   │   │   ├── directional-light.ts # createDirectionalLight()
│   │   │   └── spot-light.ts      # createSpotLight()
│   │   ├── material/
│   │   │   ├── material.ts          # Shared Material / MaterialView interfaces
│   │   │   ├── material-view.ts     # createMaterialView(), source normalization
│   │   │   ├── material-dirty.ts    # markMaterialUboDirty()
│   │   │   ├── material-rebuild.ts  # rebuildMaterial()
│   │   │   ├── pbr/               # PBR metallic-roughness material
│   │   │   │   ├── pbr-material.ts      # PbrMaterialProps + createPbrMaterial()
│   │   │   │   ├── pbr-template.ts      # PBR shader template (WGSL generation)
│   │   │   │   ├── pbr-flags.ts         # PBR feature flag bitmask
│   │   │   │   ├── pbr-pipeline.ts      # Pipeline cache + feature flags
│   │   │   │   ├── pbr-renderable.ts    # buildPbrRenderables() + single-mesh rebuild closure
│   │   │   │   ├── no-color-view.ts # PBR no-color MaterialView helper
│   │   │   │   ├── fragments/singlelight-wgsl.ts # Non-looping one-light WGSL
│   │   │   │   ├── fragments/multilight-wgsl.ts  # Generic multi-light WGSL
│   │   │   │   ├── background-material.ts    # Skybox + Ground material factories
│   │   │   │   ├── background-renderable.ts  # Skybox + Ground → Renderables
│   │   │   │   ├── background-dds-skybox.ts  # DDS environment skybox
│   │   │   │   ├── background-hdr-skybox.ts  # HDR environment skybox
│   │   │   │   ├── background-ground.ts      # Background ground plane
│   │   │   │   └── fragments/          # PBR ShaderFragment modules
│   │   │   │       ├── clearcoat-fragment.ts
│   │   │   │       ├── emissive-fragment.ts
│   │   │   │       ├── ibl-fragment.ts
│   │   │   │       ├── morph-fragment.ts
│   │   │   │       ├── pbr-shadow-fragment.ts
│   │   │   │       ├── reflectance-fragment.ts
│   │   │   │       ├── sheen-fragment.ts
│   │   │   │       └── skeleton-fragment.ts
│   │   │   └── standard/          # Standard Blinn-Phong material
│   │   │       ├── standard-material.ts    # Types, factory, texture collection
│   │   │       ├── standard-group-builder.ts # Dynamic imports + group builder
│   │   │       ├── standard-template.ts    # Standard shader template (WGSL generation)
│   │   │       ├── standard-pipeline.ts    # Pipeline cache + feature flags
│   │   │       ├── standard-renderable.ts  # buildStandardMeshRenderables() + single-mesh rebuild closure
│   │   │       ├── no-color-view.ts # Standard no-color MaterialView helper
│   │   │       ├── skybox-cubemap.ts       # CubeMap skybox for StandardMaterial scenes
│   │   │       └── fragments/             # Standard ShaderFragment modules
│   │   │           ├── normal-map-fragment.ts
│   │   │           ├── std-ambient-fragment.ts
│   │   │           ├── std-emissive-fragment.ts
│   │   │           ├── std-lightmap-fragment.ts
│   │   │           ├── std-opacity-fragment.ts
│   │   │           ├── std-reflection-fragment.ts
│   │   │           ├── std-shadow-fragment.ts
│   │   │           └── std-specular-fragment.ts
│   │   ├── grid/                  # Procedural grid material
│   │   │   └── grid-material.ts   # createGridMaterial() + GridMaterialOptions (on ShaderMaterial)
│   │   ├── shader/                # Shader composition system
│   │   │   ├── shader-composer.ts # ShaderFragment composer engine
│   │   │   ├── fragment-types.ts  # ShaderFragment interface definitions
│   │   │   ├── ubo-layout.ts     # UBO layout helpers
│   │   │   ├── wgsl-helpers.ts   # WGSL code-gen utilities
│   │   │   └── fragments/        # Shared shader fragments
│   │   │       └── thin-instance-fragment.ts
│   │   ├── render/
│   │   │   ├── renderable.ts      # Renderable, PrePassRenderable, SceneUniformUpdater
│   │   │   ├── scene-helpers.ts   # Shared helper utilities
│   │   │   └── lights-ubo.ts     # Multi-light UBO packing
│   │   ├── effect/
│   │   │   └── effect-renderer.ts # EffectWrapper fullscreen passes + RenderTarget output
│   │   ├── mesh/
│   │   │   ├── mesh.ts            # Mesh type and GPU upload
│   │   │   ├── mesh-factories.ts  # High-level createSphere/Box/Torus/Ground/Cylinder/Plane/Disc/Polyhedron/Ribbon/Tube/Extrude
│   │   │   ├── path3d.ts          # Path3D parallel-transport frames (used by tube/extrude)
│   │   │   ├── thin-instance.ts   # Thin instance CPU data model + public API
│   │   │   ├── thin-instance-gpu.ts # GPU buffer sync (lazy-loaded by renderable)
│   │   │   ├── create-sphere.ts   # Sphere geometry generator
│   │   │   ├── create-box.ts      # Box geometry generator
│   │   │   ├── create-torus.ts    # Torus geometry generator
│   │   │   └── create-ground.ts   # Ground/heightmap geometry generator
│   │   ├── skeleton/
│   │   │   ├── create-skeleton.ts   # Skeleton data creation from glTF
│   │   │   └── skeleton-updater.ts  # Joint matrix computation for skinned meshes
│   │   ├── animation/
│   │   │   ├── animation-manager.ts   # Generic AnimationTask scheduler
│   │   │   ├── animation-group.ts     # AnimationGroup state and playback helpers
│   │   │   ├── animation-group-task.ts # AnimationGroup → AnimationTask adapter
│   │   │   ├── property-animation.ts  # User-authored property animation clips
│   │   │   ├── evaluate.ts           # Keyframe interpolation (step, linear, cubic)
│   │   │   └── types.ts              # Animation type definitions
│   │   ├── morph/
│   │   │   └── create-morph-targets.ts # Morph target data + GPU texture
│   │   ├── picking/
│   │   │   ├── gpu-picker.ts        # createGpuPicker() — GPU ID-pass picking
│   │   │   ├── picking-pipeline.ts  # Picking render pipeline
│   │   │   ├── picking-shader.ts    # Picking WGSL shaders
│   │   │   ├── picking-helpers.ts   # getPickedNormal(), getPickedUV()
│   │   │   ├── picking-info.ts      # PickingInfo type
│   │   │   ├── detailed-picking.ts  # enableDetailedPicking() — CPU ray/triangle
│   │   │   └── ray.ts              # Ray intersection math
│   │   ├── resource/
│   │   │   └── gpu-pool.ts         # GPU buffer/texture pooling
│   │   ├── shadow/
│   │   │   ├── shadow-base.ts       # Shared shadow logic
│   │   │   ├── shadow-generator.ts  # ShadowGenerator contract
│   │   │   ├── esm-directional-shadow-generator.ts # Directional ESM shadow generator
│   │   │   ├── pcf-spotlight-shadow-generator.ts # Spot PCF shadow generator
│   │   │   └── pcf-directional-shadow-generator.ts # Directional PCF shadow generator
│   │   ├── frame-graph/
│   │   │   ├── task.ts              # Frame-graph task interface
│   │   │   ├── frame-graph.ts       # Ordered task list
│   │   │   ├── frame-graph-actions.ts # addTask helpers
│   │   │   └── render-task.ts  # Render-pass task + per-pass scene UBO
│   │   ├── texture/
│   │   │   ├── texture-2d.ts      # 2D texture loader
│   │   │   ├── solid-texture.ts   # 1×1 solid-color texture factory
│   │   │   ├── cube-texture.ts    # 6-face cube texture loader
│   │   │   ├── rtt.ts             # Eager render-target texture helper
│   │   │   ├── ktx2-loader.ts      # KTX2/BasisU upload for KHR_texture_basisu
│   │   │   ├── mip-count.ts        # Biased mip-count helper
│   │   │   └── generate-mipmaps.ts # GPU mipmap generation
│   │   ├── loader-gltf/
│   │   │   ├── load-gltf.ts       # GLB parser, GPU upload
│   │   │   ├── gltf-parser.ts     # glTF JSON parsing helpers
│   │   │   ├── gltf-material.ts   # glTF material → PbrMaterialProps
│   │   │   ├── gltf-ext-basisu.ts # KHR_texture_basisu dynamic feature
│   │   │   ├── gltf-interleave.ts # native interleaved VB support (lazy de-stride)
│   │   │   ├── gltf-feature-meshopt.ts # EXT_meshopt_compression dynamic feature
│   │   │   ├── gltf-ext-quantization.ts # KHR_mesh_quantization dynamic feature
│   │   │   ├── gltf-feature-xmp.ts # KHR_xmp_json_ld metadata dynamic feature
│   │   │   └── gltf-animation.ts  # glTF animation extraction
│   │   ├── loader-env/
│   │   │   ├── load-env.ts        # .env parser, RGBD decode, cubemap upload
│   │   │   ├── load-dds-env.ts    # DDS environment loading
│   │   │   ├── env-helpers.ts     # Environment helper utilities
│   │   │   └── rgbd-decode.ts     # RGBD decode helpers
│   │   ├── loader-hdr/
│   │   │   ├── load-hdr.ts        # loadHdrEnvironment() — HDR environment pipeline
│   │   │   ├── hdr-parser.ts      # RGBE file parser
│   │   │   └── hdr-ibl-pipeline.ts # GPU compute IBL from HDR
│   │   ├── loader-babylon/
│   │   │   └── load-babylon.ts    # loadBabylon() — .babylon format parser
│   │   └── loader-skybox/
│   │       ├── load-skybox.ts     # High-level skybox loader
│   │       └── skybox-renderable.ts # Skybox → deferred Renderable builder
│
├── lab/               # Dev sandbox (Scenes 1–175)
│   ├── index.html
│   ├── src/lite/scene1.ts          # Scene 1: BoomBox PBR
│   ├── src/lite/scene2.ts          # Scene 2: Sphere + DirectionalLight
│   ├── ...                         # Scenes 3–175
│   ├── src/lite/scene74.ts         # Scene 74: EffectRenderer fullscreen pass
│   ├── src/lite/scene75.ts         # Scene 75: EffectWrapper render-to-texture sphere
│   ├── src/lite/scene76.ts         # Scene 76: EffectWrapper texture binding
│   ├── src/lite/scene112.ts        # Scene 112: FlightHelmetKTX / KHR_texture_basisu
│   ├── src/lite/scene120.ts        # Scene 120: Gaussian splatting
│   ├── src/lite/scene159.ts        # Scene 159: ShaderMaterial basic
│   ├── src/lite/scene164.ts        # Scene 164: device-loss recovery
│   ├── src/lite/scene175.ts        # Scene 175: navigation raycast
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
│
├── reference/lite/                     # Per-scene reference data
│   ├── scene1-boombox/            # Scene 1 reference data
│   ├── scene2-sphere/             # Scene 2 reference data
│   ├── ...                        # Scenes 3–175
│   ├── scene74-effect-renderer/   # EffectRenderer fullscreen golden
│   ├── scene75-effect-rtt-sphere/ # EffectWrapper RTT golden
│   ├── scene76-effect-texture/    # EffectWrapper texture-binding golden
│   ├── scene112-khr-texture-basisu/ # KHR_texture_basisu golden
│   ├── scene120-gaussian-splatting/ # Gaussian splatting golden
│   ├── scene164-device-lost-recovery/ # Device-loss recovery golden
│   ├── scene175-navigation-raycast/ # Navigation raycast golden
│   └── (each contains golden screenshots for parity tests)
│
└── docs/lite/architecture/
    └── 00-overview.md             # THIS FILE

// Engine lifecycle
createEngine(canvas: HTMLCanvasElement): Promise<Engine>

// Scene
createSceneContext(engine: Engine): SceneContext
createDefaultCamera(scene: SceneContext): ArcRotateCamera
removeFromScene(scene: SceneContext, entity: Mesh | ...): void
setEnvironmentRotation(scene: SceneContext, rotation: number): void

// Camera — pure data; controls can register per-frame updates on a scene
createArcRotateCamera(alpha: number, beta: number, radius: number, target: Vec3): ArcRotateCamera
attachControl(camera: ArcRotateCamera, canvas: HTMLCanvasElement, scene?: SceneContext, options?: AttachControlOptions): () => void
createFreeCamera(position: Vec3, target: Vec3): FreeCamera
attachFreeControl(camera: FreeCamera, canvas: HTMLCanvasElement, scene?: SceneContext): () => void

// Loaders — note: loadGltf and loadBabylon take Engine, not SceneContext
loadGltf(engine: Engine, source: string | ArrayBuffer | Blob): Promise<AssetContainer>
loadEnvironment(scene: SceneContext, url: string, options: {
    brdfUrl: string;
    groundTextureUrl?: string;
    skipSkybox?: boolean;
    skipGround?: boolean;
    skyboxUrl?: string;
    skyboxSize?: number;
}): Promise<EnvironmentTextures>
loadHdrEnvironment(scene: SceneContext, url: string, options?: HdrLoadOptions): Promise<EnvironmentTextures>
loadBabylon(engine: Engine, url: string, opts?: LoadBabylonOptions): Promise<AssetContainer>
loadTexture2D(engine: Engine, url: string, options?: Texture2DOptions): Promise<Texture2D>
loadSkybox(scene: SceneContext, baseUrl: string, ext: string, size?: number): Promise<void>

// Texture factories
createSolidTexture2D(engine: Engine, r: number, g: number, b: number, a?: number): Texture2D

// EffectRenderer-style fullscreen passes
createEffectWrapper(engine: Engine, options: EffectWrapperOptions): EffectWrapper
setEffectUniforms(wrapper: EffectWrapper, data: ArrayBuffer | ArrayBufferView | Record<string | number, ArrayBuffer | ArrayBufferView>): void
setEffectTexture(wrapper: EffectWrapper, bindingNameOrIndex: string | number, texture: Texture2D): void
createEffectRenderer(engine: Engine, effect: EffectWrapper, options?: EffectRendererOptions): EffectRenderer
registerEffectRenderer(renderer: EffectRenderer): void
unregisterEffectRenderer(renderer: EffectRenderer): void
disposeEffectRenderer(renderer: EffectRenderer): void
createEffectRenderTask(config: EffectRenderTaskConfig, engine: Engine, scene: SceneContext): EffectRenderTask
disposeEffectWrapper(wrapper: EffectWrapper): void
createUniformEffectWrapper(engine: Engine, options: UniformEffectWrapperOptions): UniformEffectWrapper
setUniformEffectUniforms(wrapper: UniformEffectWrapper, data: ArrayBuffer | ArrayBufferView): void
createUniformEffectRenderTask(config: UniformEffectRenderTaskConfig, engine: Engine, scene?: SceneContext): UniformEffectRenderTask
disposeUniformEffectWrapper(wrapper: UniformEffectWrapper): void

// Lights
createHemisphericLight(direction?: [number,number,number], intensity?: number): HemisphericLight
createPointLight(position: [number,number,number], intensity?: number): PointLight
createDirectionalLight(direction: [number,number,number], intensity?: number): DirectionalLight
createSpotLight(
    position: [number,number,number],
    direction: [number,number,number],
    angle: number,
    exponent: number,
    intensity?: number,
): SpotLight

// Mesh factories
createSphere(engine: Engine, options?: SphereOptions): Mesh
createBox(engine: Engine, size?: number): Mesh
createTorus(engine: Engine, options?: TorusOptions): Mesh
createCylinder(engine: Engine, options?: CylinderOptions): Mesh
createPlane(engine: Engine, options?: PlaneOptions): Mesh
createDisc(engine: Engine, options?: DiscOptions): Mesh
createPolyhedron(engine: Engine, options?: PolyhedronOptions): Mesh
createRibbon(engine: Engine, options: RibbonOptions): Mesh
createTube(engine: Engine, options: TubeOptions): Mesh
createExtrudeShape(engine: Engine, options: ExtrudeShapeOptions): Mesh
createGround(engine: Engine, options?: GroundOptions): Mesh
createGroundFromHeightMap(engine: Engine, url: string, options: GroundOptions): Promise<Mesh>
getMeshGeometry(mesh: Mesh): {
    positions: Float32Array;
    normals: Float32Array;
    indices: Uint32Array;
    uvs?: Float32Array;
    uvs2?: Float32Array;
    tangents?: Float32Array;
    colors?: Float32Array;
} | null

// Materials
createStandardMaterial(): StandardMaterialProps
createPbrMaterial(props?: Partial<PbrMaterialProps>): PbrMaterialProps

// Shadows — generators own GPU resources; caster lists are ShadowTask inputs
registerSceneWithShadowSupport(engine: Engine, scene: SceneContext): Promise<void>
createEsmDirectionalShadowGenerator(engine: Engine, light: DirectionalLight, config?: EsmDirectionalShadowGeneratorConfig): ShadowGenerator
createPcfSpotlightShadowGenerator(engine: Engine, light: SpotLight, config?: PcfSpotlightShadowGeneratorConfig): ShadowGenerator
createPcfDirectionalShadowGenerator(engine: Engine, light: DirectionalLight, config?: PcfDirectionalShadowGeneratorConfig): ShadowGenerator
setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void
setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void

// Animation
createAnimationController(skeleton, scene): AnimationController
createAnimationGroups(gltfData, meshes, scene): AnimationGroup[]
goToFrame(group: AnimationGroup, frame: number, engine?: EngineContext): void

// Hierarchy
setParent(child: IParentable, parent: IWorldMatrixProvider | null, scene: SceneContext): void
createTransformNode(name: string, scene: SceneContext): TransformNode
cloneTransformNode(node: TransformNode, scene: SceneContext): TransformNode
collectMeshes(node: TransformNode): Mesh[]

// Math
createTranslationMat4(x: number, y: number, z: number): Mat4
createIdentityMat4(): Mat4
createScalingMat4(sx: number, sy: number, sz: number): Mat4
composeMat4(tx,ty,tz, qx,qy,qz,qw, sx,sy,sz): Mat4

// Thin Instances
addThinInstance(mesh: Mesh, matrix: Mat4): number
removeThinInstance(mesh: Mesh, index: number): void
setThinInstanceMatrix(mesh: Mesh, index: number, matrix: Mat4): void
setThinInstances(mesh: Mesh, matrices: Mat4[]): void
flushThinInstances(mesh: Mesh): void
setThinInstanceColors(mesh: Mesh, colors: Float32Array): void

// Picking
createGpuPicker(engine: Engine, scene: SceneContext): GpuPicker
enableDetailedPicking(mesh: Mesh): void
getPickedNormal(info: PickingInfo): Vec3
getPickedUV(info: PickingInfo): [number, number]

// ─── Engine ──────────────────────────────────────────────────────────
// Note: GPU internals (device, context, format) are @internal and not exposed.
interface EngineContext {
    readonly canvas: HTMLCanvasElement;
    readonly msaaSamples: number; // always 4
    drawCallCount: number; // GPU draw calls in latest renderFrame call, across its selected surfaces
}

// ─── Scene ───────────────────────────────────────────────────────────
interface SceneContext {
    readonly engine: Engine;
    clearColor: GPUColorDict;
    camera: ArcRotateCamera | FreeCamera | null;
    lights: LightBase[]; // All light types (HemisphericLight, PointLight, etc.)
    meshes: Mesh[];
    animationGroups: AnimationGroup[];
    fog: FogConfig | null;
    shadowGenerators: ShadowGenerator[];
    imageProcessing: ImageProcessingConfig;
    environmentPrimaryColor?: [number, number, number];
    fixedDeltaMs: number; // Fixed delta for deterministic animation (0 = real time)

    // Internal renderable lists
    _renderables: Renderable[];
    _opaqueRenderables: Renderable[];
    _transparentRenderables: Renderable[];
    _prePasses: PrePassRenderable[];
    _uniformUpdaters: SceneUniformUpdater[];
    _fixedDeltaMs: number;
    _beforeRender: ((deltaMs: number) => void)[];
    _deferredBuilders: (() => void | Promise<void>)[];
}

// ─── Cameras ─────────────────────────────────────────────────────────
interface ArcRotateCamera {
    alpha: number; // Horizontal rotation (azimuth)
    beta: number; // Vertical angle from top pole (0=top, π=bottom)
    radius: number; // Distance from target
    target: Vec3; // Look-at point (ObservableVec3 at runtime)
    fov: number; // Vertical FOV in radians
    nearPlane: number; // Near clip plane
    farPlane: number; // Far clip plane
    inertia: number; // Rotation + zoom inertia (0=instant, 0.9=default)
    panningInertia: number; // Panning inertia
    inertialAlphaOffset: number;
    inertialBetaOffset: number;
    inertialRadiusOffset: number;
    inertialPanningX: number;
    inertialPanningY: number;
}

interface FreeCamera {
    position: ObservableVec3; // Camera world position
    target: ObservableVec3; // Look-at target
    speed: number; // Movement speed (default 2.0, matches BJS)
    angularSensitivity: number; // Mouse rotation sensitivity (default 2000)
    inertia: number; // Damping factor (0=instant, 0.9=default)
    fov: number;
    nearPlane: number;
    farPlane: number;
}

interface Camera {
    /* Union: ArcRotateCamera | FreeCamera */
}

function getViewMatrix(camera: Camera): Mat4;
function getProjectionMatrix(camera: Camera, aspectRatio: number): Mat4;
function getViewProjectionMatrix(camera: Camera, aspectRatio: number): Mat4;
function getCameraPosition(camera: Camera): Vec3;

// ─── Lights ──────────────────────────────────────────────────────────
interface LightBase {
    readonly lightType: string;
    intensity: number;
    excludedMeshIds?: ReadonlySet<string>;
    includedOnlyMeshIds?: ReadonlySet<string>;
    shadowGenerator?: ShadowGenerator;
    parent: IWorldMatrixProvider | null;
    readonly worldMatrix: Mat4;
    readonly worldMatrixVersion: number;
}

interface HemisphericLight extends LightBase {
    readonly lightType: "hemispheric";
    direction: ObservableVec3;
    intensity: number;
    diffuseColor: [number, number, number];
    specularColor: [number, number, number];
    groundColor: [number, number, number];
}

interface PointLight extends LightBase {
    readonly lightType: "point";
    position: ObservableVec3;
    diffuse: [number, number, number];
    specular: [number, number, number];
    intensity: number;
    range: number;
}

interface DirectionalLight extends LightBase {
    readonly lightType: "directional";
    direction: ObservableVec3;
    position: ObservableVec3;
    diffuse: [number, number, number];
    specular: [number, number, number];
    intensity: number;
}

interface SpotLight extends LightBase {
    readonly lightType: "spot";
    position: ObservableVec3;
    direction: ObservableVec3;
    angle: number;
    exponent: number;
    diffuse: [number, number, number];
    specular: [number, number, number];
    intensity: number;
    range: number;
}

// ─── Materials ───────────────────────────────────────────────────────
interface PbrMaterialProps {
    baseColorTexture?: Texture2D;
    normalTexture?: Texture2D;
    ormTexture?: Texture2D; // R=occ, G=rough, B=metal
    emissiveTexture?: Texture2D;
    _emissiveColor?: [number, number, number]; // Linear RGB emissive — set via setPbrEmissive()
    specGlossTexture?: Texture2D; // KHR_materials_pbrSpecularGlossiness
    doubleSided?: boolean;
    alpha?: number; // Overall material alpha (default 1.0)
    alphaBlend?: boolean; // Enable alpha blending (glTF BLEND)
    environmentIntensity?: number; // IBL contribution scale (default 1.0)
    directIntensity?: number; // Direct light contribution scale (default 1.0)
    usePhysicalLightFalloff?: boolean; // Direct point/spot inverse-square falloff (default true)
    reflectance?: number; // Dielectric F0 (default 0.04)
    occlusionStrength?: number; // AO strength from ORM R channel (default 1.0)
    metallicF0Factor?: number; // Dielectric F0 scale (default 1.0)
    metallicReflectanceColor?: [number, number, number]; // Tints dielectric reflectance (default [1,1,1])
    metallicReflectanceTexture?: Texture2D; // RGB=reflectance tint, A=F0 scalar
    reflectanceTexture?: Texture2D; // RGB=reflectance tint only
    useOnlyMetallicFromMetallicReflectanceTexture?: boolean;
    enableSpecularAA?: boolean; // Specular anti-aliasing on IBL alphaG
    gammaAlbedo?: boolean; // Apply pow(2.2) sRGB→linear in shader
    clearCoat?: ClearCoatProps;
    sheen?: SheenProps;
}

interface ClearCoatProps {
    isEnabled?: boolean;
    intensity?: number;
    roughness?: number;
    indexOfRefraction?: number; // Default 1.5
}

interface SheenProps {
    isEnabled: boolean;
    color?: [number, number, number];
    roughness?: number;
    intensity?: number;
    texture?: Texture2D; // Sheen tint texture (modulates color)
}

interface StandardMaterialProps {
    diffuseColor: [number, number, number];
    alpha: number;
    specularColor: [number, number, number];
    specularPower: number;
    emissiveColor: [number, number, number];
    ambientColor: [number, number, number];
    diffuseTexture: Texture2D | null;
    diffuseCoordIndex: 0 | 1;
    _emissiveTexture?: Texture2D | null; // set via setStandardEmissiveTexture()
    _bumpTexture?: Texture2D | null; // set via setStandardBumpTexture()
    bumpLevel: number;
    _specularTexture?: Texture2D | null; // set via setStandardSpecularTexture()
    specularCoordIndex: 0 | 1;
    _ambientTexture?: Texture2D | null; // set via setStandardAmbientTexture()
    ambientTexLevel: number;
    ambientCoordIndex: 0 | 1;
    _lightmapTexture?: Texture2D | null; // set via setStandardLightmapTexture()
    lightmapLevel: number;
    lightmapCoordIndex: 0 | 1;
    _opacityTexture?: Texture2D | null; // set via setStandardOpacityTexture()
    opacityLevel: number;
    opacityFromRGB: boolean;
    alphaCutOff: number;
    _reflectionTexture?: Texture2D | null; // set via setStandardReflectionTexture()
    _reflectionCubeTexture?: CubeTexture | null; // set via setStandardReflectionCubeTexture()
    reflectionLevel: number;
    reflectionCoordMode: 1 | 2;
    uvScale: [number, number];
    backFaceCulling: boolean;
    disableLighting: boolean;
}

interface FogConfig {
    mode: 0 | 1 | 2 | 3; // 0=off, 1=exp, 2=exp2, 3=linear (matches BJS Scene.FOGMODE_*)
    density: number;
    start: number;
    end: number;
    color: [number, number, number];
}

interface ImageProcessingConfig {
    exposure: number;
    contrast: number;
    toneMappingEnabled: boolean;
}

// ─── Mesh ────────────────────────────────────────────────────────────
interface Mesh {
    boundMin?: Vec3;
    boundMax?: Vec3;
    name?: string;
    material: StandardMaterialProps | PbrMaterialProps | null;
    receiveShadows: boolean;
}
interface MeshGPU {
    /* internal GPU state */
}

// ─── Textures ────────────────────────────────────────────────────────
interface Texture2D {
    texture: GPUTexture;
    view: GPUTextureView;
    sampler: GPUSampler;
    width: number;
    height: number;
}
interface Texture2DOptions {
    mipMaps?: boolean; // Generate mipmaps (default true)
    addressModeU?: GPUAddressMode; // Default 'repeat'
    addressModeV?: GPUAddressMode; // Default 'repeat'
    minFilter?: GPUFilterMode; // Default 'linear'
    magFilter?: GPUFilterMode; // Default 'linear'
    invertY?: boolean; // Flip Y axis (default true, matches BJS)
    srgb?: boolean; // Use rgba8unorm-srgb format (default false)
}

// ─── Shadows ─────────────────────────────────────────────────────────
interface ShadowGenerator {
    _shadowType: "esm" | "pcf";
    _light: LightBase;
    _config: ShadowGeneratorRuntimeConfig;
}
interface EsmDirectionalShadowGeneratorConfig {
    mapSize?: number; // Shadow map size (default 1024)
    depthScale?: number; // ESM depth exponent scale (default 50)
    bias?: number; // Shadow bias (default 0.00005)
    blurScale?: number; // Gaussian blur downscale factor (default 2)
    darkness?: number; // Shadow darkness 0–1 (default 0 = full black)
    frustumEdgeFalloff?: number;
    orthoMinZ?: number; // Ortho projection near Z (default 1)
    orthoMaxZ?: number; // Ortho projection far Z (default 10000)
    forceRefreshEveryFrame?: boolean;
}
interface PcfSpotlightShadowGeneratorConfig {
    mapSize?: number; // Shadow map size (default 512)
    bias?: number;
    darkness?: number;
    normalBias?: number;
    near?: number; // Near plane for shadow projection
    far?: number; // Far plane for shadow projection
    forceRefreshEveryFrame?: boolean;
}
interface PcfDirectionalShadowGeneratorConfig {
    mapSize?: number; // Shadow map size (default 1024)
    bias?: number;
    darkness?: number;
    normalBias?: number;
    orthoMinZ?: number; // Ortho projection near Z (default 1)
    orthoMaxZ?: number; // Ortho projection far Z (default 10000)
    forceRefreshEveryFrame?: boolean;
}

// ─── Loaders ─────────────────────────────────────────────────────────
// Unified result returned by both loadGltf() and loadBabylon()
interface AssetContainer {
    // glTF: [root TransformNode]. .babylon: flat [...meshes, ...lights]
    entities: Array<Mesh | TransformNode | LightBase>;
    animationGroups?: AnimationGroup[]; // auto-ticked by addToScene()
    clearColor?: GPUColorDict; // applied to scene.clearColor by addToScene()
}

interface EnvironmentTextures {
    specularCube: GPUTexture;
    specularCubeView: GPUTextureView;
    brdfLut: GPUTexture;
    brdfLutView: GPUTextureView;
    cubeSampler: GPUSampler;
    brdfSampler: GPUSampler;
    irradianceSH: Float32Array; // 27 floats (9 vec3 SH coefficients)
    sphericalHarmonics: {
        // Pre-scaled SH bands for shader (L00…L22)
        l00: Float32Array;
        l1_1: Float32Array;
        l10: Float32Array;
        l11: Float32Array;
        l2_2: Float32Array;
        l2_1: Float32Array;
        l20: Float32Array;
        l21: Float32Array;
        l22: Float32Array;
    };
    lodGenerationScale: number; // LOD scale for specular IBL sampling (default 0.8)
}

interface HdrLoadOptions {
    faceSize?: number; // Cubemap face size in pixels (default 256)
    useCubemapSkybox?: boolean; // Render HDR cubemap as skybox background
    skipGround?: boolean; // Skip the background ground plane
    skyboxSize?: number; // Skybox mesh size (matches BJS skyboxSize)
}

// ─── Animation ───────────────────────────────────────────────────────
interface AnimationController {
    update(deltaMs: number): void;
}
interface AnimationGroup {
    name: string;
    duration: number; // seconds
    currentTime: number; // seconds
    targetedAnimations: readonly TargetedAnimation[];
    isPlaying: boolean;
    speedRatio: number;
    loopAnimation: boolean;
    weight: number;
}
interface TargetedAnimation {
    target?: object;
    targetName?: string;
    nodeIndex?: number;
    path: string;
}
interface AnimationClip {
    /* keyframe data */
}
interface GltfAnimationData {
    /* parsed glTF animation channels */
}

// ─── Hierarchy ───────────────────────────────────────────────────────
interface TransformNode {
    name: string;
    position: ObservableVec3;
    rotation: ObservableQuat;
    scaling: ObservableVec3;
}
interface IWorldMatrixProvider {
    getWorldMatrix(): Mat4;
}
interface IParentable extends IWorldMatrixProvider {
    parent: IWorldMatrixProvider | null;
}

// ─── Thin Instances ──────────────────────────────────────────────────
interface ThinInstanceData {
    matrices: Mat4[];
    colors?: Float32Array;
}

// ─── Math ────────────────────────────────────────────────────────────
class ObservableVec3 {
    x: number;
    y: number;
    z: number;
}
class ObservableQuat {
    x: number;
    y: number;
    z: number;
    w: number;
}

// ─── Picking ─────────────────────────────────────────────────────────
interface GpuPicker {
    pick(x: number, y: number): Promise<PickingInfo | null>;
}
interface PickingInfo {
    mesh: Mesh;
    faceId: number;
    worldPosition: Vec3;
}

// ─── Low-level (advanced/custom rendering) ───────────────────────────
interface DrawUpdateContext {
    targetWidth: number;
    targetHeight: number;
    _camera?: Camera | null;
}
interface Renderable {
    order: number;
    isTransparent: boolean;
    _transmissive?: boolean;
    _direct?: boolean;
    bind(engine: Engine, target: RenderTargetSignature): DrawBinding;
}
interface DrawBinding {
    pipeline: GPURenderPipeline;
    update?(context: DrawUpdateContext): void;
    draw(pass: GPURenderPassEncoder | GPURenderBundleEncoder, engine: Engine): number;
}
interface PrePassRenderable {
    execute(encoder: GPUCommandEncoder, engine: Engine): number;
}
interface SceneUniformUpdater {
    update(engine: Engine): void;
}

// ─── Mesh factory options ────────────────────────────────────────────
interface SphereOptions {
    diameter?: number;
    segments?: number;
}
interface TorusOptions {
    diameter?: number;
    thickness?: number;
    tessellation?: number;
}
interface GroundOptions {
    width?: number;
    height?: number;
    subdivisions?: number;
}

[0]  [4]  [8]  [12]     col0  col1  col2  col3
[1]  [5]  [9]  [13]  =  (X)   (Y)   (Z)   (Translation)
[2]  [6]  [10] [14]
[3]  [7]  [11] [15]

zAxis = normalize(target - eye)          // forward
xAxis = normalize(cross(up, zAxis))      // right
yAxis = cross(zAxis, xAxis)              // up
M = | xAxis.x  yAxis.x  zAxis.x  0 |    (stored column-major)
    | xAxis.y  yAxis.y  zAxis.y  0 |
    | xAxis.z  yAxis.z  zAxis.z  0 |
    | -dot(x,eye)  -dot(y,eye)  -dot(z,eye)  1 |

f = 1 / tan(fov / 2)
M = | f/aspect  0  0              0 |
    | 0         f  0              0 |
    | 0         0  far/(far-near) 1 |
    | 0         0  -far*near/(far-near) 0 |

registerScene runs deferred builders → requestAnimationFrame → resize() → renderFrame() → requestAnimationFrame ...

{
  engine,                        // readonly ref to Engine
  clearColor: {r:0.2, g:0.2, b:0.3, a:1.0},
  camera: null,                  // set by caller
  lights: [],                    // LightBase[] — all light types
  meshes: [],                    // Mesh[] — all meshes (standard + PBR)
  animationGroups: [],           // AnimationGroup[] — glTF animation groups
  fog: null,                     // FogConfig | null
  shadowGenerators: [],          // ShadowGenerator[]
  imageProcessing: { exposure: 1.0, contrast: 1.0, toneMappingEnabled: false },
  _renderables: [],              // Renderable[] — all renderables (combined)
  _opaqueRenderables: [],        // Renderable[] — sorted by order
  _transparentRenderables: [],   // Renderable[] — sorted back-to-front each frame
  _prePasses: [],                // PrePassRenderable[] — shadow passes etc.
  _uniformUpdaters: [],          // SceneUniformUpdater[] — per-frame UBO updates
  _deferredBuilders: [],         // (() => void | Promise<void>)[] — drained by buildScene() during registerScene()
  _fixedDeltaMs: 0,              // fixed delta for animation (0 = use real time)
  _beforeRender: [],             // ((deltaMs: number) => void)[] — per-frame callbacks
}

position = target + Vector3(
  radius * cos(alpha) * sin(beta),
  radius * cos(beta),
  radius * sin(alpha) * sin(beta)
)

hemiNdotL = dot(N, lightDir) * 0.5 + 0.5    // remap [-1,1] → [0,1]
hemiColor = mix(groundColor, diffuseColor, hemiNdotL)
contribution = hemiColor * intensity

interface DrawUpdateContext {
    targetWidth: number;
    targetHeight: number;
    _camera?: Camera | null;
}
interface Renderable {
    order: number;
    isTransparent: boolean;
    _transmissive?: boolean;
    _direct?: boolean;
    bind(engine, target): DrawBinding;
}
interface MaterialView {
    source: Material;
    _renderFeatures: { features: number; features2?: number };
}
interface DrawBinding {
    pipeline: GPURenderPipeline;
    update?(context: DrawUpdateContext): void;
    draw(pass, engine): number;
}
interface PrePassRenderable {
    execute(encoder, engine): number;
}
interface SceneUniformUpdater {
    update(engine): void;
}

[Header: 12B]  magic=0x46546c67, version=2, totalLength
[JSON chunk]   type=0x4E4F534A, length, UTF-8 JSON payload
[BIN chunk]    type=0x004E4942, length, binary blob

byteOffset = bufferView.byteOffset + accessor.byteOffset
TypedArray = new T(binChunk.buffer, binChunk.byteOffset + byteOffset, count * componentCount)

[Magic: 8B]  0x86 0x16 0x87 0x96 0xF6 0xD6 0x96 0x36
[JSON manifest: variable]  UTF-8, null-terminated
[Binary image data: rest]  Concatenated PNG/WebP face images

{
  "width": 256,
  "imageType": "image/png",
  "irradiance": { "x": [...], "y": [...], ... "xy": [...] },
  "specular": {
    "lodGenerationScale": 0.8,
    "mipmaps": [ { "position": 0, "length": 12345 }, ... ]
  }
}

struct SceneUniforms {
  viewProjection: mat4x4<f32>,
  view: mat4x4<f32>,
  vEyePosition: vec4<f32>,
  envRotationY: f32,
  /* SH irradiance + image processing + fog fields */
};                                // Total: 352B

worldPos = mesh.world * vec4(position, 1.0)
clipPos = scene.viewProjection * worldPos
normalW = normalize((mesh.world * vec4(normal, 0)).xyz)
tangentW = normalize((mesh.world * vec4(tangent.xyz, 0)).xyz)
bitangentW = cross(normalW, tangentW) * tangent.w

1. Sample textures (baseColor, ORM, normal, emissive)
2. Linearize sRGB (baseColor, emissive)
3. Normal mapping: TBN * (normalMap * 2 - 1)
4. Compute vectors: V, L, H, NdotL, NdotV, NdotH, VdotH
5. Material: F0 = mix(0.04, baseColor, metallic), diffuseColor = baseColor * (1 - metallic)
6. Direct lighting:
   - Cook-Torrance specular: D * G * F
   - Hemispheric diffuse: mix(groundColor, diffuseColor, dot(N,L)*0.5+0.5) / π
   - Combined: (diffuse * hemiColor + specular * lightColor * NdotL) * intensity
7. IBL:
   - Diffuse: textureSampleLevel(cubemap, N, maxMip) — RGBD decoded
   - Specular: textureSampleLevel(cubemap, reflect(-V,N), roughness*maxMip) — RGBD decoded
   - BRDF LUT: textureSample(brdfLUT, vec2(NdotV, roughness)).rg
   - Combined: (iblDiffuse * diffuseColor + iblSpecular * (F0 * brdf.x + brdf.y)) * occlusion
8. Final: direct + indirect + emissive

main.ts (e.g. scene1.ts)
  │
  ├─→ createEngine(canvas)           → Engine { device, context, format, msaaSamples }
  ├─→ createSceneContext(engine)      → SceneContext { engine, clearColor, camera:null, ... }
  │
  ├─→ loadGltf(engine, url)          → Fetches glTF/GLB, parses, uploads to GPU
  │     Returns AssetContainer          addToScene(scene, container) registers deferred builders
  │
  ├─→ loadEnvironment(scene, url)    → Fetches .env, generates BRDF LUT, uploads cubemap
  │     Sets scene._envTextures         Registers deferred builder → buildBackgroundRenderables()
  │
  ├─→ createDefaultCamera(scene)     → Reads mesh bounds → auto-frames
  │     scene.camera = camera
  │
  ├─→ createHemisphericLight()       → Returns plain HemisphericLight data
  │     scene.lights.push(light)
  │
  └─→ registerScene(scene); startEngine(engine)
        Runs deferred builders (creates pipelines + renderables)
        Builds scene._frameGraph       → begins requestAnimationFrame loop
        Each frame:
          _update(): callbacks, swaps, shadows, pre-passes, uniform updaters
          _record(): scene._frameGraph.execute()
            RenderTask writes pass scene UBO and draws bound buckets
          submit