class dwWebAudio
{
	// 0xffffffff = set
	// 0x00000000 = added
	// 0x00000001 = loaded / stopped
	// 0x00000002 = playing
	// 0x00000004 = looping
	//var dxAudioSourceState = [];
	constructor(dt)
	{
		this.dxAudioCtx = 0;
		this.dxSoundFiles = [];
		this.dxSoundFilesLoaded = 0;
		this.dxBuffer = [];
		this.dxAudioSource = [];
		this.dxAudioSourceState = [];
		//this.init();
	}
	init()
	{
		this.dxAudioCtx = 0;
		this.dxSoundFiles = [];
		this.dxSoundFilesLoaded = 0;
		this.dxBuffer = [];
		this.dxAudioSource = [];
		this.dxAudioSourceState = [];
	}
	destroy()
	{
		return;
		var i = 0;
		for (i = 0; i < this.dxSoundFiles.length; i++) {
			this.dxBuffer.pop();
			this.dxAudioSource[i].disconnect();
			this.dxAudioSourceState[i] = -1;
		}
		this.dxSoundFilesLoaded = 0;

		if (this.dxAudioCtx) {
			this.dxAudioCtx.close();
		}
		this.dxSoundFiles = [];
		this.dxSoundFilesLoaded = 0;
		this.dxBuffer = [];
		this.dxAudioSource = [];
		this.dxAudioSourceState = [];
	}
	addAudioFile(file)
	{
		this.dxSoundFiles.push(file);
		this.dxAudioSourceState.push(0);
	}
	async stopAudio(index)
	{
		this.dxAudioSource[index].stop();
		this.dxAudioSourceState[index] = 1;
	}
	async loadAudio()
	{
		var i = 0; 
		try {
			this.dxAudioCtx = new AudioContext();
			for (i = 0; i < this.dxSoundFiles.length; i++) {
				const response = await fetch(this.dxSoundFiles[i]);
				var temp = await this.dxAudioCtx.decodeAudioData(await response.arrayBuffer());
				this.dxBuffer.push(temp);
				var temp1 = this.dxAudioCtx.createBufferSource();
				this.dxAudioSource.push(temp1);
				this.dxSoundFilesLoaded = this.dxSoundFilesLoaded + 1;
				this.dxAudioSourceState[i] = 1;
			}
		} catch (err) {
			alert('Unable to fetch the audio file ['+this.dxSoundFiles[i]+'|'+i+']. Error: ' + err.message);
			this.dxAudioSourceState[i] = 0;
		}
	}
	async playAudio(index, loop)
	{
		if ((this.dxAudioSourceState[index] & 4)) {
			return;
		}
		if (!this.dxAudioCtx) {
			await this.loadAudio();
		}
		if (this.dxAudioSourceState[index] & 2) {
			this.dxAudioSource[index].stop();	
			this.dxAudioSourceState[index] = 1;
		}
		var temp1 = this.dxAudioCtx.createBufferSource();
		this.dxAudioSource[index] = temp1;
		this.dxAudioSource[index].buffer = this.dxBuffer[index];
		this.dxAudioSource[index].connect(this.dxAudioCtx.destination);
		this.dxAudioSource[index].loop = loop;
		this.dxAudioSource[index].loopStart = 0;
		this.dxAudioSource[index].loopEnd = 0;
		this.dxAudioSource[index].start(0);
		if (loop) {
			this.dxAudioSourceState[index] = 7;
		}
		else {
			this.dxAudioSourceState[index] = 3;
		}
	}
}
/*
 * Copyright 2021, GFXFundamentals.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *     * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following disclaimer
 * in the documentation and/or other materials provided with the
 * distribution.
 *     * Neither the name of GFXFundamentals. nor the names of his
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * Various 3d math functions.
 *
 * @module webgl-3d-math
 */
(function(root, factory) {  // eslint-disable-line
  if (typeof define === 'function' && define.amd) {
    // AMD. Register as an anonymous module.
    define([], factory);
  } else {
    // Browser globals
    root.m4 = factory();
  }
}(this, function() {
  "use strict";

  /**
   * An array or typed array with 3 values.
   * @typedef {number[]|TypedArray} Vector3
   * @memberOf module:webgl-3d-math
   */

  /**
   * An array or typed array with 4 values.
   * @typedef {number[]|TypedArray} Vector4
   * @memberOf module:webgl-3d-math
   */

  /**
   * An array or typed array with 16 values.
   * @typedef {number[]|TypedArray} Matrix4
   * @memberOf module:webgl-3d-math
   */


  let MatType = Float32Array;

  /**
   * Sets the type this library creates for a Mat4
   * @param {constructor} Ctor the constructor for the type. Either `Float32Array` or `Array`
   * @return {constructor} previous constructor for Mat4
   */
  function setDefaultType(Ctor) {
    const OldType = MatType;
    MatType = Ctor;
    return OldType;
  }

  /**
   * Takes two 4-by-4 matrices, a and b, and computes the product in the order
   * that pre-composes b with a.  In other words, the matrix returned will
   * transform by b first and then a.  Note this is subtly different from just
   * multiplying the matrices together.  For given a and b, this function returns
   * the same object in both row-major and column-major mode.
   * @param {Matrix4} a A matrix.
   * @param {Matrix4} b A matrix.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   */
  function multiply(a, b, dst) {
    dst = dst || new MatType(16);
    var b00 = b[0 * 4 + 0];
    var b01 = b[0 * 4 + 1];
    var b02 = b[0 * 4 + 2];
    var b03 = b[0 * 4 + 3];
    var b10 = b[1 * 4 + 0];
    var b11 = b[1 * 4 + 1];
    var b12 = b[1 * 4 + 2];
    var b13 = b[1 * 4 + 3];
    var b20 = b[2 * 4 + 0];
    var b21 = b[2 * 4 + 1];
    var b22 = b[2 * 4 + 2];
    var b23 = b[2 * 4 + 3];
    var b30 = b[3 * 4 + 0];
    var b31 = b[3 * 4 + 1];
    var b32 = b[3 * 4 + 2];
    var b33 = b[3 * 4 + 3];
    var a00 = a[0 * 4 + 0];
    var a01 = a[0 * 4 + 1];
    var a02 = a[0 * 4 + 2];
    var a03 = a[0 * 4 + 3];
    var a10 = a[1 * 4 + 0];
    var a11 = a[1 * 4 + 1];
    var a12 = a[1 * 4 + 2];
    var a13 = a[1 * 4 + 3];
    var a20 = a[2 * 4 + 0];
    var a21 = a[2 * 4 + 1];
    var a22 = a[2 * 4 + 2];
    var a23 = a[2 * 4 + 3];
    var a30 = a[3 * 4 + 0];
    var a31 = a[3 * 4 + 1];
    var a32 = a[3 * 4 + 2];
    var a33 = a[3 * 4 + 3];
    dst[ 0] = b00 * a00 + b01 * a10 + b02 * a20 + b03 * a30;
    dst[ 1] = b00 * a01 + b01 * a11 + b02 * a21 + b03 * a31;
    dst[ 2] = b00 * a02 + b01 * a12 + b02 * a22 + b03 * a32;
    dst[ 3] = b00 * a03 + b01 * a13 + b02 * a23 + b03 * a33;
    dst[ 4] = b10 * a00 + b11 * a10 + b12 * a20 + b13 * a30;
    dst[ 5] = b10 * a01 + b11 * a11 + b12 * a21 + b13 * a31;
    dst[ 6] = b10 * a02 + b11 * a12 + b12 * a22 + b13 * a32;
    dst[ 7] = b10 * a03 + b11 * a13 + b12 * a23 + b13 * a33;
    dst[ 8] = b20 * a00 + b21 * a10 + b22 * a20 + b23 * a30;
    dst[ 9] = b20 * a01 + b21 * a11 + b22 * a21 + b23 * a31;
    dst[10] = b20 * a02 + b21 * a12 + b22 * a22 + b23 * a32;
    dst[11] = b20 * a03 + b21 * a13 + b22 * a23 + b23 * a33;
    dst[12] = b30 * a00 + b31 * a10 + b32 * a20 + b33 * a30;
    dst[13] = b30 * a01 + b31 * a11 + b32 * a21 + b33 * a31;
    dst[14] = b30 * a02 + b31 * a12 + b32 * a22 + b33 * a32;
    dst[15] = b30 * a03 + b31 * a13 + b32 * a23 + b33 * a33;
    return dst;
  }


  /**
   * adds 2 vectors3s
   * @param {Vector3} a a
   * @param {Vector3} b b
   * @param {Vector3} dst optional vector3 to store result
   * @return {Vector3} dst or new Vector3 if not provided
   * @memberOf module:webgl-3d-math
   */
  function addVectors(a, b, dst) {
    dst = dst || new MatType(3);
    dst[0] = a[0] + b[0];
    dst[1] = a[1] + b[1];
    dst[2] = a[2] + b[2];
    return dst;
  }

  /**
   * subtracts 2 vectors3s
   * @param {Vector3} a a
   * @param {Vector3} b b
   * @param {Vector3} dst optional vector3 to store result
   * @return {Vector3} dst or new Vector3 if not provided
   * @memberOf module:webgl-3d-math
   */
  function subtractVectors(a, b, dst) {
    dst = dst || new MatType(3);
    dst[0] = a[0] - b[0];
    dst[1] = a[1] - b[1];
    dst[2] = a[2] - b[2];
    return dst;
  }

  /**
   * scale vectors3
   * @param {Vector3} v vector
   * @param {Number} s scale
   * @param {Vector3} dst optional vector3 to store result
   * @return {Vector3} dst or new Vector3 if not provided
   * @memberOf module:webgl-3d-math
   */
  function scaleVector(v, s, dst) {
    dst = dst || new MatType(3);
    dst[0] = v[0] * s;
    dst[1] = v[1] * s;
    dst[2] = v[2] * s;
    return dst;
  }  
  /**
   * normalizes a vector.
   * @param {Vector3} v vector to normalize
   * @param {Vector3} dst optional vector3 to store result
   * @return {Vector3} dst or new Vector3 if not provided
   * @memberOf module:webgl-3d-math
   */
  function normalize(v, dst) {
    dst = dst || new MatType(3);
    var length = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
    // make sure we don't divide by 0.
    if (length > 0.00001) {
      dst[0] = v[0] / length;
      dst[1] = v[1] / length;
      dst[2] = v[2] / length;
    }
    return dst;
  }

  /**
   * Computes the length of a vector
   * @param {Vector3} v vector to take length of
   * @return {number} length of vector
   */
  function length(v) {
    return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
  }

  /**
   * Computes the length squared of a vector
   * @param {Vector3} v vector to take length of
   * @return {number} length sqaured of vector
   */
  function lengthSq(v) {
    return v[0] * v[0] + v[1] * v[1] + v[2] * v[2];
  }

  /**
   * Computes the cross product of 2 vectors3s
   * @param {Vector3} a a
   * @param {Vector3} b b
   * @param {Vector3} dst optional vector3 to store result
   * @return {Vector3} dst or new Vector3 if not provided
   * @memberOf module:webgl-3d-math
   */
  function cross(a, b, dst) {
    dst = dst || new MatType(3);
    dst[0] = a[1] * b[2] - a[2] * b[1];
    dst[1] = a[2] * b[0] - a[0] * b[2];
    dst[2] = a[0] * b[1] - a[1] * b[0];
    return dst;
  }

  /**
   * Computes the dot product of two vectors; assumes both vectors have
   * three entries.
   * @param {Vector3} a Operand vector.
   * @param {Vector3} b Operand vector.
   * @return {number} dot product
   * @memberOf module:webgl-3d-math
   */
  function dot(a, b) {
    return (a[0] * b[0]) + (a[1] * b[1]) + (a[2] * b[2]);
  }

  /**
   * Computes the distance squared between 2 points
   * @param {Vector3} a
   * @param {Vector3} b
   * @return {number} distance squared between a and b
   */
  function distanceSq(a, b) {
    const dx = a[0] - b[0];
    const dy = a[1] - b[1];
    const dz = a[2] - b[2];
    return dx * dx + dy * dy + dz * dz;
  }

  /**
   * Computes the distance between 2 points
   * @param {Vector3} a
   * @param {Vector3} b
   * @return {number} distance between a and b
   */
  function distance(a, b) {
    return Math.sqrt(distanceSq(a, b));
  }

  /**
   * Makes an identity matrix.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function identity(dst) {
    dst = dst || new MatType(16);

    dst[ 0] = 1;
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = 1;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = 0;
    dst[10] = 1;
    dst[11] = 0;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = 0;
    dst[15] = 1;

    return dst;
  }

  /**
   * Transposes a matrix.
   * @param {Matrix4} m matrix to transpose.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function transpose(m, dst) {
    dst = dst || new MatType(16);

    dst[ 0] = m[0];
    dst[ 1] = m[4];
    dst[ 2] = m[8];
    dst[ 3] = m[12];
    dst[ 4] = m[1];
    dst[ 5] = m[5];
    dst[ 6] = m[9];
    dst[ 7] = m[13];
    dst[ 8] = m[2];
    dst[ 9] = m[6];
    dst[10] = m[10];
    dst[11] = m[14];
    dst[12] = m[3];
    dst[13] = m[7];
    dst[14] = m[11];
    dst[15] = m[15];

    return dst;
  }

  /**
   * Creates a lookAt matrix.
   * This is a world matrix for a camera. In other words it will transform
   * from the origin to a place and orientation in the world. For a view
   * matrix take the inverse of this.
   * @param {Vector3} cameraPosition position of the camera
   * @param {Vector3} target position of the target
   * @param {Vector3} up direction
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function lookAt(cameraPosition, target, up, dst) {
    dst = dst || new MatType(16);
    var zAxis = normalize(
        subtractVectors(cameraPosition, target));
    var xAxis = normalize(cross(up, zAxis));
    var yAxis = normalize(cross(zAxis, xAxis));

    dst[ 0] = xAxis[0];
    dst[ 1] = xAxis[1];
    dst[ 2] = xAxis[2];
    dst[ 3] = 0;
    dst[ 4] = yAxis[0];
    dst[ 5] = yAxis[1];
    dst[ 6] = yAxis[2];
    dst[ 7] = 0;
    dst[ 8] = zAxis[0];
    dst[ 9] = zAxis[1];
    dst[10] = zAxis[2];
    dst[11] = 0;
    dst[12] = cameraPosition[0];
    dst[13] = cameraPosition[1];
    dst[14] = cameraPosition[2];
    dst[15] = 1;

    return dst;
  }

  /**
   * Computes a 4-by-4 perspective transformation matrix given the angular height
   * of the frustum, the aspect ratio, and the near and far clipping planes.  The
   * arguments define a frustum extending in the negative z direction.  The given
   * angle is the vertical angle of the frustum, and the horizontal angle is
   * determined to produce the given aspect ratio.  The arguments near and far are
   * the distances to the near and far clipping planes.  Note that near and far
   * are not z coordinates, but rather they are distances along the negative
   * z-axis.  The matrix generated sends the viewing frustum to the unit box.
   * We assume a unit box extending from -1 to 1 in the x and y dimensions and
   * from -1 to 1 in the z dimension.
   * @param {number} fieldOfViewInRadians field of view in y axis.
   * @param {number} aspect aspect of viewport (width / height)
   * @param {number} near near Z clipping plane
   * @param {number} far far Z clipping plane
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function perspective(fieldOfViewInRadians, aspect, near, far, dst) {
    dst = dst || new MatType(16);
    var f = Math.tan(Math.PI * 0.5 - 0.5 * fieldOfViewInRadians);
    var rangeInv = 1.0 / (near - far);

    dst[ 0] = f / aspect;
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = f;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = 0;
    dst[10] = (near + far) * rangeInv;
    dst[11] = -1;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = near * far * rangeInv * 2;
    dst[15] = 0;

    return dst;
  }

  /**
   * Computes a 4-by-4 orthographic projection matrix given the coordinates of the
   * planes defining the axis-aligned, box-shaped viewing volume.  The matrix
   * generated sends that box to the unit box.  Note that although left and right
   * are x coordinates and bottom and top are y coordinates, near and far
   * are not z coordinates, but rather they are distances along the negative
   * z-axis.  We assume a unit box extending from -1 to 1 in the x and y
   * dimensions and from -1 to 1 in the z dimension.
   * @param {number} left The x coordinate of the left plane of the box.
   * @param {number} right The x coordinate of the right plane of the box.
   * @param {number} bottom The y coordinate of the bottom plane of the box.
   * @param {number} top The y coordinate of the right plane of the box.
   * @param {number} near The negative z coordinate of the near plane of the box.
   * @param {number} far The negative z coordinate of the far plane of the box.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function orthographic(left, right, bottom, top, near, far, dst) {
    dst = dst || new MatType(16);

    dst[ 0] = 2 / (right - left);
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = 2 / (top - bottom);
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = 0;
    dst[10] = 2 / (near - far);
    dst[11] = 0;
    dst[12] = (left + right) / (left - right);
    dst[13] = (bottom + top) / (bottom - top);
    dst[14] = (near + far) / (near - far);
    dst[15] = 1;

    return dst;
  }

  /**
   * Computes a 4-by-4 perspective transformation matrix given the left, right,
   * top, bottom, near and far clipping planes. The arguments define a frustum
   * extending in the negative z direction. The arguments near and far are the
   * distances to the near and far clipping planes. Note that near and far are not
   * z coordinates, but rather they are distances along the negative z-axis. The
   * matrix generated sends the viewing frustum to the unit box. We assume a unit
   * box extending from -1 to 1 in the x and y dimensions and from -1 to 1 in the z
   * dimension.
   * @param {number} left The x coordinate of the left plane of the box.
   * @param {number} right The x coordinate of the right plane of the box.
   * @param {number} bottom The y coordinate of the bottom plane of the box.
   * @param {number} top The y coordinate of the right plane of the box.
   * @param {number} near The negative z coordinate of the near plane of the box.
   * @param {number} far The negative z coordinate of the far plane of the box.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function frustum(left, right, bottom, top, near, far, dst) {
    dst = dst || new MatType(16);

    var dx = right - left;
    var dy = top - bottom;
    var dz = far - near;

    dst[ 0] = 2 * near / dx;
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = 2 * near / dy;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = (left + right) / dx;
    dst[ 9] = (top + bottom) / dy;
    dst[10] = -(far + near) / dz;
    dst[11] = -1;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = -2 * near * far / dz;
    dst[15] = 0;

    return dst;
  }

  /**
   * Makes a translation matrix
   * @param {number} tx x translation.
   * @param {number} ty y translation.
   * @param {number} tz z translation.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function translation(tx, ty, tz, dst) {
    dst = dst || new MatType(16);

    dst[ 0] = 1;
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = 1;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = 0;
    dst[10] = 1;
    dst[11] = 0;
    dst[12] = tx;
    dst[13] = ty;
    dst[14] = tz;
    dst[15] = 1;

    return dst;
  }

  /**
   * Multiply by translation matrix.
   * @param {Matrix4} m matrix to multiply
   * @param {number} tx x translation.
   * @param {number} ty y translation.
   * @param {number} tz z translation.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function translate(m, tx, ty, tz, dst) {
    // This is the optimized version of
    // return multiply(m, translation(tx, ty, tz), dst);
    dst = dst || new MatType(16);

    var m00 = m[0];
    var m01 = m[1];
    var m02 = m[2];
    var m03 = m[3];
    var m10 = m[1 * 4 + 0];
    var m11 = m[1 * 4 + 1];
    var m12 = m[1 * 4 + 2];
    var m13 = m[1 * 4 + 3];
    var m20 = m[2 * 4 + 0];
    var m21 = m[2 * 4 + 1];
    var m22 = m[2 * 4 + 2];
    var m23 = m[2 * 4 + 3];
    var m30 = m[3 * 4 + 0];
    var m31 = m[3 * 4 + 1];
    var m32 = m[3 * 4 + 2];
    var m33 = m[3 * 4 + 3];

    if (m !== dst) {
      dst[ 0] = m00;
      dst[ 1] = m01;
      dst[ 2] = m02;
      dst[ 3] = m03;
      dst[ 4] = m10;
      dst[ 5] = m11;
      dst[ 6] = m12;
      dst[ 7] = m13;
      dst[ 8] = m20;
      dst[ 9] = m21;
      dst[10] = m22;
      dst[11] = m23;
    }

    dst[12] = m00 * tx + m10 * ty + m20 * tz + m30;
    dst[13] = m01 * tx + m11 * ty + m21 * tz + m31;
    dst[14] = m02 * tx + m12 * ty + m22 * tz + m32;
    dst[15] = m03 * tx + m13 * ty + m23 * tz + m33;

    return dst;
  }

  /**
   * Makes an x rotation matrix
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function xRotation(angleInRadians, dst) {
    dst = dst || new MatType(16);
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);

    dst[ 0] = 1;
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = c;
    dst[ 6] = s;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = -s;
    dst[10] = c;
    dst[11] = 0;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = 0;
    dst[15] = 1;

    return dst;
  }

  /**
   * Multiply by an x rotation matrix
   * @param {Matrix4} m matrix to multiply
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function xRotate(m, angleInRadians, dst) {
    // this is the optimized version of
    // return multiply(m, xRotation(angleInRadians), dst);
    dst = dst || new MatType(16);

    var m10 = m[4];
    var m11 = m[5];
    var m12 = m[6];
    var m13 = m[7];
    var m20 = m[8];
    var m21 = m[9];
    var m22 = m[10];
    var m23 = m[11];
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);

    dst[4]  = c * m10 + s * m20;
    dst[5]  = c * m11 + s * m21;
    dst[6]  = c * m12 + s * m22;
    dst[7]  = c * m13 + s * m23;
    dst[8]  = c * m20 - s * m10;
    dst[9]  = c * m21 - s * m11;
    dst[10] = c * m22 - s * m12;
    dst[11] = c * m23 - s * m13;

    if (m !== dst) {
      dst[ 0] = m[ 0];
      dst[ 1] = m[ 1];
      dst[ 2] = m[ 2];
      dst[ 3] = m[ 3];
      dst[12] = m[12];
      dst[13] = m[13];
      dst[14] = m[14];
      dst[15] = m[15];
    }

    return dst;
  }

  /**
   * Makes an y rotation matrix
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function yRotation(angleInRadians, dst) {
    dst = dst || new MatType(16);
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);

    dst[ 0] = c;
    dst[ 1] = 0;
    dst[ 2] = -s;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = 1;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = s;
    dst[ 9] = 0;
    dst[10] = c;
    dst[11] = 0;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = 0;
    dst[15] = 1;

    return dst;
  }

  /**
   * Multiply by an y rotation matrix
   * @param {Matrix4} m matrix to multiply
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function yRotate(m, angleInRadians, dst) {
    // this is the optimized version of
    // return multiply(m, yRotation(angleInRadians), dst);
    dst = dst || new MatType(16);

    var m00 = m[0 * 4 + 0];
    var m01 = m[0 * 4 + 1];
    var m02 = m[0 * 4 + 2];
    var m03 = m[0 * 4 + 3];
    var m20 = m[2 * 4 + 0];
    var m21 = m[2 * 4 + 1];
    var m22 = m[2 * 4 + 2];
    var m23 = m[2 * 4 + 3];
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);

    dst[ 0] = c * m00 - s * m20;
    dst[ 1] = c * m01 - s * m21;
    dst[ 2] = c * m02 - s * m22;
    dst[ 3] = c * m03 - s * m23;
    dst[ 8] = c * m20 + s * m00;
    dst[ 9] = c * m21 + s * m01;
    dst[10] = c * m22 + s * m02;
    dst[11] = c * m23 + s * m03;

    if (m !== dst) {
      dst[ 4] = m[ 4];
      dst[ 5] = m[ 5];
      dst[ 6] = m[ 6];
      dst[ 7] = m[ 7];
      dst[12] = m[12];
      dst[13] = m[13];
      dst[14] = m[14];
      dst[15] = m[15];
    }

    return dst;
  }

  /**
   * Makes an z rotation matrix
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function zRotation(angleInRadians, dst) {
    dst = dst || new MatType(16);
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);

    dst[ 0] = c;
    dst[ 1] = s;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = -s;
    dst[ 5] = c;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = 0;
    dst[10] = 1;
    dst[11] = 0;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = 0;
    dst[15] = 1;

    return dst;
  }

  /**
   * Multiply by an z rotation matrix
   * @param {Matrix4} m matrix to multiply
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function zRotate(m, angleInRadians, dst) {
    // This is the optimized version of
    // return multiply(m, zRotation(angleInRadians), dst);
    dst = dst || new MatType(16);

    var m00 = m[0 * 4 + 0];
    var m01 = m[0 * 4 + 1];
    var m02 = m[0 * 4 + 2];
    var m03 = m[0 * 4 + 3];
    var m10 = m[1 * 4 + 0];
    var m11 = m[1 * 4 + 1];
    var m12 = m[1 * 4 + 2];
    var m13 = m[1 * 4 + 3];
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);

    dst[ 0] = c * m00 + s * m10;
    dst[ 1] = c * m01 + s * m11;
    dst[ 2] = c * m02 + s * m12;
    dst[ 3] = c * m03 + s * m13;
    dst[ 4] = c * m10 - s * m00;
    dst[ 5] = c * m11 - s * m01;
    dst[ 6] = c * m12 - s * m02;
    dst[ 7] = c * m13 - s * m03;

    if (m !== dst) {
      dst[ 8] = m[ 8];
      dst[ 9] = m[ 9];
      dst[10] = m[10];
      dst[11] = m[11];
      dst[12] = m[12];
      dst[13] = m[13];
      dst[14] = m[14];
      dst[15] = m[15];
    }

    return dst;
  }

  /**
   * Makes an rotation matrix around an arbitrary axis
   * @param {Vector3} axis axis to rotate around
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function axisRotation(axis, angleInRadians, dst) {
    dst = dst || new MatType(16);

    var x = axis[0];
    var y = axis[1];
    var z = axis[2];
    var n = Math.sqrt(x * x + y * y + z * z);
    x /= n;
    y /= n;
    z /= n;
    var xx = x * x;
    var yy = y * y;
    var zz = z * z;
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);
    var oneMinusCosine = 1 - c;

    dst[ 0] = xx + (1 - xx) * c;
    dst[ 1] = x * y * oneMinusCosine + z * s;
    dst[ 2] = x * z * oneMinusCosine - y * s;
    dst[ 3] = 0;
    dst[ 4] = x * y * oneMinusCosine - z * s;
    dst[ 5] = yy + (1 - yy) * c;
    dst[ 6] = y * z * oneMinusCosine + x * s;
    dst[ 7] = 0;
    dst[ 8] = x * z * oneMinusCosine + y * s;
    dst[ 9] = y * z * oneMinusCosine - x * s;
    dst[10] = zz + (1 - zz) * c;
    dst[11] = 0;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = 0;
    dst[15] = 1;

    return dst;
  }

  /**
   * Multiply by an axis rotation matrix
   * @param {Matrix4} m matrix to multiply
   * @param {Vector3} axis axis to rotate around
   * @param {number} angleInRadians amount to rotate
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function axisRotate(m, axis, angleInRadians, dst) {
    // This is the optimized version of
    // return multiply(m, axisRotation(axis, angleInRadians), dst);
    dst = dst || new MatType(16);

    var x = axis[0];
    var y = axis[1];
    var z = axis[2];
    var n = Math.sqrt(x * x + y * y + z * z);
    x /= n;
    y /= n;
    z /= n;
    var xx = x * x;
    var yy = y * y;
    var zz = z * z;
    var c = Math.cos(angleInRadians);
    var s = Math.sin(angleInRadians);
    var oneMinusCosine = 1 - c;

    var r00 = xx + (1 - xx) * c;
    var r01 = x * y * oneMinusCosine + z * s;
    var r02 = x * z * oneMinusCosine - y * s;
    var r10 = x * y * oneMinusCosine - z * s;
    var r11 = yy + (1 - yy) * c;
    var r12 = y * z * oneMinusCosine + x * s;
    var r20 = x * z * oneMinusCosine + y * s;
    var r21 = y * z * oneMinusCosine - x * s;
    var r22 = zz + (1 - zz) * c;

    var m00 = m[0];
    var m01 = m[1];
    var m02 = m[2];
    var m03 = m[3];
    var m10 = m[4];
    var m11 = m[5];
    var m12 = m[6];
    var m13 = m[7];
    var m20 = m[8];
    var m21 = m[9];
    var m22 = m[10];
    var m23 = m[11];

    dst[ 0] = r00 * m00 + r01 * m10 + r02 * m20;
    dst[ 1] = r00 * m01 + r01 * m11 + r02 * m21;
    dst[ 2] = r00 * m02 + r01 * m12 + r02 * m22;
    dst[ 3] = r00 * m03 + r01 * m13 + r02 * m23;
    dst[ 4] = r10 * m00 + r11 * m10 + r12 * m20;
    dst[ 5] = r10 * m01 + r11 * m11 + r12 * m21;
    dst[ 6] = r10 * m02 + r11 * m12 + r12 * m22;
    dst[ 7] = r10 * m03 + r11 * m13 + r12 * m23;
    dst[ 8] = r20 * m00 + r21 * m10 + r22 * m20;
    dst[ 9] = r20 * m01 + r21 * m11 + r22 * m21;
    dst[10] = r20 * m02 + r21 * m12 + r22 * m22;
    dst[11] = r20 * m03 + r21 * m13 + r22 * m23;

    if (m !== dst) {
      dst[12] = m[12];
      dst[13] = m[13];
      dst[14] = m[14];
      dst[15] = m[15];
    }

    return dst;
  }

  /**
   * Makes a scale matrix
   * @param {number} sx x scale.
   * @param {number} sy y scale.
   * @param {number} sz z scale.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function scaling(sx, sy, sz, dst) {
    dst = dst || new MatType(16);

    dst[ 0] = sx;
    dst[ 1] = 0;
    dst[ 2] = 0;
    dst[ 3] = 0;
    dst[ 4] = 0;
    dst[ 5] = sy;
    dst[ 6] = 0;
    dst[ 7] = 0;
    dst[ 8] = 0;
    dst[ 9] = 0;
    dst[10] = sz;
    dst[11] = 0;
    dst[12] = 0;
    dst[13] = 0;
    dst[14] = 0;
    dst[15] = 1;

    return dst;
  }

  /**
   * Multiply by a scaling matrix
   * @param {Matrix4} m matrix to multiply
   * @param {number} sx x scale.
   * @param {number} sy y scale.
   * @param {number} sz z scale.
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function scale(m, sx, sy, sz, dst) {
    // This is the optimized version of
    // return multiply(m, scaling(sx, sy, sz), dst);
    dst = dst || new MatType(16);

    dst[ 0] = sx * m[0 * 4 + 0];
    dst[ 1] = sx * m[0 * 4 + 1];
    dst[ 2] = sx * m[0 * 4 + 2];
    dst[ 3] = sx * m[0 * 4 + 3];
    dst[ 4] = sy * m[1 * 4 + 0];
    dst[ 5] = sy * m[1 * 4 + 1];
    dst[ 6] = sy * m[1 * 4 + 2];
    dst[ 7] = sy * m[1 * 4 + 3];
    dst[ 8] = sz * m[2 * 4 + 0];
    dst[ 9] = sz * m[2 * 4 + 1];
    dst[10] = sz * m[2 * 4 + 2];
    dst[11] = sz * m[2 * 4 + 3];

    if (m !== dst) {
      dst[12] = m[12];
      dst[13] = m[13];
      dst[14] = m[14];
      dst[15] = m[15];
    }

    return dst;
  }

  /**
   * creates a matrix from translation, quaternion, scale
   * @param {Number[]} translation [x, y, z] translation
   * @param {Number[]} quaternion [x, y, z, z] quaternion rotation
   * @param {Number[]} scale [x, y, z] scale
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   */
  function compose(translation, quaternion, scale, dst) {
    dst = dst || new MatType(16);

    const x = quaternion[0];
    const y = quaternion[1];
    const z = quaternion[2];
    const w = quaternion[3];

    const x2 = x + x;
    const y2 = y + y;
    const z2 = z + z;

    const xx = x * x2;
    const xy = x * y2;
    const xz = x * z2;

    const yy = y * y2;
    const yz = y * z2;
    const zz = z * z2;

    const wx = w * x2;
    const wy = w * y2;
    const wz = w * z2;

    const sx = scale[0];
    const sy = scale[1];
    const sz = scale[2];

    dst[0] = (1 - (yy + zz)) * sx;
    dst[1] = (xy + wz) * sx;
    dst[2] = (xz - wy) * sx;
    dst[3] = 0;

    dst[4] = (xy - wz) * sy;
    dst[5] = (1 - (xx + zz)) * sy;
    dst[6] = (yz + wx) * sy;
    dst[7] = 0;

    dst[ 8] = (xz + wy) * sz;
    dst[ 9] = (yz - wx) * sz;
    dst[10] = (1 - (xx + yy)) * sz;
    dst[11] = 0;

    dst[12] = translation[0];
    dst[13] = translation[1];
    dst[14] = translation[2];
    dst[15] = 1;

    return dst;
  }

  function quatFromRotationMatrix(m, dst) {
    // http://www.euclideanspace.com/maths/geometry/rotations/conversions/matrixToQuaternion/index.htm

    // assumes the upper 3x3 of m is a pure rotation matrix (i.e, unscaled)
    const m11 = m[0];
    const m12 = m[4];
    const m13 = m[8];
    const m21 = m[1];
    const m22 = m[5];
    const m23 = m[9];
    const m31 = m[2];
    const m32 = m[6];
    const m33 = m[10];

    const trace = m11 + m22 + m33;

    if (trace > 0) {
      const s = 0.5 / Math.sqrt(trace + 1);
      dst[3] = 0.25 / s;
      dst[0] = (m32 - m23) * s;
      dst[1] = (m13 - m31) * s;
      dst[2] = (m21 - m12) * s;
    } else if (m11 > m22 && m11 > m33) {
      const s = 2 * Math.sqrt(1 + m11 - m22 - m33);
      dst[3] = (m32 - m23) / s;
      dst[0] = 0.25 * s;
      dst[1] = (m12 + m21) / s;
      dst[2] = (m13 + m31) / s;
    } else if (m22 > m33) {
      const s = 2 * Math.sqrt(1 + m22 - m11 - m33);
      dst[3] = (m13 - m31) / s;
      dst[0] = (m12 + m21) / s;
      dst[1] = 0.25 * s;
      dst[2] = (m23 + m32) / s;
    } else {
      const s = 2 * Math.sqrt(1 + m33 - m11 - m22);
      dst[3] = (m21 - m12) / s;
      dst[0] = (m13 + m31) / s;
      dst[1] = (m23 + m32) / s;
      dst[2] = 0.25 * s;
    }
  }

  function decompose(mat, translation, quaternion, scale) {
    let sx = m4.length(mat.slice(0, 3));
    const sy = m4.length(mat.slice(4, 7));
    const sz = m4.length(mat.slice(8, 11));

    // if determinate is negative, we need to invert one scale
    const det = determinate(mat);
    if (det < 0) {
      sx = -sx;
    }

    translation[0] = mat[12];
    translation[1] = mat[13];
    translation[2] = mat[14];

    // scale the rotation part
    const matrix = m4.copy(mat);

    const invSX = 1 / sx;
    const invSY = 1 / sy;
    const invSZ = 1 / sz;

    matrix[0] *= invSX;
    matrix[1] *= invSX;
    matrix[2] *= invSX;

    matrix[4] *= invSY;
    matrix[5] *= invSY;
    matrix[6] *= invSY;

    matrix[8] *= invSZ;
    matrix[9] *= invSZ;
    matrix[10] *= invSZ;

    quatFromRotationMatrix(matrix, quaternion);

    scale[0] = sx;
    scale[1] = sy;
    scale[2] = sz;
  }

  function determinate(m) {
    var m00 = m[0 * 4 + 0];
    var m01 = m[0 * 4 + 1];
    var m02 = m[0 * 4 + 2];
    var m03 = m[0 * 4 + 3];
    var m10 = m[1 * 4 + 0];
    var m11 = m[1 * 4 + 1];
    var m12 = m[1 * 4 + 2];
    var m13 = m[1 * 4 + 3];
    var m20 = m[2 * 4 + 0];
    var m21 = m[2 * 4 + 1];
    var m22 = m[2 * 4 + 2];
    var m23 = m[2 * 4 + 3];
    var m30 = m[3 * 4 + 0];
    var m31 = m[3 * 4 + 1];
    var m32 = m[3 * 4 + 2];
    var m33 = m[3 * 4 + 3];
    var tmp_0  = m22 * m33;
    var tmp_1  = m32 * m23;
    var tmp_2  = m12 * m33;
    var tmp_3  = m32 * m13;
    var tmp_4  = m12 * m23;
    var tmp_5  = m22 * m13;
    var tmp_6  = m02 * m33;
    var tmp_7  = m32 * m03;
    var tmp_8  = m02 * m23;
    var tmp_9  = m22 * m03;
    var tmp_10 = m02 * m13;
    var tmp_11 = m12 * m03;

    var t0 = (tmp_0 * m11 + tmp_3 * m21 + tmp_4 * m31) -
        (tmp_1 * m11 + tmp_2 * m21 + tmp_5 * m31);
    var t1 = (tmp_1 * m01 + tmp_6 * m21 + tmp_9 * m31) -
        (tmp_0 * m01 + tmp_7 * m21 + tmp_8 * m31);
    var t2 = (tmp_2 * m01 + tmp_7 * m11 + tmp_10 * m31) -
        (tmp_3 * m01 + tmp_6 * m11 + tmp_11 * m31);
    var t3 = (tmp_5 * m01 + tmp_8 * m11 + tmp_11 * m21) -
        (tmp_4 * m01 + tmp_9 * m11 + tmp_10 * m21);

    return 1.0 / (m00 * t0 + m10 * t1 + m20 * t2 + m30 * t3);
  }

  /**
   * Computes the inverse of a matrix.
   * @param {Matrix4} m matrix to compute inverse of
   * @param {Matrix4} [dst] optional matrix to store result
   * @return {Matrix4} dst or a new matrix if none provided
   * @memberOf module:webgl-3d-math
   */
  function inverse(m, dst) {
    dst = dst || new MatType(16);
    var m00 = m[0 * 4 + 0];
    var m01 = m[0 * 4 + 1];
    var m02 = m[0 * 4 + 2];
    var m03 = m[0 * 4 + 3];
    var m10 = m[1 * 4 + 0];
    var m11 = m[1 * 4 + 1];
    var m12 = m[1 * 4 + 2];
    var m13 = m[1 * 4 + 3];
    var m20 = m[2 * 4 + 0];
    var m21 = m[2 * 4 + 1];
    var m22 = m[2 * 4 + 2];
    var m23 = m[2 * 4 + 3];
    var m30 = m[3 * 4 + 0];
    var m31 = m[3 * 4 + 1];
    var m32 = m[3 * 4 + 2];
    var m33 = m[3 * 4 + 3];
    var tmp_0  = m22 * m33;
    var tmp_1  = m32 * m23;
    var tmp_2  = m12 * m33;
    var tmp_3  = m32 * m13;
    var tmp_4  = m12 * m23;
    var tmp_5  = m22 * m13;
    var tmp_6  = m02 * m33;
    var tmp_7  = m32 * m03;
    var tmp_8  = m02 * m23;
    var tmp_9  = m22 * m03;
    var tmp_10 = m02 * m13;
    var tmp_11 = m12 * m03;
    var tmp_12 = m20 * m31;
    var tmp_13 = m30 * m21;
    var tmp_14 = m10 * m31;
    var tmp_15 = m30 * m11;
    var tmp_16 = m10 * m21;
    var tmp_17 = m20 * m11;
    var tmp_18 = m00 * m31;
    var tmp_19 = m30 * m01;
    var tmp_20 = m00 * m21;
    var tmp_21 = m20 * m01;
    var tmp_22 = m00 * m11;
    var tmp_23 = m10 * m01;

    var t0 = (tmp_0 * m11 + tmp_3 * m21 + tmp_4 * m31) -
        (tmp_1 * m11 + tmp_2 * m21 + tmp_5 * m31);
    var t1 = (tmp_1 * m01 + tmp_6 * m21 + tmp_9 * m31) -
        (tmp_0 * m01 + tmp_7 * m21 + tmp_8 * m31);
    var t2 = (tmp_2 * m01 + tmp_7 * m11 + tmp_10 * m31) -
        (tmp_3 * m01 + tmp_6 * m11 + tmp_11 * m31);
    var t3 = (tmp_5 * m01 + tmp_8 * m11 + tmp_11 * m21) -
        (tmp_4 * m01 + tmp_9 * m11 + tmp_10 * m21);

    var d = 1.0 / (m00 * t0 + m10 * t1 + m20 * t2 + m30 * t3);

    dst[0] = d * t0;
    dst[1] = d * t1;
    dst[2] = d * t2;
    dst[3] = d * t3;
    dst[4] = d * ((tmp_1 * m10 + tmp_2 * m20 + tmp_5 * m30) -
          (tmp_0 * m10 + tmp_3 * m20 + tmp_4 * m30));
    dst[5] = d * ((tmp_0 * m00 + tmp_7 * m20 + tmp_8 * m30) -
          (tmp_1 * m00 + tmp_6 * m20 + tmp_9 * m30));
    dst[6] = d * ((tmp_3 * m00 + tmp_6 * m10 + tmp_11 * m30) -
          (tmp_2 * m00 + tmp_7 * m10 + tmp_10 * m30));
    dst[7] = d * ((tmp_4 * m00 + tmp_9 * m10 + tmp_10 * m20) -
          (tmp_5 * m00 + tmp_8 * m10 + tmp_11 * m20));
    dst[8] = d * ((tmp_12 * m13 + tmp_15 * m23 + tmp_16 * m33) -
          (tmp_13 * m13 + tmp_14 * m23 + tmp_17 * m33));
    dst[9] = d * ((tmp_13 * m03 + tmp_18 * m23 + tmp_21 * m33) -
          (tmp_12 * m03 + tmp_19 * m23 + tmp_20 * m33));
    dst[10] = d * ((tmp_14 * m03 + tmp_19 * m13 + tmp_22 * m33) -
          (tmp_15 * m03 + tmp_18 * m13 + tmp_23 * m33));
    dst[11] = d * ((tmp_17 * m03 + tmp_20 * m13 + tmp_23 * m23) -
          (tmp_16 * m03 + tmp_21 * m13 + tmp_22 * m23));
    dst[12] = d * ((tmp_14 * m22 + tmp_17 * m32 + tmp_13 * m12) -
          (tmp_16 * m32 + tmp_12 * m12 + tmp_15 * m22));
    dst[13] = d * ((tmp_20 * m32 + tmp_12 * m02 + tmp_19 * m22) -
          (tmp_18 * m22 + tmp_21 * m32 + tmp_13 * m02));
    dst[14] = d * ((tmp_18 * m12 + tmp_23 * m32 + tmp_15 * m02) -
          (tmp_22 * m32 + tmp_14 * m02 + tmp_19 * m12));
    dst[15] = d * ((tmp_22 * m22 + tmp_16 * m02 + tmp_21 * m12) -
          (tmp_20 * m12 + tmp_23 * m22 + tmp_17 * m02));

    return dst;
  }

  /**
   * Takes a  matrix and a vector with 4 entries, transforms that vector by
   * the matrix, and returns the result as a vector with 4 entries.
   * @param {Matrix4} m The matrix.
   * @param {Vector4} v The point in homogenous coordinates.
   * @param {Vector4} dst optional vector4 to store result
   * @return {Vector4} dst or new Vector4 if not provided
   * @memberOf module:webgl-3d-math
   */
  function transformVector(m, v, dst) {
    dst = dst || new MatType(4);
    for (var i = 0; i < 4; ++i) {
      dst[i] = 0.0;
      for (var j = 0; j < 4; ++j) {
        dst[i] += v[j] * m[j * 4 + i];
      }
    }
    return dst;
  }

  /**
   * Takes a 4-by-4 matrix and a vector with 3 entries,
   * interprets the vector as a point, transforms that point by the matrix, and
   * returns the result as a vector with 3 entries.
   * @param {Matrix4} m The matrix.
   * @param {Vector3} v The point.
   * @param {Vector4} dst optional vector4 to store result
   * @return {Vector4} dst or new Vector4 if not provided
   * @memberOf module:webgl-3d-math
   */
  function transformPoint(m, v, dst) {
    dst = dst || new MatType(3);
    var v0 = v[0];
    var v1 = v[1];
    var v2 = v[2];
    var d = v0 * m[0 * 4 + 3] + v1 * m[1 * 4 + 3] + v2 * m[2 * 4 + 3] + m[3 * 4 + 3];

    dst[0] = (v0 * m[0 * 4 + 0] + v1 * m[1 * 4 + 0] + v2 * m[2 * 4 + 0] + m[3 * 4 + 0]) / d;
    dst[1] = (v0 * m[0 * 4 + 1] + v1 * m[1 * 4 + 1] + v2 * m[2 * 4 + 1] + m[3 * 4 + 1]) / d;
    dst[2] = (v0 * m[0 * 4 + 2] + v1 * m[1 * 4 + 2] + v2 * m[2 * 4 + 2] + m[3 * 4 + 2]) / d;

    return dst;
  }

  /**
   * Takes a 4-by-4 matrix and a vector with 3 entries, interprets the vector as a
   * direction, transforms that direction by the matrix, and returns the result;
   * assumes the transformation of 3-dimensional space represented by the matrix
   * is parallel-preserving, i.e. any combination of rotation, scaling and
   * translation, but not a perspective distortion. Returns a vector with 3
   * entries.
   * @param {Matrix4} m The matrix.
   * @param {Vector3} v The direction.
   * @param {Vector4} dst optional vector4 to store result
   * @return {Vector4} dst or new Vector4 if not provided
   * @memberOf module:webgl-3d-math
   */
  function transformDirection(m, v, dst) {
    dst = dst || new MatType(3);

    var v0 = v[0];
    var v1 = v[1];
    var v2 = v[2];

    dst[0] = v0 * m[0 * 4 + 0] + v1 * m[1 * 4 + 0] + v2 * m[2 * 4 + 0];
    dst[1] = v0 * m[0 * 4 + 1] + v1 * m[1 * 4 + 1] + v2 * m[2 * 4 + 1];
    dst[2] = v0 * m[0 * 4 + 2] + v1 * m[1 * 4 + 2] + v2 * m[2 * 4 + 2];

    return dst;
  }

  /**
   * Takes a 4-by-4 matrix m and a vector v with 3 entries, interprets the vector
   * as a normal to a surface, and computes a vector which is normal upon
   * transforming that surface by the matrix. The effect of this function is the
   * same as transforming v (as a direction) by the inverse-transpose of m.  This
   * function assumes the transformation of 3-dimensional space represented by the
   * matrix is parallel-preserving, i.e. any combination of rotation, scaling and
   * translation, but not a perspective distortion.  Returns a vector with 3
   * entries.
   * @param {Matrix4} m The matrix.
   * @param {Vector3} v The normal.
   * @param {Vector3} [dst] The direction.
   * @return {Vector3} The transformed direction.
   * @memberOf module:webgl-3d-math
   */
  function transformNormal(m, v, dst) {
    dst = dst || new MatType(3);
    var mi = inverse(m);
    var v0 = v[0];
    var v1 = v[1];
    var v2 = v[2];

    dst[0] = v0 * mi[0 * 4 + 0] + v1 * mi[0 * 4 + 1] + v2 * mi[0 * 4 + 2];
    dst[1] = v0 * mi[1 * 4 + 0] + v1 * mi[1 * 4 + 1] + v2 * mi[1 * 4 + 2];
    dst[2] = v0 * mi[2 * 4 + 0] + v1 * mi[2 * 4 + 1] + v2 * mi[2 * 4 + 2];

    return dst;
  }

  function copy(src, dst) {
    dst = dst || new MatType(16);

    dst[ 0] = src[ 0];
    dst[ 1] = src[ 1];
    dst[ 2] = src[ 2];
    dst[ 3] = src[ 3];
    dst[ 4] = src[ 4];
    dst[ 5] = src[ 5];
    dst[ 6] = src[ 6];
    dst[ 7] = src[ 7];
    dst[ 8] = src[ 8];
    dst[ 9] = src[ 9];
    dst[10] = src[10];
    dst[11] = src[11];
    dst[12] = src[12];
    dst[13] = src[13];
    dst[14] = src[14];
    dst[15] = src[15];

    return dst;
  }

  return {
    copy: copy,
    lookAt: lookAt,
    addVectors: addVectors,
    subtractVectors: subtractVectors,
    scaleVector: scaleVector,
    distance: distance,
    distanceSq: distanceSq,
    normalize: normalize,
    compose: compose,
    cross: cross,
    decompose: decompose,
    dot: dot,
    identity: identity,
    transpose: transpose,
    length: length,
    lengthSq: lengthSq,
    orthographic: orthographic,
    frustum: frustum,
    perspective: perspective,
    translation: translation,
    translate: translate,
    xRotation: xRotation,
    yRotation: yRotation,
    zRotation: zRotation,
    xRotate: xRotate,
    yRotate: yRotate,
    zRotate: zRotate,
    axisRotation: axisRotation,
    axisRotate: axisRotate,
    scaling: scaling,
    scale: scale,
    multiply: multiply,
    inverse: inverse,
    transformVector: transformVector,
    transformPoint: transformPoint,
    transformDirection: transformDirection,
    transformNormal: transformNormal,
    setDefaultType: setDefaultType,
  };

}));

/*!
 * @license twgl.js 4.17.0 Copyright (c) 2015, Gregg Tavares All Rights Reserved.
 * Available via the MIT license.
 * see: http://github.com/greggman/twgl.js for details
 */
!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports.twgl=t():e.twgl=t()}("undefined"!=typeof self?self:this,(function(){return function(e){var t={};function r(n){if(t[n])return t[n].exports;var o=t[n]={i:n,l:!1,exports:{}};return e[n].call(o.exports,o,o.exports,r),o.l=!0,o.exports}return r.m=e,r.c=t,r.d=function(e,t,n){r.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:n})},r.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return r.d(t,"a",t),t},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r.p="",r(r.s=8)}([function(e,t,r){"use strict";t.__esModule=!0,t.copyExistingProperties=function(e,t){Object.keys(t).forEach((function(r){t.hasOwnProperty(r)&&e.hasOwnProperty(r)&&(t[r]=e[r])}))},t.copyNamedProperties=function(e,t,r){e.forEach((function(e){var n=t[e];void 0!==n&&(r[e]=n)}))},t.error=function(){var e;(e=console).error.apply(e,arguments)},t.warn=function(){var e;(e=console).warn.apply(e,arguments)},t.isBuffer=function(e,t){return"undefined"!=typeof WebGLBuffer&&t instanceof WebGLBuffer},t.isRenderbuffer=function(e,t){return"undefined"!=typeof WebGLRenderbuffer&&t instanceof WebGLRenderbuffer},t.isShader=function(e,t){return"undefined"!=typeof WebGLShader&&t instanceof WebGLShader},t.isTexture=function(e,t){return"undefined"!=typeof WebGLTexture&&t instanceof WebGLTexture},t.isSampler=function(e,t){return"undefined"!=typeof WebGLSampler&&t instanceof WebGLSampler}},function(e,t,r){"use strict";t.__esModule=!0,t.getGLTypeForTypedArray=function(e){if(e instanceof Int8Array)return n;if(e instanceof Uint8Array)return o;if(e instanceof Uint8ClampedArray)return o;if(e instanceof Int16Array)return u;if(e instanceof Uint16Array)return i;if(e instanceof Int32Array)return a;if(e instanceof Uint32Array)return f;if(e instanceof Float32Array)return c;throw new Error("unsupported typed array type")},t.getGLTypeForTypedArrayType=function(e){if(e===Int8Array)return n;if(e===Uint8Array)return o;if(e===Uint8ClampedArray)return o;if(e===Int16Array)return u;if(e===Uint16Array)return i;if(e===Int32Array)return a;if(e===Uint32Array)return f;if(e===Float32Array)return c;throw new Error("unsupported typed array type")},t.getTypedArrayTypeForGLType=function(e){var t=l[e];if(!t)throw new Error("unknown gl type");return t},t.isArrayBuffer=void 0;var n=5120,o=5121,u=5122,i=5123,a=5124,f=5125,c=5126,l={},s=l;s[n]=Int8Array,s[5121]=Uint8Array,s[5122]=Int16Array,s[5123]=Uint16Array,s[a]=Int32Array,s[5125]=Uint32Array,s[5126]=Float32Array,s[32819]=Uint16Array,s[32820]=Uint16Array,s[33635]=Uint16Array,s[5131]=Uint16Array,s[33640]=Uint32Array,s[35899]=Uint32Array,s[35902]=Uint32Array,s[36269]=Uint32Array,s[34042]=Uint32Array;var y="undefined"!=typeof SharedArrayBuffer?function(e){return e&&e.buffer&&(e.buffer instanceof ArrayBuffer||e.buffer instanceof SharedArrayBuffer)}:function(e){return e&&e.buffer&&e.buffer instanceof ArrayBuffer};t.isArrayBuffer=y},function(e,t,r){"use strict";t.__esModule=!0,t.add=function(e,t,r){return(r=r||new n(3))[0]=e[0]+t[0],r[1]=e[1]+t[1],r[2]=e[2]+t[2],r},t.copy=function(e,t){return(t=t||new n(3))[0]=e[0],t[1]=e[1],t[2]=e[2],t},t.create=function(e,t,r){var o=new n(3);e&&(o[0]=e);t&&(o[1]=t);r&&(o[2]=r);return o},t.cross=function(e,t,r){r=r||new n(3);var o=e[2]*t[0]-e[0]*t[2],u=e[0]*t[1]-e[1]*t[0];return r[0]=e[1]*t[2]-e[2]*t[1],r[1]=o,r[2]=u,r},t.distance=function(e,t){var r=e[0]-t[0],n=e[1]-t[1],o=e[2]-t[2];return Math.sqrt(r*r+n*n+o*o)},t.distanceSq=function(e,t){var r=e[0]-t[0],n=e[1]-t[1],o=e[2]-t[2];return r*r+n*n+o*o},t.divide=function(e,t,r){return(r=r||new n(3))[0]=e[0]/t[0],r[1]=e[1]/t[1],r[2]=e[2]/t[2],r},t.divScalar=function(e,t,r){return(r=r||new n(3))[0]=e[0]/t,r[1]=e[1]/t,r[2]=e[2]/t,r},t.dot=function(e,t){return e[0]*t[0]+e[1]*t[1]+e[2]*t[2]},t.lerp=function(e,t,r,o){return(o=o||new n(3))[0]=e[0]+r*(t[0]-e[0]),o[1]=e[1]+r*(t[1]-e[1]),o[2]=e[2]+r*(t[2]-e[2]),o},t.lerpV=function(e,t,r,o){return(o=o||new n(3))[0]=e[0]+r[0]*(t[0]-e[0]),o[1]=e[1]+r[1]*(t[1]-e[1]),o[2]=e[2]+r[2]*(t[2]-e[2]),o},t.length=function(e){return Math.sqrt(e[0]*e[0]+e[1]*e[1]+e[2]*e[2])},t.lengthSq=function(e){return e[0]*e[0]+e[1]*e[1]+e[2]*e[2]},t.max=function(e,t,r){return(r=r||new n(3))[0]=Math.max(e[0],t[0]),r[1]=Math.max(e[1],t[1]),r[2]=Math.max(e[2],t[2]),r},t.min=function(e,t,r){return(r=r||new n(3))[0]=Math.min(e[0],t[0]),r[1]=Math.min(e[1],t[1]),r[2]=Math.min(e[2],t[2]),r},t.mulScalar=function(e,t,r){return(r=r||new n(3))[0]=e[0]*t,r[1]=e[1]*t,r[2]=e[2]*t,r},t.multiply=function(e,t,r){return(r=r||new n(3))[0]=e[0]*t[0],r[1]=e[1]*t[1],r[2]=e[2]*t[2],r},t.negate=function(e,t){return(t=t||new n(3))[0]=-e[0],t[1]=-e[1],t[2]=-e[2],t},t.normalize=function(e,t){t=t||new n(3);var r=e[0]*e[0]+e[1]*e[1]+e[2]*e[2],o=Math.sqrt(r);o>1e-5?(t[0]=e[0]/o,t[1]=e[1]/o,t[2]=e[2]/o):(t[0]=0,t[1]=0,t[2]=0);return t},t.setDefaultType=function(e){var t=n;return n=e,t},t.subtract=function(e,t,r){return(r=r||new n(3))[0]=e[0]-t[0],r[1]=e[1]-t[1],r[2]=e[2]-t[2],r};var n=Float32Array},function(e,t,r){"use strict";t.__esModule=!0,t.isWebGL1=function(e){return!e.texStorage2D},t.isWebGL2=function(e){return!!e.texStorage2D},t.glEnumToString=void 0;var n,o,u=(n={},o={},function(e,t){return function(e){var t=e.constructor.name;if(!n[t]){for(var r in e)if("number"==typeof e[r]){var u=o[e[r]];o[e[r]]=u?"".concat(u," | ").concat(r):r}n[t]=!0}}(e),o[t]||"0x"+t.toString(16)});t.glEnumToString=u},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.createAttributeSetters=oe,t.createProgram=H,t.createProgramFromScripts=function(e,t,r,n,o){for(var u=G(r,n,o),i=[],a=0;a<t.length;++a){var f=q(e,t[a],e[X[a]],u.errorCallback);if(!f)return null;i.push(f)}return H(e,i,u)},t.createProgramFromSources=V,t.createProgramInfo=function(e,t,r,n,o){var u=G(r,n,o),i=!0;if(t=t.map((function(e){if(e.indexOf("\n")<0){var t=y(e);t?e=t.text:(u.errorCallback("no element with id: "+e),i=!1)}return e})),!i)return null;var a=V(e,t,u);if(!a)return null;return ie(e,a)},t.createProgramInfoFromProgram=ie,t.createUniformSetters=$,t.createUniformBlockSpecFromProgram=J,t.createUniformBlockInfoFromProgram=ee,t.createUniformBlockInfo=function(e,t,r){return ee(e,t.program,t.uniformBlockSpec,r)},t.createTransformFeedback=function(e,t,r){var n=e.createTransformFeedback();return e.bindTransformFeedback(36386,n),e.useProgram(t.program),Z(e,t,r),e.bindTransformFeedback(36386,null),n},t.createTransformFeedbackInfo=K,t.bindTransformFeedbackInfo=Z,t.setAttributes=ue,t.setBuffersAndAttributes=function(e,t,r){r.vertexArrayObject?e.bindVertexArray(r.vertexArrayObject):(ue(t.attribSetters||t,r.attribs),r.indices&&e.bindBuffer(34963,r.indices))},t.setUniforms=re,t.setUniformBlock=function(e,t,r){te(e,t,r)&&e.bufferData(m,r.array,35048)},t.setBlockUniforms=function(e,t){var r=e.uniforms;for(var n in t){var o=r[n];if(o){var u=t[n];u.length?o.set(u):o[0]=u}}},t.bindUniformBlock=te,t.setUniformsAndBindTextures=void 0;var o=a(r(3)),u=a(r(0));function i(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return i=function(){return e},e}function a(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=i();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var a=o?Object.getOwnPropertyDescriptor(e,u):null;a&&(a.get||a.set)?Object.defineProperty(r,u,a):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}function f(e){return function(e){if(Array.isArray(e))return c(e)}(e)||function(e){if("undefined"!=typeof Symbol&&Symbol.iterator in Object(e))return Array.from(e)}(e)||function(e,t){if(!e)return;if("string"==typeof e)return c(e,t);var r=Object.prototype.toString.call(e).slice(8,-1);"Object"===r&&e.constructor&&(r=e.constructor.name);if("Map"===r||"Set"===r)return Array.from(e);if("Arguments"===r||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r))return c(e,t)}(e)||function(){throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()}function c(e,t){(null==t||t>e.length)&&(t=e.length);for(var r=0,n=new Array(t);r<t;r++)n[r]=e[r];return n}var l=u.error,s=u.warn;function y(e){return"undefined"!=typeof document&&document.getElementById?document.getElementById(e):null}var v=33984,b=34962,m=35345,p=5126,d=5124,x=5125,w=3553,h=34067,F=32879,E=35866,A={};function j(e,t){return A[t].bindPoint}function O(e,t){return function(r){e.uniform1i(t,r)}}function _(e,t){return function(r){e.uniform1iv(t,r)}}function S(e,t){return function(r){e.uniform2iv(t,r)}}function M(e,t){return function(r){e.uniform3iv(t,r)}}function R(e,t){return function(r){e.uniform4iv(t,r)}}function P(e,t,r,n){var i=j(0,t);return o.isWebGL2(e)?function(t){var o,a;u.isTexture(e,t)?(o=t,a=null):(o=t.texture,a=t.sampler),e.uniform1i(n,r),e.activeTexture(v+r),e.bindTexture(i,o),e.bindSampler(r,a)}:function(t){e.uniform1i(n,r),e.activeTexture(v+r),e.bindTexture(i,t)}}function T(e,t,r,n,i){for(var a=j(0,t),f=new Int32Array(i),c=0;c<i;++c)f[c]=r+c;return o.isWebGL2(e)?function(t){e.uniform1iv(n,f),t.forEach((function(t,n){var o,i;e.activeTexture(v+f[n]),u.isTexture(e,t)?(o=t,i=null):(o=t.texture,i=t.sampler),e.bindSampler(r,i),e.bindTexture(a,o)}))}:function(t){e.uniform1iv(n,f),t.forEach((function(t,r){e.activeTexture(v+f[r]),e.bindTexture(a,t)}))}}function g(e,t){return function(r){if(r.value)switch(e.disableVertexAttribArray(t),r.value.length){case 4:e.vertexAttrib4fv(t,r.value);break;case 3:e.vertexAttrib3fv(t,r.value);break;case 2:e.vertexAttrib2fv(t,r.value);break;case 1:e.vertexAttrib1fv(t,r.value);break;default:throw new Error("the length of a float constant value must be between 1 and 4!")}else e.bindBuffer(b,r.buffer),e.enableVertexAttribArray(t),e.vertexAttribPointer(t,r.numComponents||r.size,r.type||p,r.normalize||!1,r.stride||0,r.offset||0),void 0!==r.divisor&&e.vertexAttribDivisor(t,r.divisor)}}function z(e,t){return function(r){if(r.value){if(e.disableVertexAttribArray(t),4!==r.value.length)throw new Error("The length of an integer constant value must be 4!");e.vertexAttrib4iv(t,r.value)}else e.bindBuffer(b,r.buffer),e.enableVertexAttribArray(t),e.vertexAttribIPointer(t,r.numComponents||r.size,r.type||d,r.stride||0,r.offset||0),void 0!==r.divisor&&e.vertexAttribDivisor(t,r.divisor)}}function U(e,t){return function(r){if(r.value){if(e.disableVertexAttribArray(t),4!==r.value.length)throw new Error("The length of an unsigned integer constant value must be 4!");e.vertexAttrib4uiv(t,r.value)}else e.bindBuffer(b,r.buffer),e.enableVertexAttribArray(t),e.vertexAttribIPointer(t,r.numComponents||r.size,r.type||x,r.stride||0,r.offset||0),void 0!==r.divisor&&e.vertexAttribDivisor(t,r.divisor)}}function C(e,t,r){var n=r.size,o=r.count;return function(r){e.bindBuffer(b,r.buffer);for(var u=r.size||r.numComponents||n,i=u/o,a=r.type||p,f=A[a].size*u,c=r.normalize||!1,l=r.offset||0,s=f/o,y=0;y<o;++y)e.enableVertexAttribArray(t+y),e.vertexAttribPointer(t+y,i,a,c,f,l+s*y),void 0!==r.divisor&&e.vertexAttribDivisor(t+y,r.divisor)}}A[5126]={Type:Float32Array,size:4,setter:function(e,t){return function(r){e.uniform1f(t,r)}},arraySetter:function(e,t){return function(r){e.uniform1fv(t,r)}}},A[35664]={Type:Float32Array,size:8,setter:function(e,t){return function(r){e.uniform2fv(t,r)}}},A[35665]={Type:Float32Array,size:12,setter:function(e,t){return function(r){e.uniform3fv(t,r)}}},A[35666]={Type:Float32Array,size:16,setter:function(e,t){return function(r){e.uniform4fv(t,r)}}},A[d]={Type:Int32Array,size:4,setter:O,arraySetter:_},A[35667]={Type:Int32Array,size:8,setter:S},A[35668]={Type:Int32Array,size:12,setter:M},A[35669]={Type:Int32Array,size:16,setter:R},A[5125]={Type:Uint32Array,size:4,setter:function(e,t){return function(r){e.uniform1ui(t,r)}},arraySetter:function(e,t){return function(r){e.uniform1uiv(t,r)}}},A[36294]={Type:Uint32Array,size:8,setter:function(e,t){return function(r){e.uniform2uiv(t,r)}}},A[36295]={Type:Uint32Array,size:12,setter:function(e,t){return function(r){e.uniform3uiv(t,r)}}},A[36296]={Type:Uint32Array,size:16,setter:function(e,t){return function(r){e.uniform4uiv(t,r)}}},A[35670]={Type:Uint32Array,size:4,setter:O,arraySetter:_},A[35671]={Type:Uint32Array,size:8,setter:S},A[35672]={Type:Uint32Array,size:12,setter:M},A[35673]={Type:Uint32Array,size:16,setter:R},A[35674]={Type:Float32Array,size:16,setter:function(e,t){return function(r){e.uniformMatrix2fv(t,!1,r)}}},A[35675]={Type:Float32Array,size:36,setter:function(e,t){return function(r){e.uniformMatrix3fv(t,!1,r)}}},A[35676]={Type:Float32Array,size:64,setter:function(e,t){return function(r){e.uniformMatrix4fv(t,!1,r)}}},A[35685]={Type:Float32Array,size:24,setter:function(e,t){return function(r){e.uniformMatrix2x3fv(t,!1,r)}}},A[35686]={Type:Float32Array,size:32,setter:function(e,t){return function(r){e.uniformMatrix2x4fv(t,!1,r)}}},A[35687]={Type:Float32Array,size:24,setter:function(e,t){return function(r){e.uniformMatrix3x2fv(t,!1,r)}}},A[35688]={Type:Float32Array,size:48,setter:function(e,t){return function(r){e.uniformMatrix3x4fv(t,!1,r)}}},A[35689]={Type:Float32Array,size:32,setter:function(e,t){return function(r){e.uniformMatrix4x2fv(t,!1,r)}}},A[35690]={Type:Float32Array,size:48,setter:function(e,t){return function(r){e.uniformMatrix4x3fv(t,!1,r)}}},A[35678]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:w},A[35680]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:h},A[35679]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:F},A[35682]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:w},A[36289]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:E},A[36292]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:E},A[36293]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:h},A[36298]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:w},A[36299]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:F},A[36300]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:h},A[36303]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:E},A[36306]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:w},A[36307]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:F},A[36308]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:h},A[36311]={Type:null,size:0,setter:P,arraySetter:T,bindPoint:E};var k={};k[5126]={size:4,setter:g},k[35664]={size:8,setter:g},k[35665]={size:12,setter:g},k[35666]={size:16,setter:g},k[d]={size:4,setter:z},k[35667]={size:8,setter:z},k[35668]={size:12,setter:z},k[35669]={size:16,setter:z},k[5125]={size:4,setter:U},k[36294]={size:8,setter:U},k[36295]={size:12,setter:U},k[36296]={size:16,setter:U},k[35670]={size:4,setter:z},k[35671]={size:8,setter:z},k[35672]={size:12,setter:z},k[35673]={size:16,setter:z},k[35674]={size:4,setter:C,count:2},k[35675]={size:9,setter:C,count:3},k[35676]={size:16,setter:C,count:4};var W=/ERROR:\s*\d+:(\d+)/gi;function I(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:"",r=arguments.length>2&&void 0!==arguments[2]?arguments[2]:0,n=f(t.matchAll(W)),o=new Map(n.map((function(e,r){var o=parseInt(e[1]),u=n[r+1],i=u?u.index:t.length;return[o-1,t.substring(e.index,i)]})));return e.split("\n").map((function(e,t){var n=o.get(t);return"".concat(t+1+r,": ").concat(e).concat(n?"\n\n^^^ ".concat(n):"")})).join("\n")}var B=/^[ \t]*\n/;function L(e,t,r,n){var u=n||l,i=e.createShader(r),a=0;if(B.test(t)&&(a=1,t=t.replace(B,"")),e.shaderSource(i,t),e.compileShader(i),!e.getShaderParameter(i,35713)){var f=e.getShaderInfoLog(i);return u("".concat(I(t,f,a),"\nError compiling ").concat(o.glEnumToString(e,r),": ").concat(f)),e.deleteShader(i),null}return i}function G(e,t,r){var n,o;if("function"==typeof t&&(r=t,t=void 0),"function"==typeof e)r=e,e=void 0;else if(e&&!Array.isArray(e)){if(e.errorCallback)return e;var u=e;r=u.errorCallback,e=u.attribLocations,n=u.transformFeedbackVaryings,o=u.transformFeedbackMode}var i={errorCallback:r||l,transformFeedbackVaryings:n,transformFeedbackMode:o};if(e){var a={};Array.isArray(e)?e.forEach((function(e,r){a[e]=t?t[r]:r})):a=e,i.attribLocations=a}return i}var X=["VERTEX_SHADER","FRAGMENT_SHADER"];function D(e,t){return t.indexOf("frag")>=0?35632:t.indexOf("vert")>=0?35633:void 0}function N(e,t){t.forEach((function(t){e.deleteShader(t)}))}function H(e,t,r,n,i){for(var a=G(r,n,i),f=[],c=[],l=0;l<t.length;++l){var s=t[l];if("string"==typeof s){var v=y(s),b=v?v.text:s,m=e[X[l]];v&&v.type&&(m=D(0,v.type)||m),s=L(e,b,m,a.errorCallback),c.push(s)}u.isShader(e,s)&&f.push(s)}if(f.length!==t.length)return a.errorCallback("not enough shaders for program"),N(e,c),null;var p=e.createProgram();f.forEach((function(t){e.attachShader(p,t)})),a.attribLocations&&Object.keys(a.attribLocations).forEach((function(t){e.bindAttribLocation(p,a.attribLocations[t],t)}));var d=a.transformFeedbackVaryings;if(d&&(d.attribs&&(d=d.attribs),Array.isArray(d)||(d=Object.keys(d)),e.transformFeedbackVaryings(p,d,a.transformFeedbackMode||35981)),e.linkProgram(p),!e.getProgramParameter(p,35714)){var x=e.getProgramInfoLog(p);return a.errorCallback("".concat(f.map((function(t){var r=I(e.getShaderSource(t),"",0),n=e.getShaderParameter(t,e.SHADER_TYPE);return"".concat(o.glEnumToString(e,n),"\n").concat(r,"}")})).join("\n"),"\nError in program linking: ").concat(x)),e.deleteProgram(p),N(e,c),null}return p}function q(e,t,r,n){var o,u=y(t);if(!u)throw new Error("unknown script element: ".concat(t));o=u.text;var i=r||D(0,u.type);if(!i)throw new Error("unknown shader type");return L(e,o,i,n)}function V(e,t,r,n,o){for(var u=G(r,n,o),i=[],a=0;a<t.length;++a){var f=L(e,t[a],e[X[a]],u.errorCallback);if(!f)return null;i.push(f)}return H(e,i,u)}function Y(e){var t=e.name;return t.startsWith("gl_")||t.startsWith("webgl_")}function $(e,t){var r=0;function n(t,n,o){var u,i=n.name.endsWith("[0]"),a=n.type,f=A[a];if(!f)throw new Error("unknown type: 0x".concat(a.toString(16)));if(f.bindPoint){var c=r;r+=n.size,u=i?f.arraySetter(e,a,c,o,n.size):f.setter(e,a,c,o,n.size)}else u=f.arraySetter&&i?f.arraySetter(e,o):f.setter(e,o);return u.location=o,u}for(var o={},u=e.getProgramParameter(t,35718),i=0;i<u;++i){var a=e.getActiveUniform(t,i);if(!Y(a)){var f=a.name;f.endsWith("[0]")&&(f=f.substr(0,f.length-3));var c=e.getUniformLocation(t,a.name);c&&(o[f]=n(0,a,c))}}return o}function K(e,t){for(var r={},n=e.getProgramParameter(t,35971),o=0;o<n;++o){var u=e.getTransformFeedbackVarying(t,o);r[u.name]={index:o,type:u.type,size:u.size}}return r}function Z(e,t,r){for(var n in t.transformFeedbackInfo&&(t=t.transformFeedbackInfo),r.attribs&&(r=r.attribs),r){var o=t[n];if(o){var u=r[n];u.offset?e.bindBufferRange(35982,o.index,u.buffer,u.offset,u.size):e.bindBufferBase(35982,o.index,u.buffer)}}}function J(e,t){for(var r=e.getProgramParameter(t,35718),n=[],o=[],u=0;u<r;++u){o.push(u),n.push({});var i=e.getActiveUniform(t,u);if(Y(i))break;n[u].name=i.name}[["UNIFORM_TYPE","type"],["UNIFORM_SIZE","size"],["UNIFORM_BLOCK_INDEX","blockNdx"],["UNIFORM_OFFSET","offset"]].forEach((function(r){var u=r[0],i=r[1];e.getActiveUniforms(t,o,e[u]).forEach((function(e,t){n[t][i]=e}))}));for(var a={},f=e.getProgramParameter(t,35382),c=0;c<f;++c){var l=e.getActiveUniformBlockName(t,c),s={index:e.getUniformBlockIndex(t,l),usedByVertexShader:e.getActiveUniformBlockParameter(t,c,35396),usedByFragmentShader:e.getActiveUniformBlockParameter(t,c,35398),size:e.getActiveUniformBlockParameter(t,c,35392),uniformIndices:e.getActiveUniformBlockParameter(t,c,35395)};s.used=s.usedByVertexShader||s.usedByFragmentShader,a[l]=s}return{blockSpecs:a,uniformData:n}}var Q=/\[\d+\]\.$/;function ee(e,t,r,n){var o=r.blockSpecs,u=r.uniformData,i=o[n];if(!i)return s("no uniform block object named:",n),{name:n,uniforms:{}};var a=new ArrayBuffer(i.size),f=e.createBuffer(),c=i.index;e.bindBuffer(m,f),e.uniformBlockBinding(t,i.index,c);var l=n+".";Q.test(l)&&(l=l.replace(Q,"."));var y={};return i.uniformIndices.forEach((function(e){var t=u[e],r=A[t.type],n=r.Type,o=t.size*r.size,i=t.name;i.substr(0,l.length)===l&&(i=i.substr(l.length)),y[i]=new n(a,t.offset,o/n.BYTES_PER_ELEMENT)})),{name:n,array:a,asFloat:new Float32Array(a),buffer:f,uniforms:y}}function te(e,t,r){var n=(t.uniformBlockSpec||t).blockSpecs[r.name];if(n){var o=n.index;return e.bindBufferRange(m,o,r.buffer,r.offset||0,r.array.byteLength),!0}return!1}function re(e,t){for(var r=e.uniformSetters||e,n=arguments.length,o=1;o<n;++o){var u=arguments[o];if(Array.isArray(u))for(var i=u.length,a=0;a<i;++a)re(r,u[a]);else for(var f in u){var c=r[f];c&&c(u[f])}}}var ne=re;function oe(e,t){for(var r={},n=e.getProgramParameter(t,35721),o=0;o<n;++o){var u=e.getActiveAttrib(t,o);if(!Y(u)){var i=e.getAttribLocation(t,u.name),a=k[u.type],f=a.setter(e,i,a);f.location=i,r[u.name]=f}}return r}function ue(e,t){for(var r in t){var n=e[r];n&&n(t[r])}}function ie(e,t){var r={program:t,uniformSetters:$(e,t),attribSetters:oe(e,t)};return o.isWebGL2(e)&&(r.uniformBlockSpec=J(e,t),r.transformFeedbackInfo=K(e,t)),r}t.setUniformsAndBindTextures=ne},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.axisRotate=function(e,t,r,n){n=n||new c(16);var o=t[0],u=t[1],i=t[2],a=Math.sqrt(o*o+u*u+i*i),f=(o/=a)*o,l=(u/=a)*u,s=(i/=a)*i,y=Math.cos(r),v=Math.sin(r),b=1-y,m=f+(1-f)*y,p=o*u*b+i*v,d=o*i*b-u*v,x=o*u*b-i*v,w=l+(1-l)*y,h=u*i*b+o*v,F=o*i*b+u*v,E=u*i*b-o*v,A=s+(1-s)*y,j=e[0],O=e[1],_=e[2],S=e[3],M=e[4],R=e[5],P=e[6],T=e[7],g=e[8],z=e[9],U=e[10],C=e[11];n[0]=m*j+p*M+d*g,n[1]=m*O+p*R+d*z,n[2]=m*_+p*P+d*U,n[3]=m*S+p*T+d*C,n[4]=x*j+w*M+h*g,n[5]=x*O+w*R+h*z,n[6]=x*_+w*P+h*U,n[7]=x*S+w*T+h*C,n[8]=F*j+E*M+A*g,n[9]=F*O+E*R+A*z,n[10]=F*_+E*P+A*U,n[11]=F*S+E*T+A*C,e!==n&&(n[12]=e[12],n[13]=e[13],n[14]=e[14],n[15]=e[15]);return n},t.axisRotation=function(e,t,r){r=r||new c(16);var n=e[0],o=e[1],u=e[2],i=Math.sqrt(n*n+o*o+u*u),a=(n/=i)*n,f=(o/=i)*o,l=(u/=i)*u,s=Math.cos(t),y=Math.sin(t),v=1-s;return r[0]=a+(1-a)*s,r[1]=n*o*v+u*y,r[2]=n*u*v-o*y,r[3]=0,r[4]=n*o*v-u*y,r[5]=f+(1-f)*s,r[6]=o*u*v+n*y,r[7]=0,r[8]=n*u*v+o*y,r[9]=o*u*v-n*y,r[10]=l+(1-l)*s,r[11]=0,r[12]=0,r[13]=0,r[14]=0,r[15]=1,r},t.copy=l,t.frustum=function(e,t,r,n,o,u,i){i=i||new c(16);var a=t-e,f=n-r,l=o-u;return i[0]=2*o/a,i[1]=0,i[2]=0,i[3]=0,i[4]=0,i[5]=2*o/f,i[6]=0,i[7]=0,i[8]=(e+t)/a,i[9]=(n+r)/f,i[10]=u/l,i[11]=-1,i[12]=0,i[13]=0,i[14]=o*u/l,i[15]=0,i},t.getAxis=function(e,t,r){r=r||o.create();var n=4*t;return r[0]=e[n+0],r[1]=e[n+1],r[2]=e[n+2],r},t.getTranslation=function(e,t){return(t=t||o.create())[0]=e[12],t[1]=e[13],t[2]=e[14],t},t.identity=s,t.inverse=y,t.lookAt=function(e,t,r,n){return n=n||new c(16),i=i||o.create(),a=a||o.create(),f=f||o.create(),o.normalize(o.subtract(e,t,f),f),o.normalize(o.cross(r,f,i),i),o.normalize(o.cross(f,i,a),a),n[0]=i[0],n[1]=i[1],n[2]=i[2],n[3]=0,n[4]=a[0],n[5]=a[1],n[6]=a[2],n[7]=0,n[8]=f[0],n[9]=f[1],n[10]=f[2],n[11]=0,n[12]=e[0],n[13]=e[1],n[14]=e[2],n[15]=1,n},t.multiply=function(e,t,r){r=r||new c(16);var n=e[0],o=e[1],u=e[2],i=e[3],a=e[4],f=e[5],l=e[6],s=e[7],y=e[8],v=e[9],b=e[10],m=e[11],p=e[12],d=e[13],x=e[14],w=e[15],h=t[0],F=t[1],E=t[2],A=t[3],j=t[4],O=t[5],_=t[6],S=t[7],M=t[8],R=t[9],P=t[10],T=t[11],g=t[12],z=t[13],U=t[14],C=t[15];return r[0]=n*h+a*F+y*E+p*A,r[1]=o*h+f*F+v*E+d*A,r[2]=u*h+l*F+b*E+x*A,r[3]=i*h+s*F+m*E+w*A,r[4]=n*j+a*O+y*_+p*S,r[5]=o*j+f*O+v*_+d*S,r[6]=u*j+l*O+b*_+x*S,r[7]=i*j+s*O+m*_+w*S,r[8]=n*M+a*R+y*P+p*T,r[9]=o*M+f*R+v*P+d*T,r[10]=u*M+l*R+b*P+x*T,r[11]=i*M+s*R+m*P+w*T,r[12]=n*g+a*z+y*U+p*C,r[13]=o*g+f*z+v*U+d*C,r[14]=u*g+l*z+b*U+x*C,r[15]=i*g+s*z+m*U+w*C,r},t.negate=function(e,t){return(t=t||new c(16))[0]=-e[0],t[1]=-e[1],t[2]=-e[2],t[3]=-e[3],t[4]=-e[4],t[5]=-e[5],t[6]=-e[6],t[7]=-e[7],t[8]=-e[8],t[9]=-e[9],t[10]=-e[10],t[11]=-e[11],t[12]=-e[12],t[13]=-e[13],t[14]=-e[14],t[15]=-e[15],t},t.ortho=function(e,t,r,n,o,u,i){return(i=i||new c(16))[0]=2/(t-e),i[1]=0,i[2]=0,i[3]=0,i[4]=0,i[5]=2/(n-r),i[6]=0,i[7]=0,i[8]=0,i[9]=0,i[10]=2/(o-u),i[11]=0,i[12]=(t+e)/(e-t),i[13]=(n+r)/(r-n),i[14]=(u+o)/(o-u),i[15]=1,i},t.perspective=function(e,t,r,n,o){o=o||new c(16);var u=Math.tan(.5*Math.PI-.5*e),i=1/(r-n);return o[0]=u/t,o[1]=0,o[2]=0,o[3]=0,o[4]=0,o[5]=u,o[6]=0,o[7]=0,o[8]=0,o[9]=0,o[10]=(r+n)*i,o[11]=-1,o[12]=0,o[13]=0,o[14]=r*n*i*2,o[15]=0,o},t.rotateX=function(e,t,r){r=r||new c(16);var n=e[4],o=e[5],u=e[6],i=e[7],a=e[8],f=e[9],l=e[10],s=e[11],y=Math.cos(t),v=Math.sin(t);r[4]=y*n+v*a,r[5]=y*o+v*f,r[6]=y*u+v*l,r[7]=y*i+v*s,r[8]=y*a-v*n,r[9]=y*f-v*o,r[10]=y*l-v*u,r[11]=y*s-v*i,e!==r&&(r[0]=e[0],r[1]=e[1],r[2]=e[2],r[3]=e[3],r[12]=e[12],r[13]=e[13],r[14]=e[14],r[15]=e[15]);return r},t.rotateY=function(e,t,r){r=r||new c(16);var n=e[0],o=e[1],u=e[2],i=e[3],a=e[8],f=e[9],l=e[10],s=e[11],y=Math.cos(t),v=Math.sin(t);r[0]=y*n-v*a,r[1]=y*o-v*f,r[2]=y*u-v*l,r[3]=y*i-v*s,r[8]=y*a+v*n,r[9]=y*f+v*o,r[10]=y*l+v*u,r[11]=y*s+v*i,e!==r&&(r[4]=e[4],r[5]=e[5],r[6]=e[6],r[7]=e[7],r[12]=e[12],r[13]=e[13],r[14]=e[14],r[15]=e[15]);return r},t.rotateZ=function(e,t,r){r=r||new c(16);var n=e[0],o=e[1],u=e[2],i=e[3],a=e[4],f=e[5],l=e[6],s=e[7],y=Math.cos(t),v=Math.sin(t);r[0]=y*n+v*a,r[1]=y*o+v*f,r[2]=y*u+v*l,r[3]=y*i+v*s,r[4]=y*a-v*n,r[5]=y*f-v*o,r[6]=y*l-v*u,r[7]=y*s-v*i,e!==r&&(r[8]=e[8],r[9]=e[9],r[10]=e[10],r[11]=e[11],r[12]=e[12],r[13]=e[13],r[14]=e[14],r[15]=e[15]);return r},t.rotationX=function(e,t){t=t||new c(16);var r=Math.cos(e),n=Math.sin(e);return t[0]=1,t[1]=0,t[2]=0,t[3]=0,t[4]=0,t[5]=r,t[6]=n,t[7]=0,t[8]=0,t[9]=-n,t[10]=r,t[11]=0,t[12]=0,t[13]=0,t[14]=0,t[15]=1,t},t.rotationY=function(e,t){t=t||new c(16);var r=Math.cos(e),n=Math.sin(e);return t[0]=r,t[1]=0,t[2]=-n,t[3]=0,t[4]=0,t[5]=1,t[6]=0,t[7]=0,t[8]=n,t[9]=0,t[10]=r,t[11]=0,t[12]=0,t[13]=0,t[14]=0,t[15]=1,t},t.rotationZ=function(e,t){t=t||new c(16);var r=Math.cos(e),n=Math.sin(e);return t[0]=r,t[1]=n,t[2]=0,t[3]=0,t[4]=-n,t[5]=r,t[6]=0,t[7]=0,t[8]=0,t[9]=0,t[10]=1,t[11]=0,t[12]=0,t[13]=0,t[14]=0,t[15]=1,t},t.scale=function(e,t,r){r=r||new c(16);var n=t[0],o=t[1],u=t[2];r[0]=n*e[0],r[1]=n*e[1],r[2]=n*e[2],r[3]=n*e[3],r[4]=o*e[4],r[5]=o*e[5],r[6]=o*e[6],r[7]=o*e[7],r[8]=u*e[8],r[9]=u*e[9],r[10]=u*e[10],r[11]=u*e[11],e!==r&&(r[12]=e[12],r[13]=e[13],r[14]=e[14],r[15]=e[15]);return r},t.scaling=function(e,t){return(t=t||new c(16))[0]=e[0],t[1]=0,t[2]=0,t[3]=0,t[4]=0,t[5]=e[1],t[6]=0,t[7]=0,t[8]=0,t[9]=0,t[10]=e[2],t[11]=0,t[12]=0,t[13]=0,t[14]=0,t[15]=1,t},t.setAxis=function(e,t,r,n){n!==e&&(n=l(e,n));var o=4*r;return n[o+0]=t[0],n[o+1]=t[1],n[o+2]=t[2],n},t.setDefaultType=function(e){var t=c;return c=e,t},t.setTranslation=function(e,t,r){r=r||s(),e!==r&&(r[0]=e[0],r[1]=e[1],r[2]=e[2],r[3]=e[3],r[4]=e[4],r[5]=e[5],r[6]=e[6],r[7]=e[7],r[8]=e[8],r[9]=e[9],r[10]=e[10],r[11]=e[11]);return r[12]=t[0],r[13]=t[1],r[14]=t[2],r[15]=1,r},t.transformDirection=function(e,t,r){r=r||o.create();var n=t[0],u=t[1],i=t[2];return r[0]=n*e[0]+u*e[4]+i*e[8],r[1]=n*e[1]+u*e[5]+i*e[9],r[2]=n*e[2]+u*e[6]+i*e[10],r},t.transformNormal=function(e,t,r){r=r||o.create();var n=y(e),u=t[0],i=t[1],a=t[2];return r[0]=u*n[0]+i*n[1]+a*n[2],r[1]=u*n[4]+i*n[5]+a*n[6],r[2]=u*n[8]+i*n[9]+a*n[10],r},t.transformPoint=function(e,t,r){r=r||o.create();var n=t[0],u=t[1],i=t[2],a=n*e[3]+u*e[7]+i*e[11]+e[15];return r[0]=(n*e[0]+u*e[4]+i*e[8]+e[12])/a,r[1]=(n*e[1]+u*e[5]+i*e[9]+e[13])/a,r[2]=(n*e[2]+u*e[6]+i*e[10]+e[14])/a,r},t.translate=function(e,t,r){r=r||new c(16);var n=t[0],o=t[1],u=t[2],i=e[0],a=e[1],f=e[2],l=e[3],s=e[4],y=e[5],v=e[6],b=e[7],m=e[8],p=e[9],d=e[10],x=e[11],w=e[12],h=e[13],F=e[14],E=e[15];e!==r&&(r[0]=i,r[1]=a,r[2]=f,r[3]=l,r[4]=s,r[5]=y,r[6]=v,r[7]=b,r[8]=m,r[9]=p,r[10]=d,r[11]=x);return r[12]=i*n+s*o+m*u+w,r[13]=a*n+y*o+p*u+h,r[14]=f*n+v*o+d*u+F,r[15]=l*n+b*o+x*u+E,r},t.translation=function(e,t){return(t=t||new c(16))[0]=1,t[1]=0,t[2]=0,t[3]=0,t[4]=0,t[5]=1,t[6]=0,t[7]=0,t[8]=0,t[9]=0,t[10]=1,t[11]=0,t[12]=e[0],t[13]=e[1],t[14]=e[2],t[15]=1,t},t.transpose=function(e,t){if((t=t||new c(16))===e){var r;return r=e[1],e[1]=e[4],e[4]=r,r=e[2],e[2]=e[8],e[8]=r,r=e[3],e[3]=e[12],e[12]=r,r=e[6],e[6]=e[9],e[9]=r,r=e[7],e[7]=e[13],e[13]=r,r=e[11],e[11]=e[14],e[14]=r,t}var n=e[0],o=e[1],u=e[2],i=e[3],a=e[4],f=e[5],l=e[6],s=e[7],y=e[8],v=e[9],b=e[10],m=e[11],p=e[12],d=e[13],x=e[14],w=e[15];return t[0]=n,t[1]=a,t[2]=y,t[3]=p,t[4]=o,t[5]=f,t[6]=v,t[7]=d,t[8]=u,t[9]=l,t[10]=b,t[11]=x,t[12]=i,t[13]=s,t[14]=m,t[15]=w,t};var o=function(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=u();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var i in e)if(Object.prototype.hasOwnProperty.call(e,i)){var a=o?Object.getOwnPropertyDescriptor(e,i):null;a&&(a.get||a.set)?Object.defineProperty(r,i,a):r[i]=e[i]}r.default=e,t&&t.set(e,r);return r}(r(2));function u(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return u=function(){return e},e}var i,a,f,c=Float32Array;function l(e,t){return(t=t||new c(16))[0]=e[0],t[1]=e[1],t[2]=e[2],t[3]=e[3],t[4]=e[4],t[5]=e[5],t[6]=e[6],t[7]=e[7],t[8]=e[8],t[9]=e[9],t[10]=e[10],t[11]=e[11],t[12]=e[12],t[13]=e[13],t[14]=e[14],t[15]=e[15],t}function s(e){return(e=e||new c(16))[0]=1,e[1]=0,e[2]=0,e[3]=0,e[4]=0,e[5]=1,e[6]=0,e[7]=0,e[8]=0,e[9]=0,e[10]=1,e[11]=0,e[12]=0,e[13]=0,e[14]=0,e[15]=1,e}function y(e,t){t=t||new c(16);var r=e[0],n=e[1],o=e[2],u=e[3],i=e[4],a=e[5],f=e[6],l=e[7],s=e[8],y=e[9],v=e[10],b=e[11],m=e[12],p=e[13],d=e[14],x=e[15],w=v*x,h=d*b,F=f*x,E=d*l,A=f*b,j=v*l,O=o*x,_=d*u,S=o*b,M=v*u,R=o*l,P=f*u,T=s*p,g=m*y,z=i*p,U=m*a,C=i*y,k=s*a,W=r*p,I=m*n,B=r*y,L=s*n,G=r*a,X=i*n,D=w*a+E*y+A*p-(h*a+F*y+j*p),N=h*n+O*y+M*p-(w*n+_*y+S*p),H=F*n+_*a+R*p-(E*n+O*a+P*p),q=j*n+S*a+P*y-(A*n+M*a+R*y),V=1/(r*D+i*N+s*H+m*q);return t[0]=V*D,t[1]=V*N,t[2]=V*H,t[3]=V*q,t[4]=V*(h*i+F*s+j*m-(w*i+E*s+A*m)),t[5]=V*(w*r+_*s+S*m-(h*r+O*s+M*m)),t[6]=V*(E*r+O*i+P*m-(F*r+_*i+R*m)),t[7]=V*(A*r+M*i+R*s-(j*r+S*i+P*s)),t[8]=V*(T*l+U*b+C*x-(g*l+z*b+k*x)),t[9]=V*(g*u+W*b+L*x-(T*u+I*b+B*x)),t[10]=V*(z*u+I*l+G*x-(U*u+W*l+X*x)),t[11]=V*(k*u+B*l+X*b-(C*u+L*l+G*b)),t[12]=V*(z*v+k*d+g*f-(C*d+T*f+U*v)),t[13]=V*(B*d+T*o+I*v-(W*v+L*d+g*o)),t[14]=V*(W*f+X*d+U*o-(G*d+z*o+I*f)),t[15]=V*(G*v+C*o+L*f-(B*f+X*v+k*o)),t}},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.createAttribsFromArrays=w,t.createBuffersFromArrays=function(e,t){var r={};Object.keys(t).forEach((function(n){r[n]=F(e,t[n],n)})),t.indices?(r.numElements=t.indices.length,r.elementType=o.getGLTypeForTypedArray(x(t.indices),"indices")):r.numElements=function(e){var t,r;for(r=0;r<h.length&&!((t=h[r])in e);++r);r===h.length&&(t=Object.keys(e)[0]);var n=e[t],o=v(n).length,u=d(n,t),i=o/u;if(o%u>0)throw new Error("numComponents ".concat(u," not correct for length ").concat(o));return i}(t);return r},t.createBufferFromArray=F,t.createBufferFromTypedArray=s,t.createBufferInfoFromArrays=function(e,t,r){var n=w(e,t),u=Object.assign({},r||{});u.attribs=Object.assign({},r?r.attribs:{},n);var i=t.indices;if(i){var a=x(i,"indices");u.indices=s(e,a,34963),u.numElements=a.length,u.elementType=o.getGLTypeForTypedArray(a)}else u.numElements||(u.numElements=function(e,t){var r,n;for(n=0;n<h.length&&!((r=h[n])in t)&&!((r=c.attribPrefix+r)in t);++n);n===h.length&&(r=Object.keys(t)[0]);var o=t[r];e.bindBuffer(f,o.buffer);var u=e.getBufferParameter(f,34660);e.bindBuffer(f,null);var i=(y=o.type,5120===y||5121===y?1:5122===y||5123===y?2:5124===y||5125===y||5126===y?4:0),a=u/i,l=o.numComponents||o.size,s=a/l;var y;if(s%1!=0)throw new Error("numComponents ".concat(l," not correct for length ").concat(length));return s}(e,u.attribs));return u},t.setAttribInfoBufferFromArray=function(e,t,r,n){r=x(r),void 0!==n?(e.bindBuffer(f,t.buffer),e.bufferSubData(f,n,r)):l(e,f,t.buffer,r,t.drawType)},t.setAttributePrefix=function(e){c.attribPrefix=e},t.setAttributeDefaults_=function(e){u.copyExistingProperties(e,c)},t.getNumComponents_=d,t.getArray_=v;var o=a(r(1)),u=a(r(0));function i(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return i=function(){return e},e}function a(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=i();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var a=o?Object.getOwnPropertyDescriptor(e,u):null;a&&(a.get||a.set)?Object.defineProperty(r,u,a):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}var f=34962,c={attribPrefix:""};function l(e,t,r,n,o){e.bindBuffer(t,r),e.bufferData(t,n,o||35044)}function s(e,t,r,n){if(u.isBuffer(e,t))return t;r=r||f;var o=e.createBuffer();return l(e,r,o,t,n),o}function y(e){return"indices"===e}function v(e){return e.length?e:e.data}var b=/coord|texture/i,m=/color|colour/i;function p(e,t){var r;if(t%(r=b.test(e)?2:m.test(e)?4:3)>0)throw new Error("Can not guess numComponents for attribute '".concat(e,"'. Tried ").concat(r," but ").concat(t," values is not evenly divisible by ").concat(r,". You should specify it."));return r}function d(e,t){return e.numComponents||e.size||p(t,v(e).length)}function x(e,t){if(o.isArrayBuffer(e))return e;if(o.isArrayBuffer(e.data))return e.data;Array.isArray(e)&&(e={data:e});var r=e.type;return r||(r=y(t)?Uint16Array:Float32Array),new r(e.data)}function w(e,t){var r={};return Object.keys(t).forEach((function(n){if(!y(n)){var u=t[n],i=u.attrib||u.name||u.attribName||c.attribPrefix+n;if(u.value){if(!Array.isArray(u.value)&&!o.isArrayBuffer(u.value))throw new Error("array.value is not array or typedarray");r[i]={value:u.value}}else{var a,l,v,b;if(u.buffer&&u.buffer instanceof WebGLBuffer)a=u.buffer,b=u.numComponents||u.size,l=u.type,v=u.normalize;else if("number"==typeof u||"number"==typeof u.data){var m=u.data||u,w=u.type||Float32Array,h=m*w.BYTES_PER_ELEMENT;l=o.getGLTypeForTypedArrayType(w),v=void 0!==u.normalize?u.normalize:(E=w)===Int8Array||E===Uint8Array,b=u.numComponents||u.size||p(n,m),a=e.createBuffer(),e.bindBuffer(f,a),e.bufferData(f,h,u.drawType||35044)}else{var F=x(u,n);a=s(e,F,void 0,u.drawType),l=o.getGLTypeForTypedArray(F),v=void 0!==u.normalize?u.normalize:function(e){return e instanceof Int8Array||e instanceof Uint8Array}(F),b=d(u,n)}r[i]={buffer:a,numComponents:b,type:l,normalize:v,stride:u.stride||0,offset:u.offset||0,divisor:void 0===u.divisor?void 0:u.divisor,drawType:u.drawType}}}var E})),e.bindBuffer(f,null),r}var h=["position","positions","a_position"];function F(e,t,r){var n="indices"===r?34963:f;return s(e,x(t,r),n)}},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.setTextureDefaults_=function(e){i.copyExistingProperties(e,s),e.textureColor&&ye(e.textureColor)},t.createSampler=Fe,t.createSamplers=function(e,t){var r={};return Object.keys(t).forEach((function(n){r[n]=Fe(e,t[n])})),r},t.setSamplerParameters=he,t.createTexture=We,t.setEmptyTexture=ke,t.setTextureFromArray=Ce,t.loadTextureFromUrl=ge,t.setTextureFromElement=_e,t.setTextureFilteringForSize=Ee,t.setTextureParameters=we,t.setDefaultTextureColor=ye,t.createTextures=function(e,t,r){r=r||Se;var n=0,o=[],u={},i={};function a(){0===n&&setTimeout((function(){r(o.length?o:void 0,u,i)}),0)}return Object.keys(t).forEach((function(r){var f,c,l=t[r];("string"==typeof(c=l.src)||Array.isArray(c)&&"string"==typeof c[0])&&(f=function(e,t,u){i[r]=u,--n,e&&o.push(e),a()},++n),u[r]=We(e,l,f)})),a(),u},t.resizeTexture=function(e,t,r,n,o,u){n=n||r.width,o=o||r.height,u=u||r.depth;var i=r.target||E;e.bindTexture(i,t);var a,f=r.level||0,c=r.internalFormat||r.format||p,l=ie(c),s=r.format||l.format,v=r.src;a=v&&(y(v)||Array.isArray(v)&&"number"==typeof v[0])?r.type||le(e,v,l.type):r.type||l.type;if(i===A)for(var b=0;b<6;++b)e.texImage2D(_+b,f,c,n,o,0,s,a,null);else i===j||i===O?e.texImage3D(i,f,c,n,o,u,0,s,a,null):e.texImage2D(i,f,c,n,o,0,s,a,null)},t.canGenerateMipmap=fe,t.canFilter=ce,t.getNumComponentsForFormat=function(e){var t=re[e];if(!t)throw"unknown format: "+e;return t.u},t.getBytesPerElementForInternalFormat=ue,t.getFormatAndTypeForInternalFormat=ie;var o=f(r(3)),u=f(r(1)),i=f(r(0));function a(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return a=function(){return e},e}function f(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=a();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var i=o?Object.getOwnPropertyDescriptor(e,u):null;i&&(i.get||i.set)?Object.defineProperty(r,u,i):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}var c,l,s={textureColor:new Uint8Array([128,192,255,255]),textureOptions:{},crossOrigin:void 0},y=u.isArrayBuffer,v=function(){return c=c||("undefined"!=typeof document&&document.createElement?document.createElement("canvas").getContext("2d"):null)},b=6406,m=6407,p=6408,d=6409,x=6410,w=6402,h=34041,F=33071,E=3553,A=34067,j=32879,O=35866,_=34069,S=10241,M=10240,R=10242,P=10243,T=3317,g=3314,z=32878,U=3316,C=3315,k=32877,W=37443,I=37441,B=37440,L=5120,G=5121,X=5122,D=5123,N=5124,H=5125,q=5126,V=5131,Y=36193,$=33640,K=33319,Z=33320,J=6403,Q=36244,ee=36248,te=36249,re={},ne=re;function oe(e){if(!l){var t={};t[6406]={v:b,h:!0,F:!0,A:[1,2,2,4],type:[G,V,Y,q]},t[6409]={v:d,h:!0,F:!0,A:[1,2,2,4],type:[G,V,Y,q]},t[6410]={v:x,h:!0,F:!0,A:[2,4,4,8],type:[G,V,Y,q]},t[m]={v:m,h:!0,F:!0,A:[3,6,6,12,2],type:[G,V,Y,q,33635]},t[p]={v:p,h:!0,F:!0,A:[4,8,8,16,2,2],type:[G,V,Y,q,32819,32820]},t[6402]={v:w,h:!0,F:!1,A:[2,4],type:[H,D]},t[33321]={v:J,h:!0,F:!0,A:[1],type:[G]},t[36756]={v:J,h:!1,F:!0,A:[1],type:[L]},t[33325]={v:J,h:!1,F:!0,A:[4,2],type:[q,V]},t[33326]={v:J,h:!1,F:!1,A:[4],type:[q]},t[33330]={v:Q,h:!0,F:!1,A:[1],type:[G]},t[33329]={v:Q,h:!0,F:!1,A:[1],type:[L]},t[33332]={v:Q,h:!0,F:!1,A:[2],type:[D]},t[33331]={v:Q,h:!0,F:!1,A:[2],type:[X]},t[33334]={v:Q,h:!0,F:!1,A:[4],type:[H]},t[33333]={v:Q,h:!0,F:!1,A:[4],type:[N]},t[33323]={v:K,h:!0,F:!0,A:[2],type:[G]},t[36757]={v:K,h:!1,F:!0,A:[2],type:[L]},t[33327]={v:K,h:!1,F:!0,A:[8,4],type:[q,V]},t[33328]={v:K,h:!1,F:!1,A:[8],type:[q]},t[33336]={v:Z,h:!0,F:!1,A:[2],type:[G]},t[33335]={v:Z,h:!0,F:!1,A:[2],type:[L]},t[33338]={v:Z,h:!0,F:!1,A:[4],type:[D]},t[33337]={v:Z,h:!0,F:!1,A:[4],type:[X]},t[33340]={v:Z,h:!0,F:!1,A:[8],type:[H]},t[33339]={v:Z,h:!0,F:!1,A:[8],type:[N]},t[32849]={v:m,h:!0,F:!0,A:[3],type:[G]},t[35905]={v:m,h:!1,F:!0,A:[3],type:[G]},t[36194]={v:m,h:!0,F:!0,A:[3,2],type:[G,33635]},t[36758]={v:m,h:!1,F:!0,A:[3],type:[L]},t[35898]={v:m,h:!1,F:!0,A:[12,6,4],type:[q,V,35899]},t[35901]={v:m,h:!1,F:!0,A:[12,6,4],type:[q,V,35902]},t[34843]={v:m,h:!1,F:!0,A:[12,6],type:[q,V]},t[34837]={v:m,h:!1,F:!1,A:[12],type:[q]},t[36221]={v:ee,h:!1,F:!1,A:[3],type:[G]},t[36239]={v:ee,h:!1,F:!1,A:[3],type:[L]},t[36215]={v:ee,h:!1,F:!1,A:[6],type:[D]},t[36233]={v:ee,h:!1,F:!1,A:[6],type:[X]},t[36209]={v:ee,h:!1,F:!1,A:[12],type:[H]},t[36227]={v:ee,h:!1,F:!1,A:[12],type:[N]},t[32856]={v:p,h:!0,F:!0,A:[4],type:[G]},t[35907]={v:p,h:!0,F:!0,A:[4],type:[G]},t[36759]={v:p,h:!1,F:!0,A:[4],type:[L]},t[32855]={v:p,h:!0,F:!0,A:[4,2,4],type:[G,32820,$]},t[32854]={v:p,h:!0,F:!0,A:[4,2],type:[G,32819]},t[32857]={v:p,h:!0,F:!0,A:[4],type:[$]},t[34842]={v:p,h:!1,F:!0,A:[16,8],type:[q,V]},t[34836]={v:p,h:!1,F:!1,A:[16],type:[q]},t[36220]={v:te,h:!0,F:!1,A:[4],type:[G]},t[36238]={v:te,h:!0,F:!1,A:[4],type:[L]},t[36975]={v:te,h:!0,F:!1,A:[4],type:[$]},t[36214]={v:te,h:!0,F:!1,A:[8],type:[D]},t[36232]={v:te,h:!0,F:!1,A:[8],type:[X]},t[36226]={v:te,h:!0,F:!1,A:[16],type:[N]},t[36208]={v:te,h:!0,F:!1,A:[16],type:[H]},t[33189]={v:w,h:!0,F:!1,A:[2,4],type:[D,H]},t[33190]={v:w,h:!0,F:!1,A:[4],type:[H]},t[36012]={v:w,h:!0,F:!1,A:[4],type:[q]},t[35056]={v:h,h:!0,F:!1,A:[4],type:[34042]},t[36013]={v:h,h:!0,F:!1,A:[4],type:[36269]},Object.keys(t).forEach((function(e){var r=t[e];r.bytesPerElementMap={},r.A.forEach((function(e,t){var n=r.type[t];r.bytesPerElementMap[n]=e}))})),l=t}return l[e]}function ue(e,t){var r=oe(e);if(!r)throw"unknown internal format";var n=r.bytesPerElementMap[t];if(void 0===n)throw"unknown internal format";return n}function ie(e){var t=oe(e);if(!t)throw"unknown internal format";return{format:t.v,type:t.type[0]}}function ae(e){return 0==(e&e-1)}function fe(e,t,r,n){if(!o.isWebGL2(e))return ae(t)&&ae(r);var u=oe(n);if(!u)throw"unknown internal format";return u.h&&u.F}function ce(e){var t=oe(e);if(!t)throw"unknown internal format";return t.F}function le(e,t,r){return y(t)?u.getGLTypeForTypedArray(t):r||G}function se(e,t,r,n,o){if(o%1!=0)throw"can't guess dimensions";if(r||n){if(n){if(!r&&(r=o/n)%1)throw"can't guess dimensions"}else if((n=o/r)%1)throw"can't guess dimensions"}else{var u=Math.sqrt(o/(t===A?6:1));u%1==0?(r=u,n=u):(r=o,n=1)}return{width:r,height:n}}function ye(e){s.textureColor=new Uint8Array([255*e[0],255*e[1],255*e[2],255*e[3]])}ne[6406]={u:1},ne[6409]={u:1},ne[6410]={u:2},ne[m]={u:3},ne[p]={u:4},ne[J]={u:1},ne[36244]={u:1},ne[K]={u:2},ne[33320]={u:2},ne[m]={u:3},ne[36248]={u:3},ne[p]={u:4},ne[36249]={u:4},ne[6402]={u:1},ne[34041]={u:2};var ve={};function be(e,t){void 0!==t.colorspaceConversion&&(ve.colorspaceConversion=e.getParameter(W),e.pixelStorei(W,t.colorspaceConversion)),void 0!==t.premultiplyAlpha&&(ve.premultiplyAlpha=e.getParameter(I),e.pixelStorei(I,t.premultiplyAlpha)),void 0!==t.flipY&&(ve.flipY=e.getParameter(B),e.pixelStorei(B,t.flipY))}function me(e,t){void 0!==t.colorspaceConversion&&e.pixelStorei(W,ve.colorspaceConversion),void 0!==t.premultiplyAlpha&&e.pixelStorei(I,ve.premultiplyAlpha),void 0!==t.flipY&&e.pixelStorei(B,ve.flipY)}function pe(e){ve.unpackAlignment=e.getParameter(T),o.isWebGL2(e)&&(ve.unpackRowLength=e.getParameter(g),ve.unpackImageHeight=e.getParameter(z),ve.unpackSkipPixels=e.getParameter(U),ve.unpackSkipRows=e.getParameter(C),ve.unpackSkipImages=e.getParameter(k))}function de(e){e.pixelStorei(T,ve.unpackAlignment),o.isWebGL2(e)&&(e.pixelStorei(g,ve.unpackRowLength),e.pixelStorei(z,ve.unpackImageHeight),e.pixelStorei(U,ve.unpackSkipPixels),e.pixelStorei(C,ve.unpackSkipRows),e.pixelStorei(k,ve.unpackSkipImages))}function xe(e,t,r,n){n.minMag&&(r.call(e,t,S,n.minMag),r.call(e,t,M,n.minMag)),n.min&&r.call(e,t,S,n.min),n.mag&&r.call(e,t,M,n.mag),n.wrap&&(r.call(e,t,R,n.wrap),r.call(e,t,P,n.wrap),(t===j||i.isSampler(e,t))&&r.call(e,t,32882,n.wrap)),n.wrapR&&r.call(e,t,32882,n.wrapR),n.wrapS&&r.call(e,t,R,n.wrapS),n.wrapT&&r.call(e,t,P,n.wrapT),n.minLod&&r.call(e,t,33082,n.minLod),n.maxLod&&r.call(e,t,33083,n.maxLod),n.baseLevel&&r.call(e,t,33084,n.baseLevel),n.maxLevel&&r.call(e,t,33085,n.maxLevel)}function we(e,t,r){var n=r.target||E;e.bindTexture(n,t),xe(e,n,e.texParameteri,r)}function he(e,t,r){xe(e,t,e.samplerParameteri,r)}function Fe(e,t){var r=e.createSampler();return he(e,r,t),r}function Ee(e,t,r,n,o,u){r=r||s.textureOptions,u=u||p;var i=r.target||E;if(n=n||r.width,o=o||r.height,e.bindTexture(i,t),fe(e,n,o,u))e.generateMipmap(i);else{var a=ce(u)?9729:9728;e.texParameteri(i,S,a),e.texParameteri(i,M,a),e.texParameteri(i,R,F),e.texParameteri(i,P,F)}}function Ae(e){return!0===e.auto||void 0===e.auto&&void 0===e.level}function je(e,t){return(t=t||{}).cubeFaceOrder||[_,34070,34071,34072,34073,34074]}function Oe(e,t){var r=je(0,t).map((function(e,t){return{face:e,ndx:t}}));return r.sort((function(e,t){return e.face-t.face})),r}function _e(e,t,r,n){var o=(n=n||s.textureOptions).target||E,u=n.level||0,i=r.width,a=r.height,f=n.internalFormat||n.format||p,c=ie(f),l=n.format||c.format,y=n.type||c.type;if(be(e,n),e.bindTexture(o,t),o===A){var b,m,d=r.width,x=r.height;if(d/6===x)b=x,m=[0,0,1,0,2,0,3,0,4,0,5,0];else if(x/6===d)b=d,m=[0,0,0,1,0,2,0,3,0,4,0,5];else if(d/3==x/2)b=d/3,m=[0,0,1,0,2,0,0,1,1,1,2,1];else{if(d/2!=x/3)throw"can't figure out cube map from element: "+(r.src?r.src:r.nodeName);b=d/2,m=[0,0,1,0,0,1,1,1,0,2,1,2]}var w=v();w?(w.canvas.width=b,w.canvas.height=b,i=b,a=b,Oe(0,n).forEach((function(t){var n=m[2*t.ndx+0]*b,o=m[2*t.ndx+1]*b;w.drawImage(r,n,o,b,b,0,0,b,b),e.texImage2D(t.face,u,f,l,y,w.canvas)})),w.canvas.width=1,w.canvas.height=1):"undefined"!=typeof createImageBitmap&&(i=b,a=b,Oe(0,n).forEach((function(c){var s=m[2*c.ndx+0]*b,v=m[2*c.ndx+1]*b;e.texImage2D(c.face,u,f,b,b,0,l,y,null),createImageBitmap(r,s,v,b,b,{premultiplyAlpha:"none",colorSpaceConversion:"none"}).then((function(r){be(e,n),e.bindTexture(o,t),e.texImage2D(c.face,u,f,l,y,r),me(e,n),Ae(n)&&Ee(e,t,n,i,a,f)}))})))}else if(o===j||o===O){var h=Math.min(r.width,r.height),F=Math.max(r.width,r.height),_=F/h;if(_%1!=0)throw"can not compute 3D dimensions of element";var S=r.width===F?1:0,M=r.height===F?1:0;pe(e),e.pixelStorei(T,1),e.pixelStorei(g,r.width),e.pixelStorei(z,0),e.pixelStorei(k,0),e.texImage3D(o,u,f,h,h,h,0,l,y,null);for(var R=0;R<_;++R){var P=R*h*S,W=R*h*M;e.pixelStorei(U,P),e.pixelStorei(C,W),e.texSubImage3D(o,u,0,0,R,h,h,1,l,y,r)}de(e)}else e.texImage2D(o,u,f,l,y,r);me(e,n),Ae(n)&&Ee(e,t,n,i,a,f),we(e,t,n)}function Se(){}function Me(e,t){return void 0!==t||function(e){if("undefined"!=typeof document){var t=document.createElement("a");return t.href=e,t.hostname===location.hostname&&t.port===location.port&&t.protocol===location.protocol}var r=new URL(location.href).origin;return new URL(e,location.href).origin===r}(e)?t:"anonymous"}function Re(e){return"undefined"!=typeof ImageBitmap&&e instanceof ImageBitmap||"undefined"!=typeof ImageData&&e instanceof ImageData||"undefined"!=typeof HTMLElement&&e instanceof HTMLElement}function Pe(e,t,r){return Re(e)?(setTimeout((function(){r(null,e)})),e):function(e,t,r){var n;if(r=r||Se,t=void 0!==t?t:s.crossOrigin,t=Me(e,t),"undefined"!=typeof Image){n=new Image,void 0!==t&&(n.crossOrigin=t);var o=function(){n.removeEventListener("error",u),n.removeEventListener("load",a),n=null},u=function(){var t="couldn't load image: "+e;i.error(t),r(t,n),o()},a=function(){r(null,n),o()};return n.addEventListener("error",u),n.addEventListener("load",a),n.src=e,n}if("undefined"!=typeof ImageBitmap){var f,c,l=function(){r(f,c)},y={};t&&(y.mode="cors"),fetch(e,y).then((function(e){if(!e.ok)throw e;return e.blob()})).then((function(e){return createImageBitmap(e,{premultiplyAlpha:"none",colorSpaceConversion:"none"})})).then((function(e){c=e,setTimeout(l)})).catch((function(e){f=e,setTimeout(l)})),n=null}return n}(e,t,r)}function Te(e,t,r){var n=(r=r||s.textureOptions).target||E;if(e.bindTexture(n,t),!1!==r.color){var o=function(e){return e=e||s.textureColor,y(e)?e:new Uint8Array([255*e[0],255*e[1],255*e[2],255*e[3]])}(r.color);if(n===A)for(var u=0;u<6;++u)e.texImage2D(_+u,0,p,1,1,0,p,G,o);else n===j||n===O?e.texImage3D(n,0,p,1,1,1,0,p,G,o):e.texImage2D(n,0,p,1,1,0,p,G,o)}}function ge(e,t,r,n){return n=n||Se,r=r||s.textureOptions,Te(e,t,r),Pe((r=Object.assign({},r)).src,r.crossOrigin,(function(o,u){o?n(o,t,u):(_e(e,t,u,r),n(null,t,u))}))}function ze(e,t,r,n){n=n||Se;var o=r.src;if(6!==o.length)throw"there must be 6 urls for a cubemap";var u=r.level||0,i=r.internalFormat||r.format||p,a=ie(i),f=r.format||a.format,c=r.type||G,l=r.target||E;if(l!==A)throw"target must be TEXTURE_CUBE_MAP";Te(e,t,r),r=Object.assign({},r);var s,y=6,v=[],b=je(0,r);s=o.map((function(o,a){return Pe(o,r.crossOrigin,(m=b[a],function(o,a){--y,o?v.push(o):a.width!==a.height?v.push("cubemap face img is not a square: "+a.src):(be(e,r),e.bindTexture(l,t),5===y?je().forEach((function(t){e.texImage2D(t,u,i,f,c,a)})):e.texImage2D(m,u,i,f,c,a),me(e,r),Ae(r)&&e.generateMipmap(l)),0===y&&n(v.length?v:void 0,t,s)}));var m}))}function Ue(e,t,r,n){n=n||Se;var o=r.src,u=r.internalFormat||r.format||p,i=ie(u),a=r.format||i.format,f=r.type||G,c=r.target||O;if(c!==j&&c!==O)throw"target must be TEXTURE_3D or TEXTURE_2D_ARRAY";Te(e,t,r),r=Object.assign({},r);var l,s=o.length,y=[],b=r.level||0,m=r.width,d=r.height,x=o.length,w=!0;l=o.map((function(o,i){return Pe(o,r.crossOrigin,(p=i,function(o,i){if(--s,o)y.push(o);else{if(be(e,r),e.bindTexture(c,t),w){w=!1,m=r.width||i.width,d=r.height||i.height,e.texImage3D(c,b,u,m,d,x,0,a,f,null);for(var h=0;h<x;++h)e.texSubImage3D(c,b,0,0,h,m,d,1,a,f,i)}else{var F,E=i;i.width===m&&i.height===d||(E=(F=v()).canvas,F.canvas.width=m,F.canvas.height=d,F.drawImage(i,0,0,m,d)),e.texSubImage3D(c,b,0,0,p,m,d,1,a,f,E),F&&E===F.canvas&&(F.canvas.width=0,F.canvas.height=0)}me(e,r),Ae(r)&&e.generateMipmap(c)}0===s&&n(y.length?y:void 0,t,l)}));var p}))}function Ce(e,t,r,n){var i=(n=n||s.textureOptions).target||E;e.bindTexture(i,t);var a=n.width,f=n.height,c=n.depth,l=n.level||0,v=n.internalFormat||n.format||p,b=ie(v),m=n.format||b.format,d=n.type||le(0,r,b.type);if(y(r))r instanceof Uint8ClampedArray&&(r=new Uint8Array(r.buffer));else{var x=u.getTypedArrayTypeForGLType(d);r=new x(r)}var w,h=ue(v,d),F=r.byteLength/h;if(F%1)throw"length wrong size for format: "+o.glEnumToString(e,m);if(i===j||i===O)if(a||f||c)!a||f&&c?!f||a&&c?(w=se(0,i,a,f,F/c),a=w.width,f=w.height):(w=se(0,i,a,c,F/f),a=w.width,c=w.height):(w=se(0,i,f,c,F/a),f=w.width,c=w.height);else{var _=Math.cbrt(F);if(_%1!=0)throw"can't guess cube size of array of numElements: "+F;a=_,f=_,c=_}else w=se(0,i,a,f,F),a=w.width,f=w.height;if(pe(e),e.pixelStorei(T,n.unpackAlignment||1),be(e,n),i===A){var S=F/6*(h/r.BYTES_PER_ELEMENT);Oe(0,n).forEach((function(t){var n=S*t.ndx,o=r.subarray(n,n+S);e.texImage2D(t.face,l,v,a,f,0,m,d,o)}))}else i===j||i===O?e.texImage3D(i,l,v,a,f,c,0,m,d,r):e.texImage2D(i,l,v,a,f,0,m,d,r);return me(e,n),de(e),{width:a,height:f,depth:c,type:d}}function ke(e,t,r){var n=r.target||E;e.bindTexture(n,t);var o=r.level||0,u=r.internalFormat||r.format||p,i=ie(u),a=r.format||i.format,f=r.type||i.type;if(be(e,r),n===A)for(var c=0;c<6;++c)e.texImage2D(_+c,o,u,r.width,r.height,0,a,f,null);else n===j||n===O?e.texImage3D(n,o,u,r.width,r.height,r.depth,0,a,f,null):e.texImage2D(n,o,u,r.width,r.height,0,a,f,null);me(e,r)}function We(e,t,r){r=r||Se,t=t||s.textureOptions;var n=e.createTexture(),o=t.target||E,u=t.width||1,i=t.height||1,a=t.internalFormat||p;e.bindTexture(o,n),o===A&&(e.texParameteri(o,R,F),e.texParameteri(o,P,F));var f=t.src;if(f)if("function"==typeof f&&(f=f(e,t)),"string"==typeof f)ge(e,n,t,r);else if(y(f)||Array.isArray(f)&&("number"==typeof f[0]||Array.isArray(f[0])||y(f[0]))){var c=Ce(e,n,f,t);u=c.width,i=c.height}else Array.isArray(f)&&("string"==typeof f[0]||Re(f[0]))?o===A?ze(e,n,t,r):Ue(e,n,t,r):(_e(e,n,f,t),u=f.width,i=f.height);else ke(e,n,t);return Ae(t)&&Ee(e,n,t,u,i,a),we(e,n,t),n}},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0;var o={m4:!0,v3:!0,primitives:!0};t.primitives=t.v3=t.m4=void 0;var u=l(r(5));t.m4=u;var i=l(r(2));t.v3=i;var a=l(r(9));t.primitives=a;var f=r(10);function c(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return c=function(){return e},e}function l(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=c();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var i=o?Object.getOwnPropertyDescriptor(e,u):null;i&&(i.get||i.set)?Object.defineProperty(r,u,i):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}Object.keys(f).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=f[e]))}))},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.create3DFVertices=R,t.createAugmentedTypedArray=b,t.createCubeVertices=_,t.createPlaneVertices=A,t.createSphereVertices=j,t.createTruncatedConeVertices=S,t.createXYQuadVertices=E,t.createCrescentVertices=P,t.createCylinderVertices=T,t.createTorusVertices=g,t.createDiscVertices=z,t.deindexVertices=function(e){var t=e.indices,r={},n=t.length;return Object.keys(e).filter(m).forEach((function(o){for(var u=e[o],i=u.numComponents,a=b(i,n,u.constructor),f=0;f<n;++f)for(var c=t[f]*i,l=0;l<i;++l)a.push(u[c+l]);r[o]=a})),r},t.flattenNormals=function(e){if(e.indices)throw new Error("can not flatten normals of indexed vertices. deindex them first");for(var t=e.normal,r=t.length,n=0;n<r;n+=9){var o=t[n+0],u=t[n+1],i=t[n+2],a=t[n+3],f=t[n+4],c=t[n+5],l=t[n+6],s=t[n+7],y=t[n+8],v=o+a+l,b=u+f+s,m=i+c+y,p=Math.sqrt(v*v+b*b+m*m);v/=p,b/=p,m/=p,t[n+0]=v,t[n+1]=b,t[n+2]=m,t[n+3]=v,t[n+4]=b,t[n+5]=m,t[n+6]=v,t[n+7]=b,t[n+8]=m}return e},t.makeRandomVertexColors=function(e,t){t=t||{};var r=e.position.numElements,n=b(4,r,Uint8Array),o=t.rand||function(e,t){return t<3?(r=256,Math.random()*r|0):255;var r};if(e.color=n,e.indices)for(var u=0;u<r;++u)n.push(o(u,0),o(u,1),o(u,2),o(u,3));else for(var i=t.vertsPerColor||3,a=r/i,f=0;f<a;++f)for(var c=[o(f,0),o(f,1),o(f,2),o(f,3)],l=0;l<i;++l)n.push(c);return e},t.reorientDirections=x,t.reorientNormals=w,t.reorientPositions=h,t.reorientVertices=F,t.concatVertices=function(e){for(var t,r={},n=function(n){var o=e[n];Object.keys(o).forEach((function(e){r[e]||(r[e]=[]),t||"indices"===e||(t=e);var n=o[e],u=y(n,e),i=s(n).length/u;r[e].push(i)}))},o=0;o<e.length;++o)n(o);var u=r[t],i={};return Object.keys(r).forEach((function(t){var r=function(t){for(var r,n=0,o=0;o<e.length;++o){var u=e[o][t];n+=s(u).length,r&&!u.data||(r=u)}return{length:n,spec:r}}(t),n=I(r.spec,r.length);!function(t,r,n){for(var o=0,u=0,i=0;i<e.length;++i){var a=e[i][t],f=s(a);"indices"===t?(W(f,n,u,o),o+=r[i]):W(f,n,u),u+=f.length}}(t,u,s(n)),i[t]=n})),i},t.duplicateVertices=function(e){var t={};return Object.keys(e).forEach((function(r){var n=e[r],o=s(n),u=I(n,o.length);W(o,s(u),0),t[r]=u})),t},t.createDiscBuffers=t.createDiscBufferInfo=t.createTorusBuffers=t.createTorusBufferInfo=t.createCylinderBuffers=t.createCylinderBufferInfo=t.createCrescentBuffers=t.createCrescentBufferInfo=t.createCresentVertices=t.createCresentBuffers=t.createCresentBufferInfo=t.createXYQuadBuffers=t.createXYQuadBufferInfo=t.createTruncatedConeBuffers=t.createTruncatedConeBufferInfo=t.createSphereBuffers=t.createSphereBufferInfo=t.createPlaneBuffers=t.createPlaneBufferInfo=t.createCubeBuffers=t.createCubeBufferInfo=t.create3DFBuffers=t.create3DFBufferInfo=void 0;var o=l(r(6)),u=l(r(0)),i=l(r(1)),a=l(r(5)),f=l(r(2));function c(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return c=function(){return e},e}function l(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=c();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var i=o?Object.getOwnPropertyDescriptor(e,u):null;i&&(i.get||i.set)?Object.defineProperty(r,u,i):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}var s=o.getArray_,y=o.getNumComponents_;function v(e,t){var r=0;return e.push=function(){for(var t=0;t<arguments.length;++t){var n=arguments[t];if(n instanceof Array||i.isArrayBuffer(n))for(var o=0;o<n.length;++o)e[r++]=n[o];else e[r++]=n}},e.reset=function(e){r=e||0},e.numComponents=t,Object.defineProperty(e,"numElements",{get:function(){return this.length/this.numComponents|0}}),e}function b(e,t,r){return v(new(r||Float32Array)(e*t),e)}function m(e){return"indices"!==e}function p(e,t,r){for(var n=e.length,o=new Float32Array(3),u=0;u<n;u+=3)r(t,[e[u],e[u+1],e[u+2]],o),e[u]=o[0],e[u+1]=o[1],e[u+2]=o[2]}function d(e,t,r){r=r||f.create();var n=t[0],o=t[1],u=t[2];return r[0]=n*e[0]+o*e[1]+u*e[2],r[1]=n*e[4]+o*e[5]+u*e[6],r[2]=n*e[8]+o*e[9]+u*e[10],r}function x(e,t){return p(e,t,a.transformDirection),e}function w(e,t){return p(e,a.inverse(t),d),e}function h(e,t){return p(e,t,a.transformPoint),e}function F(e,t){return Object.keys(e).forEach((function(r){var n=e[r];r.indexOf("pos")>=0?h(n,t):r.indexOf("tan")>=0||r.indexOf("binorm")>=0?x(n,t):r.indexOf("norm")>=0&&w(n,t)})),e}function E(e,t,r){return e=e||2,{position:{numComponents:2,data:[(t=t||0)+-1*(e*=.5),(r=r||0)+-1*e,t+1*e,r+-1*e,t+-1*e,r+1*e,t+1*e,r+1*e]},normal:[0,0,1,0,0,1,0,0,1,0,0,1],texcoord:[0,0,1,0,0,1,1,1],indices:[0,1,2,2,1,3]}}function A(e,t,r,n,o){e=e||1,t=t||1,r=r||1,n=n||1,o=o||a.identity();for(var u=(r+1)*(n+1),i=b(3,u),f=b(3,u),c=b(2,u),l=0;l<=n;l++)for(var s=0;s<=r;s++){var y=s/r,v=l/n;i.push(e*y-.5*e,0,t*v-.5*t),f.push(0,1,0),c.push(y,v)}for(var m=r+1,p=b(3,r*n*2,Uint16Array),d=0;d<n;d++)for(var x=0;x<r;x++)p.push((d+0)*m+x,(d+1)*m+x,(d+0)*m+x+1),p.push((d+1)*m+x,(d+1)*m+x+1,(d+0)*m+x+1);return F({position:i,normal:f,texcoord:c,indices:p},o)}function j(e,t,r,n,o,u,i){if(t<=0||r<=0)throw new Error("subdivisionAxis and subdivisionHeight must be > 0");n=n||0,u=u||0;for(var a=(o=o||Math.PI)-n,f=(i=i||2*Math.PI)-u,c=(t+1)*(r+1),l=b(3,c),s=b(3,c),y=b(2,c),v=0;v<=r;v++)for(var m=0;m<=t;m++){var p=m/t,d=v/r,x=f*p+u,w=a*d+n,h=Math.sin(x),F=Math.cos(x),E=Math.sin(w),A=F*E,j=Math.cos(w),O=h*E;l.push(e*A,e*j,e*O),s.push(A,j,O),y.push(1-p,d)}for(var _=t+1,S=b(3,t*r*2,Uint16Array),M=0;M<t;M++)for(var R=0;R<r;R++)S.push((R+0)*_+M,(R+0)*_+M+1,(R+1)*_+M),S.push((R+1)*_+M,(R+0)*_+M+1,(R+1)*_+M+1);return{position:l,normal:s,texcoord:y,indices:S}}var O=[[3,7,5,1],[6,2,0,4],[6,7,3,2],[0,1,5,4],[7,6,4,5],[2,3,1,0]];function _(e){for(var t=(e=e||1)/2,r=[[-t,-t,-t],[+t,-t,-t],[-t,+t,-t],[+t,+t,-t],[-t,-t,+t],[+t,-t,+t],[-t,+t,+t],[+t,+t,+t]],n=[[1,0,0],[-1,0,0],[0,1,0],[0,-1,0],[0,0,1],[0,0,-1]],o=[[1,0],[0,0],[0,1],[1,1]],u=b(3,24),i=b(3,24),a=b(2,24),f=b(3,12,Uint16Array),c=0;c<6;++c){for(var l=O[c],s=0;s<4;++s){var y=r[l[s]],v=n[c],m=o[s];u.push(y),i.push(v),a.push(m)}var p=4*c;f.push(p+0,p+1,p+2),f.push(p+0,p+2,p+3)}return{position:u,normal:i,texcoord:a,indices:f}}function S(e,t,r,n,o,u,i){if(n<3)throw new Error("radialSubdivisions must be 3 or greater");if(o<1)throw new Error("verticalSubdivisions must be 1 or greater");for(var a=void 0===u||u,f=void 0===i||i,c=(a?2:0)+(f?2:0),l=(n+1)*(o+1+c),s=b(3,l),y=b(3,l),v=b(2,l),m=b(3,n*(o+c/2)*2,Uint16Array),p=n+1,d=Math.atan2(e-t,r),x=Math.cos(d),w=Math.sin(d),h=o+(f?2:0),F=a?-2:0;F<=h;++F){var E=F/o,A=r*E,j=void 0;F<0?(A=0,E=1,j=e):F>o?(A=r,E=1,j=t):j=e+F/o*(t-e),-2!==F&&F!==o+2||(j=0,E=0),A-=r/2;for(var O=0;O<p;++O){var _=Math.sin(O*Math.PI*2/n),S=Math.cos(O*Math.PI*2/n);s.push(_*j,A,S*j),F<0?y.push(0,-1,0):F>o?y.push(0,1,0):0===j?y.push(0,0,0):y.push(_*x,w,S*x),v.push(O/n,1-E)}}for(var M=0;M<o+c;++M)if(!(1===M&&a||M===o+c-2&&f))for(var R=0;R<n;++R)m.push(p*(M+0)+0+R,p*(M+0)+1+R,p*(M+1)+1+R),m.push(p*(M+0)+0+R,p*(M+1)+1+R,p*(M+1)+0+R);return{position:s,normal:y,texcoord:v,indices:m}}function M(e,t){t=t||[];for(var r=[],n=0;n<e.length;n+=4){var o=e[n],u=e.slice(n+1,n+4);u.push.apply(u,t);for(var i=0;i<o;++i)r.push.apply(r,u)}return r}function R(){var e=[0,0,0,0,150,0,30,0,0,0,150,0,30,150,0,30,0,0,30,0,0,30,30,0,100,0,0,30,30,0,100,30,0,100,0,0,30,60,0,30,90,0,67,60,0,30,90,0,67,90,0,67,60,0,0,0,30,30,0,30,0,150,30,0,150,30,30,0,30,30,150,30,30,0,30,100,0,30,30,30,30,30,30,30,100,0,30,100,30,30,30,60,30,67,60,30,30,90,30,30,90,30,67,60,30,67,90,30,0,0,0,100,0,0,100,0,30,0,0,0,100,0,30,0,0,30,100,0,0,100,30,0,100,30,30,100,0,0,100,30,30,100,0,30,30,30,0,30,30,30,100,30,30,30,30,0,100,30,30,100,30,0,30,30,0,30,60,30,30,30,30,30,30,0,30,60,0,30,60,30,30,60,0,67,60,30,30,60,30,30,60,0,67,60,0,67,60,30,67,60,0,67,90,30,67,60,30,67,60,0,67,90,0,67,90,30,30,90,0,30,90,30,67,90,30,30,90,0,67,90,30,67,90,0,30,90,0,30,150,30,30,90,30,30,90,0,30,150,0,30,150,30,0,150,0,0,150,30,30,150,30,0,150,0,30,150,30,30,150,0,0,0,0,0,0,30,0,150,30,0,0,0,0,150,30,0,150,0],t=M([18,0,0,1,18,0,0,-1,6,0,1,0,6,1,0,0,6,0,-1,0,6,1,0,0,6,0,1,0,6,1,0,0,6,0,-1,0,6,1,0,0,6,0,-1,0,6,-1,0,0]),r=M([18,200,70,120,18,80,70,200,6,70,200,210,6,200,200,70,6,210,100,70,6,210,160,70,6,70,180,210,6,100,70,210,6,76,210,100,6,140,210,80,6,90,130,110,6,160,160,220],[255]),n=e.length/3,o={position:b(3,n),texcoord:b(2,n),normal:b(3,n),color:b(4,n,Uint8Array),indices:b(3,n/3,Uint16Array)};o.position.push(e),o.texcoord.push([.22,.19,.22,.79,.34,.19,.22,.79,.34,.79,.34,.19,.34,.19,.34,.31,.62,.19,.34,.31,.62,.31,.62,.19,.34,.43,.34,.55,.49,.43,.34,.55,.49,.55,.49,.43,0,0,1,0,0,1,0,1,1,0,1,1,0,0,1,0,0,1,0,1,1,0,1,1,0,0,1,0,0,1,0,1,1,0,1,1,0,0,1,0,1,1,0,0,1,1,0,1,0,0,1,0,1,1,0,0,1,1,0,1,0,0,0,1,1,1,0,0,1,1,1,0,0,0,1,1,0,1,0,0,1,0,1,1,0,0,1,1,0,1,0,0,1,0,1,1,0,0,1,1,0,1,0,0,1,0,1,1,0,0,0,1,1,1,0,0,1,1,1,0,0,0,1,1,0,1,0,0,1,0,1,1,0,0,0,1,1,1,0,0,1,1,1,0,0,0,0,1,1,1,0,0,1,1,1,0]),o.normal.push(t),o.color.push(r);for(var u=0;u<n;++u)o.indices.push(u);return o}function P(e,t,r,n,o,u,i){if(o<=0)throw new Error("subdivisionDown must be > 0");var a=(i=i||1)-(u=u||0),c=2*(o+1)*4,l=b(3,c),s=b(3,c),y=b(2,c);function v(e,t,r){return e+(t-e)*r}function m(t,r,i,c,b,m){for(var p=0;p<=o;p++){var d=r/1,x=p/o,w=2*(d-.5),h=(u+x*a)*Math.PI,F=Math.sin(h),E=Math.cos(h),A=v(e,t,F),j=w*n,O=E*e,_=F*A;l.push(j,O,_);var S=f.add(f.multiply([0,F,E],i),c);s.push(S),y.push(d*b+m,x)}}for(var p=0;p<2;p++){var d=2*(p/1-.5);m(t,p,[1,1,1],[0,0,0],1,0),m(t,p,[0,0,0],[d,0,0],0,0),m(r,p,[1,1,1],[0,0,0],1,0),m(r,p,[0,0,0],[d,0,0],0,1)}var x=b(3,2*o*4,Uint16Array);function w(e,t){for(var r=0;r<o;++r)x.push(e+r+0,e+r+1,t+r+0),x.push(e+r+1,t+r+1,t+r+0)}var h=o+1;return w(0*h,4*h),w(5*h,7*h),w(6*h,2*h),w(3*h,1*h),{position:l,normal:s,texcoord:y,indices:x}}function T(e,t,r,n,o,u){return S(e,e,t,r,n,o,u)}function g(e,t,r,n,o,u){if(r<3)throw new Error("radialSubdivisions must be 3 or greater");if(n<3)throw new Error("verticalSubdivisions must be 3 or greater");o=o||0;for(var i=(u=u||2*Math.PI)-o,a=r+1,f=n+1,c=a*f,l=b(3,c),s=b(3,c),y=b(2,c),v=b(3,r*n*2,Uint16Array),m=0;m<f;++m)for(var p=m/n,d=p*Math.PI*2,x=Math.sin(d),w=e+x*t,h=Math.cos(d),F=h*t,E=0;E<a;++E){var A=E/r,j=o+A*i,O=Math.sin(j),_=Math.cos(j),S=O*w,M=_*w,R=O*x,P=_*x;l.push(S,F,M),s.push(R,h,P),y.push(A,1-p)}for(var T=0;T<n;++T)for(var g=0;g<r;++g){var z=1+g,U=1+T;v.push(a*T+g,a*U+g,a*T+z),v.push(a*U+g,a*U+z,a*T+z)}return{position:l,normal:s,texcoord:y,indices:v}}function z(e,t,r,n,o){if(t<3)throw new Error("divisions must be at least 3");o=o||1,n=n||0;for(var u=(t+1)*((r=r||1)+1),i=b(3,u),a=b(3,u),f=b(2,u),c=b(3,r*t*2,Uint16Array),l=0,s=e-n,y=t+1,v=0;v<=r;++v){for(var m=n+s*Math.pow(v/r,o),p=0;p<=t;++p){var d=2*Math.PI*p/t,x=m*Math.cos(d),w=m*Math.sin(d);if(i.push(x,0,w),a.push(0,1,0),f.push(1-p/t,v/r),v>0&&p!==t){var h=l+(p+1),F=l+p,E=l+p-y,A=l+(p+1)-y;c.push(h,F,E),c.push(h,E,A)}}l+=t+1}return{position:i,normal:a,texcoord:f,indices:c}}function U(e){return function(t){var r=e.apply(this,Array.prototype.slice.call(arguments,1));return o.createBuffersFromArrays(t,r)}}function C(e){return function(t){var r=e.apply(null,Array.prototype.slice.call(arguments,1));return o.createBufferInfoFromArrays(t,r)}}var k=["numComponents","size","type","normalize","stride","offset","attrib","name","attribName"];function W(e,t,r,n){n=n||0;for(var o=e.length,u=0;u<o;++u)t[r+u]=e[u]+n}function I(e,t){var r=s(e),n=new r.constructor(t),o=n;return r.numComponents&&r.numElements&&v(n,r.numComponents),e.data&&(o={data:n},u.copyNamedProperties(k,e,o)),o}var B=C(R);t.create3DFBufferInfo=B;var L=U(R);t.create3DFBuffers=L;var G=C(_);t.createCubeBufferInfo=G;var X=U(_);t.createCubeBuffers=X;var D=C(A);t.createPlaneBufferInfo=D;var N=U(A);t.createPlaneBuffers=N;var H=C(j);t.createSphereBufferInfo=H;var q=U(j);t.createSphereBuffers=q;var V=C(S);t.createTruncatedConeBufferInfo=V;var Y=U(S);t.createTruncatedConeBuffers=Y;var $=C(E);t.createXYQuadBufferInfo=$;var K=U(E);t.createXYQuadBuffers=K;var Z=C(P);t.createCrescentBufferInfo=Z;var J=U(P);t.createCrescentBuffers=J;var Q=C(T);t.createCylinderBufferInfo=Q;var ee=U(T);t.createCylinderBuffers=ee;var te=C(g);t.createTorusBufferInfo=te;var re=U(g);t.createTorusBuffers=re;var ne=C(z);t.createDiscBufferInfo=ne;var oe=U(z);t.createDiscBuffers=oe;var ue=Z;t.createCresentBufferInfo=ue;var ie=J;t.createCresentBuffers=ie;var ae=P;t.createCresentVertices=ae},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0;var o={addExtensionsToContext:!0,getContext:!0,getWebGLContext:!0,resizeCanvasToDisplaySize:!0,setDefaults:!0,attributes:!0,textures:!0,utils:!0,draw:!0,framebuffers:!0,programs:!0,typedarrays:!0,vertexArrays:!0};t.addExtensionsToContext=h,t.getContext=function(e,t){return function(e,t){for(var r=["webgl2","webgl","experimental-webgl"],n=null,o=0;o<r.length;++o)if(n=e.getContext(r[o],t)){p.addExtensionsToContext&&h(n);break}return n}(e,t)},t.getWebGLContext=function(e,t){return function(e,t){for(var r=["webgl","experimental-webgl"],n=null,o=0;o<r.length;++o)if(n=e.getContext(r[o],t)){p.addExtensionsToContext&&h(n);break}return n}(e,t)},t.resizeCanvasToDisplaySize=function(e,t){t=t||1,t=Math.max(0,t);var r=e.clientWidth*t|0,n=e.clientHeight*t|0;if(e.width!==r||e.height!==n)return e.width=r,e.height=n,!0;return!1},t.setDefaults=function(e){a.copyExistingProperties(e,p),u.setAttributeDefaults_(e),i.setTextureDefaults_(e)},t.vertexArrays=t.typedarrays=t.programs=t.framebuffers=t.draw=t.utils=t.textures=t.attributes=void 0;var u=m(r(6));t.attributes=u,Object.keys(u).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=u[e]))}));var i=m(r(7));t.textures=i,Object.keys(i).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=i[e]))}));var a=m(r(0)),f=m(r(3));t.utils=f,Object.keys(f).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=f[e]))}));var c=m(r(11));t.draw=c,Object.keys(c).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=c[e]))}));var l=m(r(12));t.framebuffers=l,Object.keys(l).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=l[e]))}));var s=m(r(4));t.programs=s,Object.keys(s).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=s[e]))}));var y=m(r(1));t.typedarrays=y,Object.keys(y).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=y[e]))}));var v=m(r(13));function b(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return b=function(){return e},e}function m(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=b();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var i=o?Object.getOwnPropertyDescriptor(e,u):null;i&&(i.get||i.set)?Object.defineProperty(r,u,i):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}t.vertexArrays=v,Object.keys(v).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(o,e)||(t[e]=v[e]))}));var p={addExtensionsToContext:!0};var d=/^(.*?)_/;function x(e,t){f.glEnumToString(e,0);var r=e.getExtension(t);if(r){var n={},o=d.exec(t)[1],u="_"+o;for(var i in r){var c=r[i],l="function"==typeof c,s=l?o:u,y=i;i.endsWith(s)&&(y=i.substring(0,i.length-s.length)),void 0!==e[y]?l||e[y]===c||a.warn(y,e[y],c,i):l?e[y]=function(e){return function(){return e.apply(r,arguments)}}(c):(e[y]=c,n[y]=c)}n.constructor={name:r.constructor.name},f.glEnumToString(n,0)}return r}var w=["ANGLE_instanced_arrays","EXT_blend_minmax","EXT_color_buffer_float","EXT_color_buffer_half_float","EXT_disjoint_timer_query","EXT_disjoint_timer_query_webgl2","EXT_frag_depth","EXT_sRGB","EXT_shader_texture_lod","EXT_texture_filter_anisotropic","OES_element_index_uint","OES_standard_derivatives","OES_texture_float","OES_texture_float_linear","OES_texture_half_float","OES_texture_half_float_linear","OES_vertex_array_object","WEBGL_color_buffer_float","WEBGL_compressed_texture_atc","WEBGL_compressed_texture_etc1","WEBGL_compressed_texture_pvrtc","WEBGL_compressed_texture_s3tc","WEBGL_compressed_texture_s3tc_srgb","WEBGL_depth_texture","WEBGL_draw_buffers"];function h(e){for(var t=0;t<w.length;++t)x(e,w[t])}},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.drawBufferInfo=i,t.drawObjectList=function(e,t){var r=null,n=null;t.forEach((function(t){if(!1!==t.active){var u=t.programInfo,a=t.vertexArrayInfo||t.bufferInfo,f=!1,c=void 0===t.type?4:t.type;u!==r&&(r=u,e.useProgram(u.program),f=!0),(f||a!==n)&&(n&&n.vertexArrayObject&&!a.vertexArrayObject&&e.bindVertexArray(null),n=a,o.setBuffersAndAttributes(e,u,a)),o.setUniforms(u,t.uniforms),i(e,a,c,t.count,t.offset,t.instanceCount)}})),n&&n.vertexArrayObject&&e.bindVertexArray(null)};var o=function(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=u();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var i in e)if(Object.prototype.hasOwnProperty.call(e,i)){var a=o?Object.getOwnPropertyDescriptor(e,i):null;a&&(a.get||a.set)?Object.defineProperty(r,i,a):r[i]=e[i]}r.default=e,t&&t.set(e,r);return r}(r(4));function u(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return u=function(){return e},e}function i(e,t,r,n,o,u){r=void 0===r?4:r;var i=t.indices,a=t.elementType,f=void 0===n?t.numElements:n;o=void 0===o?0:o,a||i?void 0!==u?e.drawElementsInstanced(r,f,void 0===a?5123:t.elementType,o,u):e.drawElements(r,f,void 0===a?5123:t.elementType,o):void 0!==u?e.drawArraysInstanced(r,o,f,u):e.drawArrays(r,o,f)}},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.bindFramebufferInfo=function(e,t,r){r=r||36160,t?(e.bindFramebuffer(r,t.framebuffer),e.viewport(0,0,t.width,t.height)):(e.bindFramebuffer(r,null),e.viewport(0,0,e.drawingBufferWidth,e.drawingBufferHeight))},t.createFramebufferInfo=function(e,t,r,n){var i=36160,a=e.createFramebuffer();e.bindFramebuffer(i,a),r=r||e.drawingBufferWidth,n=n||e.drawingBufferHeight;var c=0,m={framebuffer:a,attachments:[],width:r,height:n};return(t=t||y).forEach((function(t){var a=t.attachment,y=t.format,p=function(e){return v[e]}(y);if(p||(p=36064+c++),!a)if(function(e){return b[e]}(y))a=e.createRenderbuffer(),e.bindRenderbuffer(f,a),e.renderbufferStorage(f,y,r,n);else{var d=Object.assign({},t);d.width=r,d.height=n,void 0===d.auto&&(d.auto=!1,d.min=d.min||d.minMag||s,d.mag=d.mag||d.minMag||s,d.wrapS=d.wrapS||d.wrap||l,d.wrapT=d.wrapT||d.wrap||l),a=o.createTexture(e,d)}if(u.isRenderbuffer(e,a))e.framebufferRenderbuffer(i,p,f,a);else{if(!u.isTexture(e,a))throw new Error("unknown attachment type");void 0!==t.layer?e.framebufferTextureLayer(i,p,a,t.level||0,t.layer):e.framebufferTexture2D(i,p,t.target||3553,a,t.level||0)}m.attachments.push(a)})),m},t.resizeFramebufferInfo=function(e,t,r,n,i){n=n||e.drawingBufferWidth,i=i||e.drawingBufferHeight,t.width=n,t.height=i,(r=r||y).forEach((function(r,a){var c=t.attachments[a],l=r.format;if(u.isRenderbuffer(e,c))e.bindRenderbuffer(f,c),e.renderbufferStorage(f,l,n,i);else{if(!u.isTexture(e,c))throw new Error("unknown attachment type");o.resizeTexture(e,c,r,n,i)}}))};var o=a(r(7)),u=a(r(0));function i(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return i=function(){return e},e}function a(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=i();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var u in e)if(Object.prototype.hasOwnProperty.call(e,u)){var a=o?Object.getOwnPropertyDescriptor(e,u):null;a&&(a.get||a.set)?Object.defineProperty(r,u,a):r[u]=e[u]}return r.default=e,t&&t.set(e,r),r}var f=36161,c=34041,l=33071,s=9729,y=[{format:6408,type:5121,min:s,wrap:l},{format:c}],v={};v[34041]=33306,v[6401]=36128,v[36168]=36128,v[6402]=36096,v[33189]=36096;var b={};b[32854]=!0,b[32855]=!0,b[36194]=!0,b[34041]=!0,b[33189]=!0,b[6401]=!0,b[36168]=!0},function(e,t,r){"use strict";function n(e){return(n="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}t.__esModule=!0,t.createVertexArrayInfo=function(e,t,r){var n=e.createVertexArray();e.bindVertexArray(n),t.length||(t=[t]);return t.forEach((function(t){o.setBuffersAndAttributes(e,t,r)})),e.bindVertexArray(null),{numElements:r.numElements,elementType:r.elementType,vertexArrayObject:n}},t.createVAOAndSetAttributes=i,t.createVAOFromBufferInfo=function(e,t,r){return i(e,t.attribSetters||t,r.attribs,r.indices)};var o=function(e){if(e&&e.__esModule)return e;if(null===e||"object"!==n(e)&&"function"!=typeof e)return{default:e};var t=u();if(t&&t.has(e))return t.get(e);var r={},o=Object.defineProperty&&Object.getOwnPropertyDescriptor;for(var i in e)if(Object.prototype.hasOwnProperty.call(e,i)){var a=o?Object.getOwnPropertyDescriptor(e,i):null;a&&(a.get||a.set)?Object.defineProperty(r,i,a):r[i]=e[i]}r.default=e,t&&t.set(e,r);return r}(r(4));function u(){if("function"!=typeof WeakMap)return null;var e=new WeakMap;return u=function(){return e},e}function i(e,t,r,n){var u=e.createVertexArray();return e.bindVertexArray(u),o.setAttributes(t,r),n&&e.bindBuffer(34963,n),e.bindVertexArray(null),u}}])}));///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxMath
{
	constructor()
	{
	}
	static DEG_TO_RAD_FACTOR 	= Math.PI / 180.0;
	static getXZCirclePosition(zoomXZ, angleXZ, y)
	{
		let posX 					= Math.cos(dwGfxMath.DEG_TO_RAD_FACTOR * angleXZ);
		let posY					= y;
		let posZ 					= Math.sin(dwGfxMath.DEG_TO_RAD_FACTOR * angleXZ);
		var n = posX * posX + posZ * posZ;
		n = Math.sqrt(n);
		const position = [(posX / n) * zoomXZ, posY, (posZ / n) * zoomXZ];
		return position;
	}
	static createProjectedTextureMatrix(lightProjectionMatrix, lightWorldMatrix)
	{
		let textureMatrix 	= m4.identity();
		textureMatrix 		= m4.translate(textureMatrix, 0.5, 0.5, 0.5);
		textureMatrix 		= m4.scale(textureMatrix, 0.5, 0.5, 0.5);
		textureMatrix 		= m4.multiply(textureMatrix, lightProjectionMatrix);
		textureMatrix 		= m4.multiply(textureMatrix, m4.inverse(lightWorldMatrix));
		return textureMatrix;
	}
	static createInverseCameraMatrix(viewMatrix)
	{
		let textureMatrix 	= m4.identity();
		textureMatrix 		= m4.translate(textureMatrix, 0.5, 0.5, 0.5);
		textureMatrix 		= m4.scale(textureMatrix, 0.5, 0.5, 0.5);
		textureMatrix 		= m4.multiply(textureMatrix, m4.inverse(viewMatrix));
		return textureMatrix;
	}
	static create3DProjectionMatrix(w, h, FOV = 60.0)
	{
		const aspect 				= w / h;
		const fieldOfViewRadians 	= dwGfxMath.DEG_TO_RAD_FACTOR * FOV;
		const projectionMatrix 		= m4.perspective(fieldOfViewRadians, aspect, 1, 100);
		return projectionMatrix;
	}
	static screenToWorldRay(screenX, screenY, viewportWidth, viewportHeight, cameraWorldMatrix, projectionMatrix, dst)
	{
		const ray = dst || new dwRay();

		// pixel -> normalized device coords ([-1,1], y flipped so up is +1).
		const ndcX = (2.0 * screenX / viewportWidth) - 1.0;
		const ndcY = 1.0 - (2.0 * screenY / viewportHeight);

		// clip -> world: invert projection * view.
		const viewMatrix = m4.inverse(cameraWorldMatrix);
		const viewProj   = m4.multiply(projectionMatrix, viewMatrix);
		const invViewProj = m4.inverse(viewProj);

		// unproject the NDC near (z=-1) and far (z=+1) points. m4.transformPoint
		// treats the input as a point (w=1) and applies the perspective divide, so
		// no manual matrix indexing / vec4 math is needed.
		const near = m4.transformPoint(invViewProj, [ndcX, ndcY, -1.0]);
		const far  = m4.transformPoint(invViewProj, [ndcX, ndcY,  1.0]);

		// origin = camera world position; direction = near -> far.
		ray.setOrigin(cameraWorldMatrix[12], cameraWorldMatrix[13], cameraWorldMatrix[14]);
		ray.setDirection(far[0] - near[0], far[1] - near[1], far[2] - near[2]);
		return ray;
	};
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwRay.js
//
// Minimal, engine-neutral ray primitive: a normalized origin + direction pair.
// It knows nothing about graphics, particles, collision, or physics — it is just
// the geometric object those systems consume. Screen-to-world construction lives
// in dwGfxMath; intersection queries live in dwCollision.
//
// Layout: origin[3], direction[3] (direction kept unit-length).
// pointAt(distance, dst?) returns origin + direction * distance, writing into an
// optional destination array to avoid per-call allocation on hot paths.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

class dwRay
{
	constructor(origin, direction)
	{
		this.origin		= [0.0, 0.0, 0.0];
		this.direction	= [0.0, 0.0, 1.0];

		if (origin) {
			this.setOrigin(origin[0], origin[1], origin[2]);
		}
		if (direction) {
			this.setDirection(direction[0], direction[1], direction[2]);
		}
	}

	setOrigin(x, y, z)
	{
		this.origin[0] = x;
		this.origin[1] = y;
		this.origin[2] = z;
		return this;
	}

	// stores a normalized direction; a zero-length input is left as-is (defensive).
	setDirection(x, y, z)
	{
		const len = Math.hypot(x, y, z);
		if (len > 0.0) {
			const inv = 1.0 / len;
			this.direction[0] = x * inv;
			this.direction[1] = y * inv;
			this.direction[2] = z * inv;
		}
		return this;
	}

	set(ox, oy, oz, dx, dy, dz)
	{
		this.setOrigin(ox, oy, oz);
		this.setDirection(dx, dy, dz);
		return this;
	}

	// origin + direction * distance. Writes into dst (length >= 3) when supplied.
	pointAt(distance, dst)
	{
		const out = dst || [0.0, 0.0, 0.0];
		out[0] = this.origin[0] + this.direction[0] * distance;
		out[1] = this.origin[1] + this.direction[1] * distance;
		out[2] = this.origin[2] + this.direction[2] * distance;
		return out;
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwCollision.js
//
// Engine-neutral, query-only ray/primitive intersection helpers. This is NOT a
// physics module: nothing here moves objects or resolves collisions. Every routine
// consumes a dwRay and returns a consistent hit-result shape so callers can treat
// results uniformly and pick the nearest with nearestHit().
//
// Hit result:
//   { hit: bool, t: number, point: [x,y,z], normal: [x,y,z] }
//   - t is the ray parameter (distance along the unit direction) of the hit.
//   - point is ray.pointAt(t); normal is the surface normal at the hit (unit).
//   - a miss returns hit:false (t = Infinity); other fields are left untouched.
//
// Conventions: negative t (behind the origin) is a miss; an optional maxDistance
// culls far hits; rays starting inside a sphere/AABB report the exit is ignored and
// the first forward surface (or origin-plane) is returned per the notes on each fn.
// No matrix math is required, so m4 is not used here.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const dwCollision = {

	// reusable "miss" builder so every routine returns the same shape.
	_miss(dst)
	{
		const r = dst || { hit: false, t: Infinity, point: [0, 0, 0], normal: [0, 0, 0] };
		r.hit = false;
		r.t = Infinity;
		return r;
	},

	_fill(dst, ray, t, nx, ny, nz)
	{
		const r = dst || { hit: false, t: 0, point: [0, 0, 0], normal: [0, 0, 0] };
		r.hit = true;
		r.t = t;
		r.point = ray.pointAt(t, r.point);
		r.normal[0] = nx;
		r.normal[1] = ny;
		r.normal[2] = nz;
		return r;
	},

	// ---- ray vs infinite plane -------------------------------------------------
	// plane defined by a point on it and a (need-not-be-unit) normal. Parallel rays
	// (denominator ~0) miss. The returned normal is unit-length and oriented as given.
	rayPlane(ray, planePoint, planeNormal, maxDistance, dst)
	{
		const nlen = Math.hypot(planeNormal[0], planeNormal[1], planeNormal[2]) || 1.0;
		const nx = planeNormal[0] / nlen;
		const ny = planeNormal[1] / nlen;
		const nz = planeNormal[2] / nlen;

		const denom = ray.direction[0] * nx + ray.direction[1] * ny + ray.direction[2] * nz;
		if (Math.abs(denom) < 1e-8) {
			return this._miss(dst);   // parallel (or grazing) — no single hit.
		}

		const px = planePoint[0] - ray.origin[0];
		const py = planePoint[1] - ray.origin[1];
		const pz = planePoint[2] - ray.origin[2];
		const t = (px * nx + py * ny + pz * nz) / denom;

		if (t < 0.0 || (maxDistance !== undefined && maxDistance !== null && t > maxDistance)) {
			return this._miss(dst);
		}
		return this._fill(dst, ray, t, nx, ny, nz);
	},

	// ---- ray vs sphere ---------------------------------------------------------
	// Returns the nearest forward intersection. If the origin is inside the sphere,
	// the (forward) exit point is returned and its outward normal reported.
	raySphere(ray, center, radius, maxDistance, dst)
	{
		const ox = ray.origin[0] - center[0];
		const oy = ray.origin[1] - center[1];
		const oz = ray.origin[2] - center[2];

		// direction is unit-length, so a = 1.
		const b = 2.0 * (ox * ray.direction[0] + oy * ray.direction[1] + oz * ray.direction[2]);
		const c = ox * ox + oy * oy + oz * oz - radius * radius;
		const disc = b * b - 4.0 * c;
		if (disc < 0.0) {
			return this._miss(dst);
		}

		const sq = Math.sqrt(disc);
		let t = (-b - sq) * 0.5;
		if (t < 0.0) {
			t = (-b + sq) * 0.5;   // origin inside (or first hit behind): try far root.
		}
		if (t < 0.0 || (maxDistance !== undefined && maxDistance !== null && t > maxDistance)) {
			return this._miss(dst);
		}

		const hx = ray.origin[0] + ray.direction[0] * t;
		const hy = ray.origin[1] + ray.direction[1] * t;
		const hz = ray.origin[2] + ray.direction[2] * t;
		let nx = (hx - center[0]);
		let ny = (hy - center[1]);
		let nz = (hz - center[2]);
		const nl = Math.hypot(nx, ny, nz) || 1.0;
		return this._fill(dst, ray, t, nx / nl, ny / nl, nz / nl);
	},

	// ---- ray vs axis-aligned box (slab method) ---------------------------------
	// boxMin/boxMax are opposite corners. Returns nearest forward entry; if the
	// origin is inside the box the exit face is returned. Axis-aligned face normal.
	rayAABB(ray, boxMin, boxMax, maxDistance, dst)
	{
		let tmin = -Infinity;
		let tmax = Infinity;
		let hitAxis = 0;
		let hitSign = -1.0;

		for (let a = 0; a < 3; a++) {
			const o = ray.origin[a];
			const d = ray.direction[a];
			const lo = boxMin[a];
			const hi = boxMax[a];

			if (Math.abs(d) < 1e-8) {
				// ray parallel to this slab: miss if origin outside the slab.
				if (o < lo || o > hi) {
					return this._miss(dst);
				}
				continue;
			}

			const inv = 1.0 / d;
			let t1 = (lo - o) * inv;
			let t2 = (hi - o) * inv;
			let sign = -1.0;
			if (t1 > t2) {
				const tmp = t1; t1 = t2; t2 = tmp;
				sign = 1.0;
			}
			if (t1 > tmin) {
				tmin = t1;
				hitAxis = a;
				hitSign = sign;
			}
			if (t2 < tmax) {
				tmax = t2;
			}
			if (tmin > tmax) {
				return this._miss(dst);
			}
		}

		// choose the first non-negative parameter (entry, or exit if inside).
		let t = tmin;
		let inside = false;
		if (t < 0.0) {
			t = tmax;
			inside = true;
		}
		if (t < 0.0 || (maxDistance !== undefined && maxDistance !== null && t > maxDistance)) {
			return this._miss(dst);
		}

		const nx = hitAxis === 0 ? (inside ? -hitSign : hitSign) : 0.0;
		const ny = hitAxis === 1 ? (inside ? -hitSign : hitSign) : 0.0;
		const nz = hitAxis === 2 ? (inside ? -hitSign : hitSign) : 0.0;
		// when inside, the entry axis is not meaningful; fall back to a generic +Y.
		if (inside && nx === 0.0 && ny === 0.0 && nz === 0.0) {
			return this._fill(dst, ray, t, 0.0, 1.0, 0.0);
		}
		return this._fill(dst, ray, t, nx, ny, nz);
	},

	// ---- nearest of many hits --------------------------------------------------
	// Given an array of hit results, return the one with the smallest t among hits.
	// Returns a miss shape if none hit. Does not allocate a new result.
	nearestHit(hits)
	{
		let best = null;
		for (let i = 0; i < hits.length; i++) {
			const h = hits[i];
			if (h && h.hit && (best === null || h.t < best.t)) {
				best = h;
			}
		}
		return best || { hit: false, t: Infinity, point: [0, 0, 0], normal: [0, 0, 0] };
	}
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//
//	dwGfxModelQuad - flat quad geometry FACTORY.
//
//	This does NOT draw. It produces a twgl `arrays` object in the same shape dwGfxModel ingests
//	({ position, normal, texcoord, indices, tangent:{numComponents:4, data} }) and hands it to
//	dwGfxModel.loadQuad(). The quad is the construction atom: one quad is a surface/plane, six make
//	a cube, two crossed make an "X" (the cheap volumetric card). Billboarding is NOT this factory's
//	concern - that is a render-time model-matrix behavior applied elsewhere. This only builds a flat
//	quad, as a surface first.
//
//	Units: 1.0 = 1 cm (engine working unit). `size` is the full edge length in cm.
//
//	Plane: which axis-plane the quad lies in, and therefore which way its face normal points:
//		"xy" -> lies in XY, normal +Z   (default: a wall/surface facing the camera at rest)
//		"xz" -> lies in XZ, normal +Y   (a floor lying flat)
//		"yz" -> lies in YZ, normal +X   (a side wall)
//
//	UVs are 0..1 across the face. A constant tangent basis is emitted per-plane so a normal map
//	lights correctly (tangent.w = handedness, matching the OBJ path's {numComponents:4} tangent).
//
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxModelQuad
{
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	//	build - returns a twgl `arrays` object for a flat quad. Static: the factory holds no state.
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	static build(size = 1.0, plane = "xy")
	{
		let h = size * 0.5;

		// per-plane: four corner positions (CCW when viewed from the +normal side), the face
		// normal, and the tangent (direction of +U in world space) with handedness in .w.
		let position;
		let normal;
		let tangent;

		if (plane === "xz")
		{
			// lies flat on the ground, normal +Y. U -> +X, V -> +Z.
			position =
			[
				-h, 0.0, -h,
				 h, 0.0, -h,
				-h, 0.0,  h,
				 h, 0.0,  h,
			];
			normal =
			[
				0.0, 1.0, 0.0,
				0.0, 1.0, 0.0,
				0.0, 1.0, 0.0,
				0.0, 1.0, 0.0,
			];
			tangent =
			[
				1.0, 0.0, 0.0, 1.0,
				1.0, 0.0, 0.0, 1.0,
				1.0, 0.0, 0.0, 1.0,
				1.0, 0.0, 0.0, 1.0,
			];
		}
		else if (plane === "yz")
		{
			// side wall, normal +X. U -> +Z, V -> +Y.
			position =
			[
				0.0, -h, -h,
				0.0, -h,  h,
				0.0,  h, -h,
				0.0,  h,  h,
			];
			normal =
			[
				1.0, 0.0, 0.0,
				1.0, 0.0, 0.0,
				1.0, 0.0, 0.0,
				1.0, 0.0, 0.0,
			];
			tangent =
			[
				0.0, 0.0, 1.0, 1.0,
				0.0, 0.0, 1.0, 1.0,
				0.0, 0.0, 1.0, 1.0,
				0.0, 0.0, 1.0, 1.0,
			];
		}
		else
		{
			// default "xy": wall/surface facing +Z. U -> +X, V -> +Y.
			position =
			[
				-h, -h, 0.0,
				 h, -h, 0.0,
				-h,  h, 0.0,
				 h,  h, 0.0,
			];
			normal =
			[
				0.0, 0.0, 1.0,
				0.0, 0.0, 1.0,
				0.0, 0.0, 1.0,
				0.0, 0.0, 1.0,
			];
			tangent =
			[
				1.0, 0.0, 0.0, 1.0,
				1.0, 0.0, 0.0, 1.0,
				1.0, 0.0, 0.0, 1.0,
				1.0, 0.0, 0.0, 1.0,
			];
		}

		// UVs 0..1 across the face, matching the corner order above.
		let texcoord = [
			0.0, 1.0,  // bottom-left vertex now samples top-left texel
			1.0, 1.0,  // bottom-right → top-right
			0.0, 0.0,  // top-left     → bottom-left
			1.0, 0.0,  // top-right    → bottom-right
		];
		// two triangles (CCW), shared as an indexed quad.
		let indices =
		[
			0, 1, 2,
			2, 1, 3,
		];

		return {
			position: position,
			normal:   normal,
			texcoord: texcoord,
			indices:  indices,
			tangent:  { numComponents: 4, data: tangent },
		};
	}
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';
// =====================================================================================
// dwGfxDepthDiag  --  self-contained WebGL2 depth-sampling diagnostic suite.
//
// One entry point: dwGfxDepthDiag(gl, opts) -> { table, verdict, decision, pass, stages }.
// It runs a battery of RAW WebGL2 subtests that live entirely OUTSIDE the engine's texture
// wrappers (its own programs / textures / FBOs / VAO), so a failure cannot be blamed on
// dwGfxTexture, the fog composite, or any engine state. Every subtest:
//   - drains stale GL errors first,
//   - captures framebuffer completeness, gl.getError, depth attachment size/type,
//     TEXTURE_COMPARE_MODE, MIN/MAG filters, BASE/MAX level, DEPTH_WRITEMASK / CLEAR_VALUE
//     / FUNC / TEST, ACTIVE_TEXTURE and 2D bindings,
//   - decides PASS/FAIL numerically from an RGBA8 readback (never visual judgement).
// All GL state is saved and restored; all temporary GL objects are deleted. Nothing about
// the live scene is permanently altered. Sizes are tiny (4x4) so it is mobile-safe.
//
// The suite answers the standing question -- why does the fog read scene depth as 0 -- by
// isolating each link of the chain and printing a decision the user reports verbatim.
// =====================================================================================
function dwGfxDepthDiag(gl, opts)
{
	opts = opts || {};
	const engineDepthHandle = opts.engineDepthHandle || null; // dwGfx.getRenderSceneDepthTexture(0)
	const engineSceneFbo    = opts.engineSceneFbo || null;    // dwGfx.sceneFramebuffer
	const W = 4, H = 4;
	const TOL = 0.10;
	const near = (x, t) => (isFinite(x) && Math.abs(x - t) <= TOL);
	const num  = (x) => (isFinite(x) ? x.toFixed(3) : "n/a");

	if (!gl) { return { table: "depthdiag[no GL context]", verdict: "no GL", decision: "no GL", pass: {}, stages: [] }; }

	// ---- shared GLSL (ES 3.00) ----
	const VS = `#version 300 es
out vec2 v_uv;
void main(){
	vec2 p = vec2((gl_VertexID==1) ? 3.0 : -1.0, (gl_VertexID==2) ? 3.0 : -1.0);
	v_uv = p * 0.5 + 0.5;
	gl_Position = vec4(p, 0.0, 1.0);
}`;
	const FS_RAW = `#version 300 es
precision highp float;
in vec2 v_uv;
uniform highp sampler2D u_tex;   // plain sampler2D: reads the stored value in .r
out vec4 o;
void main(){ o = vec4(vec3(texture(u_tex, v_uv).r), 1.0); }`;
	const FS_SHADOW = `#version 300 es
precision highp float;
in vec2 v_uv;
uniform highp sampler2DShadow u_tex; // COMPARE_REF_TO_TEXTURE: returns 1.0/0.0 compare result
uniform float u_ref;
out vec4 o;
void main(){ o = vec4(vec3(texture(u_tex, vec3(v_uv, u_ref))), 1.0); }`;

	// ---- save all GL state this suite touches ----
	const S = {
		fbo:        gl.getParameter(gl.FRAMEBUFFER_BINDING),
		vp:         gl.getParameter(gl.VIEWPORT),
		prog:       gl.getParameter(gl.CURRENT_PROGRAM),
		vao:        gl.getParameter(gl.VERTEX_ARRAY_BINDING),
		active:     gl.getParameter(gl.ACTIVE_TEXTURE),
		blend:      gl.isEnabled(gl.BLEND),
		depthTest:  gl.isEnabled(gl.DEPTH_TEST),
		cull:       gl.isEnabled(gl.CULL_FACE),
		scissor:    gl.isEnabled(gl.SCISSOR_TEST),
		depthMask:  gl.getParameter(gl.DEPTH_WRITEMASK),
		colorMask:  gl.getParameter(gl.COLOR_WRITEMASK),
		clearDepth: gl.getParameter(gl.DEPTH_CLEAR_VALUE),
		depthFunc:  gl.getParameter(gl.DEPTH_FUNC),
	};
	const savedUnitTex = [];
	for (let u = 0; u < 4; u++) { gl.activeTexture(gl.TEXTURE0 + u); savedUnitTex[u] = gl.getParameter(gl.TEXTURE_BINDING_2D); }

	// ---- resource bookkeeping (everything created here is deleted in finally) ----
	const trash = { tex: [], fbo: [], prog: [], vao: [] };
	const mkTexRGBA8 = (fillByte) => {
		const t = gl.createTexture(); trash.tex.push(t);
		gl.bindTexture(gl.TEXTURE_2D, t);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
		let data = null;
		if (fillByte !== undefined) { data = new Uint8Array(W * H * 4); data.fill(fillByte); }
		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, W, H, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
		return t;
	};
	const mkTexDepth = (internal, format, type) => {
		const t = gl.createTexture(); trash.tex.push(t);
		gl.bindTexture(gl.TEXTURE_2D, t);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.NONE);
		gl.texImage2D(gl.TEXTURE_2D, 0, internal, W, H, 0, format, type, null);
		return t;
	};
	const mkColorFbo = (colorTex) => {
		const f = gl.createFramebuffer(); trash.fbo.push(f);
		gl.bindFramebuffer(gl.FRAMEBUFFER, f);
		gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, colorTex, 0);
		gl.drawBuffers([gl.COLOR_ATTACHMENT0]);
		return f;
	};
	const mkDepthFbo = (depthTex) => {
		const f = gl.createFramebuffer(); trash.fbo.push(f);
		gl.bindFramebuffer(gl.FRAMEBUFFER, f);
		gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, depthTex, 0);
		gl.drawBuffers([gl.NONE]);
		gl.readBuffer(gl.NONE);
		return f;
	};
	const mkProgram = (fsSrc) => {
		const vs = gl.createShader(gl.VERTEX_SHADER); gl.shaderSource(vs, VS); gl.compileShader(vs);
		const fs = gl.createShader(gl.FRAGMENT_SHADER); gl.shaderSource(fs, fsSrc); gl.compileShader(fs);
		const p = gl.createProgram(); gl.attachShader(p, vs); gl.attachShader(p, fs); gl.linkProgram(p);
		gl.deleteShader(vs); gl.deleteShader(fs);
		if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
			const log = gl.getProgramInfoLog(p) || "link failed";
			gl.deleteProgram(p);
			throw new Error("program link: " + log);
		}
		trash.prog.push(p);
		return p;
	};
	const drain = () => { let n = 0; while (gl.getError() !== gl.NO_ERROR && n < 32) { n++; } };
	const errStr = () => { const e = gl.getError(); return (e === gl.NO_ERROR) ? "NO_ERROR" : ("0x" + (e >>> 0).toString(16)); };

	const vao = gl.createVertexArray(); trash.vao.push(vao);

	// Sample `srcTex` through `prog` on texture `unit` into a fresh RGBA8 output FBO,
	// readPixels the center pixel and return its red channel in [0,1]. `refVal` (shadow only).
	const outTex = mkTexRGBA8(0);
	const outFbo = mkColorFbo(outTex);
	const sampleCenter = (prog, srcTex, unit, refVal) => {
		gl.bindFramebuffer(gl.FRAMEBUFFER, outFbo);
		gl.viewport(0, 0, W, H);
		gl.disable(gl.DEPTH_TEST);
		gl.disable(gl.BLEND);
		gl.disable(gl.CULL_FACE);
		gl.disable(gl.SCISSOR_TEST);
		gl.colorMask(true, true, true, true);
		gl.clearColor(0.0, 0.0, 0.0, 1.0);
		gl.clear(gl.COLOR_BUFFER_BIT);
		gl.useProgram(prog);
		gl.bindVertexArray(vao);
		gl.activeTexture(gl.TEXTURE0 + unit);
		gl.bindTexture(gl.TEXTURE_2D, srcTex);
		const loc = gl.getUniformLocation(prog, "u_tex");
		gl.uniform1i(loc, unit);
		if (refVal !== undefined) {
			const rl = gl.getUniformLocation(prog, "u_ref");
			gl.uniform1f(rl, refVal);
		}
		gl.drawArrays(gl.TRIANGLES, 0, 3);
		const px = new Uint8Array(4);
		gl.readPixels(W >> 1, H >> 1, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
		return { v: px[0] / 255, unitOK: (gl.getParameter(gl.ACTIVE_TEXTURE) === (gl.TEXTURE0 + unit)),
			bindOK: (gl.getParameter(gl.TEXTURE_BINDING_2D) === srcTex), locOK: (loc !== null) };
	};

	// capture the depth-attachment + sampler state of the currently bound FBO / a tex.
	const captureDepthState = (fboBound, tex) => {
		let complete = "n/a", dsize = "?", dtype = "?";
		if (fboBound) {
			complete = (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE) ? "COMPLETE" : "INCOMPLETE";
			try {
				dsize = String(gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE));
				const ct = gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE);
				dtype = (ct === gl.FLOAT) ? "FLOAT" : (ct === gl.UNSIGNED_NORMALIZED) ? "UNORM" : (ct === gl.UNSIGNED_INT) ? "UINT" : String(ct);
			} catch (e) { dsize = "?"; }
		}
		let cmp = "?", minF = "?", magF = "?", base = "?", max = "?";
		if (tex) {
			gl.activeTexture(gl.TEXTURE0); gl.bindTexture(gl.TEXTURE_2D, tex);
			const cm = gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE);
			cmp = (cm === gl.NONE) ? "NONE" : (cm === gl.COMPARE_REF_TO_TEXTURE) ? "COMPARE_REF" : String(cm);
			const fn = (f) => (f === gl.NEAREST) ? "NEAREST" : (f === gl.LINEAR) ? "LINEAR" : String(f);
			minF = fn(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER));
			magF = fn(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER));
			base = String(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_BASE_LEVEL));
			max  = String(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MAX_LEVEL));
		}
		return "fbo=" + complete + " dsize=" + dsize + " dtype=" + dtype + " cmp=" + cmp +
			" min=" + minF + " mag=" + magF + " base=" + base + " max=" + max +
			" wmask=" + (gl.getParameter(gl.DEPTH_WRITEMASK) ? 1 : 0) +
			" cval=" + num(gl.getParameter(gl.DEPTH_CLEAR_VALUE)) +
			" dtest=" + (gl.isEnabled(gl.DEPTH_TEST) ? "ON" : "OFF") +
			" act=" + (gl.getParameter(gl.ACTIVE_TEXTURE) - gl.TEXTURE0);
	};

	const stages = [];
	const rec = (id, passVal, detail) => { stages.push({ id, pass: !!passVal, detail }); };

	// build a standalone depth texture cleared to `sentinel` (no geometry drawn).
	const makeClearedDepth = (internal, format, type, sentinel) => {
		const t = mkTexDepth(internal, format, type);
		const f = mkDepthFbo(t);
		const state = captureDepthState(true, t);
		gl.bindFramebuffer(gl.FRAMEBUFFER, f);
		gl.disable(gl.SCISSOR_TEST);
		gl.depthMask(true);
		gl.clearDepth(sentinel);
		gl.clear(gl.DEPTH_BUFFER_BIT);
		return { tex: t, fbo: f, state, err: errStr() };
	};

	const P = {}; // pass flags used by the classifier
	try {
		// ---------- 1) COLOR CONTROL (RGBA8 0.5 through the minimal fullscreen path) ----------
		drain();
		{
			const progRaw = mkProgram(FS_RAW);
			const src = mkTexRGBA8(128); // 128/255 = 0.502
			const r = sampleCenter(progRaw, src, 0);
			P.color = near(r.v, 0.5) && r.unitOK && r.bindOK && r.locOK;
			rec("1 COLOR CONTROL", P.color, "read=" + num(r.v) + " (want ~0.5) unitOK=" + r.unitOK +
				" bindOK=" + r.bindOK + " locOK=" + r.locOK + " err=" + errStr());
		}

		// ---------- 2) STANDALONE DEPTH24 (raw sampler2D) ----------
		drain();
		{
			const progRaw = mkProgram(FS_RAW);
			const d = makeClearedDepth(gl.DEPTH_COMPONENT24, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, 0.5);
			const r = sampleCenter(progRaw, d.tex, 0);
			P.depth24 = near(r.v, 0.5);
			rec("2 STANDALONE DEPTH24", P.depth24, "read=" + num(r.v) + " (want ~0.5) clearErr=" + d.err +
				" " + d.state + " sampleErr=" + errStr());
		}

		// ---------- 3) STANDALONE DEPTH32F (raw sampler2D) ----------
		drain();
		{
			const progRaw = mkProgram(FS_RAW);
			const d = makeClearedDepth(gl.DEPTH_COMPONENT32F, gl.DEPTH_COMPONENT, gl.FLOAT, 0.5);
			const r = sampleCenter(progRaw, d.tex, 0);
			P.depth32f = near(r.v, 0.5);
			rec("3 STANDALONE DEPTH32F", P.depth32f, "read=" + num(r.v) + " (want ~0.5) clearErr=" + d.err +
				" " + d.state + " sampleErr=" + errStr());
		}

		// ---------- 4) SAMPLER MODES (raw sampler2D vs sampler2DShadow around 0.5) ----------
		drain();
		{
			const progRaw = mkProgram(FS_RAW);
			const progShadow = mkProgram(FS_SHADOW);
			const d = makeClearedDepth(gl.DEPTH_COMPONENT24, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, 0.5);
			// raw read (COMPARE_MODE stays NONE)
			const rawR = sampleCenter(progRaw, d.tex, 0);
			// switch to compare mode for the shadow sampler
			gl.activeTexture(gl.TEXTURE0); gl.bindTexture(gl.TEXTURE_2D, d.tex);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_FUNC, gl.LEQUAL);
			const lo = sampleCenter(progShadow, d.tex, 0, 0.25); // 0.25<=0.5 => 1.0
			const hi = sampleCenter(progShadow, d.tex, 0, 0.75); // 0.75<=0.5 => 0.0
			P.rawSampler = near(rawR.v, 0.5);
			P.shadow = near(lo.v, 1.0) && near(hi.v, 0.0);
			rec("4 SAMPLER MODES", P.rawSampler && P.shadow, "raw=" + num(rawR.v) + " (want ~0.5) shadow(ref0.25)=" +
				num(lo.v) + " (want ~1) shadow(ref0.75)=" + num(hi.v) + " (want ~0) => stored~0.5:" +
				(P.shadow ? "YES" : "NO") + " err=" + errStr());
		}

		// ---------- 5) TEXTURE UNITS (explicit non-zero unit, verify bindings, no feedback) ----------
		drain();
		{
			const progRaw = mkProgram(FS_RAW);
			const src = mkTexRGBA8(128);
			const r = sampleCenter(progRaw, src, 3); // deliberately unit 3
			const noFeedback = (src !== outTex); // source must not be the output attachment
			P.units = near(r.v, 0.5) && r.unitOK && r.bindOK && r.locOK && noFeedback;
			rec("5 TEXTURE UNITS", P.units, "unit=3 read=" + num(r.v) + " activeOK=" + r.unitOK +
				" bindOK=" + r.bindOK + " samplerLocOK=" + r.locOK + " noFeedback=" + noFeedback + " err=" + errStr());
		}

		// ---------- 6) MULTIPLE DEPTH (two standalone depth textures, distinct sentinels) ----------
		drain();
		{
			const progRaw = mkProgram(FS_RAW);
			const dA = makeClearedDepth(gl.DEPTH_COMPONENT24, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, 0.25);
			const dB = makeClearedDepth(gl.DEPTH_COMPONENT32F, gl.DEPTH_COMPONENT, gl.FLOAT, 0.75);
			// sample each independently while the engine's shadow/scene depth resources stay alive
			const ra = sampleCenter(progRaw, dA.tex, 0);
			const rb = sampleCenter(progRaw, dB.tex, 1);
			const aOK = near(ra.v, 0.25), bOK = near(rb.v, 0.75);
			P.twoBoth = aOK && bOK;
			P.twoOneOnly = (aOK !== bOK); // exactly one worked => resource/driver interaction
			rec("6 MULTIPLE DEPTH", P.twoBoth, "A(24)=" + num(ra.v) + " (want ~0.25) B(32F)=" + num(rb.v) +
				" (want ~0.75) bothOK=" + P.twoBoth + " oneOnly=" + P.twoOneOnly +
				" engineResourcesAlive=" + (!!engineDepthHandle) + " err=" + errStr());
		}

		// ---------- 7) ENGINE ATTACHMENT (identical raw path vs the live scene depth) ----------
		drain();
		{
			let detail, enginePass = false;
			if (!engineDepthHandle || !gl.isTexture(engineDepthHandle)) {
				detail = "engineDepthHandle=" + (engineDepthHandle ? "not-a-texture" : "null (renderbuffer/fog-off path)");
			} else {
				const progRaw = mkProgram(FS_RAW);
				const r = sampleCenter(progRaw, engineDepthHandle, 0);
				let fboState = "sceneFbo=n/a";
				if (engineSceneFbo) {
					gl.bindFramebuffer(gl.FRAMEBUFFER, engineSceneFbo);
					const complete = (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE);
					const type = gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
					const name = (type === gl.TEXTURE) ? gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME) : null;
					const tstr = (type === gl.TEXTURE) ? ("TEX id=" + (name === engineDepthHandle ? "OK" : "MISMATCH"))
						: (type === gl.RENDERBUFFER) ? "RBUF" : (type === gl.NONE) ? "NONE" : String(type);
					fboState = "sceneFbo=" + (complete ? "COMPLETE" : "INCOMPLETE") + " att=" + tstr;
				}
				// engine attachment "reads" if it returns a plausible depth (not black 0).
				enginePass = !near(r.v, 0.0);
				detail = "read=" + num(r.v) + " (production; 0=black) " + fboState + " err=" + errStr();
			}
			P.engine = enginePass;
			rec("7 ENGINE ATTACHMENT", P.engine, detail);
		}
	}
	catch (e) {
		rec("SUITE ERROR", false, (e && e.message ? e.message : String(e)));
	}
	finally {
		// ---- delete every temp GL object ----
		for (const f of trash.fbo)  { try { gl.deleteFramebuffer(f); } catch (e) {} }
		for (const t of trash.tex)  { try { gl.deleteTexture(t); } catch (e) {} }
		for (const p of trash.prog) { try { gl.deleteProgram(p); } catch (e) {} }
		for (const v of trash.vao)  { try { gl.deleteVertexArray(v); } catch (e) {} }
		// ---- restore all GL state exactly ----
		for (let u = 0; u < 4; u++) { gl.activeTexture(gl.TEXTURE0 + u); gl.bindTexture(gl.TEXTURE_2D, savedUnitTex[u]); }
		gl.activeTexture(S.active);
		gl.bindVertexArray(S.vao);
		gl.useProgram(S.prog);
		if (S.blend)     { gl.enable(gl.BLEND); }      else { gl.disable(gl.BLEND); }
		if (S.depthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (S.cull)      { gl.enable(gl.CULL_FACE); }  else { gl.disable(gl.CULL_FACE); }
		if (S.scissor)   { gl.enable(gl.SCISSOR_TEST); } else { gl.disable(gl.SCISSOR_TEST); }
		gl.depthMask(S.depthMask);
		gl.colorMask(S.colorMask[0], S.colorMask[1], S.colorMask[2], S.colorMask[3]);
		gl.clearDepth(S.clearDepth);
		gl.depthFunc(S.depthFunc);
		gl.bindFramebuffer(gl.FRAMEBUFFER, S.fbo);
		gl.viewport(S.vp[0], S.vp[1], S.vp[2], S.vp[3]);
	}

	// ---- decision classifier (priority order mirrors the standing hypothesis tree) ----
	const standaloneRaw = !!(P.depth24 || P.depth32f); // raw sampler2D can read a standalone depth tex
	let decision;
	if (!P.color) {
		decision = "FULLSCREEN SHADER / TEXTURE-UNIT / BINDING PATH is broken (color control failed) -- fix the sampling plumbing before trusting any depth result.";
	} else if (!standaloneRaw && P.shadow) {
		decision = "COMPARE-MODE / SAMPLER MISMATCH -- depth IS stored (sampler2DShadow compare works) but a plain sampler2D returns 0 on this device. FIX: sample scene depth with a shadow sampler OR use a color-encoded depth pass.";
	} else if (!standaloneRaw && !P.shadow) {
		decision = "BROWSER / FORMAT / SAMPLER PATH -- this device cannot sample a depth texture as a value at all (raw AND shadow failed on a standalone depth texture). FIX: render linear depth into an RGBA8/R32F COLOR attachment and sample that.";
	} else if (P.twoOneOnly) {
		decision = "RESOURCE / DRIVER INTERACTION -- two simultaneous standalone depth textures do not sample independently (one passed, one failed). Investigate driver depth-texture aliasing / unit state.";
	} else if (!P.engine) {
		decision = "ENGINE ATTACHMENT / STATE / LIFECYCLE -- standalone depth sampling works, but the engine's live scene DEPTH_ATTACHMENT reads black. The isolated path is fine, so the fault is attachment identity / FBO completeness / texture recreation lifecycle in the engine scene target.";
	} else {
		decision = "SCENE PASS OVERWRITE / ORDER / DEPTH-WRITE STATE -- every isolated path passes AND the engine attachment reads a real depth here. So a black production Mode 4 is a scene-pass issue: depth writes disabled, cleared after the draw, wrong order, or all logo texels alpha-discarded.";
	}

	// ---- build the compact PASS/FAIL table (HUD + console) ----
	const mark = (b) => (b ? "PASS" : "FAIL");
	let table = "==== dwGfxDepthDiag (RGBA8 readback, tol " + TOL.toFixed(2) + ") ====\n";
	for (const st of stages) { table += mark(st.pass) + "  " + st.id + "  | " + st.detail + "\n"; }
	table += "DECISION: " + decision;

	const verdict = "depthdiag[color:" + mark(P.color) + " d24:" + mark(!!P.depth24) + " d32f:" + mark(!!P.depth32f) +
		" shadow:" + mark(!!P.shadow) + " units:" + mark(!!P.units) + " two:" + mark(!!P.twoBoth) +
		" engine:" + mark(!!P.engine) + "]";

	console.log(table);
	return { table, verdict, decision, pass: P, stages };
}

// =====================================================================================
// dwGfxMakeDepthProbe(gl) -> reusable, proven-good raw depth sampler.
//
// The one-key `j` suite established (runtime, desktop Chrome) that a plain sampler2D CAN
// read the live engine depth attachment: color/d24/d32f/shadow/units/two/engine all PASS.
// Yet the fog composite reads the SAME texture as 0 at BOTH the far-plane corner and the
// center during the normal frame (HUD "depth[TEX id=OK | bg 0.000 ctr 0.000]"). A uniform
// zero (corner included) is a SAMPLING-STATE failure, not missing geometry depth.
//
// This factory builds ONE cached clean sampler (own program / VAO / 4x4 RGBA8 output FBO)
// -- byte-identical to the suite's proven-good path -- so a caller can, at any frame
// checkpoint, sample the engine depth through a KNOWN-GOOD path and simultaneously read
// back the depth texture's live sampler state (TEXTURE_COMPARE_MODE, MIN/MAG filter,
// BASE/MAX level) and the currently bound framebuffer. Comparing the clean read against
// the fog's own read AT THE SAME INSTANT localizes the first zero transition and whether
// the fault is the texture's sampler state (e.g. COMPARE_MODE left in COMPARE_REF_TO_TEXTURE
// so a plain sampler2D returns 0) rather than the depth content.
//
// probe.sample(depthTex, { forceCompareNone }) -> { v, vNone, cmp, minF, magF, base, max,
//   boundFbo, feedback, err }. All GL state touched is saved and restored; the probe never
// alters the sampled texture permanently (a forced COMPARE_MODE is restored). dispose()
// deletes the cached GL objects. Mobile-safe (4x4).
// =====================================================================================
function dwGfxMakeDepthProbe(gl)
{
	if (!gl) { return null; }
	const W = 4, H = 4;
	const VS = `#version 300 es
out vec2 v_uv;
void main(){
	vec2 p = vec2((gl_VertexID==1) ? 3.0 : -1.0, (gl_VertexID==2) ? 3.0 : -1.0);
	v_uv = p * 0.5 + 0.5;
	gl_Position = vec4(p, 0.0, 1.0);
}`;
	const FS_RAW = `#version 300 es
precision highp float;
in vec2 v_uv;
uniform highp sampler2D u_tex;
out vec4 o;
void main(){ o = vec4(vec3(texture(u_tex, v_uv).r), 1.0); }`;

	const compile = (type, src) => { const s = gl.createShader(type); gl.shaderSource(s, src); gl.compileShader(s); return s; };
	const vs = compile(gl.VERTEX_SHADER, VS);
	const fs = compile(gl.FRAGMENT_SHADER, FS_RAW);
	const prog = gl.createProgram();
	gl.attachShader(prog, vs); gl.attachShader(prog, fs); gl.linkProgram(prog);
	gl.deleteShader(vs); gl.deleteShader(fs);
	if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
		gl.deleteProgram(prog);
		return null;
	}
	const uTexLoc = gl.getUniformLocation(prog, "u_tex");
	const vao = gl.createVertexArray();

	const outTex = gl.createTexture();
	gl.bindTexture(gl.TEXTURE_2D, outTex);
	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
	gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
	gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, W, H, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
	const outFbo = gl.createFramebuffer();
	gl.bindFramebuffer(gl.FRAMEBUFFER, outFbo);
	gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, outTex, 0);
	gl.drawBuffers([gl.COLOR_ATTACHMENT0]);
	gl.bindFramebuffer(gl.FRAMEBUFFER, null);

	const errStr = () => { const e = gl.getError(); return (e === gl.NO_ERROR) ? "NO_ERROR" : ("0x" + (e >>> 0).toString(16)); };
	const drain = () => { let n = 0; while (gl.getError() !== gl.NO_ERROR && n < 32) { n++; } };
	const fname = (f) => (f === gl.NEAREST) ? "NEAREST" : (f === gl.LINEAR) ? "LINEAR" :
		(f === gl.NEAREST_MIPMAP_NEAREST) ? "N_MIP_N" : (f === gl.LINEAR_MIPMAP_LINEAR) ? "L_MIP_L" : String(f);

	// One clean raw-sampler read of `depthTex` into the private 4x4 FBO, returning the
	// center red channel in [0,1]. Never a feedback loop: the private FBO is bound first.
	const readOnce = (depthTex) => {
		gl.bindFramebuffer(gl.FRAMEBUFFER, outFbo);
		gl.viewport(0, 0, W, H);
		gl.disable(gl.DEPTH_TEST);
		gl.disable(gl.BLEND);
		gl.disable(gl.CULL_FACE);
		gl.disable(gl.SCISSOR_TEST);
		gl.colorMask(true, true, true, true);
		gl.clearColor(0, 0, 0, 1);
		gl.clear(gl.COLOR_BUFFER_BIT);
		gl.useProgram(prog);
		gl.bindVertexArray(vao);
		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_2D, depthTex);
		gl.uniform1i(uTexLoc, 0);
		gl.drawArrays(gl.TRIANGLES, 0, 3);
		const px = new Uint8Array(4);
		gl.readPixels(W >> 1, H >> 1, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
		return px[0] / 255;
	};

	return {
		sample(depthTex, opts) {
			opts = opts || {};
			if (!depthTex || !gl.isTexture(depthTex)) {
				return { v: NaN, vNone: NaN, cmp: "no-tex", minF: "?", magF: "?", base: "?", max: "?",
					boundFbo: null, feedback: false, err: "no-tex" };
			}
			drain();
			// ---- save state ----
			const sFbo    = gl.getParameter(gl.FRAMEBUFFER_BINDING);
			const sVp     = gl.getParameter(gl.VIEWPORT);
			const sProg   = gl.getParameter(gl.CURRENT_PROGRAM);
			const sVao    = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
			const sActive = gl.getParameter(gl.ACTIVE_TEXTURE);
			const sBlend  = gl.isEnabled(gl.BLEND);
			const sDepth  = gl.isEnabled(gl.DEPTH_TEST);
			const sCull   = gl.isEnabled(gl.CULL_FACE);
			const sScis   = gl.isEnabled(gl.SCISSOR_TEST);
			const sCmask  = gl.getParameter(gl.COLOR_WRITEMASK);
			gl.activeTexture(gl.TEXTURE0);
			const sTex0   = gl.getParameter(gl.TEXTURE_BINDING_2D);

			// Is `depthTex` attached to the framebuffer that is bound RIGHT NOW? If so, a sample
			// there (as the fog would do if it sampled while that fbo was bound) is a feedback
			// loop that yields 0 -- a distinct, reportable cause. (The clean read below rebinds
			// the private fbo first, so IT is never a feedback loop.)
			let feedback = false;
			try {
				if (sFbo) {
					const at = gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER,
						gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
					if (at === gl.TEXTURE) {
						const nm = gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER,
							gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME);
						feedback = (nm === depthTex);
					}
				}
			} catch (e) { feedback = false; }

			// read the live sampler state of depthTex.
			gl.activeTexture(gl.TEXTURE0);
			gl.bindTexture(gl.TEXTURE_2D, depthTex);
			const cmRaw = gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE);
			const cmp = (cmRaw === gl.NONE) ? "NONE" : (cmRaw === gl.COMPARE_REF_TO_TEXTURE) ? "COMPARE_REF" : String(cmRaw);
			const minF = fname(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER));
			const magF = fname(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER));
			const base = String(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_BASE_LEVEL));
			const max  = String(gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_MAX_LEVEL));

			// (1) read exactly as the texture is configured now (mirrors what the fog samples).
			const v = readOnce(depthTex);

			// (2) optional: read with COMPARE_MODE forced NONE (restored after). If v~0 but
			// vNone is a real depth, the fault is a stale COMPARE_REF_TO_TEXTURE on the scene
			// depth texture -- a one-line, non-speculative state fix in the fog composite.
			let vNone = NaN;
			if (opts.forceCompareNone && cmRaw !== gl.NONE) {
				gl.activeTexture(gl.TEXTURE0);
				gl.bindTexture(gl.TEXTURE_2D, depthTex);
				gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.NONE);
				vNone = readOnce(depthTex);
				gl.bindTexture(gl.TEXTURE_2D, depthTex);
				gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, cmRaw); // restore exactly
			}
			const err = errStr();

			// ---- restore state ----
			gl.activeTexture(gl.TEXTURE0);
			gl.bindTexture(gl.TEXTURE_2D, sTex0);
			gl.activeTexture(sActive);
			gl.bindVertexArray(sVao);
			gl.useProgram(sProg);
			if (sBlend) { gl.enable(gl.BLEND); } else { gl.disable(gl.BLEND); }
			if (sDepth) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
			if (sCull)  { gl.enable(gl.CULL_FACE); } else { gl.disable(gl.CULL_FACE); }
			if (sScis)  { gl.enable(gl.SCISSOR_TEST); } else { gl.disable(gl.SCISSOR_TEST); }
			gl.colorMask(sCmask[0], sCmask[1], sCmask[2], sCmask[3]);
			gl.bindFramebuffer(gl.FRAMEBUFFER, sFbo);
			gl.viewport(sVp[0], sVp[1], sVp[2], sVp[3]);

			return { v, vNone, cmp, minF, magF, base, max, boundFbo: sFbo, feedback, err };
		},
		dispose() {
			try { gl.deleteFramebuffer(outFbo); } catch (e) {}
			try { gl.deleteTexture(outTex); } catch (e) {}
			try { gl.deleteProgram(prog); } catch (e) {}
			try { gl.deleteVertexArray(vao); } catch (e) {}
		}
	};
}

// Expose globally (matches the demo's other window-level helpers).
if (typeof window !== "undefined") { window.dwGfxDepthDiag = dwGfxDepthDiag; window.dwGfxMakeDepthProbe = dwGfxMakeDepthProbe; }
if (typeof module !== "undefined" && module.exports) { module.exports = dwGfxDepthDiag; module.exports.dwGfxMakeDepthProbe = dwGfxMakeDepthProbe; }
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//
//	dwGfxNode - parent/child transform graph node.
//
//	Every node owns a local Translate/Rotate/Scale, composes it into a local matrix, and multiplies by its
//	parent's world matrix to produce its own world matrix. Transforming a parent therefore carries through to
//	every child (models, decals, lights, camera views). A node is payload-agnostic: attach a dwGfxModel, a light
//	config, or a dwGfxView via .attach() and it inherits the parent transform for free.
//
//	Matrix convention matches the rest of the engine (m4, column-major): worldMatrix = parentWorld * localMatrix,
//	i.e. the local transform is applied first, then the parent's. Rotation order is Z * Y * X (yaw/pitch/roll
//	applied as X first, then Y, then Z), matching the dwDrawInfo x/y/zRotation fields.
//
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxNode
{
	constructor(name = "")
	{
		this.name			= name;

		// local transform (TRS)
		this.position		= [0.0, 0.0, 0.0];
		this.rotation		= [0.0, 0.0, 0.0];	// radians, applied X then Y then Z
		this.scale			= [1.0, 1.0, 1.0];

		// cached matrices
		this.localMatrix	= m4.identity();
		this.worldMatrix	= m4.identity();

		// graph links
		this.parent			= null;
		this.children		= [];

		// optional payload that rides this node's world transform
		this.payload		= null;
		this.payloadType	= "";	// "model" | "light" | "view" | "" (empty group)

		this.visible		= true;
	}
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	//	graph management
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	add(child)
	{
		// re-parent cleanly if the child already lives somewhere
		if (child.parent)
		{
			child.parent.remove(child);
		}
		child.parent = this;
		this.children.push(child);
		return child;
	}
	remove(child)
	{
		let index = this.children.indexOf(child);
		if (index >= 0)
		{
			this.children.splice(index, 1);
			child.parent = null;
		}
		return child;
	}
	attach(payload, payloadType)
	{
		this.payload		= payload;
		this.payloadType	= payloadType;
		return this;
	}
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	//	local transform setters (chainable)
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	setPosition(x, y, z)
	{
		this.position = [x, y, z];
		return this;
	}
	setRotation(x, y, z)
	{
		this.rotation = [x, y, z];
		return this;
	}
	setScale(x, y, z)
	{
		this.scale = [x, y, z];
		return this;
	}
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	//	matrix build - compose local TRS, then fold in the parent's world matrix
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	computeLocalMatrix()
	{
		let m = m4.translation(this.position[0], this.position[1], this.position[2]);
		m = m4.multiply(m, m4.xRotation(this.rotation[0]));
		m = m4.multiply(m, m4.yRotation(this.rotation[1]));
		m = m4.multiply(m, m4.zRotation(this.rotation[2]));
		m = m4.multiply(m, m4.scaling(this.scale[0], this.scale[1], this.scale[2]));
		this.localMatrix = m;
		return this.localMatrix;
	}
	updateWorldMatrix(parentWorldMatrix = null)
	{
		this.computeLocalMatrix();

		if (parentWorldMatrix)
		{
			// worldMatrix = parentWorld * localMatrix
			this.worldMatrix = m4.multiply(parentWorldMatrix, this.localMatrix);
		}
		else
		{
			// root node - its local transform is already world space
			this.worldMatrix = m4.copy(this.localMatrix);
		}

		// push the freshly computed world matrix down to every child
		for (let i = 0; i < this.children.length; i++)
		{
			this.children[i].updateWorldMatrix(this.worldMatrix);
		}
	}
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	//	traversal - depth first, invisible branches skipped
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	traverse(callback)
	{
		if (!this.visible)
		{
			return;
		}
		callback(this);
		for (let i = 0; i < this.children.length; i++)
		{
			this.children[i].traverse(callback);
		}
	}
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	//	helpers - pull world-space data out of the cached world matrix
	///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
	getWorldPosition()
	{
		// translation lives in the 13th..15th slots of a column-major 4x4
		return this.worldMatrix.slice(12, 15);
	}
	getWorldMatrix()
	{
		return this.worldMatrix;
	}
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////
// This is needed if the images are not on the same domain
// NOTE: The server providing the images must give CORS permissions
// in order to be able to use the image with WebdwGfx.gl(). Most sites
// do NOT give permission.
///////////////////////////////////////////////////////////////////////////////////////////////////
class dwImage extends Image
{
	constructor()
	{
		super();
		this.ID = -1;
		this.drawInfo = new dwDrawInfo();
	}
};

///////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxTexture
{
	static textureCount = 0;

	static TextureType = Object.freeze({
		COLOR_2D: 0,
		NORMAL_MAP: 1,
		CUBE_MAP_FACE: 2,
		COLOR_BUFFER_2D: 3,
		COLOR_BUFFER_HDR_2D: 4,
	});

	constructor()
	{
		this.img 			= new dwImage();
		this.textureTarget 	= 0;
		this.isReady		= false;
		this.loadedFaces 	= 0;
	}

	requestCORSIfNotSameOrigin(img, url)
	{
		if ((new URL(url, window.location.href)).origin !== window.location.origin) {
			img.crossOrigin = "";
		}
	}

	loadImage(
		url,
		useMips = 1,
		textureType = dwGfxTexture.TextureType.COLOR_2D,
		clamp = 0,
		existingTexture = null,
		cubeFaceTarget = null
	)
	{
		const textureOwner = this;
		const img = new dwImage();

		img.drawInfo.src = url;
		img.ID = dwGfxTexture.textureCount++;
		textureOwner.requestCORSIfNotSameOrigin(img, url);
		img.loading = "eager";

		img.addEventListener('load', function(event) {
			const dwGL = dwGfx.gl();

			const isCubeFace = (textureType === dwGfxTexture.TextureType.CUBE_MAP_FACE);
			const bindTarget = isCubeFace ? dwGL.TEXTURE_CUBE_MAP : dwGL.TEXTURE_2D;
			const uploadTarget = isCubeFace ? cubeFaceTarget : dwGL.TEXTURE_2D;

			let tex = existingTexture;
			if (isCubeFace) {
				console.log("CUBEFACE target:", uploadTarget, "url:", url, "size:", img.width, img.height);
				console.log("CUBEFACE gl error after texImage2D:", dwGL.getError());
			}
			if (isCubeFace && !tex) {
				throw new Error("Cubemap face upload requires existing cubemap texture.");
			}
			if (!tex) {
				tex = dwGL.createTexture();
			}

			if (isCubeFace) {
				// use existingTexture only; do not replace owner resource handle
			} else {
				textureOwner.textureTarget = bindTarget;
				textureOwner.img.drawInfo.texture = tex;
			}
			textureOwner.img.drawInfo.width = img.width;
			textureOwner.img.drawInfo.height = img.height;

			dwGL.bindTexture(bindTarget, tex);
			if (textureType === dwGfxTexture.TextureType.NORMAL_MAP) {
				dwGL.pixelStorei(dwGL.UNPACK_COLORSPACE_CONVERSION_WEBGL, dwGL.NONE);
			}

			const ext = dwGL.getExtension('EXT_texture_filter_anisotropic')
					|| dwGL.getExtension('MOZ_EXT_texture_filter_anisotropic')
					|| dwGL.getExtension('WEBKIT_EXT_texture_filter_anisotropic');

			dwGL.texImage2D(
				uploadTarget,
				0,
				dwGL.RGBA,
				dwGL.RGBA,
				dwGL.UNSIGNED_BYTE,
				img
			);
			console.log("cube?", isCubeFace, "target:", uploadTarget, "url:", url, "size:", img.width, img.height);
			console.log("gl error after texImage2D:", dwGL.getError());
			if (clamp) {
				dwGL.texParameteri(bindTarget, dwGL.TEXTURE_WRAP_S, dwGL.CLAMP_TO_EDGE);
				dwGL.texParameteri(bindTarget, dwGL.TEXTURE_WRAP_T, dwGL.CLAMP_TO_EDGE);
				if (isCubeFace) {
					dwGL.texParameteri(bindTarget, dwGL.TEXTURE_WRAP_R, dwGL.CLAMP_TO_EDGE);
				}
			}

			if (!isCubeFace) {
				if (!useMips) {
					dwGL.texParameteri(bindTarget, dwGL.TEXTURE_MIN_FILTER, dwGL.LINEAR);
				} else {
					dwGL.texParameteri(bindTarget, dwGL.TEXTURE_MIN_FILTER, dwGL.LINEAR_MIPMAP_LINEAR);
					dwGL.generateMipmap(bindTarget);
				}
			}

			dwGL.texParameteri(bindTarget, dwGL.TEXTURE_MAG_FILTER, dwGL.LINEAR);

			if (ext) {
				const maxAnisotropy = dwGL.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
				dwGL.texParameterf(bindTarget, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(16, maxAnisotropy));
			}
			if (isCubeFace) {
				textureOwner.loadedFaces++;

				if (textureOwner.loadedFaces >= 6) {
					dwGL.bindTexture(dwGL.TEXTURE_CUBE_MAP, tex);
					dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_MIN_FILTER, dwGL.LINEAR);
					dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_MAG_FILTER, dwGL.LINEAR);
					textureOwner.isReady = true;
				}
			} else {
				textureOwner.isReady = true;
			}
		});

		img.src = url;
		return img;
	}
	createCheckerboardTexture()
	{
		const dwGL = dwGfx.gl();
		const ext = dwGL.getExtension('EXT_texture_filter_anisotropic')
				|| dwGL.getExtension('MOZ_EXT_texture_filter_anisotropic')
				|| dwGL.getExtension('WEBKIT_EXT_texture_filter_anisotropic');

		this.textureTarget 			= dwGL.TEXTURE_2D;
		this.img.drawInfo.texture 	= dwGL.createTexture();
		this.img.ID 				= dwGfxTexture.textureCount++;

		dwGL.bindTexture(dwGL.TEXTURE_2D, this.img.drawInfo.texture);

		if (ext) {
			const maxAnisotropy = dwGL.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
			dwGL.texParameterf(dwGL.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(16, maxAnisotropy));
		}

		dwGL.texImage2D(
			dwGL.TEXTURE_2D,
			0,
			dwGL.LUMINANCE,
			8,
			8,
			0,
			dwGL.LUMINANCE,
			dwGL.UNSIGNED_BYTE,
			new Uint8Array([
				0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA,
				0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF,
				0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA,
				0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF,
				0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA,
				0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF,
				0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA,
				0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF, 0xAA, 0xFF,
			])
		);

		dwGL.generateMipmap(dwGL.TEXTURE_2D);
		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_MAG_FILTER, dwGL.NEAREST);
	}
	createColorBufferTexture(width, height, useHDR = 0, clamp = 1)
	{
		const dwGL = dwGfx.gl();

		this.textureTarget = dwGL.TEXTURE_2D;
		this.img.drawInfo.texture = dwGL.createTexture();
		this.img.ID = dwGfxTexture.textureCount++;
		this.img.drawInfo.width = width;
		this.img.drawInfo.height = height;

		dwGL.bindTexture(dwGL.TEXTURE_2D, this.img.drawInfo.texture);

		const wantHDR = !!useHDR;
		const canUseHDR = !!dwGfx.extColorBufferFloat;

		if (wantHDR && canUseHDR) {
			dwGL.texImage2D(
				dwGL.TEXTURE_2D,
				0,
				dwGL.RGBA16F,
				width,
				height,
				0,
				dwGL.RGBA,
				dwGL.HALF_FLOAT,
				null
			);
		} else {
			dwGL.texImage2D(
				dwGL.TEXTURE_2D,
				0,
				dwGL.RGBA8,
				width,
				height,
				0,
				dwGL.RGBA,
				dwGL.UNSIGNED_BYTE,
				null
			);
		}

		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_MIN_FILTER, dwGL.LINEAR);
		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_MAG_FILTER, dwGL.LINEAR);

		if (clamp) {
			dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_WRAP_S, dwGL.CLAMP_TO_EDGE);
			dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_WRAP_T, dwGL.CLAMP_TO_EDGE);
		}

		dwGL.bindTexture(dwGL.TEXTURE_2D, null);
		this.isReady = true;
	}
	createDepthTexture(depthTextureSize = 512, height = null, float32 = false)
	{
		const dwGL = dwGfx.gl();

		// square by default (shadow map); pass an explicit height for a rectangular
		// depth texture that matches a non-square scene color buffer (fog depth).
		const texWidth  = depthTextureSize;
		const texHeight = (height === null) ? depthTextureSize : height;

		this.textureTarget = dwGL.TEXTURE_2D;
		this.img.drawInfo.texture = dwGL.createTexture();
		this.img.ID = dwGfxTexture.textureCount++;
		this.img.drawInfo.width  = texWidth;
		this.img.drawInfo.height = texHeight;
		dwGL.bindTexture(dwGL.TEXTURE_2D, this.img.drawInfo.texture);

		// float32=false: DEPTH_COMPONENT24 / UNSIGNED_INT -- the shadow-map format, used
		// only for hardware depth comparison, never sampled as a color value.
		// float32=true : DEPTH_COMPONENT32F / FLOAT -- the portable *sampleable* depth
		// format for the fog scene pass. A plain sampler2D read of DEPTH_COMPONENT24
		// returns 0 on some drivers (ANGLE/D3D), which made the whole scene read clear
		// (rawDepth == 0 everywhere) and clipped every fog march; 32F reads back the real
		// normalized [0,1] window depth. NEAREST-only filtering (set below) suits both.
		const internalFormat = float32 ? dwGL.DEPTH_COMPONENT32F : dwGL.DEPTH_COMPONENT24;
		const dataType       = float32 ? dwGL.FLOAT             : dwGL.UNSIGNED_INT;

		dwGL.texImage2D(
			dwGL.TEXTURE_2D,
			0,
			internalFormat,
			texWidth,
			texHeight,
			0,
			dwGL.DEPTH_COMPONENT,
			dataType,
			null
		);

		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_MAG_FILTER, dwGL.NEAREST);
		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_MIN_FILTER, dwGL.NEAREST);
		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_WRAP_S, dwGL.CLAMP_TO_EDGE);
		dwGL.texParameteri(dwGL.TEXTURE_2D, dwGL.TEXTURE_WRAP_T, dwGL.CLAMP_TO_EDGE);
	}

	createCubeMap(faceUrls, useMips = 1, clamp = 1)
	{
		this.isReady = false;
		this.loadedFaces = 0;
		const dwGL = dwGfx.gl();

		this.textureTarget = dwGL.TEXTURE_CUBE_MAP;
		this.img.ID = dwGfxTexture.textureCount++;
		this.img.drawInfo.src = "cubemap";
		this.img.drawInfo.texture = dwGL.createTexture();

		dwGL.bindTexture(dwGL.TEXTURE_CUBE_MAP, this.img.drawInfo.texture);

		const faces = [
			{ target: dwGL.TEXTURE_CUBE_MAP_POSITIVE_X, url: faceUrls.px },
			{ target: dwGL.TEXTURE_CUBE_MAP_NEGATIVE_X, url: faceUrls.nx },
			{ target: dwGL.TEXTURE_CUBE_MAP_POSITIVE_Y, url: faceUrls.py },
			{ target: dwGL.TEXTURE_CUBE_MAP_NEGATIVE_Y, url: faceUrls.ny },
			{ target: dwGL.TEXTURE_CUBE_MAP_POSITIVE_Z, url: faceUrls.pz },
			{ target: dwGL.TEXTURE_CUBE_MAP_NEGATIVE_Z, url: faceUrls.nz },
		];

		/*faces.forEach((face) => {
			dwGL.texImage2D(
				face.target,
				0,
				dwGL.RGBA,
				1,
				1,
				0,
				dwGL.RGBA,
				dwGL.UNSIGNED_BYTE,
				new Uint8Array([0, 0, 255, 255])
			);
		});*/

		/*
		dwGL.texParameteri(
			dwGL.TEXTURE_CUBE_MAP,
			dwGL.TEXTURE_MIN_FILTER,
			useMips ? dwGL.LINEAR_MIPMAP_LINEAR : dwGL.LINEAR
		);*/

		faces.forEach((face) => {
			this.loadImage(
				face.url,
				useMips,
				dwGfxTexture.TextureType.CUBE_MAP_FACE,
				clamp,
				this.img.drawInfo.texture,
				face.target
			);
		});
		dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_WRAP_S, dwGL.CLAMP_TO_EDGE);
		dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_WRAP_T, dwGL.CLAMP_TO_EDGE);
		dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_WRAP_R, dwGL.CLAMP_TO_EDGE);
		dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_MAG_FILTER, dwGL.LINEAR);
		dwGL.texParameteri(dwGL.TEXTURE_CUBE_MAP, dwGL.TEXTURE_MIN_FILTER, dwGL.LINEAR);
	}

	apply(stage = 0)
	{
		const dwGL = dwGfx.gl();

		if (stage == 0) {
			dwGL.activeTexture(dwGL.TEXTURE0);
		}
		else if (stage == 1) {
			dwGL.activeTexture(dwGL.TEXTURE1);
		}
		else if (stage == 2) {
			dwGL.activeTexture(dwGL.TEXTURE2);
		}
		else if (stage == 3) {
			dwGL.activeTexture(dwGL.TEXTURE3);
		}

		dwGL.bindTexture(this.textureTarget || dwGL.TEXTURE_2D, this.img.drawInfo.texture);
	}
};///////////////////////////////////////////////////////////////////////////////////////////////////
//
//
///////////////////////////////////////////////////////////////////////////////////////////////////
class dwDrawInfo
{
	constructor()
	{
		this.init();
	}
	init()
	{
		this.x = 0;
		this.y = 0;
		this.width = 0;
		this.height = 0;
		this.xCenter = 32.0;
		this.yCenter = 32.0;
		this.xScale = 1.0;
		this.yScale = 1.0;
		this.zScale = 1.0;
		this.xRotation = 0.0;
		this.yRotation = 0.0;
		this.zRotation = 0.0;
		this.r = 1.0;
		this.g = 1.0;
		this.b = 1.0;
		this.a = 1.0;
		this.xv = 0.0;
		this.yv = 0.0;
		this.zv = 0.0;
		this.texture = null;
		this.src = "";
	}
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxView
{
	constructor()
	{
		this.position		= [0.0, 3.3, 10.0];
		this.offset			= [0.0, 0.0, 0.0];
		this.target			= [0.0, 3.3, 10.0];
		this.viewDirection	= [0.0, 0.0, 0.0];
		this.w				= 2.0;
		this.h				= 1.0;
		this.perspective	= false;
		this.fieldOfView	= 120.0;
		this.bias			= 0.0;

		this.worldMatrix		= 0;
		this.projectionMatrix	= 0;
		this.projectedTextureMatrix	= 0;
	}
	setLightView(posX = 0.0, posY = 3.3, posZ = 10.0, targetX = 0.0, targetY = 3.3, targetZ = 0.0, r = 0.0, w = 2, h = 1)
	{
		this.position	= [posX + this.offset[0], posY + this.offset[1], posZ + this.offset[2]];
		this.target		= [targetX, targetY, targetZ];
		this.r			= r;
		this.w			= w;
		this.h			= h;

		var c = Math.cos(dwGfxMath.DEG_TO_RAD_FACTOR * this.r);
		var s = Math.sin(dwGfxMath.DEG_TO_RAD_FACTOR * this.r);
		// first draw from the POV of the light
		this.worldMatrix = m4.lookAt(
			this.position,          // position
			[this.target[0], this.target[1], this.target[2]], // target
			[s, c, 0],                                  // up
		);
		this.projectionMatrix = this.perspective
			? m4.perspective(
				(dwGfxMath.DEG_TO_RAD_FACTOR * this.fieldOfView),
				this.w / this.h,
				0.1,  // near
				10.0)   // far
			: m4.orthographic(
				-this.w / 2.0,   // left
				this.w / 2.0,   // right
				-this.h / 2.0,  // bottom
				this.h / 2.0,  // top
				0.1,                      // near
				10.0);                      // far
		this.projectedTextureMatrix	= dwGfxMath.createProjectedTextureMatrix(this.projectionMatrix, this.worldMatrix);
	}
	setCameraView(w, h)
	{
		this.w = w;
		this.h = h;
		this.projectionMatrix	= dwGfxMath.create3DProjectionMatrix(this.w, this.h);

		//let posX			= this.posX + this.offset[0];
		//let posY			= this.posY + this.offset[1] + this.angleY;
		//let posZ			= this.posZ + this.offset[2];

		this.position		= dwGfxMath.getXZCirclePosition(this.zoom, this.angleX, this.offset[1] + this.angleY);

		this.target[0]		= 0.0;
		this.target[1]		= this.position[1];
		this.target[2]		= 0.0;
		this.viewDirection	= m4.normalize([this.target[0] - this.position[0], this.target[1] - this.position[1], this.target[2] - this.position[2]]);
		// worldMatrix is also know as the cameraMatrix.
		this.worldMatrix	= m4.lookAt(this.position, this.target, [0.0, 1.0, 0.0]);
		return this.worldMatrix;
	}
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxModel
{
	constructor()
	{
		this.position		= [];
		this.normal			= [];
		this.texcoord		= [];
		this.texcoord1		= [];
		this.indices		= [];
		this.tangent		= [];
		this.arrays			= {};

		this.productResponse	= 0;
		this.isLoaded			= 0;
		this.isParsed			= 0;
		this.isFinished			= 0;
		this.programInfo 		= 0;
		this.bufferInfo			= 0;
		this.VAO				= 0;
		this.fieldOfViewRadians = (dwGfxMath.DEG_TO_RAD_FACTOR * 60);
	}
	isReady()
	{
		this.loadGPUData();
		return this.isFinished;
	}
	loadGPUData()
	{
		if ((this.isLoaded == 5) && !this.isParsed) {
			this.parseOBJFile();
			this.isParsed = 1;
		}
		if (this.isLoaded && this.isParsed && !this.isFinished) {
			if (this.tangent) {
				if (this.tangent.length > 0) {
					this.bufferInfo = twgl.createBufferInfoFromArrays(dwGfx.gl(), {position:this.position, normal:this.normal, texcoord:this.texcoord, indices:this.indices, tangent:{numComponents: 4, data:this.tangent}});
				}
			}
			else {
				this.bufferInfo = twgl.createBufferInfoFromArrays(dwGfx.gl(), {position:this.position, normal:this.normal, texcoord:this.texcoord, indices:this.indices});
			}
			this.VAO = twgl.createVAOFromBufferInfo(dwGfx.gl(), this.programInfo, this.bufferInfo);
			this.isFinished = 1;
		}
	}
	loadOBJFile(objFileName, mainURL)
	{
		const model = this;
		var url = mainURL+objFileName;
		var http = new XMLHttpRequest();
		var params = '';
		http.onreadystatechange = function() {//Call a function when the state changes.
			//alert("Try Decline: " + http.readyState + " " + http.status + " " + http.responseText);
			if (http.readyState == 4 && http.status == 200) {
				//alert("Decline: "+http.responseText);
				model.productResponse = http.responseText;
				model.isLoaded = 1;
			}
		}
		http.open('POST', url);
		http.send(params);
	}
	parseOBJFile()
	{
		let resp =		JSON.parse(this.productResponse);
		if (resp.v) {
			this.isLoaded++;
			this.position	= resp.v;
		}
		if (resp.n) {
			this.isLoaded++;
			this.normal 	= resp.n;
		}
		if (resp.uv) {
			this.isLoaded++;
			this.texcoord 	= resp.uv;
		}
		if (resp.uv) {
			this.isLoaded++;
			this.indices 	= resp.i;
		}
		if (resp.uv) {
			this.isLoaded++;
			this.tangent 	= resp.t;
		}
	}
	loadModel(modelName = "t-shirt-women.obj.json", programInfo = 0, mainURL='https://www.mykindafit.com/dwWebEngine/src/siteTemplate/pages/games/MKF-3D-Designer/assets/models/')
	{
		this.programInfo = programInfo;
		this.loadOBJFile(modelName, mainURL, this);
	}
	loadWireFrameBoundingBox(programInfo)
	{
		this.bufferInfo = twgl.createBufferInfoFromArrays(dwGfx.gl(), {
			position: [
			-1, -1, -1,
			1, -1, -1,
			-1,  1, -1,
			1,  1, -1,
			-1, -1,  1,
			1, -1,  1,
			-1,  1,  1,
			1,  1,  1,
			],
			indices: [
			0, 1,
			1, 3,
			3, 2,
			2, 0,

			4, 5,
			5, 7,
			7, 6,
			6, 4,

			0, 4,
			1, 5,
			3, 7,
			2, 6,
			],
		});
		this.VAO = twgl.createVAOFromBufferInfo(dwGfx.gl(), programInfo, this.bufferInfo);
		this.isFinished 	= 1;
	}
	drawWireFrameBoundingBox(programInfo, projectionMatrix, cameraMatrix, lightView, tex)
	{
		const viewMatrix = m4.inverse(cameraMatrix);
		dwGfx.gl().useProgram(programInfo.program);
		// Setup all the needed attributes.
		dwGfx.gl().bindVertexArray(this.VAO);
		// scale the cube in Z so it's really long
		// to represent the texture is being projected to
		// infinity
		let mat = m4.multiply(lightView.worldMatrix, m4.identity());
		let matT = m4.scale(mat, lightView.w, lightView.h, 0.1);
		mat = m4.translate(matT, 0.0, 0.0, -2.0);
		// Set the uniforms we just computed
		twgl.setUniforms(programInfo, {
			u_color: [1, 1, 1, 1],
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_world: mat,
		});
		// calls gl.drawArrays or gl.drawElements
		twgl.drawBufferInfo(dwGfx.gl(), this.bufferInfo, dwGfx.gl().LINES);
	}
	loadCubeMap(programInfo)
	{
		this.bufferInfo = twgl.createBufferInfoFromArrays(dwGfx.gl(), {
			position: {
				numComponents: 2,
				data: [
					-1, -1,
					1, -1,
					-1,  1,

					-1,  1,
					1, -1,
					1,  1,
				],
			},
		});

		this.VAO = twgl.createVAOFromBufferInfo(dwGfx.gl(), programInfo, this.bufferInfo);
		this.isFinished 	= 1;
	}
	loadQuad(programInfo)
	{
		// flat quad, built here (consistent with loadCubeMap: the loader owns its
		// geometry; the caller only passes programInfo). Units: 1.0 = 1 cm.
		let arrays = dwGfxModelQuad.build();

		this.position	= arrays.position;
		this.normal		= arrays.normal;
		this.texcoord	= arrays.texcoord;
		this.indices	= arrays.indices;
		this.tangent	= arrays.tangent;

		this.bufferInfo = twgl.createBufferInfoFromArrays(dwGfx.gl(), arrays);
		this.VAO = twgl.createVAOFromBufferInfo(dwGfx.gl(), programInfo, this.bufferInfo);
		this.isFinished 	= 1;
	}
	loadLightPoint(programInfo)
	{
		// a single light point at the origin - the atom for the particle/firework
		// engine. Position-only, no indices, drawn as gl.POINTS. The point program's
		// vertex shader writes gl_PointSize; instancing/spawning many is the caller's
		// job. Units: 1.0 = 1 cm.
		this.bufferInfo = twgl.createBufferInfoFromArrays(dwGfx.gl(), {
			position: {
				numComponents: 3,
				data: [0.0, 0.0, 0.0],
			},
		});
		this.VAO = twgl.createVAOFromBufferInfo(dwGfx.gl(), programInfo, this.bufferInfo);
		this.isFinished 	= 1;
	}
	drawLightPoint(programInfo, uniforms)
	{
		// POINTS-mode draw. The vertex shader is expected to write gl_PointSize; the
		// fragment shader does the radial glow. Additive blend (gl.ONE, gl.ONE) is the
		// caller's to enable for the firework/light-point look.
		dwGfx.gl().bindVertexArray(this.VAO);
		twgl.setUniforms(programInfo, uniforms);
		twgl.drawBufferInfo(dwGfx.gl(), this.bufferInfo, dwGfx.gl().POINTS);
	}
	renderGL()
	{
	}
	draw()
	{
		if (this.isReady()) {
			dwGfx.gl().bindVertexArray(this.VAO);
			twgl.drawBufferInfo(dwGfx.gl(), this.bufferInfo);
		}
	}
	drawIt(programInfo, uniforms)
	{
		// ------ Draw the Whatever --------
		//gl.frontFace(gl.CW);
		// Setup all the needed attributes.
		dwGfx.gl().bindVertexArray(this.VAO);
		// Set the uniforms unique to the cube
		twgl.setUniforms(programInfo, uniforms);
		// calls gl.drawArrays or gl.drawElements
		twgl.drawBufferInfo(dwGfx.gl(), this.bufferInfo);
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxGpuTimer.js
//
// Reusable ASYNCHRONOUS GPU timing utility for the WebGL2 demo, built on EXT_disjoint_timer_query_webgl2.
// Its whole reason to exist is to measure real GPU cost (the fog raymarch, the composite, the surfel body)
// WITHOUT ever stalling the pipeline: a timing tool that calls gl.finish()/gl.flush() or spin-waits on a
// query result changes the very thing it claims to measure and destroys frame pacing. So this class:
//   - never calls finish / flush / readPixels / getError-loops, and never waits on a result;
//   - only reads a query once gl.getQueryParameter(q, QUERY_RESULT_AVAILABLE) is true (typically 1-3 frames
//     after the draw), from poll(), which is called once per frame and returns immediately either way.
//
// QUERY RING (why): a WebGLQuery cannot be re-begun while its result is still in flight, and allocating one
// per frame would leak GPU objects at 60Hz forever. Each named scope therefore owns a small pool created
// LAZILY (at most poolSize objects, ever) and recycles them: after warmup, createQuery() is never called
// again. If every query in a scope's pool is still in flight (GPU running several frames behind), the frame
// is simply NOT timed and counted as dropped -- dropping a sample is always preferable to blocking or to
// reporting a number we cannot trust.
//
// DISJOINT (why the check is not optional): the extension's timer is only valid while the GPU keeps a
// stable clock. If the driver changes power state, preempts us, or otherwise loses the timebase it raises
// GPU_DISJOINT_EXT, and EVERY timestamp spanning that event is garbage -- often by orders of magnitude. Such
// a sample must be DISCARDED, not smoothed, or one clock change poisons the HUD for seconds. The flag is
// latched and CLEARED BY READING, so it is read at most once per poll() and applied to everything harvested
// in that poll.
//
// NO NESTING / NO OVERLAP (a hard GL rule, not a style choice): TIME_ELAPSED_EXT allows exactly ONE active
// query per context. Nested or interleaved scopes are therefore impossible; a begin() while another scope is
// active is REFUSED (and counted in `refused`) rather than silently producing wrong numbers or a GL error.
// Callers must use scopes SEQUENTIALLY: begin("raymarch")/end("raymarch") then begin("composite")/...
// Anyone who wants a "total" must time a single enclosing scope instead of wrapping the parts.
//
// FALLBACK HONESTY: when the extension is absent (Firefox, most mobile drivers, any browser that disabled it
// for fingerprinting reasons) the class measures CPU SUBMISSION time with performance.now() -- the cost of
// issuing the commands, which is NOT the GPU cost and is usually far smaller. That number is labelled
// "CPU submit" everywhere it surfaces and mode/available are exposed so a HUD can say so too. Presenting CPU
// submission time as GPU time would be a correctness bug, not a cosmetic one, so the string "GPU" is only
// ever emitted while mode === "gpu".
//
// SMOOTHING = ROLLING MEDIAN (not an EMA): frame timings are spiky and occasionally garbage (a disjoint we
// failed to catch, a driver hiccup, a first-use shader compile). An EMA folds every outlier permanently into
// the displayed value; a median over an odd window simply ignores up to floor(N/2) outliers. Both the raw
// latest sample and the smoothed value are exposed, in MILLISECONDS (the extension reports NANOSECONDS).
//
// CONTEXT LOSS: gl.isContextLost(), or a query object that comes back null/invalid, drops all pending state
// and the pool instead of throwing; the pool is then rebuilt lazily on the next begin(), so the timer simply
// resumes once the context is back.
//
// GL is fetched through dwGfx.gl() INSIDE the methods, never cached at construction: this class is routinely
// constructed before a context exists (and in headless node tests, where there is no GL at all -- there it
// reports mode "cpu" and still works).
//
// API
//   new dwGfxGpuTimer({ poolSize: 4, windowSize: 7, enabled: true })
//   available            -> true when EXT_disjoint_timer_query_webgl2 is usable
//   mode                 -> "gpu" | "cpu"          (cpu == performance.now() submission time)
//   extState()           -> "ok" | "absent" | "no-gl"
//   begin(name)          -> true if the scope started; false if refused (overlap / no query / lost context)
//   end(name)            -> true if the scope closed
//   poll()               -> number of samples harvested this call; NEVER blocks. Call once per frame.
//   get(name)            -> { latestMs, smoothedMs, samples, dropped } | null
//   label(name)          -> "raymarch 3.12ms (GPU)" | "fog 4.01ms (CPU submit)"
//   summary()            -> one HUD line: mode + extension state + every scope + refused/dropped/disjoint
//   reset()              -> abandon pending queries + clear stats (NOT a per-frame call: it frees the pool)
//   dispose()            -> delete every query object this timer ever created
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_GPU_TIMER_EXT = "EXT_disjoint_timer_query_webgl2";

// 4 queries per scope covers the usual 1-3 frames of GPU latency with a spare; more just wastes objects,
// fewer starts dropping samples on a GPU that runs behind.
const DW_GPU_TIMER_POOL = 4;
// odd so the median is a real sample and never an average of two; 7 rides out isolated spikes without
// feeling laggy at 60Hz (~0.12s of history).
const DW_GPU_TIMER_WINDOW = 7;
const DW_GPU_TIMER_MAX_POOL = 16;
const DW_GPU_TIMER_MAX_WINDOW = 63;
const DW_GPU_TIMER_NS_TO_MS = 1.0 / 1000000.0;

class dwGfxGpuTimer
{
	constructor(options = {})
	{
		const o = options;

		this.poolSize	= (o.poolSize	!== undefined)
						? Math.max(1, Math.min(o.poolSize | 0, DW_GPU_TIMER_MAX_POOL))
						: DW_GPU_TIMER_POOL;
		// forced ODD: an even window would make the "median" an average of two samples, which is exactly the
		// outlier-blending behaviour the median was chosen to avoid.
		let w			= (o.windowSize	!== undefined) ? (o.windowSize | 0) : DW_GPU_TIMER_WINDOW;
		w				= Math.max(1, Math.min(w, DW_GPU_TIMER_MAX_WINDOW));
		this.windowSize	= (w % 2 === 0) ? (w + 1) : w;
		this.enabled	= (o.enabled	!== undefined) ? !!o.enabled : true;

		// extension probe result. undefined => not probed yet; null => probed and absent. Deliberately NOT
		// resolved here: the context may not exist yet (and must not be cached anyway).
		this._ext		= undefined;
		this._extProbed	= false;

		this._scopes	= new Map();   // name -> scope record (own ring, own smoothing window)
		this._active	= null;        // name of the one scope allowed to be open (TIME_ELAPSED cannot nest)
		this._activeQuery = null;

		// misuse / health counters, so a caller can SEE that numbers are missing instead of quietly
		// believing wrong ones.
		this.refused	= 0;   // begin() while another scope was already open (or no query free)
		this.strayEnds	= 0;   // end(name) that matched no open scope
		this.disjoint	= 0;   // samples thrown away because the GPU timebase went disjoint
		this.dropped	= 0;   // samples lost for any reason (disjoint + pool exhaustion + context loss)
		this.contextLosses = 0;
		this.polls		= 0;
	}

	// ---- environment -------------------------------------------------------------------------------

	// GL is looked up on every use, never stored: the timer outlives context loss/restore and is often
	// constructed before dwGfx has a context at all.
	_gl()
	{
		try {
			if (typeof dwGfx === "undefined" || !dwGfx || typeof dwGfx.gl !== "function") {
				return null;
			}
			return dwGfx.gl() || null;
		} catch (e) {
			return null;
		}
	}

	_now()
	{
		return (typeof performance !== "undefined" && performance && performance.now)
			? performance.now()
			: Date.now();
	}

	// Probe once per context. With NO context we do not latch anything: a timer built before GL exists must
	// still upgrade itself to "gpu" on its first real frame instead of being stuck in the fallback forever.
	_extension(gl)
	{
		if (this._extProbed) {
			return this._ext;
		}
		if (!gl) {
			return null;
		}
		let ext = null;
		try {
			ext = gl.getExtension(DW_GPU_TIMER_EXT) || null;
		} catch (e) {
			ext = null;
		}
		this._ext = ext;
		this._extProbed = true;
		return ext;
	}

	get available()
	{
		return this._extension(this._gl()) !== null;
	}

	// "gpu" means real GPU time. Anything else is CPU submission time and must be labelled as such.
	get mode()
	{
		return this.available ? "gpu" : "cpu";
	}

	extState()
	{
		const gl = this._gl();
		if (!gl) { return "no-gl"; }
		return this._extension(gl) ? "ok" : "absent";
	}

	// ---- scopes ------------------------------------------------------------------------------------

	_scope(name)
	{
		let s = this._scopes.get(name);
		if (s) {
			return s;
		}
		s = {
			name:		name,
			pool:		[],    // every query object created for this scope (bounded by poolSize)
			free:		[],    // subset of pool that is idle and re-beginnable
			pending:	[],    // FIFO of ended-but-unresolved queries
			win:		[],    // rolling window of accepted samples (ms), length <= windowSize
			scratch:	[],    // reused sort buffer -> the median costs no allocation
			latestMs:	null,
			smoothedMs:	null,
			samples:	0,
			dropped:	0,
			refused:	0,
			cpuStart:	0,
		};
		this._scopes.set(name, s);
		return s;
	}

	scopeNames()
	{
		return Array.from(this._scopes.keys());
	}

	// Take an idle query, creating one only while the pool is under its cap. null => every query is still in
	// flight; the caller then skips timing this frame rather than allocating or blocking.
	_acquire(gl, scope)
	{
		if (scope.free.length > 0) {
			return scope.free.pop();
		}
		if (scope.pool.length >= this.poolSize) {
			return null;
		}
		let q = null;
		try {
			q = gl.createQuery();
		} catch (e) {
			q = null;
		}
		if (!q) {
			return null;   // context lost mid-create, or a driver refusing to allocate
		}
		scope.pool.push(q);
		return q;
	}

	// Delete every query object of a scope and forget all in-flight state. Used for context loss, for an
	// invalid query, and for reset(): an in-flight query can never be safely re-begun, so abandoning the
	// object is the only correct way to give up on it.
	_dropScopeQueries(gl, scope)
	{
		if (gl) {
			for (let i = 0; i < scope.pool.length; i++) {
				try { gl.deleteQuery(scope.pool[i]); } catch (e) { /* already gone with the context */ }
			}
		}
		this.dropped += scope.pending.length;
		scope.dropped += scope.pending.length;
		scope.pool.length = 0;
		scope.free.length = 0;
		scope.pending.length = 0;
	}

	// Context loss is normal on mobile/tab-switch, so it must degrade rather than throw. All GL objects are
	// gone; drop them, re-probe the extension (a restored context has its own extension objects), and let
	// the next begin() rebuild the pool.
	_handleContextLoss(gl)
	{
		this.contextLosses++;
		this._scopes.forEach((s) => { this._dropScopeQueries(gl, s); });
		this._active = null;
		this._activeQuery = null;
		this._extProbed = false;
		this._ext = undefined;
	}

	// ---- measurement -------------------------------------------------------------------------------

	// Open a scope. Returns false when nothing was started -- disabled, context lost, no free query, or
	// (the important one) another scope is already open: TIME_ELAPSED_EXT cannot nest or overlap, so the
	// second begin is REFUSED and counted instead of corrupting both measurements.
	begin(name)
	{
		if (!this.enabled) {
			return false;
		}
		const gl = this._gl();
		if (gl && gl.isContextLost && gl.isContextLost()) {
			this._handleContextLoss(gl);
			return false;
		}
		const scope = this._scope(name);
		if (this._active !== null) {
			this.refused++;
			scope.refused++;
			return false;
		}

		const ext = this._extension(gl);
		if (!gl || !ext) {
			// FALLBACK: CPU submission time. Never presented as GPU time (see label()/summary()).
			scope.cpuStart = this._now();
			this._active = name;
			this._activeQuery = null;
			return true;
		}

		const q = this._acquire(gl, scope);
		if (!q) {
			// pool exhausted: the GPU is more than poolSize frames behind. Skip the sample.
			this.dropped++;
			scope.dropped++;
			this.refused++;
			scope.refused++;
			return false;
		}
		try {
			gl.beginQuery(ext.TIME_ELAPSED_EXT, q);
		} catch (e) {
			scope.free.push(q);
			this.dropped++;
			scope.dropped++;
			return false;
		}
		this._active = name;
		this._activeQuery = q;
		return true;
	}

	// Close the scope opened by begin(name). A mismatched end (because begin was refused, which callers are
	// expected to ignore) is a counted no-op -- endQuery is never issued without a matching beginQuery.
	end(name)
	{
		if (this._active === null || this._active !== name) {
			if (this.enabled) { this.strayEnds++; }
			return false;
		}
		const scope = this._scope(name);
		const gl = this._gl();
		const q = this._activeQuery;
		this._active = null;
		this._activeQuery = null;

		if (!q) {
			// CPU fallback: the measurement is complete right now (submission time), so record it directly.
			this._record(scope, Math.max(0, this._now() - scope.cpuStart));
			return true;
		}
		if (gl && gl.isContextLost && gl.isContextLost()) {
			this._handleContextLoss(gl);
			return false;
		}
		const ext = this._extension(gl);
		try {
			gl.endQuery(ext.TIME_ELAPSED_EXT);
		} catch (e) {
			scope.free.push(q);
			this.dropped++;
			scope.dropped++;
			return false;
		}
		scope.pending.push(q);   // resolved later, by poll(), only once the result is available
		return true;
	}

	// Harvest whatever finished. Non-blocking by construction: availability is only ever QUERIED, never
	// waited for, so a query that is not ready just stays pending. Call once per frame; returns the number
	// of accepted samples.
	poll()
	{
		this.polls++;
		const gl = this._gl();
		if (!gl) {
			return 0;   // CPU fallback resolves inside end(); nothing to harvest.
		}
		if (gl.isContextLost && gl.isContextLost()) {
			this._handleContextLoss(gl);
			return 0;
		}
		const ext = this._extension(gl);
		if (!ext) {
			return 0;
		}

		// GPU_DISJOINT_EXT is latched and CLEARED BY READING, so it is read at most once per poll and that
		// one answer condemns everything harvested in this poll. Reading it per query would consume the flag
		// on the first query and let the rest of the garbage through.
		let disjointKnown = false;
		let disjoint = false;

		let harvested = 0;
		const scopes = Array.from(this._scopes.values());
		for (let si = 0; si < scopes.length; si++) {
			const scope = scopes[si];
			// FIFO: timer queries complete in submission order, so the first unresolved one ends the scan.
			while (scope.pending.length > 0) {
				const q = scope.pending[0];
				if (!q) {
					scope.pending.shift();
					this.dropped++;
					scope.dropped++;
					continue;
				}
				let ready = false;
				let bad = false;
				try {
					ready = !!gl.getQueryParameter(q, gl.QUERY_RESULT_AVAILABLE);
				} catch (e) {
					bad = true;
				}
				if (bad) {
					// an invalid query object: give up on this scope's GL state and rebuild it lazily.
					this._dropScopeQueries(gl, scope);
					break;
				}
				if (!ready) {
					break;   // still in flight -- we do NOT wait for it.
				}
				scope.pending.shift();

				if (!disjointKnown) {
					try {
						disjoint = !!gl.getParameter(ext.GPU_DISJOINT_EXT);
					} catch (e) {
						disjoint = false;
					}
					disjointKnown = true;
				}

				let ns = 0;
				let readOk = true;
				try {
					ns = gl.getQueryParameter(q, gl.QUERY_RESULT);
				} catch (e) {
					readOk = false;
				}
				scope.free.push(q);   // recycled either way -> no allocation after warmup

				if (disjoint) {
					// The GPU changed clocks while this spanned the frame: the number is meaningless.
					this.disjoint++;
					this.dropped++;
					scope.dropped++;
					continue;
				}
				if (!readOk || typeof ns !== "number" || !isFinite(ns) || ns < 0) {
					this.dropped++;
					scope.dropped++;
					continue;
				}
				this._record(scope, ns * DW_GPU_TIMER_NS_TO_MS);   // the extension reports NANOSECONDS
				harvested++;
			}
		}
		return harvested;
	}

	// Accept one sample (ms) into the scope's rolling window and re-derive the median.
	_record(scope, ms)
	{
		scope.latestMs = ms;
		scope.samples++;
		scope.win.push(ms);
		if (scope.win.length > this.windowSize) {
			scope.win.shift();
		}
		scope.smoothedMs = this._median(scope);
	}

	// Median of the current window. Insertion sort into a REUSED scratch array: the window is tiny (<=63)
	// and this keeps the per-frame allocation count at zero, which matters in a 60Hz render loop.
	_median(scope)
	{
		const n = scope.win.length;
		if (n === 0) {
			return null;
		}
		const s = scope.scratch;
		s.length = n;
		for (let i = 0; i < n; i++) {
			const v = scope.win[i];
			let j = i - 1;
			while (j >= 0 && s[j] > v) { s[j + 1] = s[j]; j--; }
			s[j + 1] = v;
		}
		// odd window (enforced in the constructor) => a real sample. The even case only occurs while the
		// window is still filling, where the two central samples are averaged.
		return (n % 2 === 1) ? s[(n - 1) >> 1] : 0.5 * (s[(n >> 1) - 1] + s[n >> 1]);
	}

	// ---- results -----------------------------------------------------------------------------------

	get(name)
	{
		const s = this._scopes.get(name);
		if (!s) {
			return null;
		}
		return {
			latestMs:	s.latestMs,
			smoothedMs:	s.smoothedMs,
			samples:	s.samples,
			dropped:	s.dropped,
			refused:	s.refused,
			pending:	s.pending.length,
		};
	}

	// The suffix is the whole point: "(GPU)" is emitted ONLY in gpu mode. In the fallback the value is CPU
	// submission time and says so, because a HUD reading "3ms GPU" when the GPU was never measured is worse
	// than no HUD at all.
	label(name)
	{
		const suffix = (this.mode === "gpu") ? "GPU" : "CPU submit";
		const s = this._scopes.get(name);
		const v = s ? s.smoothedMs : null;
		const text = (v === null || v === undefined) ? "--" : v.toFixed(2);
		return name + " " + text + "ms (" + suffix + ")";
	}

	// One HUD line. Leads with the measurement mode + extension state so the numbers are never ambiguous,
	// and ends with the health counters so refused/dropped samples are visible rather than invisible.
	summary()
	{
		const gpu = (this.mode === "gpu");
		const head = (gpu ? "GPU" : "CPU submit") + " [ext:" + this.extState() + " pool" + this.poolSize
			+ " win" + this.windowSize + "]";
		const parts = [];
		this._scopes.forEach((s) => {
			parts.push(s.name + " " + ((s.smoothedMs === null) ? "--" : s.smoothedMs.toFixed(2)) + "ms");
		});
		const body = parts.length ? (" " + parts.join(" ")) : " (no scopes)";
		return head + body + " | refused " + this.refused + " dropped " + this.dropped
			+ " disjoint " + this.disjoint;
	}

	// ---- lifecycle ---------------------------------------------------------------------------------

	// Abandon everything in flight and clear the statistics. This FREES the query objects (an in-flight
	// query can never be safely re-begun), so it is a context-loss / user-action call, not a per-frame one:
	// the pool is rebuilt lazily on the next begin().
	reset()
	{
		const gl = this._gl();
		this._scopes.forEach((s) => {
			this._dropScopeQueries(gl, s);
			s.win.length = 0;
			s.scratch.length = 0;
			s.latestMs = null;
			s.smoothedMs = null;
			s.samples = 0;
			s.dropped = 0;
			s.refused = 0;
		});
		this._active = null;
		this._activeQuery = null;
		this.refused = 0;
		this.strayEnds = 0;
		this.disjoint = 0;
		this.dropped = 0;
		this.polls = 0;
		return this;
	}

	// Delete every query object ever created by this timer. Safe to call twice and safe on a lost context.
	dispose()
	{
		const gl = this._gl();
		this._scopes.forEach((s) => {
			if (gl) {
				for (let i = 0; i < s.pool.length; i++) {
					try { gl.deleteQuery(s.pool[i]); } catch (e) { /* context already gone */ }
				}
			}
			s.pool.length = 0;
			s.free.length = 0;
			s.pending.length = 0;
		});
		this._active = null;
		this._activeQuery = null;
		return this;
	}
}
// dwGfxPerfConsole -- permanent, lightweight performance isolation console.
//
// Three independent jobs, deliberately in one file so the demo gains one include and a
// handful of call sites instead of a scattered debug layer:
//
//   1. ALWAYS-ON MINI FPS. A tiny top-right badge fed from requestAnimationFrame deltas.
//      It survives the full debug HUD being switched off, so there is always a trustworthy
//      frame-rate reading. DOM is touched at most every 250 ms (4 Hz).
//
//   2. CATEGORY REGISTRY. Optional-effect categories are registered with GETTER/SETTER
//      closures onto the demo's real config flags -- this console never becomes a second
//      source of truth. Shift+Digit hotkeys toggle them; Shift+0 snapshots every category
//      and forces the core-scene baseline; Shift+9 restores the snapshot exactly.
//
//   3. CPU-SUBMIT PASS TIMING. performance.now() around a pass measures how long the CPU
//      took to SUBMIT it. That is NOT GPU time and is labelled "CPU submit" everywhere it
//      is surfaced. Real GPU time comes from dwGfxGpuTimer (fog only, see the demo).
//
// No WebGL, no DOM measurement, no layout reads. Safe to construct headless (document
// absent) -- the badge is simply skipped and everything else still works, which is what
// the node test suite relies on.

class dwGfxPerfConsole
{
	constructor(options)
	{
		const o = options || {};

		// DOM writes and median recomputation are both clamped to this interval. 250 ms is the
		// 4 Hz ceiling the badge and the full HUD share.
		this.updateIntervalMs = (o.updateIntervalMs !== undefined) ? +o.updateIntervalMs : 250.0;

		// Rolling-median window for the CPU-submit timings. Odd so the median is a real sample.
		this.windowSize = Math.max(1, Math.min(63, (o.windowSize !== undefined) ? (o.windowSize | 0) : 7));
		if ((this.windowSize % 2) === 0) { this.windowSize++; }

		// Master switch for the CPU-submit instrumentation. When false, cpuBegin/cpuEnd are
		// early-return no-ops: no performance.now() calls at all, not merely a hidden readout.
		this.timingEnabled = (o.timingEnabled !== undefined) ? !!o.timingEnabled : true;

		// ---- mini FPS accumulator (requestAnimationFrame based) ----
		this.miniVisible  = (o.miniVisible !== undefined) ? !!o.miniVisible : true;
		this.fps          = 0.0;
		this.frameMs      = 0.0;
		this._accumMs     = 0.0;
		this._accumFrames = 0;
		this._lastFlushMs = 0.0;
		this._miniText    = "";
		this._miniEl      = null;

		// ---- category registry ----
		// Insertion-ordered map: id -> { id, slot, label, token, get, set, baseline }
		this._cats     = new Map();
		this._bySlot   = new Map();
		this._snapshot = null;   // null => no snapshot; otherwise Map(id -> bool)

		// ---- CPU-submit scopes ----
		this._scopes = new Map();

		this.onChange = (typeof o.onChange === "function") ? o.onChange : null;

		if (o.attach !== false) { this._attachMini(); }
	}

	// ---- mini FPS badge --------------------------------------------------------------------

	// Own DOM node, created once. pointer-events:none is load-bearing: the badge sits over the
	// canvas and must never swallow a camera drag or a touch-weld. `contain` keeps its reflow
	// scoped to itself so a text change cannot dirty the page layout.
	_attachMini()
	{
		if (typeof document === "undefined" || !document.body) { return null; }
		let el = document.getElementById("dwPerfMini");
		if (!el) {
			el = document.createElement("div");
			el.id = "dwPerfMini";
			el.style.cssText =
				"position:fixed; right:8px; top:8px; z-index:2147483001;" +
				"font:11px/1.25 monospace; color:#0f0; background:rgba(0,0,0,0.45);" +
				"padding:2px 5px; border-radius:3px; white-space:pre;" +
				"pointer-events:none; contain:content;" +
				"-webkit-user-select:none; user-select:none;";
			document.body.appendChild(el);
		}
		this._miniEl = el;
		el.style.display = this.miniVisible ? "block" : "none";
		return el;
	}

	setMini(on)
	{
		this.miniVisible = !!on;
		if (this._miniEl) { this._miniEl.style.display = this.miniVisible ? "block" : "none"; }
		return this.miniVisible;
	}

	toggleMini() { return this.setMini(!this.miniVisible); }

	// Called once per rAF with the raw frame delta. Accumulates only; the DOM write and the
	// FPS recomputation happen at most every updateIntervalMs. Returns true on a flush frame,
	// which the demo reuses as the single 4 Hz gate for the full HUD so the two stay in step
	// and neither can be updated per-frame by accident.
	frame(rawMs, nowMs)
	{
		const now = (nowMs !== undefined) ? nowMs : this._now();
		// Reject the first frame and tab-away spikes so the badge cannot show a garbage number.
		if (rawMs > 0.0 && rawMs < 1000.0) {
			this._accumMs += rawMs;
			this._accumFrames++;
		}
		if ((now - this._lastFlushMs) < this.updateIntervalMs) { return false; }
		this._lastFlushMs = now;
		if (this._accumFrames > 0 && this._accumMs > 0.0) {
			const ms  = this._accumMs / this._accumFrames;
			const fps = 1000.0 / ms;
			// EMA over the 4 Hz flushes: already an average of ~15 frames, so a light blend is
			// enough to stop the last digit flickering without making the reading laggy.
			this.frameMs = (this.frameMs > 0.0) ? (this.frameMs + (ms  - this.frameMs) * 0.35) : ms;
			this.fps     = (this.fps     > 0.0) ? (this.fps     + (fps - this.fps)     * 0.35) : fps;
		}
		this._accumMs = 0.0;
		this._accumFrames = 0;
		if (this.miniVisible && this._miniEl) {
			const txt = this.fps.toFixed(0) + " fps  " + this.frameMs.toFixed(1) + " ms";
			// Skip the DOM write when the rendered text is unchanged.
			if (txt !== this._miniText) {
				this._miniText = txt;
				this._miniEl.textContent = txt;
			}
		}
		return true;
	}

	miniText() { return this.fps.toFixed(0) + " fps  " + this.frameMs.toFixed(1) + " ms"; }

	// ---- category registry -----------------------------------------------------------------

	// `get`/`set` are closures onto the demo's own flags, so fogConfig/leavesConfig stay the
	// single source of truth and an existing unshifted key (f, l, x, ...) and a Shift+Digit
	// hotkey can never disagree. `baseline:false` opts a category out of the Shift+0 sweep.
	register(id, opts)
	{
		const c = opts || {};
		if (typeof c.get !== "function" || typeof c.set !== "function") {
			throw new Error("dwGfxPerfConsole.register(" + id + "): get/set closures are required");
		}
		const slot = (c.slot !== undefined) ? (c.slot | 0) : -1;
		const cat = {
			id:       id,
			slot:     slot,
			label:    c.label || id,
			token:    c.token || id.toUpperCase(),
			get:      c.get,
			set:      c.set,
			baseline: (c.baseline !== undefined) ? !!c.baseline : true,
		};
		this._cats.set(id, cat);
		if (slot >= 0) { this._bySlot.set(slot, cat); }
		return cat;
	}

	has(id) { return this._cats.has(id); }
	ids() { return Array.from(this._cats.keys()); }
	slotOf(id) { const c = this._cats.get(id); return c ? c.slot : -1; }

	isOn(id)
	{
		const c = this._cats.get(id);
		return c ? !!c.get() : false;
	}

	set(id, on)
	{
		const c = this._cats.get(id);
		if (!c) { return false; }
		const v = !!on;
		c.set(v);
		if (this.onChange) { this.onChange(id, v); }
		return v;
	}

	toggle(id) { return this.set(id, !this.isOn(id)); }

	// "on" | "off" | "bypass". "bypass" means the live snapshot recorded this category as ON,
	// so it is off only because the Shift+0 baseline forced it -- Shift+9 will bring it back.
	// A category the user turned off themselves reads "off", even under a baseline.
	state(id)
	{
		const c = this._cats.get(id);
		if (!c) { return "off"; }
		if (c.get()) { return "on"; }
		if (this._snapshot && this._snapshot.get(id) === true) { return "bypass"; }
		return "off";
	}

	// Snapshot EVERY registered category (not only the baseline ones) so restore is exact even
	// if a category is later opted out of the sweep, then force the baseline ones off. Capturing
	// twice overwrites the snapshot with the current -- already-baselined -- state, which would
	// make Shift+9 a no-op, so a repeat capture while a snapshot exists is ignored instead.
	// That makes capture/restore/capture/restore deterministic.
	captureBaseline()
	{
		if (this._snapshot) { return false; }
		const snap = new Map();
		this._cats.forEach((c, id) => { snap.set(id, !!c.get()); });
		this._snapshot = snap;
		this._cats.forEach((c, id) => {
			if (c.baseline && c.get()) { this.set(id, false); }
		});
		return true;
	}

	restoreBaseline()
	{
		if (!this._snapshot) { return false; }
		const snap = this._snapshot;
		// Clear first so state() stops reporting "bypass" while the setters run.
		this._snapshot = null;
		snap.forEach((wasOn, id) => {
			if (this._cats.has(id) && this.isOn(id) !== wasOn) { this.set(id, wasOn); }
		});
		return true;
	}

	hasSnapshot() { return this._snapshot !== null; }

	// True when a snapshot exists and every baseline category is currently off, i.e. the
	// core-scene baseline is actually in force rather than partially edited since Shift+0.
	atBaseline()
	{
		if (!this._snapshot) { return false; }
		let all = true;
		this._cats.forEach((c) => { if (c.baseline && c.get()) { all = false; } });
		return all;
	}

	// Shift + Digit0-9, plus Shift+F for the mini badge. Returns true when the event was consumed,
	// so the demo can `return` before its unshifted Digit1-5 surfel presets are ever reached.
	//
	// Matching on event.code makes the mapping layout-independent: Shift+3 emits '#' on a US
	// layout but something else elsewhere, and code stays "Digit3" either way. Shift+F is used
	// for the badge because every unshifted letter a-z is already bound by the demo, while
	// SHIFTED letters are entirely free (the demo compares event.key against lowercase).
	handleKey(event)
	{
		if (!event || !event.shiftKey) { return false; }
		const code = event.code || "";
		if (code === "KeyF") { this.toggleMini(); return true; }
		if (code.length !== 6 || code.indexOf("Digit") !== 0) { return false; }
		const d = code.charCodeAt(5) - 48;
		if (d < 0 || d > 9) { return false; }
		if (d === 0) { this.captureBaseline(); return true; }
		if (d === 9) { this.restoreBaseline(); return true; }
		const cat = this._bySlot.get(d);
		if (!cat) { return false; }
		this.toggle(cat.id);
		return true;
	}

	// ---- CPU-submit pass timing ------------------------------------------------------------

	_now()
	{
		return (typeof performance !== "undefined" && performance.now)
			? performance.now() : Date.now();
	}

	_scope(id)
	{
		let s = this._scopes.get(id);
		if (!s) {
			// Fixed-size ring + reusable scratch: no per-frame allocation once warmed up.
			s = {
				id: id, start: 0.0, open: false,
				ring: new Array(this.windowSize).fill(0.0),
				scratch: new Array(this.windowSize).fill(0.0),
				n: 0, w: 0, latestMs: null, dirty: false, medianMs: null,
			};
			this._scopes.set(id, s);
		}
		return s;
	}

	cpuBegin(id)
	{
		if (!this.timingEnabled) { return false; }
		const s = this._scope(id);
		s.start = this._now();
		s.open = true;
		return true;
	}

	// A stray end (begin was refused because timing is disabled) is a silent no-op, so callers
	// may pair the two unconditionally without leaking a half-open scope.
	cpuEnd(id)
	{
		if (!this.timingEnabled) { return false; }
		const s = this._scopes.get(id);
		if (!s || !s.open) { return false; }
		s.open = false;
		const ms = this._now() - s.start;
		s.latestMs = ms;
		s.ring[s.w] = ms;
		s.w = (s.w + 1) % this.windowSize;
		if (s.n < this.windowSize) { s.n++; }
		s.dirty = true;
		return true;
	}

	// Median is computed lazily on read, so the sort happens at HUD cadence (4 Hz) rather than
	// once per frame per scope.
	cpuMs(id)
	{
		const s = this._scopes.get(id);
		if (!s || s.n === 0) { return null; }
		if (s.dirty) {
			const k = s.n;
			// Insertion sort into the reusable scratch array: no allocation, and k <= 63.
			for (let i = 0; i < k; i++) {
				const v = s.ring[i];
				let j = i - 1;
				while (j >= 0 && s.scratch[j] > v) { s.scratch[j + 1] = s.scratch[j]; j--; }
				s.scratch[j + 1] = v;
			}
			s.medianMs = s.scratch[k >> 1];
			s.dirty = false;
		}
		return s.medianMs;
	}

	cpuScopeNames() { return Array.from(this._scopes.keys()); }

	resetTiming()
	{
		this._scopes.forEach((s) => {
			s.open = false; s.n = 0; s.w = 0;
			s.latestMs = null; s.medianMs = null; s.dirty = false;
		});
		return this;
	}

	// ---- HUD text --------------------------------------------------------------------------

	// Compact isolation summary. UPPERCASE token == category on, lowercase == user turned it
	// off, "~token" == bypassed by the Shift+0 baseline. Leading CORE appears only when the
	// baseline is genuinely in force.
	isolationLine()
	{
		const parts = [];
		if (this.atBaseline()) { parts.push("CORE"); }
		this._cats.forEach((c, id) => {
			const st = this.state(id);
			if (st === "on") { parts.push(c.token); }
			else if (st === "bypass") { parts.push("~" + c.token.toLowerCase()); }
			else { parts.push(c.token.toLowerCase()); }
		});
		return "iso: " + parts.join(" ") + (this._snapshot ? "   [snap: Shift+9 restores]" : "");
	}

	// CPU-submit timings only. The label is explicit because these are submission costs, never
	// GPU time -- see dwGfxGpuTimer for the one real GPU scope.
	timingLine()
	{
		if (!this.timingEnabled) { return "cpu submit: off"; }
		const parts = [];
		this._scopes.forEach((s, id) => {
			const v = this.cpuMs(id);
			parts.push(id + " " + ((v === null) ? "--" : v.toFixed(2)));
		});
		return "cpu submit (ms, not GPU): " + (parts.length ? parts.join("  ") : "(no scopes)");
	}

	dispose()
	{
		if (this._miniEl && this._miniEl.parentNode) {
			this._miniEl.parentNode.removeChild(this._miniEl);
		}
		this._miniEl = null;
		this._scopes.clear();
		return this;
	}
}

if (typeof module !== "undefined" && module.exports) { module.exports = dwGfxPerfConsole; }
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxSpiritCamera.js
//
// GESTURE CLASSIFIER for the spirit camera. This class owns NO camera state -- no position, no yaw,
// no pitch, no zoom. It converts raw pointer events into a small, mode-neutral INTENT record and
// hands that record to whoever asks for it. The camera (dwCameraView's spirit mode) owns the
// persistent position/yaw/pitch/velocity and does the dt integration.
//
// WHY THE SPLIT
//   An earlier revision of this file drove the camera by shrinking the orbit radius, which faked
//   "moving toward what you are looking at" by consuming zoom. That is not translation: the camera
//   still could not leave its origin-locked sphere, could not pitch, and the user's chosen zoom was
//   destroyed by the gesture. The fix is to give the camera a real position and a real velocity, and
//   to demote this class to what it is actually good at -- deciding whether a contact was a tap, a
//   drag, or a hold, and turning pixels into angles. Touch stays completely independent of the
//   motion model: it cannot reach camera state even by accident, because it is never handed any.
//
// INTENT RECORD (the entire contract with the camera):
//     {
//       tap:    bool,        one-shot: this contact was an interaction, not a camera gesture
//       look:   [yawDeg, pitchDeg],   angular delta accumulated since the last poll
//       lookPx: [dxPx, dyPx],         the same drag in RAW PIXELS, carried alongside so a consumer
//                                     with its own historic gains (legacy orbit mode) can reproduce
//                                     them exactly instead of inverting this class's conversion
//       fling:  [yawDegPerSec, pitchDegPerSec] | null,   one-shot release impulse
//       glide:  -1..1,       throttle along the view direction. Positive accelerates forward (touch
//                            hold, or a wand push-forward impulse); NEGATIVE brakes and then
//                            reverses (a wand pull-back impulse). Touch alone never goes negative.
//       dolly:  worldUnits,  one-shot discrete step along the view direction (wheel / pinch)
//       stop:   bool,        one-shot: kill all velocity (new contact, or cancel)
//     }
//   Every field is mode-neutral. The camera decides what a "look" means: in spirit mode it rotates
//   yaw/pitch; in legacy orbit mode it moves azimuth/height. `glide` is meaningful only in spirit
//   mode -- orbit mode has nowhere to glide TO -- and orbit mode simply ignores it. That is what
//   makes the two modes coexist without either one being a special case of the other.
//
// GESTURE MODEL:
//   tap          -> poll() reports tap:true once; the demo keeps its existing interaction.
//   drag         -> look, with a release fling.
//   hold         -> after holdDelay, glide ramps 0 -> 1 over holdRamp seconds.
//   hold + drag  -> both are simply active at once. No special case, no arbitration.
//   release      -> glide returns to 0 and the fling decays; the camera's own damping eases it out.
//
// HOUSE RULES: pure scalar arithmetic, no matrices, no GL, no DOM. Node-constructible.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

class dwGfxSpiritCamera
{
	constructor(options = {})
	{
		const o = options || {};

		// ---- pixels -> degrees. lookSpeedX deliberately matches the demo's existing inline handler
		// (angleX += dx * 0.3) so the horizontal feel is unchanged when the intents are consumed by
		// legacy orbit mode. Pitch has no legacy equivalent -- the old rig could not pitch at all. ----
		this.lookSpeedX	= o.lookSpeedX	!== undefined ? o.lookSpeedX	: 0.3;   // deg per pixel, yaw
		this.lookSpeedY	= o.lookSpeedY	!== undefined ? o.lookSpeedY	: 0.22;  // deg per pixel, pitch
		this.invertY	= o.invertY		!== undefined ? o.invertY		: false;

		// ---- hold-to-glide throttle shaping ----
		this.holdGlide	= o.holdGlide	!== undefined ? o.holdGlide		: true;
		this.holdDelay	= o.holdDelay	!== undefined ? o.holdDelay		: 0.18;  // s of contact before the ramp starts
		this.holdRamp	= o.holdRamp	!== undefined ? o.holdRamp		: 0.55;  // s from 0 to full throttle

		// ---- release fling ----
		this.inertia	= o.inertia		!== undefined ? o.inertia		: 1.0;   // 0 disables the fling entirely
		this.flingMax	= o.flingMax	!== undefined ? o.flingMax		: 720.0; // deg/s cap, both axes

		// ---- tap classification ----
		this.tapMaxMs	= o.tapMaxMs	!== undefined ? o.tapMaxMs		: 250.0;
		this.tapSlopPx	= o.tapSlopPx	!== undefined ? o.tapSlopPx		: 12.0;

		this.enabled	= o.enabled		!== undefined ? o.enabled		: true;

		///////////////////////////////////////////////////////////////////////////////////////////
		// WAND ASSIST (additive THIRD input mode; TOUCH and legacy ORBIT are untouched)
		//
		// The device itself becomes the wand: rotating it supplies LOOK, and a push-forward
		// acceleration impulse supplies forward glide (pull back brakes, then reverses). It emits
		// the SAME mode-neutral intent record as a finger does, so the camera needs no new door and
		// legacy orbit mode is structurally immune -- sensor look is written only into the DEGREES
		// accumulators, never into lookPx, and orbit mode drives itself from lookPx alone.
		//
		// Everything is gated on an explicit state machine, because a motion sensor is not like a
		// pointer: it fires whether or not anyone asked for it, and on iOS reading it at all
		// requires permission obtained from a user gesture.
		//
		//     OFF -> PERMISSION -> CALIBRATING -> ACTIVE
		//                       \-> DENIED  (unavailable, insecure context, or refused)
		//
		// wandSample() REFUSES to accept anything outside CALIBRATING/ACTIVE and counts the
		// refusals, so "no sensor input before permission or while the mode is disabled" is
		// enforced here as well as by the host not attaching listeners. Two independent gates.
		//
		// No DOM: capability detection is a pure function of a plain env record the host supplies,
		// and samples arrive as plain numbers. That keeps the house rule intact and makes the whole
		// mode testable with synthetic events.
		///////////////////////////////////////////////////////////////////////////////////////////
		this.wandMode		= false;		// master enable; false => not one sample is read
		this.wandState		= "OFF";		// OFF | PERMISSION | CALIBRATING | ACTIVE | DENIED
		this.wandReason		= "";			// why DENIED, for the HUD and the console

		this.wandInvertX	= o.wandInvertX	!== undefined ? o.wandInvertX	: false;
		this.wandInvertY	= o.wandInvertY	!== undefined ? o.wandInvertY	: false;
		// camera degrees per device degree. 1.0 is true 1:1 pointing, which is what makes it read
		// as a wand rather than as a joystick.
		this.wandYawSens	= o.wandYawSens	!== undefined ? o.wandYawSens	: 1.0;
		this.wandPitchSens	= o.wandPitchSens !== undefined ? o.wandPitchSens : 1.0;

		// dead zone + hysteresis. The dead zone kills hand tremor around neutral; the hysteresis
		// SHRINKS it once the axis has broken out, so tracking stays smooth instead of chattering
		// on and off at the boundary. Re-arming needs a return to (dead - hyst).
		this.wandDeadZoneDeg	= o.wandDeadZoneDeg	!== undefined ? o.wandDeadZoneDeg	: 1.5;
		this.wandHystDeg		= o.wandHystDeg		!== undefined ? o.wandHystDeg		: 0.6;

		this.wandFilterHz	= o.wandFilterHz	!== undefined ? o.wandFilterHz	: 8.0;	// e-folds/s
		this.wandMaxRateDeg	= o.wandMaxRateDeg	!== undefined ? o.wandMaxRateDeg: 180.0;	// deg/s cap
		this.wandPitchLimit	= o.wandPitchLimit	!== undefined ? o.wandPitchLimit: 60.0;	// deg either side of neutral

		// ---- thrust: a genuine IMPULSE detector, not an accelerometer follower ----
		// A push is transient: it accelerates, then decelerates as the arm stops. Mapping raw
		// acceleration to throttle would have the rebound cancel the push exactly. So the first
		// breach latches a signed throttle and opens a refractory window during which the OPPOSITE
		// sign is ignored as rebound; the throttle then bleeds off on its own.
		this.wandThrustAxis		= o.wandThrustAxis		!== undefined ? o.wandThrustAxis	: 2;	// 0=x 1=y 2=z
		this.wandThrustSign		= o.wandThrustSign		!== undefined ? o.wandThrustSign	: -1.0;	// +z points at your face
		this.wandThrustEnter	= o.wandThrustEnter		!== undefined ? o.wandThrustEnter	: 2.2;	// m/s^2 to trigger
		this.wandThrustFullG	= o.wandThrustFullG		!== undefined ? o.wandThrustFullG	: 6.0;	// m/s^2 = full throttle
		this.wandThrustFilterHz	= o.wandThrustFilterHz	!== undefined ? o.wandThrustFilterHz: 6.0;
		this.wandImpulseHold	= o.wandImpulseHold		!== undefined ? o.wandImpulseHold	: 0.45;	// s refractory
		this.wandThrustDecay	= o.wandThrustDecay		!== undefined ? o.wandThrustDecay	: 2.5;	// e-folds/s

		// calibration / confidence
		this.wandCalibSamples	= o.wandCalibSamples	!== undefined ? o.wandCalibSamples	: 8;
		this.wandJitterRef		= o.wandJitterRef		!== undefined ? o.wandJitterRef		: 3.0;	// deg/sample = zero confidence
		this.wandConfidence		= 0.0;

		// While the wand is ACTIVE a plain touch HOLD must not also push you forward, or every
		// contact would move the camera by accident. Drag still steers and tap still interacts.
		this.wandSuppressHold	= o.wandSuppressHold	!== undefined ? o.wandSuppressHold	: true;

		// optional recorder. Samples are stored as compact 7-number arrays
		// [tMs, alpha, beta, gamma, ax, ay, az] so a session can be replayed verbatim.
		this.wandRecord		= o.wandRecord		!== undefined ? o.wandRecord	: false;
		this.wandRecordMax	= o.wandRecordMax	!== undefined ? o.wandRecordMax	: 600;

		this._wandNeutralA	= 0.0;
		this._wandNeutralB	= 0.0;
		this._wandCalibN	= 0;
		this._wandCalibBaseA = 0.0;
		this._wandCalibSumA	= 0.0;
		this._wandCalibSumB	= 0.0;
		this._wandJitterAcc	= 0.0;
		this._wandLastRawA	= null;
		this._wandLastRawB	= null;
		this._wandOffA		= 0.0;		// filtered offset from neutral, degrees
		this._wandOffB		= 0.0;
		this._wandPrevA		= 0.0;		// last EMITTED (post dead-zone) offset
		this._wandPrevB		= 0.0;
		this._wandArmedA	= false;	// dead-zone hysteresis latch
		this._wandArmedB	= false;
		this._wandThrustF	= 0.0;		// filtered thrust axis
		this._wandThrottle	= 0.0;		// signed, -1..1
		this._wandImpulseT	= 0.0;
		this._wandImpulseSgn = 0;
		this._wandLastT		= null;		// ms
		this._wandAccepted	= 0;
		this._wandRefused	= 0;
		this._wandSamples	= [];

		// ---- classifier state (gesture only -- nothing here is camera state) ----
		this.holding	= false;
		this.holdTime	= 0.0;

		this._lookYaw	= 0.0;   // accumulated since last poll
		this._lookPitch	= 0.0;
		this._lookPxX	= 0.0;   // the same drag in raw pixels
		this._lookPxY	= 0.0;
		this._dolly		= 0.0;
		this._tap		= false;
		this._stop		= false;
		this._fling		= null;

		this._yawRate	= 0.0;   // running estimate, deg/s
		this._pitchRate	= 0.0;

		this._downX		= 0.0;
		this._downY		= 0.0;
		this._downMs	= 0.0;
		this._travelPx	= 0.0;
		this._dragging	= false;
	}

	// ---- pointer input ---------------------------------------------------------------------------
	// The demo feeds RAW client pixels; this owns the pixels -> degrees conversion so the touch and
	// mouse handlers stay identical to each other and neither needs to know any camera constants.

	onPointerDown(clientX, clientY, timeMs)
	{
		this.holding	= true;
		this.holdTime	= 0.0;
		this._downX		= clientX;
		this._downY		= clientY;
		this._downMs	= timeMs;
		this._travelPx	= 0.0;
		this._dragging	= false;
		this._yawRate	= 0.0;
		this._pitchRate	= 0.0;
		// grabbing stops the drift, like catching a spinning globe.
		this._stop		= true;
		return this;
	}

	// dx/dy are pixel deltas since the last move. dt is used only to estimate the release rate.
	onPointerDrag(dx, dy, dt)
	{
		if (!this.holding) {
			return this;
		}
		this._travelPx += Math.abs(dx) + Math.abs(dy);
		if (this._travelPx > this.tapSlopPx) {
			this._dragging = true;
		}

		const dYaw   = dx * this.lookSpeedX;
		const dPitch = (this.invertY ? dy : -dy) * this.lookSpeedY;

		this._lookYaw   += dYaw;
		this._lookPitch += dPitch;
		this._lookPxX   += dx;
		this._lookPxY   += dy;

		// Exponential average rather than the raw last delta, so one jittery final event cannot
		// throw the camera on release.
		const step = (dt && dt > 1e-4) ? dt : (1.0 / 60.0);
		const w = 0.35;
		this._yawRate   = this._yawRate   * (1.0 - w) + (dYaw   / step) * w;
		this._pitchRate = this._pitchRate * (1.0 - w) + (dPitch / step) * w;
		return this;
	}

	// wheel / pinch: a discrete step along the view direction, in world units. Positive moves
	// forward. The camera clamps it against its own bounds; this class does not know them.
	addDolly(worldUnits)
	{
		this._dolly += worldUnits;
		return this;
	}

	// Returns { tap, dragged, heldMs } so the demo can decide whether this contact was an
	// interaction or a camera gesture. Classifies only -- triggers nothing.
	onPointerUp(timeMs)
	{
		const heldMs = timeMs - this._downMs;
		const tap = (!this._dragging) && (heldMs <= this.tapMaxMs) && (this._travelPx <= this.tapSlopPx);

		if (this.inertia && this._dragging) {
			this._fling = [
				this._clampRate(this._yawRate   * this.inertia),
				this._clampRate(this._pitchRate * this.inertia),
			];
		}
		else {
			this._fling = [0.0, 0.0];
		}
		if (tap) {
			this._tap = true;
		}

		this.holding	= false;
		this.holdTime	= 0.0;
		const r = { tap: tap, dragged: this._dragging, heldMs: heldMs };
		this._dragging	= false;
		this._travelPx	= 0.0;
		this._yawRate	= 0.0;
		this._pitchRate	= 0.0;
		return r;
	}

	// interrupted contact (touchcancel / pointer leaving the canvas): drop the gesture with no fling
	// and no tap, leaving no stale hold that would keep gliding forever.
	cancel()
	{
		this.holding	= false;
		this.holdTime	= 0.0;
		this._dragging	= false;
		this._travelPx	= 0.0;
		this._yawRate	= 0.0;
		this._pitchRate	= 0.0;
		this._fling		= [0.0, 0.0];
		this._tap		= false;
		this._stop		= true;
		return this;
	}

	// ---- wand assist: capability, permission, calibration ----------------------------------------

	// PURE capability test. The host passes what it can see of the environment; this decides. Kept
	// DOM-free so it is testable, and so a host on a platform with a different sensor API can
	// supply the same three booleans.
	//   env = { secure, hasOrientation, hasMotion, needsPermission }
	static wandCapability(env)
	{
		const e = env || {};
		if (!e.secure) {
			return { ok: false, needsPermission: false, reason: "insecure context (HTTPS required)" };
		}
		if (!e.hasOrientation) {
			return { ok: false, needsPermission: false, reason: "no DeviceOrientationEvent" };
		}
		return {
			ok: true,
			needsPermission: !!e.needsPermission,
			reason: e.hasMotion ? "" : "no DeviceMotionEvent (look only, no thrust)",
		};
	}

	// The host is about to ask the platform for permission. Enters PERMISSION, which accepts no
	// samples -- so a sensor that is already firing (Android needs no permission but may have been
	// left attached) still cannot move anything until wandGranted() lands.
	wandRequest()
	{
		this.wandMode	= true;
		this.wandState	= "PERMISSION";
		this.wandReason	= "";
		this._wandResetMotion();
		return this;
	}

	// Permission obtained (or not required). Goes straight to CALIBRATING: the mode is never usable
	// without a neutral, because "normalized relative to neutral" is the whole idea.
	wandGranted()
	{
		this.wandMode	= true;
		this.wandReason	= "";
		return this.recenterWand();
	}

	// Refused, or unavailable. Falls all the way back to touch: wandMode false means wandSample()
	// refuses everything even if the host forgets to detach a listener.
	wandDenied(reason)
	{
		this.wandMode	= false;
		this.wandState	= "DENIED";
		this.wandReason	= reason || "denied";
		this._wandResetMotion();
		return this;
	}

	// Explicit off. Distinct from DENIED so the HUD can tell "you turned it off" from "you cannot
	// have it", and so toggling back on does not have to clear a denial.
	wandDisable()
	{
		this.wandMode	= false;
		this.wandState	= "OFF";
		this.wandReason	= "";
		this._wandResetMotion();
		return this;
	}

	// Explicit recenter / calibrate. Whatever attitude the device is in NOW becomes neutral, which
	// is what makes the mode usable lying down, in a car, or in portrait vs landscape. Refuses to
	// run from OFF/DENIED, so it can never be a back door into sampling.
	recenterWand()
	{
		if (!this.wandMode) {
			return this;
		}
		this.wandState		= "CALIBRATING";
		this._wandCalibN	= 0;
		this._wandCalibSumA	= 0.0;
		this._wandCalibSumB	= 0.0;
		this._wandJitterAcc	= 0.0;
		this._wandLastRawA	= null;
		this._wandLastRawB	= null;
		this.wandConfidence	= 0.0;
		this._wandResetMotion();
		return this;
	}

	// Drop every derived quantity. Never touches the neutral: recenterWand owns that.
	_wandResetMotion()
	{
		this._wandOffA		= 0.0;
		this._wandOffB		= 0.0;
		this._wandPrevA		= 0.0;
		this._wandPrevB		= 0.0;
		this._wandArmedA	= false;
		this._wandArmedB	= false;
		this._wandThrustF	= 0.0;
		this._wandThrottle	= 0.0;
		this._wandImpulseT	= 0.0;
		this._wandImpulseSgn = 0;
		this._wandLastT		= null;
		return this;
	}

	// ---- wand assist: the single ingest point -----------------------------------------------------
	//
	// s = { t, alpha, beta, gamma, ax, ay, az }   (gamma is accepted and DELIBERATELY NOT USED:
	// roll must never reach the camera, or holding the phone at a natural angle would bank the
	// whole world.) Returns true only if the sample was accepted.
	wandSample(s)
	{
		if (!s) { return false; }
		if (!this.wandMode || (this.wandState !== "CALIBRATING" && this.wandState !== "ACTIVE")) {
			this._wandRefused++;
			return false;
		}

		const tMs = (typeof s.t === "number") ? s.t : 0.0;
		let dt = (this._wandLastT === null) ? (1.0 / 60.0) : ((tMs - this._wandLastT) * 0.001);
		if (!(dt > 1e-4)) { dt = 1.0 / 60.0; }
		if (dt > 0.1) { dt = 0.1; }
		this._wandLastT = tMs;

		const rawA = (typeof s.alpha === "number") ? s.alpha : 0.0;
		const rawB = (typeof s.beta  === "number") ? s.beta  : 0.0;

		if (this.wandRecord) {
			if (this._wandSamples.length >= this.wandRecordMax) { this._wandSamples.shift(); }
			this._wandSamples.push([tMs, rawA, rawB,
				(typeof s.gamma === "number") ? s.gamma : 0.0,
				(typeof s.ax === "number") ? s.ax : 0.0,
				(typeof s.ay === "number") ? s.ay : 0.0,
				(typeof s.az === "number") ? s.az : 0.0]);
		}
		this._wandAccepted++;

		// ---- jitter estimate -> confidence. Sample-to-sample movement while the user is trying to
		// hold still is the only honest measure of how trustworthy this sensor is. ----
		if (this._wandLastRawA !== null) {
			this._wandJitterAcc += Math.abs(dwGfxSpiritCamera.wandShortestArc(rawA - this._wandLastRawA))
				+ Math.abs(rawB - this._wandLastRawB);
		}
		this._wandLastRawA = rawA;
		this._wandLastRawB = rawB;

		if (this.wandState === "CALIBRATING")
		{
			if (this._wandCalibN === 0) { this._wandCalibBaseA = rawA; }
			// accumulate as shortest arcs from the first sample, so calibrating across the 0/360
			// seam averages correctly instead of landing at 180.
			this._wandCalibSumA += dwGfxSpiritCamera.wandShortestArc(rawA - this._wandCalibBaseA);
			this._wandCalibSumB += rawB;
			this._wandCalibN++;
			if (this._wandCalibN >= this.wandCalibSamples)
			{
				const n = this._wandCalibN;
				this._wandNeutralA = this._wandCalibBaseA + this._wandCalibSumA / n;
				this._wandNeutralB = this._wandCalibSumB / n;
				const jitter = (n > 1) ? (this._wandJitterAcc / (n - 1)) : this.wandJitterRef;
				let conf = 1.0 - (jitter / this.wandJitterRef);
				if (conf < 0.0) { conf = 0.0; }
				if (conf > 1.0) { conf = 1.0; }
				this.wandConfidence = conf;
				// seed the filters AT neutral and the emitted offsets at zero, so the first ACTIVE
				// sample produces exactly no look. Calibration must not itself move the camera.
				this._wandOffA = 0.0;
				this._wandOffB = 0.0;
				this._wandPrevA = 0.0;
				this._wandPrevB = 0.0;
				this.wandState = "ACTIVE";
			}
			return true;
		}

		// ---- ACTIVE: normalize relative to neutral, low-pass, dead zone, rate cap ----
		let offA = dwGfxSpiritCamera.wandShortestArc(rawA - this._wandNeutralA);
		let offB = rawB - this._wandNeutralB;
		if (this.wandInvertX) { offA = -offA; }
		if (this.wandInvertY) { offB = -offB; }
		// pitch limit is applied to the DEVICE offset, before any gain, so it is a real limit on how
		// far the wand can point rather than a clamp the sensitivity can defeat.
		const pl = this.wandPitchLimit;
		if (offB >  pl) { offB =  pl; }
		if (offB < -pl) { offB = -pl; }

		const k = 1.0 - Math.exp(-this.wandFilterHz * dt);
		this._wandOffA += (offA - this._wandOffA) * k;
		this._wandOffB += (offB - this._wandOffB) * k;

		const a = this._wandDead(this._wandOffA, "A");
		const b = this._wandDead(this._wandOffB, "B");

		// absolute pointing, expressed as a DELTA so it composes with drag steering and needs no
		// change anywhere downstream.
		let dYaw   = (a - this._wandPrevA) * this.wandYawSens;
		let dPitch = (b - this._wandPrevB) * this.wandPitchSens;
		this._wandPrevA = a;
		this._wandPrevB = b;

		const cap = this.wandMaxRateDeg * dt;
		if (dYaw   >  cap) { dYaw   =  cap; }
		if (dYaw   < -cap) { dYaw   = -cap; }
		if (dPitch >  cap) { dPitch =  cap; }
		if (dPitch < -cap) { dPitch = -cap; }

		// degrees only -- never lookPx. Legacy orbit mode reads lookPx, so it cannot be reached by
		// the sensor even if someone enables the wand while in orbit mode.
		this._lookYaw   += dYaw;
		this._lookPitch += dPitch;

		this._wandThrust(s, dt);
		return true;
	}

	// dead zone with hysteresis. Disarmed: output 0 until |v| breaks the full dead zone. Armed: the
	// dead zone shrinks by wandHystDeg, and stays shrunk until |v| falls back inside it. Subtracting
	// the (inner) zone rather than gating means the output is continuous through the threshold, so
	// arming does not step the camera.
	_wandDead(v, axis)
	{
		const dead = this.wandDeadZoneDeg;
		const inner = (dead - this.wandHystDeg) > 0.0 ? (dead - this.wandHystDeg) : 0.0;
		const key = (axis === "A") ? "_wandArmedA" : "_wandArmedB";
		const mag = Math.abs(v);
		if (this[key]) {
			if (mag < inner) { this[key] = false; return 0.0; }
		}
		else {
			if (mag <= dead) { return 0.0; }
			this[key] = true;
		}
		const out = mag - inner;
		return (v < 0.0) ? -out : out;
	}

	// signed impulse detector. See the constructor note: the refractory window is what stops the
	// deceleration half of a push from cancelling the push.
	_wandThrust(s, dt)
	{
		const acc = [
			(typeof s.ax === "number") ? s.ax : 0.0,
			(typeof s.ay === "number") ? s.ay : 0.0,
			(typeof s.az === "number") ? s.az : 0.0,
		];
		let i = this.wandThrustAxis;
		if (!(i >= 0 && i <= 2)) { i = 2; }
		const raw = acc[i] * this.wandThrustSign;

		const kt = 1.0 - Math.exp(-this.wandThrustFilterHz * dt);
		this._wandThrustF += (raw - this._wandThrustF) * kt;

		if (this._wandImpulseT > 0.0) { this._wandImpulseT -= dt; }

		const f = this._wandThrustF;
		if (Math.abs(f) > this.wandThrustEnter)
		{
			const sgn = (f > 0.0) ? 1 : -1;
			// inside the window, only the SAME direction may refresh; the opposite sign is the
			// rebound of the gesture we are already serving.
			if (!(this._wandImpulseT > 0.0 && sgn !== this._wandImpulseSgn))
			{
				let t = f / this.wandThrustFullG;
				if (t >  1.0) { t =  1.0; }
				if (t < -1.0) { t = -1.0; }
				this._wandThrottle	= t;
				this._wandImpulseSgn = sgn;
				this._wandImpulseT	= this.wandImpulseHold;
			}
		}
		this._wandThrottle *= Math.exp(-this.wandThrustDecay * dt);
		if (Math.abs(this._wandThrottle) < 1e-3) { this._wandThrottle = 0.0; }
		return this;
	}

	// shortest signed arc in degrees, for the alpha (compass) axis which wraps at 360.
	static wandShortestArc(d)
	{
		let x = d % 360.0;
		if (x >  180.0) { x -= 360.0; }
		if (x < -180.0) { x += 360.0; }
		return x;
	}

	// true only when the wand is genuinely driving the camera.
	wandActive()
	{
		return this.wandMode && this.wandState === "ACTIVE";
	}

	// compact HUD/diagnostic record.
	wandStatus()
	{
		return {
			state: this.wandState,
			reason: this.wandReason,
			active: this.wandActive(),
			yaw: this._wandOffA,
			pitch: this._wandOffB,
			thrust: this._wandThrottle,
			confidence: this.wandConfidence,
			accepted: this._wandAccepted,
			refused: this._wandRefused,
			recorded: this._wandSamples.length,
		};
	}

	// ---- recorder / replay -----------------------------------------------------------------------
	// Samples are [tMs, alpha, beta, gamma, ax, ay, az]. Replaying a recording through wandSample()
	// reproduces a session exactly, which is also how the tests drive synthetic sensor events.
	wandSamples()
	{
		return this._wandSamples;
	}
	wandClearSamples()
	{
		this._wandSamples = [];
		return this;
	}
	wandReplay(rows)
	{
		if (!rows) { return 0; }
		let n = 0;
		for (let i = 0; i < rows.length; i++) {
			const r = rows[i];
			if (!r) { continue; }
			const okSample = this.wandSample({
				t: r[0], alpha: r[1], beta: r[2], gamma: r[3], ax: r[4], ay: r[5], az: r[6],
			});
			if (okSample) { n++; }
		}
		return n;
	}

	// ---- intent ----------------------------------------------------------------------------------

	// Advance the hold timer and return the intent accumulated since the previous poll. One-shot
	// fields (tap, fling, dolly, stop) are cleared here, so an intent is delivered exactly once even
	// if the caller polls at a different rate than events arrive.
	poll(dt)
	{
		let h = dt;
		if (!(h > 0.0)) { h = 0.0; }
		if (h > 0.1) { h = 0.1; }

		const wandOn = this.wandActive();

		let glide = 0.0;
		if (this.holding && this.holdGlide) {
			this.holdTime += h;
			const over = this.holdTime - this.holdDelay;
			if (over > 0.0) {
				glide = (this.holdRamp > 1e-4) ? (over / this.holdRamp) : 1.0;
				if (glide > 1.0) { glide = 1.0; }
			}
			// While the wand is driving, forward motion belongs to the push impulse alone. A touch
			// that merely rests on the glass must not also fly the camera, or every tap-and-look
			// would move you. Drag still steers, tap still interacts -- only the hold THROTTLE goes.
			if (wandOn && this.wandSuppressHold) { glide = 0.0; }
		}
		// Thrust is SIGNED: forward glides, backward brakes against the existing velocity and then
		// reverses. That ordering is not special-cased anywhere -- it is what applying a negative
		// acceleration along the view direction does.
		if (wandOn) {
			glide += this._wandThrottle;
			if (glide >  1.0) { glide =  1.0; }
			if (glide < -1.0) { glide = -1.0; }
		}

		const intent = {
			tap:    this._tap,
			look:   [this._lookYaw, this._lookPitch],
			lookPx: [this._lookPxX, this._lookPxY],
			fling:  this._fling,
			glide:  this.enabled ? glide : 0.0,
			dolly:  this._dolly,
			stop:   this._stop,
			wand:   wandOn ? this._wandThrottle : 0.0,   // diagnostic only; glide already carries it
		};

		this._tap		= false;
		this._lookYaw	= 0.0;
		this._lookPitch	= 0.0;
		this._lookPxX	= 0.0;
		this._lookPxY	= 0.0;
		this._fling		= null;
		this._dolly		= 0.0;
		this._stop		= false;
		return intent;
	}

	// Convenience: poll and hand the intent to a camera that implements applyIntent()/updateSpirit().
	// This is the ONLY place this class touches a camera object, and it still only calls the two
	// public entry points -- it never reads or writes camera state. Returns the intent for the HUD.
	drive(cameraView, dt)
	{
		const intent = this.poll(dt);
		if (cameraView && typeof cameraView.applyIntent === "function") {
			cameraView.applyIntent(intent);
		}
		if (cameraView && typeof cameraView.updateSpirit === "function") {
			cameraView.updateSpirit(dt);
		}
		return intent;
	}

	// compact diagnostic for the HUD.
	state()
	{
		return {
			holding: this.holding,
			dragging: this._dragging,
			holdTime: this.holdTime,
			enabled: this.enabled,
			wand: this.wandStatus(),
		};
	}

	_clampRate(r)
	{
		const m = this.flingMax;
		if (r >  m) { return  m; }
		if (r < -m) { return -m; }
		return r;
	}
}

if (typeof module !== "undefined" && module.exports) {
	module.exports = { dwGfxSpiritCamera: dwGfxSpiritCamera };
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxParticle.js
//
// Reusable, pooled GPU particle / light-point engine that renders through the
// batched GL_POINTS path added to dwGfx (gfx.drawParticles). Nothing here touches
// the PBR / bloom / cubemap paths; effects just produce a flat Float32Array batch
// that dwGfx uploads and draws additively into the HDR scene buffer.
//
// Layout (must match dwGfx.createParticleResources / drawParticles):
//   [px, py, pz, size, r, g, b, a]  per point   (8 floats, a_position + a_color)
// Color rgb is HDR (already multiplied by intensity) so values > 1 bloom.
//
// Design:
//   dwGfxParticlePool     - SoA typed-array storage + free list, no per-frame GC.
//                           Standard physics/visual fields + a fixed trail ring.
//   dwGfxParticleEmitter  - config-driven spawn (continuous rate + burst) with an
//                           onDeath lifecycle seam (child emitters, e.g. fireworks).
//   dwGfxFireflyEffect     - concrete first effect: wandering fireflies that
//                           occasionally dart and leave a short light-point trail.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_PARTICLE_STRIDE = 8;   // floats per emitted point (matches dwGfx)

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Pooled particle storage. Fixed capacity, reused slots, zero per-frame allocation.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxParticlePool
{
	constructor(capacity = 256, trailLength = 8)
	{
		this.capacity		= capacity;
		this.trailLength	= trailLength;

		// physics
		this.px = new Float32Array(capacity);
		this.py = new Float32Array(capacity);
		this.pz = new Float32Array(capacity);
		this.vx = new Float32Array(capacity);
		this.vy = new Float32Array(capacity);
		this.vz = new Float32Array(capacity);
		this.ax = new Float32Array(capacity);
		this.ay = new Float32Array(capacity);
		this.az = new Float32Array(capacity);

		// visual
		this.r			= new Float32Array(capacity);
		this.g			= new Float32Array(capacity);
		this.b			= new Float32Array(capacity);
		this.size		= new Float32Array(capacity);
		this.intensity	= new Float32Array(capacity);
		this.alpha		= new Float32Array(capacity);

		// lifetime (seconds)
		this.age		= new Float32Array(capacity);
		this.life		= new Float32Array(capacity);
		this.alive		= new Uint8Array(capacity);

		// per-particle trail ring buffer (light-point history for darts).
		const tl = capacity * trailLength;
		this.trailX		= new Float32Array(tl);
		this.trailY		= new Float32Array(tl);
		this.trailZ		= new Float32Array(tl);
		this.trailI		= new Float32Array(tl);   // recorded intensity at that sample
		this.trailCount	= new Int32Array(capacity);
		this.trailHead	= new Int32Array(capacity);

		// free list of available slots
		this.freeList	= new Int32Array(capacity);
		for (let i = 0; i < capacity; i++) {
			this.freeList[i] = capacity - 1 - i;
		}
		this.freeTop	= capacity;   // number of free slots on the stack
	}

	spawn()
	{
		if (this.freeTop <= 0) {
			return -1;
		}
		const i = this.freeList[--this.freeTop];
		this.alive[i]		= 1;
		this.age[i]			= 0.0;
		this.vx[i] = this.vy[i] = this.vz[i] = 0.0;
		this.ax[i] = this.ay[i] = this.az[i] = 0.0;
		this.alpha[i]		= 0.0;
		this.intensity[i]	= 1.0;
		this.trailCount[i]	= 0;
		this.trailHead[i]	= 0;
		return i;
	}

	kill(i)
	{
		if (!this.alive[i]) {
			return;
		}
		this.alive[i] = 0;
		this.freeList[this.freeTop++] = i;
	}

	pushTrail(i, x, y, z, intensity)
	{
		const tl = this.trailLength;
		const head = this.trailHead[i];
		const base = i * tl + head;
		this.trailX[base] = x;
		this.trailY[base] = y;
		this.trailZ[base] = z;
		this.trailI[base] = intensity;
		this.trailHead[i] = (head + 1) % tl;
		if (this.trailCount[i] < tl) {
			this.trailCount[i]++;
		}
	}

	clearTrail(i)
	{
		this.trailCount[i] = 0;
		this.trailHead[i]  = 0;
	}
}

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Generic emitter. Continuous emission at `rate` particles/sec plus one-shot
// bursts. `config.init(pool, index)` seeds a freshly spawned particle. `onDeath`
// is the lifecycle seam a later fireworks effect can use to spawn child emitters.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxParticleEmitter
{
	constructor(pool, config = {})
	{
		this.pool		= pool;
		this.rate		= config.rate || 0.0;         // continuous particles/sec
		this.init		= config.init || null;        // function(pool, i)
		this.onDeath	= config.onDeath || null;     // function(pool, i)
		this.accumulator = 0.0;
		this.enabled	= true;
	}

	burst(n)
	{
		for (let k = 0; k < n; k++) {
			const i = this.pool.spawn();
			if (i < 0) {
				break;
			}
			if (this.init) {
				this.init(this.pool, i);
			}
		}
	}

	// continuous emission; call once per frame from the owning effect's update.
	update(dt)
	{
		if (!this.enabled || this.rate <= 0.0) {
			return;
		}
		this.accumulator += this.rate * dt;
		while (this.accumulator >= 1.0) {
			this.accumulator -= 1.0;
			const i = this.pool.spawn();
			if (i < 0) {
				break;
			}
			if (this.init) {
				this.init(this.pool, i);
			}
		}
	}
}

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Firefly / lightning-bug effect.
//
// Per firefly state machine (all times in seconds):
//   HIDDEN   -> invisible pause
//   FADE_IN  -> alpha 0..1
//   ACTIVE   -> gentle 3D wander; occasional brief dart with a light-point trail;
//               flicker; counts down its life
//   FADE_OUT -> alpha 1..0, then respawn (new home + pause)
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
const DW_FF_HIDDEN   = 0;
const DW_FF_FADE_IN  = 1;
const DW_FF_ACTIVE   = 2;
const DW_FF_FADE_OUT = 3;

class dwGfxFireflyEffect
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;

		// ---- tuneable constants (defaults: subtle warm yellow-green fireflies) ----
		const o = options;
		this.count			= o.count			!== undefined ? o.count			: 20;
		this.center			= o.center			|| [0.0, 2.3, 0.0];   // around the logo/scene
		this.bounds			= o.bounds			|| [3.0, 2.0, 3.0];   // half-extents of wander box
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 8;   // 6..10

		this.glowSize		= o.glowSize		!== undefined ? o.glowSize		: 0.07;   // world units
		this.glowIntensity	= o.glowIntensity	!== undefined ? o.glowIntensity	: 2.6;    // HDR

		this.colorBase		= o.colorBase		|| [0.75, 1.0, 0.35];  // warm yellow-green
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.12;

		// a minority of fireflies glow pink/magenta instead of yellow-green.
		this.magentaChance	= o.magentaChance	!== undefined ? o.magentaChance	: 0.28;   // fraction magenta
		this.magentaBase	= o.magentaBase		|| [1.0, 0.30, 0.85];  // pink/magenta

		this.wanderSpeed	= o.wanderSpeed		!== undefined ? o.wanderSpeed	: 0.35;   // drift amplitude
		this.springK		= o.springK			!== undefined ? o.springK		: 0.8;    // pull back to home

		this.dartChance		= o.dartChance		!== undefined ? o.dartChance	: 0.15;   // avg darts/sec/bug
		this.dartSpeed		= o.dartSpeed		!== undefined ? o.dartSpeed		: 6.0;    // impulse speed
		this.dartDuration	= o.dartDuration	!== undefined ? o.dartDuration	: 0.22;   // seconds

		this.fadeInTime		= o.fadeInTime		!== undefined ? o.fadeInTime	: 1.2;
		this.fadeOutTime	= o.fadeOutTime		!== undefined ? o.fadeOutTime	: 1.5;
		this.lifeMin		= o.lifeMin			!== undefined ? o.lifeMin		: 6.0;
		this.lifeMax		= o.lifeMax			!== undefined ? o.lifeMax		: 12.0;
		this.pauseMin		= o.pauseMin		!== undefined ? o.pauseMin		: 0.3;
		this.pauseMax		= o.pauseMax		!== undefined ? o.pauseMax		: 3.5;
		// --------------------------------------------------------------------------

		this.pool = new dwGfxParticlePool(this.count, this.trailLength);

		// per-firefly extra state (parallel to pool slots).
		const n = this.count;
		this.phase		= new Int32Array(n);
		this.phaseTimer	= new Float32Array(n);   // counts down HIDDEN pause / FADE times
		this.homeX		= new Float32Array(n);
		this.homeY		= new Float32Array(n);
		this.homeZ		= new Float32Array(n);
		this.seedA		= new Float32Array(n);   // wander phase seeds
		this.seedB		= new Float32Array(n);
		this.seedC		= new Float32Array(n);
		this.dartTimer	= new Float32Array(n);   // remaining dart time (>0 == darting)
		this.flickerP	= new Float32Array(n);   // flicker phase
		this.clock		= new Float32Array(n);   // per-bug simulation clock

		// GPU batch: head + trail points per firefly.
		const maxPoints = this.count * (1 + this.trailLength);
		this.batch = new Float32Array(maxPoints * DW_PARTICLE_STRIDE);
		this.batchCount = 0;

		// emitter drives spawning; init() seeds each firefly slot.
		this.emitter = new dwGfxParticleEmitter(this.pool, {
			init: (pool, i) => this._initFirefly(pool, i),
		});

		// spawn the full flight up front (fixed population that respawns in place).
		this.emitter.burst(this.count);
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	_initFirefly(pool, i)
	{
		// pick a home somewhere in the wander box around the scene center.
		this.homeX[i] = this.center[0] + this._rand(-this.bounds[0], this.bounds[0]);
		this.homeY[i] = this.center[1] + this._rand(-this.bounds[1], this.bounds[1]);
		this.homeZ[i] = this.center[2] + this._rand(-this.bounds[2], this.bounds[2]);

		pool.px[i] = this.homeX[i];
		pool.py[i] = this.homeY[i];
		pool.pz[i] = this.homeZ[i];

		// pick this firefly's palette once (stable for its whole lifetime): most
		// are the warm yellow-green base, a minority are pink/magenta. Trails read
		// pool.r/g/b in buildBatch, so they inherit this color automatically.
		const base = (Math.random() < this.magentaChance) ? this.magentaBase : this.colorBase;
		const j = this.colorJitter;
		pool.r[i] = Math.max(0.0, base[0] + this._rand(-j, j));
		pool.g[i] = Math.max(0.0, base[1] + this._rand(-j, j));
		pool.b[i] = Math.max(0.0, base[2] + this._rand(-j, j));

		pool.size[i]		= this.glowSize * this._rand(0.8, 1.3);
		pool.intensity[i]	= this.glowIntensity;
		pool.alpha[i]		= 0.0;
		pool.life[i]		= this._rand(this.lifeMin, this.lifeMax);
		pool.age[i]			= 0.0;
		pool.clearTrail(i);

		this.seedA[i]	= this._rand(0.0, Math.PI * 2.0);
		this.seedB[i]	= this._rand(0.0, Math.PI * 2.0);
		this.seedC[i]	= this._rand(0.0, Math.PI * 2.0);
		this.flickerP[i]= this._rand(0.0, Math.PI * 2.0);
		this.clock[i]	= this._rand(0.0, 100.0);
		this.dartTimer[i] = 0.0;

		this.phase[i]		= DW_FF_HIDDEN;
		this.phaseTimer[i]	= this._rand(this.pauseMin, this.pauseMax);
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}
		const pool = this.pool;

		for (let i = 0; i < this.count; i++)
		{
			if (!pool.alive[i]) {
				// fixed population: respawn any freed slot immediately.
				const s = pool.spawn();
				if (s >= 0) {
					this._initFirefly(pool, s);
				}
				continue;
			}

			this.clock[i] += dt;
			const t = this.clock[i];

			switch (this.phase[i])
			{
				case DW_FF_HIDDEN:
					pool.alpha[i] = 0.0;
					this.phaseTimer[i] -= dt;
					if (this.phaseTimer[i] <= 0.0) {
						this.phase[i] = DW_FF_FADE_IN;
						this.phaseTimer[i] = this.fadeInTime;
					}
					break;

				case DW_FF_FADE_IN:
					this.phaseTimer[i] -= dt;
					pool.alpha[i] = 1.0 - Math.max(0.0, this.phaseTimer[i]) / this.fadeInTime;
					if (this.phaseTimer[i] <= 0.0) {
						pool.alpha[i] = 1.0;
						this.phase[i] = DW_FF_ACTIVE;
					}
					break;

				case DW_FF_ACTIVE:
					pool.age[i] += dt;
					pool.alpha[i] = 1.0;
					if (pool.age[i] >= pool.life[i]) {
						this.phase[i] = DW_FF_FADE_OUT;
						this.phaseTimer[i] = this.fadeOutTime;
					}
					break;

				case DW_FF_FADE_OUT:
					this.phaseTimer[i] -= dt;
					pool.alpha[i] = Math.max(0.0, this.phaseTimer[i]) / this.fadeOutTime;
					if (this.phaseTimer[i] <= 0.0) {
						pool.kill(i);
						continue;
					}
					break;
			}

			// ---- motion (all phases except pure HIDDEN benefit from drift) ----
			// gentle layered-sine wander target offset from home.
			const w = this.wanderSpeed;
			const ox = w * (Math.sin(t * 0.7 + this.seedA[i]) + 0.5 * Math.sin(t * 1.7 + this.seedB[i]));
			const oy = w * 0.6 * (Math.sin(t * 0.9 + this.seedB[i]) + 0.4 * Math.sin(t * 2.3 + this.seedC[i]));
			const oz = w * (Math.sin(t * 0.6 + this.seedC[i]) + 0.5 * Math.sin(t * 1.3 + this.seedA[i]));

			const targetX = this.homeX[i] + ox;
			const targetY = this.homeY[i] + oy;
			const targetZ = this.homeZ[i] + oz;

			// occasional dart: brief random impulse (only while active & visible).
			if (this.phase[i] === DW_FF_ACTIVE && this.dartTimer[i] <= 0.0) {
				if (Math.random() < this.dartChance * dt) {
					this.dartTimer[i] = this.dartDuration;
					const dirX = this._rand(-1.0, 1.0);
					const dirY = this._rand(-0.6, 0.6);
					const dirZ = this._rand(-1.0, 1.0);
					const len = Math.hypot(dirX, dirY, dirZ) || 1.0;
					pool.vx[i] = (dirX / len) * this.dartSpeed;
					pool.vy[i] = (dirY / len) * this.dartSpeed;
					pool.vz[i] = (dirZ / len) * this.dartSpeed;
				}
			}

			if (this.dartTimer[i] > 0.0) {
				// darting: integrate velocity, record a fading light-point trail.
				this.dartTimer[i] -= dt;
				pool.px[i] += pool.vx[i] * dt;
				pool.py[i] += pool.vy[i] * dt;
				pool.pz[i] += pool.vz[i] * dt;
				// dampen the impulse so the dart eases out.
				const damp = Math.max(0.0, 1.0 - dt * 6.0);
				pool.vx[i] *= damp;
				pool.vy[i] *= damp;
				pool.vz[i] *= damp;
				pool.pushTrail(i, pool.px[i], pool.py[i], pool.pz[i], pool.intensity[i]);
			}
			else {
				// normal: spring toward the wander target (keeps it bounded).
				const k = Math.max(0.0, 1.0 - Math.exp(-this.springK * dt));
				pool.px[i] += (targetX - pool.px[i]) * k;
				pool.py[i] += (targetY - pool.py[i]) * k;
				pool.pz[i] += (targetZ - pool.pz[i]) * k;
				// let any lingering trail shrink away one sample per frame between darts.
				if (pool.trailCount[i] > 0) {
					pool.trailCount[i]--;
				}
			}

			// flicker modulates intensity a little for that firefly shimmer.
			this.flickerP[i] += dt * 6.0;
			const flick = 0.75 + 0.25 * Math.sin(this.flickerP[i]) + 0.1 * Math.sin(this.flickerP[i] * 2.7);
			pool.intensity[i] = this.glowIntensity * flick;
		}
	}

	// build the GPU batch from current state (read-only w.r.t. simulation).
	// Returns { data, count } for gfx.drawParticles.
	buildBatch()
	{
		const pool = this.pool;
		const batch = this.batch;
		const tl = this.trailLength;
		let o = 0;

		for (let i = 0; i < this.count; i++)
		{
			if (!pool.alive[i] || pool.alpha[i] <= 0.001) {
				continue;
			}

			const inten = pool.intensity[i];
			const a = pool.alpha[i];

			// bright head point.
			batch[o + 0] = pool.px[i];
			batch[o + 1] = pool.py[i];
			batch[o + 2] = pool.pz[i];
			batch[o + 3] = pool.size[i];
			batch[o + 4] = pool.r[i] * inten;
			batch[o + 5] = pool.g[i] * inten;
			batch[o + 6] = pool.b[i] * inten;
			batch[o + 7] = a;
			o += DW_PARTICLE_STRIDE;

			// trail: smaller, dimmer points, most-recent brightest.
			const tc = pool.trailCount[i];
			for (let s = 0; s < tc; s++)
			{
				// walk back from the most recent sample.
				const idx = ((pool.trailHead[i] - 1 - s) % tl + tl) % tl;
				const base = i * tl + idx;
				const falloff = 1.0 - (s / tl);          // 1 at head .. ~0 at tail
				const ti = pool.trailI[base] * falloff * 0.6;

				batch[o + 0] = pool.trailX[base];
				batch[o + 1] = pool.trailY[base];
				batch[o + 2] = pool.trailZ[base];
				batch[o + 3] = pool.size[i] * (0.3 + 0.5 * falloff);
				batch[o + 4] = pool.r[i] * ti;
				batch[o + 5] = pool.g[i] * ti;
				batch[o + 6] = pool.b[i] * ti;
				batch[o + 7] = a * falloff;
				o += DW_PARTICLE_STRIDE;
			}
		}

		this.batchCount = o / DW_PARTICLE_STRIDE;
		return { data: batch, count: this.batchCount };
	}
}

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Touch / tap burst effect.
//
// A compact, one-shot burst emitted at a point in the world: a bright central
// flash, a ring of expanding radial sparks, and a few faster tracer particles that
// leave short light-point trails. Reuses the same pooled storage, emitter seam and
// batched GL_POINTS light-point shader as the fireflies (no new shader, no PBR
// changes). Colors are HDR so the flash and tracers bloom.
//
// The demo builds a world-space dwRay from the tap location (dwGfxMath.screenToWorldRay)
// and calls emitFromRay(ray, touchDepth, strength). This first pass uses a fixed
// depth along the ray (no scene raycast); dwCollision is available for future use.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
const DW_TOUCH_FLASH  = 0;
const DW_TOUCH_SPARK  = 1;
const DW_TOUCH_TRACER = 2;

class dwGfxParticleEffectTouch
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- tuneable constants (restrained but immediately visible + blooms) ----
		this.touchDepth		= o.touchDepth		!== undefined ? o.touchDepth	: 6.0;   // world units in front of camera
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 6;     // tracer trail samples (4..10)

		this.burstCount		= o.burstCount		!== undefined ? o.burstCount	: 24;    // radial sparks per tap
		this.tracerCount	= o.tracerCount		!== undefined ? o.tracerCount	: 3;     // fast trailing streaks (2..3)
		this.maxConcurrent	= o.maxConcurrent	!== undefined ? o.maxConcurrent	: 4;     // overlapping taps before recycling

		this.flashSize		= o.flashSize		!== undefined ? o.flashSize		: 0.45;  // world units
		this.flashIntensity	= o.flashIntensity	!== undefined ? o.flashIntensity: 5.0;   // HDR
		this.flashLife		= o.flashLife		!== undefined ? o.flashLife		: 0.28;  // seconds

		this.sparkSize		= o.sparkSize		!== undefined ? o.sparkSize		: 0.10;
		this.sparkIntensity	= o.sparkIntensity	!== undefined ? o.sparkIntensity: 2.8;
		this.sparkSpeed		= o.sparkSpeed		!== undefined ? o.sparkSpeed		: 3.0;   // radial expansion speed
		this.sparkLifeMin	= o.sparkLifeMin	!== undefined ? o.sparkLifeMin	: 0.45;
		this.sparkLifeMax	= o.sparkLifeMax	!== undefined ? o.sparkLifeMax	: 0.85;

		this.tracerSize		= o.tracerSize		!== undefined ? o.tracerSize		: 0.11;
		this.tracerIntensity= o.tracerIntensity	!== undefined ? o.tracerIntensity: 3.4;
		this.tracerSpeed	= o.tracerSpeed		!== undefined ? o.tracerSpeed	: 8.0;
		this.tracerLife		= o.tracerLife		!== undefined ? o.tracerLife		: 0.5;

		this.drag			= o.drag			!== undefined ? o.drag			: 2.2;   // per-second velocity damping
		this.gravity		= o.gravity			!== undefined ? o.gravity		: -1.2;  // gentle downward pull (world y/s^2)
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.10;

		// HDR palette (warm core, cool sparks, magenta tracers to echo the fireflies).
		this.flashColor		= o.flashColor		|| [1.0, 0.92, 0.65];
		this.sparkColor		= o.sparkColor		|| [0.55, 0.85, 1.0];
		this.tracerColor	= o.tracerColor		|| [1.0, 0.45, 0.9];
		// --------------------------------------------------------------------------

		const perTap = 1 + this.burstCount + this.tracerCount;
		this.capacity = perTap * this.maxConcurrent;

		this.pool = new dwGfxParticlePool(this.capacity, this.trailLength);

		// per-slot behavior tag (parallel to pool slots).
		this.kind = new Int32Array(this.capacity);

		// emitter is used only for the onDeath/init seam parity with other effects;
		// bursts here are driven directly by emitFromRay for precise per-kind seeding.
		this.emitter = new dwGfxParticleEmitter(this.pool, {});

		// GPU batch: head + trail points per particle.
		const maxPoints = this.capacity * (1 + this.trailLength);
		this.batch = new Float32Array(maxPoints * DW_PARTICLE_STRIDE);
		this.batchCount = 0;

		this._pt = [0.0, 0.0, 0.0];   // scratch for ray.pointAt
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	_setColor(i, base)
	{
		const j = this.colorJitter;
		this.pool.r[i] = Math.max(0.0, base[0] + this._rand(-j, j));
		this.pool.g[i] = Math.max(0.0, base[1] + this._rand(-j, j));
		this.pool.b[i] = Math.max(0.0, base[2] + this._rand(-j, j));
	}

	// random unit vector (uniform on sphere).
	_randDir(out)
	{
		const z = this._rand(-1.0, 1.0);
		const a = this._rand(0.0, Math.PI * 2.0);
		const r = Math.sqrt(Math.max(0.0, 1.0 - z * z));
		out[0] = r * Math.cos(a);
		out[1] = r * Math.sin(a);
		out[2] = z;
		return out;
	}

	_spawnAt(cx, cy, cz, kind, size, intensity, life, color, speed)
	{
		const pool = this.pool;
		const i = pool.spawn();
		if (i < 0) {
			return -1;
		}
		this.kind[i] = kind;
		pool.px[i] = cx;
		pool.py[i] = cy;
		pool.pz[i] = cz;

		const dir = [0.0, 0.0, 0.0];
		if (speed > 0.0) {
			this._randDir(dir);
			pool.vx[i] = dir[0] * speed;
			pool.vy[i] = dir[1] * speed;
			pool.vz[i] = dir[2] * speed;
		}
		else {
			pool.vx[i] = pool.vy[i] = pool.vz[i] = 0.0;
		}

		this._setColor(i, color);
		pool.size[i]		= size;
		pool.intensity[i]	= intensity;
		pool.alpha[i]		= 0.0;
		pool.age[i]			= 0.0;
		pool.life[i]		= life;
		pool.clearTrail(i);
		return i;
	}

	// emit a burst `touchDepth` world units along `ray` from its origin. `strength`
	// (default 1) scales spark/tracer speed and intensity for softer/harder taps.
	emitFromRay(ray, touchDepth, strength)
	{
		const td = (touchDepth !== undefined && touchDepth !== null) ? touchDepth : this.touchDepth;
		const s  = (strength !== undefined && strength !== null) ? strength : 1.0;

		const c = ray.pointAt(td, this._pt);
		const cx = c[0], cy = c[1], cz = c[2];

		// central flash: stationary, brightest, quick decay.
		this._spawnAt(cx, cy, cz, DW_TOUCH_FLASH, this.flashSize, this.flashIntensity * s, this.flashLife, this.flashColor, 0.0);

		// expanding radial sparks.
		for (let k = 0; k < this.burstCount; k++) {
			const life = this._rand(this.sparkLifeMin, this.sparkLifeMax);
			const spd  = this.sparkSpeed * s * this._rand(0.6, 1.2);
			this._spawnAt(cx, cy, cz, DW_TOUCH_SPARK, this.sparkSize * this._rand(0.7, 1.2), this.sparkIntensity, life, this.sparkColor, spd);
		}

		// fast tracers with trails.
		for (let k = 0; k < this.tracerCount; k++) {
			this._spawnAt(cx, cy, cz, DW_TOUCH_TRACER, this.tracerSize, this.tracerIntensity, this.tracerLife, this.tracerColor, this.tracerSpeed * s * this._rand(0.85, 1.15));
		}
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}
		const pool = this.pool;
		const damp = Math.max(0.0, 1.0 - this.drag * dt);
		const fadeIn = 0.04;

		for (let i = 0; i < this.capacity; i++)
		{
			if (!pool.alive[i]) {
				continue;
			}

			pool.age[i] += dt;
			const age = pool.age[i];
			const life = pool.life[i];
			if (age >= life) {
				pool.kill(i);
				continue;
			}

			// quick pop-in then linear decay over the remaining life.
			let a;
			if (age < fadeIn) {
				a = age / fadeIn;
			}
			else {
				a = 1.0 - (age - fadeIn) / (life - fadeIn);
			}
			pool.alpha[i] = a < 0.0 ? 0.0 : a;

			// integrate motion (flash is stationary; sparks/tracers move).
			pool.vy[i] += this.gravity * dt;
			pool.px[i] += pool.vx[i] * dt;
			pool.py[i] += pool.vy[i] * dt;
			pool.pz[i] += pool.vz[i] * dt;
			pool.vx[i] *= damp;
			pool.vy[i] *= damp;
			pool.vz[i] *= damp;

			if (this.kind[i] === DW_TOUCH_TRACER) {
				pool.pushTrail(i, pool.px[i], pool.py[i], pool.pz[i], pool.intensity[i]);
			}
		}
	}

	// build the GPU batch from current state (read-only w.r.t. simulation).
	// Returns { data, count } for gfx.drawParticles. Same layout as the fireflies.
	buildBatch()
	{
		const pool = this.pool;
		const batch = this.batch;
		const tl = this.trailLength;
		let o = 0;

		for (let i = 0; i < this.capacity; i++)
		{
			if (!pool.alive[i] || pool.alpha[i] <= 0.001) {
				continue;
			}

			const inten = pool.intensity[i];
			const a = pool.alpha[i];

			// bright head point.
			batch[o + 0] = pool.px[i];
			batch[o + 1] = pool.py[i];
			batch[o + 2] = pool.pz[i];
			batch[o + 3] = pool.size[i];
			batch[o + 4] = pool.r[i] * inten;
			batch[o + 5] = pool.g[i] * inten;
			batch[o + 6] = pool.b[i] * inten;
			batch[o + 7] = a;
			o += DW_PARTICLE_STRIDE;

			// trail: smaller, dimmer points, most-recent brightest (tracers only).
			const tc = pool.trailCount[i];
			for (let s = 0; s < tc; s++)
			{
				const idx = ((pool.trailHead[i] - 1 - s) % tl + tl) % tl;
				const base = i * tl + idx;
				const falloff = 1.0 - (s / tl);
				const ti = pool.trailI[base] * falloff * 0.6;

				batch[o + 0] = pool.trailX[base];
				batch[o + 1] = pool.trailY[base];
				batch[o + 2] = pool.trailZ[base];
				batch[o + 3] = pool.size[i] * (0.3 + 0.5 * falloff);
				batch[o + 4] = pool.r[i] * ti;
				batch[o + 5] = pool.g[i] * ti;
				batch[o + 6] = pool.b[i] * ti;
				batch[o + 7] = a * falloff;
				o += DW_PARTICLE_STRIDE;
			}
		}

		this.batchCount = o / DW_PARTICLE_STRIDE;
		return { data: batch, count: this.batchCount };
	}
}

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Welding-torch effect (multi-touch, continuous).
//
// One persistent instance drives MANY simultaneous welding "heads" (one per finger),
// keyed by an arbitrary id (the demo passes Touch.identifier). Each head spews a tight,
// energetic, continuously-visible cone of hot sparks at its current world position and
// streaks them along the finger's motion (prev->current). Reuses the same pooled storage
// and batched GL_POINTS light-point path as the fireflies (no new shader, no PBR change).
// Colors are HDR (hot blue-white core + cyan, with a psychedelic magenta minority) so
// they bloom.
//
// Lifecycle (called from the demo's touch handlers):
//   start(id, x, y, z) - begin a welding head at a world point            (touchstart)
//   move(id, x, y, z)  - move a head; sparks streak along prev->current   (touchmove)
//   stop(id)           - end a head; its live sparks keep fading naturally (touchend / touchcancel)
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
const DW_WELD_SPARK  = 0;
const DW_WELD_TRACER = 1;

class dwGfxParticleEffectWeld
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- tuneable constants (compact, energetic, continuously visible) ----
		this.maxHeads		= o.maxHeads		!== undefined ? o.maxHeads		: 10;   // concurrent fingers
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 4;
		this.capacity		= o.capacity		!== undefined ? o.capacity		: 512;  // shared live-particle cap

		this.sparkRate		= o.sparkRate		!== undefined ? o.sparkRate		: 110.0; // sparks/sec/head
		this.tracerRate		= o.tracerRate		!== undefined ? o.tracerRate	: 14.0;  // trailing streaks/sec/head

		this.sparkSize		= o.sparkSize		!== undefined ? o.sparkSize		: 0.07;
		this.sparkIntensity	= o.sparkIntensity	!== undefined ? o.sparkIntensity: 3.4;   // HDR
		this.sparkSpeed		= o.sparkSpeed		!== undefined ? o.sparkSpeed		: 3.2;   // spit-cone speed
		this.sparkLifeMin	= o.sparkLifeMin	!== undefined ? o.sparkLifeMin	: 0.18;
		this.sparkLifeMax	= o.sparkLifeMax	!== undefined ? o.sparkLifeMax	: 0.45;

		this.tracerSize		= o.tracerSize		!== undefined ? o.tracerSize		: 0.09;
		this.tracerIntensity= o.tracerIntensity	!== undefined ? o.tracerIntensity: 4.0;
		this.tracerSpeed	= o.tracerSpeed		!== undefined ? o.tracerSpeed	: 5.5;
		this.tracerLifeMin	= o.tracerLifeMin	!== undefined ? o.tracerLifeMin	: 0.25;
		this.tracerLifeMax	= o.tracerLifeMax	!== undefined ? o.tracerLifeMax	: 0.5;

		this.drag			= o.drag			!== undefined ? o.drag			: 3.0;
		this.gravity		= o.gravity			!== undefined ? o.gravity		: -3.5;  // sparks spit then fall
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.12;

		// HDR palette: hot blue-white core + cyan, with a psychedelic magenta minority.
		this.coreColor		= o.coreColor		|| [0.85, 0.95, 1.0];
		this.cyanColor		= o.cyanColor		|| [0.55, 0.85, 1.0];
		this.magentaColor	= o.magentaColor	|| [1.0, 0.30, 0.85];
		this.magentaChance	= o.magentaChance	!== undefined ? o.magentaChance	: 0.30;
		// -----------------------------------------------------------------------

		this.pool = new dwGfxParticlePool(this.capacity, this.trailLength);
		this.kind = new Int32Array(this.capacity);   // per-slot behavior tag

		// active welding heads, keyed by id (Touch.identifier). "or equivalent" per spec.
		this.heads = new Map();

		const maxPoints = this.capacity * (1 + this.trailLength);
		this.batch = new Float32Array(maxPoints * DW_PARTICLE_STRIDE);
		this.batchCount = 0;
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	_pickColor()
	{
		if (Math.random() < this.magentaChance) {
			return this.magentaColor;
		}
		return (Math.random() < 0.5) ? this.coreColor : this.cyanColor;
	}

	_setColor(i, base)
	{
		const j = this.colorJitter;
		this.pool.r[i] = Math.max(0.0, base[0] + this._rand(-j, j));
		this.pool.g[i] = Math.max(0.0, base[1] + this._rand(-j, j));
		this.pool.b[i] = Math.max(0.0, base[2] + this._rand(-j, j));
	}

	_randDir(out)
	{
		const z = this._rand(-1.0, 1.0);
		const a = this._rand(0.0, Math.PI * 2.0);
		const r = Math.sqrt(Math.max(0.0, 1.0 - z * z));
		out[0] = r * Math.cos(a);
		out[1] = r * Math.sin(a);
		out[2] = z;
		return out;
	}

	// begin a welding head for a finger. No-op growth past maxHeads (existing heads keep going).
	start(id, x, y, z)
	{
		if (!this.heads.has(id) && this.heads.size >= this.maxHeads) {
			return;
		}
		this.heads.set(id, { x: x, y: y, z: z, px: x, py: y, pz: z, sparkAcc: 0.0, tracerAcc: 0.0 });
	}

	// update a head's current world position (previous position is advanced in update()).
	move(id, x, y, z)
	{
		const h = this.heads.get(id);
		if (!h) {
			return;
		}
		h.x = x;
		h.y = y;
		h.z = z;
	}

	// end a head. Its already-spawned sparks keep fading naturally via the shared pool.
	stop(id)
	{
		this.heads.delete(id);
	}

	stopAll()
	{
		this.heads.clear();
	}

	_spawn(kind, x, y, z, base, size, intensity, life, speed)
	{
		const pool = this.pool;
		const i = pool.spawn();
		if (i < 0) {
			return -1;   // shared cap reached: self-limits, no overflow.
		}
		this.kind[i] = kind;
		pool.px[i] = x;
		pool.py[i] = y;
		pool.pz[i] = z;

		const dir = [0.0, 0.0, 0.0];
		this._randDir(dir);
		// bias the spit slightly upward so it arcs like a torch rather than a sphere.
		pool.vx[i] = dir[0] * speed;
		pool.vy[i] = dir[1] * speed + this._rand(0.5, 1.5);
		pool.vz[i] = dir[2] * speed;

		this._setColor(i, base);
		pool.size[i]		= size;
		pool.intensity[i]	= intensity;
		pool.alpha[i]		= 0.0;
		pool.age[i]			= 0.0;
		pool.life[i]		= life;
		pool.clearTrail(i);
		return i;
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}
		const pool = this.pool;

		// ---- emit from each active head, streaking spawns along prev->current motion ----
		this.heads.forEach((h) =>
		{
			h.sparkAcc  += this.sparkRate  * dt;
			h.tracerAcc += this.tracerRate * dt;

			let ns = Math.floor(h.sparkAcc);
			h.sparkAcc -= ns;
			for (let k = 0; k < ns; k++) {
				const t = Math.random();
				const x = h.px + (h.x - h.px) * t;
				const y = h.py + (h.y - h.py) * t;
				const z = h.pz + (h.z - h.pz) * t;
				this._spawn(DW_WELD_SPARK, x, y, z, this._pickColor(),
					this.sparkSize * this._rand(0.7, 1.3),
					this.sparkIntensity,
					this._rand(this.sparkLifeMin, this.sparkLifeMax),
					this.sparkSpeed * this._rand(0.6, 1.3));
			}

			let nt = Math.floor(h.tracerAcc);
			h.tracerAcc -= nt;
			for (let k = 0; k < nt; k++) {
				const t = Math.random();
				const x = h.px + (h.x - h.px) * t;
				const y = h.py + (h.y - h.py) * t;
				const z = h.pz + (h.z - h.pz) * t;
				this._spawn(DW_WELD_TRACER, x, y, z, this._pickColor(),
					this.tracerSize,
					this.tracerIntensity,
					this._rand(this.tracerLifeMin, this.tracerLifeMax),
					this.tracerSpeed * this._rand(0.7, 1.2));
			}

			h.px = h.x;
			h.py = h.y;
			h.pz = h.z;
		});

		// ---- advance all live particles ----
		const damp = Math.max(0.0, 1.0 - this.drag * dt);
		const fadeIn = 0.03;
		for (let i = 0; i < this.capacity; i++)
		{
			if (!pool.alive[i]) {
				continue;
			}
			pool.age[i] += dt;
			const age = pool.age[i];
			const life = pool.life[i];
			if (age >= life) {
				pool.kill(i);
				continue;
			}

			let a;
			if (age < fadeIn) {
				a = age / fadeIn;
			}
			else {
				a = 1.0 - (age - fadeIn) / (life - fadeIn);
			}
			pool.alpha[i] = a < 0.0 ? 0.0 : a;

			pool.vy[i] += this.gravity * dt;
			pool.px[i] += pool.vx[i] * dt;
			pool.py[i] += pool.vy[i] * dt;
			pool.pz[i] += pool.vz[i] * dt;
			pool.vx[i] *= damp;
			pool.vy[i] *= damp;
			pool.vz[i] *= damp;

			if (this.kind[i] === DW_WELD_TRACER) {
				pool.pushTrail(i, pool.px[i], pool.py[i], pool.pz[i], pool.intensity[i]);
			}
		}
	}

	// build the GPU batch from current state (read-only). Same layout as the fireflies.
	buildBatch()
	{
		const pool = this.pool;
		const batch = this.batch;
		const tl = this.trailLength;
		let o = 0;

		for (let i = 0; i < this.capacity; i++)
		{
			if (!pool.alive[i] || pool.alpha[i] <= 0.001) {
				continue;
			}

			const inten = pool.intensity[i];
			const a = pool.alpha[i];

			batch[o + 0] = pool.px[i];
			batch[o + 1] = pool.py[i];
			batch[o + 2] = pool.pz[i];
			batch[o + 3] = pool.size[i];
			batch[o + 4] = pool.r[i] * inten;
			batch[o + 5] = pool.g[i] * inten;
			batch[o + 6] = pool.b[i] * inten;
			batch[o + 7] = a;
			o += DW_PARTICLE_STRIDE;

			const tc = pool.trailCount[i];
			for (let s = 0; s < tc; s++)
			{
				const idx = ((pool.trailHead[i] - 1 - s) % tl + tl) % tl;
				const base = i * tl + idx;
				const falloff = 1.0 - (s / tl);
				const ti = pool.trailI[base] * falloff * 0.6;

				batch[o + 0] = pool.trailX[base];
				batch[o + 1] = pool.trailY[base];
				batch[o + 2] = pool.trailZ[base];
				batch[o + 3] = pool.size[i] * (0.3 + 0.5 * falloff);
				batch[o + 4] = pool.r[i] * ti;
				batch[o + 5] = pool.g[i] * ti;
				batch[o + 6] = pool.b[i] * ti;
				batch[o + 7] = a * falloff;
				o += DW_PARTICLE_STRIDE;
			}
		}

		this.batchCount = o / DW_PARTICLE_STRIDE;
		return { data: batch, count: this.batchCount };
	}
}

///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Firework burst effect (multi-touch release).
//
// One persistent instance handles several overlapping exploding bursts. explodeAt(x,y,z)
// (or explodeFromRay) throws a bright central flash plus a WIDE radial shell of sparks and
// a handful of fast tracers with light-point trails — deliberately wider, faster and
// shorter-lived than the welding stream so a finger lift reads as a clear "pop". Reuses the
// same pooled storage / batched GL_POINTS path (no new shader). Psychedelic HDR palette
// (magenta/pink + cyan + acid-green accents) so it blooms.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
const DW_FW_FLASH  = 0;
const DW_FW_SPARK  = 1;
const DW_FW_TRACER = 2;

class dwGfxParticleEffectFirework
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- tuneable constants (wide, short-lived, clearly visible) ----
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 6;
		this.burstCount		= o.burstCount		!== undefined ? o.burstCount	: 60;   // radial sparks per pop
		this.tracerCount	= o.tracerCount		!== undefined ? o.tracerCount	: 10;   // fast trailing streaks
		this.maxConcurrent	= o.maxConcurrent	!== undefined ? o.maxConcurrent	: 6;    // overlapping pops

		this.flashSize		= o.flashSize		!== undefined ? o.flashSize		: 0.7;
		this.flashIntensity	= o.flashIntensity	!== undefined ? o.flashIntensity: 6.0;
		this.flashLife		= o.flashLife		!== undefined ? o.flashLife		: 0.30;

		this.sparkSize		= o.sparkSize		!== undefined ? o.sparkSize		: 0.12;
		this.sparkIntensity	= o.sparkIntensity	!== undefined ? o.sparkIntensity: 3.0;
		this.sparkSpeed		= o.sparkSpeed		!== undefined ? o.sparkSpeed		: 7.0;  // wide expansion
		this.sparkLifeMin	= o.sparkLifeMin	!== undefined ? o.sparkLifeMin	: 0.6;
		this.sparkLifeMax	= o.sparkLifeMax	!== undefined ? o.sparkLifeMax	: 1.2;

		this.tracerSize		= o.tracerSize		!== undefined ? o.tracerSize		: 0.13;
		this.tracerIntensity= o.tracerIntensity	!== undefined ? o.tracerIntensity: 3.6;
		this.tracerSpeed	= o.tracerSpeed		!== undefined ? o.tracerSpeed	: 11.0;
		this.tracerLife		= o.tracerLife		!== undefined ? o.tracerLife		: 0.8;

		this.drag			= o.drag			!== undefined ? o.drag			: 1.6;
		this.gravity		= o.gravity			!== undefined ? o.gravity		: -2.2;
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.12;

		// HDR psychedelic palette: warm core flash + magenta/pink, cyan and acid-green sparks.
		this.flashColor		= o.flashColor		|| [1.0, 0.90, 0.70];
		this.paletteA		= o.paletteA		|| [1.0, 0.30, 0.85];  // magenta / pink
		this.paletteB		= o.paletteB		|| [0.55, 0.85, 1.0];  // cyan
		this.paletteC		= o.paletteC		|| [0.70, 1.0, 0.40];  // acid-green accent
		// -----------------------------------------------------------------

		const perBurst = 1 + this.burstCount + this.tracerCount;
		this.capacity = perBurst * this.maxConcurrent;

		this.pool = new dwGfxParticlePool(this.capacity, this.trailLength);
		this.kind = new Int32Array(this.capacity);

		const maxPoints = this.capacity * (1 + this.trailLength);
		this.batch = new Float32Array(maxPoints * DW_PARTICLE_STRIDE);
		this.batchCount = 0;

		this._pt = [0.0, 0.0, 0.0];   // scratch for ray.pointAt
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	_setColor(i, base)
	{
		const j = this.colorJitter;
		this.pool.r[i] = Math.max(0.0, base[0] + this._rand(-j, j));
		this.pool.g[i] = Math.max(0.0, base[1] + this._rand(-j, j));
		this.pool.b[i] = Math.max(0.0, base[2] + this._rand(-j, j));
	}

	_randDir(out)
	{
		const z = this._rand(-1.0, 1.0);
		const a = this._rand(0.0, Math.PI * 2.0);
		const r = Math.sqrt(Math.max(0.0, 1.0 - z * z));
		out[0] = r * Math.cos(a);
		out[1] = r * Math.sin(a);
		out[2] = z;
		return out;
	}

	_pickPalette()
	{
		const r = Math.random();
		if (r < 0.5)  { return this.paletteA; }
		if (r < 0.8)  { return this.paletteB; }
		return this.paletteC;
	}

	_spawnAt(cx, cy, cz, kind, size, intensity, life, color, speed)
	{
		const pool = this.pool;
		const i = pool.spawn();
		if (i < 0) {
			return -1;
		}
		this.kind[i] = kind;
		pool.px[i] = cx;
		pool.py[i] = cy;
		pool.pz[i] = cz;

		const dir = [0.0, 0.0, 0.0];
		if (speed > 0.0) {
			this._randDir(dir);
			pool.vx[i] = dir[0] * speed;
			pool.vy[i] = dir[1] * speed;
			pool.vz[i] = dir[2] * speed;
		}
		else {
			pool.vx[i] = pool.vy[i] = pool.vz[i] = 0.0;
		}

		this._setColor(i, color);
		pool.size[i]		= size;
		pool.intensity[i]	= intensity;
		pool.alpha[i]		= 0.0;
		pool.age[i]			= 0.0;
		pool.life[i]		= life;
		pool.clearTrail(i);
		return i;
	}

	// explode at a world point. `strength` (default 1) scales spark/tracer speed + flash.
	explodeAt(x, y, z, strength)
	{
		const s = (strength !== undefined && strength !== null) ? strength : 1.0;

		// bright central flash: stationary, brightest, quick decay.
		this._spawnAt(x, y, z, DW_FW_FLASH, this.flashSize, this.flashIntensity * s, this.flashLife, this.flashColor, 0.0);

		// wide radial shell of sparks.
		for (let k = 0; k < this.burstCount; k++) {
			const life = this._rand(this.sparkLifeMin, this.sparkLifeMax);
			const spd  = this.sparkSpeed * s * this._rand(0.5, 1.3);
			this._spawnAt(x, y, z, DW_FW_SPARK, this.sparkSize * this._rand(0.7, 1.3), this.sparkIntensity, life, this._pickPalette(), spd);
		}

		// fast tracers with trails.
		for (let k = 0; k < this.tracerCount; k++) {
			this._spawnAt(x, y, z, DW_FW_TRACER, this.tracerSize, this.tracerIntensity, this.tracerLife, this._pickPalette(), this.tracerSpeed * s * this._rand(0.8, 1.2));
		}
	}

	// convenience: explode at a fixed depth along a world-space ray.
	explodeFromRay(ray, depth, strength)
	{
		const c = ray.pointAt(depth, this._pt);
		this.explodeAt(c[0], c[1], c[2], strength);
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}
		const pool = this.pool;
		const damp = Math.max(0.0, 1.0 - this.drag * dt);
		const fadeIn = 0.04;

		for (let i = 0; i < this.capacity; i++)
		{
			if (!pool.alive[i]) {
				continue;
			}
			pool.age[i] += dt;
			const age = pool.age[i];
			const life = pool.life[i];
			if (age >= life) {
				pool.kill(i);
				continue;
			}

			let a;
			if (age < fadeIn) {
				a = age / fadeIn;
			}
			else {
				a = 1.0 - (age - fadeIn) / (life - fadeIn);
			}
			pool.alpha[i] = a < 0.0 ? 0.0 : a;

			pool.vy[i] += this.gravity * dt;
			pool.px[i] += pool.vx[i] * dt;
			pool.py[i] += pool.vy[i] * dt;
			pool.pz[i] += pool.vz[i] * dt;
			pool.vx[i] *= damp;
			pool.vy[i] *= damp;
			pool.vz[i] *= damp;

			if (this.kind[i] === DW_FW_TRACER) {
				pool.pushTrail(i, pool.px[i], pool.py[i], pool.pz[i], pool.intensity[i]);
			}
		}
	}

	// build the GPU batch from current state (read-only). Same layout as the fireflies.
	buildBatch()
	{
		const pool = this.pool;
		const batch = this.batch;
		const tl = this.trailLength;
		let o = 0;

		for (let i = 0; i < this.capacity; i++)
		{
			if (!pool.alive[i] || pool.alpha[i] <= 0.001) {
				continue;
			}

			const inten = pool.intensity[i];
			const a = pool.alpha[i];

			batch[o + 0] = pool.px[i];
			batch[o + 1] = pool.py[i];
			batch[o + 2] = pool.pz[i];
			batch[o + 3] = pool.size[i];
			batch[o + 4] = pool.r[i] * inten;
			batch[o + 5] = pool.g[i] * inten;
			batch[o + 6] = pool.b[i] * inten;
			batch[o + 7] = a;
			o += DW_PARTICLE_STRIDE;

			const tc = pool.trailCount[i];
			for (let s = 0; s < tc; s++)
			{
				const idx = ((pool.trailHead[i] - 1 - s) % tl + tl) % tl;
				const base = i * tl + idx;
				const falloff = 1.0 - (s / tl);
				const ti = pool.trailI[base] * falloff * 0.6;

				batch[o + 0] = pool.trailX[base];
				batch[o + 1] = pool.trailY[base];
				batch[o + 2] = pool.trailZ[base];
				batch[o + 3] = pool.size[i] * (0.3 + 0.5 * falloff);
				batch[o + 4] = pool.r[i] * ti;
				batch[o + 5] = pool.g[i] * ti;
				batch[o + 6] = pool.b[i] * ti;
				batch[o + 7] = a * falloff;
				o += DW_PARTICLE_STRIDE;
			}
		}

		this.batchCount = o / DW_PARTICLE_STRIDE;
		return { data: batch, count: this.batchCount };
	}
}
"use strict";

// dwGfxFallingLeaves -- a reusable, configurable falling-leaves particle effect for the DW
// WebGL2 engine. Self-contained: it builds its OWN instanced program, its OWN base-quad + a
// dynamic per-instance buffer, and draws two-sided procedural leaf quads with rigorous GL
// state save/restore (mirroring dwGfxVolumetricFog's discipline). It is engine-agnostic beyond
// two hooks it shares with the rest of the demo: dwGfx.gl() for the WebGL2 context and the
// global m4 for matrix math (m4 ONLY, per project rule). StandardPBR and the fog are untouched.
//
// WHY A NEW FILE (architecture decision): the engine's other particle systems
// (dwGfxFireflyEffect / dwGfxParticleEffectWeld / dwGfxParticleEffectFirework) live only in the
// REMOTE dwGfx.php concatenation and expose an ADDITIVE light-point path (gfx.drawParticles),
// which cannot render two-sided textured/silhouetted leaf quads with tumbling orientation and
// alpha over-compositing. Leaves therefore need their own quad program. Following the proven
// local-override model of dwGfxVolumetricFog.js, this ships as a NEW local file the demo
// <script>-includes, so it takes effect immediately with no remote rebuild.
//
// RENDER SLOT: draw() is called in the demo's established transparent-particle slot -- inside the
// scene HDR framebuffer, after the opaque scene + fog, before the buffer is resolved -- so bloom
// can pick up bright leaves. Leaves DEPTH-TEST against the scene depth (so the logo occludes
// them) but do NOT write depth (depthMask(false)), matching the transparent-path convention
// ("avoid writing scene depth for transparent leaves").
//
// TOUCH / CATCH BRIDGE (deferred, per instructions): the local workspace does not contain the
// dwRay / dwCollision sources, so rather than fabricating duplicate collision code this effect
// EXPOSES a clean catch API -- tryCatchAt(worldPoint, radius), tryCatchRay(origin, dir, radius),
// getActiveLeaves() (world positions + bounds + stable ids) -- plus onCaught / onGroundHit
// callbacks. A later mini-game (or a dwRay/dwCollision multi-touch bridge) drives these without
// changing the emitter. See README section at the bottom of this file.

class dwGfxFallingLeaves
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options || {};

		// ---- capacity (bounded GPU/CPU cost; preallocated, reused, no per-frame churn) ----
		this.HARD_MAX  = 4096;                       // absolute upper bound (mobile safety)
		this.maxLeaves = dwGfxFallingLeaves._clampInt(o.maxLeaves, 1, this.HARD_MAX, 220);

		// ---- emission ----
		this.enabled      = (o.enabled      !== undefined) ? !!o.enabled      : true;
		this.emissionRate = (o.emissionRate !== undefined) ? +o.emissionRate  : 18.0; // leaves/sec at intensity 1
		this.intensity    = (o.intensity    !== undefined) ? +o.intensity     : 1.0;  // global 0..N multiplier

		// ---- spawn region (world space) ----
		// Leaves are born across a horizontal slab high above the scene and fall to groundHeight.
		this.spawnCenter = dwGfxFallingLeaves._vec3(o.spawnCenter, [0.0, 9.0, 0.0]);
		this.spawnExtent = dwGfxFallingLeaves._vec3(o.spawnExtent, [9.0, 1.2, 6.0]); // half-extents (x,y,z)
		this.groundHeight = (o.groundHeight !== undefined) ? +o.groundHeight : -2.0;

		// ---- motion (floaty autumn drift, NOT a fast drop) ----
		// Terminal fall speed ~= gravity/drag; with the defaults below that is ~0.54 world/s, so a
		// leaf takes ~15-20s to cross the framing and drifts rather than plummets. Raise gravity or
		// lower drag to make them fall faster.
		this.gravity      = (o.gravity   !== undefined) ? +o.gravity   : 0.7;  // downward accel (world/s^2)
		this.drag         = (o.drag      !== undefined) ? +o.drag      : 1.3;  // velocity damping (1/s)
		this.wind         = dwGfxFallingLeaves._vec3(o.wind, [0.35, 0.0, 0.1]); // steady lateral wind
		this.turbulence   = (o.turbulence !== undefined) ? +o.turbulence : 0.9; // gusty lateral sway
		this.swayScale    = (o.swayScale  !== undefined) ? +o.swayScale  : 1.4; // rocking amplitude scale
		this.fallSpeedMax = (o.fallSpeedMax !== undefined) ? +o.fallSpeedMax : 1.5; // terminal-ish clamp
		// gentle vertical "variable descent": a slow bob superimposed on the fall. Symmetric (net
		// zero over a cycle) so leaves still reach the ground; scaled by descentSway * turbulence.
		this.descentSway  = (o.descentSway !== undefined) ? +o.descentSway : 0.4;

		// ---- visual size ----
		// `radius` is the world-space visual radius of a leaf quad. It is chosen to match the
		// on-screen scale of the engine's firefly points: a leaf quad of world size S and a firefly
		// point of world size S scale identically on screen (both size = sizeScale * S / dist, with
		// sizeScale = projection[1][1] * canvasHeight * 0.5). The firefly world point-size lives in
		// the REMOTE dwGfxParticle.js and is not readable here, so DEFAULT_RADIUS is the documented
		// visual match -- tune it here or via the `radius` config. When `sizeRange` is not given
		// explicitly, a narrow +/-20% band is centered on `radius` (bounded per-leaf variation).
		// NOTE: catch/collision uses this.sz[i] (see tryCatchAt/tryCatchRay), so it stays coherent
		// with the visual size automatically -- there is no separate collision radius to keep in sync.
		this.radius = (o.radius !== undefined) ? Math.max(0.001, +o.radius) : dwGfxFallingLeaves.DEFAULT_RADIUS;

		// ---- per-leaf randomized ranges ----
		this.sizeRange     = (o.sizeRange !== undefined)
			? dwGfxFallingLeaves._range(o.sizeRange, [this.radius * 0.8, this.radius * 1.2])
			: [this.radius * 0.8, this.radius * 1.2];
		this.lifeRange     = dwGfxFallingLeaves._range(o.lifeRange, [18.0, 28.0]);  // seconds (floaty -> longer)
		this.spinRange     = dwGfxFallingLeaves._range(o.spinRange, [-2.4, 2.4]);   // rad/s angular vel

		// ---- palette (configurable; NO uncontrolled rainbow) ----
		// Each spawned leaf picks ONE palette entry and applies a small brightness-only variation,
		// so hues stay within the authored autumn set (orange/red/yellow/brown/gold by default).
		this.palette = dwGfxFallingLeaves._palette(o.palette, [
			[0.85, 0.35, 0.10], // orange
			[0.72, 0.12, 0.08], // red
			[0.90, 0.68, 0.12], // yellow/gold
			[0.55, 0.30, 0.10], // brown
			[0.88, 0.50, 0.14], // amber
		]);
		this.colorVariation = (o.colorVariation !== undefined) ? +o.colorVariation : 0.15; // brightness +/-

		// ---- lighting / look (kept LDR so bloom does not over-catch leaves) ----
		this.lightDir   = dwGfxFallingLeaves._vec3(o.lightDir, [0.35, 0.85, -0.40]); // matches moonDir
		this.ambient    = (o.ambient    !== undefined) ? +o.ambient    : 0.35;
		this.masterOpacity = (o.masterOpacity !== undefined) ? +o.masterOpacity : 1.0;
		this.fadeTime   = (o.fadeTime   !== undefined) ? +o.fadeTime   : 0.6; // fade-IN seconds (at birth)
		// Explicit fade-OUT: on a ground hit or lifetime expiry the leaf enters a brief, NON-scoring
		// "dying" state -- physics stop, alpha ramps to 0 over fadeOutTime, then the slot recycles.
		// The ground-hit callback/stat fires exactly ONCE at the semantic hit (when dying begins), not
		// again on recycle. fadeOutTime<=0 recycles immediately (prior behavior).
		this.fadeOutTime = (o.fadeOutTime !== undefined) ? Math.max(0.0, +o.fadeOutTime) : 0.8;

		// ---- optional texture hook (safe fallback: procedural silhouette when absent) ----
		// Accepts EITHER a raw WebGLTexture OR a dwGfxTexture wrapper (whose GPU handle is
		// .img.drawInfo.texture, populated asynchronously once the image loads, with .isReady true).
		// The handle is resolved lazily every frame in draw() so a not-yet-loaded logo renders as the
		// procedural fallback until its texture is live, then switches to the logo automatically -- no
		// duplicate load and no second GPU texture is ever created here.
		this.leafTexture = (o.leafTexture !== undefined) ? o.leafTexture : null;
		this._texState   = "fallback"; // HUD: "logo" | "waiting" | "fallback" (see _resolveLeafTexture)
		this._texWarned  = false;      // one-time guard so a rejected handle warns once, not every frame

		// ---- callbacks / events (mini-game hooks) ----
		this.onGroundHit = (typeof o.onGroundHit === "function") ? o.onGroundHit : null;
		this.onCaught    = (typeof o.onCaught    === "function") ? o.onCaught    : null;

		// ---- temporary "reaction" boost (website events) ----
		this._boostMul = 1.0;
		this._boostTimer = 0.0;

		// ---- deterministic PRNG (mulberry32) so spawns/palette are reproducible in tests ----
		this._seed = (o.seed !== undefined) ? (o.seed >>> 0) : 0x1EAF;
		this._rng  = dwGfxFallingLeaves._mulberry32(this._seed);

		// ---- internal counters (minimal, for testing/HUD) ----
		this.stats = { spawned: 0, groundHits: 0, caught: 0, expired: 0, active: 0 };

		this._time = 0.0;
		this._emitAccum = 0.0;
		this._idCounter = 0;

		this._allocStorage(this.maxLeaves);

		// ---- GL resources ----
		this.ok = false;
		this.initError = "";     // compact reason string when ok===false (HUD/diagnostics)
		this.lastDrawn = 0;      // instances issued by the most recent draw() (0 => not drawing)
		this.drawCalls = 0;      // total successful instanced draw calls (draw-path liveness)
		this.programInfo = null;
		this.vao = null;
		this.quadBuffer = null;
		this.instanceBuffer = null;
		this._loc = {};
		this._initGL();
	}

	// ---------------- storage (preallocated typed arrays + free list) ----------------
	_allocStorage(n)
	{
		this.px = new Float32Array(n); this.py = new Float32Array(n); this.pz = new Float32Array(n);
		this.vx = new Float32Array(n); this.vy = new Float32Array(n); this.vz = new Float32Array(n);
		this.rx = new Float32Array(n); this.ry = new Float32Array(n); this.rz = new Float32Array(n);
		this.wx = new Float32Array(n); this.wy = new Float32Array(n); this.wz = new Float32Array(n); // angular vel
		this.sz = new Float32Array(n);
		this.life = new Float32Array(n); this.maxLife = new Float32Array(n);
		this.cr = new Float32Array(n); this.cg = new Float32Array(n); this.cb = new Float32Array(n);
		this.phase = new Float32Array(n); // per-leaf sway phase
		this.ids = new Int32Array(n);
		this.active = new Uint8Array(n);
		// frozen leaves are drawn but skipped by the physics sim (used by the spawnTestLeaf probe:
		// a deterministic, static, large/bright leaf for definitive on-device draw-path verification).
		this.frozen = new Uint8Array(n);
		// dying leaves have already scored (ground hit / expiry): physics stopped, alpha ramping to 0
		// over dieTimer seconds, then recycled. They never re-fire callbacks and are not catchable.
		this.dying = new Uint8Array(n);
		this.dieTimer = new Float32Array(n);

		// free-list stack of unused slots; activeList holds packed active indices for iteration.
		this._free = new Int32Array(n);
		for (let i = 0; i < n; i++) { this._free[i] = n - 1 - i; }
		this._freeTop = n; // number of free slots on the stack
		this.count = 0;    // active leaves

		// interleaved per-instance GPU data: 11 floats/leaf (see STRIDE_F below).
		this._inst = new Float32Array(n * dwGfxFallingLeaves.STRIDE_F);

		// reusable scratch for getActiveLeaves() (no per-call allocation).
		this._scratchActive = new Array(n);
		for (let i = 0; i < n; i++) { this._scratchActive[i] = { id: 0, x: 0, y: 0, z: 0, size: 0 }; }
	}

	_initGL()
	{
		const gl = (typeof dwGfx !== "undefined" && dwGfx.gl) ? dwGfx.gl() : null;
		if (!gl) {
			this.initError = "no WebGL2 context";
			console.warn("dwGfxFallingLeaves: no WebGL2 context; leaves disabled.");
			return;
		}
		if (typeof twgl === "undefined" || !twgl.createProgramInfo) {
			this.initError = "twgl unavailable";
			console.warn("dwGfxFallingLeaves: twgl not loaded; leaves disabled.");
			return;
		}
		try {
			const errors = [];
			this.programInfo = twgl.createProgramInfo(
				gl,
				[dwGfxFallingLeaves.VS, dwGfxFallingLeaves.FS],
				{ errorCallback: (m) => errors.push(m) }
			);
			if (!this.programInfo || !this.programInfo.program) {
				// compact one-line reason for the HUD; full multi-line compiler output to console.
				const joined = errors.join(" | ").replace(/\s+/g, " ").trim();
				this.initError = "shader build failed" + (joined ? (": " + joined.slice(0, 160)) : "");
				console.warn("dwGfxFallingLeaves: shader build failed; leaves disabled." +
					(errors.length ? ("\ntwgl:\n" + errors.join("\n")) : ""));
				this.programInfo = null;
				return;
			}
			const prog = this.programInfo.program;

			// base quad (TRIANGLE_STRIP): corner in [-0.5,0.5], uv in [0,1]. 4 verts * (2+2) floats.
			const quad = new Float32Array([
				-0.5, -0.5, 0.0, 0.0,
				 0.5, -0.5, 1.0, 0.0,
				-0.5,  0.5, 0.0, 1.0,
				 0.5,  0.5, 1.0, 1.0,
			]);
			this.quadBuffer = gl.createBuffer();
			this.instanceBuffer = gl.createBuffer();
			this.vao = gl.createVertexArray();

			const L = this._loc;
			L.a_corner  = gl.getAttribLocation(prog, "a_corner");
			L.a_uv      = gl.getAttribLocation(prog, "a_uv");
			L.i_center  = gl.getAttribLocation(prog, "i_center");
			L.i_size    = gl.getAttribLocation(prog, "i_size");
			L.i_rot     = gl.getAttribLocation(prog, "i_rot");
			L.i_color   = gl.getAttribLocation(prog, "i_color");
			L.i_alpha   = gl.getAttribLocation(prog, "i_alpha");

			L.u_viewProjection = gl.getUniformLocation(prog, "u_viewProjection");
			L.u_lightDir       = gl.getUniformLocation(prog, "u_lightDir");
			L.u_ambient        = gl.getUniformLocation(prog, "u_ambient");
			L.u_opacity        = gl.getUniformLocation(prog, "u_opacity");
			L.u_useTexture     = gl.getUniformLocation(prog, "u_useTexture");
			L.u_leafTex        = gl.getUniformLocation(prog, "u_leafTex");

			// bounded analytic fog transmittance uniforms (per-leaf attenuation, set in draw()).
			L.u_fogEnabled        = gl.getUniformLocation(prog, "u_fogEnabled");
			L.u_fogCameraPos      = gl.getUniformLocation(prog, "u_fogCameraPos");
			L.u_fogDensity        = gl.getUniformLocation(prog, "u_fogDensity");
			L.u_fogMaxDistance    = gl.getUniformLocation(prog, "u_fogMaxDistance");
			L.u_fogPocketCount    = gl.getUniformLocation(prog, "u_fogPocketCount");
			L.u_fogPocketCenters  = gl.getUniformLocation(prog, "u_fogPocketCenters");
			L.u_fogPocketRadii    = gl.getUniformLocation(prog, "u_fogPocketRadii");
			L.u_fogPocketFeathers = gl.getUniformLocation(prog, "u_fogPocketFeathers");
			L.u_fogPocketDensity  = gl.getUniformLocation(prog, "u_fogPocketDensity");

			const prevVAO = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
			const prevArr = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
			gl.bindVertexArray(this.vao);

			gl.bindBuffer(gl.ARRAY_BUFFER, this.quadBuffer);
			gl.bufferData(gl.ARRAY_BUFFER, quad, gl.STATIC_DRAW);
			const QSTRIDE = 4 * 4;
			if (L.a_corner >= 0) {
				gl.enableVertexAttribArray(L.a_corner);
				gl.vertexAttribPointer(L.a_corner, 2, gl.FLOAT, false, QSTRIDE, 0);
			}
			if (L.a_uv >= 0) {
				gl.enableVertexAttribArray(L.a_uv);
				gl.vertexAttribPointer(L.a_uv, 2, gl.FLOAT, false, QSTRIDE, 2 * 4);
			}

			gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
			gl.bufferData(gl.ARRAY_BUFFER, this._inst.byteLength, gl.DYNAMIC_DRAW);
			const S = dwGfxFallingLeaves.STRIDE_F * 4;
			const setInst = (loc, size, offF) => {
				if (loc < 0) { return; }
				gl.enableVertexAttribArray(loc);
				gl.vertexAttribPointer(loc, size, gl.FLOAT, false, S, offF * 4);
				gl.vertexAttribDivisor(loc, 1);
			};
			setInst(L.i_center, 3, 0);
			setInst(L.i_size,   1, 3);
			setInst(L.i_rot,    3, 4);
			setInst(L.i_color,  3, 7);
			setInst(L.i_alpha,  1, 10);

			gl.bindVertexArray(prevVAO);
			gl.bindBuffer(gl.ARRAY_BUFFER, prevArr);

			this.ok = true;
		}
		catch (e) {
			this.initError = "init threw: " + ((e && e.message) ? e.message : String(e)).slice(0, 160);
			console.warn("dwGfxFallingLeaves: init threw; leaves disabled.", e);
			this.ok = false;
		}
	}

	// ---------------- public runtime setters (website-reaction friendly) ----------------
	setEnabled(on)        { this.enabled = !!on; }
	setEmissionRate(r)    { this.emissionRate = Math.max(0.0, +r || 0.0); }
	setIntensity(i)       { this.intensity = Math.max(0.0, +i || 0.0); }
	setGroundHeight(y)    { this.groundHeight = +y; }
	setWind(x, z)         { this.wind[0] = +x || 0.0; this.wind[2] = +z || 0.0; }
	setTurbulence(t)      { this.turbulence = Math.max(0.0, +t || 0.0); }
	setMasterOpacity(a)   { this.masterOpacity = dwGfxFallingLeaves._clamp01(+a); }
	// Accepts a raw WebGLTexture, a dwGfxTexture wrapper, or null. The handle is resolved lazily in
	// draw() so passing a wrapper before its image has loaded is fine (renders fallback until ready).
	setLeafTexture(tex)   { this.leafTexture = tex || null; }
	setRadius(r)          { this.radius = Math.max(0.001, +r || 0.001); this.sizeRange = [this.radius * 0.8, this.radius * 1.2]; }

	// True only if `obj` is a live WebGLTexture belonging to THIS gl context (not deleted, not from
	// another context). Safe to call on ANY value: it never lets gl.isTexture see a non-WebGLTexture
	// argument (which throws a WebIDL TypeError in browsers) and never triggers a GL error.
	_isNativeTexture(gl, obj)
	{
		if (!obj || typeof obj !== "object") { return false; } // null / primitive / undefined
		const Ctor = (typeof WebGLTexture !== "undefined") ? WebGLTexture : null;
		if (Ctor) {
			// Same-realm brand check first. gl.isTexture requires a WebGLTexture?|null argument, so we
			// only hand it a value that has already passed `instanceof` -- never an arbitrary object.
			if (!(obj instanceof Ctor)) { return false; }
			try { return !!gl.isTexture(obj); } catch (e) { return false; }
		}
		// WebGLTexture constructor not exposed in this realm (unusual): guardedly probe with isTexture.
		try { return !!gl.isTexture(obj); } catch (e) { return false; }
	}

	// One-time diagnostic (never per-frame) naming the shape of a rejected texture value.
	_warnBadTexOnce(value, why)
	{
		if (this._texWarned) { return; }
		this._texWarned = true;
		let shape;
		try {
			const ctor = (value && value.constructor && value.constructor.name) ? value.constructor.name : "";
			shape = (value === null) ? "null"
				: (typeof value !== "object") ? (typeof value + " " + String(value))
				: (ctor || "Object") + (typeof value.then === "function" ? " (thenable/Promise)" : "");
		} catch (e) { shape = "<unprintable>"; }
		if (typeof console !== "undefined" && console.warn) {
			console.warn("dwGfxFallingLeaves: leaf texture rejected (" + why + "); drawing procedural fallback. Got: " + shape);
		}
	}

	// Resolve the current leaf texture to a live WebGLTexture handle for THIS context, or null. Records
	// a compact HUD state on this._texState. Accepts a raw WebGLTexture or a dwGfxTexture wrapper (whose
	// authoritative native handle is .img.drawInfo.texture, assigned only after the image's async load,
	// with .isReady flipped true then). Never creates/owns a texture, so there is no duplicate load or
	// second GPU owner. Never returns a wrapper, texture-info, promise, image, or cross-context handle.
	_resolveLeafTexture(gl)
	{
		const t = this.leafTexture;
		if (!t) { this._texState = "fallback"; return null; }         // nothing configured (not an error)

		// 1) a raw native WebGLTexture handed in directly.
		if (this._isNativeTexture(gl, t)) { this._texState = "logo"; this._texWarned = false; return t; }

		// 2) a dwGfxTexture wrapper: read its authoritative native handle (populated on async load).
		if (t.img && t.img.drawInfo && ("texture" in t.img.drawInfo)) {
			const handle = t.img.drawInfo.texture;
			if (this._isNativeTexture(gl, handle)) { this._texState = "logo"; this._texWarned = false; return handle; }
			// wrapper present but no LIVE handle yet: still loading, or a load that failed.
			if (!t.isReady) { this._texState = "waiting"; return null; } // expected pre-load: no warning
			// isReady true but the handle is not a live texture for this context -> genuinely wrong.
			this._texState = "fallback";
			this._warnBadTexOnce(handle, "dwGfxTexture.img.drawInfo.texture is not a live WebGLTexture for this context");
			return null;
		}

		// 3) something else entirely (a twgl texture-info, a promise, an Image, a cross-context handle).
		this._texState = "fallback";
		this._warnBadTexOnce(t, "leafTexture is neither a WebGLTexture nor a dwGfxTexture wrapper");
		return null;
	}

	// Swap the palette immediately. Existing airborne leaves keep their color; only NEW spawns
	// use the new palette (so a swap reads as a natural transition, not a jarring recolor).
	setPalette(arr)       { this.palette = dwGfxFallingLeaves._palette(arr, this.palette); }

	// Temporarily multiply the emission rate for `seconds` (e.g. a website "gust" reaction).
	// Multiple calls take the strongest active boost; it decays automatically.
	boost(multiplier, seconds)
	{
		const m = Math.max(1.0, +multiplier || 1.0);
		const s = Math.max(0.0, +seconds || 0.0);
		if (m >= this._boostMul || this._boostTimer <= 0.0) { this._boostMul = m; }
		this._boostTimer = Math.max(this._boostTimer, s);
	}

	// ---------------- catch API (deferred touch/collision bridge) ----------------
	// Catch the nearest active leaf within `radius` of a WORLD point. Returns the caught leaf id
	// (>=0) or -1. Fires onCaught({id,x,y,z,size}). Safe to call from multi-touch handlers: call
	// it once per active pointer -- each call removes at most one leaf.
	tryCatchAt(worldPoint, radius)
	{
		if (!worldPoint) { return -1; }
		const px = +worldPoint[0], py = +worldPoint[1], pz = +worldPoint[2];
		const r = Math.max(0.0, +radius || 0.0);
		let best = -1, bestD2 = r * r;
		for (let i = 0; i < this.maxLeaves; i++) {
			if (!this.active[i] || this.dying[i]) { continue; } // dying leaves already scored
			// generous catch radius scales with leaf size so bigger leaves are easier to grab.
			const rr = bestD2 + this.sz[i] * this.sz[i];
			const dx = this.px[i] - px, dy = this.py[i] - py, dz = this.pz[i] - pz;
			const d2 = dx * dx + dy * dy + dz * dz;
			if (d2 <= rr && d2 <= bestD2 + this.sz[i] * this.sz[i]) {
				if (d2 < bestD2) { bestD2 = d2; best = i; }
			}
		}
		if (best < 0) { return -1; }
		const info = { id: this.ids[best], x: this.px[best], y: this.py[best], z: this.pz[best], size: this.sz[best] };
		this._despawn(best);
		this.stats.caught++;
		if (this.onCaught) { try { this.onCaught(info); } catch (e) { /* user cb must not break the sim */ } }
		return info.id;
	}

	// Catch along a world-space ray (origin + normalized dir): grabs the nearest leaf whose center
	// lies within `radius` of the ray. This is the clean hook a dwRay/dwCollision screen-pick
	// bridge calls once per pointer; no duplicate collision math is baked into the emitter.
	tryCatchRay(origin, dir, radius)
	{
		if (!origin || !dir) { return -1; }
		const ox = +origin[0], oy = +origin[1], oz = +origin[2];
		let dxn = +dir[0], dyn = +dir[1], dzn = +dir[2];
		const dl = Math.hypot(dxn, dyn, dzn) || 1.0;
		dxn /= dl; dyn /= dl; dzn /= dl;
		const r = Math.max(0.0, +radius || 0.0);
		let best = -1, bestT = Infinity;
		for (let i = 0; i < this.maxLeaves; i++) {
			if (!this.active[i] || this.dying[i]) { continue; } // dying leaves already scored
			const wx = this.px[i] - ox, wy = this.py[i] - oy, wz = this.pz[i] - oz;
			const t = wx * dxn + wy * dyn + wz * dzn; // projection onto ray
			if (t < 0.0) { continue; }                // behind the ray origin
			const cx = ox + dxn * t, cy = oy + dyn * t, cz = oz + dzn * t;
			const ex = this.px[i] - cx, ey = this.py[i] - cy, ez = this.pz[i] - cz;
			const perp2 = ex * ex + ey * ey + ez * ez;
			const rr = r + this.sz[i];
			if (perp2 <= rr * rr && t < bestT) { bestT = t; best = i; }
		}
		if (best < 0) { return -1; }
		const info = { id: this.ids[best], x: this.px[best], y: this.py[best], z: this.pz[best], size: this.sz[best] };
		this._despawn(best);
		this.stats.caught++;
		if (this.onCaught) { try { this.onCaught(info); } catch (e) { /* swallow */ } }
		return info.id;
	}

	// Snapshot of currently airborne leaves (world position + size + stable id) for an external
	// collision system. Reuses an internal scratch array to avoid per-frame allocation; the
	// returned array's first getActiveLeaves().length entries are valid for THIS frame only.
	getActiveLeaves()
	{
		let n = 0;
		for (let i = 0; i < this.maxLeaves; i++) {
			if (!this.active[i] || this.dying[i]) { continue; } // dying leaves already scored -> not catchable
			const e = this._scratchActive[n++];
			e.id = this.ids[i]; e.x = this.px[i]; e.y = this.py[i]; e.z = this.pz[i]; e.size = this.sz[i];
		}
		this._scratchActive.length = this.maxLeaves; // keep capacity stable
		return this._scratchActive.slice(0, n);
	}

	// ---------------- diagnostics / probe (temporary on-device verification) ----------------
	// Place a large, bright, STATIC leaf at a world point (default: origin, slightly toward +Z so
	// it sits just in front of the logo). Bypasses spawn-region/physics/emission entirely, so it
	// is a definitive test of the shader + instance buffer + draw call. Returns the leaf id (>=0)
	// or -1 at capacity. Cleared with clearTestLeaves() or reset(); it does not fall, expire, drift,
	// or fire ground/caught events, so it never contaminates normal behavior. (Rendering still
	// requires a live GL context; the demo's probe key checks .ok before calling.)
	spawnTestLeaf(worldPoint, opts)
	{
		if (this._freeTop <= 0) { return -1; }
		const o = opts || {};
		const i = this._free[--this._freeTop];
		const p = (Array.isArray(worldPoint) && worldPoint.length >= 3) ? worldPoint : [0.0, 0.8, 1.0];
		this.px[i] = +p[0]; this.py[i] = +p[1]; this.pz[i] = +p[2];
		this.vx[i] = 0.0; this.vy[i] = 0.0; this.vz[i] = 0.0;
		this.rx[i] = 0.0; this.ry[i] = 0.0; this.rz[i] = 0.0;
		this.wx[i] = 0.0; this.wy[i] = 0.0; this.wz[i] = 0.0;
		this.sz[i] = (o.size !== undefined) ? +o.size : 1.4;   // large so it is unmistakable
		this.maxLife[i] = 1e9;                                  // never expires
		this.life[i] = Math.max(this.fadeTime, 0.001);         // fully faded-in immediately
		this.phase[i] = 0.0;
		const c = (Array.isArray(o.color) && o.color.length >= 3) ? o.color : [1.0, 0.85, 0.15]; // bright gold
		this.cr[i] = dwGfxFallingLeaves._clamp01(+c[0]);
		this.cg[i] = dwGfxFallingLeaves._clamp01(+c[1]);
		this.cb[i] = dwGfxFallingLeaves._clamp01(+c[2]);
		this.frozen[i] = 1;
		this.dying[i] = 0; this.dieTimer[i] = 0.0;
		this.active[i] = 1;
		this.ids[i] = this._idCounter++;
		this.count++;
		return this.ids[i];
	}

	// Remove all probe (frozen) leaves without touching the ambient sim or firing events.
	clearTestLeaves()
	{
		for (let i = 0; i < this.maxLeaves; i++) {
			if (this.active[i] && this.frozen[i]) { this.frozen[i] = 0; this._despawn(i); }
		}
	}

	frozenCount()
	{
		let n = 0;
		for (let i = 0; i < this.maxLeaves; i++) { if (this.active[i] && this.frozen[i]) { n++; } }
		return n;
	}

	// Compact one-line status for the HUD. Distinguishes: init/shader failure (with compact error),
	// enabled-with-live-count, updating-but-not-drawing (count>0 yet nothing issued last frame), and
	// draw success (drawn>0). The caller prefixes the on/off label + caught/missed counters.
	statusLine()
	{
		if (!this.ok) { return "INIT-FAIL " + (this.initError || "unknown"); }
		const fz = this.frozenCount();
		let s = "live " + this.count + "/" + this.maxLeaves + " drawn " + this.lastDrawn;
		if (this.count > 0 && this.lastDrawn === 0) { s += " (NOT DRAWING)"; }
		if (fz > 0) { s += " probe " + fz; }
		// texture state: logo (using the My Kinda Fit logo), waiting (wrapper set, image still
		// loading), or fallback (procedural leaf silhouette -- no texture, or a failed load).
		s += " tex:" + this._texState;
		return s;
	}

	// ---------------- lifecycle ----------------
	_despawn(i)
	{
		if (!this.active[i]) { return; }
		this.active[i] = 0;
		this.dying[i] = 0; this.dieTimer[i] = 0.0; // clean the recycled slot
		this._free[this._freeTop++] = i;
		this.count--;
		if (this.count < 0) { this.count = 0; }
	}

	// Begin the non-scoring fade-out. The scoring event (ground hit / expiry) has ALREADY happened
	// and its callback/stat fired exactly once at the call site; this only ramps alpha to 0 and then
	// recycles. fadeOutTime<=0 recycles immediately (identical to the prior instant-disappear).
	_beginDying(i)
	{
		if (this.fadeOutTime > 0.0) {
			this.dying[i] = 1;
			this.dieTimer[i] = this.fadeOutTime;
			this.vx[i] = 0.0; this.vy[i] = 0.0; this.vz[i] = 0.0; // physics stop; it settles/fades in place
		} else {
			this._despawn(i);
		}
	}

	_spawn()
	{
		if (this._freeTop <= 0) { return -1; } // at capacity -> drop (bounded cost, no churn)
		const i = this._free[--this._freeTop];
		const rng = this._rng;

		this.px[i] = this.spawnCenter[0] + (rng() * 2.0 - 1.0) * this.spawnExtent[0];
		this.py[i] = this.spawnCenter[1] + (rng() * 2.0 - 1.0) * this.spawnExtent[1];
		this.pz[i] = this.spawnCenter[2] + (rng() * 2.0 - 1.0) * this.spawnExtent[2];

		this.vx[i] = (rng() * 2.0 - 1.0) * 0.4;
		this.vy[i] = -0.2 - rng() * 0.5;
		this.vz[i] = (rng() * 2.0 - 1.0) * 0.4;

		this.rx[i] = rng() * 6.2831853;
		this.ry[i] = rng() * 6.2831853;
		this.rz[i] = rng() * 6.2831853;
		this.wx[i] = this.spinRange[0] + rng() * (this.spinRange[1] - this.spinRange[0]);
		this.wy[i] = this.spinRange[0] + rng() * (this.spinRange[1] - this.spinRange[0]);
		this.wz[i] = this.spinRange[0] + rng() * (this.spinRange[1] - this.spinRange[0]);

		this.sz[i] = this.sizeRange[0] + rng() * (this.sizeRange[1] - this.sizeRange[0]);
		this.maxLife[i] = this.lifeRange[0] + rng() * (this.lifeRange[1] - this.lifeRange[0]);
		this.life[i] = 0.0;
		this.phase[i] = rng() * 6.2831853;

		// palette pick (index only -> hue stays authored) + brightness-only variation.
		const p = this.palette[(rng() * this.palette.length) | 0] || this.palette[0];
		const b = 1.0 + (rng() * 2.0 - 1.0) * this.colorVariation;
		this.cr[i] = dwGfxFallingLeaves._clamp01(p[0] * b);
		this.cg[i] = dwGfxFallingLeaves._clamp01(p[1] * b);
		this.cb[i] = dwGfxFallingLeaves._clamp01(p[2] * b);

		this.frozen[i] = 0;
		this.dying[i] = 0; this.dieTimer[i] = 0.0;
		this.active[i] = 1;
		this.ids[i] = this._idCounter++;
		this.count++;
		this.stats.spawned++;
		return i;
	}

	update(dt)
	{
		if (!(dt > 0.0)) { return; }
		if (dt > 0.1) { dt = 0.1; } // clamp tab-away spikes (stable sim)
		this._time += dt;

		// decay the temporary reaction boost.
		if (this._boostTimer > 0.0) {
			this._boostTimer -= dt;
			if (this._boostTimer <= 0.0) { this._boostTimer = 0.0; this._boostMul = 1.0; }
		}

		// emission (accumulator so fractional rates are exact and frame-rate independent).
		if (this.enabled) {
			this._emitAccum += this.emissionRate * this.intensity * this._boostMul * dt;
			let budget = this._freeTop; // never spawn more than free slots this frame
			while (this._emitAccum >= 1.0 && budget > 0) {
				this._emitAccum -= 1.0;
				this._spawn();
				budget--;
			}
			if (this._emitAccum > 4.0) { this._emitAccum = 4.0; } // cap backlog
		}

		const g = this.gravity, dragK = Math.max(0.0, 1.0 - this.drag * dt);
		const wpx = this.wind[0], wpz = this.wind[2], turb = this.turbulence, t = this._time;

		for (let i = 0; i < this.maxLeaves; i++) {
			if (!this.active[i]) { continue; }

			// probe leaves (spawnTestLeaf): drawn but not simulated -- give a gentle roll so they
			// read as a leaf, but no translation/gravity/ground/expire, so they stay put on-device.
			if (this.frozen[i]) {
				this.rz[i] += 0.6 * dt;
				continue;
			}

			// dying leaves (already scored): count down the fade-out, keep a slow settle-roll, then
			// recycle. No physics, no ground/expire re-trigger, no duplicate callback.
			if (this.dying[i]) {
				this.rz[i] += 0.3 * dt;
				this.dieTimer[i] -= dt;
				if (this.dieTimer[i] <= 0.0) { this._despawn(i); }
				continue;
			}

			// gusty lateral wind: steady + per-leaf sinusoidal turbulence (cheap, no texture).
			const ph = this.phase[i];
			const gustX = wpx + turb * Math.sin(t * 1.7 + ph);
			const gustZ = wpz + turb * Math.cos(t * 1.3 + ph * 0.7);

			this.vx[i] += gustX * dt;
			this.vz[i] += gustZ * dt;
			this.vy[i] -= g * dt;
			// gentle variable descent: a slow, per-leaf vertical bob (symmetric over a cycle, so it
			// only modulates the rate of fall -- leaves still reach the ground and fire onGroundHit).
			this.vy[i] += this.descentSway * turb * Math.sin(t * 0.9 + ph * 1.3) * dt;

			// drag + terminal fall clamp.
			this.vx[i] *= dragK; this.vy[i] *= dragK; this.vz[i] *= dragK;
			if (this.vy[i] < -this.fallSpeedMax) { this.vy[i] = -this.fallSpeedMax; }

			this.px[i] += this.vx[i] * dt;
			this.py[i] += this.vy[i] * dt;
			this.pz[i] += this.vz[i] * dt;

			// tumble/rock: base angular velocity + wind-driven sway on the roll axis.
			this.rx[i] += this.wx[i] * dt;
			this.ry[i] += this.wy[i] * dt;
			this.rz[i] += (this.wz[i] + this.swayScale * Math.sin(t * 2.1 + ph)) * dt;

			this.life[i] += dt;

			// semantic ground hit: fire the callback/stat EXACTLY ONCE here, pin to the ground, then
			// enter the non-scoring fade-out (the leaf lingers a moment instead of vanishing).
			if (this.py[i] <= this.groundHeight) {
				this.py[i] = this.groundHeight;
				const info = { id: this.ids[i], x: this.px[i], y: this.py[i], z: this.pz[i], size: this.sz[i] };
				this.stats.groundHits++;
				if (this.onGroundHit) { try { this.onGroundHit(info); } catch (e) { /* swallow */ } }
				this._beginDying(i);
				continue;
			}
			// lifetime cap (bounded backlog; counts separately from a ground hit). Also fades out.
			if (this.life[i] >= this.maxLife[i]) {
				this.stats.expired++;
				this._beginDying(i);
				continue;
			}
		}
		this.stats.active = this.count;
	}

	// per-leaf opacity: fade IN at birth, and (once dying) fade OUT over fadeOutTime. Scaled by
	// masterOpacity. Fade-out is driven by the dying dieTimer so it is visible on ground/expiry
	// regardless of remaining lifetime (a ground hit can happen long before maxLife).
	_leafAlpha(i)
	{
		if (this.dying[i]) {
			const ft = this.fadeOutTime;
			const a = (ft > 0.0) ? (this.dieTimer[i] / ft) : 0.0;
			return dwGfxFallingLeaves._clamp01(a) * this.masterOpacity;
		}
		const f = this.fadeTime;
		let a = 1.0;
		if (f > 0.0 && this.life[i] < f) { a = this.life[i] / f; }
		return dwGfxFallingLeaves._clamp01(a) * this.masterOpacity;
	}

	// Pack active leaves contiguously into the instance buffer. Returns instance count.
	_buildInstances()
	{
		const inst = this._inst, ST = dwGfxFallingLeaves.STRIDE_F;
		let n = 0;
		for (let i = 0; i < this.maxLeaves; i++) {
			if (!this.active[i]) { continue; }
			const o = n * ST;
			inst[o + 0] = this.px[i]; inst[o + 1] = this.py[i]; inst[o + 2] = this.pz[i];
			inst[o + 3] = this.sz[i];
			inst[o + 4] = this.rx[i]; inst[o + 5] = this.ry[i]; inst[o + 6] = this.rz[i];
			inst[o + 7] = this.cr[i]; inst[o + 8] = this.cg[i]; inst[o + 9] = this.cb[i];
			inst[o + 10] = this._leafAlpha(i);
			n++;
		}
		return n;
	}

	// Draw all active leaves in ONE instanced call into the currently-bound framebuffer (the
	// demo calls this inside the scene HDR buffer, in the transparent-particle slot). Saves and
	// restores every GL bit it touches so it never disturbs the fog / bloom / particle passes.
	// fogParams (optional): the SAME bounded analytic structure the light points use
	// ({ cameraPos, density, maxDistance, pocketCount, pocketCenters, pocketRadii,
	// pocketFeathers, pocketDensity }, arrays sized to 8 pockets). When supplied, each leaf's
	// color + alpha are attenuated by transmittance along its own camera->center path (so leaves
	// may be drawn AFTER the fullscreen fog composite without it overlaying foreground leaves).
	// Omit / pass null to render leaves unfogged (u_fogEnabled=0 => v_fogT=1.0).
	draw(cameraView, fogParams)
	{
		if (!this.ok || !this.programInfo || this.count <= 0) { return; }
		const gl = (typeof dwGfx !== "undefined" && dwGfx.gl) ? dwGfx.gl() : null;
		if (!gl || typeof m4 === "undefined") { return; }

		const n = this._buildInstances();
		if (n <= 0) { this.lastDrawn = 0; return; }

		// view-projection = proj * inverse(cameraWorld)  (m4 ONLY; same convention as the fog/shadow).
		const viewProjection = m4.multiply(cameraView.projectionMatrix, m4.inverse(cameraView.worldMatrix));

		// ---- save GL state ----
		const prevProgram   = gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO       = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArr       = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		const prevBlend     = gl.getParameter(gl.BLEND);
		const prevDepthTest = gl.getParameter(gl.DEPTH_TEST);
		const prevDepthMask = gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevCull      = gl.getParameter(gl.CULL_FACE);
		const prevDepthFunc = gl.getParameter(gl.DEPTH_FUNC);
		const prevSrcRGB    = gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB    = gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcA      = gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstA      = gl.getParameter(gl.BLEND_DST_ALPHA);
		const prevActiveTex = gl.getParameter(gl.ACTIVE_TEXTURE);

		gl.useProgram(this.programInfo.program);
		gl.bindVertexArray(this.vao);

		gl.bindBuffer(gl.ARRAY_BUFFER, this.instanceBuffer);
		gl.bufferSubData(gl.ARRAY_BUFFER, 0, this._inst, 0, n * dwGfxFallingLeaves.STRIDE_F);

		const L = this._loc;
		gl.uniformMatrix4fv(L.u_viewProjection, false, viewProjection);
		// normalize the light dir on the CPU (cheap, avoids a per-fragment normalize of a uniform).
		let lx = this.lightDir[0], ly = this.lightDir[1], lz = this.lightDir[2];
		const ll = Math.hypot(lx, ly, lz) || 1.0; lx /= ll; ly /= ll; lz /= ll;
		if (L.u_lightDir) { gl.uniform3f(L.u_lightDir, lx, ly, lz); }
		if (L.u_ambient)  { gl.uniform1f(L.u_ambient, this.ambient); }
		if (L.u_opacity)  { gl.uniform1f(L.u_opacity, dwGfxFallingLeaves._clamp01(this.masterOpacity)); }

		const texHandle = this._resolveLeafTexture(gl); // also updates this._texState for the HUD
		const useTex = !!texHandle;
		if (L.u_useTexture) { gl.uniform1i(L.u_useTexture, useTex ? 1 : 0); }
		if (useTex) {
			gl.activeTexture(gl.TEXTURE0);
			gl.bindTexture(gl.TEXTURE_2D, texHandle);
			if (L.u_leafTex) { gl.uniform1i(L.u_leafTex, 0); }
		}

		// bounded analytic per-leaf fog: set the LIVE fog uniforms when fogParams is supplied,
		// otherwise force u_fogEnabled=0 so the VS emits v_fogT=1.0 (unfogged, unchanged output).
		const fogOn = !!(fogParams && fogParams.pocketCount !== undefined);
		if (L.u_fogEnabled) { gl.uniform1i(L.u_fogEnabled, fogOn ? 1 : 0); }
		if (fogOn) {
			const cp = fogParams.cameraPos || [0, 0, 0];
			if (L.u_fogCameraPos)   { gl.uniform3f(L.u_fogCameraPos, cp[0], cp[1], cp[2]); }
			if (L.u_fogDensity)     { gl.uniform1f(L.u_fogDensity, (fogParams.density !== undefined) ? fogParams.density : 0.0); }
			if (L.u_fogMaxDistance) { gl.uniform1f(L.u_fogMaxDistance, (fogParams.maxDistance !== undefined) ? fogParams.maxDistance : 1.0e6); }
			if (L.u_fogPocketCount) { gl.uniform1i(L.u_fogPocketCount, fogParams.pocketCount | 0); }
			if (L.u_fogPocketCenters  && fogParams.pocketCenters)  { gl.uniform3fv(L.u_fogPocketCenters, fogParams.pocketCenters); }
			if (L.u_fogPocketRadii    && fogParams.pocketRadii)    { gl.uniform3fv(L.u_fogPocketRadii, fogParams.pocketRadii); }
			if (L.u_fogPocketFeathers && fogParams.pocketFeathers) { gl.uniform1fv(L.u_fogPocketFeathers, fogParams.pocketFeathers); }
			if (L.u_fogPocketDensity  && fogParams.pocketDensity)  { gl.uniform1fv(L.u_fogPocketDensity, fogParams.pocketDensity); }
		}

		// deliberate transparent-leaf state: alpha over-composite, depth-TESTED (logo occludes),
		// NO depth write (transparent path), two-sided (cull disabled).
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
		gl.enable(gl.DEPTH_TEST);
		// Set depthFunc EXPLICITLY: enabling DEPTH_TEST without it inherits whatever the prior
		// fog/particle passes left bound (a wrong func can reject every leaf fragment -> invisible).
		gl.depthFunc(gl.LEQUAL);
		gl.depthMask(false);
		gl.disable(gl.CULL_FACE);

		gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, n);
		this.lastDrawn = n;
		this.drawCalls++;

		// ---- restore GL state ----
		if (useTex) { gl.bindTexture(gl.TEXTURE_2D, null); }
		gl.activeTexture(prevActiveTex);
		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcA, prevDstA);
		if (prevBlend)     { gl.enable(gl.BLEND); }      else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (prevCull)      { gl.enable(gl.CULL_FACE); }  else { gl.disable(gl.CULL_FACE); }
		gl.depthFunc(prevDepthFunc);
		gl.depthMask(prevDepthMask);
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArr);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);
	}

	// Remove all airborne leaves without firing events (e.g. scene reset).
	reset()
	{
		for (let i = 0; i < this.maxLeaves; i++) { this.active[i] = 0; this.frozen[i] = 0; this.dying[i] = 0; this.dieTimer[i] = 0.0; }
		this._freeTop = this.maxLeaves;
		for (let i = 0; i < this.maxLeaves; i++) { this._free[i] = this.maxLeaves - 1 - i; }
		this.count = 0;
		this._emitAccum = 0.0;
		this.stats.active = 0;
	}

	dispose()
	{
		const gl = (typeof dwGfx !== "undefined" && dwGfx.gl) ? dwGfx.gl() : null;
		if (!gl) { return; }
		if (this.quadBuffer)     { gl.deleteBuffer(this.quadBuffer); this.quadBuffer = null; }
		if (this.instanceBuffer) { gl.deleteBuffer(this.instanceBuffer); this.instanceBuffer = null; }
		if (this.vao)            { gl.deleteVertexArray(this.vao); this.vao = null; }
		if (this.programInfo && this.programInfo.program) { gl.deleteProgram(this.programInfo.program); }
		this.programInfo = null;
		this.ok = false;
	}

	// ---------------- small pure helpers ----------------
	static _clamp01(v) { return v < 0.0 ? 0.0 : (v > 1.0 ? 1.0 : v); }
	static _clampInt(v, lo, hi, dflt)
	{
		if (v === undefined || v === null || !isFinite(+v)) { return dflt; }
		let x = +v | 0; if (x < lo) { x = lo; } if (x > hi) { x = hi; } return x;
	}
	static _vec3(v, dflt) { return (Array.isArray(v) && v.length >= 3) ? [+v[0], +v[1], +v[2]] : dflt.slice(); }
	static _range(v, dflt)
	{
		if (Array.isArray(v) && v.length >= 2 && isFinite(+v[0]) && isFinite(+v[1])) {
			const a = +v[0], b = +v[1]; return a <= b ? [a, b] : [b, a];
		}
		return dflt.slice();
	}
	static _palette(v, dflt)
	{
		if (Array.isArray(v) && v.length > 0) {
			const out = [];
			for (let i = 0; i < v.length; i++) {
				const c = v[i];
				if (Array.isArray(c) && c.length >= 3) {
					out.push([dwGfxFallingLeaves._clamp01(+c[0]), dwGfxFallingLeaves._clamp01(+c[1]), dwGfxFallingLeaves._clamp01(+c[2])]);
				}
			}
			if (out.length > 0) { return out; }
		}
		return dflt.map((c) => c.slice());
	}
	static _mulberry32(seed)
	{
		let a = seed >>> 0;
		return function () {
			a |= 0; a = (a + 0x6D2B79F5) | 0;
			let t = Math.imul(a ^ (a >>> 15), 1 | a);
			t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
			return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
		};
	}
}

// interleaved floats per instance: center(3) size(1) rot(3) color(3) alpha(1) = 11.
dwGfxFallingLeaves.STRIDE_F = 11;

// Default world-space visual radius of a leaf quad, chosen to visually match the engine's firefly
// points. The firefly world point-size lives in the remote dwGfxParticle.js (not readable here);
// this is the documented match and the single place to tune it (or pass `radius` in the config).
dwGfxFallingLeaves.DEFAULT_RADIUS = 0.5;

// ------------------------------ shaders ------------------------------
dwGfxFallingLeaves.VS = `#version 300 es
// Instanced leaf quad. Each instance carries a world center, a size, an euler-angle triple
// (tumble/spin/rock), an RGB color, and an alpha. The base quad corner is rotated by the euler
// matrix, scaled, offset by the center, and projected -- so the quad tumbles as a real leaf.
in vec2 a_corner;   // [-0.5,0.5]^2
in vec2 a_uv;       // [0,1]^2
in vec3 i_center;
in float i_size;
in vec3 i_rot;      // euler x,y,z (radians)
in vec3 i_color;
in float i_alpha;

uniform mat4 u_viewProjection;

// ---- bounded analytic fog transmittance to each leaf CENTER ----
// Identical density model + step budget as the light-point path (dwGfx.js particleVS): a small
// fixed march along the camera -> leaf-center segment over the LIVE fog base density + finite
// ellipsoid pockets, Beer-Lambert T = exp(-optical). Per-INSTANCE (i_center is constant across
// the 4 quad corners), NOT per-fragment, and integrated on the leaf's OWN world-space path --
// never the background scene depth. Lets the leaves render AFTER the fullscreen fog composite
// (so the fog can no longer overlay a foreground leaf) while still fading correctly into the haze.
// u_fogEnabled==0 => v_fogT=1.0 (byte-for-byte the pre-fog leaf look).
#define DW_LFOG_MAX_POCKETS 8
#define DW_LFOG_STEPS 10
uniform int   u_fogEnabled;
uniform vec3  u_fogCameraPos;
uniform float u_fogDensity;
uniform float u_fogMaxDistance;
uniform int   u_fogPocketCount;
uniform vec3  u_fogPocketCenters[DW_LFOG_MAX_POCKETS];
uniform vec3  u_fogPocketRadii[DW_LFOG_MAX_POCKETS];
uniform float u_fogPocketFeathers[DW_LFOG_MAX_POCKETS];
uniform float u_fogPocketDensity[DW_LFOG_MAX_POCKETS];

out vec2 v_uv;
out vec3 v_color;
out float v_alpha;
out vec3 v_normal;  // world-space quad normal (pre-flip); FS flips for the back face
out float v_fogT;   // 1.0 = unfogged, 0.0 = fully swallowed by fog

mat3 dwEuler(vec3 e)
{
	float cx = cos(e.x), sx = sin(e.x);
	float cy = cos(e.y), sy = sin(e.y);
	float cz = cos(e.z), sz = sin(e.z);
	mat3 rx = mat3(1.0, 0.0, 0.0,  0.0, cx, sx,  0.0, -sx, cx);
	mat3 ry = mat3(cy, 0.0, -sy,   0.0, 1.0, 0.0, sy, 0.0, cy);
	mat3 rz = mat3(cz, sz, 0.0,   -sz, cz, 0.0,  0.0, 0.0, 1.0);
	return rz * ry * rx;
}

float dwLeafFogTransmittance(vec3 P)
{
	vec3 toP = P - u_fogCameraPos;
	float dist = length(toP);
	if (dist < 1.0e-4) { return 1.0; }
	vec3 dir = toP / dist;
	float marchLen = min(dist, u_fogMaxDistance);
	float segLen = marchLen / float(DW_LFOG_STEPS);
	float optical = 0.0;
	for (int i = 0; i < DW_LFOG_STEPS; i++) {
		float t = (float(i) + 0.5) * segLen;
		vec3 wpos = u_fogCameraPos + dir * t;
		float sigma;
		if (u_fogPocketCount <= 0) {
			sigma = max(u_fogDensity, 0.0);        // constant/weather fallback: homogeneous
		} else {
			sigma = 0.0;
			for (int pj = 0; pj < DW_LFOG_MAX_POCKETS; pj++) {
				if (pj >= u_fogPocketCount) { break; }
				vec3 radii = max(u_fogPocketRadii[pj], vec3(1.0e-4));
				vec3 q = (wpos - u_fogPocketCenters[pj]) / radii;
				float nd = length(q);
				float feather = clamp(u_fogPocketFeathers[pj], 1.0e-3, 1.0);
				float mask = 1.0 - smoothstep(1.0 - feather, 1.0, nd);
				float dScale = max(u_fogPocketDensity[pj], 0.0);
				sigma += max(u_fogDensity * dScale * mask, 0.0);
			}
		}
		optical += sigma * segLen;
	}
	return exp(-optical);
}

void main()
{
	mat3 R = dwEuler(i_rot);
	vec3 local = vec3(a_corner * i_size, 0.0);
	vec3 world = i_center + R * local;
	v_uv = a_uv;
	v_color = i_color;
	v_alpha = i_alpha;
	v_normal = normalize(R * vec3(0.0, 0.0, 1.0));
	v_fogT = (u_fogEnabled == 1) ? dwLeafFogTransmittance(i_center) : 1.0;
	gl_Position = u_viewProjection * vec4(world, 1.0);
}
`;

dwGfxFallingLeaves.FS = `#version 300 es
precision highp float;
// GLSL ES 3.00 predeclares a default precision for sampler2D, so no explicit precision line is
// required for u_leafTex (unlike sampler3D / sampler2DShadow). The leaf silhouette is procedural
// by default; a texture is used ONLY when u_useTexture==1 and a valid texture is bound.
in vec2 v_uv;
in vec3 v_color;
in float v_alpha;
in vec3 v_normal;
in float v_fogT;           // bounded analytic fog transmittance to this leaf's center

uniform vec3 u_lightDir;   // normalized, world space (toward the light)
uniform float u_ambient;
uniform float u_opacity;
uniform int u_useTexture;
uniform sampler2D u_leafTex;

out vec4 fragColor;

// Procedural leaf silhouette: a rounded, pointed blade (points at top & bottom) with a central
// midrib. Antialiased with fwidth so it stays crisp at any size. Returns coverage in [0,1] plus
// a midrib shade factor in .y.
vec2 dwLeafMask(vec2 uv)
{
	vec2 p = uv * 2.0 - 1.0;                 // [-1,1]^2, y is along the blade
	float ay = abs(p.y);
	// blade half-width envelope: widest near the middle, tapering to sharp points at |y|=1.
	float halfW = pow(max(0.0, 1.0 - ay), 0.6) * 0.82;
	float edge = halfW - abs(p.x);
	float aa = fwidth(edge) + 1e-4;
	float mask = smoothstep(-aa, aa, edge);
	// clip the vertical extent so the points are clean.
	float aay = fwidth(ay) + 1e-4;
	mask *= smoothstep(-aay, aay, 1.0 - ay);
	// central midrib: subtle darkening along x=0.
	float rib = smoothstep(0.05, 0.0, abs(p.x)) * 0.35;
	return vec2(mask, rib);
}

void main()
{
	// two-sided shading: flip the normal for the back face so both sides catch light.
	vec3 N = normalize(v_normal);
	if (!gl_FrontFacing) { N = -N; }
	float diff = max(dot(N, u_lightDir), 0.0);
	float shade = u_ambient + (1.0 - u_ambient) * diff;

	vec3 base;
	float coverage;
	float rib = 0.0;
	if (u_useTexture == 1) {
		// LOGO PATH: the texture alpha is the silhouette (the logo shape), NOT the procedural blade,
		// so the leaf reads as the My Kinda Fit logo. The albedo is greyscale, so multiplying by the
		// per-leaf palette color tints it (orange/red/yellow/brown) while preserving logo detail and
		// its alpha. No midrib is applied -- the logo carries its own shape.
		vec4 tex = texture(u_leafTex, v_uv);
		base = v_color * tex.rgb;
		coverage = tex.a;
	} else {
		// FALLBACK PATH: procedural leaf silhouette (used until the logo texture is live/valid).
		vec2 lm = dwLeafMask(v_uv);
		base = v_color;
		coverage = lm.x;
		rib = lm.y;
	}
	if (coverage <= 0.003) { discard; }

	// apply midrib darkening (fallback only) + directional shade; keep LDR so bloom does not
	// over-catch leaves.
	vec3 rgb = base * shade * (1.0 - rib);

	float alpha = coverage * v_alpha * u_opacity;
	// Fog fade on the leaf's OWN camera->center path (v_fogT==1.0 when fog is disabled): scale
	// both the lit color and the over-composite alpha by transmittance, so a leaf deep in the
	// haze recedes into the already-fogged background instead of sitting crisply on top of it.
	rgb   *= v_fogT;
	alpha *= v_fogT;
	if (alpha <= 0.003) { discard; }
	fragColor = vec4(rgb, alpha);
}
`;

// ------------------------------------------------------------------------------------------
// REUSE / INTEGRATION NOTES (website-reaction control + deferred touch bridge)
// ------------------------------------------------------------------------------------------
// Construct:   const leaves = new dwGfxFallingLeaves(gfx, { palette:[...], maxLeaves:220, ... });
// Per frame:   leaves.update(dt);              // in the demo update(dt)
//              leaves.draw(CameraView);        // in the transparent-particle slot of render()
//
// Website reactions (call any time, no rebuild):
//   leaves.setPalette([[r,g,b], ...]);         // swap the active palette (affects NEW spawns)
//   leaves.setEmissionRate(30);                // steady rate change
//   leaves.setIntensity(2.0);                  // global multiplier
//   leaves.boost(4.0, 2.5);                    // temporary "gust": 4x for 2.5s, auto-decays
//   leaves.setWind(1.5, 0.0); leaves.setTurbulence(1.4);
//
// Mini-game catch scoring (deferred multi-touch bridge -- dwRay/dwCollision live only in the
// remote engine, so integration is left to the caller instead of duplicating collision code):
//   leaves.onCaught    = (leaf) => { score += 1; };   // leaf = {id,x,y,z,size}
//   leaves.onGroundHit = (leaf) => { score -= 1; };
//   // per active pointer, from a touch handler, once you have a WORLD point or a picking ray:
//   leaves.tryCatchAt(worldPoint, 0.6);               // sphere catch
//   leaves.tryCatchRay(rayOrigin, rayDir, 0.4);       // ray/screen-pick catch
//   // or drive an external collision system with the world bounds:
//   const list = leaves.getActiveLeaves();            // [{id,x,y,z,size}, ...] (this frame)

if (typeof module !== "undefined" && module.exports) { module.exports = dwGfxFallingLeaves; }
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxGoldenWisps.js
//
// Sparse "golden ember wisp" light-point effect. Every so often a few golden ember
// heads appear at random points in a controlled scene volume, fade in fast, hold hot
// like ash for ~1s, drift as if caught by a light wind, curl/spiral around a random
// local axis (forming part or all of a loop), leave a short curved contrail of fading
// gold light points, then cool and die.
//
// Built entirely on the existing pooled light-point infrastructure in dwGfxParticle.js
// (dwGfxParticlePool + the 8-float [px,py,pz,size, r,g,b,a] batch that dwGfx.drawParticles
// uploads and draws additively into the HDR scene buffer). No new shader: the head + trail
// are ordinary HDR light points, so bloom and the built-in per-particle fog transmittance
// (v_fogT, passed via drawParticles' fogParams) apply for free. Particles never write depth.
//
// Only scalar/vector arithmetic is used (cross/normalize on plain arrays), consistent with
// the other particle effects; no matrix work is required (so no m4 dependency).
//
// Public API (mirrors the other effects):
//   new dwGfxGoldenWisps(gfx, options)
//   .update(dt)                 - simulation only, no GPU work
//   .buildBatch()  -> {data,count} for gfx.drawParticles
//   .burst(n)                   - force-spawn n wisps now (optional)
//   .enabled                    - when false, update() lets live wisps finish then idles
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

// Local stride constant (matches dwGfxParticle.js / dwGfx). Declared here so this module
// is self-contained if loaded before/after the others; value is identical everywhere.
const DW_WISP_STRIDE = 8;

class dwGfxGoldenWisps
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- population / caps ----
		this.maxActive		= o.maxActive		!== undefined ? o.maxActive		: 48;   // hard cap on live wisps
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 12;   // bounded contrail samples

		// ---- spawn volume (box half-extents around center) ----
		this.center			= o.center			|| [0.0, 1.0, 0.0];
		this.bounds			= o.bounds			|| [6.0, 3.0, 6.0];

		// ---- sparse randomized burst cadence ----
		this.burstIntervalMin	= o.burstIntervalMin	!== undefined ? o.burstIntervalMin	: 0.7;   // seconds between bursts
		this.burstIntervalMax	= o.burstIntervalMax	!== undefined ? o.burstIntervalMax	: 2.2;
		this.burstMin			= o.burstMin			!== undefined ? o.burstMin			: 1;     // wisps per burst
		this.burstMax			= o.burstMax			!== undefined ? o.burstMax			: 3;

		// ---- lifetime (seconds): fast fade-in, hot hold ~1s, smooth cooling ----
		this.lifeMin		= o.lifeMin			!== undefined ? o.lifeMin		: 1.0;
		this.lifeMax		= o.lifeMax			!== undefined ? o.lifeMax		: 1.6;
		this.fadeInTime		= o.fadeInTime		!== undefined ? o.fadeInTime	: 0.14;  // quick pop to hot
		this.coolTime		= o.coolTime		!== undefined ? o.coolTime		: 0.55;  // trailing cool/fade

		// ---- head appearance ----
		this.headSize		= o.headSize		!== undefined ? o.headSize		: 0.085; // world units
		this.headSizeJitter	= o.headSizeJitter	!== undefined ? o.headSizeJitter: 0.35;
		this.intensity		= o.intensity		!== undefined ? o.intensity		: 3.2;   // HDR peak (blooms)

		// ---- trail ----
		this.trailStride	= o.trailStride		!== undefined ? o.trailStride	: 1;     // record every Nth frame

		// ---- motion ----
		this.wind			= o.wind			|| [0.35, 0.05, -0.2];  // light steady wind (world/s)
		this.buoyancy		= o.buoyancy		!== undefined ? o.buoyancy		: 0.45;  // gentle upward drift (world/s^2)
		this.drag			= o.drag			!== undefined ? o.drag			: 1.3;   // per-second velocity damping
		this.driftSpeed		= o.driftSpeed		!== undefined ? o.driftSpeed	: 0.6;   // initial random drift speed
		this.loopRadiusMin	= o.loopRadiusMin	!== undefined ? o.loopRadiusMin	: 0.25;  // curl radius (world units)
		this.loopRadiusMax	= o.loopRadiusMax	!== undefined ? o.loopRadiusMax	: 0.9;
		this.loopFreqMin	= o.loopFreqMin		!== undefined ? o.loopFreqMin	: 2.0;   // curl angular speed (rad/s)
		this.loopFreqMax	= o.loopFreqMax		!== undefined ? o.loopFreqMax	: 5.5;

		// ---- gold-only palette (HDR, base rgb; NO rainbow) ----
		// weighted pick: mostly rich gold, some amber, a little white-gold core, a little
		// restrained orange. Cooling shifts the emitted color toward amber/orange as it dies.
		this.palette		= o.palette || [
			{ c: [1.00, 0.95, 0.75], w: 0.15 },   // white-gold core (rare)
			{ c: [1.00, 0.80, 0.32], w: 0.45 },   // rich gold (common)
			{ c: [1.00, 0.62, 0.20], w: 0.28 },   // amber
			{ c: [1.00, 0.48, 0.12], w: 0.12 },   // restrained orange
		];
		this.coolColor		= o.coolColor		|| [1.0, 0.42, 0.12];  // color a wisp cools toward as it dies
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.05;
		// ----------------------------------------------------------------------

		// precompute cumulative palette weights (once).
		this._palCum = [];
		let acc = 0.0;
		for (let p = 0; p < this.palette.length; p++) {
			acc += (this.palette[p].w > 0 ? this.palette[p].w : 0.0);
			this._palCum.push(acc);
		}
		this._palTotal = acc > 0 ? acc : 1.0;

		this.enabled = (o.enabled !== undefined) ? o.enabled : true;

		// pooled storage (reused; zero per-frame GC).
		this.pool = new dwGfxParticlePool(this.maxActive, this.trailLength);

		// per-wisp extra state parallel to pool slots.
		const n = this.maxActive;
		this.cx = new Float32Array(n);   // drifting curl-center (loop is offset from this)
		this.cy = new Float32Array(n);
		this.cz = new Float32Array(n);
		this.axX = new Float32Array(n);  // loop plane basis u
		this.axY = new Float32Array(n);
		this.axZ = new Float32Array(n);
		this.ayX = new Float32Array(n);  // loop plane basis v
		this.ayY = new Float32Array(n);
		this.ayZ = new Float32Array(n);
		this.loopR = new Float32Array(n);
		this.loopF = new Float32Array(n);
		this.loopPhase = new Float32Array(n);
		this.trailAcc = new Float32Array(n);   // frames since last trail sample (as time)
		this.baseR = new Float32Array(n);      // chosen palette color (hot)
		this.baseG = new Float32Array(n);
		this.baseB = new Float32Array(n);

		// GPU batch: head + trail points per wisp, allocated once.
		const maxPoints = this.maxActive * (1 + this.trailLength);
		this.batch = new Float32Array(maxPoints * DW_WISP_STRIDE);
		this.batchCount = 0;

		// burst cadence timer.
		this.burstTimer = this._rand(this.burstIntervalMin, this.burstIntervalMax);

		// scratch vectors (avoid per-frame allocation in hot loops).
		this._d0 = [0.0, 0.0, 0.0];
		this._d1 = [0.0, 0.0, 0.0];
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	// random unit vector (uniform on sphere).
	_randDir(out)
	{
		const z = this._rand(-1.0, 1.0);
		const a = this._rand(0.0, Math.PI * 2.0);
		const r = Math.sqrt(Math.max(0.0, 1.0 - z * z));
		out[0] = r * Math.cos(a);
		out[1] = r * Math.sin(a);
		out[2] = z;
		return out;
	}

	// weighted gold-only palette pick into (baseR/G/B) with slight jitter.
	_pickColor(i)
	{
		const r = Math.random() * this._palTotal;
		let sel = this.palette[this.palette.length - 1].c;
		for (let p = 0; p < this._palCum.length; p++) {
			if (r <= this._palCum[p]) { sel = this.palette[p].c; break; }
		}
		const j = this.colorJitter;
		// jitter is symmetric but clamped >= 0; it never introduces blue/green dominance
		// because the palette itself is gold-only (r >= g >= b for every entry).
		this.baseR[i] = Math.max(0.0, sel[0] + this._rand(-j, j));
		this.baseG[i] = Math.max(0.0, sel[1] + this._rand(-j, j * 0.5));
		this.baseB[i] = Math.max(0.0, sel[2] + this._rand(-j * 0.5, j * 0.5));
	}

	// seed one freshly spawned wisp slot.
	_initWisp(i)
	{
		const pool = this.pool;

		// spawn point inside the box volume.
		this.cx[i] = this.center[0] + this._rand(-this.bounds[0], this.bounds[0]);
		this.cy[i] = this.center[1] + this._rand(-this.bounds[1], this.bounds[1]);
		this.cz[i] = this.center[2] + this._rand(-this.bounds[2], this.bounds[2]);

		// randomized orthonormal loop-plane basis about a random axis.
		const axis = this._randDir(this._d0);
		// pick an arbitrary vector not parallel to axis, then Gram-Schmidt for u, v = axis x u.
		let hx = 0.0, hy = 1.0, hz = 0.0;
		if (Math.abs(axis[1]) > 0.9) { hx = 1.0; hy = 0.0; hz = 0.0; }
		// u = normalize(h - (h.axis)axis)
		const d = hx * axis[0] + hy * axis[1] + hz * axis[2];
		let ux = hx - d * axis[0], uy = hy - d * axis[1], uz = hz - d * axis[2];
		const ul = Math.hypot(ux, uy, uz) || 1.0;
		ux /= ul; uy /= ul; uz /= ul;
		// v = axis x u (already unit; axis and u are orthonormal).
		const vx = axis[1] * uz - axis[2] * uy;
		const vy = axis[2] * ux - axis[0] * uz;
		const vz = axis[0] * uy - axis[1] * ux;
		this.axX[i] = ux; this.axY[i] = uy; this.axZ[i] = uz;
		this.ayX[i] = vx; this.ayY[i] = vy; this.ayZ[i] = vz;

		this.loopR[i]		= this._rand(this.loopRadiusMin, this.loopRadiusMax);
		this.loopF[i]		= this._rand(this.loopFreqMin, this.loopFreqMax) * (Math.random() < 0.5 ? -1.0 : 1.0);
		this.loopPhase[i]	= this._rand(0.0, Math.PI * 2.0);
		this.trailAcc[i]	= 0.0;

		// initial random drift velocity (light-wind catch).
		const dir = this._randDir(this._d1);
		pool.vx[i] = dir[0] * this.driftSpeed * this._rand(0.4, 1.0);
		pool.vy[i] = Math.abs(dir[1]) * this.driftSpeed * this._rand(0.3, 0.9);   // bias gently up
		pool.vz[i] = dir[2] * this.driftSpeed * this._rand(0.4, 1.0);

		this._pickColor(i);

		pool.size[i]		= this.headSize * this._rand(1.0 - this.headSizeJitter, 1.0 + this.headSizeJitter);
		pool.intensity[i]	= this.intensity;
		pool.alpha[i]		= 0.0;
		pool.age[i]			= 0.0;
		pool.life[i]		= this._rand(this.lifeMin, this.lifeMax);
		pool.r[i] = this.baseR[i];
		pool.g[i] = this.baseG[i];
		pool.b[i] = this.baseB[i];

		// initial rendered position = center + loop offset (so trail starts coherent).
		const c = Math.cos(this.loopPhase[i]) * this.loopR[i];
		const s = Math.sin(this.loopPhase[i]) * this.loopR[i];
		pool.px[i] = this.cx[i] + this.axX[i] * c + this.ayX[i] * s;
		pool.py[i] = this.cy[i] + this.axY[i] * c + this.ayY[i] * s;
		pool.pz[i] = this.cz[i] + this.axZ[i] * c + this.ayZ[i] * s;
		pool.clearTrail(i);
	}

	// force-spawn n wisps now (respects the hard cap via the pool free list).
	burst(n)
	{
		for (let k = 0; k < n; k++) {
			const i = this.pool.spawn();
			if (i < 0) { break; }   // hard cap reached: self-limits, no overflow.
			this._initWisp(i);
		}
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}
		const pool = this.pool;

		// ---- sparse randomized burst cadence ----
		if (this.enabled) {
			this.burstTimer -= dt;
			if (this.burstTimer <= 0.0) {
				const n = Math.round(this._rand(this.burstMin, this.burstMax));
				this.burst(n);
				this.burstTimer = this._rand(this.burstIntervalMin, this.burstIntervalMax);
			}
		}

		// ---- advance live wisps ----
		const damp = Math.max(0.0, 1.0 - this.drag * dt);
		const wx = this.wind[0], wy = this.wind[1], wz = this.wind[2];

		for (let i = 0; i < this.maxActive; i++)
		{
			if (!pool.alive[i]) {
				continue;
			}

			pool.age[i] += dt;
			const age = pool.age[i];
			const life = pool.life[i];
			if (age >= life) {
				pool.kill(i);
				continue;
			}

			// fade curve: fast fade-in -> hot hold ~1 -> smooth cool/fade out.
			let a;
			if (age < this.fadeInTime) {
				a = age / this.fadeInTime;                 // quick pop to hot
			} else if (age > life - this.coolTime) {
				a = Math.max(0.0, (life - age) / this.coolTime);   // cooling tail
			} else {
				a = 1.0;                                   // hot ash hold
			}
			pool.alpha[i] = a;

			// cooling fraction 0(hot)..1(dead) over the cool tail: shift color toward
			// coolColor and dim intensity so the ember reads as cooling ash, not a fade only.
			let cool = 0.0;
			if (age > life - this.coolTime) {
				cool = Math.min(1.0, (age - (life - this.coolTime)) / this.coolTime);
			}
			const cr = this.baseR[i] + (this.coolColor[0] - this.baseR[i]) * cool;
			const cg = this.baseG[i] + (this.coolColor[1] - this.baseG[i]) * cool;
			const cb = this.baseB[i] + (this.coolColor[2] - this.baseB[i]) * cool;
			pool.r[i] = cr; pool.g[i] = cg; pool.b[i] = cb;
			pool.intensity[i] = this.intensity * (1.0 - 0.55 * cool);

			// ---- integrate the drifting curl-center: wind + buoyancy + drag ----
			pool.vy[i] += this.buoyancy * dt;
			this.cx[i] += (pool.vx[i] + wx) * dt;
			this.cy[i] += (pool.vy[i] + wy) * dt;
			this.cz[i] += (pool.vz[i] + wz) * dt;
			pool.vx[i] *= damp;
			pool.vy[i] *= damp;
			pool.vz[i] *= damp;

			// ---- curl/loop: rotate around the wisp's local plane basis ----
			this.loopPhase[i] += this.loopF[i] * dt;
			// loop radius eases in then out over life so the wisp "forms part or all of a loop".
			const lifeT = age / life;
			const radEnv = Math.sin(Math.PI * Math.min(1.0, Math.max(0.0, lifeT)));  // 0..1..0
			const rr = this.loopR[i] * (0.35 + 0.65 * radEnv);
			const c = Math.cos(this.loopPhase[i]) * rr;
			const s = Math.sin(this.loopPhase[i]) * rr;

			pool.px[i] = this.cx[i] + this.axX[i] * c + this.ayX[i] * s;
			pool.py[i] = this.cy[i] + this.axY[i] * c + this.ayY[i] * s;
			pool.pz[i] = this.cz[i] + this.axZ[i] * c + this.ayZ[i] * s;

			// ---- record a bounded, curved contrail (every trailStride*dt) ----
			this.trailAcc[i] += dt;
			const sampleEvery = this.trailStride * (1.0 / 60.0);
			if (this.trailAcc[i] >= sampleEvery) {
				this.trailAcc[i] = 0.0;
				pool.pushTrail(i, pool.px[i], pool.py[i], pool.pz[i], pool.intensity[i]);
			}
		}
	}

	// build the GPU batch from current state (read-only). Same 8-float layout as the
	// other effects: head point then trail points (shorter-lived / decaying behind it).
	buildBatch()
	{
		const pool = this.pool;
		const batch = this.batch;
		const tl = this.trailLength;
		let o = 0;

		for (let i = 0; i < this.maxActive; i++)
		{
			if (!pool.alive[i] || pool.alpha[i] <= 0.001) {
				continue;
			}

			const inten = pool.intensity[i];
			const a = pool.alpha[i];

			// hot ember head.
			batch[o + 0] = pool.px[i];
			batch[o + 1] = pool.py[i];
			batch[o + 2] = pool.pz[i];
			batch[o + 3] = pool.size[i];
			batch[o + 4] = pool.r[i] * inten;
			batch[o + 5] = pool.g[i] * inten;
			batch[o + 6] = pool.b[i] * inten;
			batch[o + 7] = a;
			o += DW_WISP_STRIDE;

			// curved contrail: smaller, dimmer, shorter-lived, most-recent brightest.
			const tc = pool.trailCount[i];
			for (let sIdx = 0; sIdx < tc; sIdx++)
			{
				const idx = ((pool.trailHead[i] - 1 - sIdx) % tl + tl) % tl;
				const base = i * tl + idx;
				const falloff = 1.0 - (sIdx / tl);            // 1 at head .. ~0 at tail
				const ti = pool.trailI[base] * falloff * 0.5; // trail dimmer than head

				batch[o + 0] = pool.trailX[base];
				batch[o + 1] = pool.trailY[base];
				batch[o + 2] = pool.trailZ[base];
				batch[o + 3] = pool.size[i] * (0.25 + 0.5 * falloff);
				batch[o + 4] = pool.r[i] * ti;
				batch[o + 5] = pool.g[i] * ti;
				batch[o + 6] = pool.b[i] * ti;
				batch[o + 7] = a * falloff;
				o += DW_WISP_STRIDE;
			}
		}

		this.batchCount = o / DW_WISP_STRIDE;
		return { data: batch, count: this.batchCount };
	}

	// count of currently live wisps (for HUD / tests).
	activeCount()
	{
		let n = 0;
		for (let i = 0; i < this.maxActive; i++) {
			if (this.pool.alive[i]) { n++; }
		}
		return n;
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxLuminousFrogs.js
//
// "Creatures of the Night" prototype: a small group of stylized luminous point-rig frogs that
// rest, breathe, occasionally crouch and launch on a ballistic arc, land with a squash, pause,
// pick a new heading, and mostly sit scattered through the fog. Purely a visual proof.
//
// Built on the same pooled light-point path as the golden wisps / fireflies (dwGfxParticlePool +
// the 8-float [px,py,pz,size, r,g,b,a] batch that dwGfx.drawParticles uploads additively into the
// HDR scene buffer). No new shader: every rig point is an ordinary HDR light point, so bloom and
// the built-in per-particle fog transmittance (v_fogT, via drawParticles' fogParams) apply for
// free. Particles never write depth (owned by drawParticles' depthMask(false)).
//
// Each frog is ONE pool slot (its ground anchor + airborne velocity + a short airborne motion
// trail) plus a parallel state-machine record. buildBatch() draws a compact readable rig around
// the anchor: body, head, two brighter eyes, two hind legs, two forelegs (8 points), plus the
// short trail during flight. Only scalar/vector arithmetic is used (no matrix work, no m4 needed).
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_FROG_STRIDE = 8;   // floats per emitted point (matches dwGfx / dwGfxParticle)
const DW_FROG_RIG    = 8;   // rig points per frog: body, head, eyeL, eyeR, hindL, hindR, foreL, foreR

// state machine phases.
const DW_FROG_REST    = 0;   // idle breathing, legs tucked
const DW_FROG_CROUCH  = 1;   // compress down before launch
const DW_FROG_LAUNCH  = 2;   // brief push-off (legs extend, body stretches)
const DW_FROG_AIR     = 3;   // ballistic arc
const DW_FROG_LAND    = 4;   // landing compression
const DW_FROG_PAUSE   = 5;   // settle, then choose a new heading

class dwGfxLuminousFrogs
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- population / caps ----
		this.count			= o.count			!== undefined ? o.count			: 6;    // active frogs (spawned up front)
		this.maxActive		= o.maxActive		!== undefined ? o.maxActive		: 8;    // hard cap on slots
		if (this.count > this.maxActive) { this.count = this.maxActive; }
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 4;    // short airborne motion trail

		// ---- roam / spawn area (box half-extents around center on the ground plane) ----
		this.center			= o.center			|| [0.0, 0.0, 0.0];
		this.bounds			= o.bounds			|| [7.0, 0.0, 7.0];
		// ground/baseline the frogs rest on (absolute world Y). Defaults to the scene ground -2.0.
		// `baseY` is accepted as an alias; rest/crouch/land + the ballistic arc are all relative to this.
		this.groundY		= o.groundY			!== undefined ? o.groundY
							: (o.baseY			!== undefined ? o.baseY			: -2.0);

		// ---- scale / appearance ----
		this.frogSize		= o.frogSize		!== undefined ? o.frogSize		: 0.14;  // base point scale (world units)
		this.frogSizeJitter	= o.frogSizeJitter	!== undefined ? o.frogSizeJitter: 0.25;
		this.bodyIntensity	= o.bodyIntensity	!== undefined ? o.bodyIntensity	: 2.3;   // HDR
		this.eyeIntensity	= o.eyeIntensity	!== undefined ? o.eyeIntensity	: 3.6;   // eyes slightly brighter

		// ---- jump behavior (mostly resting; occasional scattered hops) ----
		this.restMin		= o.restMin			!== undefined ? o.restMin		: 1.8;   // seconds resting between decisions
		this.restMax		= o.restMax			!== undefined ? o.restMax		: 5.0;
		this.jumpChance		= o.jumpChance		!== undefined ? o.jumpChance	: 0.45;  // P(jump) when a rest ends (else re-rest)
		this.crouchTime		= o.crouchTime		!== undefined ? o.crouchTime	: 0.18;
		this.launchTime		= o.launchTime		!== undefined ? o.launchTime	: 0.06;
		this.landTime		= o.landTime		!== undefined ? o.landTime		: 0.16;
		this.pauseMin		= o.pauseMin		!== undefined ? o.pauseMin		: 0.25;
		this.pauseMax		= o.pauseMax		!== undefined ? o.pauseMax		: 0.8;

		this.jumpDistMin	= o.jumpDistMin		!== undefined ? o.jumpDistMin	: 0.8;
		this.jumpDistMax	= o.jumpDistMax		!== undefined ? o.jumpDistMax	: 2.6;
		this.jumpHeightMin	= o.jumpHeightMin	!== undefined ? o.jumpHeightMin	: 0.5;
		this.jumpHeightMax	= o.jumpHeightMax	!== undefined ? o.jumpHeightMax	: 1.3;
		this.flightMin		= o.flightMin		!== undefined ? o.flightMin		: 0.5;   // arc flight time (s)
		this.flightMax		= o.flightMax		!== undefined ? o.flightMax		: 0.85;

		this.breathSpeed	= o.breathSpeed		!== undefined ? o.breathSpeed	: 2.2;   // idle breathing rate
		this.fadeInTime		= o.fadeInTime		!== undefined ? o.fadeInTime	: 0.6;   // spawn/toggle-on fade

		// ---- palette: luminous green/teal with occasional warm gold accent ----
		this.greenColor		= o.greenColor		|| [0.35, 1.00, 0.50];
		this.tealColor		= o.tealColor		|| [0.30, 1.00, 0.85];
		this.goldColor		= o.goldColor		|| [1.00, 0.80, 0.32];
		this.eyeColor		= o.eyeColor		|| [0.80, 1.00, 0.72];  // bright green-white eyes
		this.goldEyeColor	= o.goldEyeColor	|| [1.00, 0.92, 0.60];  // eyes for gold-accent frogs
		this.goldChance		= o.goldChance		!== undefined ? o.goldChance	: 0.22;  // fraction of frogs with gold accent
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.05;
		// ----------------------------------------------------------------------

		this.enabled = (o.enabled !== undefined) ? o.enabled : true;

		// pooled storage (anchor + airborne velocity + short trail); reused, no per-frame GC.
		this.pool = new dwGfxParticlePool(this.maxActive, this.trailLength);

		// per-frog state parallel to pool slots.
		const n = this.maxActive;
		this.st			= new Int32Array(n);
		this.stTimer	= new Float32Array(n);
		this.yaw		= new Float32Array(n);       // heading
		this.breath		= new Float32Array(n);       // breathing phase
		this.legX		= new Float32Array(n);       // 0 tucked .. 1 extended
		this.squash		= new Float32Array(n);       // vertical squash/stretch (1 neutral)
		this.gold		= new Uint8Array(n);         // gold-accent flag
		this.eR			= new Float32Array(n);       // per-frog eye color
		this.eG			= new Float32Array(n);
		this.eB			= new Float32Array(n);
		this.flightT	= new Float32Array(n);       // arc flight duration
		this.flightE	= new Float32Array(n);       // arc elapsed
		this.vy0		= new Float32Array(n);       // arc initial vertical speed
		this.arcG		= new Float32Array(n);       // arc gravity

		// GPU batch: rig + trail per frog, allocated once.
		const maxPoints = this.maxActive * (DW_FROG_RIG + this.trailLength);
		this.batch = new Float32Array(maxPoints * DW_FROG_STRIDE);
		this.batchCount = 0;

		// spawn the resident population up front.
		for (let k = 0; k < this.count; k++) {
			const i = this.pool.spawn();
			if (i < 0) { break; }
			this._initFrog(i);
		}
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	_setColor(i, base)
	{
		const j = this.colorJitter;
		this.pool.r[i] = Math.max(0.0, base[0] + this._rand(-j, j));
		this.pool.g[i] = Math.max(0.0, base[1] + this._rand(-j, j));
		this.pool.b[i] = Math.max(0.0, base[2] + this._rand(-j, j));
	}

	_initFrog(i)
	{
		const pool = this.pool;

		pool.px[i] = this.center[0] + this._rand(-this.bounds[0], this.bounds[0]);
		pool.py[i] = this.groundY;
		pool.pz[i] = this.center[2] + this._rand(-this.bounds[2], this.bounds[2]);
		pool.vx[i] = pool.vy[i] = pool.vz[i] = 0.0;

		this.gold[i] = (Math.random() < this.goldChance) ? 1 : 0;
		if (this.gold[i]) {
			this._setColor(i, this.goldColor);
			this.eR[i] = this.goldEyeColor[0]; this.eG[i] = this.goldEyeColor[1]; this.eB[i] = this.goldEyeColor[2];
		} else {
			this._setColor(i, (Math.random() < 0.5) ? this.greenColor : this.tealColor);
			this.eR[i] = this.eyeColor[0]; this.eG[i] = this.eyeColor[1]; this.eB[i] = this.eyeColor[2];
		}

		pool.size[i]		= this.frogSize * this._rand(1.0 - this.frogSizeJitter, 1.0 + this.frogSizeJitter);
		pool.intensity[i]	= this.bodyIntensity;
		pool.alpha[i]		= 0.0;   // fades in
		pool.age[i]			= 0.0;
		pool.life[i]		= 1e9;   // resident (never auto-dies)
		pool.clearTrail(i);

		this.yaw[i]		= this._rand(0.0, Math.PI * 2.0);
		this.breath[i]	= this._rand(0.0, Math.PI * 2.0);
		this.legX[i]	= 0.0;
		this.squash[i]	= 1.0;
		this.st[i]		= DW_FROG_REST;
		this.stTimer[i]	= this._rand(this.restMin, this.restMax);
		this.flightE[i]	= 0.0;
	}

	_beginJump(i)
	{
		const pool = this.pool;
		// choose a heading (bias back toward center when near the edge so frogs stay scattered).
		const dxC = this.center[0] - pool.px[i];
		const dzC = this.center[2] - pool.pz[i];
		const edge = (Math.abs(pool.px[i] - this.center[0]) > this.bounds[0] * 0.85) ||
					 (Math.abs(pool.pz[i] - this.center[2]) > this.bounds[2] * 0.85);
		if (edge && (dxC * dxC + dzC * dzC) > 1e-4) {
			this.yaw[i] = Math.atan2(dxC, dzC) + this._rand(-0.6, 0.6);
		} else {
			this.yaw[i] += this._rand(-Math.PI, Math.PI);
		}

		const dist = this._rand(this.jumpDistMin, this.jumpDistMax);
		const hgt  = this._rand(this.jumpHeightMin, this.jumpHeightMax);
		const T    = this._rand(this.flightMin, this.flightMax);
		this.flightT[i] = T;
		this.flightE[i] = 0.0;

		// projectile that peaks at ~hgt and lands after T: g from apex, vy0 from g and T.
		const g = 8.0 * hgt / (T * T);   // so that apex height ~= hgt at t=T/2
		this.arcG[i] = g;
		this.vy0[i]  = 0.5 * g * T;

		// horizontal velocity carries `dist` over T along the heading.
		const fx = Math.sin(this.yaw[i]);
		const fz = Math.cos(this.yaw[i]);
		const hs = dist / T;
		pool.vx[i] = fx * hs;
		pool.vz[i] = fz * hs;
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}
		const pool = this.pool;

		for (let i = 0; i < this.maxActive; i++)
		{
			if (!pool.alive[i]) {
				continue;
			}

			// spawn/toggle fade-in.
			if (pool.alpha[i] < 1.0) {
				pool.alpha[i] = Math.min(1.0, pool.alpha[i] + dt / this.fadeInTime);
			}
			this.breath[i] += dt * this.breathSpeed;

			switch (this.st[i])
			{
				case DW_FROG_REST:
				{
					// legs tuck, body breathes gently.
					this.legX[i]  += (0.0 - this.legX[i]) * Math.min(1.0, dt * 6.0);
					const b = 0.06 * Math.sin(this.breath[i]);
					this.squash[i] = 1.0 + b;
					this.stTimer[i] -= dt;
					if (this.stTimer[i] <= 0.0) {
						if (Math.random() < this.jumpChance) {
							this.st[i] = DW_FROG_CROUCH;
							this.stTimer[i] = this.crouchTime;
						} else {
							// small idle turn, keep resting (scattered, mostly still).
							this.yaw[i] += this._rand(-0.8, 0.8);
							this.stTimer[i] = this._rand(this.restMin, this.restMax);
						}
					}
					break;
				}

				case DW_FROG_CROUCH:
				{
					this.legX[i]  += (0.3 - this.legX[i]) * Math.min(1.0, dt * 10.0);
					this.squash[i] += (0.62 - this.squash[i]) * Math.min(1.0, dt * 12.0);   // compress
					this.stTimer[i] -= dt;
					if (this.stTimer[i] <= 0.0) {
						this.st[i] = DW_FROG_LAUNCH;
						this.stTimer[i] = this.launchTime;
						this._beginJump(i);
					}
					break;
				}

				case DW_FROG_LAUNCH:
				{
					this.legX[i]  += (1.0 - this.legX[i]) * Math.min(1.0, dt * 20.0);
					this.squash[i] += (1.35 - this.squash[i]) * Math.min(1.0, dt * 20.0);   // stretch up
					this.stTimer[i] -= dt;
					if (this.stTimer[i] <= 0.0) {
						this.st[i] = DW_FROG_AIR;
					}
					break;
				}

				case DW_FROG_AIR:
				{
					this.flightE[i] += dt;
					const e = this.flightE[i];
					// ballistic arc about the ground anchor height.
					pool.px[i] += pool.vx[i] * dt;
					pool.pz[i] += pool.vz[i] * dt;
					pool.py[i] = this.groundY + this.vy0[i] * e - 0.5 * this.arcG[i] * e * e;
					this.legX[i] = 1.0;                         // extended in flight
					this.squash[i] = 1.15;                      // slight stretch
					// short airborne motion trail.
					pool.pushTrail(i, pool.px[i], pool.py[i], pool.pz[i], pool.intensity[i]);
					if (e >= this.flightT[i] || pool.py[i] <= this.groundY) {
						pool.py[i] = this.groundY;
						pool.vx[i] = pool.vz[i] = 0.0;
						// keep the frog inside the roam box.
						pool.px[i] = Math.min(this.center[0] + this.bounds[0], Math.max(this.center[0] - this.bounds[0], pool.px[i]));
						pool.pz[i] = Math.min(this.center[2] + this.bounds[2], Math.max(this.center[2] - this.bounds[2], pool.pz[i]));
						this.st[i] = DW_FROG_LAND;
						this.stTimer[i] = this.landTime;
					}
					break;
				}

				case DW_FROG_LAND:
				{
					this.legX[i]  += (0.15 - this.legX[i]) * Math.min(1.0, dt * 14.0);
					this.squash[i] += (0.7 - this.squash[i]) * Math.min(1.0, dt * 16.0);   // compress on impact
					this.stTimer[i] -= dt;
					// let the airborne trail shrink away after landing.
					if (pool.trailCount[i] > 0) { pool.trailCount[i]--; }
					if (this.stTimer[i] <= 0.0) {
						this.st[i] = DW_FROG_PAUSE;
						this.stTimer[i] = this._rand(this.pauseMin, this.pauseMax);
					}
					break;
				}

				case DW_FROG_PAUSE:
				{
					this.squash[i] += (1.0 - this.squash[i]) * Math.min(1.0, dt * 10.0);   // recover
					if (pool.trailCount[i] > 0) { pool.trailCount[i]--; }
					this.stTimer[i] -= dt;
					if (this.stTimer[i] <= 0.0) {
						this.st[i] = DW_FROG_REST;
						this.stTimer[i] = this._rand(this.restMin, this.restMax);
					}
					break;
				}
			}
		}
	}

	// emit one rig point into the batch at (batch offset o) and return the new offset.
	_emit(o, x, y, z, size, r, g, b, a)
	{
		const batch = this.batch;
		batch[o + 0] = x;
		batch[o + 1] = y;
		batch[o + 2] = z;
		batch[o + 3] = size;
		batch[o + 4] = r;
		batch[o + 5] = g;
		batch[o + 6] = b;
		batch[o + 7] = a;
		return o + DW_FROG_STRIDE;
	}

	// build the GPU batch: readable point rig around each frog anchor + short trail.
	buildBatch()
	{
		const pool = this.pool;
		const tl = this.trailLength;
		let o = 0;

		for (let i = 0; i < this.maxActive; i++)
		{
			if (!pool.alive[i] || pool.alpha[i] <= 0.001) {
				continue;
			}

			const a = pool.alpha[i];
			const s = pool.size[i];
			const sq = this.squash[i];
			const inten = pool.intensity[i];
			const br = pool.r[i] * inten, bg = pool.g[i] * inten, bb = pool.b[i] * inten;
			const eInten = this.eyeIntensity;
			const er = this.eR[i] * eInten, eg = this.eG[i] * eInten, eb = this.eB[i] * eInten;

			// local frame from heading: forward (fx,fz), right (rx,rz).
			const fx = Math.sin(this.yaw[i]), fz = Math.cos(this.yaw[i]);
			const rx = Math.cos(this.yaw[i]), rz = -Math.sin(this.yaw[i]);
			const px = pool.px[i], py = pool.py[i], pz = pool.pz[i];
			const leg = this.legX[i];

			// helper local->world: p + (f*ff + r*rr) + up*uu, scaled by s.
			// body (center, low, largest).
			o = this._emit(o, px, py + 0.45 * sq * s, pz, s * 1.0, br, bg, bb, a);
			// head (forward + up).
			o = this._emit(o,
				px + fx * 0.65 * s, py + (0.7 * sq) * s, pz + fz * 0.65 * s,
				s * 0.72, br, bg, bb, a);
			// eyes (near head, offset left/right, slightly up, brighter).
			o = this._emit(o,
				px + fx * 0.8 * s + rx * 0.28 * s, py + (0.9 * sq) * s, pz + fz * 0.8 * s + rz * 0.28 * s,
				s * 0.42, er, eg, eb, a);
			o = this._emit(o,
				px + fx * 0.8 * s - rx * 0.28 * s, py + (0.9 * sq) * s, pz + fz * 0.8 * s - rz * 0.28 * s,
				s * 0.42, er, eg, eb, a);
			// hind legs (behind, spread out as legs extend).
			const hindBack = 0.45 + 0.5 * leg;
			const hindSide = 0.42 + 0.25 * leg;
			o = this._emit(o,
				px - fx * hindBack * s + rx * hindSide * s, py + 0.12 * s, pz - fz * hindBack * s + rz * hindSide * s,
				s * 0.5, br, bg, bb, a);
			o = this._emit(o,
				px - fx * hindBack * s - rx * hindSide * s, py + 0.12 * s, pz - fz * hindBack * s - rz * hindSide * s,
				s * 0.5, br, bg, bb, a);
			// forelegs (front, small; reach forward slightly as legs extend).
			const foreFwd = 0.45 + 0.25 * leg;
			o = this._emit(o,
				px + fx * foreFwd * s + rx * 0.28 * s, py + 0.1 * s, pz + fz * foreFwd * s + rz * 0.28 * s,
				s * 0.34, br, bg, bb, a);
			o = this._emit(o,
				px + fx * foreFwd * s - rx * 0.28 * s, py + 0.1 * s, pz + fz * foreFwd * s - rz * 0.28 * s,
				s * 0.34, br, bg, bb, a);

			// short airborne motion trail (dim, most-recent brightest).
			const tc = pool.trailCount[i];
			for (let k = 0; k < tc; k++) {
				const idx = ((pool.trailHead[i] - 1 - k) % tl + tl) % tl;
				const base = i * tl + idx;
				const falloff = 1.0 - (k / tl);
				const ti = pool.trailI[base] * falloff * 0.4;
				o = this._emit(o,
					pool.trailX[base], pool.trailY[base], pool.trailZ[base],
					s * (0.25 + 0.4 * falloff),
					pool.r[i] * ti, pool.g[i] * ti, pool.b[i] * ti, a * falloff);
			}
		}

		this.batchCount = o / DW_FROG_STRIDE;
		return { data: this.batch, count: this.batchCount };
	}

	activeCount()
	{
		let n = 0;
		for (let i = 0; i < this.maxActive; i++) {
			if (this.pool.alive[i]) { n++; }
		}
		return n;
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxLightSerpents.js
//
// "Creatures of the Night" prototype: one (configurable) restrained light serpent that wanders
// forward across the fog scene with a lateral slither wave and a lower-frequency vertical wave
// (an up/down-hill feel), fades in whole, slithers for an interval, then fades head-to-tail and
// respawns elsewhere after a delay. Purely a visual proof.
//
// Built on the same pooled light-point path as the golden wisps / fireflies (dwGfxParticlePool +
// the 8-float [px,py,pz,size, r,g,b,a] batch that dwGfx.drawParticles uploads additively into the
// HDR scene buffer). No new shader: each segment is an ordinary HDR light point, so bloom and the
// built-in per-particle fog transmittance apply. Particles never write depth.
//
// The body is a chain of pooled segments sampled from a per-serpent head-position history ring
// (bright head -> fading tail). The slither/vertical waves are produced by steering the head
// (yaw oscillation) and modulating head height, so the wave travels naturally down the body as
// segments follow the recorded path. Terrain is faked as a low-frequency undulation of a safe
// base height; a future ground-height callback (option groundHeightFn) is honored if supplied.
// Only scalar/vector arithmetic is used (no matrix work, no m4 needed).
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_SERP_STRIDE = 8;   // floats per emitted point (matches dwGfx / dwGfxParticle)

// per-serpent lifecycle phases.
const DW_SERP_FADE_IN  = 0;
const DW_SERP_ACTIVE   = 1;
const DW_SERP_FADE_OUT = 2;   // head-to-tail
const DW_SERP_DELAY    = 3;   // hidden between appearances

class dwGfxLightSerpents
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- population / chain ----
		this.count			= o.count			!== undefined ? o.count			: 1;    // serpents
		this.segments		= o.segments		!== undefined ? o.segments		: 24;   // 18..30 light-point segments
		if (this.segments < 2) { this.segments = 2; }
		this.sampleStride	= o.sampleStride	!== undefined ? o.sampleStride	: 3;    // history frames between segments

		// ---- roam area (box half-extents around center) + heights ----
		this.center			= o.center			|| [0.0, 0.0, 0.0];
		this.bounds			= o.bounds			|| [8.0, 0.0, 8.0];
		// scene ground baseline (absolute world Y). The faked terrain undulation is centered on this.
		// Defaults to -2.0; `groundY` is accepted as an alias.
		this.baseY			= o.baseY			!== undefined ? o.baseY
							: (o.groundY		!== undefined ? o.groundY		: -2.0);
		this.baseHeight		= o.baseHeight		!== undefined ? o.baseHeight	: 0.35;  // safe clearance over the ground
		// optional (x,z) -> ABSOLUTE world ground Y hook for future real terrain. When supplied its
		// result is used verbatim (absolute world Y). When absent, ground = baseY + faked undulation.
		this.groundHeightFn	= o.groundHeightFn	|| null;

		// ---- motion ----
		this.speed			= o.speed			!== undefined ? o.speed			: 2.2;   // forward world units/s
		this.slitherAmp		= o.slitherAmp		!== undefined ? o.slitherAmp	: 0.9;   // yaw oscillation amplitude (rad)
		this.slitherFreq	= o.slitherFreq		!== undefined ? o.slitherFreq	: 2.4;   // lateral wave rate (rad/s)
		this.wanderFreq		= o.wanderFreq		!== undefined ? o.wanderFreq	: 0.25;  // slow heading drift rate
		this.wanderAmp		= o.wanderAmp		!== undefined ? o.wanderAmp		: 0.5;   // slow heading drift amplitude (rad)
		this.vertAmp		= o.vertAmp			!== undefined ? o.vertAmp		: 0.45;  // vertical wave amplitude (world units)
		this.vertFreq		= o.vertFreq		!== undefined ? o.vertFreq		: 1.1;   // vertical (up/down-hill) rate
		this.terrainAmp		= o.terrainAmp		!== undefined ? o.terrainAmp	: 0.6;   // faked terrain undulation amplitude
		this.terrainScale	= o.terrainScale	!== undefined ? o.terrainScale	: 0.12;  // faked terrain spatial frequency

		// ---- appearance ----
		this.headSize		= o.headSize		!== undefined ? o.headSize		: 0.16;  // world units
		this.tailSizeScale	= o.tailSizeScale	!== undefined ? o.tailSizeScale	: 0.35;  // tail size as fraction of head
		this.headIntensity	= o.headIntensity	!== undefined ? o.headIntensity	: 3.4;   // HDR
		this.tailIntensity	= o.tailIntensity	!== undefined ? o.tailIntensity	: 1.2;

		// ---- lifecycle timing ----
		this.fadeInTime		= o.fadeInTime		!== undefined ? o.fadeInTime	: 1.2;
		this.activeMin		= o.activeMin		!== undefined ? o.activeMin		: 7.0;   // slither interval (s)
		this.activeMax		= o.activeMax		!== undefined ? o.activeMax		: 13.0;
		this.fadeOutTime	= o.fadeOutTime		!== undefined ? o.fadeOutTime	: 1.6;   // head-to-tail sweep
		this.delayMin		= o.delayMin		!== undefined ? o.delayMin		: 2.0;
		this.delayMax		= o.delayMax		!== undefined ? o.delayMax		: 5.0;

		// ---- restrained gold/green-teal palette ----
		this.headColor		= o.headColor		|| [0.85, 1.00, 0.55];  // bright green-gold head
		this.bodyColor		= o.bodyColor		|| [0.30, 0.95, 0.70];  // green-teal body
		this.colorJitter	= o.colorJitter		!== undefined ? o.colorJitter	: 0.04;
		// ----------------------------------------------------------------------

		this.enabled = (o.enabled !== undefined) ? o.enabled : true;

		// pooled segment storage (all slots kept alive; positions rewritten each frame).
		const cap = this.count * this.segments;
		this.pool = new dwGfxParticlePool(cap, 0);
		for (let i = 0; i < cap; i++) {
			this.pool.spawn();   // reserve every slot once (fixed chain, no per-frame spawn/kill).
		}

		// per-serpent state.
		const n = this.count;
		this.st			= new Int32Array(n);
		this.stTimer	= new Float32Array(n);
		this.hx			= new Float32Array(n);   // head world pos
		this.hy			= new Float32Array(n);
		this.hz			= new Float32Array(n);
		this.baseYaw	= new Float32Array(n);   // slowly-drifting travel heading
		this.tSlither	= new Float32Array(n);   // slither clock
		this.tVert		= new Float32Array(n);   // vertical-wave clock
		this.tWander	= new Float32Array(n);   // wander clock
		this.fade		= new Float32Array(n);   // 0..1 overall fade-in level
		this.fadeCut	= new Float32Array(n);   // head-to-tail cut position (0..1) during fade-out

		// per-serpent head-position history ring.
		this.histLen = this.segments * this.sampleStride + 4;
		this.histX = new Float32Array(n * this.histLen);
		this.histY = new Float32Array(n * this.histLen);
		this.histZ = new Float32Array(n * this.histLen);
		this.histHead = new Int32Array(n);   // next write index
		this.histCount = new Int32Array(n);

		// GPU batch (allocated once): one point per segment.
		this.batch = new Float32Array(cap * DW_SERP_STRIDE);
		this.batchCount = 0;

		for (let s = 0; s < this.count; s++) {
			this._respawn(s, true);
		}
	}

	_rand(a, b)
	{
		return a + Math.random() * (b - a);
	}

	// faked terrain height (or the supplied ground hook) at a world x,z.
	_groundAt(x, z)
	{
		if (this.groundHeightFn) {
			return this.groundHeightFn(x, z);   // absolute world Y, used verbatim.
		}
		// smooth low-frequency undulation centered on baseY so a flat floor still feels like rolling ground.
		return this.baseY + this.terrainAmp * 0.5 * (Math.sin(x * this.terrainScale) + Math.cos(z * this.terrainScale * 1.3));
	}

	_respawn(s, immediate)
	{
		this.hx[s] = this.center[0] + this._rand(-this.bounds[0], this.bounds[0]);
		this.hz[s] = this.center[2] + this._rand(-this.bounds[2], this.bounds[2]);
		this.baseYaw[s] = this._rand(0.0, Math.PI * 2.0);
		this.hy[s] = this._groundAt(this.hx[s], this.hz[s]) + this.baseHeight;
		this.tSlither[s] = this._rand(0.0, Math.PI * 2.0);
		this.tVert[s]    = this._rand(0.0, Math.PI * 2.0);
		this.tWander[s]  = this._rand(0.0, Math.PI * 2.0);
		this.fade[s]     = 0.0;
		this.fadeCut[s]  = 0.0;

		// prime the history ring with the head position so the body starts coherent.
		const off = s * this.histLen;
		for (let k = 0; k < this.histLen; k++) {
			this.histX[off + k] = this.hx[s];
			this.histY[off + k] = this.hy[s];
			this.histZ[off + k] = this.hz[s];
		}
		this.histHead[s] = 0;
		this.histCount[s] = this.histLen;

		this.st[s] = immediate ? DW_SERP_FADE_IN : DW_SERP_DELAY;
		this.stTimer[s] = immediate ? 0.0 : this._rand(this.delayMin, this.delayMax);
	}

	_pushHistory(s)
	{
		const off = s * this.histLen;
		const h = this.histHead[s];
		this.histX[off + h] = this.hx[s];
		this.histY[off + h] = this.hy[s];
		this.histZ[off + h] = this.hz[s];
		this.histHead[s] = (h + 1) % this.histLen;
		if (this.histCount[s] < this.histLen) { this.histCount[s]++; }
	}

	// advance the head one step (forward wander + lateral slither + vertical wave).
	_advanceHead(s, dt)
	{
		this.tSlither[s] += dt;
		this.tVert[s]    += dt;
		this.tWander[s]  += dt;

		// slow travel-heading drift keeps the serpent wandering the scene.
		this.baseYaw[s] += this.wanderAmp * this.wanderFreq * Math.cos(this.tWander[s] * this.wanderFreq) * dt;

		// steer back toward center if approaching the roam edge.
		const dxC = this.center[0] - this.hx[s];
		const dzC = this.center[2] - this.hz[s];
		if (Math.abs(this.hx[s] - this.center[0]) > this.bounds[0] ||
			Math.abs(this.hz[s] - this.center[2]) > this.bounds[2]) {
			const toC = Math.atan2(dxC, dzC);
			// nudge baseYaw toward center.
			let d = toC - this.baseYaw[s];
			while (d > Math.PI) d -= Math.PI * 2.0;
			while (d < -Math.PI) d += Math.PI * 2.0;
			this.baseYaw[s] += d * Math.min(1.0, dt * 1.5);
		}

		// instantaneous heading = travel heading + lateral slither oscillation.
		const yaw = this.baseYaw[s] + this.slitherAmp * Math.sin(this.tSlither[s] * this.slitherFreq);
		const fx = Math.sin(yaw), fz = Math.cos(yaw);
		this.hx[s] += fx * this.speed * dt;
		this.hz[s] += fz * this.speed * dt;

		// vertical wave over faked terrain: up/down-hill feeling.
		const ground = this._groundAt(this.hx[s], this.hz[s]);
		this.hy[s] = ground + this.baseHeight + this.vertAmp * Math.sin(this.tVert[s] * this.vertFreq);

		this._pushHistory(s);
	}

	// simulation only (no GPU work). Call from the demo's update(dt).
	update(dt)
	{
		if (!(dt > 0.0)) {
			return;
		}

		for (let s = 0; s < this.count; s++)
		{
			switch (this.st[s])
			{
				case DW_SERP_FADE_IN:
					this._advanceHead(s, dt);
					this.fade[s] = Math.min(1.0, this.fade[s] + dt / this.fadeInTime);
					if (this.fade[s] >= 1.0) {
						this.st[s] = DW_SERP_ACTIVE;
						this.stTimer[s] = this._rand(this.activeMin, this.activeMax);
					}
					break;

				case DW_SERP_ACTIVE:
					this._advanceHead(s, dt);
					this.fade[s] = 1.0;
					this.stTimer[s] -= dt;
					if (this.stTimer[s] <= 0.0) {
						this.st[s] = DW_SERP_FADE_OUT;
						this.fadeCut[s] = 0.0;
					}
					break;

				case DW_SERP_FADE_OUT:
					this._advanceHead(s, dt);
					// head-to-tail cut sweeps 0->1 over fadeOutTime.
					this.fadeCut[s] += dt / this.fadeOutTime;
					if (this.fadeCut[s] >= 1.0) {
						this.fadeCut[s] = 1.0;
						this._respawn(s, false);   // -> DELAY, then reappears elsewhere.
					}
					break;

				case DW_SERP_DELAY:
					this.stTimer[s] -= dt;
					if (this.stTimer[s] <= 0.0) {
						this._respawn(s, true);    // reappear at the already-chosen new spot.
						this.st[s] = DW_SERP_FADE_IN;
					}
					break;
			}
		}
	}

	// sample the head-history ring `back` frames behind the head into (out[0..2]).
	_sampleHistory(s, back, out)
	{
		const off = s * this.histLen;
		const idx = ((this.histHead[s] - 1 - back) % this.histLen + this.histLen) % this.histLen;
		out[0] = this.histX[off + idx];
		out[1] = this.histY[off + idx];
		out[2] = this.histZ[off + idx];
	}

	// build the GPU batch: bright head -> fading tail, per serpent, honoring fade-in and the
	// head-to-tail fade-out. One point per segment.
	buildBatch()
	{
		const seg = this.segments;
		const stride = this.sampleStride;
		const jbase = this.colorJitter;
		const p = [0.0, 0.0, 0.0];
		let o = 0;

		for (let s = 0; s < this.count; s++)
		{
			if (this.st[s] === DW_SERP_DELAY) {
				continue;   // hidden between appearances.
			}
			const fadeIn = this.fade[s];
			const cut = (this.st[s] === DW_SERP_FADE_OUT) ? this.fadeCut[s] : 0.0;

			for (let k = 0; k < seg; k++)
			{
				const n = k / (seg - 1);   // 0 head .. 1 tail

				// head-to-tail fade-out: segments with normalized pos < cut have vanished.
				let cutA = 1.0;
				if (cut > 0.0) {
					const edge = 0.12;
					cutA = Math.min(1.0, Math.max(0.0, (n - cut) / edge));
				}
				const a = fadeIn * cutA;
				if (a <= 0.001) {
					continue;
				}

				this._sampleHistory(s, k * stride, p);

				// bright head, fading/shrinking tail.
				const size = this.headSize * (1.0 - (1.0 - this.tailSizeScale) * n);
				const inten = this.headIntensity + (this.tailIntensity - this.headIntensity) * n;
				// head uses the bright head color, body blends toward the green-teal body color.
				const t = Math.min(1.0, n * 1.6);
				const cr = this.headColor[0] + (this.bodyColor[0] - this.headColor[0]) * t;
				const cg = this.headColor[1] + (this.bodyColor[1] - this.headColor[1]) * t;
				const cb = this.headColor[2] + (this.bodyColor[2] - this.headColor[2]) * t;
				// stable per-segment jitter (index-based, no per-frame randomness).
				const j = ((k * 0.6180339887) % 1.0 - 0.5) * 2.0 * jbase;

				this.batch[o + 0] = p[0];
				this.batch[o + 1] = p[1];
				this.batch[o + 2] = p[2];
				this.batch[o + 3] = size;
				this.batch[o + 4] = Math.max(0.0, cr + j) * inten;
				this.batch[o + 5] = Math.max(0.0, cg + j) * inten;
				this.batch[o + 6] = Math.max(0.0, cb + j) * inten;
				this.batch[o + 7] = a;
				o += DW_SERP_STRIDE;
			}
		}

		this.batchCount = o / DW_SERP_STRIDE;
		return { data: this.batch, count: this.batchCount };
	}

	// count of currently visible serpents (for HUD / tests).
	activeCount()
	{
		let n = 0;
		for (let s = 0; s < this.count; s++) {
			if (this.st[s] !== DW_SERP_DELAY) { n++; }
		}
		return n;
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxMattePointRenderer.js
//
// Reusable "matte point" renderer -- a companion to dwGfxUmbralPointRenderer for a restrained,
// NON-glowing body/structure layer. Where the umbral renderer multiplicatively darkens the scene and
// the standard particle path additively BLOOMS, this renderer draws soft matte discs with ordinary
// ALPHA / OVER blending: they read as solid-but-soft material sitting in the scene, not light.
//
// How it stays "matte" (not a light source):
//  - Normal alpha-over blend: blendFuncSeparate(SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE,
//    ONE_MINUS_SRC_ALPHA). Overlapping points composite front-over-back the usual way (no additive
//    accumulation), so nothing runs away in intensity.
//  - TIGHT soft-disc profile with little/no outer halo: alpha = 1 - smoothstep(coreSharpness, 1, r),
//    i.e. a flat core out to `coreSharpness` then a short soft edge to the rim -- unlike the broad
//    exp() aura of glow sprites.
//  - Colors stay BELOW the bloom bright-pass threshold by default (restrained matteColor * intensity
//    well under 1.0, and the bright-pass threshold is 2.0), so the matte layer is not fed to bloom.
//
// Shared safety with the other point effects:
//  - Own WebGL2 point-sprite program, created lazily on first draw() (headless construction / node
//    tests need no GL context).
//  - Depth-TESTs against the authoritative opaque + alpha-tested-logo depth (LEQUAL) but NEVER writes
//    depth (depthMask(false)), so matte shapes hide behind solid geometry.
//  - Bounded analytic per-point fog attenuation folded into alpha (distant => fainter), matching the
//    other post-fog point effects. fogParams === null => no attenuation.
//  - Captures + restores every GL state it touches (program / VAO / ARRAY_BUFFER / blend enable +
//    separate factors / depth test / depth write mask / cull).
//
// Batch layout: 8 floats/point [px, py, pz, size, r, g, b, alpha] (a_position vec4 + a_color vec4),
// matching the engine's particle attribute locations (0 and 4). One draw for all creatures that
// append into the shared batch. m4 is used only for the view matrix inverse.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_MATTE_STRIDE = 8;   // floats per emitted matte point
const DW_MATTE_PFOG_MAX_POCKETS = 8;   // bounded pocket count (matches the analytic fog cap)

class dwGfxMattePointRenderer
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		this.maxPoints	= o.maxPoints	!== undefined ? o.maxPoints	: 512;   // hard cap on matte points
		this.coreSharpness = o.coreSharpness !== undefined ? o.coreSharpness : 0.72;  // 0..1: flat core radius
		this.maxPointSize = o.maxPointSize !== undefined ? o.maxPointSize : 1024.0;
		// default max emitted luminance stays under the bloom bright-pass threshold (2.0) so the matte
		// layer is not fed to bloom. Informational cap used by callers/tests; not clamped here.
		this.bloomThreshold = o.bloomThreshold !== undefined ? o.bloomThreshold : 2.0;
		this.enabled	= (o.enabled !== undefined) ? o.enabled : true;

		// Creature-material fog floor: distant fog must not drive the readable body/rim silhouette to
		// zero alpha. This clamps ONLY this renderer's per-point transmittance to [fogFloor, 1] -- it
		// does NOT touch the global volumetric fog. fogFloor 0 => exact prior behavior.
		this.fogFloor	= o.fogFloor	!== undefined ? o.fogFloor	: 0.0;
		// A/B visibility diagnostic: a single global multiplier on emitted alpha (post-fog, pre-clamp).
		// 1.0 = normal; the demo can raise it (fogConfig.matteDiag) to force the silhouette for tuning.
		this.alphaScale	= o.alphaScale	!== undefined ? o.alphaScale	: 1.0;

		// pooled batch, allocated once (no per-frame allocation).
		this.batch = new Float32Array(this.maxPoints * DW_MATTE_STRIDE);
		this.count = 0;

		// GL resources are created lazily on the first draw() (guarded so node/tests need no GL).
		this._glReady		= false;
		this._programInfo	= null;
		this._vao			= null;
		this._vbo			= null;
	}

	// clear the shared batch at the start of a frame; creatures then append into it.
	reset()
	{
		this.count = 0;
		return this;
	}

	// append one matte point. size is world units; (r,g,b) is the matte color (kept below the bloom
	// threshold by the caller); alpha in [0,1]. Returns false when the hard cap is reached.
	push(x, y, z, size, r, g, b, alpha)
	{
		if (this.count >= this.maxPoints) {
			return false;
		}
		let o = this.count * DW_MATTE_STRIDE;
		const bt = this.batch;
		bt[o + 0] = x;
		bt[o + 1] = y;
		bt[o + 2] = z;
		bt[o + 3] = size;
		bt[o + 4] = r;
		bt[o + 5] = g;
		bt[o + 6] = b;
		let a = alpha * this.alphaScale;
		bt[o + 7] = a < 0.0 ? 0.0 : (a > 1.0 ? 1.0 : a);
		this.count++;
		return true;
	}

	// append with fog attenuation folded into alpha (distant/foggy => fainter matte).
	pushFogged(x, y, z, size, r, g, b, alpha, fogParams)
	{
		const t = this._fogTransmittance(x, y, z, fogParams);
		return this.push(x, y, z, size, r, g, b, alpha * t);
	}

	// bounded analytic transmittance in [0,1] to a world point. 1 (near/clear) -> 0 (far/foggy).
	// null fogParams => 1.0 (unfogged). Clamped distance + bounded pockets => no unbounded work.
	_fogTransmittance(x, y, z, fp)
	{
		if (!fp) {
			return 1.0;
		}
		const cp = fp.cameraPos;
		const dx = x - cp[0], dy = y - cp[1], dz = z - cp[2];
		let dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
		const maxD = fp.maxDistance !== undefined ? fp.maxDistance : 1e9;
		const d = dist < maxD ? dist : maxD;

		let optical = (fp.density || 0.0) * d;

		// ellipsoid pockets add extra local extinction when the point sits inside one (bounded count).
		const n = Math.min(fp.pocketCount | 0, DW_MATTE_PFOG_MAX_POCKETS);
		if (n > 0 && fp.pocketCenters) {
			for (let i = 0; i < n; i++) {
				const cx = fp.pocketCenters[i * 3 + 0];
				const cy = fp.pocketCenters[i * 3 + 1];
				const cz = fp.pocketCenters[i * 3 + 2];
				const rr = fp.pocketRadii ? fp.pocketRadii[i] : 0.0;
				const fe = fp.pocketFeathers ? fp.pocketFeathers[i] : 0.0;
				const pd = fp.pocketDensity ? fp.pocketDensity[i] : 0.0;
				if (rr <= 0.0) { continue; }
				const px = x - cx, py = y - cy, pz = z - cz;
				const pdist = Math.sqrt(px * px + py * py + pz * pz);
				const e0 = rr + fe, e1 = rr - fe;
				let inside;
				if (e0 === e1) {
					inside = pdist <= rr ? 1.0 : 0.0;
				} else {
					let tt = (pdist - e0) / (e1 - e0);
					tt = tt < 0.0 ? 0.0 : (tt > 1.0 ? 1.0 : tt);
					inside = tt * tt * (3.0 - 2.0 * tt);
				}
				optical += pd * inside * d * 0.5;
			}
		}
		let t = Math.exp(-optical);
		t = t < 0.0 ? 0.0 : (t > 1.0 ? 1.0 : t);
		// creature-material fog floor: remap into [fogFloor, 1] so a distant/foggy body/rim never
		// fully vanishes. Does not affect the global fog; fogFloor 0 => exact prior transmittance.
		return this.fogFloor + (1.0 - this.fogFloor) * t;
	}

	// read-only view of the current batch (for tests / diagnostics).
	batchView()
	{
		return { data: this.batch, count: this.count };
	}

	activeCount()
	{
		return this.count;
	}

	// ---- GL ----------------------------------------------------------------------------------------

	_vsSource()
	{
		return "#version 300 es\n" +
			"layout(location = 0) in vec4 a_position;\n" +   // xyz world, w = world size
			"layout(location = 4) in vec4 a_color;\n" +      // rgb = matte color, w = alpha
			"uniform mat4 u_view;\n" +
			"uniform mat4 u_projection;\n" +
			"uniform float u_sizeScale;\n" +
			"uniform float u_maxPointSize;\n" +
			"out vec3 v_color;\n" +
			"out float v_alpha;\n" +
			"void main() {\n" +
			"  vec4 viewPos = u_view * vec4(a_position.xyz, 1.0);\n" +
			"  gl_Position = u_projection * viewPos;\n" +
			"  float dist = max(0.0001, -viewPos.z);\n" +
			"  float ps = a_position.w * u_sizeScale / dist;\n" +
			"  gl_PointSize = clamp(ps, 1.0, u_maxPointSize);\n" +
			"  v_color = a_color.rgb;\n" +
			"  v_alpha = a_color.w;\n" +
			"}\n";
	}

	_fsSource()
	{
		return "#version 300 es\n" +
			"precision highp float;\n" +
			"in vec3 v_color;\n" +
			"in float v_alpha;\n" +
			"uniform float u_coreSharpness;\n" +
			"out vec4 fragColor;\n" +
			"void main() {\n" +
			"  vec2 c = gl_PointCoord - vec2(0.5);\n" +
			"  float r = length(c) * 2.0;\n" +           // 0 center .. 1 rim
			"  if (r > 1.0) { discard; }\n" +
			"  float disc = 1.0 - smoothstep(u_coreSharpness, 1.0, r);\n" +   // flat core -> short soft edge, no broad halo
			"  float a = v_alpha * disc;\n" +
			"  if (a <= 0.0) { discard; }\n" +
			"  fragColor = vec4(v_color, a);\n" +   // straight alpha for SRC_ALPHA/ONE_MINUS_SRC_ALPHA over-blend
			"}\n";
	}

	_initGL()
	{
		const gl = dwGfx.gl();
		this._programInfo = twgl.createProgramInfo(gl, [this._vsSource(), this._fsSource()], {
			attribLocations: { 'a_position': 0, 'a_color': 4 },
		});

		this._vao = gl.createVertexArray();
		this._vbo = gl.createBuffer();

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		gl.bufferData(gl.ARRAY_BUFFER, this.batch.byteLength, gl.DYNAMIC_DRAW);

		const stride = DW_MATTE_STRIDE * 4;   // bytes
		gl.enableVertexAttribArray(0);
		gl.vertexAttribPointer(0, 4, gl.FLOAT, false, stride, 0);
		gl.enableVertexAttribArray(4);
		gl.vertexAttribPointer(4, 4, gl.FLOAT, false, stride, 16);

		gl.bindVertexArray(null);
		gl.bindBuffer(gl.ARRAY_BUFFER, null);

		this._glReady = true;
	}

	// draw the accumulated matte batch with alpha-over blending into the currently-bound scene FB.
	// Fully self-contained: captures + restores every GL state it touches.
	draw(cameraView)
	{
		if (!this.enabled || this.count <= 0) {
			return;
		}
		const gl = dwGfx.gl();
		if (!this._glReady) {
			this._initGL();
		}

		let count = this.count;
		if (count > this.maxPoints) { count = this.maxPoints; }

		// ---- capture prior GL state ----
		const prevProgram	= gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO		= gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArrayBuf	= gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		const prevBlend		= gl.isEnabled(gl.BLEND);
		const prevDepthTest	= gl.isEnabled(gl.DEPTH_TEST);
		const prevCull		= gl.isEnabled(gl.CULL_FACE);
		const prevDepthMask	= gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevSrcRGB	= gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB	= gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcAlpha	= gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstAlpha	= gl.getParameter(gl.BLEND_DST_ALPHA);

		const viewMatrix = m4.inverse(cameraView.worldMatrix);
		const projectionMatrix = cameraView.projectionMatrix;
		const sizeScale = projectionMatrix[5] * gl.canvas.height * 0.5;

		gl.useProgram(this._programInfo.program);
		twgl.setUniforms(this._programInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_sizeScale: sizeScale,
			u_maxPointSize: this.maxPointSize,
			u_coreSharpness: this.coreSharpness,
		});

		// ALPHA / OVER: standard front-over-back transparency, dst_alpha kept sane. Depth-test but
		// never write depth.
		gl.enable(gl.BLEND);
		gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(false);
		gl.disable(gl.CULL_FACE);

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.batch, 0, count * DW_MATTE_STRIDE);
		gl.drawArrays(gl.POINTS, 0, count);

		// ---- restore prior GL state exactly ----
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArrayBuf);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);
		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
		if (prevBlend) { gl.enable(gl.BLEND); } else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (prevCull) { gl.enable(gl.CULL_FACE); } else { gl.disable(gl.CULL_FACE); }
		gl.depthMask(prevDepthMask);
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxUmbralPointRenderer.js
//
// First-pass "colored umbral creature" point renderer. Draws soft dark point-sprites that
// MULTIPLICATIVELY darken + chromatically tint the HDR scene color that is already in the bound
// scene framebuffer (after the fog composite). This is a visible, inexpensive proof -- NOT the
// final quarter-resolution blurred-mask architecture.
//
// How it stays safe:
//  - Its own WebGL2 point-sprite program (created lazily on first draw so headless construction /
//    node tests never need a GL context).
//  - MULTIPLICATIVE blend: dst_rgb = dst_rgb * src_rgb (blendFuncSeparate(ZERO, SRC_COLOR, ZERO, ONE)),
//    so the scene is only darkened/tinted, never brightened -> nothing is fed to bloom as positive
//    light, and overlapping points combine order-independently (multiplication is commutative), so
//    NO transparent back-to-front sort is needed.
//  - Reads the destination via the blend unit, never by sampling the color attachment -> no feedback
//    loop with the HDR color texture. No extra fullscreen FBO / blur pass.
//  - Depth-TESTs against the authoritative opaque + alpha-tested-logo depth (LEQUAL) but NEVER writes
//    depth (depthMask(false)), so umbral shapes hide behind solid geometry yet all overlap.
//  - Captures and restores every GL state it touches (program / VAO / ARRAY_BUFFER / blend enable +
//    separate factors / depth test / depth write mask / cull).
//
// Per-point transmission (in the fragment shader):
//     radial       = exp(-r*r*softness)                 // 1 at core -> broad soft aura at rim
//     k            = clamp(radial * strength, 0, 1)
//     transmission = mix(vec3(1.0), tint, k)            // 1 = unchanged, tint = dark colored core
// giving a dark core with a broad colored inverse-glow aura. `tint` is arbitrary per point, so any
// chromatic umbra (purple / green / blue / red / ...) is supported, not just purple.
//
// Fog: strength is attenuated per point on the CPU by a bounded analytic transmittance to the point's
// own world-space position (camera distance clamped to maxDistance + up to 8 ellipsoid pockets),
// matching the "camera->center path" spirit of the other post-fog point effects. Distant shapes fade
// INTO the haze rather than cutting through it. fogParams === null => no attenuation.
//
// Batch layout: 8 floats/point [px, py, pz, size, tintR, tintG, tintB, strength] (a_position vec4 +
// a_color vec4), matching the engine's particle attribute locations (0 and 4). One draw for all
// creatures that append into the shared batch. m4 is used only for the view matrix inverse.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_UMBRAL_STRIDE = 8;   // floats per emitted umbral point
const DW_UMBRAL_PFOG_MAX_POCKETS = 8;   // bounded pocket count (matches the analytic fog cap)

class dwGfxUmbralPointRenderer
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		this.maxPoints	= o.maxPoints	!== undefined ? o.maxPoints	: 512;   // hard cap on umbral points
		this.softness	= o.softness	!== undefined ? o.softness	: 3.0;   // radial aura width (larger = tighter core)
		this.maxPointSize = o.maxPointSize !== undefined ? o.maxPointSize : 1024.0;
		this.enabled	= (o.enabled !== undefined) ? o.enabled : true;

		// Creature-material fog floor: distant fog must not drive the umbral darkening strength to zero
		// where the scene IS lit (bright fog), so the silhouette still reads at range. Clamps ONLY this
		// renderer's per-point transmittance to [fogFloor, 1]; the global fog is untouched. 0 => prior.
		this.fogFloor	= o.fogFloor	!== undefined ? o.fogFloor	: 0.0;

		// pooled batch, allocated once (no per-frame allocation).
		this.batch = new Float32Array(this.maxPoints * DW_UMBRAL_STRIDE);
		this.count = 0;

		// GL resources are created lazily on the first draw() (guarded so node/tests need no GL).
		this._glReady		= false;
		this._programInfo	= null;
		this._vao			= null;
		this._vbo			= null;
	}

	// clear the shared batch at the start of a frame; creatures then append into it.
	reset()
	{
		this.count = 0;
		return this;
	}

	// append one umbral point. size is world units; tint is the multiplicative transmission color at
	// the core; strength in [0,1]. Returns false when the hard cap is reached (over-request clamps).
	push(x, y, z, size, tr, tg, tb, strength)
	{
		if (this.count >= this.maxPoints) {
			return false;
		}
		let o = this.count * DW_UMBRAL_STRIDE;
		const b = this.batch;
		b[o + 0] = x;
		b[o + 1] = y;
		b[o + 2] = z;
		b[o + 3] = size;
		b[o + 4] = tr;
		b[o + 5] = tg;
		b[o + 6] = tb;
		b[o + 7] = strength < 0.0 ? 0.0 : (strength > 1.0 ? 1.0 : strength);
		this.count++;
		return true;
	}

	// append with fog attenuation folded into strength (distant/foggy => weaker darkening).
	pushFogged(x, y, z, size, tr, tg, tb, strength, fogParams)
	{
		const t = this._fogTransmittance(x, y, z, fogParams);
		return this.push(x, y, z, size, tr, tg, tb, strength * t);
	}

	// bounded analytic transmittance in [0,1] to a world point. 1 (near/clear) -> 0 (far/foggy).
	// null fogParams => 1.0 (unfogged). Clamped distance + bounded pockets => no unbounded work.
	_fogTransmittance(x, y, z, fp)
	{
		if (!fp) {
			return 1.0;
		}
		const cp = fp.cameraPos;
		const dx = x - cp[0], dy = y - cp[1], dz = z - cp[2];
		let dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
		const maxD = fp.maxDistance !== undefined ? fp.maxDistance : 1e9;
		const d = dist < maxD ? dist : maxD;

		let optical = (fp.density || 0.0) * d;

		// ellipsoid pockets add extra local extinction when the point sits inside one (bounded count).
		const n = Math.min(fp.pocketCount | 0, DW_UMBRAL_PFOG_MAX_POCKETS);
		if (n > 0 && fp.pocketCenters) {
			for (let i = 0; i < n; i++) {
				const cx = fp.pocketCenters[i * 3 + 0];
				const cy = fp.pocketCenters[i * 3 + 1];
				const cz = fp.pocketCenters[i * 3 + 2];
				const rr = fp.pocketRadii ? fp.pocketRadii[i] : 0.0;
				const fe = fp.pocketFeathers ? fp.pocketFeathers[i] : 0.0;
				const pd = fp.pocketDensity ? fp.pocketDensity[i] : 0.0;
				if (rr <= 0.0) { continue; }
				const px = x - cx, py = y - cy, pz = z - cz;
				const pdist = Math.sqrt(px * px + py * py + pz * pz);
				// smoothstep(rr+fe, rr-fe, pdist): 1 well inside, 0 outside the feathered shell.
				const e0 = rr + fe, e1 = rr - fe;
				let inside;
				if (e0 === e1) {
					inside = pdist <= rr ? 1.0 : 0.0;
				} else {
					let tt = (pdist - e0) / (e1 - e0);
					tt = tt < 0.0 ? 0.0 : (tt > 1.0 ? 1.0 : tt);
					inside = tt * tt * (3.0 - 2.0 * tt);
				}
				optical += pd * inside * d * 0.5;
			}
		}
		let t = Math.exp(-optical);
		t = t < 0.0 ? 0.0 : (t > 1.0 ? 1.0 : t);
		// creature-material fog floor: remap into [fogFloor, 1] so a distant silhouette keeps some
		// darkening strength where the scene is lit. Global fog untouched; fogFloor 0 => exact prior.
		return this.fogFloor + (1.0 - this.fogFloor) * t;
	}

	// read-only view of the current batch (for tests / diagnostics).
	batchView()
	{
		return { data: this.batch, count: this.count };
	}

	activeCount()
	{
		return this.count;
	}

	// ---- GL ----------------------------------------------------------------------------------------

	_vsSource()
	{
		return "#version 300 es\n" +
			"layout(location = 0) in vec4 a_position;\n" +   // xyz world, w = world size
			"layout(location = 4) in vec4 a_color;\n" +      // rgb = umbral tint, w = strength
			"uniform mat4 u_view;\n" +
			"uniform mat4 u_projection;\n" +
			"uniform float u_sizeScale;\n" +
			"uniform float u_maxPointSize;\n" +
			"out vec3 v_tint;\n" +
			"out float v_strength;\n" +
			"void main() {\n" +
			"  vec4 viewPos = u_view * vec4(a_position.xyz, 1.0);\n" +
			"  gl_Position = u_projection * viewPos;\n" +
			"  float dist = max(0.0001, -viewPos.z);\n" +
			"  float ps = a_position.w * u_sizeScale / dist;\n" +
			"  gl_PointSize = clamp(ps, 1.0, u_maxPointSize);\n" +
			"  v_tint = a_color.rgb;\n" +
			"  v_strength = a_color.w;\n" +
			"}\n";
	}

	_fsSource()
	{
		return "#version 300 es\n" +
			"precision highp float;\n" +
			"in vec3 v_tint;\n" +
			"in float v_strength;\n" +
			"uniform float u_softness;\n" +
			"out vec4 fragColor;\n" +
			"void main() {\n" +
			"  vec2 c = gl_PointCoord - vec2(0.5);\n" +
			"  float r = length(c) * 2.0;\n" +           // 0 center .. 1 rim
			"  if (r > 1.0) { discard; }\n" +
			"  float radial = exp(-r * r * u_softness);\n" +   // dark core -> broad soft aura
			"  float k = clamp(radial * v_strength, 0.0, 1.0);\n" +
			"  vec3 transmission = mix(vec3(1.0), v_tint, k);\n" +   // 1 = unchanged, tint = dark colored
			"  fragColor = vec4(transmission, 1.0);\n" +
			"}\n";
	}

	_initGL()
	{
		const gl = dwGfx.gl();
		this._programInfo = twgl.createProgramInfo(gl, [this._vsSource(), this._fsSource()], {
			attribLocations: { 'a_position': 0, 'a_color': 4 },
		});

		this._vao = gl.createVertexArray();
		this._vbo = gl.createBuffer();

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		gl.bufferData(gl.ARRAY_BUFFER, this.batch.byteLength, gl.DYNAMIC_DRAW);

		const stride = DW_UMBRAL_STRIDE * 4;   // bytes
		gl.enableVertexAttribArray(0);
		gl.vertexAttribPointer(0, 4, gl.FLOAT, false, stride, 0);
		gl.enableVertexAttribArray(4);
		gl.vertexAttribPointer(4, 4, gl.FLOAT, false, stride, 16);

		gl.bindVertexArray(null);
		gl.bindBuffer(gl.ARRAY_BUFFER, null);

		this._glReady = true;
	}

	// draw the accumulated umbral batch multiplicatively into the currently-bound scene FB.
	// Fully self-contained: captures + restores every GL state it touches.
	draw(cameraView)
	{
		if (!this.enabled || this.count <= 0) {
			return;
		}
		const gl = dwGfx.gl();
		if (!this._glReady) {
			this._initGL();
		}

		let count = this.count;
		if (count > this.maxPoints) { count = this.maxPoints; }

		// ---- capture prior GL state ----
		const prevProgram	= gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO		= gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArrayBuf	= gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		const prevBlend		= gl.isEnabled(gl.BLEND);
		const prevDepthTest	= gl.isEnabled(gl.DEPTH_TEST);
		const prevCull		= gl.isEnabled(gl.CULL_FACE);
		const prevDepthMask	= gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevSrcRGB	= gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB	= gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcAlpha	= gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstAlpha	= gl.getParameter(gl.BLEND_DST_ALPHA);

		const viewMatrix = m4.inverse(cameraView.worldMatrix);
		const projectionMatrix = cameraView.projectionMatrix;
		const sizeScale = projectionMatrix[5] * gl.canvas.height * 0.5;

		gl.useProgram(this._programInfo.program);
		twgl.setUniforms(this._programInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_sizeScale: sizeScale,
			u_maxPointSize: this.maxPointSize,
			u_softness: this.softness,
		});

		// MULTIPLICATIVE: dst_rgb *= src_rgb, dst_alpha untouched. Depth-test but never write depth.
		gl.enable(gl.BLEND);
		gl.blendFuncSeparate(gl.ZERO, gl.SRC_COLOR, gl.ZERO, gl.ONE);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(false);
		gl.disable(gl.CULL_FACE);

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.batch, 0, count * DW_UMBRAL_STRIDE);
		gl.drawArrays(gl.POINTS, 0, count);

		// ---- restore prior GL state exactly ----
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArrayBuf);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);
		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
		if (prevBlend) { gl.enable(gl.BLEND); } else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (prevCull) { gl.enable(gl.CULL_FACE); } else { gl.disable(gl.CULL_FACE); }
		gl.depthMask(prevDepthMask);
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxSurfelPointRenderer.js
//
// Isolated "surfel" (surface-element) point/splat renderer. Unlike the matte renderer (flat alpha-over
// discs) and the umbral renderer (multiplicative darkening), this path draws SHADED, surface-oriented
// splats: each surfel carries a world-space NORMAL and is lit by a simple ambient + directional (moon)
// term, so a chain of surfels reads as a continuous, rounded 3D surface (e.g. a snake's body) rather
// than a flat sprite cloud.
//
// Fully self-contained + safe (same discipline as the matte / umbral renderers):
//  - Own WebGL2 point-sprite program, created lazily on the first draw() so headless construction /
//    node tests need no GL context. This renderer is completely independent of dwGfxMattePointRenderer
//    (which is left unchanged) and of the umbral / light-serpent paths.
//  - Depth-TESTs against the authoritative opaque + logo depth (LEQUAL) and, by default, WRITES depth
//    for the solid disc core (alpha-clipped) so nearer surfels correctly occlude farther ones and the
//    body reads as an opaque surface. The soft rim uses alpha-over blend. depthWrite is configurable;
//    set false to behave like the other non-writing point effects. Explicitly saves + restores
//    depthFunc (the other point effects assume the ambient LEQUAL; here we set it and restore it).
//  - Captures + restores every GL state it touches (program / VAO / ARRAY_BUFFER / blend enable +
//    separate factors / depth test / depth write mask / depth func / cull).
//  - Bounded analytic per-surfel fog attenuation folded into opacity (identical maths to the matte /
//    umbral renderers), with a creature-material fogFloor so a distant body never fully vanishes.
//    fogParams === null => no attenuation.
//
// Lighting (vertex shader, world space): given surfel normal N and a normalized moon direction L,
//     diff  = max(0, dot(N, L))
//     shade = ambientColor + lightColor * diff
//     v_color = baseColor * shade
// A tiny rim/wrap term keeps the shaded-away side from going fully black so the silhouette still reads.
//
// FOG OWNERSHIP (fogMode) -- a compositing-category decision, made explicitly by the caller:
//   "global" : the body is drawn in the PRE-FOG opaque scene stage, into the same HDR color + the same
//              authoritative scene-depth attachment that dwGfxVolumetricFog samples. The volumetric pass
//              then fogs the body from its REAL ray integration (density + ellipsoid pockets + noise +
//              shadowing), exactly like any other opaque geometry. The internal analytic per-surfel mix
//              below is NEUTRALIZED (fogAmt forced to 0 in pushFogged) so the body is not fogged twice.
//              This is the correct mode whenever global volumetric fog is active: an opaque surface
//              composited AFTER a fullscreen fog pass can only ever be pasted on top of it.
//   "self"   : nothing else fogs these pixels (global fog disabled, or the body is deliberately drawn
//              post-fog), so the bounded analytic approximation below is used. This is the legacy path
//              and remains the default, so an unaware caller is unaffected.
// Only the BODY moves pre-fog. Emissive eyes/markings stay in the post-fog additive light-point path with
// their existing per-point attenuation -- they are emitters, not surfaces, and must not write depth.
//
// Fog model (IMPORTANT): the snake body is an OPAQUE surface, so fog must NOT be folded into its alpha
// (doing so makes the body TRANSPARENT and lets the bright fog show through -> the body vanishes into the
// haze instead of being tinted by it). Instead this renderer keeps alpha = geometric coverage (presence /
// depth) and attenuates the LIT color toward the fog color by the per-surfel fog amount (1 - transmittance)
// -- exactly how a real object recedes into atmosphere. A transmittance floor (fogFloor) caps the mix so a
// distant body keeps at least `fogFloor` of its own lit color and stays readable; depth attenuation is
// still obvious because nearer surfels keep more of their color. fogParams === null => no fog.
//
// TWO-PASS BODY (no offscreen target, no OIT, no sorting; at most TWO draw calls for the whole body):
//   Pass A "core"   : BLEND OFF, depth test LEQUAL, depth WRITE ON. The fragment shader keeps only the
//                     solid inner disc (geometric coverage `disc` >= coreClip) and discards the soft outer
//                     band. This lays down a genuinely OPAQUE surface + authoritative depth. The clip is on
//                     GEOMETRIC coverage, never on the fog/opacity-scaled alpha, so heavy fog or a low
//                     creature opacity can never discard the whole body.
//   Pass B "fringe" : premultiplied-alpha blend (ONE, ONE_MINUS_SRC_ALPHA), depth WRITE OFF, depth test
//                     LESS. The shader keeps only the soft outer band (disc < coreClip); the core is NOT
//                     redrawn, so there is no double-blend brightening.
//                     Why depthFunc LESS for the fringe: point sprites are flat (every fragment of one
//                     sprite carries the same depth) and pass A DISCARDED this fringe band, so a fringe
//                     fragment is never rejected by its own core. What LESS does reject is a fringe
//                     fragment landing on a NEIGHBOUR's already-written core at equal (or nearer) depth --
//                     exactly the soft-halo / see-through accumulation that washed the body out when it
//                     came toward the camera. Against the far background the fringe still passes (fringe
//                     depth < background depth), so silhouette edges stay antialiased. With LEQUAL those
//                     equal-depth neighbour cores would blend a second time and the halos come back.
//   `fringe = false` => pass A only (hard-core A/B diagnostic; exactly ONE draw call).
//   `depthWrite = false` => legacy SINGLE pass (alpha-over, depth test only, full soft disc) so the
//                     renderer can still behave like the non-writing matte / umbral point effects.
//
// ALBEDO TEXTURE: sampled ONCE PER SURFEL in the VERTEX shader (textureLod, level 0) and multiplied into
// the per-surfel tint before lighting -- not per fragment, so the cost stays ~free at 100K points. The
// renderer owns a lazily-created 1x1 opaque WHITE fallback, so the default look is identical to the
// untextured pipeline. Supply a real skin later with setAlbedoTexture(tex) (null reverts to white); the
// snake's surfel generation does not change. The active texture unit and its previous 2D binding are
// saved and restored.
//   The sampler uniform is assigned DIRECTLY with gl.uniform1i(loc, unit) while our program is current --
//   deliberately NOT through twgl.setUniforms. twgl's sampler setter takes a WebGLTexture, not a unit
//   index: given a plain number it resolves `textureOrPair.texture` to undefined and then calls
//   gl.bindTexture(TEXTURE_2D, undefined) on its own chosen unit, which UNBINDS whatever we had just
//   bound. That made every vertex fetch return (0,0,0,1) and turned the whole body black. Binding + the
//   uniform now live in one place here, with no twgl involvement, so they cannot disagree.
//   The 1x1 fallback is a COMPLETE texture: RGBA/UNSIGNED_BYTE 255,255,255,255 with explicit NEAREST
//   min+mag filters (no mipmap dependency -- the WebGL default MIN_FILTER is NEAREST_MIPMAP_LINEAR, which
//   would be incomplete for a mip-less texture and also sample black) and CLAMP_TO_EDGE wrapping.
//
// Batch layout: 14 floats/surfel (stride 56 B)
//     [ px, py, pz, size,  nx, ny, nz,  r, g, b, opacity,  fogAmt,  u, v ]
//   a_position (loc 0) vec4  = xyz + world size            (offset  0)   floats 0..3
//   a_normal   (loc 1) vec3  = world-space normal          (offset 16)   floats 4..6
//   a_color    (loc 4) vec4  = rgb + opacity               (offset 28)   floats 7..10
//   a_fog      (loc 2) float = fog amount 1-transmittance  (offset 44)   float  11
//   a_texcoord (loc 3) vec2  = albedo UV (cylindrical)     (offset 48)   floats 12..13
// (locations follow the engine convention a_position=0, a_normal=1, a_color=4; a_fog keeps loc 2 and the
// new UV takes the free loc 3. This is its own program so the layout cannot collide with the matte /
// umbral renderers.) m4 is view-inverse only.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_SURFEL_STRIDE = 14;   // floats per emitted surfel (12 + cylindrical UV)
const DW_SURFEL_PFOG_MAX_POCKETS = 8;   // bounded pocket count (matches the analytic fog cap)

// Absolute hard capacity shared by the renderer + the snake (dwGfxSurfelSnake.js references this global;
// this file's <script> is always loaded first). 131072 = 2^17: comfortably above the 100,000-surfel stress
// preset and a clean documented power-of-two cap. Staging cost at stride 14 floats:
// 131072 * 14 * 4 B ~= 7.34 MB for the reused CPU batch, plus one GPU buffer of the same size (allocated
// once, on the first draw). The 100K preset itself uses 100000 * 14 * 4 B ~= 5.6 MB. maxPoints is clamped
// to this so a caller can never over-allocate the staging buffer.
const DW_SURFEL_MAX_CAPACITY = 131072;

class dwGfxSurfelPointRenderer
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// staging capacity. Defaults to the shared hard cap so a single renderer can hold the 100K stress
		// preset; clamped to DW_SURFEL_MAX_CAPACITY so a caller can never over-allocate the pooled batch.
		this.maxPoints	= o.maxPoints	!== undefined
						? Math.max(1, Math.min(o.maxPoints | 0, DW_SURFEL_MAX_CAPACITY))
						: DW_SURFEL_MAX_CAPACITY;
		this.maxPointSize = o.maxPointSize !== undefined ? o.maxPointSize : 1024.0;
		this.enabled	= (o.enabled !== undefined) ? o.enabled : true;

		// ---- two-pass core / fringe -------------------------------------------------------------------
		// fringeWidth is the RADIAL width of the soft antialiased band at the splat rim, as a fraction of
		// the splat radius (0 => a hard-edged disc, 1 => the whole splat is a gradient). The coverage
		// falloff therefore runs over r in [1-fringeWidth, 1]. Tight is deliberate: a wide feather is what
		// produced the matte halos / see-through accumulation, so the default is narrow enough to kill the
		// halos while still antialiasing the silhouette.
		this.fringeWidth = o.fringeWidth !== undefined ? Math.max(0.0, Math.min(o.fringeWidth, 1.0)) : 0.30;
		// coreSharpness (legacy name) is the radius where the coverage falloff BEGINS. Derived from
		// fringeWidth unless explicitly supplied, so old configs keep working.
		this.coreSharpness = o.coreSharpness !== undefined
						? Math.max(0.0, Math.min(o.coreSharpness, 1.0))
						: (1.0 - this.fringeWidth);
		// coreClip: geometric-coverage threshold that separates the OPAQUE core (pass A, writes depth) from
		// the soft fringe (pass B, blended, no depth write). Clamped away from 0/1 so neither pass can ever
		// become empty. `alphaClip` is accepted as the legacy alias.
		this.coreClip	= o.coreClip	!== undefined ? o.coreClip
						: (o.alphaClip !== undefined ? o.alphaClip : 0.5);
		this.coreClip	= Math.max(0.05, Math.min(this.coreClip, 0.95));
		this.alphaClip	= this.coreClip;   // legacy alias kept in sync
		// fringe pass on/off. false => hard-core only (one draw call) for an A/B halo diagnostic.
		this.fringe		= (o.fringe !== undefined) ? !!o.fringe : true;

		// depth: write the solid disc core so surfels occlude each other -> reads as an opaque surface.
		// depthWrite false => legacy single-pass, non-writing point effect (test only, alpha-over).
		this.depthWrite	= (o.depthWrite !== undefined) ? o.depthWrite : true;

		// ---- who owns this body's fog (EXPLICIT, never inferred) --------------------------------------
		//   "global" : the body is drawn in the pre-fog opaque scene stage and the authoritative
		//              volumetric pass fogs it from its own ray integration + the scene depth this
		//              renderer just wrote. The internal analytic mix is NEUTRALIZED (see pushFogged) so
		//              the body is never fogged twice.
		//   "self"   : no global volumetric fog owns these pixels (fog disabled, or the body is drawn
		//              post-fog), so the bounded per-surfel analytic approximation is applied as before.
		// Defaults to "self" -> a caller that knows nothing about this flag keeps the legacy behaviour.
		this.fogMode	= (o.fogMode === "global") ? "global" : "self";

		// ---- albedo texture ---------------------------------------------------------------------------
		// null => the renderer's own lazily-created 1x1 opaque WHITE texture, which reproduces the current
		// (untextured) coloring exactly. setAlbedoTexture(tex) swaps in a real skin later with no change to
		// surfel generation. No external image dependency is introduced here.
		this._albedoTex	= o.albedoTexture || null;   // custom WebGLTexture or null
		this._whiteTex	= null;                      // created in _initGL
		this._uAlbedoLoc = null;                     // located in _initGL
		this.textureUnit = o.textureUnit !== undefined ? (o.textureUnit | 0) : 0;

		// simple moon-style directional light + ambient (world space). Defaults: cool moonlight from
		// upper-left-front. lightColor/ambientColor are multipliers over each surfel's base color.
		this.lightDir	= o.lightDir	|| [-0.35, 0.80, 0.45];   // normalized in _initGL uniforms upload
		this.lightColor	= o.lightColor	|| [0.85, 0.90, 1.05];    // cool moonlight
		this.ambientColor = o.ambientColor || [0.22, 0.24, 0.32];   // never fully black on the shaded side
		this.wrap		= o.wrap		!== undefined ? o.wrap		: 0.35;  // 0..1 wrap-lighting softening

		// creature-material fog floor. Clamps ONLY this renderer's per-surfel transmittance into
		// [fogFloor, 1]; the global volumetric fog is untouched. Because fog attenuates the surfel's LIT
		// COLOR toward u_fogColor (not its alpha), fogFloor is the minimum fraction of the body's own lit
		// color that survives at maximum fog -> a distant body stays readable but still recedes. Higher =>
		// more readable / less atmospheric; 0 => body can tint fully to the fog color at range.
		this.fogFloor	= o.fogFloor	!== undefined ? o.fogFloor	: 0.5;
		// color the fog tints the body toward (should match the scene's fog color for a coherent look).
		this.fogColor	= o.fogColor	|| [0.06, 0.08, 0.10];
		// global opacity multiplier (post-fog, pre-clamp) for A/B tuning; 1.0 = normal.
		this.alphaScale	= o.alphaScale	!== undefined ? o.alphaScale	: 1.0;

		// pooled batch, allocated once (no per-frame allocation).
		this.batch = new Float32Array(this.maxPoints * DW_SURFEL_STRIDE);
		this.count = 0;

		// GL resources are created lazily on the first draw() (guarded so node/tests need no GL).
		this._glReady		= false;
		this._programInfo	= null;
		this._vao			= null;
		this._vbo			= null;
	}

	// clear the shared batch at the start of a frame; creatures then append into it.
	reset()
	{
		this.count = 0;
		return this;
	}

	// append one surfel. size is world units; (nx,ny,nz) world-space normal; (r,g,b) base color;
	// opacity in [0,1]; (u,v) albedo UV (optional, default 0,0 -> any texel of the white fallback).
	// Returns false when the hard cap is reached.
	push(x, y, z, size, nx, ny, nz, r, g, b, opacity, u, v)
	{
		if (this.count >= this.maxPoints) {
			return false;
		}
		let o = this.count * DW_SURFEL_STRIDE;
		const bt = this.batch;
		bt[o + 0] = x;
		bt[o + 1] = y;
		bt[o + 2] = z;
		bt[o + 3] = size;
		bt[o + 4] = nx;
		bt[o + 5] = ny;
		bt[o + 6] = nz;
		bt[o + 7] = r;
		bt[o + 8] = g;
		bt[o + 9] = b;
		let a = opacity * this.alphaScale;
		bt[o + 10] = a < 0.0 ? 0.0 : (a > 1.0 ? 1.0 : a);
		bt[o + 11] = 0.0;   // fog amount (unfogged); pushFogged overrides
		bt[o + 12] = u !== undefined ? u : 0.0;
		bt[o + 13] = v !== undefined ? v : 0.0;
		this.count++;
		return true;
	}

	// append with fog folded into the COLOR (not the alpha): the body keeps full coverage/opacity and its
	// lit color is tinted toward u_fogColor in the shader by fogAmt = 1 - transmittance, so a distant body
	// recedes into the haze while staying an opaque, readable surface. fogFloor caps fogAmt at 1-fogFloor.
	// (u,v) are appended AFTER fogParams so existing callers keep working unchanged.
	//
	// fogMode === "global" NEUTRALIZES this internal approximation (fogAmt forced to 0) because the
	// authoritative volumetric pass fogs the body from its own ray integration. Enforced HERE, at the one
	// place fog enters the batch, so a caller that still passes fogParams cannot double-fog the body.
	pushFogged(x, y, z, size, nx, ny, nz, r, g, b, opacity, fogParams, u, v)
	{
		if (!this.push(x, y, z, size, nx, ny, nz, r, g, b, opacity, u, v)) {
			return false;
		}
		const t = (this.fogMode === "global") ? 1.0 : this._fogTransmittance(x, y, z, fogParams);
		this.batch[(this.count - 1) * DW_SURFEL_STRIDE + 11] = 1.0 - t;   // fog amount
		return true;
	}

	// bounded analytic transmittance in [0,1] to a world point. 1 (near/clear) -> 0 (far/foggy).
	// null fogParams => 1.0 (unfogged). Clamped distance + bounded pockets => no unbounded work.
	_fogTransmittance(x, y, z, fp)
	{
		if (!fp) {
			return 1.0;
		}
		const cp = fp.cameraPos;
		const dx = x - cp[0], dy = y - cp[1], dz = z - cp[2];
		let dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
		const maxD = fp.maxDistance !== undefined ? fp.maxDistance : 1e9;
		const d = dist < maxD ? dist : maxD;

		let optical = (fp.density || 0.0) * d;

		const n = Math.min(fp.pocketCount | 0, DW_SURFEL_PFOG_MAX_POCKETS);
		if (n > 0 && fp.pocketCenters) {
			for (let i = 0; i < n; i++) {
				const cx = fp.pocketCenters[i * 3 + 0];
				const cy = fp.pocketCenters[i * 3 + 1];
				const cz = fp.pocketCenters[i * 3 + 2];
				const rr = fp.pocketRadii ? fp.pocketRadii[i] : 0.0;
				const fe = fp.pocketFeathers ? fp.pocketFeathers[i] : 0.0;
				const pd = fp.pocketDensity ? fp.pocketDensity[i] : 0.0;
				if (rr <= 0.0) { continue; }
				const px = x - cx, py = y - cy, pz = z - cz;
				const pdist = Math.sqrt(px * px + py * py + pz * pz);
				const e0 = rr + fe, e1 = rr - fe;
				let inside;
				if (e0 === e1) {
					inside = pdist <= rr ? 1.0 : 0.0;
				} else {
					let tt = (pdist - e0) / (e1 - e0);
					tt = tt < 0.0 ? 0.0 : (tt > 1.0 ? 1.0 : tt);
					inside = tt * tt * (3.0 - 2.0 * tt);
				}
				optical += pd * inside * d * 0.5;
			}
		}
		let t = Math.exp(-optical);
		t = t < 0.0 ? 0.0 : (t > 1.0 ? 1.0 : t);
		return this.fogFloor + (1.0 - this.fogFloor) * t;
	}

	// read-only view of the current batch (for tests / diagnostics).
	batchView()
	{
		return { data: this.batch, count: this.count };
	}

	activeCount()
	{
		return this.count;
	}

	// ---- GL ----------------------------------------------------------------------------------------

	_vsSource()
	{
		return "#version 300 es\n" +
			"layout(location = 0) in vec4 a_position;\n" +   // xyz world, w = world size
			"layout(location = 1) in vec3 a_normal;\n" +     // world-space surfel normal
			"layout(location = 2) in float a_fog;\n" +       // fog amount = 1 - transmittance (0 near .. 1 far)
			"layout(location = 3) in vec2 a_texcoord;\n" +   // cylindrical albedo UV (U along body, V around ring)
			"layout(location = 4) in vec4 a_color;\n" +      // rgb base color, w = opacity
			"uniform mat4 u_view;\n" +
			"uniform mat4 u_projection;\n" +
			"uniform float u_sizeScale;\n" +
			"uniform float u_maxPointSize;\n" +
			"uniform vec3 u_lightDir;\n" +      // normalized world-space moon direction
			"uniform vec3 u_lightColor;\n" +
			"uniform vec3 u_ambient;\n" +
			"uniform float u_wrap;\n" +
			"uniform vec3 u_fogColor;\n" +      // atmosphere color the body tints toward with distance
			"uniform sampler2D u_albedo;\n" +   // 1x1 white fallback by default -> identical to untextured
			"out vec3 v_color;\n" +
			"out float v_alpha;\n" +
			"void main() {\n" +
			"  vec4 viewPos = u_view * vec4(a_position.xyz, 1.0);\n" +
			"  gl_Position = u_projection * viewPos;\n" +
			"  float dist = max(0.0001, -viewPos.z);\n" +
			"  float ps = a_position.w * u_sizeScale / dist;\n" +
			"  gl_PointSize = clamp(ps, 1.0, u_maxPointSize);\n" +
			"  vec3 N = normalize(a_normal);\n" +
			"  float ndl = dot(N, u_lightDir);\n" +
			"  float diff = max(0.0, (ndl + u_wrap) / (1.0 + u_wrap));\n" +   // wrap softens the terminator
			"  vec3 shade = u_ambient + u_lightColor * diff;\n" +
			// albedo sampled ONCE PER SURFEL (explicit level 0: a vertex shader has no derivatives). The
			// white fallback is (1,1,1) so this multiply is a no-op until a real skin is supplied.
			"  vec3 albedo = textureLod(u_albedo, a_texcoord, 0.0).rgb;\n" +
			"  vec3 lit = a_color.rgb * albedo * shade;\n" +
			// atmospheric fog: tint the LIT color toward the fog color AFTER lighting (so the fog term is
			// not darkened by the surfel's own shading). Alpha is untouched -> the body stays opaque.
			"  v_color = mix(lit, u_fogColor, a_fog);\n" +
			"  v_alpha = a_color.w;\n" +
			"}\n";
	}

	// u_pass selects the body pass:
	//   0 = LEGACY single pass  : full soft disc, straight alpha, alpha-over blend, no depth write.
	//   1 = CORE   (pass A)     : keep disc >= coreClip only, opaque, writes depth, blending disabled.
	//   2 = FRINGE (pass B)     : keep disc <  coreClip only, PREMULTIPLIED alpha, no depth write.
	// In every mode the coverage clip tests GEOMETRIC coverage (disc), never the fog/opacity-scaled alpha,
	// so heavy fog or a low creature opacity can never discard the body.
	_fsSource()
	{
		return "#version 300 es\n" +
			"precision highp float;\n" +
			"in vec3 v_color;\n" +
			"in float v_alpha;\n" +
			"uniform float u_coreSharpness;\n" +
			"uniform float u_coreClip;\n" +
			"uniform int u_pass;\n" +
			"out vec4 fragColor;\n" +
			"void main() {\n" +
			"  vec2 c = gl_PointCoord - vec2(0.5);\n" +
			"  float r = length(c) * 2.0;\n" +           // 0 center .. 1 rim
			"  if (r > 1.0) { discard; }\n" +
			"  float disc = 1.0 - smoothstep(u_coreSharpness, 1.0, r);\n" +   // flat core -> short soft edge
			"  float a = v_alpha * disc;\n" +
			"  if (u_pass == 1) {\n" +
			// CORE: solid inner disc only. Opaque output (alpha 1) with blending disabled, so the core is a
			// genuine opaque surface and cannot accumulate see-through washes from overlapping neighbours.
			"    if (disc < u_coreClip) { discard; }\n" +
			"    fragColor = vec4(v_color, 1.0);\n" +
			"  } else if (u_pass == 2) {\n" +
			// FRINGE: soft outer band only -- the core is NOT redrawn, so no double blend. Premultiplied
			// output pairs with blendFunc(ONE, ONE_MINUS_SRC_ALPHA).
			"    if (disc >= u_coreClip) { discard; }\n" +
			"    if (a <= 0.0) { discard; }\n" +
			"    fragColor = vec4(v_color * a, a);\n" +
			"  } else {\n" +
			// LEGACY: full soft disc, straight alpha for SRC_ALPHA / ONE_MINUS_SRC_ALPHA.
			"    if (a <= 0.0) { discard; }\n" +
			"    fragColor = vec4(v_color, a);\n" +
			"  }\n" +
			"}\n";
	}

	_initGL()
	{
		const gl = dwGfx.gl();
		// lazy init happens INSIDE the first draw(), i.e. before draw() captures the caller's state, so it
		// must put back whatever was bound rather than leaving null behind (would break the first frame).
		const prevVAO = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArrayBuf = gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		this._programInfo = twgl.createProgramInfo(gl, [this._vsSource(), this._fsSource()], {
			attribLocations: { 'a_position': 0, 'a_normal': 1, 'a_fog': 2, 'a_texcoord': 3, 'a_color': 4 },
		});

		this._vao = gl.createVertexArray();
		this._vbo = gl.createBuffer();

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		gl.bufferData(gl.ARRAY_BUFFER, this.batch.byteLength, gl.DYNAMIC_DRAW);

		const stride = DW_SURFEL_STRIDE * 4;   // bytes (56)
		gl.enableVertexAttribArray(0);
		gl.vertexAttribPointer(0, 4, gl.FLOAT, false, stride, 0);
		gl.enableVertexAttribArray(1);
		gl.vertexAttribPointer(1, 3, gl.FLOAT, false, stride, 16);
		gl.enableVertexAttribArray(2);
		gl.vertexAttribPointer(2, 1, gl.FLOAT, false, stride, 44);
		gl.enableVertexAttribArray(3);
		gl.vertexAttribPointer(3, 2, gl.FLOAT, false, stride, 48);
		gl.enableVertexAttribArray(4);
		gl.vertexAttribPointer(4, 4, gl.FLOAT, false, stride, 28);

		gl.bindVertexArray(prevVAO);
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArrayBuf);

		// sampler location cached once; assigned per draw with gl.uniform1i (never via twgl -- see header).
		this._uAlbedoLoc = gl.getUniformLocation(this._programInfo.program, "u_albedo");

		this._initWhiteTexture(gl);
		this._glReady = true;
	}

	// 1x1 opaque WHITE fallback albedo, owned by this renderer. White => the albedo multiply in the vertex
	// shader is a no-op, so the default look matches the untextured pipeline exactly. Restores the previous
	// active unit + 2D binding so creating it cannot disturb the engine's texture state.
	//
	// MUST be a COMPLETE texture or every fetch returns black: level 0 is uploaded and BOTH filters are set
	// explicitly to NEAREST. The WebGL default MIN_FILTER is NEAREST_MIPMAP_LINEAR, which makes a mip-less
	// texture incomplete; NEAREST needs no mip chain, so we never call generateMipmap. CLAMP_TO_EDGE keeps a
	// 1x1 unambiguous regardless of the UVs the snake generates. NEAREST on a 1x1 is also exact - no
	// filtering can dilute pure white, so the per-surfel tint/lighting is reproduced bit-for-bit.
	_initWhiteTexture(gl)
	{
		const prevActive = gl.getParameter(gl.ACTIVE_TEXTURE);
		const prevBinding = gl.getParameter(gl.TEXTURE_BINDING_2D);
		this._whiteTex = gl.createTexture();
		gl.bindTexture(gl.TEXTURE_2D, this._whiteTex);
		gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE,
			new Uint8Array([255, 255, 255, 255]));
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
		gl.bindTexture(gl.TEXTURE_2D, prevBinding);
		gl.activeTexture(prevActive);
	}

	// ---- albedo texture API ------------------------------------------------------------------------

	// Supply a real skin later without touching snake generation. `tex` is a WebGLTexture (or null to
	// revert to the built-in white fallback). Safe to call before GL init.
	setAlbedoTexture(tex)
	{
		this._albedoTex = tex || null;
		return this;
	}

	// For the HUD. "custom" = caller-supplied skin; "white" = built-in complete fallback (default coloring);
	// "ERR" = we are past GL init with nothing bindable, i.e. the fallback failed to build -- the state that
	// would show up as a black body, so it is worth seeing on screen rather than guessing.
	textureState()
	{
		if (this._albedoTex) { return "custom"; }
		if (this._glReady && !this._whiteTex) { return "ERR"; }
		return "white";
	}

	// the texture actually bound for drawing (custom if supplied, else the white fallback).
	_activeTexture()
	{
		return this._albedoTex || this._whiteTex;
	}

	_normalized3(v)
	{
		const l = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]) || 1.0;
		return [v[0] / l, v[1] / l, v[2] / l];
	}

	// draw the accumulated surfel batch as shaded splats into the currently-bound scene FB.
	// Fully self-contained: captures + restores every GL state it touches.
	draw(cameraView)
	{
		if (!this.enabled || this.count <= 0) {
			return;
		}
		const gl = dwGfx.gl();
		if (!this._glReady) {
			this._initGL();
		}

		let count = this.count;
		if (count > this.maxPoints) { count = this.maxPoints; }

		// ---- capture prior GL state (program / VAO / buffers / blend enable+funcs+equations / depth
		//      test+mask+func / cull / active texture unit + its 2D binding) ----
		const prevProgram	= gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO		= gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArrayBuf	= gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		const prevBlend		= gl.isEnabled(gl.BLEND);
		const prevDepthTest	= gl.isEnabled(gl.DEPTH_TEST);
		const prevCull		= gl.isEnabled(gl.CULL_FACE);
		const prevDepthMask	= gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevDepthFunc	= gl.getParameter(gl.DEPTH_FUNC);
		const prevSrcRGB	= gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB	= gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcAlpha	= gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstAlpha	= gl.getParameter(gl.BLEND_DST_ALPHA);
		const prevEqRGB		= gl.getParameter(gl.BLEND_EQUATION_RGB);
		const prevEqAlpha	= gl.getParameter(gl.BLEND_EQUATION_ALPHA);
		const prevActiveTex	= gl.getParameter(gl.ACTIVE_TEXTURE);

		const viewMatrix = m4.inverse(cameraView.worldMatrix);
		const projectionMatrix = cameraView.projectionMatrix;
		const sizeScale = projectionMatrix[5] * gl.canvas.height * 0.5;
		const L = this._normalized3(this.lightDir);

		gl.useProgram(this._programInfo.program);

		// ---- albedo: bind on our unit and point the sampler at that unit, both in one place ----
		// Order matters: the program is already current, so gl.uniform1i lands on it. u_albedo is
		// deliberately NOT in the twgl.setUniforms block below -- twgl's sampler setter would rebind the
		// unit to undefined (=> null => black vertex fetches). Done once here, so BOTH passes below sample
		// the same live binding. The previous binding on the borrowed unit is captured for restore.
		const unit = this.textureUnit;
		gl.activeTexture(gl.TEXTURE0 + unit);
		const prevTexBinding = gl.getParameter(gl.TEXTURE_BINDING_2D);
		gl.bindTexture(gl.TEXTURE_2D, this._activeTexture());
		if (this._uAlbedoLoc !== null) {
			gl.uniform1i(this._uAlbedoLoc, unit);
		}
		twgl.setUniforms(this._programInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_sizeScale: sizeScale,
			u_maxPointSize: this.maxPointSize,
			u_coreSharpness: this.coreSharpness,
			u_coreClip: this.coreClip,
			u_lightDir: L,
			u_lightColor: this.lightColor,
			u_ambient: this.ambientColor,
			u_wrap: this.wrap,
			u_fogColor: this.fogColor,
		});

		// shared for every pass: depth test against the authoritative opaque + logo depth, no culling.
		gl.enable(gl.DEPTH_TEST);
		gl.disable(gl.CULL_FACE);
		gl.blendEquationSeparate(gl.FUNC_ADD, gl.FUNC_ADD);

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		// ONE upload of the active slice, reused by both passes -> at most two draw calls for the whole body
		// regardless of point count. No per-surfel draws, no sorting, no per-frame allocation.
		gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.batch, 0, count * DW_SURFEL_STRIDE);

		if (this.depthWrite) {
			// ---- PASS A: opaque core. Blending OFF, depth WRITE ON, LEQUAL against the scene. ----
			gl.disable(gl.BLEND);
			gl.depthFunc(gl.LEQUAL);
			gl.depthMask(true);
			twgl.setUniforms(this._programInfo, { u_pass: 1 });
			gl.drawArrays(gl.POINTS, 0, count);

			if (this.fringe) {
				// ---- PASS B: antialiased fringe. Premultiplied alpha, depth WRITE OFF, depthFunc LESS. ----
				// LESS (not LEQUAL) rejects fringe fragments sitting on a neighbour's equal-depth core, which
				// is what removes the soft halos / see-through accumulation; the fringe still feathers into
				// the farther background, and it is never rejected by its OWN core (pass A discarded this
				// band, so no depth was written for these fragments).
				gl.enable(gl.BLEND);
				gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
				gl.depthMask(false);
				gl.depthFunc(gl.LESS);
				twgl.setUniforms(this._programInfo, { u_pass: 2 });
				gl.drawArrays(gl.POINTS, 0, count);
			}
		} else {
			// ---- LEGACY single pass: full soft disc, alpha-over, depth test only (no write). ----
			gl.enable(gl.BLEND);
			gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
			gl.depthFunc(gl.LEQUAL);
			gl.depthMask(false);
			twgl.setUniforms(this._programInfo, { u_pass: 0 });
			gl.drawArrays(gl.POINTS, 0, count);
		}

		// ---- restore prior GL state exactly ----
		gl.bindTexture(gl.TEXTURE_2D, prevTexBinding);
		gl.activeTexture(prevActiveTex);
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArrayBuf);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);
		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
		gl.blendEquationSeparate(prevEqRGB, prevEqAlpha);
		if (prevBlend) { gl.enable(gl.BLEND); } else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (prevCull) { gl.enable(gl.CULL_FACE); } else { gl.disable(gl.CULL_FACE); }
		gl.depthMask(prevDepthMask);
		gl.depthFunc(prevDepthFunc);
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxSurfelSnake.js
//
// Procedural "surfel snake": a tapered 3D tube built from rings of shaded surfels wrapped around an
// animated centerline/spine. It REUSES the motion language of dwGfxLightSerpents (slow yaw wander +
// lateral slither + vertical wave riding faked rolling terrain, driven by a head-position history
// ring) WITHOUT modifying or replacing that effect. Where the light serpent emits additive HDR light
// points down its history path, this snake emits SHADED surface elements (via dwGfxSurfelPointRenderer)
// so the body reads as a continuous, rounded, moon-lit surface going over small hills.
//
// Geometry: the spine is sampled from the head-position history ring at `ringCount` stations from head
// to tail. At each station a stable local frame (tangent / normal / binormal, parallel-transport-free
// but stabilized against a world-up reference) is built, and `pointsPerRing` surfels are placed around
// an ELLIPSE of the local body radius. The body radius follows an ANATOMICAL profile (see _radiusAt):
// rounded snout/head bulb -> short neck -> long nearly-constant torso -> gradual taper to a blunt
// (nonzero) tail. This reads as a snake rather than a cone.
//
// Cross-section: each ring is an ellipse, not a circle -- crossSectionScale = [horizontal, vertical]
// (default [1.0, 0.55]) keeps the full body WIDTH along the level binormal B while reducing vertical
// THICKNESS along the frame normal N, so the body reads flatter/more serpentine. Each surfel's world
// normal is the true ellipse normal, built from the INVERSE semi-axes (ca/aV along N, sa/aH along B) and
// then normalized -- not the circular radial direction, which would light a flattened body as if it were
// still round. Ring spacing uses the ellipse perimeter (Ramanujan) so flattening cannot open gaps.
//
// UVs: each surfel carries a cylindrical albedo UV -- U runs head(0) -> tail(1) along the body, V wraps
// 0..<1 around each ring (seam between the last and first point of a ring). The renderer samples its
// albedo texture once per surfel in the vertex shader; its default 1x1 white fallback makes this a no-op
// until a real skin is supplied, so texturing changes nothing visually by default.
//
// Density (configurable, deterministic rebuild):
//  - surfelCount ~= ringCount * pointsPerRing. Configure either directly (setDensity(ringCount, ppr))
//    or by target (setDensityTarget(n) snaps to the nearest LOD tier). Presets ~100 / 500 / 1000.
//  - a hard clamp (maxSurfels, default 4096) guards the batch; rebuild only happens on config change,
//    never per frame. Per-frame work only rewrites spine samples + frames into the renderer batch.
//  - distance LOD: when auto-LOD is enabled AND no density is force-pinned, the tier is chosen from the
//    camera->head distance among {1000, 500, 250, 100, 32}. forceDensity(target) pins a tier so the
//    user can compare densities visually; setAutoLOD(true) + clearForce() returns to automatic.
//
// Motion parameters mirror dwGfxLightSerpents defaults; only scalar/vector arithmetic (no m4 here).
// Optional emissive eyes are emitted through the existing additive light-point path (drawParticles):
// buildEyeBatch() returns an [px,py,pz,size,r,g,b,a] batch the demo uploads with gfx.drawParticles.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

// Absolute renderer/snake capacity (DW_SURFEL_MAX_CAPACITY) is defined in dwGfxSurfelPointRenderer.js,
// which is always loaded first (own <script> before this file). 131072 = 2^17: above the 100K stress
// preset, a documented power-of-two hard cap. Staging cost at stride 12 floats ~= 6.29 MB (reused).

// Auto-LOD ladder (chosen by camera->head DISTANCE). Deliberately tops out at ~1000: the 10K/100K stress
// presets are reachable only by explicit force (keys 4/5), never auto-selected, so roaming never silently
// spikes to 100K. { target, ringCount, pointsPerRing, sampleStride } -- product ~ the tier label.
const DW_SURFEL_SNAKE_LOD = [
	{ target: 1000, ringCount: 40, pointsPerRing: 25, sampleStride: 3 },  // 1000
	{ target:  500, ringCount: 32, pointsPerRing: 16, sampleStride: 3 },  // 512
	{ target:  250, ringCount: 24, pointsPerRing: 10, sampleStride: 3 },  // 240
	{ target:  100, ringCount: 16, pointsPerRing:  7, sampleStride: 3 },  // 112
	{ target:   32, ringCount:  8, pointsPerRing:  4, sampleStride: 3 },  //  32
];

// Explicit density PRESETS for the numeric keys (1/2/3/4/5 -> ~100/500/1000/10000/100000). High-density
// tiers keep pointsPerRing large enough for a smooth circular cross-section and use a FRACTIONAL
// sampleStride so the body spans a sane number of history frames (a fixed physical length) instead of
// growing into a giant tube as ringCount climbs. Products are exact or near-exact to the label.
const DW_SURFEL_SNAKE_PRESETS = [
	{ target:    100, ringCount:  16, pointsPerRing:   7, sampleStride: 3.0  },  //    112
	{ target:    500, ringCount:  32, pointsPerRing:  16, sampleStride: 3.0  },  //    512
	{ target:   1000, ringCount:  40, pointsPerRing:  25, sampleStride: 3.0  },  //   1000
	{ target:  10000, ringCount: 125, pointsPerRing:  80, sampleStride: 1.2  },  //  10000 (body ~150 frames)
	{ target: 100000, ringCount: 800, pointsPerRing: 125, sampleStride: 0.22 },  // 100000 (body ~176 frames)
];

class dwGfxSurfelSnake
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		this.enabled = (o.enabled !== undefined) ? o.enabled : true;

		// ---- density / clamp ----
		// hard cap on emitted surfels. Defaults to the shared 131072 capacity so the 100K stress preset
		// fits; clamped so a caller can never ask for more than the renderer's staging buffer holds.
		this.maxSurfels	= o.maxSurfels	!== undefined ? Math.min(o.maxSurfels, DW_SURFEL_MAX_CAPACITY)
						: DW_SURFEL_MAX_CAPACITY;
		this.minPointsPerRing = 3;
		// history frames between rings. May be FRACTIONAL (high-density presets) -> _sampleHistory lerps
		// between adjacent frames, so ringCount can climb without the body growing into a giant tube.
		this.sampleStride = o.sampleStride !== undefined ? Math.max(0.05, o.sampleStride) : 3;

		// ---- roam area + heights (mirrors light serpent) ----
		this.center		= o.center		|| [0.0, 0.0, 0.0];
		this.bounds		= o.bounds		|| [8.0, 0.0, 8.0];
		this.baseY		= o.baseY		!== undefined ? o.baseY
						: (o.groundY	!== undefined ? o.groundY		: -2.0);
		this.baseHeight	= o.baseHeight	!== undefined ? o.baseHeight	: 0.9;   // clearance so the tube sits above ground
		this.groundHeightFn = o.groundHeightFn || null;

		// optional deterministic spawn (world [x,z] + heading) so the snake lands in a known, on-screen
		// spot on first load instead of a random point in the roam bounds. null => random respawn.
		this.spawn		= o.spawn		|| null;
		this.spawnYaw	= o.spawnYaw	!== undefined ? o.spawnYaw	: null;

		// ---- motion (mirrors light serpent defaults) ----
		this.speed		= o.speed		!== undefined ? o.speed		: 2.2;
		this.slitherAmp	= o.slitherAmp	!== undefined ? o.slitherAmp	: 0.9;
		this.slitherFreq = o.slitherFreq !== undefined ? o.slitherFreq	: 2.4;
		this.wanderFreq	= o.wanderFreq	!== undefined ? o.wanderFreq	: 0.25;
		this.wanderAmp	= o.wanderAmp	!== undefined ? o.wanderAmp		: 0.5;
		this.vertAmp	= o.vertAmp		!== undefined ? o.vertAmp		: 0.45;
		this.vertFreq	= o.vertFreq	!== undefined ? o.vertFreq		: 1.1;
		this.terrainAmp	= o.terrainAmp	!== undefined ? o.terrainAmp	: 0.6;
		this.terrainScale = o.terrainScale !== undefined ? o.terrainScale : 0.12;

		// ---- body shape (anatomical radius profile, head -> tail) ----------------------------------
		// bodyRadius is the TORSO (mid-body) radius; every other shape knob scales relative to it. The
		// profile is piecewise-smooth so the silhouette reads as a SNAKE, not a cone:
		//   [0 .. headLength]              rounded snout / head bulb (blunt nonzero nose -> headScale peak)
		//   [headLength .. neckLength]     short smooth head -> neck -> torso transition
		//   [neckLength .. tailTaperStart] nearly constant torso girth (neckScale * bodyRadius)
		//   [tailTaperStart .. 1]          gradual tail taper easing to a BLUNT tip (tailRadiusScale of torso)
		this.bodyRadius	= o.bodyRadius	!== undefined ? o.bodyRadius	: 0.55;   // torso (mid-body) radius, world units
		// head bulb size relative to torso. Preserves the previous max head size; back-compat: headRoundScale.
		this.headScale	= o.headScale	!== undefined ? o.headScale
						: (o.headRoundScale !== undefined ? o.headRoundScale : 1.15);
		// torso / neck girth as a fraction of bodyRadius (1.0 = full bodyRadius). The "body scale" knob.
		this.neckScale	= o.neckScale	!== undefined ? o.neckScale		: 1.0;
		// blunt rounded nose radius as a fraction of the head bulb (so the snout is rounded, never a point).
		this.noseRound	= o.noseRound	!== undefined ? o.noseRound		: 0.6;
		this.headLength	= o.headLength	!== undefined ? o.headLength	: 0.10;   // fraction of length: head bulb
		this.neckLength	= o.neckLength	!== undefined ? o.neckLength	: 0.20;   // fraction: end of head->torso neck
		// tail: stays at full torso until tailTaperStart, then eases to tailRadiusScale*torso at the blunt tip.
		this.tailTaperStart	= o.tailTaperStart !== undefined ? o.tailTaperStart : 0.72;  // taper begins late (~72%)
		this.tailRadiusScale = o.tailRadiusScale !== undefined ? o.tailRadiusScale : 0.5;  // blunt tip vs torso (~50%)
		this.tailTaperPower	= o.tailTaperPower !== undefined ? o.tailTaperPower : 1.6;    // ease shape (>1 fuller longer)
		// clamp to safe ranges (no divide-by-zero / inverted / runaway shapes) and keep the segment ordering
		// headLength < neckLength < tailTaperStart intact regardless of what the caller passes.
		this.headScale	= Math.max(0.5, Math.min(3.0, this.headScale));
		this.neckScale	= Math.max(0.1, Math.min(2.0, this.neckScale));
		this.noseRound	= Math.max(0.1, Math.min(1.0, this.noseRound));
		this.headLength	= Math.max(0.02, Math.min(0.40, this.headLength));
		this.neckLength	= Math.max(this.headLength + 0.02, Math.min(0.50, this.neckLength));
		this.tailRadiusScale = Math.max(0.0, Math.min(1.0, this.tailRadiusScale));
		this.tailTaperStart	= Math.max(this.neckLength + 0.02, Math.min(0.95, this.tailTaperStart));
		this.tailTaperPower	= Math.max(0.1, Math.min(8.0, this.tailTaperPower));
		this.surfelOverlap	= o.surfelOverlap !== undefined ? o.surfelOverlap : 2.2; // splat size vs ring spacing (fills gaps)
		this.twist		= o.twist		!== undefined ? o.twist		: 0.0;   // per-ring angular twist (rad)

		// ---- cross-section (ELLIPTICAL ring, so the body reads flatter like a real snake) --------------
		// Each ring is an ellipse in the local frame instead of a circle: the HORIZONTAL semi-axis (along
		// the binormal B, which is always level) is scaled by crossSectionScale[0] and the VERTICAL semi-axis
		// (along the frame normal N, which carries the up component) by crossSectionScale[1]. Defaults keep
		// full body WIDTH (1.0) and reduce vertical THICKNESS to 0.55 -> a flatter, more serpentine body.
		// `verticalRadiusScale` is accepted as a shorthand for just the vertical axis. The longitudinal
		// anatomical profile (_radiusAt) is untouched -- this only reshapes the cross-section.
		const cs = o.crossSectionScale;
		this.horizontalRadiusScale = (cs && cs.length >= 1) ? cs[0]
								: (o.horizontalRadiusScale !== undefined ? o.horizontalRadiusScale : 1.0);
		this.verticalRadiusScale = (cs && cs.length >= 2) ? cs[1]
								: (o.verticalRadiusScale !== undefined ? o.verticalRadiusScale : 0.55);
		// clamp away from 0 so the ellipse can never degenerate to a line (which would break the normals).
		this.horizontalRadiusScale = Math.max(0.05, Math.min(2.0, this.horizontalRadiusScale));
		this.verticalRadiusScale   = Math.max(0.05, Math.min(2.0, this.verticalRadiusScale));

		// ---- appearance ----
		this.bodyColor	= o.bodyColor	|| [0.22, 0.55, 0.35];   // deep green body
		this.bellyColor	= o.bellyColor	|| [0.55, 0.62, 0.40];   // paler underside
		this.bandColor	= o.bandColor	|| [0.12, 0.30, 0.22];   // darker banding
		this.bandFreq	= o.bandFreq	!== undefined ? o.bandFreq		: 14.0;  // bands along body
		this.opacity	= o.opacity		!== undefined ? o.opacity		: 1.0;

		// ---- eyes (emissive, via additive light path) ----
		this.eyeEnabled	= (o.eyeEnabled !== undefined) ? o.eyeEnabled : true;
		this.eyeColor	= o.eyeColor	|| [1.0, 0.85, 0.35];    // amber
		this.eyeIntensity = o.eyeIntensity !== undefined ? o.eyeIntensity : 3.4;  // HDR (survives bloom)
		this.eyeSize	= o.eyeSize		!== undefined ? o.eyeSize		: 0.10;
		this.eyeSpread	= o.eyeSpread	!== undefined ? o.eyeSpread		: 0.45;  // fraction of head radius
		this.eyeForward	= o.eyeForward	!== undefined ? o.eyeForward	: 0.35;  // toward snout

		// ---- LOD control ----
		this.autoLOD	= (o.autoLOD !== undefined) ? o.autoLOD : true;
		this._forced	= (o.forceTarget !== undefined);   // density pinned?
		this._lodTierIndex = -1;

		// ---- head state (mirrors light serpent) ----
		this.hx = 0.0; this.hy = 0.0; this.hz = 0.0;
		this.baseYaw = 0.0;
		this.tSlither = 0.0; this.tVert = 0.0; this.tWander = 0.0;
		this.fade = 0.0;   // 0..1 gentle fade-in

		// fixed scratch vectors (no per-frame allocation).
		this._c = [0.0, 0.0, 0.0];
		this._cN = [0.0, 0.0, 0.0];
		this._cP = [0.0, 0.0, 0.0];
		this._T = [0.0, 0.0, 0.0];
		this._N = [0.0, 0.0, 0.0];
		this._B = [0.0, 0.0, 0.0];

		// eye batch (allocated once): 2 eyes x 8 floats.
		this._eyeBatch = new Float32Array(2 * 8);
		this._eyeCount = 0;

		// initial density (direct config wins; else target; else default preset ~500).
		let rc, ppr, stride = this.sampleStride;
		if (o.ringCount !== undefined || o.pointsPerRing !== undefined) {
			rc = o.ringCount !== undefined ? o.ringCount : 32;
			ppr = o.pointsPerRing !== undefined ? o.pointsPerRing : 16;
			this._forced = true;
		} else {
			const tier = this._tierForTarget(o.forceTarget !== undefined ? o.forceTarget
				: (o.surfelCount !== undefined ? o.surfelCount : 500));
			rc = tier.ringCount; ppr = tier.pointsPerRing; stride = tier.sampleStride;
		}
		this.ringCount = 0; this.pointsPerRing = 0; this.histLen = 0;
		this.histX = null; this.histY = null; this.histZ = null;
		this.histHead = 0; this.histCount = 0;
		this.setDensity(rc, ppr, stride);   // allocates history ring + primes spine

		this._respawn();
	}

	// --- density -------------------------------------------------------------------------------------

	// snap a total-surfel target to the nearest density PRESET (100/500/1000/10000/100000).
	_tierForTarget(target)
	{
		let best = DW_SURFEL_SNAKE_PRESETS[0], bestD = Infinity;
		for (let i = 0; i < DW_SURFEL_SNAKE_PRESETS.length; i++) {
			const d = Math.abs(DW_SURFEL_SNAKE_PRESETS[i].target - target);
			if (d < bestD) { bestD = d; best = DW_SURFEL_SNAKE_PRESETS[i]; }
		}
		return best;
	}

	// deterministic rebuild: set ring/point counts (+ optional history stride), clamp to the surfel cap,
	// (re)allocate the history ring ONLY when its length changes, and preserve the live spine across the
	// change (no respawn / no phase reset) so a density switch never visually restarts the snake. No
	// per-frame allocation happens here -- this runs only on an actual density change.
	setDensity(ringCount, pointsPerRing, sampleStride)
	{
		let rc = ringCount | 0;
		let ppr = pointsPerRing | 0;
		let stride = (sampleStride !== undefined) ? Math.max(0.05, sampleStride) : this.sampleStride;
		if (rc < 2) { rc = 2; }
		if (ppr < this.minPointsPerRing) { ppr = this.minPointsPerRing; }
		// clamp product to the hard cap (shed points-per-ring first, then rings).
		if (rc * ppr > this.maxSurfels) {
			ppr = Math.max(this.minPointsPerRing, Math.floor(this.maxSurfels / rc));
			if (rc * ppr > this.maxSurfels) {
				rc = Math.max(2, Math.floor(this.maxSurfels / ppr));
			}
		}
		if (rc === this.ringCount && ppr === this.pointsPerRing && stride === this.sampleStride && this.histX) {
			return this;   // no change -> no rebuild, history untouched.
		}
		this.ringCount = rc;
		this.pointsPerRing = ppr;
		this.sampleStride = stride;

		// history ring long enough to cover the whole body (max back index) plus a small pad.
		const need = Math.ceil(this.ringCount * this.sampleStride) + 4;
		if (!this.histX) {
			// fresh construction: allocate + prime to the current head position.
			this.histLen = need;
			this.histX = new Float32Array(this.histLen);
			this.histY = new Float32Array(this.histLen);
			this.histZ = new Float32Array(this.histLen);
			this._primeHistory();
		} else if (need !== this.histLen) {
			// density changed the buffer length: RESAMPLE the existing spine into the new buffer so the
			// head position, heading, and body shape carry over continuously (no flatten / no respawn).
			this._resampleHistory(need);
		}
		// same-length change (e.g. only pointsPerRing): keep the existing history verbatim -> no visible reset.
		return this;
	}

	// Preserve the current spine when the history buffer is resized. Extracts existing samples newest-first,
	// then writes them into a fresh linear buffer with the newest sample at the end (matching the ring
	// convention histHead=0 => index len-1 is the most recent). Growing pads the older tail with the oldest
	// available sample; shrinking keeps the most recent `newLen` samples. Runs only on a density change.
	_resampleHistory(newLen)
	{
		const oldCount = this.histCount > 0 ? this.histCount : 1;
		const tmpX = new Float32Array(oldCount);
		const tmpY = new Float32Array(oldCount);
		const tmpZ = new Float32Array(oldCount);
		for (let b = 0; b < oldCount; b++) {   // b=0 newest
			const idx = ((this.histHead - 1 - b) % this.histLen + this.histLen) % this.histLen;
			tmpX[b] = this.histX[idx]; tmpY[b] = this.histY[idx]; tmpZ[b] = this.histZ[idx];
		}
		const nx = new Float32Array(newLen);
		const ny = new Float32Array(newLen);
		const nz = new Float32Array(newLen);
		for (let k = 0; k < newLen; k++) {
			const age = newLen - 1 - k;                       // 0 at the newest (index newLen-1)
			const src = age < oldCount ? age : oldCount - 1;  // pad older entries with the oldest sample
			nx[k] = tmpX[src]; ny[k] = tmpY[src]; nz[k] = tmpZ[src];
		}
		this.histX = nx; this.histY = ny; this.histZ = nz;
		this.histLen = newLen;
		this.histHead = 0;          // next write overwrites the oldest (index 0); newest stays at len-1
		this.histCount = newLen;
	}

	setDensityTarget(target)
	{
		const t = this._tierForTarget(target);
		return this.setDensity(t.ringCount, t.pointsPerRing, t.sampleStride);
	}

	// pin a density tier (disables auto-LOD selection until cleared) so densities can be compared.
	forceDensity(target)
	{
		this._forced = true;
		this._lodTierIndex = -1;
		return this.setDensityTarget(target);
	}

	clearForce()
	{
		this._forced = false;
		this._lodTierIndex = -1;
		return this;
	}

	setAutoLOD(on)
	{
		this.autoLOD = !!on;
		return this;
	}

	surfelCount()
	{
		return this.ringCount * this.pointsPerRing;
	}

	// --- motion (mirrors dwGfxLightSerpents) ---------------------------------------------------------

	_rand(a, b) { return a + Math.random() * (b - a); }

	_groundAt(x, z)
	{
		if (this.groundHeightFn) {
			return this.groundHeightFn(x, z);
		}
		return this.baseY + this.terrainAmp * 0.5 *
			(Math.sin(x * this.terrainScale) + Math.cos(z * this.terrainScale * 1.3));
	}

	_respawn()
	{
		if (this.spawn) {
			this.hx = this.spawn[0];
			this.hz = this.spawn[1];
			this.baseYaw = (this.spawnYaw !== null) ? this.spawnYaw : 0.0;
		} else {
			this.hx = this.center[0] + this._rand(-this.bounds[0], this.bounds[0]);
			this.hz = this.center[2] + this._rand(-this.bounds[2], this.bounds[2]);
			this.baseYaw = this._rand(0.0, Math.PI * 2.0);
		}
		this.hy = this._groundAt(this.hx, this.hz) + this.baseHeight;
		this.tSlither = this._rand(0.0, Math.PI * 2.0);
		this.tVert = this._rand(0.0, Math.PI * 2.0);
		this.tWander = this._rand(0.0, Math.PI * 2.0);
		this.fade = 0.0;
		this._primeHistory();
	}

	_primeHistory()
	{
		if (!this.histX) { return; }
		for (let k = 0; k < this.histLen; k++) {
			this.histX[k] = this.hx;
			this.histY[k] = this.hy;
			this.histZ[k] = this.hz;
		}
		this.histHead = 0;
		this.histCount = this.histLen;
	}

	_pushHistory()
	{
		const h = this.histHead;
		this.histX[h] = this.hx;
		this.histY[h] = this.hy;
		this.histZ[h] = this.hz;
		this.histHead = (h + 1) % this.histLen;
		if (this.histCount < this.histLen) { this.histCount++; }
	}

	_advanceHead(dt)
	{
		this.tSlither += dt;
		this.tVert += dt;
		this.tWander += dt;

		this.baseYaw += this.wanderAmp * this.wanderFreq * Math.cos(this.tWander * this.wanderFreq) * dt;

		if (Math.abs(this.hx - this.center[0]) > this.bounds[0] ||
			Math.abs(this.hz - this.center[2]) > this.bounds[2]) {
			const toC = Math.atan2(this.center[0] - this.hx, this.center[2] - this.hz);
			let d = toC - this.baseYaw;
			while (d > Math.PI) d -= Math.PI * 2.0;
			while (d < -Math.PI) d += Math.PI * 2.0;
			this.baseYaw += d * Math.min(1.0, dt * 1.5);
		}

		const yaw = this.baseYaw + this.slitherAmp * Math.sin(this.tSlither * this.slitherFreq);
		const fx = Math.sin(yaw), fz = Math.cos(yaw);
		this.hx += fx * this.speed * dt;
		this.hz += fz * this.speed * dt;

		const ground = this._groundAt(this.hx, this.hz);
		this.hy = ground + this.baseHeight + this.vertAmp * Math.sin(this.tVert * this.vertFreq);

		this._pushHistory();
	}

	// simulation only (no GPU work). Call from the demo update(dt).
	update(dt)
	{
		if (!this.enabled || !(dt > 0.0)) {
			return;
		}
		this._advanceHead(dt);
		this.fade = Math.min(1.0, this.fade + dt / 1.2);
	}

	// sample the head-history ring `back` frames behind the head into out[0..2]. `back` may be FRACTIONAL:
	// the two bracketing integer frames are linearly interpolated so many rings can be packed between a
	// small number of stored frames (fractional sampleStride) without stepping/aliasing. Integer `back`
	// (the low-density presets) yields the exact stored frame (interp weight 0) -> unchanged behavior.
	_sampleHistory(back, out)
	{
		let b = back;
		const maxB = this.histLen - 1;
		if (b < 0) { b = 0; }
		if (b > maxB) { b = maxB; }
		const b0 = Math.floor(b);
		const f = b - b0;
		const b1 = b0 < maxB ? b0 + 1 : b0;
		const i0 = ((this.histHead - 1 - b0) % this.histLen + this.histLen) % this.histLen;
		const i1 = ((this.histHead - 1 - b1) % this.histLen + this.histLen) % this.histLen;
		out[0] = this.histX[i0] + (this.histX[i1] - this.histX[i0]) * f;
		out[1] = this.histY[i0] + (this.histY[i1] - this.histY[i0]) * f;
		out[2] = this.histZ[i0] + (this.histZ[i1] - this.histZ[i0]) * f;
	}

	// distance-based LOD: pick a tier from the camera->head distance unless density is force-pinned.
	// cameraPos may be null (skips LOD). Returns true if the density changed (rebuild happened).
	applyLOD(cameraPos)
	{
		if (this._forced || !this.autoLOD || !cameraPos) {
			return false;
		}
		const dx = this.hx - cameraPos[0], dy = this.hy - cameraPos[1], dz = this.hz - cameraPos[2];
		const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
		// near -> high tier. thresholds tuned for the demo camera (~10 units out).
		let idx;
		if (dist < 6.0) { idx = 0; }        // 1000
		else if (dist < 12.0) { idx = 1; }  // 500
		else if (dist < 20.0) { idx = 2; }  // 250
		else if (dist < 32.0) { idx = 3; }  // 100
		else { idx = 4; }                   // 32
		if (idx === this._lodTierIndex) {
			return false;
		}
		this._lodTierIndex = idx;
		const tier = DW_SURFEL_SNAKE_LOD[idx];
		const before = this.ringCount * 1000 + this.pointsPerRing;
		// setDensity resamples the live spine (no respawn), so an auto-LOD tier change is continuous too.
		this.setDensity(tier.ringCount, tier.pointsPerRing, tier.sampleStride);
		return before !== (this.ringCount * 1000 + this.pointsPerRing);
	}

	// --- geometry ------------------------------------------------------------------------------------

	_norm(v)
	{
		const l = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
		if (l > 1e-6) { v[0] /= l; v[1] /= l; v[2] /= l; }
		else { v[0] = 0.0; v[1] = 0.0; v[2] = 1.0; }
	}

	// smoothstep 0..1 (C1 continuous ease used to keep every profile segment from reading as a straight cone).
	_smooth01(x)
	{
		x = x < 0.0 ? 0.0 : (x > 1.0 ? 1.0 : x);
		return x * x * (3.0 - 2.0 * x);
	}

	// max head-bulb radius (world units). Eyes key off this (not _radiusAt(0)) so rounding the snout never
	// moves the eyes; with the default headScale this equals the previous head radius exactly.
	_headRadius()
	{
		return this.bodyRadius * this.headScale;
	}

	// anatomical body radius along t (0 head .. 1 tail): a rounded snout/head bulb, a short neck transition,
	// a long NEARLY-CONSTANT torso, then a gradual tail taper to a BLUNT (nonzero) tip. Deliberately not a
	// straight cone. Returns world units. Every denominator below is guaranteed > 0 by the constructor clamps.
	_radiusAt(t)
	{
		t = t < 0.0 ? 0.0 : (t > 1.0 ? 1.0 : t);
		const head = this.headScale;            // head bulb peak (x bodyRadius)
		const torso = this.neckScale;           // constant torso girth (x bodyRadius)
		const nose = this.noseRound * head;     // blunt rounded nose (x bodyRadius)
		let scale;
		if (t <= this.headLength) {
			// rounded snout: blunt nose swells up to the head bulb peak.
			scale = nose + (head - nose) * this._smooth01(t / this.headLength);
		} else if (t <= this.neckLength) {
			// short smooth head -> torso transition (the neck).
			scale = head + (torso - head) *
				this._smooth01((t - this.headLength) / (this.neckLength - this.headLength));
		} else if (t <= this.tailTaperStart) {
			// nearly constant torso girth.
			scale = torso;
		} else {
			// gradual tail taper easing to a blunt tip = tailRadiusScale of the torso girth.
			const u = (t - this.tailTaperStart) / (1.0 - this.tailTaperStart);
			const ease = Math.pow(this._smooth01(u), this.tailTaperPower);
			const tip = torso * this.tailRadiusScale;
			scale = torso + (tip - torso) * ease;
		}
		return this.bodyRadius * scale;
	}

	// Build the tube: append shaded surfels (rings around the spine) into the given surfel renderer.
	// fogParams may be null. Returns the number of surfels appended.
	appendSurfels(surfelRenderer, fogParams)
	{
		if (!this.enabled || !surfelRenderer) {
			return 0;
		}
		const seg = this.ringCount;
		const ppr = this.pointsPerRing;
		const stride = this.sampleStride;
		const up = 0, up1 = 1, up2 = 0;   // world up reference (0,1,0)
		const c = this._c, cN = this._cN, cP = this._cP;
		const T = this._T, N = this._N, B = this._B;
		const fadeA = this.opacity * this.fade;
		let appended = 0;

		for (let i = 0; i < seg; i++)
		{
			const t = seg > 1 ? i / (seg - 1) : 0.0;   // 0 head .. 1 tail
			const back = i * stride;

			this._sampleHistory(back, c);
			// tangent from neighboring stations (central difference where possible).
			this._sampleHistory(back - stride < 0 ? 0 : back - stride, cN);   // toward head
			this._sampleHistory(back + stride, cP);                            // toward tail
			T[0] = cN[0] - cP[0]; T[1] = cN[1] - cP[1]; T[2] = cN[2] - cP[2];
			this._norm(T);

			// stable frame: B = normalize(T x up); N = B x T. Guard T ~parallel to up.
			B[0] = T[1] * up2 - T[2] * up1;
			B[1] = T[2] * up  - T[0] * up2;
			B[2] = T[0] * up1 - T[1] * up;
			if (B[0] * B[0] + B[1] * B[1] + B[2] * B[2] < 1e-6) {
				// T parallel to up -> use world +X as the reference instead.
				B[0] = T[1] * 0.0 - T[2] * 0.0;
				B[1] = T[2] * 1.0 - T[0] * 0.0;
				B[2] = T[0] * 0.0 - T[1] * 1.0;
			}
			this._norm(B);
			N[0] = B[1] * T[2] - B[2] * T[1];
			N[1] = B[2] * T[0] - B[0] * T[2];
			N[2] = B[0] * T[1] - B[1] * T[0];
			this._norm(N);

			const radius = this._radiusAt(t);
			// elliptical semi-axes: aH along the level binormal B (width), aV along N (thickness).
			const aH = radius * this.horizontalRadiusScale;
			const aV = radius * this.verticalRadiusScale;
			// splat size scaled so adjacent surfels overlap and fill the ring (no gaps at low density).
			// Ellipse perimeter via Ramanujan's approximation, so flattening the body cannot open gaps
			// (a circle's 2*PI*r would under-estimate the spacing for an eccentric ring).
			const ringPerimeter = Math.PI * (3.0 * (aH + aV) -
								Math.sqrt((3.0 * aH + aV) * (aH + 3.0 * aV)));
			const ringSpacing = ringPerimeter / ppr;   // circumferential gap within the ring
			// longitudinal gap to the next ring (toward the tail): as the radius shrinks the circumferential
			// gap gets small, but the spine spacing stays ~constant, so floor the splat to bridge whichever
			// neighbor gap is larger -> tail coverage stays continuous without collapsing to specks. The
			// longitudinal term is halved so a wide ring spacing never blows the splat up into giant overlaps.
			const dxl = c[0] - cP[0], dyl = c[1] - cP[1], dzl = c[2] - cP[2];
			const longSpacing = Math.sqrt(dxl * dxl + dyl * dyl + dzl * dzl);
			const cover = Math.max(ringSpacing, 0.5 * longSpacing);
			const size = Math.max(0.02, cover * this.surfelOverlap);

			// longitudinal band factor for subtle markings.
			const band = 0.5 + 0.5 * Math.sin(t * this.bandFreq);
			const twist = this.twist * t;

			for (let j = 0; j < ppr; j++)
			{
				const vAround = j / ppr;   // V wraps 0 .. <1 around the ring (seam between j=ppr-1 and j=0)
				const ang = vAround * Math.PI * 2.0 + twist;
				const ca = Math.cos(ang), sa = Math.sin(ang);
				// ELLIPSE position: ca scales the vertical (N) axis, sa the horizontal (B) axis.
				const px = c[0] + (ca * aV) * N[0] + (sa * aH) * B[0];
				const py = c[1] + (ca * aV) * N[1] + (sa * aH) * B[1];
				const pz = c[2] + (ca * aV) * N[2] + (sa * aH) * B[2];

				// ELLIPSE normal: the surface normal of (n/aV)^2 + (b/aH)^2 = 1 is the gradient, which uses
				// the INVERSE semi-axes -- (ca/aV, sa/aH) -- NOT the circular radial direction (ca, sa).
				// Copying the circular radial would light a flattened body as if it were still round.
				let nN = ca / aV, nB = sa / aH;
				const nl = Math.sqrt(nN * nN + nB * nB) || 1.0;
				nN /= nl; nB /= nl;
				const ox = nN * N[0] + nB * B[0];
				const oy = nN * N[1] + nB * B[1];
				const oz = nN * N[2] + nB * B[2];

				// belly (facing down) is paler; back is body color; darker bands modulate.
				const downMix = Math.max(0.0, -oy) * 0.6;       // 0 back .. up to 0.6 belly
				const bandMix = band * 0.35;
				let cr = this.bodyColor[0] * (1.0 - bandMix) + this.bandColor[0] * bandMix;
				let cg = this.bodyColor[1] * (1.0 - bandMix) + this.bandColor[1] * bandMix;
				let cb = this.bodyColor[2] * (1.0 - bandMix) + this.bandColor[2] * bandMix;
				cr = cr * (1.0 - downMix) + this.bellyColor[0] * downMix;
				cg = cg * (1.0 - downMix) + this.bellyColor[1] * downMix;
				cb = cb * (1.0 - downMix) + this.bellyColor[2] * downMix;

				// cylindrical UV: U runs head(0) -> tail(1) along the body, V wraps around the ring.
				const uAlong = t;

				if (fogParams) {
					if (surfelRenderer.pushFogged(px, py, pz, size, ox, oy, oz, cr, cg, cb, fadeA,
							fogParams, uAlong, vAround)) {
						appended++;
					} else {
						return appended;   // renderer cap reached.
					}
				} else {
					if (surfelRenderer.push(px, py, pz, size, ox, oy, oz, cr, cg, cb, fadeA,
							uAlong, vAround)) {
						appended++;
					} else {
						return appended;
					}
				}
			}
		}
		return appended;
	}

	// Build the emissive eye batch for the existing additive light path (gfx.drawParticles).
	// Returns { data, count } with stride-8 points, or count 0 when eyes are disabled/hidden.
	buildEyeBatch()
	{
		this._eyeCount = 0;
		if (!this.eyeEnabled || !this.enabled || this.fade <= 0.001) {
			return { data: this._eyeBatch, count: 0 };
		}
		// head frame: use the most recent samples.
		const c = this._c, cN = this._cN, cP = this._cP, T = this._T, N = this._N, B = this._B;
		const stride = this.sampleStride;
		this._sampleHistory(0, c);
		this._sampleHistory(0, cN);
		this._sampleHistory(stride, cP);
		T[0] = cN[0] - cP[0]; T[1] = cN[1] - cP[1]; T[2] = cN[2] - cP[2];
		this._norm(T);
		B[0] = T[1] * 0.0 - T[2] * 1.0;
		B[1] = T[2] * 0.0 - T[0] * 0.0;
		B[2] = T[0] * 1.0 - T[1] * 0.0;
		if (B[0] * B[0] + B[1] * B[1] + B[2] * B[2] < 1e-6) { B[0] = 1.0; B[1] = 0.0; B[2] = 0.0; }
		this._norm(B);
		N[0] = B[1] * T[2] - B[2] * T[1];
		N[1] = B[2] * T[0] - B[0] * T[2];
		N[2] = B[0] * T[1] - B[1] * T[0];
		this._norm(N);

		const headR = this._headRadius();
		const spread = headR * this.eyeSpread;
		const fwd = headR * this.eyeForward;
		const up = 0.35 * headR;   // eyes sit slightly above the spine
		const inten = this.eyeIntensity;
		const cr = this.eyeColor[0] * inten, cg = this.eyeColor[1] * inten, cb = this.eyeColor[2] * inten;
		const a = this.fade;

		for (let e = 0; e < 2; e++)
		{
			const s = (e === 0) ? -1.0 : 1.0;
			const px = c[0] + T[0] * fwd + B[0] * s * spread + N[0] * up;
			const py = c[1] + T[1] * fwd + B[1] * s * spread + N[1] * up;
			const pz = c[2] + T[2] * fwd + B[2] * s * spread + N[2] * up;
			const o = e * 8;
			this._eyeBatch[o + 0] = px;
			this._eyeBatch[o + 1] = py;
			this._eyeBatch[o + 2] = pz;
			this._eyeBatch[o + 3] = this.eyeSize;
			this._eyeBatch[o + 4] = cr;
			this._eyeBatch[o + 5] = cg;
			this._eyeBatch[o + 6] = cb;
			this._eyeBatch[o + 7] = a;
		}
		this._eyeCount = 2;
		return { data: this._eyeBatch, count: this._eyeCount };
	}

	activeCount()
	{
		return this.enabled ? 1 : 0;
	}
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxUmbralDeer.js
//
// "Colored umbral creature" prototype: ONE calm animated umbral deer standing on the fog ground,
// positioned separately from the owl. Its body is a hierarchical rig of soft DARK point-sprites
// (drawn by dwGfxUmbralPointRenderer, which multiplicatively darkens + chromatically tints the HDR
// scene after the fog composite). Its two eyes and antler tips are ordinary emissive HDR light
// points (drawn through the existing gfx.drawParticles path) so they keep bloom.
//
// State sequence:
//   DELAY (hidden) -> EYES_ANTLER (eyes + antler-tip accents fade in) -> BODY_REVEAL (body/neck/
//   head/legs umbral silhouette resolves) -> IDLE (breathing + slow head turn) -> WALK (a few
//   cautious steps) -> BOUND (short spring away) -> FADE (body dissolves into fog) -> DELAY (respawn
//   after a delay).
//
// Only scalar/vector rig math is used (headings, local frame, lerps); no matrix work. Configurable
// anchor / scale / tint / strength / timing / walk path. Ground baseline default -2.0 with an
// optional absolute-world-Y groundHeightFn(x,z) hook (used verbatim, matching the serpent/frog
// convention). Pooled/preallocated arrays, hard point cap, no per-frame allocation.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

// deer umbral rig points: 3 body + 1 neck + 2 head + 4 legs + 1 tail + 2 ears + 6 antlers = 19.
const DW_DEER_RIG = 19;

// state machine phases.
const DW_DEER_DELAY			= 0;
const DW_DEER_EYES_ANTLER	= 1;
const DW_DEER_BODY_REVEAL	= 2;
const DW_DEER_IDLE			= 3;
const DW_DEER_WALK			= 4;
const DW_DEER_BOUND			= 5;
const DW_DEER_FADE			= 6;

const DW_DEER_STATE_NAMES = [
	"DELAY", "EYES_ANTLER", "BODY_REVEAL", "IDLE", "WALK", "BOUND", "FADE",
];

class dwGfxUmbralDeer
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- placement / scale ----
		this.anchor		= o.anchor		|| [2.5, -2.0, -5.5];   // separate from the owl, on the lit ground fog
		this.spawnJitter = o.spawnJitter !== undefined ? o.spawnJitter : 2.0;
		this.scale		= o.scale		!== undefined ? o.scale		: 1.4;
		this.groundY	= o.groundY		!== undefined ? o.groundY
						: (o.baseY		!== undefined ? o.baseY		: -2.0);
		this.groundHeightFn = o.groundHeightFn || null;   // (x,z) -> ABSOLUTE world Y (verbatim)

		// ---- umbral (dark, multiplicative) material ----
		this.umbralColor	= o.umbralColor		|| [0.18, 0.34, 0.52];   // restrained cool teal-blue
		this.umbralStrength	= o.umbralStrength	!== undefined ? o.umbralStrength : 0.85;
		this.umbralSize		= o.umbralSize		!== undefined ? o.umbralSize	: 0.8;

		// ---- emissive eyes / antler tips (HDR light points) ----
		this.eyeColor		= o.eyeColor		|| [0.55, 0.85, 1.00];   // cool ice-blue
		this.eyeIntensity	= o.eyeIntensity	!== undefined ? o.eyeIntensity	: 3.2;
		this.eyeSize		= o.eyeSize			!== undefined ? o.eyeSize		: 0.09;
		this.eyeSpread		= o.eyeSpread		!== undefined ? o.eyeSpread		: 0.12;
		this.antlerColor	= o.antlerColor		|| [0.70, 0.90, 1.00];   // faint ice-blue tips
		this.antlerIntensity = o.antlerIntensity !== undefined ? o.antlerIntensity : 1.8;
		this.antlerSize		= o.antlerSize		!== undefined ? o.antlerSize	: 0.06;

		// ---- matte body/structure layer (non-glowing alpha-over points; below bloom threshold) ----
		// A restrained solid-but-soft material layer that reads over/with the dark umbral silhouette.
		this.matteEnabled	= (o.matteEnabled !== undefined) ? o.matteEnabled : true;
		this.matteColor		= o.matteColor		|| [0.30, 0.52, 0.68];   // cool cyan-blue rim (below bloom)
		this.matteOpacity	= o.matteOpacity	!== undefined ? o.matteOpacity	: 0.50;  // base alpha (readable)
		this.matteSize		= o.matteSize		!== undefined ? o.matteSize		: 0.50;  // world units (base)
		this.matteAlphaMax	= o.matteAlphaMax	!== undefined ? o.matteAlphaMax	: 0.85;  // per-point alpha clamp
		this.breathRate		= o.breathRate		!== undefined ? o.breathRate	: 1.0;   // breathing modulation rate mult
		this.breathAmount	= o.breathAmount	!== undefined ? o.breathAmount	: 0.18;  // size/opacity breathing depth
		this.motionGlow		= o.motionGlow		!== undefined ? o.motionGlow	: 0.6;   // brightening per unit rig speed
		this.actionPulse	= o.actionPulse		!== undefined ? o.actionPulse	: 0.7;   // extra brightening on bound/land
		this.pulseDecay		= o.pulseDecay		!== undefined ? o.pulseDecay	: 1.4;   // action-pulse decay (seconds)

		// ---- walk / bound path (deer yaw-frame offsets) ----
		this.walkForward = o.walkForward !== undefined ? o.walkForward	: 2.4;
		this.boundForward = o.boundForward !== undefined ? o.boundForward : 3.5;
		this.boundRise	= o.boundRise	!== undefined ? o.boundRise		: 1.2;
		this.stepAmp	= o.stepAmp		!== undefined ? o.stepAmp		: 0.12;   // leg swing
		this.stepFreq	= o.stepFreq	!== undefined ? o.stepFreq		: 3.2;

		// ---- idle breathing + head turn + blink ----
		this.breatheAmp	= o.breatheAmp	!== undefined ? o.breatheAmp	: 0.03;
		this.breatheFreq = o.breatheFreq !== undefined ? o.breatheFreq	: 1.1;
		this.headTurnAmp = o.headTurnAmp !== undefined ? o.headTurnAmp	: 0.35;
		this.headTurnFreq = o.headTurnFreq !== undefined ? o.headTurnFreq : 0.45;
		this.blinkMin	= o.blinkMin	!== undefined ? o.blinkMin		: 2.0;
		this.blinkMax	= o.blinkMax	!== undefined ? o.blinkMax		: 5.0;
		this.blinkTime	= o.blinkTime	!== undefined ? o.blinkTime		: 0.13;

		// ---- lifecycle timing (seconds) ----
		this.delayMin	= o.delayMin	!== undefined ? o.delayMin		: 3.0;
		this.delayMax	= o.delayMax	!== undefined ? o.delayMax		: 7.0;
		this.eyeInTime	= o.eyeInTime	!== undefined ? o.eyeInTime		: 1.0;
		this.revealTime	= o.revealTime	!== undefined ? o.revealTime	: 1.3;
		this.idleMin	= o.idleMin		!== undefined ? o.idleMin		: 2.5;
		this.idleMax	= o.idleMax		!== undefined ? o.idleMax		: 5.0;
		this.walkTime	= o.walkTime	!== undefined ? o.walkTime		: 2.2;
		this.boundTime	= o.boundTime	!== undefined ? o.boundTime		: 0.9;
		this.fadeTime	= o.fadeTime	!== undefined ? o.fadeTime		: 1.2;

		this.enabled = (o.enabled !== undefined) ? o.enabled : true;

		// ---- runtime state ----
		this.st = DW_DEER_DELAY;
		this.stTimer = this._rand(this.delayMin, this.delayMax);
		this.reveal = 0.0;       // body umbral strength ramp 0..1
		this.eyeReveal = 0.0;    // eye + antler emissive ramp 0..1
		this.yaw = 0.0;
		this.stepPhase = 0.0;
		this.breatheClock = this._rand(0.0, Math.PI * 2.0);
		this.headClock = this._rand(0.0, Math.PI * 2.0);
		this.blinkTimer = this._rand(this.blinkMin, this.blinkMax);
		this.blinking = 0.0;
		this.px = this.anchor[0]; this.py = this.anchor[1]; this.pz = this.anchor[2];

		// matte-layer motion tracking + action pulse.
		this.prevPx = this.px; this.prevPy = this.py; this.prevPz = this.pz;
		this.motion = 0.0;   // smoothed rig speed (world units / s)
		this.pulse = 0.0;    // action pulse envelope 0..1 (spikes on bound/land)

		// phase interpolation endpoints.
		this.pStart = [0, 0, 0];
		this.pEnd = [0, 0, 0];
		this.phaseDur = 1.0;

		// preallocated emissive batch: 2 eyes + up to 6 antler tips.
		this.emissive = new Float32Array((2 + 6) * 8);
		this.emissiveCount = 0;

		this._pickAnchor();
	}

	_rand(a, b) { return a + Math.random() * (b - a); }
	_ease(t) { t = t < 0 ? 0 : (t > 1 ? 1 : t); return t * t * (3.0 - 2.0 * t); }

	// absolute world ground Y under (x,z): hook verbatim, else flat baseline.
	_groundAt(x, z)
	{
		return this.groundHeightFn ? this.groundHeightFn(x, z) : this.groundY;
	}

	_pickAnchor()
	{
		const j = this.spawnJitter;
		this.px = this.anchor[0] + this._rand(-j, j);
		this.pz = this.anchor[2] + this._rand(-j, j);
		this.py = this._groundAt(this.px, this.pz);
		this.yaw = this._rand(0.0, Math.PI * 2.0);
	}

	_setPhase(ex, ez, dur)
	{
		this.pStart[0] = this.px; this.pStart[1] = this.py; this.pStart[2] = this.pz;
		this.pEnd[0] = ex; this.pEnd[2] = ez;
		this.pEnd[1] = this._groundAt(ex, ez);
		this.phaseDur = dur > 1e-4 ? dur : 1e-4;
	}

	// advance ground-locked position along the active phase using eased progress from stTimer.
	// optional vertical hop (bound) is added on top of the ground-following interpolation.
	_advancePhase(hop)
	{
		const t = this._ease(1.0 - this.stTimer / this.phaseDur);
		this.px = this.pStart[0] + (this.pEnd[0] - this.pStart[0]) * t;
		this.pz = this.pStart[2] + (this.pEnd[2] - this.pStart[2]) * t;
		const gy = this._groundAt(this.px, this.pz);
		const arc = hop ? Math.sin(t * Math.PI) * this.boundRise : 0.0;
		this.py = gy + arc;
	}

	update(dt)
	{
		if (!(dt > 0.0)) { return; }

		// blink clock (eyes only).
		if (this.blinking > 0.0) {
			this.blinking -= dt;
		} else {
			this.blinkTimer -= dt;
			if (this.blinkTimer <= 0.0) {
				this.blinking = this.blinkTime;
				this.blinkTimer = this._rand(this.blinkMin, this.blinkMax);
			}
		}
		this.breatheClock += dt * this.breatheFreq;
		this.headClock += dt * this.headTurnFreq;

		switch (this.st)
		{
			case DW_DEER_DELAY:
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					this._pickAnchor();
					this.reveal = 0.0; this.eyeReveal = 0.0;
					this.st = DW_DEER_EYES_ANTLER;
				}
				break;

			case DW_DEER_EYES_ANTLER:
				this.eyeReveal = Math.min(1.0, this.eyeReveal + dt / this.eyeInTime);
				if (this.eyeReveal >= 1.0) { this.st = DW_DEER_BODY_REVEAL; }
				break;

			case DW_DEER_BODY_REVEAL:
				this.reveal = Math.min(1.0, this.reveal + dt / this.revealTime);
				if (this.reveal >= 1.0) {
					this.st = DW_DEER_IDLE;
					this.stTimer = this._rand(this.idleMin, this.idleMax);
				}
				break;

			case DW_DEER_IDLE:
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					// walk: a few cautious steps forward in the current heading.
					const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);
					this._setPhase(this.px + fx * this.walkForward, this.pz + fz * this.walkForward, this.walkTime);
					this.st = DW_DEER_WALK;
					this.stTimer = this.walkTime;
				}
				break;

			case DW_DEER_WALK:
				this._advancePhase(false);
				this.stepPhase += dt * this.stepFreq;
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					// bound: short spring away (forward + arc up). Action pulse spikes at launch.
					const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);
					this._setPhase(this.px + fx * this.boundForward, this.pz + fz * this.boundForward, this.boundTime);
					this.st = DW_DEER_BOUND;
					this.stTimer = this.boundTime;
					this.pulse = 1.0;
				}
				break;

			case DW_DEER_BOUND:
				this._advancePhase(true);
				this.stepPhase += dt * this.stepFreq * 1.6;
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					this.st = DW_DEER_FADE;
					this.stTimer = this.fadeTime;
					this.pulse = Math.max(this.pulse, 0.8);   // landing thump
				}
				break;

			case DW_DEER_FADE:
				this.reveal = Math.max(0.0, this.reveal - dt / this.fadeTime);
				this.eyeReveal = Math.max(0.0, this.eyeReveal - dt / this.fadeTime);
				this.stTimer -= dt;
				if (this.stTimer <= 0.0 || (this.reveal <= 0.0 && this.eyeReveal <= 0.0)) {
					this.reveal = 0.0; this.eyeReveal = 0.0;
					this.st = DW_DEER_DELAY;
					this.stTimer = this._rand(this.delayMin, this.delayMax);
				}
				break;
		}

		// matte-layer motion tracking: smoothed rig speed drives motion brightening; action pulse decays.
		const vx = (this.px - this.prevPx) / dt;
		const vy = (this.py - this.prevPy) / dt;
		const vz = (this.pz - this.prevPz) / dt;
		const speed = Math.sqrt(vx * vx + vy * vy + vz * vz);
		this.motion += (speed - this.motion) * Math.min(1.0, dt * 6.0);   // exponential smoothing
		this.prevPx = this.px; this.prevPy = this.py; this.prevPz = this.pz;
		if (this.pulse > 0.0) { this.pulse = Math.max(0.0, this.pulse - dt / this.pulseDecay); }
	}

	// current head-cluster world position (with idle head turn + breathing applied), into out[0..2].
	// returns nothing; also stores the head-turn lateral offset for eye placement.
	_headPos(out, rx, rz, fx, fz)
	{
		const s = this.scale;
		const breathe = Math.sin(this.breatheClock) * this.breatheAmp * s;
		const turn = Math.sin(this.headClock) * this.headTurnAmp;   // lateral head sway
		// neck leans forward; head sits ahead + up of the shoulders.
		out[0] = this.px + fx * 0.75 * s + rx * turn * s;
		out[1] = this.py + (1.05 + breathe) * s;
		out[2] = this.pz + fz * 0.75 * s + rz * turn * s;
	}

	// append the deer's umbral silhouette into the shared umbral renderer (fog-attenuated strength).
	appendUmbral(renderer, fogParams)
	{
		if (!this.enabled || this.reveal <= 0.001) {
			return 0;
		}
		const s = this.scale;
		const strength = this.umbralStrength * this.reveal;
		const c = this.umbralColor;
		const sz = this.umbralSize * s;

		const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);   // forward (xz)
		const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);  // right (xz)
		const px = this.px, py = this.py, pz = this.pz;

		const breathe = Math.sin(this.breatheClock) * this.breatheAmp * s;

		let n = 0;
		const put = (x, y, z, size) => {
			if (renderer.pushFogged(x, y, z, size, c[0], c[1], c[2], strength, fogParams)) { n++; }
		};

		// body (torso: rear / mid / front, along forward axis, at back height).
		const bodyY = py + (0.62 + breathe) * s;
		put(px - fx * 0.42 * s, bodyY, pz - fz * 0.42 * s, sz * 0.95);
		put(px, bodyY, pz, sz * 1.05);
		put(px + fx * 0.40 * s, bodyY, pz + fz * 0.40 * s, sz * 0.95);

		// neck (rising from the front of the torso toward the head).
		put(px + fx * 0.60 * s, py + 0.85 * s, pz + fz * 0.60 * s, sz * 0.7);

		// head cluster (with idle head turn + breathing).
		const head = [0, 0, 0];
		this._headPos(head, rx, rz, fx, fz);
		const hX = head[0], hY = head[1], hZ = head[2];
		put(hX, hY, hZ, sz * 0.62);
		put(hX + fx * 0.18 * s, hY - 0.06 * s, hZ + fz * 0.18 * s, sz * 0.42);   // muzzle

		// four legs (front-left/right, rear-left/right), swinging in WALK/BOUND.
		const swing = Math.sin(this.stepPhase) * this.stepAmp * s;
		const swing2 = Math.sin(this.stepPhase + Math.PI) * this.stepAmp * s;
		const legTopY = py + 0.30 * s;
		const legBotY = py - 0.05 * s;   // feet near the ground baseline
		// front pair (near the neck)
		put(px + fx * 0.34 * s + rx * 0.20 * s + fx * swing, (legTopY + legBotY) * 0.5,
			pz + fz * 0.34 * s + rz * 0.20 * s + fz * swing, sz * 0.4);
		put(px + fx * 0.34 * s - rx * 0.20 * s + fx * swing2, (legTopY + legBotY) * 0.5,
			pz + fz * 0.34 * s - rz * 0.20 * s + fz * swing2, sz * 0.4);
		// rear pair
		put(px - fx * 0.34 * s + rx * 0.20 * s + fx * swing2, (legTopY + legBotY) * 0.5,
			pz - fz * 0.34 * s + rz * 0.20 * s + fz * swing2, sz * 0.4);
		put(px - fx * 0.34 * s - rx * 0.20 * s + fx * swing, (legTopY + legBotY) * 0.5,
			pz - fz * 0.34 * s - rz * 0.20 * s + fz * swing, sz * 0.4);

		// tail (short, behind + slightly up).
		put(px - fx * 0.55 * s, py + 0.55 * s, pz - fz * 0.55 * s, sz * 0.32);

		// ears (either side of the head top).
		put(hX + rx * 0.14 * s, hY + 0.16 * s, hZ + rz * 0.14 * s, sz * 0.28);
		put(hX - rx * 0.14 * s, hY + 0.16 * s, hZ - rz * 0.14 * s, sz * 0.28);

		// antler branches (three soft points per side, rising + spreading from the head top).
		const antY = hY + 0.22 * s;
		put(hX + rx * 0.10 * s, antY, hZ + rz * 0.10 * s, sz * 0.26);
		put(hX + rx * 0.24 * s + fx * 0.08 * s, antY + 0.20 * s, hZ + rz * 0.24 * s + fz * 0.08 * s, sz * 0.22);
		put(hX + rx * 0.30 * s - fx * 0.10 * s, antY + 0.36 * s, hZ + rz * 0.30 * s - fz * 0.10 * s, sz * 0.18);
		put(hX - rx * 0.10 * s, antY, hZ - rz * 0.10 * s, sz * 0.26);
		put(hX - rx * 0.24 * s + fx * 0.08 * s, antY + 0.20 * s, hZ - rz * 0.24 * s + fz * 0.08 * s, sz * 0.22);
		put(hX - rx * 0.30 * s - fx * 0.10 * s, antY + 0.36 * s, hZ - rz * 0.30 * s - fz * 0.10 * s, sz * 0.18);

		return n;
	}

	// append the deer's restrained MATTE body/structure layer into the shared matte renderer
	// (alpha-over, below bloom). Idle breathing modulates each point's size + opacity with a small
	// per-point phase offset; rig motion brightens the layer; the action pulse adds a brief lift on
	// the bound/landing. Fog-attenuated per point. Returns the number of points appended.
	appendMatte(renderer, fogParams)
	{
		if (!this.enabled || !this.matteEnabled || this.reveal <= 0.001) {
			return 0;
		}
		const s = this.scale;
		const mc = this.matteColor;
		const msz = this.matteSize * s;

		const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);   // forward (xz)
		const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);  // right (xz)
		const px = this.px, py = this.py, pz = this.pz;

		// motion brightening (bounded) + action pulse; base opacity scaled by the body reveal.
		const motionTerm = 1.0 + this.motionGlow * Math.min(this.motion, 3.0);
		const pulseTerm = 1.0 + this.actionPulse * this.pulse;
		const baseA = this.matteOpacity * this.reveal;

		// Readable structural silhouette: reuse the umbral rig positions (torso rear/mid/front, neck,
		// head + muzzle, four legs, tail, ears, antler branches) so the deer's outline -- crucially the
		// antlers -- is recognizable as material over the dark umbral form. Restrained point count
		// (mirrors DW_DEER_RIG), not a dense mesh.
		const breathe = Math.sin(this.breatheClock) * this.breatheAmp * s;
		const bodyY = py + (0.62 + breathe) * s;
		const legMidY = py + 0.125 * s;

		const head = [0, 0, 0];
		this._headPos(head, rx, rz, fx, fz);
		const hX = head[0], hY = head[1], hZ = head[2];
		const antY = hY + 0.22 * s;

		const P = [
			[px - fx * 0.42 * s, bodyY, pz - fz * 0.42 * s, 1.00],   // torso rear
			[px,                 bodyY, pz,                 1.12],   // torso mid
			[px + fx * 0.40 * s, bodyY, pz + fz * 0.40 * s, 1.00],   // torso front
			[px + fx * 0.60 * s, py + 0.85 * s, pz + fz * 0.60 * s, 0.78],   // neck
			[hX, hY, hZ, 0.66],                                              // head
			[hX + fx * 0.18 * s, hY - 0.06 * s, hZ + fz * 0.18 * s, 0.46],   // muzzle
			[px + fx * 0.34 * s + rx * 0.20 * s, legMidY, pz + fz * 0.34 * s + rz * 0.20 * s, 0.44],   // FL leg
			[px + fx * 0.34 * s - rx * 0.20 * s, legMidY, pz + fz * 0.34 * s - rz * 0.20 * s, 0.44],   // FR leg
			[px - fx * 0.34 * s + rx * 0.20 * s, legMidY, pz - fz * 0.34 * s + rz * 0.20 * s, 0.44],   // RL leg
			[px - fx * 0.34 * s - rx * 0.20 * s, legMidY, pz - fz * 0.34 * s - rz * 0.20 * s, 0.44],   // RR leg
			[px - fx * 0.55 * s, py + 0.55 * s, pz - fz * 0.55 * s, 0.34],   // tail
			[hX + rx * 0.14 * s, hY + 0.16 * s, hZ + rz * 0.14 * s, 0.30],   // ear L
			[hX - rx * 0.14 * s, hY + 0.16 * s, hZ - rz * 0.14 * s, 0.30],   // ear R
			[hX + rx * 0.10 * s, antY, hZ + rz * 0.10 * s, 0.30],                                       // antler L base
			[hX + rx * 0.24 * s + fx * 0.08 * s, antY + 0.20 * s, hZ + rz * 0.24 * s + fz * 0.08 * s, 0.26],  // antler L mid
			[hX + rx * 0.30 * s - fx * 0.10 * s, antY + 0.36 * s, hZ + rz * 0.30 * s - fz * 0.10 * s, 0.22],  // antler L tip
			[hX - rx * 0.10 * s, antY, hZ - rz * 0.10 * s, 0.30],                                       // antler R base
			[hX - rx * 0.24 * s + fx * 0.08 * s, antY + 0.20 * s, hZ - rz * 0.24 * s + fz * 0.08 * s, 0.26],  // antler R mid
			[hX - rx * 0.30 * s - fx * 0.10 * s, antY + 0.36 * s, hZ - rz * 0.30 * s - fz * 0.10 * s, 0.22],  // antler R tip
		];

		let n = 0;
		for (let i = 0; i < P.length; i++) {
			// per-point breathing phase offset so the layer "breathes" non-uniformly (subtle).
			const phase = this.breatheClock * this.breathRate + i * 0.9;
			const breath = 1.0 + this.breathAmount * Math.sin(phase);
			const size = msz * P[i][3] * breath;
			// opacity gets a gentler breathing wobble plus motion/pulse brightening; clamp restrained.
			let a = baseA * (0.85 + 0.15 * breath) * motionTerm * pulseTerm;
			if (a > this.matteAlphaMax) { a = this.matteAlphaMax; }
			if (renderer.pushFogged(P[i][0], P[i][1], P[i][2], size, mc[0], mc[1], mc[2], a, fogParams)) { n++; }
		}
		return n;
	}

	// build the emissive HDR light-point batch (two eyes + antler tips) for gfx.drawParticles.
	buildEmissiveBatch()
	{
		const b = this.emissive;
		let o = 0;
		const s = this.scale;

		const blink = this.blinking > 0.0
			? Math.abs((this.blinking / this.blinkTime) * 2.0 - 1.0)   // 1 open -> 0 shut -> 1 open
			: 1.0;
		const eyeA = this.eyeReveal * blink;

		const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);
		const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);
		const head = [0, 0, 0];
		this._headPos(head, rx, rz, fx, fz);
		const hX = head[0], hY = head[1], hZ = head[2];

		if (eyeA > 0.001) {
			const er = this.eyeColor[0] * this.eyeIntensity;
			const eg = this.eyeColor[1] * this.eyeIntensity;
			const eb = this.eyeColor[2] * this.eyeIntensity;
			const spread = this.eyeSpread * s;
			const fwd = 0.14 * s;
			// left eye
			b[o + 0] = hX + rx * spread + fx * fwd; b[o + 1] = hY + 0.02 * s; b[o + 2] = hZ + rz * spread + fz * fwd;
			b[o + 3] = this.eyeSize * s; b[o + 4] = er; b[o + 5] = eg; b[o + 6] = eb; b[o + 7] = eyeA; o += 8;
			// right eye
			b[o + 0] = hX - rx * spread + fx * fwd; b[o + 1] = hY + 0.02 * s; b[o + 2] = hZ - rz * spread + fz * fwd;
			b[o + 3] = this.eyeSize * s; b[o + 4] = er; b[o + 5] = eg; b[o + 6] = eb; b[o + 7] = eyeA; o += 8;
		}

		// antler tips (fade in with the body reveal so they resolve as the silhouette does).
		const tipA = this.eyeReveal * this.reveal;
		if (tipA > 0.001) {
			const ar = this.antlerColor[0] * this.antlerIntensity;
			const ag = this.antlerColor[1] * this.antlerIntensity;
			const ab = this.antlerColor[2] * this.antlerIntensity;
			const antY = hY + 0.22 * s + 0.36 * s;   // outermost antler tip height
			// left tip
			b[o + 0] = hX + rx * 0.30 * s - fx * 0.10 * s; b[o + 1] = antY; b[o + 2] = hZ + rz * 0.30 * s - fz * 0.10 * s;
			b[o + 3] = this.antlerSize * s; b[o + 4] = ar; b[o + 5] = ag; b[o + 6] = ab; b[o + 7] = tipA; o += 8;
			// right tip
			b[o + 0] = hX - rx * 0.30 * s - fx * 0.10 * s; b[o + 1] = antY; b[o + 2] = hZ - rz * 0.30 * s - fz * 0.10 * s;
			b[o + 3] = this.antlerSize * s; b[o + 4] = ar; b[o + 5] = ag; b[o + 6] = ab; b[o + 7] = tipA; o += 8;
		}

		this.emissiveCount = o / 8;
		return { data: b, count: this.emissiveCount };
	}

	isVisible() { return this.st !== DW_DEER_DELAY; }
	stateName() { return DW_DEER_STATE_NAMES[this.st]; }
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxUmbralOwl.js
//
// "Colored umbral creature" prototype: ONE animated umbral owl in the distant/background fog. Its
// body is a hierarchical rig of soft DARK point-sprites (drawn by dwGfxUmbralPointRenderer, which
// multiplicatively darkens + chromatically tints the HDR scene after the fog composite). Its two
// eyes -- and a subtle dive trail -- are ordinary emissive HDR light points (drawn through the
// existing gfx.drawParticles path) so they keep bloom.
//
// State sequence:
//   DELAY (hidden) -> EYES_IN (two eyes fade in, track + blink) -> BODY_REVEAL (head/body umbral
//   silhouette resolves) -> IDLE (idle head movement) -> WINGS_UNFOLD -> LAUNCH -> FLAP_DIVE (flap +
//   dive toward the ground) -> BANK_AWAY (veer off + rise) -> DISSOLVE (body dissolves into fog) ->
//   EYES_LINGER (eyes linger, then fade) -> DELAY (respawn after a delay).
//
// Only scalar/vector rig math is used (headings, local frame, lerps); no matrix work. Configurable
// anchor / scale / tint / strength / timing / flight path. Ground baseline default -2.0 (owl is
// airborne but its dive is clamped above the ground). Pooled/preallocated arrays, hard point cap,
// no per-frame allocation.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

// owl umbral rig points: 3 body + 2 head + 6 wings + 2 tail = 13.
const DW_OWL_RIG = 13;

// state machine phases.
const DW_OWL_DELAY			= 0;
const DW_OWL_EYES_IN		= 1;
const DW_OWL_BODY_REVEAL	= 2;
const DW_OWL_IDLE			= 3;
const DW_OWL_WINGS_UNFOLD	= 4;
const DW_OWL_LAUNCH			= 5;
const DW_OWL_FLAP_DIVE		= 6;
const DW_OWL_BANK_AWAY		= 7;
const DW_OWL_DISSOLVE		= 8;
const DW_OWL_EYES_LINGER	= 9;

const DW_OWL_STATE_NAMES = [
	"DELAY", "EYES_IN", "BODY_REVEAL", "IDLE", "WINGS_UNFOLD",
	"LAUNCH", "FLAP_DIVE", "BANK_AWAY", "DISSOLVE", "EYES_LINGER",
];

class dwGfxUmbralOwl
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options;

		// ---- placement / scale ----
		this.anchor		= o.anchor		|| [-2.0, 1.2, -6.0];   // airborne, near the lit ground-fog contrast zone
		this.spawnJitter = o.spawnJitter !== undefined ? o.spawnJitter : 2.0;  // anchor jitter on respawn
		this.scale		= o.scale		!== undefined ? o.scale		: 1.6;
		this.groundY	= o.groundY		!== undefined ? o.groundY
						: (o.baseY		!== undefined ? o.baseY		: -2.0);
		this.groundClearance = o.groundClearance !== undefined ? o.groundClearance : 0.6;

		// ---- umbral (dark, multiplicative) material ----
		this.umbralColor	= o.umbralColor		|| [0.40, 0.14, 0.55];   // restrained violet
		this.umbralStrength	= o.umbralStrength	!== undefined ? o.umbralStrength : 0.85;
		this.umbralSize		= o.umbralSize		!== undefined ? o.umbralSize	: 0.9;  // world units (base point size)

		// ---- emissive eyes / trail (HDR light points) ----
		this.eyeColor		= o.eyeColor		|| [1.00, 0.82, 0.35];   // gold (violet also reads well)
		this.eyeIntensity	= o.eyeIntensity	!== undefined ? o.eyeIntensity	: 3.6;
		this.eyeSize		= o.eyeSize			!== undefined ? o.eyeSize		: 0.10;
		this.eyeSpread		= o.eyeSpread		!== undefined ? o.eyeSpread		: 0.18;
		this.trailLength	= o.trailLength		!== undefined ? o.trailLength	: 6;
		this.trailColor		= o.trailColor		|| this.umbralColor;
		this.trailIntensity	= o.trailIntensity	!== undefined ? o.trailIntensity : 1.1;

		// ---- matte body/structure silhouette (non-glowing alpha-over points; below bloom threshold) ----
		this.matteEnabled	= (o.matteEnabled !== undefined) ? o.matteEnabled : true;
		this.matteColor		= o.matteColor		|| [0.34, 0.20, 0.62];   // deep violet/indigo rim (below bloom)
		this.matteOpacity	= o.matteOpacity	!== undefined ? o.matteOpacity	: 0.44;  // readable, still restrained
		this.matteSize		= o.matteSize		!== undefined ? o.matteSize		: 0.52;
		this.matteAlphaMax	= o.matteAlphaMax	!== undefined ? o.matteAlphaMax	: 0.80;  // per-point alpha clamp
		this.breathRate		= o.breathRate		!== undefined ? o.breathRate	: 1.0;
		this.breathAmount	= o.breathAmount	!== undefined ? o.breathAmount	: 0.16;
		this.motionGlow		= o.motionGlow		!== undefined ? o.motionGlow	: 0.35;
		this.actionPulse	= o.actionPulse		!== undefined ? o.actionPulse	: 0.6;
		this.pulseDecay		= o.pulseDecay		!== undefined ? o.pulseDecay	: 1.2;

		// ---- flight path (owl yaw-frame offsets) ----
		this.launchRise	= o.launchRise	!== undefined ? o.launchRise	: 0.8;
		this.diveForward = o.diveForward !== undefined ? o.diveForward	: 5.0;
		this.diveDrop	= o.diveDrop	!== undefined ? o.diveDrop		: 3.2;
		this.bankSide	= o.bankSide	!== undefined ? o.bankSide		: 5.5;
		this.bankRise	= o.bankRise	!== undefined ? o.bankRise		: 2.8;
		this.flapAmp	= o.flapAmp		!== undefined ? o.flapAmp		: 0.9;
		this.flapFreq	= o.flapFreq	!== undefined ? o.flapFreq		: 6.0;

		// ---- idle head movement + blink ----
		this.headAmp	= o.headAmp		!== undefined ? o.headAmp		: 0.18;
		this.headFreq	= o.headFreq	!== undefined ? o.headFreq		: 0.7;
		this.blinkMin	= o.blinkMin	!== undefined ? o.blinkMin		: 1.8;
		this.blinkMax	= o.blinkMax	!== undefined ? o.blinkMax		: 4.5;
		this.blinkTime	= o.blinkTime	!== undefined ? o.blinkTime		: 0.14;

		// ---- lifecycle timing (seconds) ----
		this.delayMin	= o.delayMin	!== undefined ? o.delayMin		: 2.5;
		this.delayMax	= o.delayMax	!== undefined ? o.delayMax		: 6.0;
		this.eyeInTime	= o.eyeInTime	!== undefined ? o.eyeInTime		: 1.0;
		this.revealTime	= o.revealTime	!== undefined ? o.revealTime	: 1.2;
		this.idleMin	= o.idleMin		!== undefined ? o.idleMin		: 2.0;
		this.idleMax	= o.idleMax		!== undefined ? o.idleMax		: 4.0;
		this.wingsTime	= o.wingsTime	!== undefined ? o.wingsTime		: 0.7;
		this.launchTime	= o.launchTime	!== undefined ? o.launchTime	: 0.35;
		this.diveTime	= o.diveTime	!== undefined ? o.diveTime		: 1.3;
		this.bankTime	= o.bankTime	!== undefined ? o.bankTime		: 1.1;
		this.dissolveTime = o.dissolveTime !== undefined ? o.dissolveTime : 1.0;
		this.eyeLingerTime = o.eyeLingerTime !== undefined ? o.eyeLingerTime : 0.9;

		this.enabled = (o.enabled !== undefined) ? o.enabled : true;

		// ---- runtime state ----
		this.st = DW_OWL_DELAY;
		this.stTimer = this._rand(this.delayMin, this.delayMax);
		this.reveal = 0.0;       // body umbral strength ramp 0..1
		this.eyeReveal = 0.0;    // eye emissive ramp 0..1
		this.wingUnfold = 0.0;   // 0 folded .. 1 unfolded
		this.yaw = 0.0;
		this.flapPhase = 0.0;
		this.headClock = this._rand(0.0, Math.PI * 2.0);
		this.blinkTimer = this._rand(this.blinkMin, this.blinkMax);
		this.blinking = 0.0;     // remaining blink time
		this.px = this.anchor[0]; this.py = this.anchor[1]; this.pz = this.anchor[2];

		// matte-layer motion tracking + action pulse.
		this.prevPx = this.px; this.prevPy = this.py; this.prevPz = this.pz;
		this.motion = 0.0;   // smoothed rig speed (world units / s)
		this.pulse = 0.0;    // action pulse envelope 0..1 (spikes on launch/dive)

		// phase interpolation endpoints.
		this.pStart = [0, 0, 0];
		this.pEnd = [0, 0, 0];
		this.phaseDur = 1.0;

		// emissive trail ring (dive).
		this.trailX = new Float32Array(this.trailLength);
		this.trailY = new Float32Array(this.trailLength);
		this.trailZ = new Float32Array(this.trailLength);
		this.trailHead = 0;
		this.trailCount = 0;

		// preallocated emissive batch: 2 eyes + trail.
		this.emissive = new Float32Array((2 + this.trailLength) * 8);
		this.emissiveCount = 0;

		this._pickAnchor();
	}

	_rand(a, b) { return a + Math.random() * (b - a); }
	_ease(t) { t = t < 0 ? 0 : (t > 1 ? 1 : t); return t * t * (3.0 - 2.0 * t); }

	_pickAnchor()
	{
		const j = this.spawnJitter;
		this.px = this.anchor[0] + this._rand(-j, j);
		this.py = this.anchor[1] + this._rand(-j * 0.4, j * 0.4);
		this.pz = this.anchor[2] + this._rand(-j, j);
		this.yaw = this._rand(0.0, Math.PI * 2.0);
	}

	_setPhase(ex, ey, ez, dur)
	{
		this.pStart[0] = this.px; this.pStart[1] = this.py; this.pStart[2] = this.pz;
		this.pEnd[0] = ex; this.pEnd[1] = ey; this.pEnd[2] = ez;
		this.phaseDur = dur > 1e-4 ? dur : 1e-4;
	}

	// advance current position along the active phase using eased progress from stTimer.
	_advancePhase()
	{
		const t = this._ease(1.0 - this.stTimer / this.phaseDur);
		this.px = this.pStart[0] + (this.pEnd[0] - this.pStart[0]) * t;
		this.py = this.pStart[1] + (this.pEnd[1] - this.pStart[1]) * t;
		this.pz = this.pStart[2] + (this.pEnd[2] - this.pStart[2]) * t;
	}

	_pushTrail()
	{
		const h = this.trailHead;
		this.trailX[h] = this.px; this.trailY[h] = this.py; this.trailZ[h] = this.pz;
		this.trailHead = (h + 1) % this.trailLength;
		if (this.trailCount < this.trailLength) { this.trailCount++; }
	}

	update(dt)
	{
		if (!(dt > 0.0)) { return; }

		// blink clock (eyes only).
		if (this.blinking > 0.0) {
			this.blinking -= dt;
		} else {
			this.blinkTimer -= dt;
			if (this.blinkTimer <= 0.0) {
				this.blinking = this.blinkTime;
				this.blinkTimer = this._rand(this.blinkMin, this.blinkMax);
			}
		}
		this.headClock += dt * this.headFreq;

		switch (this.st)
		{
			case DW_OWL_DELAY:
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					this._pickAnchor();
					this.reveal = 0.0; this.eyeReveal = 0.0; this.wingUnfold = 0.0;
					this.trailCount = 0; this.trailHead = 0;
					this.st = DW_OWL_EYES_IN;
				}
				break;

			case DW_OWL_EYES_IN:
				this.eyeReveal = Math.min(1.0, this.eyeReveal + dt / this.eyeInTime);
				if (this.eyeReveal >= 1.0) { this.st = DW_OWL_BODY_REVEAL; }
				break;

			case DW_OWL_BODY_REVEAL:
				this.reveal = Math.min(1.0, this.reveal + dt / this.revealTime);
				if (this.reveal >= 1.0) {
					this.st = DW_OWL_IDLE;
					this.stTimer = this._rand(this.idleMin, this.idleMax);
				}
				break;

			case DW_OWL_IDLE:
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					this.st = DW_OWL_WINGS_UNFOLD;
					this.stTimer = this.wingsTime;
				}
				break;

			case DW_OWL_WINGS_UNFOLD:
				this.wingUnfold = Math.min(1.0, this.wingUnfold + dt / this.wingsTime);
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					this.wingUnfold = 1.0;
					// launch: brief rise.
					this._setPhase(this.px, this.py + this.launchRise, this.pz, this.launchTime);
					this.st = DW_OWL_LAUNCH;
					this.stTimer = this.launchTime;
					this.pulse = 1.0;   // action pulse spikes at launch
				}
				break;

			case DW_OWL_LAUNCH:
				this._advancePhase();
				this.flapPhase += dt * this.flapFreq;
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					// dive: forward + down toward the ground (clamped above it).
					const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);
					let ty = this.py - this.diveDrop;
					const minY = this.groundY + this.groundClearance;
					if (ty < minY) { ty = minY; }
					this._setPhase(
						this.px + fx * this.diveForward,
						ty,
						this.pz + fz * this.diveForward,
						this.diveTime);
					this.st = DW_OWL_FLAP_DIVE;
					this.stTimer = this.diveTime;
					this.pulse = Math.max(this.pulse, 0.9);   // dive lift
				}
				break;

			case DW_OWL_FLAP_DIVE:
				this._advancePhase();
				this.flapPhase += dt * this.flapFreq;
				this._pushTrail();
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					// bank: veer to the side + rise back into the haze.
					const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);
					this._setPhase(
						this.px + rx * this.bankSide,
						this.py + this.bankRise,
						this.pz + rz * this.bankSide,
						this.bankTime);
					this.st = DW_OWL_BANK_AWAY;
					this.stTimer = this.bankTime;
				}
				break;

			case DW_OWL_BANK_AWAY:
				this._advancePhase();
				this.flapPhase += dt * this.flapFreq * 0.6;
				if (this.trailCount > 0) { this.trailCount--; }
				this.stTimer -= dt;
				if (this.stTimer <= 0.0) {
					this.st = DW_OWL_DISSOLVE;
					this.stTimer = this.dissolveTime;
				}
				break;

			case DW_OWL_DISSOLVE:
				this.reveal = Math.max(0.0, this.reveal - dt / this.dissolveTime);
				this.wingUnfold = Math.max(0.0, this.wingUnfold - dt / this.dissolveTime);
				if (this.trailCount > 0) { this.trailCount--; }
				this.stTimer -= dt;
				if (this.stTimer <= 0.0 || this.reveal <= 0.0) {
					this.reveal = 0.0;
					this.st = DW_OWL_EYES_LINGER;
					this.stTimer = this.eyeLingerTime;
				}
				break;

			case DW_OWL_EYES_LINGER:
				this.eyeReveal = Math.max(0.0, this.eyeReveal - dt / this.eyeLingerTime);
				this.stTimer -= dt;
				if (this.stTimer <= 0.0 || this.eyeReveal <= 0.0) {
					this.eyeReveal = 0.0;
					this.st = DW_OWL_DELAY;
					this.stTimer = this._rand(this.delayMin, this.delayMax);
				}
				break;
		}

		// matte-layer motion tracking: smoothed rig speed drives motion brightening; action pulse decays.
		const vx = (this.px - this.prevPx) / dt;
		const vy = (this.py - this.prevPy) / dt;
		const vz = (this.pz - this.prevPz) / dt;
		const speed = Math.sqrt(vx * vx + vy * vy + vz * vz);
		this.motion += (speed - this.motion) * Math.min(1.0, dt * 6.0);   // exponential smoothing
		this.prevPx = this.px; this.prevPy = this.py; this.prevPz = this.pz;
		if (this.pulse > 0.0) { this.pulse = Math.max(0.0, this.pulse - dt / this.pulseDecay); }
	}

	// current head-cluster world position (with idle head movement offset applied), into out[0..2].
	_headPos(out, rx, rz, upX, upY, upZ)
	{
		const s = this.scale;
		const hy = Math.sin(this.headClock) * this.headAmp;             // small yaw sway
		const hp = Math.cos(this.headClock * 0.7) * this.headAmp * 0.5; // small pitch
		out[0] = this.px + rx * hy * s;
		out[1] = this.py + (0.95 + hp) * s;
		out[2] = this.pz + rz * hy * s;
	}

	// append the owl's umbral silhouette into the shared umbral renderer (fog-attenuated strength).
	appendUmbral(renderer, fogParams)
	{
		if (!this.enabled || this.reveal <= 0.001) {
			return 0;
		}
		const s = this.scale;
		const strength = this.umbralStrength * this.reveal;
		const c = this.umbralColor;
		const sz = this.umbralSize * s;

		const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);   // forward (xz)
		const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);  // right (xz)
		const px = this.px, py = this.py, pz = this.pz;

		let n = 0;
		const put = (x, y, z, size) => {
			if (renderer.pushFogged(x, y, z, size, c[0], c[1], c[2], strength, fogParams)) { n++; }
		};

		// body (torso, stacked up).
		put(px, py + 0.05 * s, pz, sz * 1.05);
		put(px, py + 0.38 * s, pz, sz * 1.0);
		put(px + fx * 0.05 * s, py + 0.66 * s, pz + fz * 0.05 * s, sz * 0.85);

		// head cluster (with idle movement).
		const hy = Math.sin(this.headClock) * this.headAmp;
		const hp = Math.cos(this.headClock * 0.7) * this.headAmp * 0.5;
		const hX = px + rx * hy * s, hY = py + (0.95 + hp) * s, hZ = pz + rz * hy * s;
		put(hX, hY, hZ, sz * 0.8);
		put(hX + fx * 0.06 * s, hY + 0.12 * s, hZ + fz * 0.06 * s, sz * 0.6);   // brow

		// wings: shoulder / mid / tip, spread by wingUnfold, flapping when unfolded.
		const flap = Math.sin(this.flapPhase * this.flapFreq) * this.flapAmp * this.wingUnfold;
		const wu = this.wingUnfold;
		// left (-right)
		put(px - rx * 0.28 * s, py + 0.55 * s, pz - rz * 0.28 * s, sz * 0.7);
		put(px - rx * (0.28 + 0.60 * wu) * s, py + (0.55 + 0.10 * flap) * s, pz - rz * (0.28 + 0.60 * wu) * s, sz * 0.62);
		put(px - rx * (0.28 + 1.15 * wu) * s, py + (0.55 + 0.22 * flap) * s, pz - rz * (0.28 + 1.15 * wu) * s, sz * 0.5);
		// right (+right)
		put(px + rx * 0.28 * s, py + 0.55 * s, pz + rz * 0.28 * s, sz * 0.7);
		put(px + rx * (0.28 + 0.60 * wu) * s, py + (0.55 + 0.10 * flap) * s, pz + rz * (0.28 + 0.60 * wu) * s, sz * 0.62);
		put(px + rx * (0.28 + 1.15 * wu) * s, py + (0.55 + 0.22 * flap) * s, pz + rz * (0.28 + 1.15 * wu) * s, sz * 0.5);

		// tail (behind + below).
		put(px - fx * 0.12 * s, py - 0.28 * s, pz - fz * 0.12 * s, sz * 0.6);
		put(px - fx * 0.22 * s, py - 0.55 * s, pz - fz * 0.22 * s, sz * 0.45);

		return n;
	}

	// append the owl's MATTE body/structure silhouette into the shared matte renderer (alpha-over,
	// below bloom). Reuses the umbral rig positions (body, head + brow, both wings spread/flapping by
	// wingUnfold, tail) so the owl's outline is recognizable as material over the dark umbral form,
	// readable against both bright fog and the black forest. Breathing + motion/pulse brightening;
	// fog-attenuated per point. Returns the number of points appended.
	appendMatte(renderer, fogParams)
	{
		if (!this.enabled || !this.matteEnabled || this.reveal <= 0.001) {
			return 0;
		}
		const s = this.scale;
		const mc = this.matteColor;
		const msz = this.matteSize * s;

		const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);
		const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);
		const px = this.px, py = this.py, pz = this.pz;

		const motionTerm = 1.0 + this.motionGlow * Math.min(this.motion, 4.0);
		const pulseTerm = 1.0 + this.actionPulse * this.pulse;
		const baseA = this.matteOpacity * this.reveal;

		// head cluster (with idle movement), matching the umbral head placement.
		const hy = Math.sin(this.headClock) * this.headAmp;
		const hp = Math.cos(this.headClock * 0.7) * this.headAmp * 0.5;
		const hX = px + rx * hy * s, hY = py + (0.95 + hp) * s, hZ = pz + rz * hy * s;

		// wings: shoulder / mid / tip, spread by wingUnfold, flapping when unfolded (mirror umbral).
		const flap = Math.sin(this.flapPhase * this.flapFreq) * this.flapAmp * this.wingUnfold;
		const wu = this.wingUnfold;

		const P = [
			[px, py + 0.05 * s, pz, 1.05],                                            // body base
			[px, py + 0.38 * s, pz, 1.00],                                            // body mid
			[px + fx * 0.05 * s, py + 0.66 * s, pz + fz * 0.05 * s, 0.85],            // body upper
			[hX, hY, hZ, 0.80],                                                       // head
			[hX + fx * 0.06 * s, hY + 0.12 * s, hZ + fz * 0.06 * s, 0.60],            // brow
			[px - rx * 0.28 * s, py + 0.55 * s, pz - rz * 0.28 * s, 0.70],            // wing L shoulder
			[px - rx * (0.28 + 0.60 * wu) * s, py + (0.55 + 0.10 * flap) * s, pz - rz * (0.28 + 0.60 * wu) * s, 0.62],  // wing L mid
			[px - rx * (0.28 + 1.15 * wu) * s, py + (0.55 + 0.22 * flap) * s, pz - rz * (0.28 + 1.15 * wu) * s, 0.50],  // wing L tip
			[px + rx * 0.28 * s, py + 0.55 * s, pz + rz * 0.28 * s, 0.70],            // wing R shoulder
			[px + rx * (0.28 + 0.60 * wu) * s, py + (0.55 + 0.10 * flap) * s, pz + rz * (0.28 + 0.60 * wu) * s, 0.62],  // wing R mid
			[px + rx * (0.28 + 1.15 * wu) * s, py + (0.55 + 0.22 * flap) * s, pz + rz * (0.28 + 1.15 * wu) * s, 0.50],  // wing R tip
			[px - fx * 0.12 * s, py - 0.28 * s, pz - fz * 0.12 * s, 0.60],            // tail upper
			[px - fx * 0.22 * s, py - 0.55 * s, pz - fz * 0.22 * s, 0.45],            // tail lower
		];

		let n = 0;
		for (let i = 0; i < P.length; i++) {
			const phase = this.flapPhase * this.breathRate + i * 0.9;
			const breath = 1.0 + this.breathAmount * Math.sin(phase);
			const size = msz * P[i][3] * breath;
			let a = baseA * (0.85 + 0.15 * breath) * motionTerm * pulseTerm;
			if (a > this.matteAlphaMax) { a = this.matteAlphaMax; }
			if (renderer.pushFogged(P[i][0], P[i][1], P[i][2], size, mc[0], mc[1], mc[2], a, fogParams)) { n++; }
		}
		return n;
	}

	// build the emissive HDR light-point batch (two eyes + subtle dive trail) for gfx.drawParticles.
	buildEmissiveBatch()
	{
		const b = this.emissive;
		let o = 0;
		const s = this.scale;

		const blink = this.blinking > 0.0
			? Math.abs((this.blinking / this.blinkTime) * 2.0 - 1.0)   // 1 open -> 0 shut -> 1 open
			: 1.0;
		const eyeA = this.eyeReveal * blink;

		if (eyeA > 0.001) {
			const rx = Math.cos(this.yaw), rz = -Math.sin(this.yaw);
			const fx = Math.sin(this.yaw), fz = Math.cos(this.yaw);
			const hy = Math.sin(this.headClock) * this.headAmp;
			const hp = Math.cos(this.headClock * 0.7) * this.headAmp * 0.5;
			const hX = this.px + rx * hy * s, hY = this.py + (0.95 + hp) * s, hZ = this.pz + rz * hy * s;
			const er = this.eyeColor[0] * this.eyeIntensity;
			const eg = this.eyeColor[1] * this.eyeIntensity;
			const eb = this.eyeColor[2] * this.eyeIntensity;
			const spread = this.eyeSpread * s;
			const fwd = 0.12 * s;
			// left eye
			b[o + 0] = hX + rx * spread + fx * fwd; b[o + 1] = hY + 0.02 * s; b[o + 2] = hZ + rz * spread + fz * fwd;
			b[o + 3] = this.eyeSize * s; b[o + 4] = er; b[o + 5] = eg; b[o + 6] = eb; b[o + 7] = eyeA; o += 8;
			// right eye
			b[o + 0] = hX - rx * spread + fx * fwd; b[o + 1] = hY + 0.02 * s; b[o + 2] = hZ - rz * spread + fz * fwd;
			b[o + 3] = this.eyeSize * s; b[o + 4] = er; b[o + 5] = eg; b[o + 6] = eb; b[o + 7] = eyeA; o += 8;
		}

		// subtle dive trail (fades with recency), so the streak retains bloom.
		const tc = this.trailCount;
		const tl = this.trailLength;
		const tr = this.trailColor[0] * this.trailIntensity;
		const tg = this.trailColor[1] * this.trailIntensity;
		const tb = this.trailColor[2] * this.trailIntensity;
		for (let k = 0; k < tc; k++) {
			const idx = ((this.trailHead - 1 - k) % tl + tl) % tl;
			const falloff = 1.0 - (k / tl);
			const a = falloff * 0.5 * this.reveal;
			if (a <= 0.001) { continue; }
			b[o + 0] = this.trailX[idx]; b[o + 1] = this.trailY[idx]; b[o + 2] = this.trailZ[idx];
			b[o + 3] = this.eyeSize * s * (0.5 + 0.5 * falloff);
			b[o + 4] = tr * falloff; b[o + 5] = tg * falloff; b[o + 6] = tb * falloff; b[o + 7] = a;
			o += 8;
		}

		this.emissiveCount = o / 8;
		return { data: b, count: this.emissiveCount };
	}

	isVisible() { return this.st !== DW_OWL_DELAY; }
	stateName() { return DW_OWL_STATE_NAMES[this.st]; }
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGLGfx
{
	constructor()
	{
		this.gl = 0;
		this.context = 0;
		this.canvas = 0;
	}
};
function dwGetTime()
{
	const d = new Date();
	return (d.getTime());
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfx
{
	constructor()
	{
		this.colorVS = `
			#version 300 es
			in vec4 a_position;

			uniform mat4 u_projection;
			uniform mat4 u_view;
			uniform mat4 u_world;

			void main() {
				// Multiply the position by the matrices.
				gl_Position = u_projection * u_view * u_world * a_position;
			}
		`;
		this.colorFS = `
			#version 300 es
			precision highp float;
			uniform vec4 u_color;
			out vec4 outColor;

			void main() {
				outColor = vec4(1.0, 0.0, 0.0, 1.0);
			}
		`;
		this.standardPBRVS = `
			#version 300 es
			in vec4 a_position;
			in vec2 a_texcoord;
			in vec3 a_normal;
			in vec4 a_tangent;

			uniform mat4 u_projection;
			uniform mat4 u_view;
			uniform mat4 u_world;
			uniform mat4 u_inverseTransposeModelMatrix;
			uniform mat4 u_textureMatrix;

			out vec2 v_texcoord;
			out vec4 v_projectedTexcoord;
			out vec3 v_normal;
			out vec4 v_worldPosition;
			out mat3 v_tbn;

			out vec4 v_clipPosition;

			void main()
			{
				// Multiply the position by the matrix.
				vec4 worldPosition = u_world * a_position;
				vec4 clipPos 	= u_projection * u_view * worldPosition;
				gl_Position		= clipPos;
				v_clipPosition 	= clipPos;

				// Pass the texture coord to the fragment shader.
				v_texcoord = a_texcoord;
				vec3 N = normalize((u_inverseTransposeModelMatrix * vec4(a_normal, 0.0)).xyz);
				vec3 T = normalize((u_inverseTransposeModelMatrix * vec4(a_tangent.xyz, 0.0)).xyz);
				T = normalize(T - N * dot(T, N));
				vec3 B = normalize(cross(T, N)) * a_tangent.w;
				v_tbn = mat3(T, B, N);

				v_projectedTexcoord = u_textureMatrix * worldPosition;
				v_worldPosition = worldPosition;
				v_normal = N;
			}
		`;
		this.standardPBRFS = `
			#version 300 es
			precision highp float;

			in vec2 v_texcoord;
			in vec3 v_normal;
			in vec4 v_worldPosition;
			in mat3 v_tbn;
			in vec4 v_projectedTexcoord;
			in vec4 v_clipPosition;

			uniform vec4 u_colorMult;
			uniform sampler2D u_texture0;
			uniform sampler2D u_texture1;

			uniform vec3 u_cameraPosition;

			// keep these in the shader design, even if not used yet
			uniform vec3 u_dirLightDirection;
			uniform vec3 u_dirLightColor;
			uniform float u_dirLightIntensity;

			uniform bool u_useCameraDirLight;
			uniform vec3 u_cameraLightDirection;
			uniform vec3 u_cameraLightColor;
			uniform float u_cameraLightIntensity;

			uniform bool u_usePointLight;
			uniform vec3 u_pointLightPosition;
			uniform vec3 u_pointLightColor;
			uniform float u_pointLightIntensity;
			uniform float u_pointLightRange;

			uniform bool u_useCameraSpotLight;
			uniform vec3 u_cameraSpotLightPosition;
			uniform vec3 u_cameraSpotLightDirection;
			uniform vec3 u_cameraSpotLightColor;
			uniform float u_cameraSpotLightIntensity;
			uniform float u_cameraSpotLightInnerCutoff;
			uniform float u_cameraSpotLightOuterCutoff;
			uniform float u_cameraSpotLightRange;

			uniform bool u_useDecalLayer;
			uniform sampler2D u_decalTexture;
			uniform vec4 u_decalColor;
			uniform float u_decalAlpha;
			uniform vec3 u_decalReverseLightDirection;

			uniform samplerCube u_envMap;
			uniform float u_envLod;       // for future roughness/LUT integration if you want

			uniform sampler2D u_sceneColorTexture;
			uniform vec2 u_sceneTexelSize;
			uniform float u_refractionStrength;
			uniform float u_glassMode;

			uniform float u_matRoughness;
			uniform float u_matMetallic;
			uniform float u_matSheen;
			uniform float u_matOpacity;
			uniform float u_matEnvStrength;
			uniform float u_matAlphaCutoff;    // 0 = disabled; >0 discards texels below cutoff (opt-in)

			uniform float u_decalBrightness;   // 1.0 = unchanged
			uniform float u_decalContrast;     // 1.0 = unchanged
			uniform float u_decalAlphaMul;     // 1.0 = unchanged

			uniform float u_normalStrength;

			uniform vec3  u_emissiveColor;      // glow tint (0 = off)
			uniform float u_emissiveStrength;   // HDR multiplier; exceed bloom threshold to bloom

			out vec4 outColor;

			const float PI = 3.14159265359;

			struct MaterialData
			{
				vec3 baseColor;
				float roughness;
				float metallic;
				float ao;
				float sheen;
			};
			vec2 getScreenUV(vec4 clipPos)
			{
				vec2 uv = clipPos.xy / clipPos.w;
				uv = uv * 0.5 + 0.5;
				return uv;
			}
			float saturate(float x)
			{
				return clamp(x, 0.0, 1.0);
			}
			// standardPBRFS
			vec3 getNormal() {
				vec3 normalColor = texture(u_texture1, v_texcoord).rgb;
				vec3 tangentNormal = normalColor * 2.0 - 1.0;
				tangentNormal.g = -tangentNormal.g;

				tangentNormal = normalize(mix(vec3(0.0, 0.0, 1.0), tangentNormal, u_normalStrength));

				return normalize(v_tbn * tangentNormal);
			}
			vec3 fresnelSchlick(float cosTheta, vec3 F0)
			{
				return F0 + (1.0 - F0) * pow(1.0 - cosTheta, 5.0);
			}
			float DistributionGGX(vec3 N, vec3 H, float roughness)
			{
				float a = roughness * roughness;
				float a2 = a * a;
				float NdotH = max(dot(N, H), 0.0);
				float NdotH2 = NdotH * NdotH;
				float denom = NdotH2 * (a2 - 1.0) + 1.0;
				return a2 / max(PI * denom * denom, 0.0001);
			}

			float GeometrySchlickGGX(float NdotV, float roughness)
			{
				float r = roughness + 1.0;
				float k = (r * r) / 8.0;
				return NdotV / (NdotV * (1.0 - k) + k);
			}

			float GeometrySmith(vec3 N, vec3 V, vec3 L, float roughness)
			{
				float NdotV = max(dot(N, V), 0.0);
				float NdotL = max(dot(N, L), 0.0);
				float ggxV = GeometrySchlickGGX(NdotV, roughness);
				float ggxL = GeometrySchlickGGX(NdotL, roughness);
				return ggxV * ggxL;
			}
			///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
			vec3 evaluateSheen(
				vec3 sheenColor,
				float sheenStrength,
				vec3 N,
				vec3 V,
				vec3 L
			)
			{
				vec3 H = normalize(V + L);
				float NdotL = max(dot(N, L), 0.0);
				float NdotV = max(dot(N, V), 0.0);
				float NdotH = max(dot(N, H), 0.0);

				float FH = pow(1.0 - max(dot(L, H), 0.0), 5.0);
				float grazing = pow(1.0 - NdotV, 2.0);

				float sheenTerm = FH * grazing * NdotL;
				return sheenColor * sheenStrength * sheenTerm;
			}
			vec3 evaluateDirectionalLight(
				vec3 lightDirection,
				vec3 lightColor,
				float lightIntensity,
				MaterialData mat,
				vec3 N,
				vec3 V
			)
			{
				// lightDirection = direction the light travels, from light toward surface
				// L = direction from surface toward light
				vec3 L = normalize(-lightDirection);
				vec3 H = normalize(V + L);

				float NdotL = max(dot(N, L), 0.0);
				float NdotV = max(dot(N, V), 0.0);
				float HdotV = max(dot(H, V), 0.0);

				vec3 radiance = lightColor * lightIntensity;
				vec3 F0 = mix(vec3(0.04), mat.baseColor, mat.metallic);

				float D = DistributionGGX(N, H, mat.roughness);
				float G = GeometrySmith(N, V, L, mat.roughness);
				vec3 F = fresnelSchlick(HdotV, F0);

				vec3 kS = F;
				vec3 kD = (vec3(1.0) - kS) * (1.0 - mat.metallic);

				vec3 diffuse = kD * mat.baseColor / PI;
				vec3 specular = (D * G * F) / max(4.0 * NdotV * NdotL, 0.0001);

				vec3 sheen = evaluateSheen(mat.baseColor, mat.sheen, N, V, L);
				return ((diffuse + specular) + sheen) * radiance * NdotL;
			}
			vec3 evaluatePointLight(
				vec3 lightPosition,
				vec3 lightColor,
				float lightIntensity,
				float lightRange,
				MaterialData mat,
				vec3 N,
				vec3 V
			)
			{
				vec3 toLight = lightPosition - v_worldPosition.xyz;
				float dist = length(toLight);
				vec3 L = normalize(toLight);
				vec3 H = normalize(V + L);

				float attenuation = 1.0 / max(dist * dist, 0.0001);
				if (lightRange > 0.0)
				{
					float fade = saturate(1.0 - dist / lightRange);
					attenuation *= fade * fade;
				}

				float NdotL = max(dot(N, L), 0.0);
				float NdotV = max(dot(N, V), 0.0);
				float HdotV = max(dot(H, V), 0.0);

				vec3 radiance = lightColor * lightIntensity * attenuation;
				vec3 F0 = mix(vec3(0.04), mat.baseColor, mat.metallic);

				float D = DistributionGGX(N, H, mat.roughness);
				float G = GeometrySmith(N, V, L, mat.roughness);
				vec3 F = fresnelSchlick(HdotV, F0);

				vec3 kS = F;
				vec3 kD = (vec3(1.0) - kS) * (1.0 - mat.metallic);

				vec3 diffuse = kD * mat.baseColor / PI;
				vec3 specular = (D * G * F) / max(4.0 * NdotV * NdotL, 0.0001);

				vec3 sheen = evaluateSheen(mat.baseColor, mat.sheen, N, V, L);
				return ((diffuse + specular) + sheen) * radiance * NdotL;
			}
			vec3 evaluateSpotLight(
				vec3 lightPosition,
				vec3 lightDirection,
				vec3 lightColor,
				float lightIntensity,
				float innerCutoff,
				float outerCutoff,
				float lightRange,
				MaterialData mat,
				vec3 N,
				vec3 V
			)
			{
				vec3 toLight = lightPosition - v_worldPosition.xyz;
				float dist = length(toLight);
				vec3 L = normalize(toLight);
				vec3 H = normalize(V + L);

				float attenuation = 1.0;

				// Use a softer falloff instead of pure 1 / dist^2
				if (lightRange > 0.0) {
					float t = saturate(dist / lightRange);
					// One of these three options:

					// Option A: simple linear
					//float fade = 1.0 - t;

					// Option B: cubic smoothstep (gentle)
					float fade = 1.0 - t * t * (3.0 - 2.0 * t);

					// Option C: artist-friendly curve
					// float fade = pow(1.0 - t, 1.5);

					attenuation = fade;
				}
				else if (lightRange < 0.0) {
					float fade = saturate(1.0 - dist / (-lightRange));
					attenuation *= fade * fade;
				}
				else {
					// Fallback: 1 / dist^2 if you really want physical-style behavior
					attenuation = 1.0 / max(dist * dist, 0.0001);
				}

				// Compare spotlight axis with light->fragment direction
				float theta = dot(normalize(-L), normalize(lightDirection));
				float epsilon = max(innerCutoff - outerCutoff, 0.0001);
				float spot = clamp((theta - outerCutoff) / epsilon, 0.0, 1.0);

				float NdotL = max(dot(N, L), 0.0);
				float NdotV = max(dot(N, V), 0.0);
				float HdotV = max(dot(H, V), 0.0);

				vec3 radiance = lightColor * lightIntensity * attenuation * spot;
				vec3 F0 = mix(vec3(0.04), mat.baseColor, mat.metallic);

				float D = DistributionGGX(N, H, mat.roughness);
				float G = GeometrySmith(N, V, L, mat.roughness);
				vec3 F = fresnelSchlick(HdotV, F0);

				vec3 kS = F;
				vec3 kD = (vec3(1.0) - kS) * (1.0 - mat.metallic);

				vec3 diffuse = kD * mat.baseColor / PI;
				vec3 specular = (D * G * F) / max(4.0 * NdotV * NdotL, 0.0001);

				vec3 sheen = evaluateSheen(mat.baseColor, mat.sheen, N, V, L);
				return ((diffuse + specular) + sheen) * radiance * NdotL;
			}
			vec3 evaluateThinTranslucency(
				vec3 lightDirection,
				vec3 lightColor,
				float lightIntensity,
				MaterialData mat,
				vec3 N,
				vec3 V,
				vec3 transColor,
				float transStrength,
				float transPower,
				float transDistortion
			)
			{
				vec3 L = normalize(-lightDirection);

				// Back lighting only: strongest when light is behind surface
				float backLit = max(dot(-N, L), 0.0);

				// Slightly bend transmitted light through the normal
				vec3 Lt = normalize(-L + N * transDistortion);

				// Strongest when transmitted light exits toward camera
				float viewScatter = pow(max(dot(V, Lt), 0.0), transPower);

				float trans = backLit * viewScatter * transStrength;

				return transColor * mat.baseColor * lightColor * lightIntensity * trans;
			}
			vec3 applyBrightnessContrast(vec3 color, float brightness, float contrast)
			{
				color *= brightness;
				color = (color - 0.5) * contrast + 0.5;
				return max(color, vec3(0.0));
			}
			void main()
			{
				MaterialData mat;

				// Color textures are assumed to be authored in display/sRGB-like space.
				// Decode to linear before lighting.
				vec4 baseSample = texture(u_texture0, v_texcoord);

				// Opt-in alpha cutout (u_matAlphaCutoff > 0). Fully/near-transparent
				// texels are discarded so that, when this material is drawn with depth
				// writes enabled (blended logo into the scene depth texture), the
				// transparent background does not stamp a solid rectangle into depth.
				// Texels above the cutoff still blend softly, preserving soft edges.
				if (u_matAlphaCutoff > 0.0 && baseSample.a < u_matAlphaCutoff) {
					discard;
				}

				baseSample.rgb = pow(max(baseSample.rgb, vec3(0.0)), vec3(2.2));

				vec4 finalSurfaceColor = baseSample;
				bool hasDecal = false;

				if (u_useDecalLayer) {
					vec3 projectedTexcoord = v_projectedTexcoord.xyz / v_projectedTexcoord.w;

					bool inRange =
						projectedTexcoord.x >= 0.0 &&
						projectedTexcoord.x <= 1.0 &&
						projectedTexcoord.y >= 0.0 &&
						projectedTexcoord.y <= 1.0;

					vec3 projectorDir = normalize(u_decalReverseLightDirection);
					vec3 No = getNormal();
					float facing = dot(No, projectorDir);

					projectedTexcoord.y = -projectedTexcoord.y;

					vec4 decalSample = texture(u_decalTexture, projectedTexcoord.xy);
					decalSample.rgb = pow(max(decalSample.rgb, vec3(0.0)), vec3(2.2));
					decalSample.rgb = applyBrightnessContrast(
						decalSample.rgb,
						u_decalBrightness,
						u_decalContrast
					);

					if (!(decalSample.a > 0.01 && inRange && facing > 0.0)) {
						finalSurfaceColor.a = 0.0;
						discard;
					}

					hasDecal = true;

					vec3 decalRGB = decalSample.rgb * u_decalColor.rgb;
					float a = decalSample.a * u_decalAlpha * u_decalAlphaMul * u_decalColor.a;
					a = clamp(a, 0.0, 1.0);

					vec3 baseRGB = baseSample.rgb;
					vec3 blendedRGB = mix(baseRGB, baseRGB * decalRGB, a);

					finalSurfaceColor = vec4(blendedRGB, mix(baseSample.a, 1.0, a));
				}
				mat.baseColor = finalSurfaceColor.rgb;
				mat.roughness = u_matRoughness;
				mat.metallic  = u_matMetallic;
				mat.ao        = 1.0;
				mat.sheen     = u_matSheen;

				if (hasDecal) {
					mat.metallic = min(mat.metallic, 0.02);
					mat.roughness = max(mat.roughness, 0.55);
					mat.sheen = max(mat.sheen, 0.10);
				}
				vec3 N = getNormal();
				vec3 V = normalize(u_cameraPosition - v_worldPosition.xyz);

				vec3 color = vec3(0.0);

				// ambient
				color += mat.baseColor * 0.02 * mat.ao;

				// static directional light
				color += evaluateDirectionalLight(
					u_dirLightDirection,
					u_dirLightColor,
					u_dirLightIntensity,
					mat,
					N,
					V
				);
				// For this test, only use the camera directional light.
				if (u_useCameraDirLight)
				{
					
					color += evaluateDirectionalLight(
						u_cameraLightDirection,
						u_cameraLightColor,
						u_cameraLightIntensity,
						mat,
						N,
						V
					);
				}
				// camera spotlight
				if (u_useCameraSpotLight)
				{
					color += evaluateSpotLight(
						u_cameraSpotLightPosition,
						u_cameraSpotLightDirection,
						u_cameraSpotLightColor,
						u_cameraSpotLightIntensity,
						u_cameraSpotLightInnerCutoff,
						u_cameraSpotLightOuterCutoff,
						u_cameraSpotLightRange,
						mat,
						N,
						V
					);
				}
				// leave these paths in place, but do not enable them yet
				if (u_usePointLight)
				{
					color += evaluatePointLight(
						u_pointLightPosition,
						u_pointLightColor,
						u_pointLightIntensity,
						u_pointLightRange,
						mat,
						N,
						V
					);
				}
				vec3 transColor = vec3(1.0, 0.35, 0.25); // warm red/orange through skin/fabric, tune later

				/*color += evaluateThinTranslucency(
					u_dirLightDirection,
					u_dirLightColor,
					u_dirLightIntensity,
					mat,
					N,
					V,
					transColor,
					0.20,   // strength
					4.0,    // power / sharpness
					0.35    // distortion
				);*/
				if (hasDecal) {
					vec3 Lc = normalize(-u_cameraLightDirection);
					vec3 Hc = normalize(V + Lc);
					float coat = pow(max(dot(N, Hc), 0.0), 64.0) * max(dot(N, Lc), 0.0);
					color += vec3(1.0) * coat * 0.04;
				}
				vec3 Nenv = N;
				vec3 Venv = V;
				float facing = dot(Nenv, Venv);
				if (facing > 0.0) {
					vec3 Renv = reflect(-Venv, Nenv);
					Renv.x = -Renv.x;

					vec3 envColor = texture(u_envMap, Renv).rgb;

					vec3 F0 = mix(vec3(0.04), mat.baseColor, mat.metallic);
					vec3 Fenv = fresnelSchlick(max(dot(Nenv, Venv), 0.0), F0);

					// use a softer gloss scaling
					float gloss = 1.0 - mat.roughness;
					gloss = gloss * gloss;

					// clamp env strength for very shiny metals
					float metalEnvScale = mix(0.6, 0.25, mat.metallic);
					float envStrength = u_matEnvStrength * metalEnvScale;

					vec3 envSpec = envColor * Fenv * gloss * envStrength;

					if (hasDecal) {
						envSpec *= 0.15;
					}

					color += envSpec;

					color += envSpec;
				}

				// emissive: albedo (already linearized) is its own glow mask; alpha untouched.
				color += baseSample.rgb * u_emissiveColor * u_emissiveStrength;

				vec3 Nglass = normalize(getNormal());
				vec3 Vglass = normalize(u_cameraPosition - v_worldPosition.xyz);
				if (u_glassMode > 0.5) {

					vec2 screenUV = getScreenUV(v_clipPosition);
					vec2 refractOffset = Nglass.xy * u_sceneTexelSize * u_refractionStrength;
					vec2 refractUV = clamp(screenUV + refractOffset, vec2(0.001), vec2(0.999));

					vec3 sceneBehind = texture(u_sceneColorTexture, refractUV).rgb;

					float NdotV = max(dot(Nglass, Vglass), 0.0);
					vec3 F = fresnelSchlick(NdotV, vec3(0.5));

					float glassTint = hasDecal ? 0.55 : 0.15;
					vec3 transmitted = sceneBehind * mix(vec3(1.0), finalSurfaceColor.rgb, glassTint);
					vec3 glassColor = mix(transmitted, color * 1.0, F);

					if (hasDecal) {
						glassColor = mix(glassColor, finalSurfaceColor.rgb, 1.0);
					}

					outColor = vec4(glassColor, u_matOpacity) * u_colorMult;
				} else {
					outColor = vec4(color, finalSurfaceColor.a * u_matOpacity) * u_colorMult;
				}
			}
		`;
		this.envmapVertexShaderSource = `
			#version 300 es
			in vec4 a_position;
			in vec3 a_normal;

			uniform mat4 u_projection;
			uniform mat4 u_view;
			uniform mat4 u_world;

			out vec3 v_worldPosition;
			out vec3 v_worldNormal;

			void main()
			{
				// Multiply the position by the matrix.
				gl_Position = u_projection * u_view * u_world * a_position;

				// send the view position to the fragment shader
				v_worldPosition = (u_world * a_position).xyz;

				// orient the normals and pass to the fragment shader
				v_worldNormal = mat3(u_world) * a_normal;
			}
		`;
		this.envmapFragmentShaderSource = `
			#version 300 es
			precision highp float;

			// Passed in from the vertex shader.
			in vec3 v_worldPosition;
			in vec3 v_worldNormal;
			// The texture.
			uniform samplerCube u_texture;
			// The position of the camera
			uniform vec3 u_worldCameraPosition;
			// we need to declare an output for the fragment shader
			out vec4 outColor;

			void main()
			{
				vec3 worldNormal = normalize(v_worldNormal);
				vec3 eyeToSurfaceDir = normalize(v_worldPosition - u_worldCameraPosition);
				vec3 direction = reflect(eyeToSurfaceDir,worldNormal);

				outColor = texture(u_texture, direction);
			}
		`;
		this.cubeMapVS = `
			#version 300 es

			in vec4 a_position;
			out vec4 v_position;

			void main()
			{
				v_position = a_position;
				gl_Position = vec4(a_position.xy, 1.0, 1.0);
			}
		`;
		this.cubeMapFS = `
			#version 300 es
			precision highp float;

			uniform samplerCube u_skybox;
			uniform mat4 u_viewDirectionProjectionInverse;

			in vec4 v_position;

			// we need to declare an output for the fragment shader
			out vec4 outColor;

			void main()
			{
				vec4 t = u_viewDirectionProjectionInverse * v_position;
				vec3 dir = normalize(t.xyz / t.w);
				dir.x = -dir.x;
				outColor = texture(u_skybox, dir);
			}
		`;
		this.presentVS = `
			#version 300 es
			out vec2 v_uv;

			void main()
			{
				vec2 pos;
				if (gl_VertexID == 0) {
					pos = vec2(-1.0, -1.0);
				} else if (gl_VertexID == 1) {
					pos = vec2( 3.0, -1.0);
				} else {
					pos = vec2(-1.0,  3.0);
				}

				v_uv = pos * 0.5 + 0.5;
				gl_Position = vec4(pos, 0.0, 1.0);
			}
		`;

		this.presentFS = `
			#version 300 es
			precision highp float;

			in vec2 v_uv;

			uniform sampler2D u_sceneTexture;
			uniform float u_exposure;
			uniform float u_contrast;
			uniform float u_saturation;
			uniform float u_blackPoint;

			out vec4 outColor;

			vec3 ACESFilm(vec3 x)
			{
				const float a = 2.51;
				const float b = 0.03;
				const float c = 2.43;
				const float d = 0.59;
				const float e = 0.14;
				return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);
			}

			vec3 applyContrast(vec3 color, float contrast)
			{
				return clamp((color - 0.5) * contrast + 0.5, 0.0, 1.0);
			}

			vec3 applySaturation(vec3 color, float saturation)
			{
				float luma = dot(color, vec3(0.2126, 0.7152, 0.0722));
				return mix(vec3(luma), color, saturation);
			}

			void main()
			{
				vec3 color = texture(u_sceneTexture, v_uv).rgb;

				// Scene is linear HDR here.
				color *= u_exposure;

				// Filmic tone map
				color = ACESFilm(color);

				// Pull blacks down a bit to fight milky output
				color = max((color - vec3(u_blackPoint)) / (1.0 - u_blackPoint), vec3(0.0));

				// Mild grading controls
				color = applyContrast(color, u_contrast);
				color = applySaturation(color, u_saturation);

				// Final display gamma
				color = pow(color, vec3(1.0 / 2.2));

				outColor = vec4(color, 1.0);
			}
		`;
		this.brightPassVS = this.presentVS;  // reuse fullscreen triangle
		this.brightPassFS = `
			#version 300 es
			precision highp float;

			in vec2 v_uv;

			uniform sampler2D u_sceneTexture;
			uniform float u_threshold;
			uniform float u_softThreshold;

			out vec4 outColor;

			// From LearnOpenGL-style bloom: soft knee threshold.
			vec3 brightPass(vec3 color, float threshold, float softThreshold) {
				float luma = dot(color, vec3(0.2126, 0.7152, 0.0722));
				float knee = threshold * softThreshold;
				float soft = clamp((luma - threshold + knee) / max(knee, 1e-4), 0.0, 1.0);
				float weight = max(luma - threshold, 0.0) + soft;
				return color * weight;
			}

			void main() {
				vec3 color = texture(u_sceneTexture, v_uv).rgb;
				vec3 bright = brightPass(color, u_threshold, u_softThreshold);
				outColor = vec4(bright, 1.0);
			}
		`;

		this.blurVS = this.presentVS;  // fullscreen triangle
		this.blurFS = `
			#version 300 es
			precision highp float;

			in vec2 v_uv;

			uniform sampler2D u_bloomTexture;
			uniform vec2 u_texelSize;
			uniform bool u_horizontal;

			out vec4 outColor;

			// Simple 5-tap Gaussian-ish kernel.
			void main() {
				vec2 offset = u_horizontal ? vec2(u_texelSize.x, 0.0)
										: vec2(0.0, u_texelSize.y);

				vec3 result = vec3(0.0);
				result += texture(u_bloomTexture, v_uv - 2.0 * offset).rgb * 0.06;
				result += texture(u_bloomTexture, v_uv - 1.0 * offset).rgb * 0.24;
				result += texture(u_bloomTexture, v_uv).rgb              * 0.40;
				result += texture(u_bloomTexture, v_uv + 1.0 * offset).rgb * 0.24;
				result += texture(u_bloomTexture, v_uv + 2.0 * offset).rgb * 0.06;

				outColor = vec4(result, 1.0);
			}
		`;
		this.bloomCombineVS = this.presentVS;  // fullscreen triangle
		this.bloomCombineFS = `
			#version 300 es
			precision highp float;

			in vec2 v_uv;

			uniform sampler2D u_sceneTexture;   // original HDR scene
			uniform sampler2D u_bloomTexture;   // blurred bright pass
			uniform float u_exposure;
			uniform float u_contrast;
			uniform float u_saturation;
			uniform float u_blackPoint;
			uniform float u_bloomStrength;

			out vec4 outColor;

			vec3 ACESFilm(vec3 x)
			{
				const float a = 2.51;
				const float b = 0.03;
				const float c = 2.43;
				const float d = 0.59;
				const float e = 0.14;
				return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);
			}

			vec3 applyContrast(vec3 color, float contrast)
			{
				return clamp((color - 0.5) * contrast + 0.5, 0.0, 1.0);
			}

			vec3 applySaturation(vec3 color, float saturation)
			{
				float luma = dot(color, vec3(0.2126, 0.7152, 0.0722));
				return mix(vec3(luma), color, saturation);
			}

			void main()
			{
				// HDR scene
				vec3 color = texture(u_sceneTexture, v_uv).rgb;

				// Bloom already in HDR space
				vec3 bloom = texture(u_bloomTexture, v_uv).rgb * u_bloomStrength;

				color += bloom;

				color *= u_exposure;
				color = ACESFilm(color);
				color = max((color - vec3(u_blackPoint)) / (1.0 - u_blackPoint), vec3(0.0));
				color = applyContrast(color, u_contrast);
				color = applySaturation(color, u_saturation);
				color = pow(color, vec3(1.0 / 2.2));

				outColor = vec4(color, 1.0);
			}
		`;
		// Dedicated GPU light-point / particle path. Batched GL_POINTS, additive,
		// HDR color so the existing bloom pipeline picks the points up as glow.
		// a_position.xyz = world position, a_position.w = world-space point size.
		// a_color.rgb    = HDR color (already premultiplied by intensity, may exceed 1).
		// a_color.a      = alpha fade.
		this.particleVS = `
			#version 300 es
			in vec4 a_position;   // xyz = world pos, w = world size
			in vec4 a_color;      // rgb = HDR color * intensity, a = alpha

			uniform mat4 u_projection;
			uniform mat4 u_view;
			uniform float u_sizeScale;      // projection[5] * viewportHeight * 0.5
			uniform float u_maxPointSize;

			// ---- bounded analytic fog transmittance to the particle CENTER ----
			// Mirrors the volumetric fog's density model (base density + finite ellipsoid
			// pockets) but integrated per-POINT (not per-fragment) with a small fixed step
			// budget along the camera -> particle segment, so the glow is attenuated by the
			// fog that actually lies on its OWN path (never the full background depth) at a
			// cost of a handful of iterations per point. Noise/warp/moon are intentionally
			// omitted (per-point, must stay cheap); the smooth ellipsoid mask + Beer-Lambert
			// transmittance are the same shape the composite uses, so a point in front of the
			// fog stays bright, one inside a pocket is partially attenuated, and one behind a
			// dense pocket is strongly attenuated. Documented approximation, not background fog.
			#define DW_PFOG_MAX_POCKETS 8
			#define DW_PFOG_STEPS 10
			uniform int   u_fogEnabled;                          // 0 = pass-through (T=1)
			uniform vec3  u_fogCameraPos;                        // world-space camera position
			uniform float u_fogDensity;                          // base fog density (sigma)
			uniform float u_fogMaxDistance;                      // clamp the integrated path
			uniform int   u_fogPocketCount;                      // 0 => homogeneous base density
			uniform vec3  u_fogPocketCenters[DW_PFOG_MAX_POCKETS];
			uniform vec3  u_fogPocketRadii[DW_PFOG_MAX_POCKETS];
			uniform float u_fogPocketFeathers[DW_PFOG_MAX_POCKETS];
			uniform float u_fogPocketDensity[DW_PFOG_MAX_POCKETS];

			out vec4 v_color;
			out float v_fogT;   // 1.0 = unfogged, 0.0 = fully occluded by fog

			float dwParticleFogTransmittance(vec3 P)
			{
				vec3 toP = P - u_fogCameraPos;
				float dist = length(toP);
				if (dist < 1.0e-4) { return 1.0; }
				vec3 dir = toP / dist;
				float marchLen = min(dist, u_fogMaxDistance);
				float segLen = marchLen / float(DW_PFOG_STEPS);
				float optical = 0.0;
				for (int i = 0; i < DW_PFOG_STEPS; i++) {
					float t = (float(i) + 0.5) * segLen;
					vec3 wpos = u_fogCameraPos + dir * t;
					float sigma;
					if (u_fogPocketCount <= 0) {
						sigma = max(u_fogDensity, 0.0);        // constant/weather fallback: homogeneous
					} else {
						sigma = 0.0;
						for (int pj = 0; pj < DW_PFOG_MAX_POCKETS; pj++) {
							if (pj >= u_fogPocketCount) { break; }
							vec3 radii = max(u_fogPocketRadii[pj], vec3(1.0e-4));
							vec3 q = (wpos - u_fogPocketCenters[pj]) / radii;
							float nd = length(q);
							float feather = clamp(u_fogPocketFeathers[pj], 1.0e-3, 1.0);
							float mask = 1.0 - smoothstep(1.0 - feather, 1.0, nd);
							float dScale = max(u_fogPocketDensity[pj], 0.0);
							sigma += max(u_fogDensity * dScale * mask, 0.0);
						}
					}
					optical += sigma * segLen;
				}
				return exp(-optical);
			}

			void main()
			{
				vec4 viewPos = u_view * vec4(a_position.xyz, 1.0);
				gl_Position  = u_projection * viewPos;

				// perspective point size: shrink with view-space distance.
				float dist = max(-viewPos.z, 0.0001);
				float size = u_sizeScale * a_position.w / dist;
				gl_PointSize = clamp(size, 1.0, u_maxPointSize);

				v_color = a_color;
				v_fogT  = (u_fogEnabled == 1) ? dwParticleFogTransmittance(a_position.xyz) : 1.0;
			}
		`;
		this.particleFS = `
			#version 300 es
			precision highp float;

			in vec4 v_color;
			in float v_fogT;   // bounded analytic fog transmittance to this point's center
			out vec4 outColor;

			void main()
			{
				// soft radial glow from the point sprite center.
				vec2 pc = gl_PointCoord * 2.0 - 1.0;
				float r2 = dot(pc, pc);
				if (r2 > 1.0) {
					discard;
				}
				float falloff = 1.0 - r2;
				falloff = falloff * falloff;   // softer, rounder core

				// RGB stays pure HDR (>1 allowed) so bloom sees the bright cores;
				// the blend factor (SRC_ALPHA, ONE) applies the fade, so lifecycle
				// alpha and radial falloff both live in the output alpha. Net screen
				// contribution = rgb * (alpha * falloff).
				// Bounded analytic fog attenuation on this point's OWN camera->center path:
				// scales the additive HDR glow by transmittance so a point behind dense fog
				// cannot punch bright over geometry, while a point in front stays untouched
				// (v_fogT == 1.0 when fog is disabled -> byte-for-byte the original output).
				outColor = vec4(v_color.rgb * v_fogT, v_color.a * falloff);
			}
		`;
		this.colorProgramInfo		= 0;
		this.standardPBRShaderProgramInfo	= 0;
		this.cubeMapProgramInfo		= 0;
		this.presentProgramInfo = 0;
		this.fullscreenVAO = null;

		// particle path resources (created in createShaders)
		this.particleProgramInfo	= 0;
		this.particleVAO			= null;
		this.particleVBO			= null;
		this.particleMax			= 0;
		this.particleStrideFloats	= 8;   // vec4 position + vec4 color
	}

	static gfx 					= [];
	static currentGfx 			= -1;
	static checkerboardTexture	= null;

	static sceneFramebuffer     	= null;
	static sceneColorTexture    	= null;
	// Sole owner of the sampleable scene-depth texture wrapper. createSceneFrameBuffer is
	// the only writer; it creates/attaches/deletes it. Consumers (fog) never store their own
	// handle -- they call getRenderSceneDepthTexture() at render time. No duplicate long-lived
	// reference to the same GPU depth texture exists anywhere else.
	static sceneDepthTexture    	= null;
	static sceneDepthRenderbuffer 	= null;

	static depthFramebuffer     = null;

	static extColorBufferFloat  = null;

	static bloomTextureA 		= null;
	static bloomTextureB 		= null;
	static bloomFramebufferA 	= null;
	static bloomFramebufferB 	= null;
	static sceneColorTex 		= null;
	static sceneFBO 			= null;
	static sceneDepthRB 		= null;
	init(canvasIDName)
	{
		dwGfx.currentGfx = dwGfx.gfx.length;
		dwGfx.gfx.push(new dwGLGfx());
		dwGfx.gfx[dwGfx.currentGfx].canvas = document.getElementById(canvasIDName);
		dwGfx.gfx[dwGfx.currentGfx].gl = dwGfx.gfx[dwGfx.currentGfx].canvas.getContext('webgl2');
		if (!dwGfx.gl()) {
			alert("dwGfx::init: Could not make GL handle.");
			return;
		}

		dwGfx.extColorBufferFloat = dwGfx.gl().getExtension("EXT_color_buffer_float");

		dwGfx.checkerboardTexture = new dwGfxTexture();
		dwGfx.checkerboardTexture.createCheckerboardTexture();
	}
	static createSceneTargets(w, h)
	{
		const gl = dwGfx.gl();

		if (dwGfx.sceneColorTexture && dwGfx.sceneColorTexture.img && dwGfx.sceneColorTexture.img.drawInfo && dwGfx.sceneColorTexture.img.drawInfo.texture) {
			gl.deleteTexture(dwGfx.sceneColorTexture.img.drawInfo.texture);
		}
		if (dwGfx.sceneDepthRB) {
			gl.deleteRenderbuffer(dwGfx.sceneDepthRB);
		}
		if (dwGfx.sceneFBO) {
			gl.deleteFramebuffer(dwGfx.sceneFBO);
		}

		dwGfx.sceneColorTexture = new dwGfxTexture();
		dwGfx.sceneColorTexture.createColorBufferTexture(w, h, 1, 1);

		dwGfx.sceneFBO = gl.createFramebuffer();
		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFBO);

		gl.framebufferTexture2D(
			gl.FRAMEBUFFER,
			gl.COLOR_ATTACHMENT0,
			gl.TEXTURE_2D,
			dwGfx.sceneColorTexture.img.drawInfo.texture,
			0
		);

		dwGfx.sceneDepthRB = gl.createRenderbuffer();
		gl.bindRenderbuffer(gl.RENDERBUFFER, dwGfx.sceneDepthRB);
		gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT16, w, h);
		gl.framebufferRenderbuffer(
			gl.FRAMEBUFFER,
			gl.DEPTH_ATTACHMENT,
			gl.RENDERBUFFER,
			dwGfx.sceneDepthRB
		);

		const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
		console.log("scene fbo status =", status);

		gl.bindRenderbuffer(gl.RENDERBUFFER, null);
		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
	}
	static createSceneFrameBuffer(colorTextureObj, depthTextureObj = null)
	{
		const gl = dwGfx.gl();

		if (!colorTextureObj || !colorTextureObj.img || !gl.isTexture(colorTextureObj.img.drawInfo.texture)) {
			throw new Error("createSceneFrameBuffer: invalid color texture object");
		}

		const colorTexture = colorTextureObj.img.drawInfo.texture;
		const width = colorTextureObj.img.drawInfo.width;
		const height = colorTextureObj.img.drawInfo.height;

		// Owner replaces resources in place: delete the previously owned scene-depth
		// texture / renderbuffer / framebuffer before creating their replacements, so no
		// stale GPU object survives a resize/recreation. Consumers hold no depth handle of
		// their own; they re-query getRenderSceneDepthTexture() after recreation.
		if (dwGfx.sceneDepthTexture && dwGfx.sceneDepthTexture.img && dwGfx.sceneDepthTexture.img.drawInfo && gl.isTexture(dwGfx.sceneDepthTexture.img.drawInfo.texture)) {
			gl.deleteTexture(dwGfx.sceneDepthTexture.img.drawInfo.texture);
		}
		if (dwGfx.sceneDepthRenderbuffer) {
			gl.deleteRenderbuffer(dwGfx.sceneDepthRenderbuffer);
		}
		if (dwGfx.sceneFramebuffer) {
			gl.deleteFramebuffer(dwGfx.sceneFramebuffer);
		}

		dwGfx.sceneColorTexture = colorTextureObj;
		// sceneDepthTexture is set in the texture branch only (null in the renderbuffer
		// branch) so the fog can never sample a depth texture that was never rendered into.
		dwGfx.sceneDepthTexture = null;
		dwGfx.sceneDepthRenderbuffer = null;

		dwGfx.sceneFramebuffer = gl.createFramebuffer();
		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);

		gl.framebufferTexture2D(
			gl.FRAMEBUFFER,
			gl.COLOR_ATTACHMENT0,
			gl.TEXTURE_2D,
			colorTexture,
			0
		);

		if (depthTextureObj && depthTextureObj.img && gl.isTexture(depthTextureObj.img.drawInfo.texture)) {
			const depthHandle = depthTextureObj.img.drawInfo.texture;
			gl.framebufferTexture2D(
				gl.FRAMEBUFFER,
				gl.DEPTH_ATTACHMENT,
				gl.TEXTURE_2D,
				depthHandle,
				0
			);
			dwGfx.sceneDepthTexture = depthTextureObj;
		} else {
			dwGfx.sceneDepthRenderbuffer = gl.createRenderbuffer();
			gl.bindRenderbuffer(gl.RENDERBUFFER, dwGfx.sceneDepthRenderbuffer);
			gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT16, width, height);
			gl.framebufferRenderbuffer(
				gl.FRAMEBUFFER,
				gl.DEPTH_ATTACHMENT,
				gl.RENDERBUFFER,
				dwGfx.sceneDepthRenderbuffer
			);
			gl.bindRenderbuffer(gl.RENDERBUFFER, null);
		}

		gl.drawBuffers([gl.COLOR_ATTACHMENT0]);

		const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
		if (status !== gl.FRAMEBUFFER_COMPLETE) {
			throw new Error("Scene framebuffer incomplete: " + status);
		}

		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
	}
	// Read-only accessor to the currently owned scene-depth attachment. Returns the EXACT
	// WebGLTexture attached to the scene framebuffer's DEPTH_ATTACHMENT, queried live from the
	// FBO, WITHOUT transferring ownership: the caller must not store or delete it -- dwGfx
	// remains responsible for its replacement/deletion. Returns null when depth is a
	// renderbuffer (fog-disabled path) or nothing is attached. There is one scene target, so
	// index must be 0. createSceneFrameBuffer is the only writer, so this query can never
	// diverge from what was rendered that frame.
	static getRenderSceneDepthTexture(index = 0)
	{
		const gl = dwGfx.gl();
		if (!gl || index !== 0 || !dwGfx.sceneFramebuffer) {
			return null;
		}
		const prevFBO = gl.getParameter(gl.FRAMEBUFFER_BINDING);
		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);
		let handle = null;
		const type = gl.getFramebufferAttachmentParameter(
			gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
		if (type === gl.TEXTURE) {
			handle = gl.getFramebufferAttachmentParameter(
				gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME);
		}
		gl.bindFramebuffer(gl.FRAMEBUFFER, prevFBO);
		return (handle && gl.isTexture(handle)) ? handle : null;
	}
	static createBloomTargets(width, height)
	{
		const gl = dwGfx.gl();
		const w = Math.max(1, (width  / 2) | 0);
		const h = Math.max(1, (height / 2) | 0);

		// Create HDR-ish color textures for bloom
		const texA = new dwGfxTexture();
		texA.createColorBufferTexture(w, h, 1, 1);
		const texB = new dwGfxTexture();
		texB.createColorBufferTexture(w, h, 1, 1);

		dwGfx.bloomTextureA = texA;
		dwGfx.bloomTextureB = texB;

		const fbA = gl.createFramebuffer();
		gl.bindFramebuffer(gl.FRAMEBUFFER, fbA);
		gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texA.img.drawInfo.texture, 0);
		gl.drawBuffers([gl.COLOR_ATTACHMENT0]);
		if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
			throw new Error("Bloom framebuffer A incomplete");
		}

		const fbB = gl.createFramebuffer();
		gl.bindFramebuffer(gl.FRAMEBUFFER, fbB);
		gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texB.img.drawInfo.texture, 0);
		gl.drawBuffers([gl.COLOR_ATTACHMENT0]);
		if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
			throw new Error("Bloom framebuffer B incomplete");
		}

		gl.bindFramebuffer(gl.FRAMEBUFFER, null);

		dwGfx.bloomFramebufferA = fbA;
		dwGfx.bloomFramebufferB = fbB;
	}
	static createDepthBuffer(depthTexture)
	{
		const gl = dwGfx.gl();

		if (!depthTexture || !gl.isTexture(depthTexture)) {
			throw new Error("createDepthBuffer: invalid depth texture");
		}

		dwGfx.depthFramebuffer = gl.createFramebuffer();
		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.depthFramebuffer);

		gl.framebufferTexture2D(
			gl.FRAMEBUFFER,
			gl.DEPTH_ATTACHMENT,
			gl.TEXTURE_2D,
			depthTexture,
			0
		);

		gl.drawBuffers([gl.NONE]);
		gl.readBuffer(gl.NONE);

		const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
		if (status !== gl.FRAMEBUFFER_COMPLETE) {
			throw new Error("Depth framebuffer incomplete: " + status);
		}

		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
	}
	// Read-only accessor to the authoritative directional shadow depth attachment (Step 5B).
	// Returns the EXACT WebGLTexture attached to dwGfx.depthFramebuffer's DEPTH_ATTACHMENT,
	// queried LIVE from the FBO -- deliberately NOT a separately stored handle, so it can never
	// diverge from what the shadow pass renders into (the same single-source-of-truth discipline
	// as getRenderSceneDepthTexture). Ownership is NOT transferred: the caller must not store or
	// delete it. Returns null when no depth framebuffer exists or its attachment is not a texture.
	static getShadowDepthTexture()
	{
		const gl = dwGfx.gl();
		if (!gl || !dwGfx.depthFramebuffer) {
			return null;
		}
		const prevFBO = gl.getParameter(gl.FRAMEBUFFER_BINDING);
		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.depthFramebuffer);
		let handle = null;
		const type = gl.getFramebufferAttachmentParameter(
			gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
		if (type === gl.TEXTURE) {
			handle = gl.getFramebufferAttachmentParameter(
				gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME);
		}
		gl.bindFramebuffer(gl.FRAMEBUFFER, prevFBO);
		return (handle && gl.isTexture(handle)) ? handle : null;
	}
	presentSceneTexture(
		textureObj = null,
		exposure = 0.95,
		contrast = 1.08,
		saturation = 1.06,
		blackPoint = 0.02,
		bloomThreshold = 1.0,
		bloomSoftThreshold = 0.5,
		bloomStrength = 0.8,
		bloomIterations = 3
	)
	{
		const gl = dwGfx.gl();
		const texObj = textureObj || dwGfx.sceneColorTexture;

		if (!texObj || !texObj.isReady) {
			return;
		}

		this.runBloomPass(texObj, bloomThreshold, bloomSoftThreshold, bloomIterations);

		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);

		gl.useProgram(this.bloomCombineProgramInfo.program);
		gl.disable(gl.DEPTH_TEST);
		gl.depthMask(false);
		gl.disable(gl.BLEND);

		gl.bindVertexArray(this.fullscreenVAO);

		twgl.setUniforms(this.bloomCombineProgramInfo, {
			u_sceneTexture: texObj.img.drawInfo.texture,
			u_bloomTexture: dwGfx.bloomTextureA.img.drawInfo.texture,
			u_exposure: exposure,
			u_contrast: contrast,
			u_saturation: saturation,
			u_blackPoint: blackPoint,
			u_bloomStrength: bloomStrength,
		});

		gl.drawArrays(gl.TRIANGLES, 0, 3);

		gl.bindVertexArray(null);
		gl.depthMask(true);
	}
	runBloomPass(sceneTexture, threshold = 1.0, softThreshold = 0.5, iterations = 2)
	{
		const gl = dwGfx.gl();
		if (!dwGfx.bloomTextureA || !dwGfx.bloomTextureB) {
			return;
		}

		const w = dwGfx.bloomTextureA.img.drawInfo.width;
		const h = dwGfx.bloomTextureA.img.drawInfo.height;

		gl.disable(gl.DEPTH_TEST);
		gl.depthMask(false);
		gl.disable(gl.BLEND);

		gl.bindVertexArray(this.fullscreenVAO);

		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.bloomFramebufferA);
		gl.viewport(0, 0, w, h);
		gl.useProgram(this.brightPassProgramInfo.program);

		twgl.setUniforms(this.brightPassProgramInfo, {
			u_sceneTexture: sceneTexture.img.drawInfo.texture,
			u_threshold: threshold,
			u_softThreshold: softThreshold,
		});

		gl.drawArrays(gl.TRIANGLES, 0, 3);

		gl.useProgram(this.blurProgramInfo.program);

		for (let i = 0; i < iterations; ++i) {
			gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.bloomFramebufferB);
			gl.viewport(0, 0, w, h);

			twgl.setUniforms(this.blurProgramInfo, {
				u_bloomTexture: dwGfx.bloomTextureA.img.drawInfo.texture,
				u_texelSize: [1.0 / w, 1.0 / h],
				u_horizontal: true,
			});

			gl.drawArrays(gl.TRIANGLES, 0, 3);

			gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.bloomFramebufferA);
			gl.viewport(0, 0, w, h);

			twgl.setUniforms(this.blurProgramInfo, {
				u_bloomTexture: dwGfx.bloomTextureB.img.drawInfo.texture,
				u_texelSize: [1.0 / w, 1.0 / h],
				u_horizontal: false,
			});

			gl.drawArrays(gl.TRIANGLES, 0, 3);
		}

		gl.bindVertexArray(null);
		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
		gl.depthMask(true);
	}
	presentSceneTextureRaw(textureObj = null)
	{
		const gl = dwGfx.gl();
		const texObj = textureObj || dwGfx.sceneColorTexture;

		if (!texObj || !texObj.isReady) {
			return;
		}

		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);

		gl.useProgram(this.presentProgramInfo.program);
		gl.disable(gl.DEPTH_TEST);
		gl.depthMask(false);
		gl.disable(gl.BLEND);

		gl.bindVertexArray(this.fullscreenVAO);

		twgl.setUniforms(this.presentProgramInfo, {
			u_sceneTexture: texObj.img.drawInfo.texture,
			u_exposure: 1.0,
			u_contrast: 1.0,
			u_saturation: 1.0,
			u_blackPoint: 0.0,
		});

		gl.drawArrays(gl.TRIANGLES, 0, 3);

		gl.bindVertexArray(null);
		gl.depthMask(true);
	}
	createShaders()
	{
		const programOptions = {
			attribLocations: {
				'a_position': 0,
				'a_normal':   1,
				'a_texcoord': 2,
				'a_tangent':  3,
				'a_color':    4,
			},
		};

		this.colorProgramInfo       	= twgl.createProgramInfo(dwGfx.gl(), [this.colorVS, this.colorFS], programOptions);
		this.standardPBRShaderProgramInfo	= twgl.createProgramInfo(dwGfx.gl(), [this.standardPBRVS, this.standardPBRFS], programOptions);
		this.cubeMapProgramInfo     	= twgl.createProgramInfo(dwGfx.gl(), [this.cubeMapVS, this.cubeMapFS], programOptions);
		this.presentProgramInfo			= twgl.createProgramInfo(dwGfx.gl(), [this.presentVS, this.presentFS], programOptions);

		this.brightPassProgramInfo		= twgl.createProgramInfo(dwGfx.gl(), [this.brightPassVS, this.brightPassFS], programOptions);
		this.blurProgramInfo			= twgl.createProgramInfo(dwGfx.gl(), [this.blurVS, this.blurFS], programOptions);
		this.bloomCombineProgramInfo	= twgl.createProgramInfo(dwGfx.gl(), [this.bloomCombineVS, this.bloomCombineFS], programOptions);

		this.particleProgramInfo		= twgl.createProgramInfo(dwGfx.gl(), [this.particleVS, this.particleFS], programOptions);

		twgl.setAttributePrefix("a_");

		this.fullscreenVAO = dwGfx.gl().createVertexArray();

		this.createParticleResources();
	}
	// Allocate the dynamic GL_POINTS batch buffer + VAO. One interleaved buffer:
	// [px, py, pz, size, r, g, b, a] per point (a_position vec4 + a_color vec4).
	createParticleResources(maxParticles = 4096)
	{
		const gl = dwGfx.gl();

		this.particleMax = maxParticles;
		this.particleData = new Float32Array(maxParticles * this.particleStrideFloats);

		this.particleVAO = gl.createVertexArray();
		this.particleVBO = gl.createBuffer();

		gl.bindVertexArray(this.particleVAO);
		gl.bindBuffer(gl.ARRAY_BUFFER, this.particleVBO);
		gl.bufferData(gl.ARRAY_BUFFER, this.particleData.byteLength, gl.DYNAMIC_DRAW);

		const stride = this.particleStrideFloats * 4;   // bytes
		gl.enableVertexAttribArray(0);                  // a_position (vec4)
		gl.vertexAttribPointer(0, 4, gl.FLOAT, false, stride, 0);
		gl.enableVertexAttribArray(4);                  // a_color (vec4)
		gl.vertexAttribPointer(4, 4, gl.FLOAT, false, stride, 16);

		gl.bindVertexArray(null);
		gl.bindBuffer(gl.ARRAY_BUFFER, null);
	}
	// Draw a batch of light points. `data` is a Float32Array laid out as above,
	// `count` is the number of points. Uses the existing camera view/projection
	// convention (view = inverse(cameraView.worldMatrix)).
	//
	// Render state is fully self-contained: every GL state this method touches is
	// captured up front and restored on exit (blend enable + separate factors,
	// depth test enable, depth write mask, cull enable, bound program/VAO/buffer).
	// Nothing is left for a later pass to reset.
	//
	// Blend: SRC_ALPHA, ONE (additive that respects source alpha). The FS keeps
	// rgb as pure HDR and folds lifecycle alpha * radial falloff into the output
	// alpha, so the on-screen contribution is rgb * (alpha * falloff) — head bright,
	// trail samples dimmer/smaller, everything fading to nothing as alpha -> 0.
	// fogParams (optional): { cameraPos:[x,y,z], density, maxDistance, pocketCount,
	// pocketCenters:Float32Array(count*3), pocketRadii:Float32Array(count*3),
	// pocketFeathers:Float32Array(count), pocketDensity:Float32Array(count) }. When
	// present the VS integrates a bounded analytic transmittance to each point CENTER
	// and the FS scales the additive glow by it (per-point, NOT the background depth,
	// NOT a per-fragment march). Omit / pass null to keep the glow unfogged.
	drawParticles(cameraView, data, count, fogParams)
	{
		if (!count || count <= 0) {
			return;
		}
		const gl = dwGfx.gl();
		const programInfo = this.particleProgramInfo;

		if (count > this.particleMax) {
			count = this.particleMax;
		}

		// ---- capture prior GL state ----
		const prevProgram	= gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO		= gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArrayBuf	= gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		const prevBlend		= gl.isEnabled(gl.BLEND);
		const prevDepthTest	= gl.isEnabled(gl.DEPTH_TEST);
		const prevDepthFunc	= gl.getParameter(gl.DEPTH_FUNC);
		const prevCull		= gl.isEnabled(gl.CULL_FACE);
		const prevDepthMask	= gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevSrcRGB	= gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB	= gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcAlpha	= gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstAlpha	= gl.getParameter(gl.BLEND_DST_ALPHA);

		const viewMatrix = m4.inverse(cameraView.worldMatrix);
		const projectionMatrix = cameraView.projectionMatrix;

		// world-size -> pixel-size factor for gl_PointSize (perspective).
		const sizeScale = projectionMatrix[5] * gl.canvas.height * 0.5;

		gl.useProgram(programInfo.program);
		twgl.setUniforms(programInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_sizeScale: sizeScale,
			u_maxPointSize: 1024.0,
		});

		// ---- bounded analytic per-point fog transmittance uniforms ----
		// Enabled only when fogParams is supplied; otherwise u_fogEnabled=0 makes the
		// VS emit v_fogT=1.0 (byte-for-byte the pre-fog additive glow).
		if (fogParams && fogParams.pocketCount !== undefined) {
			twgl.setUniforms(programInfo, {
				u_fogEnabled:       1,
				u_fogCameraPos:     fogParams.cameraPos || [0, 0, 0],
				u_fogDensity:       (fogParams.density !== undefined) ? fogParams.density : 0.0,
				u_fogMaxDistance:   (fogParams.maxDistance !== undefined) ? fogParams.maxDistance : 1.0e6,
				u_fogPocketCount:   fogParams.pocketCount | 0,
				u_fogPocketCenters: fogParams.pocketCenters,
				u_fogPocketRadii:   fogParams.pocketRadii,
				u_fogPocketFeathers: fogParams.pocketFeathers,
				u_fogPocketDensity: fogParams.pocketDensity,
			});
		} else {
			twgl.setUniforms(programInfo, { u_fogEnabled: 0 });
		}

		// additive-with-alpha glow; keep depth test so points hide behind opaque
		// geometry (incl. the alpha-tested logo silhouette in the scene depth), but
		// never write depth so overlapping points all contribute. depthFunc is set
		// explicitly (LEQUAL) so occlusion never depends on inherited caller state.
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
		gl.enable(gl.DEPTH_TEST);
		gl.depthFunc(gl.LEQUAL);
		gl.depthMask(false);
		gl.disable(gl.CULL_FACE);

		gl.bindVertexArray(this.particleVAO);
		gl.bindBuffer(gl.ARRAY_BUFFER, this.particleVBO);
		gl.bufferSubData(gl.ARRAY_BUFFER, 0, data, 0, count * this.particleStrideFloats);

		gl.drawArrays(gl.POINTS, 0, count);

		// ---- restore prior GL state exactly ----
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArrayBuf);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);

		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
		if (prevBlend) { gl.enable(gl.BLEND); } else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		gl.depthFunc(prevDepthFunc);
		if (prevCull) { gl.enable(gl.CULL_FACE); } else { gl.disable(gl.CULL_FACE); }
		gl.depthMask(prevDepthMask);
	}
	static beginRenderSceneFrameBuffer(clear = 1)
	{
		const gl = dwGfx.gl();

		if (!dwGfx.sceneFramebuffer || !dwGfx.sceneColorTexture) {
			throw new Error("beginRenderSceneFrameBuffer: scene framebuffer not created");
		}

		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);
		gl.viewport(
			0,
			0,
			dwGfx.sceneColorTexture.img.drawInfo.width,
			dwGfx.sceneColorTexture.img.drawInfo.height
		);

		if (clear) {
			// DEPTH_BUFFER_BIT clears are gated by depthMask; a stale depthMask(false)
			// (left by a prior Transparency/CubeMap pass) would silently skip the depth
			// clear and leave the scene depth texture uninitialized. Force it true here.
			// clearDepth is set explicitly to 1.0 (far): the fog's sky test maps raw
			// depth >= 0.9999 to u_maxDistance, so a background that is not exactly 1.0
			// would reconstruct to a near distance and make outside fog collapse. Do not
			// rely on the GL default surviving other passes.
			gl.depthMask(true);
			gl.clearDepth(1.0);
			gl.clearColor(0.0, 0.0, 0.0, 1.0);
			gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
		}
	}

	static endRenderSceneFrameBuffer()
	{
		const gl = dwGfx.gl();
		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
	}

	static beginRenderDepthBuffer(depthTextureSize = 512)
	{
		const gl = dwGfx.gl();
		gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.depthFramebuffer);
		gl.viewport(0, 0, depthTextureSize, depthTextureSize);
		gl.clear(gl.DEPTH_BUFFER_BIT);
	}

	static endRenderDepthBuffer()
	{
		const gl = dwGfx.gl();
		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
	}
	static beginRenderScene(clear = 1)
	{
		const gl = dwGfx.gl();
		//console.log("canvas size:", gl.canvas.width, gl.canvas.height);
		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);

		if (clear) {
			gl.clearColor(0.9, 0.9, 0.9, 1.0);
			gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
		}
	}
	static endRenderScene()
	{
	}
	applyStandardPBR(programInfo, projectionMatrix, cameraView, lightView, bias, cubeMapTex)
	{
		var tex 	= dwGfx.checkerboardTexture.img.drawInfo.texture;
		var texCT 	= dwGfx.checkerboardTexture.img.drawInfo.texture;

		const cameraMatrix = cameraView.worldMatrix;
		const viewMatrix = m4.inverse(cameraMatrix);
		dwGfx.gl().useProgram(programInfo.program);

		const cameraPos = cameraMatrix.slice(12, 15);
		const t = dwGetTime() * 0.001;

		// layered smooth flicker
		const flicker =
			0.55 +
			0.25 * Math.sin(t * 7.3) +
			0.12 * Math.sin(t * 13.7 + 1.9) +
			0.08 * Math.sin(t * 23.1 + 4.2);

		// small flame sway
		const flameX = 0.04 * Math.sin(t * 5.1);
		const flameY = 0.02 * Math.sin(t * 8.7 + 0.8);
		const flameZ = 0.03 * Math.sin(t * 6.3 + 2.1);

		// choose a world-space candle position
		const candleBasePos = [0.0, 1.2, 2.0];

		const pointPos = [
			candleBasePos[0] + flameX,
			candleBasePos[1] + flameY,
			candleBasePos[2] + flameZ,
		];

		const pointIntensity = 2.5 + flicker * 1.5;
		const pointRange = 4.5 + flicker * 0.8;
		const pointColor = [1.0, 0.72 + flicker * 0.06, 0.38 + flicker * 0.04];
		const pointLightRange = 3.2 + flicker * 0.5;

		let worldMatrix = m4.translation(0, 0, 0);
		let invTransModelMatrix = m4.inverse(worldMatrix);
		invTransModelMatrix = m4.transpose(invTransModelMatrix);

		const sw = dwGfx.sceneColorTexture.img.drawInfo.width;
		const sh = dwGfx.sceneColorTexture.img.drawInfo.height;
		twgl.setUniforms(programInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_world: worldMatrix,
			u_colorMult: [1, 1, 1, 1],
			u_world: worldMatrix,
			u_inverseTransposeModelMatrix: invTransModelMatrix,
			u_texture0: tex,
			u_texture1: tex,
			u_cameraPosition: cameraPos,

			// decal texture
			u_useDecalLayer: false,
			u_decalColor: [1.0, 1.0, 1.0, 1.0],
			u_decalAlpha: 1.0,

			// static directional light
			u_dirLightDirection: [0.0, 0.0, -1.0],
			u_dirLightColor: [1.0, 0.95, 0.95],
			u_dirLightIntensity: 1.0,

			// camera spotlight
			u_useCameraSpotLight: true,
			u_cameraSpotLightPosition: cameraPos,
			u_cameraSpotLightDirection: cameraView.viewDirection,
			u_cameraSpotLightColor: [1.0, 0.98, 0.96],
			u_cameraSpotLightIntensity: 6.0,
			u_cameraSpotLightInnerCutoff: Math.cos(dwGfxMath.DEG_TO_RAD_FACTOR * 15.0),
			u_cameraSpotLightOuterCutoff: Math.cos(dwGfxMath.DEG_TO_RAD_FACTOR * 22.0),
			u_cameraSpotLightRange: -8.0,

			// point light
			u_usePointLight: false,
			u_pointLightPosition: pointPos,
			u_pointLightColor: pointColor,
			u_pointLightIntensity: pointIntensity,
			u_pointLightRange: pointLightRange,

			// environment map
			u_envMap: cubeMapTex.img.drawInfo.texture,
    		u_envLod: 0.0,

			// Transparency & glass
			u_glassMode: 0.0,
			u_sceneColorTexture: texCT,
			u_sceneTexelSize: [1.0 / sw, 1.0 / sh],
			u_refractionStrength: 30.0,

			u_decalBrightness: 1.0,
			u_decalContrast: 1.0,
			u_decalAlphaMul: 1.0,
			u_normalStrength: 1.0,

			// emissive off by default so it never leaks between materials/draws
			u_emissiveColor: [0.0, 0.0, 0.0],
			u_emissiveStrength: 0.0,

			// alpha cutout disabled by default; only materials that opt in (e.g. the
			// blended logo that must also write depth) set u_matAlphaCutoff > 0.
			u_matAlphaCutoff: 0.0,
		});
	}
	applyDecal(programInfo, projectionMatrix, cameraView, textureMatrix, lightWorldMatrix)
	{
		var tex0 = dwGfx.checkerboardTexture.img.drawInfo.texture;
		var tex1 = dwGfx.checkerboardTexture.img.drawInfo.texture;
		var tex2 = dwGfx.checkerboardTexture.img.drawInfo.texture;
		const cameraMatrix = cameraView.worldMatrix;
		const viewMatrix = m4.inverse(cameraMatrix);
		dwGfx.gl().useProgram(programInfo.program);

		let worldMatrix = m4.translation(0, 0, 0);
		let invTransModelMatrix = m4.inverse(worldMatrix);
		invTransModelMatrix = m4.transpose(invTransModelMatrix);
		const cameraPos = cameraMatrix.slice(12, 15);

		twgl.setUniforms(programInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_world: worldMatrix,
			u_inverseTransposeModelMatrix: invTransModelMatrix,
			u_colorMult: [1, 1, 1, 1],
			u_texture0: tex0,
			u_texture1: tex1,
			u_cameraPosition: cameraPos,

			u_useDecalLayer: true,
			u_textureMatrix: textureMatrix,
			u_decalTexture: tex2,
			u_decalColor: [1.0, 1.0, 1.0, 1.0],
			u_decalAlpha: 1.0,
			u_decalReverseLightDirection: lightWorldMatrix.slice(8, 11),
		});
	}
	applyDirectionalLight(programInfo, intensity=0.5, direction=[0.0,-1.0,0.0], color=[1.0,1.0,1.0])
	{
		twgl.setUniforms(programInfo, {
			// static directional light
			u_dirLightDirection: direction,
			u_dirLightColor: color,
			u_dirLightIntensity: intensity,
		});
	}
	applySpotLight(programInfo, view, range=30.0, intensity=8.0, color=[1.0, 1.0, 1.0], innerCutoffDegrees=12.5, outerCutoffDegrees=20.0)
	{
		const cameraMatrix = view.worldMatrix;
		const viewMatrix = m4.inverse(cameraMatrix);
		dwGfx.gl().useProgram(programInfo.program);

		const viewPos = cameraMatrix.slice(12, 15);
		twgl.setUniforms(programInfo, {
			// camera spotlight
			u_useCameraSpotLight: true,
			u_cameraSpotLightPosition: viewPos,
			u_cameraSpotLightDirection: view.viewDirection,
			u_cameraSpotLightColor: color,
			u_cameraSpotLightIntensity: intensity,
			u_cameraSpotLightInnerCutoff: Math.cos(dwGfxMath.DEG_TO_RAD_FACTOR * innerCutoffDegrees),
			u_cameraSpotLightOuterCutoff: Math.cos(dwGfxMath.DEG_TO_RAD_FACTOR * outerCutoffDegrees),
			u_cameraSpotLightRange: range,
		});
	}
	applyPointLight(programInfo, pointPos = [0,0,0], pointIntensity = 5.0, pointRange = 5.0, pointColor = [1,1,1])
	{
		twgl.setUniforms(programInfo, {
			// point light
			u_usePointLight: true,
			u_pointLightPosition: pointPos,
			u_pointLightColor: pointColor,
			u_pointLightIntensity: pointIntensity * 0.45,
			u_pointLightRange: pointRange,
		});
	}
	applyCandleLight(programInfo)
	{
		const t = dwGetTime() * 0.001;
		// layered smooth flicker
		const flicker =
			0.55 +
			0.25 * Math.sin(t * 7.3) +
			0.12 * Math.sin(t * 13.7 + 1.9) +
			0.08 * Math.sin(t * 23.1 + 4.2);

		// small flame sway
		const flameX = 0.04 * Math.sin(t * 5.1);
		const flameY = 0.02 * Math.sin(t * 8.7 + 0.8);
		const flameZ = 0.03 * Math.sin(t * 6.3 + 2.1);

		// choose a world-space candle position
		const candleBasePos = [0.0, 1.2, 2.0];

		const pointPos = [
			candleBasePos[0] + flameX,
			candleBasePos[1] + flameY,
			candleBasePos[2] + flameZ,
		];

		const pointIntensity = 2.5 + flicker * 1.5;
		const pointRange = 4.5 + flicker * 0.8;
		const pointColor = [1.0, 0.72 + flicker * 0.06, 0.38 + flicker * 0.04];

		let worldMatrix = m4.translation(0, 0, 0);
		let invTransModelMatrix = m4.inverse(worldMatrix);
		invTransModelMatrix = m4.transpose(invTransModelMatrix);
		twgl.setUniforms(programInfo, {
			// point light
			u_usePointLight: true,
			u_pointLightPosition: pointPos,
			u_pointLightColor: pointColor,
			u_pointLightIntensity: pointIntensity * 0.45,
			u_pointLightRange: pointRange,
		});
	}
	applyUniforms(programInfo, params)
	{
		twgl.setUniforms(programInfo, params);
	}
	applyBaseTexture(programInfo, texture)
	{
		var tex = dwGfx.checkerboardTexture.img.drawInfo.texture;
		if (texture.isReady) {
			tex = texture.img.drawInfo.texture;
		}
		twgl.setUniforms(programInfo, {
			u_texture0: tex,
		});
	}
	applyNormalMapTexture(programInfo, texture)
	{
		var tex = dwGfx.checkerboardTexture.img.drawInfo.texture;
		if (texture.isReady) {
			tex = texture.img.drawInfo.texture;
		}
		twgl.setUniforms(programInfo, {
			u_texture1: tex,
		});
	}
	applyDecalTexture(programInfo, texture)
	{
		var tex = dwGfx.checkerboardTexture.img.drawInfo.texture;
		if (texture.isReady) {
			tex = texture.img.drawInfo.texture;
		}
		twgl.setUniforms(programInfo, {
			u_decalTexture: tex,
		});
	}
	applyModelMatrix(programInfo, modelMatrix)
	{
		let invTransModelMatrix = m4.inverse(modelMatrix);
		invTransModelMatrix = m4.transpose(invTransModelMatrix);
		twgl.setUniforms(programInfo, {
			u_world: modelMatrix,
			u_inverseTransposeModelMatrix: invTransModelMatrix,
		});
	}
	applyAmbientColor(programInfo, rgba)
	{
		twgl.setUniforms(programInfo, {
			u_colorMult: rgba,
		});
	}
	applyShadowMap(projectionMatrix, cameraMatrix, textureMatrix, lightWorldMatrix, projectedTexture, bias)
	{
		// Make a view matrix from the camera matrix.
		const viewMatrix = m4.inverse(cameraMatrix);
		dwGfx.gl().useProgram(this.colorProgramInfo.program);
		// set uniforms that are the same for both the sphere and plane
		// note: any values with no corresponding uniform in the shader
		// are ignored.
		twgl.setUniforms(this.colorProgramInfo, {
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_bias: bias,
			u_textureMatrix: textureMatrix,
			u_projectedTexture: projectedTexture,
			u_reverseLightDirection: lightWorldMatrix.slice(8, 11),
		});
	}
	applyCubeMap(projectionMatrix, cameraMatrix, programInfo, cubeMapTexture)
	{
		const gl = dwGfx.gl();
		const viewMatrix = m4.inverse(cameraMatrix);

		const viewDirectionMatrix = [
			viewMatrix[0], viewMatrix[1], viewMatrix[2], 0,
			viewMatrix[4], viewMatrix[5], viewMatrix[6], 0,
			viewMatrix[8], viewMatrix[9], viewMatrix[10], 0,
			0, 0, 0, 1,
		];

		const viewDirectionProjectionMatrix = m4.multiply(projectionMatrix, viewDirectionMatrix);
		const viewDirectionProjectionInverse = m4.inverse(viewDirectionProjectionMatrix);

		gl.useProgram(programInfo.program);

		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_CUBE_MAP, cubeMapTexture);

		twgl.setUniforms(programInfo, {
			u_viewDirectionProjectionInverse: viewDirectionProjectionInverse,
			u_skybox: cubeMapTexture,
		});
	}
	static gl()
	{
		return dwGfx.gfx[dwGfx.currentGfx].gl;
	}
	static canvas()
	{
		return dwGfx.gfx[dwGfx.currentGfx].canvas;
	}
	static applyRenderState_Start()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		twgl.resizeCanvasToDisplaySize(gl.canvas);
		//gl.enable(gl.CULL_FACE);
		gl.disable(gl.CULL_FACE);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(true);
		gl.depthFunc(gl.LEQUAL); 
		gl.frontFace(gl.CCW);
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
		gl.cullFace(gl.BACK);
	}
	static applyRenderState_CubeMap()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		gl.depthFunc(gl.LEQUAL); 
		gl.depthMask(false);
		gl.enable(gl.POLYGON_OFFSET_FILL);
		gl.polygonOffset(-1.0, -1.0);
		gl.enable(gl.CULL_FACE);
	}
	static applyRenderState_Decals()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(false);   // critical for overlay passes
	}
	static applyRenderState_Opaque()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		gl.disable(gl.BLEND);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(true);
	}
	static applyRenderState_TransparencyDepth()
	{
		// Alpha-blended surface that ALSO writes depth (opt-in). Same as Opaque's
		// depth handling (DEPTH_TEST + depthMask true) but with alpha blending on so
		// soft alpha edges show, while still populating the scene depth texture the
		// fog pass samples. Only safe for materials that discard transparent texels
		// via u_matAlphaCutoff, so the background does not stamp depth.
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(true);
		// Self-contained depth-write state. This pass usually runs right after the
		// cubemap pass, which enables POLYGON_OFFSET_FILL (-1,-1) and CULL_FACE and
		// leaves them set. If inherited here they corrupt the depth the fog samples:
		// the polygon offset biases every written depth value (so reconstructed
		// distance is wrong) and back-face culling drops the back-facing logo quad
		// (so half the geometry never stamps depth). Establish a clean, unbiased,
		// double-sided depth write so the scene depth texture is exactly the geometry.
		gl.disable(gl.POLYGON_OFFSET_FILL);
		gl.polygonOffset(0.0, 0.0);
		gl.disable(gl.CULL_FACE);
		gl.depthFunc(gl.LEQUAL);
	}
	static applyRenderState_Transparency()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
		gl.enable(gl.DEPTH_TEST);
		gl.depthMask(false);
	}
	static applyRenderState_Stop()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		gl.depthMask(true);
		gl.disable(gl.BLEND);
		gl.disable(gl.POLYGON_OFFSET_FILL);
	}
};
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxVolumetricFog
//
// Layer 2 of the staged volumetric fog ladder: depth-aware fog whose horizontal
// coverage is driven by an authored 2D "weather map" sampled in world XZ. Broad
// pockets of the map raise fog density; genuinely-black regions of the map leave
// the scene completely clear. Falls back to Layer 1 constant-density fog until (or
// if) the map is unavailable.
//
// Two pocket sources, selected by fogMode:
//  - "analytic": a deterministic world-space ellipsoid/SDF fog pocket evaluated at
//    every march sample -- no texture, UV, threshold, or CORS involved. Density is 1
//    inside pocketRadii, feathers smoothly to 0 at the boundary, and is 0 outside.
//    Invalid radii fall back to constant fog. Use for a guaranteed-visible diagnostic.
//  - "weather": the authored 2D map path described below.
//
// Weather map (Layer 2):
//  - A single-channel (read as .r) texture sampled at world XZ, centered on the world so
//    the world origin maps to UV (0.5, 0.5) (the authored central pocket):
//        uv = (samplePos.xz + worldOffset) / mapWorldSize + 0.5
//    mapWorldSize is the world units the map footprint spans (larger = larger footprint).
//    The map is sampled VOLUMETRICALLY: coverage is evaluated at every ray-march sample
//    along the view ray, not once at the surface, so a ray enters a pocket, accumulates
//    fog, and exits to clear air. UV outside [0,1] is treated as clear air (explicit
//    bounds; texture wrap is CLAMP_TO_EDGE), so the centered diagnostic pocket never
//    tiles or smears beyond its footprint.
//  - coverageThreshold + edgeSoftness shape the raw map value into a soft 0..1 mask
//    via smoothstep; mapInfluence blends that mask against "full fog everywhere"
//    (1.0 = the map fully gates fog, so map==0 => no fog; 0.0 = ignore the map).
//  - Loaded asynchronously. Until the image arrives the pass runs as plain constant
//    fog (u_useWeatherMap = 0); when it loads we flip to map-driven with no reload.
//    If the image errors we log a warning and stay on constant fog (scene intact).
//
// Design notes:
//  - Self-contained: owns its own GLSL program + empty VAO (fullscreen triangle via
//    gl_VertexID, same trick as the engine's post passes). Does NOT touch StandardPBR.
//  - Reads the scene DEPTH texture (must be a sampleable depth texture, not a depth
//    renderbuffer) and writes fog into the scene COLOR texture. To avoid a feedback
//    loop (sampling a texture attached to the bound framebuffer), the composite uses
//    its OWN framebuffer that attaches ONLY the scene color texture (no depth). The
//    engine's scene framebuffer keeps its depth attachment, so particles drawn after
//    the fog pass still depth-test correctly.
//  - Ray reconstruction uses m4 only (inverse(projection) for the view-space ray + distance,
//    and the camera world matrix = inverse(view) to rotate the ray into world space). The
//    direction is built in view space and rotated, never from a far-plane world endpoint, so
//    long rays to distant pockets stay precise. No manual matrix code.
//  - composite() saves and restores every GL bit it touches (framebuffer, viewport,
//    program, VAO, active texture + unit-0 binding, blend, depth test/mask, cull,
//    color mask, separate blend factors).
//  - Fails gracefully: if the shader or composite framebuffer will not build, it logs
//    a warning and becomes a no-op (the scene renders exactly as if fog were absent).
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
class dwGfxVolumetricFog
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;

		const o = options || {};
		// Restrained defaults; all tuneable at runtime by the demo.
		this.density     = (o.density     !== undefined) ? o.density              : 0.035;
		this.color       = (o.color       !== undefined) ? o.color.slice(0, 3)    : [0.62, 0.68, 0.75];
		this.maxDistance = (o.maxDistance !== undefined) ? o.maxDistance          : 100.0;
		this.steps       = (o.steps       !== undefined) ? (o.steps | 0)          : 24;
		this.debugMode   = (o.debugMode   !== undefined) ? (o.debugMode | 0)      : 0; // 0 off, 1 distance, 2 fog factor, 3 weather coverage

		// ---- Layer 2: authored weather-map coverage ----
		// World-size formulation: the map tile is centered on the world so that world
		// origin maps to UV (0.5, 0.5) (the authored central pocket), and mapWorldSize is
		// the number of world units one full tile spans:
		//     uv = (worldPos.xz + worldOffset) / mapWorldSize + 0.5
		// The scene's only drawn geometry (the logo quad) sits at the origin spanning a
		// few world units, and the camera is ~10 units away. A restrained mapWorldSize of
		// 40 puts the tile's strong central pocket squarely on/around the logo directly in
		// front of the user, with the surrounding clear regions falling within the view.
		this.mapWorldSize      = (o.mapWorldSize      !== undefined) ? o.mapWorldSize                : 40.0;
		this.worldOffset       = (o.worldOffset       !== undefined) ? o.worldOffset.slice(0, 2)     : [0.0, 0.0]; // world XZ offset, added before centering
		this.coverageThreshold = (o.coverageThreshold !== undefined) ? o.coverageThreshold           : 0.35;
		this.edgeSoftness      = (o.edgeSoftness       !== undefined) ? o.edgeSoftness                : 0.25;
		this.mapInfluence      = (o.mapInfluence       !== undefined) ? o.mapInfluence                : 1.0;  // 1 = map fully gates fog

		// ---- Analytic world-space fog pocket (deterministic diagnostic) ----
		// A smooth ellipsoid/SDF fog volume evaluated in pure world space at every march
		// sample -- no texture, no UV mapping, no thresholds, no CORS. When fogMode is
		// "analytic" the weather map is bypassed entirely (but its state is preserved so it
		// can be re-selected later). Density is 1 inside pocketRadii, feathers smoothly to 0
		// at the ellipsoid boundary, and is exactly 0 outside. Centered on the visible logo
		// at the world origin (slightly above the floor for a ground-fog look).
		this.fogMode       = (o.fogMode       !== undefined) ? String(o.fogMode)            : "weather"; // "analytic" | "weather"
		this.pocketCenter  = (o.pocketCenter  !== undefined) ? o.pocketCenter.slice(0, 3)   : [0.0, 0.5, 0.0];
		this.pocketRadii   = (o.pocketRadii   !== undefined) ? o.pocketRadii.slice(0, 3)    : [5.0, 2.0, 5.0];
		this.pocketFeather = (o.pocketFeather !== undefined) ? o.pocketFeather              : 0.35; // feather band as a fraction of the radius (0..1)

		// ---- Multiple analytic pockets ----
		// Optional array of finite ellipsoid pockets scattered in world space:
		//   pockets: [{ center:[x,y,z], radii:[x,y,z], feather:0..1, densityScale:>=0 }, ...]
		// When supplied (non-empty) it drives the analytic path; the array is capped at
		// dwGfxVolumetricFog.MAX_POCKETS. When NOT supplied, a single pocket is synthesized
		// from pocketCenter/pocketRadii/pocketFeather above, so existing single-pocket
		// callers are byte-for-byte backward compatible. Runtime-settable (see composite()).
		this.pockets = (Array.isArray(o.pockets) && o.pockets.length > 0) ? o.pockets.slice(0, dwGfxVolumetricFog.MAX_POCKETS) : null;

		// DIAGNOSTIC: when true, the analytic pocket ignores the reconstructed scene
		// depth and uses the full ray length (u_maxDistance), so the ray always reaches
		// the ellipsoid and the pocket is visible from OUTSIDE, not only once the camera
		// is within it. The finite ellipsoid density mask is unchanged -- fog is still 0
		// outside the pocket. Tradeoff: analytic fog draws THROUGH foreground geometry
		// (depth is ignored). Not final production behavior; a test aid only. Only affects
		// fogMode "analytic"; the weather/constant path is untouched.
		this.ignoreSceneDepth = (o.ignoreSceneDepth !== undefined) ? !!o.ignoreSceneDepth : false;

		// ---- Step 4: internal 3D density variation + analytic-edge erosion ----
		// A single deterministic, genuinely tileable 32^3 R8 value/fractal noise volume is
		// built ONCE at init (no URL/CORS). It is sampled in STABLE WORLD SPACE at each march
		// sample (so no camera swimming), animated by a slow world-space wind vector * time,
		// with exactly ONE 3D fetch per step (no second octave / no domain warp -- first pass).
		// The single fetch both (a) modulates internal density into dense masses + thin gaps
		// and (b) erodes the analytic pocket boundary band so silhouettes read organic/broken.
		// Every control is independently toggleable for clean A/B; defaults are subtle so the
		// existing pockets remain readable and never vanish. Ranges are clamped in composite().
		this.noiseEnabled  = (o.noiseEnabled  !== undefined) ? !!o.noiseEnabled : true;
		this.noiseScale    = (o.noiseScale    !== undefined) ? +o.noiseScale    : 0.08; // world^-1 (freq)
		this.noiseStrength = (o.noiseStrength !== undefined) ? +o.noiseStrength : 0.5;  // density +/- fraction (0..1)
		this.noiseContrast = (o.noiseContrast !== undefined) ? +o.noiseContrast : 1.4;  // >1 punchier masses/gaps
		this.edgeErosion   = (o.edgeErosion   !== undefined) ? +o.edgeErosion   : 0.35; // boundary break-up (0..1)
		// Boundary displacement: perturbs the normalized pocket distance (1.0 == radius) BEFORE
		// the feather, so pockets grow broad irregular lobes instead of looking round. Default
		// 0.18 => max +/-0.09 of the radius (~half the 0.35 feather band): clearly non-round yet
		// safely keeps the solid core. 0 reproduces the exact prior ellipsoid silhouette.
		this.shapeWarp     = (o.shapeWarp     !== undefined) ? +o.shapeWarp     : 0.18; // 0..1 (fraction of radius)
		this.windVelocity  = (Array.isArray(o.windVelocity) && o.windVelocity.length >= 3)
			? o.windVelocity.slice(0, 3) : [0.15, 0.02, 0.07];                          // world units / second
		this.NOISE_SIZE    = 32;

		// ---- Step 5A: moon in-scattering (no shadows) ----
		// An RGB-only directional scatter term added inside the ray march. It NEVER touches the fog
		// alpha, so moonEnabled:false (or moonIntensity:0 with moonAmbient:0) reproduces the current
		// fog exactly. moonDir is the WORLD-space direction FROM the fog TOWARD the moon; it is
		// normalized in composite() before upload. Defaults are tuned restrained; the demo overrides.
		this.moonEnabled    = (o.moonEnabled    !== undefined) ? !!o.moonEnabled : false;
		this.moonDir        = (Array.isArray(o.moonDir) && o.moonDir.length >= 3)
			? o.moonDir.slice(0, 3) : [0.0, 1.0, 1.0];                     // up-and-forward by default
		this.moonColor      = (Array.isArray(o.moonColor) && o.moonColor.length >= 3)
			? o.moonColor.slice(0, 3) : [0.60, 0.72, 0.95];               // silver-blue moonlight
		this.moonIntensity  = (o.moonIntensity  !== undefined) ? +o.moonIntensity  : 0.6;
		this.moonAnisotropy = (o.moonAnisotropy !== undefined) ? +o.moonAnisotropy : 0.55; // fwd halo
		this.moonAmbient    = (o.moonAmbient    !== undefined) ? +o.moonAmbient    : 0.05; // flat lift

		// ---- Step 5B: directional shadow-map visibility for the scatter term ----
		// Disabled by DEFAULT: enabling it requires a valid authoritative directional shadow depth
		// texture + light-space matrix (see composite(); shadowOn also requires gl.isTexture). When
		// the resource is missing the scatter term stays fully lit (Step 5A unaffected). shadowMatrix
		// maps world -> [0,1] uv+depth (projection*inverse(lightWorld) with a bias matrix folded in),
		// supplied per-frame by the demo. shadowStride samples the shadow map every Nth march step.
		this.shadowEnabled  = (o.shadowEnabled  !== undefined) ? !!o.shadowEnabled : false;
		this.shadowMatrix   = (o.shadowMatrix   !== undefined) ? o.shadowMatrix     : null; // Float32Array/[16]
		this.shadowTexture  = (o.shadowTexture  !== undefined) ? o.shadowTexture    : null; // WebGLTexture (DEPTH24)
		this.shadowBias     = (o.shadowBias     !== undefined) ? +o.shadowBias      : 0.0025;
		// QUALITY-FIRST shadow sampling defaults. These four exist because a single binary depth
		// compare, held across a stride window, on a perfectly coherent per-pixel march grid draws
		// the shadow map's texel grid, the stride shells and the light frustum's silhouette straight
		// into the fog (hard staircased shaft edges, horizontal slabs, a trapezoid around the logo).
		//   shadowStride 1 -- the correctness/reference path: every march sample gets its own tap.
		//                     >1 is still supported and is now INTERPOLATED between bracketing taps
		//                     rather than sample-and-held, so it degrades smoothly instead of banding.
		//   shadowPCF 1    -- 3x3 depth compares at the real texel size: 10 visibility levels and a
		//                     texel-wide soft edge. 0 = single tap (cheap diagnostic / A/B).
		//   shadowSoftness -- PCF radius in TEXELS (1.0 == immediately adjacent texels).
		//   shadowJitter   -- per-pixel offset of the shadow tap along the ray, in march-step
		//                     fractions, to decorrelate the march grid. 0 disables it for A/B.
		// shadowMapSize is the REAL shadow map dimension (engine default 512); the demo passes the
		// live texture's width so the PCF offsets are exactly one texel and never a guess.
		this.shadowStride   = (o.shadowStride   !== undefined) ? (o.shadowStride | 0) : 1;
		this.shadowPCF      = (o.shadowPCF      !== undefined) ? (o.shadowPCF | 0)    : 1;
		this.shadowSoftness = (o.shadowSoftness !== undefined) ? +o.shadowSoftness  : 1.0;
		this.shadowJitter   = (o.shadowJitter   !== undefined) ? +o.shadowJitter    : 0.75;
		this.shadowMapSize  = (o.shadowMapSize  !== undefined) ? (o.shadowMapSize | 0) : 512;
		this.shadowDiag     = "shadow[off]"; // HUD proof of the runtime binding/validity decision

		// ---- Step 6: analytic-march cost controls. Both defaults are QUALITY-SAFE. ----
		// earlyExitTransmittance -- the front-to-back march stops once the accumulated
		//   transmittance falls below this. 0.001 is EXACTLY the constant that used to be
		//   hard-coded in the shader, so the default behaviour is unchanged; 0 disables the
		//   early exit entirely (the reference path, for A/B).
		// stepWorldLength -- OPT-IN adaptive step sizing, in WORLD UNITS. 0 (the default)
		//   means OFF: the full step budget is spread across the OCCUPIED interval union,
		//   which is never coarser than the old hull march (occupied <= hull). When > 0 the
		//   step count may only be REDUCED to whatever that world-space spacing needs, so it
		//   can trade density for speed but can never be enabled by accident. This is the
		//   primary FPS lever to A/B in a live browser.
		this.earlyExitTransmittance = (o.earlyExitTransmittance !== undefined) ? +o.earlyExitTransmittance : 0.001;
		this.stepWorldLength        = (o.stepWorldLength        !== undefined) ? +o.stepWorldLength        : 0.0;
		this.marchDiag              = "march[-]"; // HUD: resolved step budget / early-exit threshold

		this.ok                = false;
		this.programInfo       = null;
		this.vao               = null;
		this.fbo               = null;
		this.fboColorTexHandle = null; // rebuild fbo when the scene color texture changes

		// ---- feedback-loop guard state (surfaced on the HUD / trace) ----
		// The scene depth texture the fog samples is the DEPTH_ATTACHMENT of dwGfx's scene
		// framebuffer. Sampling a texture while a framebuffer that has it attached is bound as
		// the DRAW (or READ) target is a framebuffer-texture feedback loop -> the sample is
		// undefined and reads 0 on real drivers (runtime-proven: valid depth content + correct
		// sampler state, yet the fog read 0). composite() binds its OWN color-only destination
		// (this.fbo, no depth attachment) before sampling, and _assertNoDepthFeedback() proves
		// it at draw time: "SAFE" (destination shares no attachment with the sampled depth) or
		// "LOOP" (fails loudly + skips the undefined draw instead of sampling garbage).
		this.fbSafe            = "";

		// ---- explicit, unique sampler texture units (surfaced on the HUD) ----
		// The fog program has exactly two samplers: u_depthTexture (scene depth) and
		// u_weatherMap (weather/coverage). They get FIXED, unique units here. composite()
		// assigns them with RAW gl.uniform1i on cached locations and binds the live depth
		// handle to DEPTH_UNIT LAST, immediately before draw -- it never routes the samplers
		// through twgl.setUniforms, whose sampler setter is version-dependent (it can allocate
		// its own unit and/or rebind the texture when handed a value, silently overriding the
		// manual unit-0 depth bind). That twgl path was the ONLY material difference from the
		// clean probe (raw uniform1i) that reads this same attachment correctly. depthBindDiag
		// records the runtime proof: "depthUnit=0 bind=OK uniform=OK" or a loud failure.
		this.DEPTH_UNIT        = 0;
		this.WEATHER_UNIT      = 1;
		this.NOISE_UNIT        = 2; // 3D noise volume gets its OWN unique unit (TEXTURE_3D)
		this.SHADOW_UNIT       = 3; // Step 5B shadow map gets its OWN unique unit (sampler2DShadow)
		this.depthSamplerLoc   = null; // cached WebGLUniformLocation (opaque; compare to null)
		this.weatherSamplerLoc = null;
		this.noiseSamplerLoc   = null; // null => u_noiseVolume was optimized out (noise inactive)
		this.shadowSamplerLoc  = null; // null => u_shadowMap optimized out (shadows inactive)
		this.depthBindDiag     = "depthUnit=? bind=? uniform=?";
		this._depthBindLogged  = false;

		// 3D noise volume runtime state. noiseTex is ALWAYS a complete 3D texture once init
		// runs (the full volume, or a 1x1x1 fallback if creation fails) so the sampler3D on
		// NOISE_UNIT is never left pointing at an incomplete/empty unit. noiseReady is true
		// only for the real volume; a failure disables noise but keeps the scene rendering.
		this.noiseTex      = null;
		this.noiseReady    = false;
		this.noiseVolDiag  = "noise[pending]";

		// ---- one-time runtime depth diagnostic (surfaced on the HUD) ----
		// The static path (createDepthTexture -> DEPTH_ATTACHMENT -> clearDepth(1) -> sample
		// on unit 0) is self-consistent, yet the device reports Mode 4 rawDepth as solid
		// black (== 0). depthDiag holds the runtime facts source cannot prove: scene FBO
		// completeness, the depth attachment's TYPE + object identity vs the sampled texture,
		// and the actual grayscale value read back at a background + center pixel.
		this.depthDiag       = "depth[pending]";
		this._depthDiagDone  = false;
		this._depthDiagLogged = false;

		// ---- deterministic depth ISOLATION probe result (surfaced on the HUD) ----
		// Filled by runDepthIsolationTest(): a known nonzero sentinel is cleared into the
		// EXACT scene depth attachment (no geometry drawn) and read straight back, to
		// decide whether a black rawDepth is a sampler/format failure (A) or a later
		// scene-pass write/overwrite (B). Empty until the test is run (demo: press 'i').
		this.depthIsolation  = "";

		// ---- DISPLAYED sentinel probe result (surfaced on the HUD) ----
		// Filled by presentDepthSentinelToCanvas(): clears the EXACT live scene depth
		// attachment to a known midrange sentinel (no geometry) and draws that exact raw
		// depth straight to the canvas, so the human eye decides gray (sampling works =>
		// CAUSE B) vs black (sampling broken => CAUSE A). Empty until run (demo: 'k').
		this.depthSentinel   = "";

		// weather map (async). weatherReady flips true only once the image has been
		// uploaded to a GL texture; until then the pass runs as constant fog.
		this.weatherTex    = null;
		this.weatherReady  = false;
		this.weatherFailed = false;
		// 1x1 opaque-white color texture bound to the weather sampler whenever the real
		// map is not ready. Keeps unit 1 a valid, filterable color texture (never the
		// depth texture) so the not-ready/failed fallback path is always a clean draw.
		this.placeholderTex = null;
		// 1x1 DEPTH_COMPONENT24 placeholder cleared to the far value (1.0) with hardware compare
		// enabled, bound to the shadow unit whenever no valid real shadow map is supplied. A far
		// placeholder makes every compare pass => fully lit, so a missing shadow map never darkens
		// the fog and unit 3 always holds a complete, compare-mode depth texture (never left empty).
		this.shadowPlaceholderTex = null;

		this._initGL();

		if (o.weatherMapUrl) {
			this._loadWeatherMap(o.weatherMapUrl);
		}
	}

	// Asynchronously load the authored weather map into a REPEAT-wrapped GL texture.
	// Safe to call before the first frame: composite() renders constant fog until this
	// resolves, then switches to map-driven with no reload. On error we log once and
	// stay on constant fog so the scene is never broken.
	_loadWeatherMap(url)
	{
		const gl = dwGfx.gl();
		if (!gl) {
			return;
		}
		const self = this;
		const img = new Image();
		// only request CORS for cross-origin URLs (mirrors dwGfxTexture); the asset is
		// normally deployed same-origin beside the demo, so no CORS attribute is set.
		try {
			if ((new URL(url, window.location.href)).origin !== window.location.origin) {
				img.crossOrigin = "";
			}
		}
		catch (e) { /* relative URL resolution can throw in exotic hosts; ignore */ }

		img.addEventListener("load", function() {
			// upload without disturbing the engine's active-unit binding. Captured before
			// the try so the finally can always restore them even if the upload throws
			// (e.g. a tainted image), leaving no leaked binding on unit 0.
			const prevActive = gl.getParameter(gl.ACTIVE_TEXTURE);
			gl.activeTexture(gl.TEXTURE0);
			const prevTex0 = gl.getParameter(gl.TEXTURE_BINDING_2D);
			try {
				const tex = gl.createTexture();
				gl.bindTexture(gl.TEXTURE_2D, tex);
				gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
				// Centered diagnostic map: clamp so the single pocket does not tile/smear
				// outside its [0,1] world footprint. The shader also bounds-checks the UV
				// and treats outside-footprint samples as clear air, so wrap only guards
				// the edge texels. LINEAR filtering, base level (no mipmaps needed since
				// the march samples at LOD 0).
				gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
				gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
				gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
				gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);

				self.weatherTex   = tex;
				self.weatherReady = true;
				self.weatherFailed = false;
			}
			catch (e) {
				self.weatherFailed = true;
				console.warn("dwGfxVolumetricFog: weather map upload failed; using constant fog.", e);
			}
			finally {
				gl.bindTexture(gl.TEXTURE_2D, prevTex0);
				gl.activeTexture(prevActive);
			}
		});
		img.addEventListener("error", function() {
			self.weatherFailed = true;
			console.warn("dwGfxVolumetricFog: weather map failed to load ('" + url + "'); using constant fog.");
		});
		img.src = url;
	}

	_initGL()
	{
		const gl = dwGfx.gl();
		if (!gl) {
			console.warn("dwGfxVolumetricFog: no WebGL2 context; fog disabled.");
			return;
		}
		try {
			const errors = [];
			this.programInfo = twgl.createProgramInfo(
				gl,
				[dwGfxVolumetricFog.VS, dwGfxVolumetricFog.FS],
				{ errorCallback: (m) => errors.push(m) }
			);
			if (!this.programInfo || !this.programInfo.program) {
				// The production compile (twgl) failed. Emit the FULL diagnostic: shader stage,
				// complete info logs, and numbered source lines around the reported error -- not
				// just the generic one-liner that hid the real cause. This runs ONLY on the
				// failure branch (fog is already disabled), so it adds no production compile path.
				console.warn("dwGfxVolumetricFog: shader build failed; fog disabled." +
					(errors.length ? ("\ntwgl: " + errors.join("\n")) : ""));
				this._logShaderBuildFailure(gl, dwGfxVolumetricFog.VS, dwGfxVolumetricFog.FS);
				this.programInfo = null;
				return;
			}
			this.vao = gl.createVertexArray(); // empty VAO; fullscreen triangle needs no attributes

			// Cache the sampler uniform locations ONCE. getUniformLocation returns an opaque
			// WebGLUniformLocation (never the number 0), so a valid location is only ever
			// falsy when it is null -- compare to null explicitly rather than testing !loc.
			this.depthSamplerLoc   = gl.getUniformLocation(this.programInfo.program, "u_depthTexture");
			this.weatherSamplerLoc = gl.getUniformLocation(this.programInfo.program, "u_weatherMap");
			// u_noiseVolume may legitimately be null if the driver optimized it out (never
			// statically used) -- then it is not an active sampler and cannot collide with a
			// unit, so we simply disable the noise layer rather than failing the whole fog.
			this.noiseSamplerLoc   = gl.getUniformLocation(this.programInfo.program, "u_noiseVolume");
			// u_shadowMap may legitimately be null if the driver optimized it out (shadows never
			// statically used) -- then it is not an active sampler, cannot collide with a unit, and
			// the Step 5B shadow layer is simply disabled while the rest of the fog renders.
			this.shadowSamplerLoc  = gl.getUniformLocation(this.programInfo.program, "u_shadowMap");
			// All four units must be UNIQUE and within the driver's combined-sampler limit. Four
			// units (0..3) is far below any real limit; assert anyway so a future added sampler
			// can't silently collide (which reintroduces the depth-reads-0 failure).
			const maxUnits = gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS) | 0;
			const units = [this.DEPTH_UNIT, this.WEATHER_UNIT, this.NOISE_UNIT, this.SHADOW_UNIT];
			const uniqueOk = (new Set(units)).size === units.length;
			const rangeOk = units.every((u) => u >= 0 && u < maxUnits);
			if (!uniqueOk || !rangeOk) {
				console.warn("dwGfxVolumetricFog: sampler unit assignment invalid (depth=" +
					this.DEPTH_UNIT + " weather=" + this.WEATHER_UNIT + " noise=" + this.NOISE_UNIT +
					" shadow=" + this.SHADOW_UNIT + " max=" + maxUnits + "); fog disabled.");
				this.programInfo = null;
				return;
			}
			if (this.depthSamplerLoc === null) {
				console.warn("dwGfxVolumetricFog: u_depthTexture sampler location not found; fog disabled.");
				this.programInfo = null;
				return;
			}
			if (this.noiseSamplerLoc === null) {
				// noise sampler compiled out => noise cannot run; keep the rest of the fog.
				this.noiseEnabled = false;
			}
			if (this.shadowSamplerLoc === null) {
				// shadow sampler compiled out => shadow layer cannot run; keep the rest of the fog.
				this.shadowEnabled = false;
			}

			// 1x1 opaque-white placeholder for the weather sampler (unit 1) while the real
			// map is loading or if it never loads. A white texel => coverage 1.0 => the
			// smoothstep mask is 1 => densityScale 1 => exact Layer 1 constant fog. Save
			// and restore unit 0's binding so construction never disturbs engine state.
			const prevActive = gl.getParameter(gl.ACTIVE_TEXTURE);
			gl.activeTexture(gl.TEXTURE0);
			const prevTex0 = gl.getParameter(gl.TEXTURE_BINDING_2D);
			this.placeholderTex = gl.createTexture();
			gl.bindTexture(gl.TEXTURE_2D, this.placeholderTex);
			gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE,
				new Uint8Array([255, 255, 255, 255]));
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);

			// 1x1 DEPTH_COMPONENT24 shadow placeholder for unit 3 (see field docs). Cleared to the
			// far depth (1.0) with COMPARE_REF_TO_TEXTURE/LEQUAL so a sampler2DShadow compare against
			// any ref <= 1.0 returns 1.0 (fully lit). Reuses the saved/restored unit-0 binding above.
			this.shadowPlaceholderTex = gl.createTexture();
			gl.bindTexture(gl.TEXTURE_2D, this.shadowPlaceholderTex);
			gl.texImage2D(gl.TEXTURE_2D, 0, gl.DEPTH_COMPONENT24, 1, 1, 0, gl.DEPTH_COMPONENT,
				gl.UNSIGNED_INT, new Uint32Array([0xFFFFFFFF]));
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_FUNC, gl.LEQUAL);

			gl.bindTexture(gl.TEXTURE_2D, prevTex0);
			gl.activeTexture(prevActive);

			// Build the deterministic tileable 3D noise volume once (never per-frame). On any
			// failure it disables noise and installs a 1x1x1 fallback so the sampler3D unit
			// stays complete and the rest of the fog renders unchanged.
			this._buildNoiseVolume(gl);

			this.ok = true;
		}
		catch (e) {
			console.warn("dwGfxVolumetricFog: init threw; fog disabled.", e);
			this.ok = false;
		}
	}

	// Generate a deterministic, genuinely PERIODIC (tileable) single-channel value/fractal
	// noise cube of side N. Each octave uses a lattice whose frequency divides evenly into
	// the volume and whose integer lattice indices wrap modulo that frequency, so opposite
	// faces meet seamlessly under REPEAT wrapping (no visible seam). Low-frequency octaves
	// (2,4,8) give large soft masses plus finer break-up. Returns a Uint8Array (N^3, R8).
	_generateTileableNoise(N)
	{
		const out = new Uint8Array(N * N * N);
		// deterministic PRNG (mulberry32) -- identical layout on every device/run.
		let a = 0x9E3779B9 >>> 0;
		const rng = () => {
			a |= 0; a = (a + 0x6D2B79F5) | 0;
			let t = Math.imul(a ^ (a >>> 15), 1 | a);
			t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
			return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
		};
		const octaves = [{ freq: 2, amp: 0.55 }, { freq: 4, amp: 0.30 }, { freq: 8, amp: 0.15 }];
		let ampSum = 0;
		const grids = octaves.map((o) => {
			ampSum += o.amp;
			const g = new Float32Array(o.freq * o.freq * o.freq);
			for (let i = 0; i < g.length; i++) { g[i] = rng(); }
			return { f: o.freq, amp: o.amp, g: g };
		});
		const smooth = (t) => t * t * (3.0 - 2.0 * t);          // C1 fade
		const lerp = (p, q, t) => p + (q - p) * t;
		for (let z = 0; z < N; z++) {
			for (let y = 0; y < N; y++) {
				for (let x = 0; x < N; x++) {
					let v = 0.0;
					for (let oi = 0; oi < grids.length; oi++) {
						const oc = grids[oi], f = oc.f;
						const fx = x / N * f, fy = y / N * f, fz = z / N * f;
						const xi = Math.floor(fx), yi = Math.floor(fy), zi = Math.floor(fz);
						const x0 = ((xi % f) + f) % f, y0 = ((yi % f) + f) % f, z0 = ((zi % f) + f) % f;
						const x1 = (x0 + 1) % f, y1 = (y0 + 1) % f, z1 = (z0 + 1) % f; // wrap => seamless
						const tx = smooth(fx - xi), ty = smooth(fy - yi), tz = smooth(fz - zi);
						const g = oc.g;
						const idx = (xx, yy, zz) => xx + f * (yy + f * zz);
						const c00 = lerp(g[idx(x0, y0, z0)], g[idx(x1, y0, z0)], tx);
						const c10 = lerp(g[idx(x0, y1, z0)], g[idx(x1, y1, z0)], tx);
						const c01 = lerp(g[idx(x0, y0, z1)], g[idx(x1, y0, z1)], tx);
						const c11 = lerp(g[idx(x0, y1, z1)], g[idx(x1, y1, z1)], tx);
						const c0 = lerp(c00, c10, ty), c1 = lerp(c01, c11, ty);
						v += lerp(c0, c1, tz) * oc.amp;
					}
					v /= ampSum;                                    // normalized to [0,1]
					let b = Math.round(v * 255.0);
					out[x + N * (y + N * z)] = b < 0 ? 0 : (b > 255 ? 255 : b);
				}
			}
		}
		return out;
	}

	// Upload the tileable volume as an R8 TEXTURE_3D with REPEAT wrapping + LINEAR filtering
	// (no mipmaps). Saves/restores the active unit and 3D binding so init never disturbs the
	// engine. On any failure: disable noise and install a 1x1x1 fallback so NOISE_UNIT still
	// holds a complete 3D texture (the sampler3D is never left pointing at an empty unit).
	_buildNoiseVolume(gl)
	{
		const N = this.NOISE_SIZE | 0;
		const prevActive = gl.getParameter(gl.ACTIVE_TEXTURE);
		gl.activeTexture(gl.TEXTURE0);
		const prev3D = gl.getParameter(gl.TEXTURE_BINDING_3D);
		try {
			const data = this._generateTileableNoise(N);
			const tex = gl.createTexture();
			gl.bindTexture(gl.TEXTURE_3D, tex);
			gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
			gl.texImage3D(gl.TEXTURE_3D, 0, gl.R8, N, N, N, 0, gl.RED, gl.UNSIGNED_BYTE, data);
			gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_S, gl.REPEAT);
			gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_T, gl.REPEAT);
			gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_R, gl.REPEAT);
			gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
			gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
			const err = gl.getError();
			if (err !== gl.NO_ERROR) { throw new Error("GL error 0x" + (err >>> 0).toString(16) + " uploading 3D noise"); }
			this.noiseTex     = tex;
			this.noiseReady   = true;
			this.noiseVolDiag = "noise=" + N + "^3 R8 REPEAT/LINEAR";
		}
		catch (e) {
			console.warn("dwGfxVolumetricFog: 3D noise volume creation failed; noise disabled.", e);
			this.noiseReady   = false;
			this.noiseEnabled = false;
			this.noiseVolDiag = "noise=FAILED (disabled)";
			// 1x1x1 fallback so the sampler3D unit is still complete on drivers that validate it.
			try {
				const ph = gl.createTexture();
				gl.bindTexture(gl.TEXTURE_3D, ph);
				gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
				gl.texImage3D(gl.TEXTURE_3D, 0, gl.R8, 1, 1, 1, 0, gl.RED, gl.UNSIGNED_BYTE, new Uint8Array([128]));
				gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_S, gl.REPEAT);
				gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_T, gl.REPEAT);
				gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_WRAP_R, gl.REPEAT);
				gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
				gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
				this.noiseTex = ph;
			}
			catch (e2) { this.noiseTex = null; }
		}
		gl.bindTexture(gl.TEXTURE_3D, prev3D);
		gl.activeTexture(prevActive);
	}

	// Assign u_noiseVolume -> NOISE_UNIT (raw uniform1i on the cached location) and bind the
	// live 3D volume there. Shared by composite() and the depth-diag draws so the sampler3D
	// NEVER defaults to unit 0 (where the 2D depth texture lives) -- a sampler-type collision
	// on unit 0 would fail the draw and reintroduce the depth-reads-0 bug. Leaves the active
	// unit on NOISE_UNIT; callers bind the depth texture LAST to restore the depth unit.
	_bindNoiseSampler(gl)
	{
		if (this.noiseSamplerLoc === null) { return; } // optimized out => not active => no unit conflict
		gl.uniform1i(this.noiseSamplerLoc, this.NOISE_UNIT);
		if (this.noiseTex) {
			gl.activeTexture(gl.TEXTURE0 + this.NOISE_UNIT);
			gl.bindTexture(gl.TEXTURE_3D, this.noiseTex);
		}
	}

	// Failure-only diagnostic: the production twgl compile already failed and fog is disabled,
	// so here we compile each stage explicitly PURELY to surface what twgl swallowed -- the
	// shader stage, the complete gl.getShaderInfoLog / gl.getProgramInfoLog, and the numbered
	// source lines around the error the driver reported ("ERROR: 0:<line>: ..."). All temp
	// objects are deleted; nothing here is used for rendering (no duplicate production path).
	_logShaderBuildFailure(gl, vsSrc, fsSrc)
	{
		const numberedAround = (src, line) => {
			const lines = src.split("\n");
			const from = Math.max(0, (line | 0) - 4);
			const to   = Math.min(lines.length, (line | 0) + 3);
			let out = "";
			for (let i = from; i < to; i++) {
				const ln = i + 1;
				out += (ln === line ? " >> " : "    ") + ln + " | " + lines[i] + "\n";
			}
			return out;
		};
		const firstErrorLine = (log) => {
			// GLSL error format: "ERROR: <col>:<line>: ..." -> pull the <line>.
			const m = /(?:ERROR|WARNING)\s*:\s*\d+\s*:\s*(\d+)/i.exec(log || "");
			return m ? (m[1] | 0) : 0;
		};
		const compileStage = (type, name, src) => {
			const sh = gl.createShader(type);
			gl.shaderSource(sh, src);
			gl.compileShader(sh);
			const okc = gl.getShaderParameter(sh, gl.COMPILE_STATUS);
			if (!okc) {
				const log = gl.getShaderInfoLog(sh) || "(empty info log)";
				const line = firstErrorLine(log);
				console.warn("dwGfxVolumetricFog: " + name + " COMPILE FAILED\n" + log +
					(line ? ("\nsource around line " + line + ":\n" + numberedAround(src, line)) : ""));
			}
			return { sh, okc };
		};
		try {
			const vs = compileStage(gl.VERTEX_SHADER, "VERTEX_SHADER", vsSrc);
			const fs = compileStage(gl.FRAGMENT_SHADER, "FRAGMENT_SHADER", fsSrc);
			if (vs.okc && fs.okc) {
				// Both stages compiled -> the failure is at LINK time; surface the program log.
				const prog = gl.createProgram();
				gl.attachShader(prog, vs.sh); gl.attachShader(prog, fs.sh);
				gl.linkProgram(prog);
				if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
					console.warn("dwGfxVolumetricFog: PROGRAM LINK FAILED\n" + (gl.getProgramInfoLog(prog) || "(empty program log)"));
				}
				gl.deleteProgram(prog);
			}
			gl.deleteShader(vs.sh);
			gl.deleteShader(fs.sh);
		}
		catch (e) {
			console.warn("dwGfxVolumetricFog: shader-failure diagnostic threw.", e);
		}
	}

	// Force the composite framebuffer to be rebuilt (call after scene targets are
	// recreated, e.g. on resize or fog enable/disable).
	invalidateTargets()
	{
		this.fboColorTexHandle = null;
		// Targets were recreated (resize / fog toggle), so the scene depth attachment may be
		// a new texture. Re-arm the one-time depth diagnostic to re-verify TEX id=OK and the
		// sampled values against the freshly attached texture on the next composite.
		this._depthDiagDone = false;
	}

	// Flatten this.pockets (or the single-pocket fallback) into the fixed-size arrays the
	// shader expects. Returns { count, centers, radii, feathers, density, steps }. Called
	// once per composite; MAX_POCKETS is tiny so the per-frame cost is negligible. The
	// per-pocket march budget (steps) is full resolution for a single pocket (identical to
	// the original single-pocket look) and capped for multiple pockets so worst-case mobile
	// cost stays bounded (count * steps).
	_buildPocketUniforms()
	{
		const MAX = dwGfxVolumetricFog.MAX_POCKETS;
		const centers  = new Float32Array(MAX * 3);
		const radii    = new Float32Array(MAX * 3);
		const feathers = new Float32Array(MAX);
		const density  = new Float32Array(MAX);

		// source list: explicit array, else a single pocket from the legacy scalar config.
		const list = (Array.isArray(this.pockets) && this.pockets.length > 0)
			? this.pockets
			: [{ center: this.pocketCenter, radii: this.pocketRadii, feather: this.pocketFeather, densityScale: 1.0 }];

		const count = Math.min(list.length, MAX);
		for (let i = 0; i < count; i++) {
			const p = list[i] || {};
			const c = p.center || [0, 0, 0];
			const r = p.radii  || [0, 0, 0];
			centers[i * 3 + 0] = +c[0] || 0; centers[i * 3 + 1] = +c[1] || 0; centers[i * 3 + 2] = +c[2] || 0;
			radii[i * 3 + 0]   = +r[0] || 0; radii[i * 3 + 1]   = +r[1] || 0; radii[i * 3 + 2]   = +r[2] || 0;
			feathers[i] = (p.feather !== undefined) ? +p.feather : this.pocketFeather;
			density[i]  = (p.densityScale !== undefined) ? +p.densityScale : 1.0;
		}

		let steps = this.steps | 0;
		if (steps < 1) { steps = 1; }
		// GLOBAL step budget for the unified single-hull march (not per-pocket). One pocket ->
		// full budget over its own chord (appearance unchanged). Multiple pockets share ONE
		// march across the union hull, so add a few steps per extra pocket to keep the wider
		// hull adequately sampled, capped well under the shader's DW_FOG_MAX_STEPS (128).
		const HULL_STEP_CAP = 96;
		const gSteps = (count <= 1)
			? steps
			: Math.min(steps + (count - 1) * 8, HULL_STEP_CAP);

		return { count, centers, radii, feathers, density, steps: gSteps };
	}

	_ensureFBO(colorTexObj)
	{
		const gl = dwGfx.gl();
		const handle = colorTexObj.img.drawInfo.texture;
		if (this.fbo && this.fboColorTexHandle === handle) {
			return true;
		}
		if (this.fbo) {
			gl.deleteFramebuffer(this.fbo);
			this.fbo = null;
		}
		const fbo = gl.createFramebuffer();
		gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
		gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, handle, 0);
		gl.drawBuffers([gl.COLOR_ATTACHMENT0]);
		const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
		gl.bindFramebuffer(gl.FRAMEBUFFER, null);
		if (status !== gl.FRAMEBUFFER_COMPLETE) {
			console.warn("dwGfxVolumetricFog: composite framebuffer incomplete (" + status + "); fog disabled this frame.");
			gl.deleteFramebuffer(fbo);
			this.fbo = null;
			return false;
		}
		this.fbo = fbo;
		this.fboColorTexHandle = handle;
		return true;
	}

	// Feedback-loop guard. With `this.fbo` bound as the current draw/read target, verify the
	// texture the fog is about to sample (`depthHandle`, the scene DEPTH_ATTACHMENT) is NOT
	// attached to that bound framebuffer. Checks BOTH the draw and read framebuffers (WebGL2
	// binds them separately). Sets this.fbSafe = "SAFE" | "LOOP" and, on a loop, warns once.
	// Returns true when it is safe to sample. Touches no state; queries only.
	_assertNoDepthFeedback(gl, depthHandle)
	{
		const attachedDepth = (target) => {
			try {
				const type = gl.getFramebufferAttachmentParameter(target, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
				if (type !== gl.TEXTURE) { return null; }
				return gl.getFramebufferAttachmentParameter(target, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME);
			} catch (e) { return null; }
		};
		// gl.FRAMEBUFFER queries the draw framebuffer; also check the read framebuffer.
		const drawDepth = attachedDepth(gl.DRAW_FRAMEBUFFER || gl.FRAMEBUFFER);
		const readDepth = attachedDepth(gl.READ_FRAMEBUFFER || gl.FRAMEBUFFER);
		const loop = (drawDepth === depthHandle) || (readDepth === depthHandle);
		this.fbSafe = loop ? "LOOP" : "SAFE";
		if (loop && !this._fbLoopLogged) {
			this._fbLoopLogged = true;
			console.warn("dwGfxVolumetricFog: FEEDBACK LOOP -- the scene depth texture is attached " +
				"to the bound draw/read framebuffer while the fog is sampling it. The sample would be " +
				"undefined (reads 0). Skipping the fog draw this frame. The composite destination must " +
				"be a color-only FBO that shares NO attachment with the sampled scene depth.");
		}
		return !loop;
	}

	// Draw-time proof that the depth sampler path is wired correctly. Called AFTER the depth
	// texture is bound last on DEPTH_UNIT (so ACTIVE_TEXTURE is already that unit) and BEFORE
	// drawArrays. Verifies three independent facts and records them in this.depthBindDiag
	// ("depthUnit=<n> bind=OK uniform=OK"), warning once on any failure. Queries only; the
	// active unit is already the depth unit, so reading TEXTURE_BINDING_2D needs no change.
	_assertDepthSampler(gl, depthHandle)
	{
		const wantUnit = this.DEPTH_UNIT;
		const activeOk = (gl.getParameter(gl.ACTIVE_TEXTURE) === (gl.TEXTURE0 + wantUnit));
		const boundOk  = (gl.getParameter(gl.TEXTURE_BINDING_2D) === depthHandle);
		const uniOk    = (this.depthSamplerLoc !== null) &&
			(gl.getUniform(this.programInfo.program, this.depthSamplerLoc) === wantUnit);
		this.depthBindDiag = "depthUnit=" + wantUnit +
			" bind=" + (boundOk ? "OK" : "BAD") +
			" uniform=" + (uniOk ? "OK" : "BAD") +
			(activeOk ? "" : " active=BAD");
		const allOk = activeOk && boundOk && uniOk;
		if (!allOk && !this._depthBindLogged) {
			this._depthBindLogged = true;
			console.warn("dwGfxVolumetricFog: DEPTH SAMPLER BINDING FAILED -- " + this.depthBindDiag +
				". texture(u_depthTexture) would sample unit " + wantUnit + ", which must hold the live " +
				"scene depth texture with u_depthTexture == " + wantUnit + "; otherwise the read is 0 and " +
				"marchDist collapses (Debug Mode 1 all black).");
		}
		return allOk;
	}

	// Composite fog into dwGfx.sceneColorTexture using dwGfx.sceneDepthTexture.
	// Call after the opaque scene (and skybox) have been drawn into the scene
	// framebuffer and before bloom/tone mapping. Returns true if fog was applied.
	// Returns false (no-op) if fog is unavailable or the scene has no sampleable
	// depth texture (the fog-disabled render path), so callers never need to guard.
	composite(cameraView)
	{
		if (!this.ok) {
			return false;
		}
		const gl = dwGfx.gl();

		const colorObj = dwGfx.sceneColorTexture;
		if (!colorObj || !colorObj.img || !gl.isTexture(colorObj.img.drawInfo.texture)) {
			return false;
		}
		// SINGLE OWNER, QUERIED AT RENDER TIME: ask the scene-target owner (dwGfx) for the
		// exact WebGLTexture currently attached to its DEPTH_ATTACHMENT. The fog keeps NO
		// long-lived depth handle of its own -- previously a duplicate wrapper reference could
		// resolve to a different WebGLTexture than the one rendered into (HUD "TEX id=MISMATCH"),
		// so the fog sampled a never-rendered texture and read 0 everywhere. With no second
		// stored handle to go stale, divergence is impossible. Ownership is not transferred:
		// dwGfx still deletes/replaces the texture. null => renderbuffer / not attached.
		const depthHandle = dwGfx.getRenderSceneDepthTexture(0);
		if (!depthHandle) {
			return false;
		}
		if (!this._ensureFBO(colorObj)) {
			return false;
		}

		const w = colorObj.img.drawInfo.width;
		const h = colorObj.img.drawInfo.height;

		// ---- capture prior GL state ----
		const prevFBO       = gl.getParameter(gl.FRAMEBUFFER_BINDING);
		const prevViewport  = gl.getParameter(gl.VIEWPORT);
		const prevProgram   = gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO       = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevActiveTex = gl.getParameter(gl.ACTIVE_TEXTURE);
		const prevBlend     = gl.isEnabled(gl.BLEND);
		const prevDepthTest = gl.isEnabled(gl.DEPTH_TEST);
		const prevCull      = gl.isEnabled(gl.CULL_FACE);
		const prevDepthMask = gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevColorMask = gl.getParameter(gl.COLOR_WRITEMASK);
		const prevSrcRGB    = gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB    = gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcAlpha  = gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstAlpha  = gl.getParameter(gl.BLEND_DST_ALPHA);
		gl.activeTexture(gl.TEXTURE1);
		const prevTex1      = gl.getParameter(gl.TEXTURE_BINDING_2D);
		gl.activeTexture(gl.TEXTURE0);
		const prevTex0      = gl.getParameter(gl.TEXTURE_BINDING_2D);

		// camera ray reconstruction (m4 only). u_invProj inverts ONLY the projection, giving
		// both the VIEW-space ray direction (near-plane point; camera at origin) and the robust
		// VIEW-space DISTANCE (length is the world distance along the ray). u_invView is the
		// camera world matrix (= inverse(view)); it rotates the view-space ray direction into
		// world space (w = 0, rotation only). Deriving the direction this way avoids building the
		// enormous far-plane world endpoint that lost precision on long rays. The camera position
		// is the worldMatrix translation, EXACTLY as applyStandardPBR derives it, so the fog ray
		// matches the scene render.
		const invProj       = m4.inverse(cameraView.projectionMatrix);
		const cm            = cameraView.worldMatrix;

		let steps = this.steps | 0;
		if (steps < 1) { steps = 1; }

		// ---- fog composite pass ----
		// Bind the SEPARATE color-only destination FIRST, so the scene framebuffer (which owns
		// the depth attachment the fog is about to sample) is no longer the bound draw/read
		// target. gl.bindFramebuffer(FRAMEBUFFER, ...) rebinds BOTH the draw and read targets,
		// fully detaching the scene framebuffer -- the sampled depth can no longer be in a
		// feedback loop with the draw destination.
		gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);

		// Loud feedback-loop guard: prove the depth we are about to sample is NOT attached to
		// the framebuffer bound as the draw/read target. If it ever is (e.g. a future refactor
		// makes the destination share the scene depth), skip the undefined draw and log once
		// instead of silently sampling zeros.
		if (!this._assertNoDepthFeedback(gl, depthHandle)) {
			// restore the exact prior state before bailing (mirror the restore block below).
			gl.activeTexture(gl.TEXTURE1); gl.bindTexture(gl.TEXTURE_2D, prevTex1);
			gl.activeTexture(gl.TEXTURE0); gl.bindTexture(gl.TEXTURE_2D, prevTex0);
			gl.activeTexture(prevActiveTex);
			gl.bindVertexArray(prevVAO);
			gl.useProgram(prevProgram);
			gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
			if (prevBlend)     { gl.enable(gl.BLEND); }      else { gl.disable(gl.BLEND); }
			if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
			if (prevCull)      { gl.enable(gl.CULL_FACE); }  else { gl.disable(gl.CULL_FACE); }
			gl.depthMask(prevDepthMask);
			gl.colorMask(prevColorMask[0], prevColorMask[1], prevColorMask[2], prevColorMask[3]);
			gl.bindFramebuffer(gl.FRAMEBUFFER, prevFBO);
			gl.viewport(prevViewport[0], prevViewport[1], prevViewport[2], prevViewport[3]);
			return false;
		}

		gl.viewport(0, 0, w, h);
		gl.useProgram(this.programInfo.program);
		gl.bindVertexArray(this.vao);

		gl.disable(gl.DEPTH_TEST);
		gl.depthMask(false);
		gl.disable(gl.CULL_FACE);
		gl.colorMask(true, true, true, true);
		gl.enable(gl.BLEND);
		gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);

		// Weather map completeness: bind the real map when ready, else the 1x1 white
		// placeholder (a normal filterable color texture) so the color sampler is always
		// complete. Never bind the depth texture on the weather unit: on strict iOS/Safari
		// drivers a depth texture bound to a non-shadow sampler2D leaves the draw's texture
		// completeness undefined, which breaks the constant-fog fallback.
		const useWeatherMap = !!(this.weatherReady && this.weatherTex && gl.isTexture(this.weatherTex));

		// Noise is on only when enabled, the volume built, its sampler is active, and the
		// texture is live. windVelocity * time drives the world-space animation; the phase is
		// wrapped to [0,1) (the volume tiles at every integer under REPEAT) so it stays small
		// and precise across long sessions instead of growing without bound.
		const noiseOn = !!(this.noiseEnabled && this.noiseReady && this.noiseSamplerLoc !== null &&
			this.noiseTex && gl.isTexture(this.noiseTex));
		const tSec = (typeof performance !== "undefined" && performance.now) ? (performance.now() * 0.001) : (Date.now() * 0.001);
		const wv = this.windVelocity;
		const wrap01 = (x) => x - Math.floor(x);
		const noisePhase = [wrap01(wv[0] * tSec), wrap01(wv[1] * tSec), wrap01(wv[2] * tSec)];

		// Flatten the scattered pockets (or the single-pocket fallback) into fixed-size
		// arrays sized to the shader's DW_FOG_MAX_POCKETS.
		const pk = this._buildPocketUniforms();

		// ---- Step 5A/5B runtime state ----
		// Moon scattering is a pure RGB add; it is on only when explicitly enabled. moonDir is
		// normalized here (a zero/degenerate vector falls back to straight up so dot() is finite).
		const moonOn = !!this.moonEnabled;
		const md = (Array.isArray(this.moonDir) && this.moonDir.length >= 3) ? this.moonDir : [0.0, 1.0, 0.0];
		const mdLen = Math.hypot(md[0], md[1], md[2]);
		const moonDirN = (mdLen > 1e-6) ? [md[0] / mdLen, md[1] / mdLen, md[2] / mdLen] : [0.0, 1.0, 0.0];
		// Shadowing is on only when: moon on, enabled, its sampler is active, a light-space matrix
		// is supplied, and a REAL shadow texture is a live GL texture. Otherwise it falls back to
		// the far placeholder (fully lit) so Step 5A still works exactly. This is the single
		// authoritative validity decision; the shader's visRatio collapses to 1.0 when shadow is off.
		const haveShadowTex = !!(this.shadowTexture && gl.isTexture(this.shadowTexture));
		const shadowOn = !!(moonOn && this.shadowEnabled && this.shadowSamplerLoc !== null &&
			this.shadowMatrix && haveShadowTex);
		// State + the sampling mode that actually produced this frame, e.g.
		//   shadow[on PCF3 stride1 jit0.75 512]   /   shadow[on tap1 stride2 jit0 512]
		// so a banding/edge report can be read straight off the HUD instead of guessed at. The mode
		// suffix is only appended when shadowing is actually running (it means nothing otherwise).
		const shadowMode = " " + ((this.shadowPCF | 0) === 0 ? "tap1" : "PCF3") +
			" stride" + Math.max(this.shadowStride | 0, 1) +
			" jit" + Math.min(Math.max(this.shadowJitter, 0.0), 1.0) +
			" " + Math.max(this.shadowMapSize | 0, 1);
		this.shadowDiag = "shadow[" + (this.shadowEnabled ? (shadowOn ? "on" + shadowMode : (haveShadowTex ? "wait" : "noTex")) : "off") + "]";
		// Identity fallback keeps the mat4 upload well-formed when no real matrix is set (shadowOn
		// is false then, so the value is never actually sampled).
		const shadowMat = this.shadowMatrix ? this.shadowMatrix : [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1];

		// ---- Step 6 march cost controls, resolved once per composite ----
		// eeT: the early-exit transmittance threshold. Clamped to [0, 0.5]; 0 disables the
		// early-out entirely, and the 0.5 ceiling stops a typo from terminating rays while
		// they are still half transparent. swl: the opt-in world-space step target; negative
		// and non-finite values collapse to 0 (off).
		const eeT = Number.isFinite(this.earlyExitTransmittance)
			? Math.min(Math.max(this.earlyExitTransmittance, 0.0), 0.5) : 0.001;
		const swl = Number.isFinite(this.stepWorldLength) ? Math.max(this.stepWorldLength, 0.0) : 0.0;
		// HUD: the resolved march configuration, e.g. march[steps28 union ee0.001] or, with the
		// adaptive lever engaged, march[steps28 union swl1.5 ee0.001]. "union" records that the
		// budget is spread over the occupied interval union rather than the whole hull.
		this.marchDiag = "march[steps" + pk.steps + " union" +
			(swl > 0.0 ? " swl" + swl : "") +
			(eeT > 0.0 ? " ee" + eeT : " ee-off") + "]";

		// Set ONLY the non-sampler uniforms through twgl. The two sampler uniforms
		// (u_depthTexture, u_weatherMap) are DELIBERATELY excluded: twgl's sampler setter is
		// version-dependent and may allocate its own texture unit and/or rebind the texture
		// when handed a value, silently overriding the manual unit-0 depth bind -- that was
		// the one path that differed from the clean probe (raw uniform1i) which reads this
		// same texture correctly, and it left texture(u_depthTexture) sampling 0 everywhere.
		twgl.setUniforms(this.programInfo, {
			u_invProj:      invProj,
			u_invView:      cm,
			u_cameraPos:    [cm[12], cm[13], cm[14]],
			u_density:      this.density,
			u_fogColor:     this.color,
			u_maxDistance:  this.maxDistance,
			u_steps:        steps,
			u_debugMode:    this.debugMode | 0,
			// ---- Layer 2 weather-map uniforms (sampler u_weatherMap set raw below) ----
			u_useWeatherMap:     useWeatherMap ? 1 : 0,
			u_mapWorldSize:      this.mapWorldSize,
			u_worldOffset:       this.worldOffset,
			u_coverageThreshold: this.coverageThreshold,
			u_edgeSoftness:      this.edgeSoftness,
			u_mapInfluence:      this.mapInfluence,
			// ---- analytic pocket uniforms (arrays sized to DW_FOG_MAX_POCKETS) ----
			u_fogMode:       (this.fogMode === "analytic") ? 1 : 0,
			u_pocketCount:   pk.count,
			u_pocketSteps:   pk.steps,
			u_pocketCenters: pk.centers,
			u_pocketRadii:   pk.radii,
			u_pocketFeathers: pk.feathers,
			u_pocketDensity: pk.density,
			u_ignoreSceneDepth: this.ignoreSceneDepth ? 1 : 0,
			// ---- Step 4 noise uniforms (sampler u_noiseVolume set raw below) ----
			// Clamp every control to a sane range; noiseOn==0 makes the shader take the exact
			// pre-noise path (byte-for-byte A/B), so toggling is a true no-op comparison.
			u_noiseEnabled:  noiseOn ? 1 : 0,
			u_noiseScale:    Math.max(this.noiseScale, 1.0e-4),
			u_noiseStrength: Math.min(Math.max(this.noiseStrength, 0.0), 1.0),
			u_noiseContrast: Math.min(Math.max(this.noiseContrast, 0.1), 8.0),
			u_edgeErosion:   Math.min(Math.max(this.edgeErosion, 0.0), 1.0),
			u_shapeWarp:     Math.min(Math.max(this.shapeWarp, 0.0), 1.0),
			u_noisePhase:    noisePhase,
			// ---- Step 5A moon-scattering uniforms (RGB only; alpha untouched) ----
			// moonOff => u_moonEnabled 0 => shader takes the exact prior color path.
			u_moonEnabled:    moonOn ? 1 : 0,
			u_moonDir:        moonDirN,
			u_moonColor:      this.moonColor,
			u_moonIntensity:  Math.max(this.moonIntensity, 0.0),
			u_moonAnisotropy: Math.min(Math.max(this.moonAnisotropy, -0.9), 0.9),
			u_moonAmbient:    Math.max(this.moonAmbient, 0.0),
			// ---- Step 5B shadow uniforms (sampler u_shadowMap set raw below) ----
			// shadowOff => u_shadowEnabled 0 => visRatio stays 1.0 (fully lit), Step 5A exact.
			u_shadowEnabled:  shadowOn ? 1 : 0,
			u_shadowMatrix:   shadowMat,
			u_shadowBias:     Math.max(this.shadowBias, 0.0),
			u_shadowStride:   Math.max(this.shadowStride | 0, 1),
			// Real texel size -> the PCF offsets land on actual neighbouring texels. Guarded so a
			// bad/zero size can never produce a division by zero or an enormous offset.
			u_shadowTexel:    1.0 / Math.max(this.shadowMapSize | 0, 1),
			u_shadowPCF:      (this.shadowPCF | 0) === 0 ? 0 : 1,
			u_shadowSoftness: Math.min(Math.max(this.shadowSoftness, 0.0), 8.0),
			u_shadowJitter:   Math.min(Math.max(this.shadowJitter, 0.0), 1.0),
			// ---- Step 6 march cost controls. Clamped so a bad value can never make the march
			// unbounded (stepWorldLength) or exit on the first sample (earlyExitTransmittance).
			// Defaults 0.001 / 0.0 reproduce the previous march semantics exactly.
			u_earlyExitT:      Math.min(Math.max(eeT, 0.0), 0.5),
			u_stepWorldLength: Math.max(swl, 0.0),
		});

		// ---- samplers: raw, explicit units, depth bound LAST, then asserted ----
		// Assign each sampler -> unit with raw gl.uniform1i on the cached locations (the fog
		// program is current). This is exactly what the passing clean probe does.
		gl.uniform1i(this.depthSamplerLoc, this.DEPTH_UNIT);
		if (this.weatherSamplerLoc !== null) { gl.uniform1i(this.weatherSamplerLoc, this.WEATHER_UNIT); }
		if (this.shadowSamplerLoc !== null) { gl.uniform1i(this.shadowSamplerLoc, this.SHADOW_UNIT); }

		// Bind weather on its own unit FIRST, then the 3D noise volume on NOISE_UNIT, then the
		// live scene depth on DEPTH_UNIT LAST so no later bind (helper, weather, noise, twgl)
		// can overwrite the depth unit before the draw. ACTIVE_TEXTURE is left on the depth
		// unit for the draw-time assert. Noise is on its OWN unit, so this preserves the
		// confirmed depth-binding fix exactly (depth unit is still the last thing touched).
		gl.activeTexture(gl.TEXTURE0 + this.WEATHER_UNIT);
		gl.bindTexture(gl.TEXTURE_2D, useWeatherMap ? this.weatherTex : this.placeholderTex);
		this._bindNoiseSampler(gl);
		// Step 5B: bind the shadow map on its OWN unit (real texture when valid, else the far
		// placeholder so the compare always returns fully-lit). Its COMPARE_MODE is set per-texture;
		// the placeholder already carries COMPARE_REF_TO_TEXTURE/LEQUAL. A real engine shadow map is
		// a plain DEPTH24 depth texture, so enable hardware compare on it here (idempotent) -- this
		// is the ONLY place the shadow texture's sampler state is set, avoiding the prior twgl
		// sampler-reassignment bug (samplers are all raw uniform1i, bound explicitly, depth LAST).
		if (this.shadowSamplerLoc !== null) {
			const shadowTex = shadowOn ? this.shadowTexture : this.shadowPlaceholderTex;
			gl.activeTexture(gl.TEXTURE0 + this.SHADOW_UNIT);
			gl.bindTexture(gl.TEXTURE_2D, shadowTex);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
			gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_FUNC, gl.LEQUAL);
		}
		gl.activeTexture(gl.TEXTURE0 + this.DEPTH_UNIT);
		gl.bindTexture(gl.TEXTURE_2D, depthHandle);

		// Runtime proof that the depth sampler truly resolves to DEPTH_UNIT, that unit holds
		// the exact live depthHandle, and ACTIVE_TEXTURE is on it -- all at draw time. Fails
		// loudly (console + HUD depthBindDiag) instead of silently sampling 0.
		this._assertDepthSampler(gl, depthHandle);

		// Step 5B debug assert (mode 6 == shadow view): prove u_shadowMap resolves to SHADOW_UNIT
		// and that unit holds the exact expected texture (real map when shadowOn, else placeholder).
		// Runs only in the shadow debug view so it costs nothing on the production path. Records the
		// result on shadowDiag ("bind=OK" / "bind=MISMATCH") for the HUD instead of failing the draw.
		if ((this.debugMode | 0) === 6 && this.shadowSamplerLoc !== null) {
			const want = shadowOn ? this.shadowTexture : this.shadowPlaceholderTex;
			const uniVal = gl.getUniform(this.programInfo.program, this.shadowSamplerLoc);
			const prevA = gl.getParameter(gl.ACTIVE_TEXTURE);
			gl.activeTexture(gl.TEXTURE0 + this.SHADOW_UNIT);
			const boundTex = gl.getParameter(gl.TEXTURE_BINDING_2D);
			gl.activeTexture(prevA);
			const bindOk = (uniVal === this.SHADOW_UNIT) && (boundTex === want) && gl.isTexture(boundTex);
			this.shadowDiag += " bind=" + (bindOk ? "OK" : "MISMATCH");
		}

		gl.drawArrays(gl.TRIANGLES, 0, 3);

		// One-time diagnostic build probe. Runs after the real draw (program/VAO/unit-0
		// depth binding still current) and before state restore below, which rebinds the
		// prior framebuffer/program/textures and cleans up everything the probe touches.
		if (!this._depthDiagDone) {
			this._depthDiagDone = true;
			this._runDepthDiagnostics(gl, depthHandle, w, h);
		}

		// ---- restore prior GL state exactly ----
		gl.activeTexture(gl.TEXTURE1);
		gl.bindTexture(gl.TEXTURE_2D, prevTex1);
		gl.activeTexture(gl.TEXTURE0);
		gl.bindTexture(gl.TEXTURE_2D, prevTex0);
		gl.activeTexture(prevActiveTex);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);
		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
		if (prevBlend)     { gl.enable(gl.BLEND); }      else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (prevCull)      { gl.enable(gl.CULL_FACE); }  else { gl.disable(gl.CULL_FACE); }
		gl.depthMask(prevDepthMask);
		gl.colorMask(prevColorMask[0], prevColorMask[1], prevColorMask[2], prevColorMask[3]);
		gl.bindFramebuffer(gl.FRAMEBUFFER, prevFBO);
		gl.viewport(prevViewport[0], prevViewport[1], prevViewport[2], prevViewport[3]);
		return true;
	}

	// One-time runtime probe (diagnostic build). Static source cannot explain a solid-black
	// Mode 4 rawDepth (== 0) because the whole path is self-consistent, so this asserts the
	// three runtime facts that decide the root cause:
	//   (1) the scene framebuffer is COMPLETE,
	//   (2) its DEPTH_ATTACHMENT is a TEXTURE whose GL object is EXACTLY the texture the fog
	//       samples on unit 0 (not a renderbuffer, not stale, not the wrong variable), and
	//   (3) the grayscale value the shader actually samples at a background corner and the
	//       center pixel (guarded Mode-4 readback), so "reads 0" is measured, not assumed.
	// Interpretation (logged once + on HUD as fogEffect.depthDiag):
	//   RBUF / NONE            -> sampleable-depth scene FBO was never built (ensureSceneTargets
	//                             fell back to the renderbuffer path) -> fog samples a texture
	//                             that was never rendered into -> 0.
	//   TEX id=MISMATCH        -> a resize/recreation left dwGfx.sceneDepthTexture pointing at a
	//                             different object than the FBO attachment -> stale/wrong -> 0.
	//   TEX id=OK bg 0.000     -> attachment is perfect; the device's plain sampler2D read of a
	//                             DEPTH_COMPONENT24 texture returns 0 (driver/format issue).
	//   TEX id=OK bg ~1.000    -> depth is actually fine; the black is elsewhere (mode wiring).
	// Never throws: the ignoreSceneDepth fallback keeps the scene rendering regardless.
	_runDepthDiagnostics(gl, boundDepthHandle, w, h)
	{
		let attachStr = "?";
		let valStr = "val n/a";
		try {
			gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);
			const complete = (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE);
			const type = gl.getFramebufferAttachmentParameter(
				gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
			const typeStr = (type === gl.TEXTURE) ? "TEX"
				: (type === gl.RENDERBUFFER) ? "RBUF"
				: (type === gl.NONE) ? "NONE" : String(type);
			let idMatch = false;
			if (type === gl.TEXTURE) {
				// The attachment's own object vs the handle fog actually bound on unit 0.
				// After the single-source-of-truth fix these are the same query, so this is
				// OK by construction; it stays as a live assertion against future regressions.
				const name = gl.getFramebufferAttachmentParameter(
					gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME);
				idMatch = (name === boundDepthHandle);
			}
			attachStr = typeStr + (complete ? "" : "!INCOMPLETE") + (type === gl.TEXTURE ? (idMatch ? " id=OK" : " id=MISMATCH") : "");

			// Numeric readback: render Mode 4 (raw depth as grayscale) into the fog composite
			// color target, then read back a background corner + the center. The composite's
			// program/VAO/unit-0 depth binding are still current from the draw above.
			gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);
			twgl.setUniforms(this.programInfo, { u_debugMode: 4 });
			gl.drawArrays(gl.TRIANGLES, 0, 3);
			const fmt = gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_FORMAT);
			const typ = gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_TYPE);
			const readR = (px, py) => {
				if (fmt !== gl.RGBA) { return NaN; }
				if (typ === gl.UNSIGNED_BYTE) { const b = new Uint8Array(4);  gl.readPixels(px, py, 1, 1, fmt, typ, b); return b[0] / 255; }
				if (typ === gl.FLOAT)         { const f = new Float32Array(4); gl.readPixels(px, py, 1, 1, fmt, typ, f); return f[0]; }
				if (typ === gl.HALF_FLOAT || typ === 0x8D61) { const u = new Uint16Array(4); gl.readPixels(px, py, 1, 1, fmt, typ, u); return dwGfxVolumetricFog._halfToFloat(u[0]); }
				return NaN;
			};
			const cx = Math.max(0, Math.min(w - 1, w >> 1));
			const cy = Math.max(0, Math.min(h - 1, h >> 1));
			const bg  = readR(1, 1);      // corner: expected background (~1.0 white)
			const ctr = readR(cx, cy);    // center: geometry (< 1.0 if depth is written)
			const f = (x) => (isFinite(x) ? x.toFixed(3) : "n/a");
			valStr = "bg " + f(bg) + " ctr " + f(ctr);
		}
		catch (e) {
			attachStr = "probe-threw:" + (e && e.message ? e.message : e);
		}
		this.depthDiag = "depth[" + attachStr + " | " + valStr + "]";
		if (!this._depthDiagLogged) {
			this._depthDiagLogged = true;
			console.warn("dwGfxVolumetricFog DIAGNOSTIC " + this.depthDiag +
				" -- expect 'TEX id=OK | bg ~1.000 ctr <1.000'. RBUF/NONE => sampleable-depth FBO " +
				"not built; id=MISMATCH => stale/wrong depth texture; bg 0.000 with TEX id=OK => " +
				"device returns 0 sampling DEPTH_COMPONENT24 (format). ignoreSceneDepth fallback stays on.");
		}
	}

	// -------------------------------------------------------------------------------------
	// Deterministic depth ISOLATION probe (temporary diagnostic; changes NO production
	// rendering -- it only runs when explicitly called, e.g. the demo's 'i' key).
	//
	// Purpose: a black Mode-4 rawDepth (== 0) with a proven-correct attachment (TEX id=OK)
	// has exactly two possible causes; this test decides which, on the actual device:
	//   (A) SAMPLER/FORMAT failure -- a plain sampler2D cannot read this depth texture's
	//       format back as a value on this driver, OR
	//   (B) a later scene-pass WRITE/OVERWRITE -- the attachment is sampled fine but was
	//       left cleared/zeroed by the time the fog reads it.
	//
	// Method (all on the EXACT live scene DEPTH_ATTACHMENT the fog samples):
	//   1. baseline: read the current attachment (bg corner + center) as production left it.
	//   2. clear that attachment to a KNOWN nonzero midrange sentinel (default 0.5) with NO
	//      geometry drawn (pure clearDepth + clear(DEPTH_BUFFER_BIT)), then read it straight
	//      back through the same Mode-4 sampler.
	// Verdict:
	//   sentinel reads back ~sentinel  -> SAMPLING OK  => if baseline was ~0 the cause is (B):
	//                                     the scene pass is not leaving valid depth.
	//   sentinel reads back ~0 (black) -> SAMPLING BROKEN => cause (A): format/sampler.
	//
	// Also captures the exact scene-FBO depth state (completeness, attachment type+id,
	// DEPTH_WRITEMASK, DEPTH_FUNC, DEPTH_TEST, DEPTH_CLEAR_VALUE, TEXTURE_COMPARE_MODE).
	// Every GL bit touched is saved and restored; clearDepth is restored so later frames are
	// unaffected. The live scene depth holds the sentinel only for the REMAINDER of this
	// frame (next beginRenderSceneFrameBuffer re-clears to 1.0 and redraws geometry).
	runDepthIsolationTest(sentinel = 0.5)
	{
		const gl = dwGfx.gl();
		if (!this.ok || !gl) { this.depthIsolation = "isolation[fog not ready]"; return this.depthIsolation; }
		let s = (typeof sentinel === "number" && isFinite(sentinel)) ? sentinel : 0.5;
		s = Math.min(1.0, Math.max(0.0, s));

		const colorObj = dwGfx.sceneColorTexture;
		if (!colorObj || !colorObj.img || !gl.isTexture(colorObj.img.drawInfo.texture)) {
			this.depthIsolation = "isolation[no scene color texture]"; return this.depthIsolation;
		}
		const depthHandle = dwGfx.getRenderSceneDepthTexture(0);
		if (!depthHandle) {
			this.depthIsolation = "isolation[no sampleable scene depth (renderbuffer/fog-off path)]"; return this.depthIsolation;
		}
		if (!this._ensureFBO(colorObj)) {
			this.depthIsolation = "isolation[composite FBO incomplete]"; return this.depthIsolation;
		}
		const w = colorObj.img.drawInfo.width, h = colorObj.img.drawInfo.height;

		// ---- save every GL bit this probe touches ----
		const prevFBO        = gl.getParameter(gl.FRAMEBUFFER_BINDING);
		const prevViewport   = gl.getParameter(gl.VIEWPORT);
		const prevProgram    = gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO        = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevActiveTex  = gl.getParameter(gl.ACTIVE_TEXTURE);
		const prevBlend      = gl.isEnabled(gl.BLEND);
		const prevDepthTest  = gl.isEnabled(gl.DEPTH_TEST);
		const prevCull       = gl.isEnabled(gl.CULL_FACE);
		const prevScissor    = gl.isEnabled(gl.SCISSOR_TEST);
		const prevDepthMask  = gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevColorMask  = gl.getParameter(gl.COLOR_WRITEMASK);
		const prevClearDepth = gl.getParameter(gl.DEPTH_CLEAR_VALUE);
		gl.activeTexture(gl.TEXTURE1); const prevTex1 = gl.getParameter(gl.TEXTURE_BINDING_2D);
		gl.activeTexture(gl.TEXTURE0); const prevTex0 = gl.getParameter(gl.TEXTURE_BINDING_2D);

		const num = (x) => (isFinite(x) ? x.toFixed(3) : "n/a");
		const near = (x, t) => (isFinite(x) && Math.abs(x - t) <= 0.10);
		const funcName = (f) => ({
			[gl.NEVER]:"NEVER", [gl.LESS]:"LESS", [gl.EQUAL]:"EQUAL", [gl.LEQUAL]:"LEQUAL",
			[gl.GREATER]:"GREATER", [gl.NOTEQUAL]:"NOTEQUAL", [gl.GEQUAL]:"GEQUAL", [gl.ALWAYS]:"ALWAYS"
		}[f] || ("0x" + (f >>> 0).toString(16)));

		// draw Mode-4 rawDepth of `depthHandle` into the color-only composite FBO and read
		// back a background corner + center. Assumes nothing about prior binding state.
		const drawAndRead = () => {
			gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);
			gl.viewport(0, 0, w, h);
			gl.useProgram(this.programInfo.program);
			gl.bindVertexArray(this.vao);
			gl.disable(gl.DEPTH_TEST);
			gl.disable(gl.BLEND);
			gl.disable(gl.CULL_FACE);
			gl.disable(gl.SCISSOR_TEST);
			gl.colorMask(true, true, true, true);
			gl.activeTexture(gl.TEXTURE1);
			gl.bindTexture(gl.TEXTURE_2D, this.placeholderTex); // keep unit 1 a complete color texture
			gl.activeTexture(gl.TEXTURE0);
			gl.bindTexture(gl.TEXTURE_2D, depthHandle);
			// Samplers via raw uniform1i (never twgl) so the depth unit can't be reassigned.
			// Mode 4 returns raw depth before any march, but u_noiseVolume is still an active
			// sampler3D: pin it to NOISE_UNIT (with the volume bound) so it never defaults to
			// unit 0 where the 2D depth texture lives -- a sampler-type collision there would
			// fail this diagnostic draw. Depth is rebound LAST to keep unit 0 authoritative.
			twgl.setUniforms(this.programInfo, { u_useWeatherMap: 0, u_debugMode: 4, u_noiseEnabled: 0 });
			gl.uniform1i(this.depthSamplerLoc, this.DEPTH_UNIT);
			if (this.weatherSamplerLoc !== null) { gl.uniform1i(this.weatherSamplerLoc, this.WEATHER_UNIT); }
			this._bindNoiseSampler(gl);
			gl.activeTexture(gl.TEXTURE0 + this.DEPTH_UNIT);
			gl.bindTexture(gl.TEXTURE_2D, depthHandle);
			gl.drawArrays(gl.TRIANGLES, 0, 3);
			const rfmt = gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_FORMAT);
			const rtyp = gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_TYPE);
			const readR = (px, py) => {
				if (rfmt !== gl.RGBA) { return NaN; }
				if (rtyp === gl.UNSIGNED_BYTE) { const b = new Uint8Array(4);  gl.readPixels(px, py, 1, 1, rfmt, rtyp, b); return b[0] / 255; }
				if (rtyp === gl.FLOAT)         { const f = new Float32Array(4); gl.readPixels(px, py, 1, 1, rfmt, rtyp, f); return f[0]; }
				if (rtyp === gl.HALF_FLOAT || rtyp === 0x8D61) { const u = new Uint16Array(4); gl.readPixels(px, py, 1, 1, rfmt, rtyp, u); return dwGfxVolumetricFog._halfToFloat(u[0]); }
				return NaN;
			};
			const cx = Math.max(0, Math.min(w - 1, w >> 1));
			const cy = Math.max(0, Math.min(h - 1, h >> 1));
			return { bg: readR(1, 1), ctr: readR(cx, cy) };
		};

		let stateStr = "state[n/a]";
		let verdict = "inconclusive";
		try {
			// ---- capture the exact scene-FBO depth state ----
			gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);
			const complete = (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE);
			const attType  = gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE);
			const attName  = (attType === gl.TEXTURE) ? gl.getFramebufferAttachmentParameter(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME) : null;
			const attStr   = (attType === gl.TEXTURE) ? ("TEX" + (attName === depthHandle ? " id=OK" : " id=MISMATCH"))
				: (attType === gl.RENDERBUFFER) ? "RBUF" : (attType === gl.NONE) ? "NONE" : String(attType);
			const dFunc    = gl.getParameter(gl.DEPTH_FUNC);
			const dTest    = gl.isEnabled(gl.DEPTH_TEST);
			gl.activeTexture(gl.TEXTURE0);
			gl.bindTexture(gl.TEXTURE_2D, depthHandle);
			let cmp = 0; try { cmp = gl.getTexParameter(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE); } catch (e) { cmp = -1; }
			const cmpStr = (cmp === gl.NONE) ? "NONE" : (cmp === gl.COMPARE_REF_TO_TEXTURE) ? "COMPARE_REF!" : String(cmp);
			stateStr = "state[complete=" + (complete ? "Y" : "N") + " att=" + attStr +
				" writemask=" + (prevDepthMask ? 1 : 0) + " func=" + funcName(dFunc) +
				" test=" + (dTest ? "ON" : "OFF") + " cmp=" + cmpStr +
				" clear=" + num(prevClearDepth) + "]";

			// ---- (1) baseline: read production depth as-is ----
			const base = drawAndRead();

			// ---- (2) sentinel: clear the EXACT attachment to `s`, no geometry, read back ----
			gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);
			gl.disable(gl.SCISSOR_TEST);
			gl.depthMask(true);
			gl.clearDepth(s);
			gl.clear(gl.DEPTH_BUFFER_BIT);
			const sent = drawAndRead();

			const samplingOk = near(sent.bg, s) || near(sent.ctr, s);
			if (samplingOk) {
				verdict = "SAMPLING OK (sentinel " + num(s) + " read bg=" + num(sent.bg) + " ctr=" + num(sent.ctr) +
					") => plain sampler2D CAN read this depth. baseline bg=" + num(base.bg) + " ctr=" + num(base.ctr) +
					(near(base.bg, 0) ? " -> baseline ~0 => CAUSE B: scene pass leaves no valid depth (write/overwrite)"
						: " -> baseline nonzero => depth path is healthy");
			} else {
				verdict = "SAMPLING BROKEN (sentinel " + num(s) + " read bg=" + num(sent.bg) + " ctr=" + num(sent.ctr) +
					") => plain sampler2D CANNOT read this depth texture on this device -> CAUSE A: format/sampler";
			}
			this.depthIsolation = "isolation[" + verdict + " | " + stateStr + "]";
		}
		catch (e) {
			this.depthIsolation = "isolation[probe-threw: " + (e && e.message ? e.message : e) + "]";
		}
		finally {
			// ---- restore every GL bit exactly (clearDepth back to its prior value) ----
			gl.clearDepth(prevClearDepth);
			gl.activeTexture(gl.TEXTURE1); gl.bindTexture(gl.TEXTURE_2D, prevTex1);
			gl.activeTexture(gl.TEXTURE0); gl.bindTexture(gl.TEXTURE_2D, prevTex0);
			gl.activeTexture(prevActiveTex);
			gl.bindVertexArray(prevVAO);
			gl.useProgram(prevProgram);
			if (prevBlend)     { gl.enable(gl.BLEND); }      else { gl.disable(gl.BLEND); }
			if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
			if (prevCull)      { gl.enable(gl.CULL_FACE); }  else { gl.disable(gl.CULL_FACE); }
			if (prevScissor)   { gl.enable(gl.SCISSOR_TEST); } else { gl.disable(gl.SCISSOR_TEST); }
			gl.depthMask(prevDepthMask);
			gl.colorMask(prevColorMask[0], prevColorMask[1], prevColorMask[2], prevColorMask[3]);
			gl.bindFramebuffer(gl.FRAMEBUFFER, prevFBO);
			gl.viewport(prevViewport[0], prevViewport[1], prevViewport[2], prevViewport[3]);
		}

		console.warn("dwGfxVolumetricFog ISOLATION " + this.depthIsolation);
		return this.depthIsolation;
	}

	// -------------------------------------------------------------------------------------
	// DISPLAYED sentinel probe (temporary diagnostic). This is the definitive, HUMAN-VISIBLE
	// version of runDepthIsolationTest: the caller runs it INSTEAD of the scene pass and
	// returns from render() immediately, so nothing can clear/write the depth after us.
	//
	// Steps (all on the EXACT live scene DEPTH_ATTACHMENT the fog samples):
	//   1. bind dwGfx.sceneFramebuffer; verify checkFramebufferStatus === FRAMEBUFFER_COMPLETE.
	//   2. enable(DEPTH_TEST); depthMask(true); clearDepth(sentinel); clear(DEPTH_BUFFER_BIT)
	//      ONLY -- no geometry. Capture getError().
	//   3. draw that exact raw-depth attachment (Mode 4) straight to the DEFAULT framebuffer
	//      (the canvas) so the value is visible immediately, before any scene pass runs.
	// Verdict (visible on the canvas AND read back into the HUD string):
	//   whole canvas mid-gray (~sentinel) => sampler/texture/attachment path WORKS. So a black
	//                                         production Mode 4 is a later write/overwrite or a
	//                                         disabled depth write => CAUSE B.
	//   whole canvas black (~0)           => the sampler/texture/attachment path is DEFINITIVELY
	//                                         broken on this device => CAUSE A (format/sampler).
	// Restores framebuffer, clearDepth, depthMask, depthFunc, depthTest, and the rest of the
	// touched GL state; alters no durable state. Stored on this.depthSentinel and returned.
	presentDepthSentinelToCanvas(sentinel = 0.5)
	{
		const gl = dwGfx.gl();
		if (!this.ok || !gl) { this.depthSentinel = "sentinel[fog not ready]"; return this.depthSentinel; }
		let s = (typeof sentinel === "number" && isFinite(sentinel)) ? sentinel : 0.5;
		s = Math.min(1.0, Math.max(0.0, s));

		const depthHandle = dwGfx.getRenderSceneDepthTexture(0);
		if (!depthHandle) { this.depthSentinel = "sentinel[no sampleable scene depth (renderbuffer/fog-off path)]"; return this.depthSentinel; }

		const cw = gl.drawingBufferWidth, ch = gl.drawingBufferHeight;
		const num  = (x) => (isFinite(x) ? x.toFixed(3) : "n/a");
		const near = (x, t) => (isFinite(x) && Math.abs(x - t) <= 0.10);

		// ---- save every GL bit this probe touches ----
		const prevFBO        = gl.getParameter(gl.FRAMEBUFFER_BINDING);
		const prevViewport   = gl.getParameter(gl.VIEWPORT);
		const prevProgram    = gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO        = gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevActiveTex  = gl.getParameter(gl.ACTIVE_TEXTURE);
		const prevBlend      = gl.isEnabled(gl.BLEND);
		const prevDepthTest  = gl.isEnabled(gl.DEPTH_TEST);
		const prevCull       = gl.isEnabled(gl.CULL_FACE);
		const prevScissor    = gl.isEnabled(gl.SCISSOR_TEST);
		const prevDepthMask  = gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevColorMask  = gl.getParameter(gl.COLOR_WRITEMASK);
		const prevClearDepth = gl.getParameter(gl.DEPTH_CLEAR_VALUE);
		const prevDepthFunc  = gl.getParameter(gl.DEPTH_FUNC);
		gl.activeTexture(gl.TEXTURE1); const prevTex1 = gl.getParameter(gl.TEXTURE_BINDING_2D);
		gl.activeTexture(gl.TEXTURE0); const prevTex0 = gl.getParameter(gl.TEXTURE_BINDING_2D);

		let statusStr = "?", errStr = "?", pxStr = "n/a", verdict = "inconclusive";
		try {
			// ---- (1)+(2) clear the EXACT live scene depth attachment to the sentinel ----
			gl.bindFramebuffer(gl.FRAMEBUFFER, dwGfx.sceneFramebuffer);
			statusStr = (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE) ? "COMPLETE" : "INCOMPLETE";
			gl.disable(gl.SCISSOR_TEST);
			gl.enable(gl.DEPTH_TEST);
			gl.depthMask(true);
			gl.clearDepth(s);
			gl.clear(gl.DEPTH_BUFFER_BIT);
			const err = gl.getError();
			errStr = (err === gl.NO_ERROR) ? "NO_ERROR" : ("0x" + (err >>> 0).toString(16));

			// ---- (3) present that exact raw-depth attachment straight to the CANVAS ----
			gl.bindFramebuffer(gl.FRAMEBUFFER, null);
			gl.viewport(0, 0, cw, ch);
			gl.useProgram(this.programInfo.program);
			gl.bindVertexArray(this.vao);
			gl.disable(gl.DEPTH_TEST);
			gl.disable(gl.BLEND);
			gl.disable(gl.CULL_FACE);
			gl.disable(gl.SCISSOR_TEST);
			gl.colorMask(true, true, true, true);
			gl.activeTexture(gl.TEXTURE1);
			gl.bindTexture(gl.TEXTURE_2D, this.placeholderTex); // keep unit 1 a complete color texture
			gl.activeTexture(gl.TEXTURE0);
			gl.bindTexture(gl.TEXTURE_2D, depthHandle);
			// Samplers via raw uniform1i (never twgl) so the depth unit can't be reassigned.
			// Mode 4 returns raw depth before any march, but u_noiseVolume is still an active
			// sampler3D: pin it to NOISE_UNIT (with the volume bound) so it never defaults to
			// unit 0 where the 2D depth texture lives -- a sampler-type collision there would
			// fail this diagnostic draw. Depth is rebound LAST to keep unit 0 authoritative.
			twgl.setUniforms(this.programInfo, { u_useWeatherMap: 0, u_debugMode: 4, u_noiseEnabled: 0 });
			gl.uniform1i(this.depthSamplerLoc, this.DEPTH_UNIT);
			if (this.weatherSamplerLoc !== null) { gl.uniform1i(this.weatherSamplerLoc, this.WEATHER_UNIT); }
			this._bindNoiseSampler(gl);
			gl.activeTexture(gl.TEXTURE0 + this.DEPTH_UNIT);
			gl.bindTexture(gl.TEXTURE_2D, depthHandle);
			gl.drawArrays(gl.TRIANGLES, 0, 3);

			// read one center pixel of the canvas for the HUD (the same value the eye sees).
			const rfmt = gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_FORMAT);
			const rtyp = gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_TYPE);
			let px = NaN;
			if (rfmt === gl.RGBA) {
				const cx = Math.max(0, Math.min(cw - 1, cw >> 1));
				const cy = Math.max(0, Math.min(ch - 1, ch >> 1));
				if (rtyp === gl.UNSIGNED_BYTE) { const b = new Uint8Array(4);  gl.readPixels(cx, cy, 1, 1, rfmt, rtyp, b); px = b[0] / 255; }
				else if (rtyp === gl.FLOAT)    { const f = new Float32Array(4); gl.readPixels(cx, cy, 1, 1, rfmt, rtyp, f); px = f[0]; }
				else if (rtyp === gl.HALF_FLOAT || rtyp === 0x8D61) { const u = new Uint16Array(4); gl.readPixels(cx, cy, 1, 1, rfmt, rtyp, u); px = dwGfxVolumetricFog._halfToFloat(u[0]); }
			}
			pxStr = num(px);
			verdict = near(px, s) ? ("GRAY(~" + num(s) + ") SAMPLING WORKS => production black is CAUSE B (later write/overwrite or depth writes disabled)")
				: near(px, 0) ? "BLACK(~0) sampler/texture/attachment DEFINITIVELY broken => CAUSE A (format/sampler)"
				: ("UNEXPECTED px=" + pxStr);
			this.depthSentinel = "sentinel[fbo=" + statusStr + " err=" + errStr + " canvas.center=" + pxStr + " s=" + num(s) + " -> " + verdict + "]";
		}
		catch (e) {
			this.depthSentinel = "sentinel[probe-threw: " + (e && e.message ? e.message : e) + "]";
		}
		finally {
			// ---- restore every GL bit exactly ----
			gl.clearDepth(prevClearDepth);
			gl.depthFunc(prevDepthFunc);
			gl.activeTexture(gl.TEXTURE1); gl.bindTexture(gl.TEXTURE_2D, prevTex1);
			gl.activeTexture(gl.TEXTURE0); gl.bindTexture(gl.TEXTURE_2D, prevTex0);
			gl.activeTexture(prevActiveTex);
			gl.bindVertexArray(prevVAO);
			gl.useProgram(prevProgram);
			if (prevBlend)     { gl.enable(gl.BLEND); }      else { gl.disable(gl.BLEND); }
			if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
			if (prevCull)      { gl.enable(gl.CULL_FACE); }  else { gl.disable(gl.CULL_FACE); }
			if (prevScissor)   { gl.enable(gl.SCISSOR_TEST); } else { gl.disable(gl.SCISSOR_TEST); }
			gl.depthMask(prevDepthMask);
			gl.colorMask(prevColorMask[0], prevColorMask[1], prevColorMask[2], prevColorMask[3]);
			gl.bindFramebuffer(gl.FRAMEBUFFER, prevFBO);
			gl.viewport(prevViewport[0], prevViewport[1], prevViewport[2], prevViewport[3]);
		}

		console.warn("dwGfxVolumetricFog SENTINEL " + this.depthSentinel);
		return this.depthSentinel;
	}
};

// IEEE-754 half-float (uint16) -> Number. Used only by the depth-readback diagnostic when
// the composite color target reports HALF_FLOAT as its implementation read type.
dwGfxVolumetricFog._halfToFloat = function(h)
{
	const s = (h & 0x8000) >> 15;
	const e = (h & 0x7C00) >> 10;
	const f = h & 0x03FF;
	if (e === 0) { return (s ? -1 : 1) * Math.pow(2, -14) * (f / 1024); }
	if (e === 0x1F) { return f ? NaN : ((s ? -1 : 1) * Infinity); }
	return (s ? -1 : 1) * Math.pow(2, e - 15) * (1 + f / 1024);
};

// Conservative compile-time maximum pocket count. MUST match DW_FOG_MAX_POCKETS in the
// fragment shader. The active count uploaded each frame is clamped to this.
dwGfxVolumetricFog.MAX_POCKETS = 8;

// Fullscreen triangle (no VBO); mirrors the engine's presentVS.
dwGfxVolumetricFog.VS = `#version 300 es
out vec2 v_uv;
void main()
{
	vec2 pos;
	if (gl_VertexID == 0) {
		pos = vec2(-1.0, -1.0);
	} else if (gl_VertexID == 1) {
		pos = vec2( 3.0, -1.0);
	} else {
		pos = vec2(-1.0,  3.0);
	}
	v_uv = pos * 0.5 + 0.5;
	gl_Position = vec4(pos, 0.0, 1.0);
}
`;

dwGfxVolumetricFog.FS = `#version 300 es
precision highp float;
// GLSL ES 3.00 predeclares a default precision ONLY for sampler2D / samplerCube; sampler3D
// has NONE, so an unqualified 'uniform sampler3D' is a COMPILE ERROR. Declare it explicitly
// (this is the Step 4 fix for "shader build failed; fog disabled").
precision highp sampler3D;
// GLSL ES 3.00 predeclares NO default precision for shadow samplers (same rule as sampler3D).
// The Step 5B directional shadow map is read through a sampler2DShadow (hardware depth compare,
// the portable path for a DEPTH_COMPONENT24 shadow map -- a plain sampler2D read of DEPTH24
// returns 0 on ANGLE/D3D/iOS), so it MUST carry an explicit precision or the shader will not
// compile ("ERROR: 'sampler2DShadow' : No precision specified").
precision highp sampler2DShadow;

// Conservative compile-time maximum number of analytic pockets. The JS side caps the
// active count (u_pocketCount) to this; unused array slots are never marched.
#define DW_FOG_MAX_POCKETS 8

in vec2 v_uv;

uniform sampler2D u_depthTexture; // scene depth (window-space depth, [0,1])
uniform mat4  u_invProj;          // inverse(projection), built with m4 (view-space ray + distance)
uniform mat4  u_invView;          // camera world matrix = inverse(view); rotates view dirs to world
uniform vec3  u_cameraPos;        // camera world position
uniform float u_density;          // constant fog density
uniform vec3  u_fogColor;         // fog color (composited over the HDR scene)
uniform float u_maxDistance;      // fog fully saturates / clamps by this distance
uniform int   u_steps;            // ray-march sample count
uniform int   u_debugMode;        // 0 normal, 1 distance, 2 fog factor, 3 pocket coverage, 4 raw depth,
                                  // 5 scatter color (opaque), 6 shadow visibility / visRatio (opaque),
                                  // 7 shadow-frustum coverage, 8 projected reference depth,
                                  // 9 march cost (steps used / occupied fraction / early exit)

// ---- Layer 2: authored weather-map coverage ----
uniform sampler2D u_weatherMap;        // authored coverage, sampled in world XZ (.r)
uniform int   u_useWeatherMap;         // 0 constant fog (map not ready), 1 map-driven
uniform float u_mapWorldSize;          // world units one full map tile spans
uniform vec2  u_worldOffset;           // world XZ offset added before centering
uniform float u_coverageThreshold;     // map values below this => clear
uniform float u_edgeSoftness;          // smoothstep width above the threshold
uniform float u_mapInfluence;          // 0 ignore map .. 1 map fully gates fog

// ---- analytic world-space fog pockets (1..DW_FOG_MAX_POCKETS finite ellipsoids) ----
uniform int   u_fogMode;               // 0 weather-map, 1 analytic ellipsoid pockets
uniform int   u_ignoreSceneDepth;      // DIAGNOSTIC: 1 = analytic pockets ignore scene depth
uniform int   u_pocketCount;           // active pockets (0..DW_FOG_MAX_POCKETS)
uniform int   u_pocketSteps;           // per-pocket march budget (mobile-capped in JS)
uniform vec3  u_pocketCenters[DW_FOG_MAX_POCKETS]; // per-pocket center in world space
uniform vec3  u_pocketRadii[DW_FOG_MAX_POCKETS];   // per-pocket ellipsoid radii (world units)
uniform float u_pocketFeathers[DW_FOG_MAX_POCKETS];// per-pocket feather (fraction of radius)
uniform float u_pocketDensity[DW_FOG_MAX_POCKETS]; // per-pocket density scale (multiplies u_density)

// ---- Step 4: internal 3D density variation + analytic-edge erosion ----
uniform sampler3D u_noiseVolume;   // deterministic tileable value/fractal noise (.r, R8, REPEAT)
uniform int   u_noiseEnabled;      // 0 => exact pre-noise path (A/B toggle), 1 => modulate
uniform float u_noiseScale;        // world^-1 spatial frequency (larger => finer detail)
uniform float u_noiseStrength;     // density +/- fraction: masses/gaps amplitude (0..1)
uniform float u_noiseContrast;     // >1 sharpens masses vs gaps (contrast about 0.5)
uniform float u_edgeErosion;       // 0..1 break-up of the analytic pocket boundary band
uniform vec3  u_noisePhase;        // windVelocity * time, wrapped to [0,1) (world-space drift)
uniform float u_shapeWarp;         // boundary displacement of the analytic silhouette, in
                                   // normalized-distance units (fraction of pocket radius); 0 => round

// ---- Step 5A: moon in-scattering (no shadows). This is an RGB-ONLY term; the fog alpha is
// computed solely from 'optical' and is NEVER touched here, so u_moonEnabled==0 OR
// u_moonIntensity==0 (with u_moonAmbient==0) reproduces the current fog path byte-for-byte. ----
uniform int   u_moonEnabled;     // 0 => exact prior color path, 1 => add silver-blue scatter
uniform vec3  u_moonDir;         // WORLD-space direction fog->moon (normalized on the JS side)
uniform vec3  u_moonColor;       // scatter tint (silver-blue for a moonlit forest)
uniform float u_moonIntensity;   // directional scatter strength (0 => no directional term)
uniform float u_moonAnisotropy;  // HG g, clamped [-0.9,0.9]; >0 forward halo toward the moon
uniform float u_moonAmbient;     // flat, view-independent lift so shadowed fog is not pure fogColor

// ---- Step 5B: directional shadow-map visibility for the scatter term. Step 5A still works
// exactly when this is disabled (visRatio collapses to 1.0 == fully lit). The shadow map is the
// ENGINE's authoritative directional depth texture (dwGfx.getShadowDepthTexture()), read via
// hardware depth compare (sampler2DShadow) -- the portable path for a DEPTH_COMPONENT24 map. ----
uniform int   u_shadowEnabled;   // 0 => scatter is fully lit (no shadow sampling at all)
uniform sampler2DShadow u_shadowMap; // authoritative directional shadow depth (DEPTH24, compare)
uniform mat4  u_shadowMatrix;    // world -> light clip -> [0,1] uv+depth (bias folded in, m4)
uniform float u_shadowBias;      // depth bias to suppress acne (subtracted from the ref depth)
uniform int   u_shadowStride;    // tap the shadow map every Nth march step (>=1). 1 == reference.
                                 // >1 does NOT sample-and-hold: skipped samples are resolved by
                                 // linear interpolation between the two bracketing taps (see below).
uniform float u_shadowTexel;     // 1.0 / shadowMapSize -- REAL texel size, for the PCF offsets
uniform int   u_shadowPCF;       // 1 => 3x3 PCF (default, quality); 0 => single tap (diagnostic)
uniform float u_shadowSoftness;  // PCF radius in texels (1.0 == adjacent texels)
uniform float u_shadowJitter;    // 0..1 scale on the per-pixel shadow-tap jitter (0 == A/B off)

// ---- Step 6: analytic-march cost controls (quality-safe defaults; see the JS constructor) ----
uniform float u_earlyExitT;      // stop the front-to-back march below this transmittance; 0 = never
uniform float u_stepWorldLength; // >0 => target world-space step length; may only REDUCE the budget

out vec4 fragColor;

#define DW_FOG_MAX_STEPS 128

// Upper clamp on the Henyey-Greenstein phase used by the moon in-scatter term. At the default
// anisotropy g=0.55 the forward lobe peaks near (1-g^2)/(1-g)^3 ~= 7.6, which on its own drives the
// directional term far past the bloom threshold and washes the frame white. Clamping the phase (not
// the final color) keeps a pronounced-but-bounded forward glow while staying LDR / silver-blue.
#define DW_FOG_MAX_PHASE 3.0

// Conventional (non-reversed-Z) depth clears to 1.0 at the far plane. A sample at or above
// (1.0 - DW_FOG_DEPTH_CLEAR_EPS) is the cleared background / sky -- NO scene occluder -- and
// must NOT be unprojected (its homogeneous w -> 0 there, producing zero/NaN/precision
// failure). Only depth STRICTLY below this threshold is real geometry. The runtime 't' trace
// showed afterClear v=1.000, confirming the conventional convention is active here.
#define DW_FOG_DEPTH_CLEAR_EPS 1.0e-4

// ONE 3D texture fetch per march sample (first pass: no second octave, no domain warp).
// Sampled in STABLE WORLD SPACE (wpos), so the pattern is locked to the world and does not
// swim with the camera; it drifts only by the world-space wind phase. The SAME single fetch
// drives THREE effects from one value: (1) boundary displacement of the analytic pocket
// silhouette (dwFogWarp, applied to the normalized distance BEFORE the feather), (2) internal
// density variation, and (3) edge erosion of the mask band (dwFogModulate). It is split into a
// fetch + two consumers so the fetched value can perturb the distance before mask/feather are
// evaluated -- using NO extra lookup, octave, channel, or domain-warp sample.

// The single fetch. Returns the contrast-shaped noise in [0,1]. When noise is DISABLED it
// returns the neutral 0.5 WITHOUT sampling, so warp == 0, density x1, and erosion == 0 =>
// exact pre-noise path.
float dwFogNoise(vec3 wpos)
{
	if (u_noiseEnabled == 0) { return 0.5; }
	vec3 uvw = wpos * u_noiseScale + u_noisePhase;         // REPEAT wrap => seamless tiling
	float n  = texture(u_noiseVolume, uvw).r;              // [0,1], LINEAR  (the ONLY fetch)
	return clamp((n - 0.5) * u_noiseContrast + 0.5, 0.0, 1.0);
}

// Displace the normalized pocket distance BEFORE the feather, turning the perfect ellipsoid
// into broad irregular lobes / dents / protrusions. Dense noise (nc>0.5) pushes the boundary
// OUT (nd smaller => protrusion); thin noise pulls it IN (dent). The low-frequency world-space
// noise keeps lobes broad (no sparkling specks); the shift is bounded to +/-0.5*shapeWarp of
// the radius, and it cannot disconnect the core because the feather smoothstep is already fully
// saturated (mask==1) for deep-core samples. shapeWarp==0 OR disabled (nc==0.5) => nd unchanged
// => the exact prior analytic silhouette.
float dwFogWarp(float nd, float nc)
{
	return nd + (0.5 - nc) * u_shapeWarp;
}

// Internal density variation + boundary-band erosion, consuming the SAME fetched nc. Erodes
// only the transition band (4*mask*(1-mask), which is 0 at solid core and empty air) so cores
// stay dense and no fog leaks outside. The density multiplier is centered on 1.0
// ([1-strength, 1+strength], mean ~1 so pockets stay readable). Disabled => density x1 and mask
// untouched (exact prior path).
float dwFogModulate(float nc, inout float mask)
{
	if (u_noiseEnabled == 0) { return 1.0; }
	float band = 4.0 * mask * (1.0 - mask);
	mask = clamp(mask - u_edgeErosion * (1.0 - nc) * band, 0.0, 1.0);
	return 1.0 + u_noiseStrength * (nc * 2.0 - 1.0);
}

// ---- Step 5A: Henyey-Greenstein phase function -------------------------------------------------
// Normalized so the isotropic case (g==0) returns exactly 1.0 (the 1/4pi constant is folded into
// u_moonIntensity for tuning freedom). g is clamped to [-0.9,0.9] by the caller; the denominator is
// floored at 1e-4 so a grazing forward angle with |g|->1 can never divide by zero (no NaN/Inf).
float dwHGPhase(float cosT, float g)
{
	float g2    = g * g;
	float denom = 1.0 + g2 - 2.0 * g * cosT;
	denom       = max(denom, 1e-4);
	return (1.0 - g2) / (denom * sqrt(denom));
}

// ---- Step 5B: directional shadow-map visibility -----------------------------------------------
// Returns 1.0 (fully lit) whenever the world sample cannot be validly tested -- behind the light
// (w<=0), outside the [0,1] shadow frustum in x/y, or beyond the far depth -- so a missing or
// partial shadow map NEVER darkens the fog (fail-open). Inside the frustum it does a hardware depth
// compare through the sampler2DShadow (portable for the DEPTH24 map): 1.0 lit, 0.0 shadowed. The
// bias is subtracted from the reference depth to suppress self-shadow acne. Only called when
// u_shadowEnabled==1 (and only for non-negligible density), so the unshadowed path pays nothing.
// Extended variant: also reports whether the sample fell INSIDE the shadow frustum
// (inside=1.0) and, if so, the projected reference depth in [0,1] (refZ) it compared against.
// These two outs drive debug modes 7 (frustum coverage) and 8 (projected reference depth) so
// a solid-white mode 6 can be diagnosed: no coverage in mode 7 == fail-open because samples are
// outside the frustum; coverage in mode 7 but white mode 6 == samples ARE tested yet nothing
// occludes (depth range / compare state / occluder problem, not a frustum-coverage problem).
// One depth compare that is fail-open OUTSIDE the map. Offsets are applied in UV space and a tap
// that lands outside [0,1] returns 1.0 (lit) instead of being clamped: clamping would smear the
// border texel along the whole frustum edge, which is exactly what draws a hard rectangle.
float dwShadowTap(vec2 uv, float ref)
{
	// positive-logic bounds so a NaN uv (every comparison false) fails OPEN rather than falling
	// through into an undefined compare.
	if (!(uv.x >= 0.0 && uv.x <= 1.0 && uv.y >= 0.0 && uv.y <= 1.0)) { return 1.0; }
	return textureLod(u_shadowMap, vec3(uv, ref), 0.0);
}

float dwShadowVisEx(vec3 wpos, out float inside, out float refZ)
{
	inside = 0.0;
	refZ   = 0.0;
	vec4 sc = u_shadowMatrix * vec4(wpos, 1.0);
	// Positive-logic guard: NaN/Inf w (degenerate matrix, huge wpos) makes every comparison false,
	// so !(...) is true and we fail open. A plain "sc.w <= 0.0" would let NaN slip to the divide.
	if (!(sc.w > 0.0)) { return 1.0; }                // behind the light plane, or non-finite
	vec3 p = sc.xyz / sc.w;                           // -> [0,1] uv + depth (bias matrix folded in)
	// Fail-open outside the [0,1] frustum in x/y AND in z on BOTH ends: p.z<0 (in front of the
	// light near plane) is as invalid a compare as p.z>1 (past the far plane). Written as the
	// negation of an all-inside test so a NaN component also fails open (NaN>=0 is false).
	if (!(p.x >= 0.0 && p.x <= 1.0 && p.y >= 0.0 && p.y <= 1.0 && p.z >= 0.0 && p.z <= 1.0)) { return 1.0; }
	inside = 1.0;
	refZ   = p.z;
	float ref = clamp(p.z - u_shadowBias, 0.0, 1.0);

	// ---- filtered visibility ----------------------------------------------------------------
	// The engine shadow map is DEPTH24 with NEAREST/NEAREST filtering, so ONE sampler2DShadow
	// compare is strictly binary (0.0 or 1.0) -- that hard step is what staircases the shaft
	// silhouette along shadow-map texels. A 3x3 box of compares at the REAL texel size gives 10
	// discrete levels and a texel-wide soft edge without touching the shared texture's filter
	// state (the PBR floor shadow samples the same texture and must not change).
	float vis;
	if (u_shadowPCF == 1) {
		float r = u_shadowTexel * max(u_shadowSoftness, 0.0);
		vis = 0.0;
		for (int oy = -1; oy <= 1; oy++) {
			for (int ox = -1; ox <= 1; ox++) {
				vis += dwShadowTap(p.xy + vec2(float(ox), float(oy)) * r, ref);
			}
		}
		vis *= (1.0 / 9.0);
	} else {
		vis = dwShadowTap(p.xy, ref);   // single-tap diagnostic / lowest cost
	}

	// ---- frustum-border feather --------------------------------------------------------------
	// Fail-open is the right physics (an untestable sample must not darken the fog), but a STEP
	// from "tested, shadowed" to "untested, lit" at the frustum wall paints the light frustum's
	// silhouette into the fog as a hard rectangle/trapezoid. Ramp visibility back to 1.0 across a
	// few texels of the u/v border and the tail of the depth range, so the shadowed region ends by
	// fading out instead of by a straight edge. This only ever makes the fog LIGHTER (never darker),
	// so it cannot invent shadow where the map has none.
	float fadeUV = max(u_shadowTexel * 4.0, 1e-4);
	vec2  dUV    = min(p.xy, 1.0 - p.xy);            // distance to the nearest u/v wall
	float edge   = min(smoothstep(0.0, fadeUV, dUV.x), smoothstep(0.0, fadeUV, dUV.y));
	edge         = min(edge, smoothstep(0.0, 0.02, 1.0 - p.z));   // fade out at the far plane
	return mix(1.0, vis, clamp(edge, 0.0, 1.0));
}
float dwShadowVis(vec3 wpos)
{
	float inside; float refZ;
	return dwShadowVisEx(wpos, inside, refZ);
}

// Per-pixel shadow-tap offset in [-0.5, 0.5] * u_shadowJitter, as a fraction of one march step.
// Interleaved-gradient noise: a good blue-noise-like screen distribution from two cheap fracts,
// and a function of gl_FragCoord ONLY -- no time term, so it is perfectly stable frame to frame
// (no sparkle/crawl) while still decorrelating neighbouring pixels' march phase.
//
// It is applied ONLY to the position of the shadow lookup, never to the density/noise sample.
// That is deliberate: it breaks up the coherent shadow-tap shells that read as horizontal slabs,
// while the fog's pocket/noise integral stays bit-for-bit what it is today.
float dwShadowJitterFrac()
{
	if (u_shadowJitter <= 0.0) { return 0.0; }
	float ign = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))));
	return (ign - 0.5) * clamp(u_shadowJitter, 0.0, 1.0);
}

void main()
{
	float depth = texture(u_depthTexture, v_uv).r; // [0,1] window-space depth

	// Debug Mode 4 (rawDepth): the exact scalar sampled from the SAME production depth
	// sampler (u_depthTexture, bound on unit 0), shown as opaque grayscale BEFORE any NDC
	// conversion, world reconstruction, fog intersection, or ignoreSceneDepth logic. This
	// is the ground-truth probe and is independent of u_fogMode and u_ignoreSceneDepth.
	// Expect clear/background ~1.0 (white) and nearer geometry <1.0 (darker silhouette).
	// All black => raw depth is not reaching the fog pass (attachment/clear/write), which
	// is upstream of every reconstruction/fog decision below.
	if (u_debugMode == 4) {
		fragColor = vec4(vec3(depth), 1.0);
		return;
	}

	// ---- world ray DIRECTION (robust, view-space derivation) ----
	// Derive the pixel ray in VIEW space (camera at the origin), then rotate it into world
	// space with the camera's world matrix (w = 0 => rotation only, no translation).
	// The previous path reconstructed the enormous FAR-plane world endpoint
	// (inverse(proj*view) * ndc with ndc.z = 1, whose homogeneous w -> 0 there so the point
	// magnitude -> ~far) and then subtracted u_cameraPos: a divide by a near-zero w followed
	// by catastrophic cancellation of two large coordinates. The tiny angular error that
	// produced was negligible for near samples but, multiplied by a long march distance t,
	// swung distant samples far enough to MISS the ray-ellipsoid test entirely -- so distant
	// pockets vanished while touched/near ones looked fine. Reconstructing at the NEAR plane
	// (ndc.z = -1) keeps w well away from zero and the view point O(near); no world endpoint
	// and no camera subtraction. Mathematically the same direction, numerically well-conditioned.
	vec2 ndcXY  = v_uv * 2.0 - 1.0;
	vec4 vNearH = u_invProj * vec4(ndcXY, -1.0, 1.0); // near-plane point in view space
	vec3 viewDir = vNearH.xyz / vNearH.w;             // camera at view origin => this is a direction
	vec3 rayDir = normalize((u_invView * vec4(viewDir, 0.0)).xyz);

	// ---- march DISTANCE from the SAME raw depth, reconstructed in VIEW space ----
	// The previous derivation took length(world - u_cameraPos): a difference of two large
	// world coordinates whose homogeneous w -> 0 as depth -> 1, which is numerically
	// fragile (worst on mobile fp) and could collapse the distance to ~0. Instead invert
	// ONLY the projection: in view space the camera is the origin, so the Euclidean length
	// of the reconstructed view position IS the world distance along the ray (a rigid
	// view transform preserves lengths). No camera subtraction, well-conditioned matrix.
	float marchDist;
	if (depth >= 1.0 - DW_FOG_DEPTH_CLEAR_EPS) {
		// Background / far plane (no geometry occluder): set the march limit DIRECTLY to the
		// configured maximum. Critically, we do NOT unproject depth==1.0 -- that far-plane
		// point has homogeneous w -> 0, so length(view.xyz / w) is zero/NaN/precision-blown
		// and would collapse the ray, hiding distant fog behind an invisible near clip. The
		// sky therefore fogs to u_maxDistance exactly like the ignoreSceneDepth path, so an
		// OUTSIDE/distant camera looking at a pocket against the sky marches the full chord.
		marchDist = u_maxDistance;
	} else {
		// Real geometry (strictly nearer than the clear plane): unproject to a finite VIEW-
		// space distance. In view space the camera is the origin, so the length of the
		// reconstructed position IS the world distance along the ray (rigid transform).
		vec4 ndcP  = vec4(v_uv * 2.0 - 1.0, depth * 2.0 - 1.0, 1.0);
		vec4 viewH = u_invProj * ndcP;
		float vw   = viewH.w;
		if (abs(vw) < 1e-6) {
			marchDist = u_maxDistance;                 // degenerate w -> treat as far, never 0
		} else {
			float d = length(viewH.xyz / vw);
			// Clamp to a finite, positive geometry distance; any non-finite / non-positive
			// result falls back to the far distance so a single bad sample can never silently
			// zero the segment (which would drop the fog) for the whole frame.
			marchDist = (d > 0.0 && d < 1.0e30) ? min(d, u_maxDistance) : u_maxDistance;
		}
	}

	int steps = u_steps;
	if (steps < 1) { steps = 1; }
	float softness = max(u_edgeSoftness, 1e-4);

	float optical = 0.0;
	float maxMask = 0.0; // strongest coverage the ray crossed (debug mode 3)

	// Step 5A/5B in-scattering accumulators. These NEVER contribute to 'optical' (the fog alpha),
	// so the moon layer is purely additive to RGB: with u_moonEnabled==0 they stay 0 and the alpha
	// is byte-for-byte the prior path. Rather than a ray-AVERAGED scalar visibility (which can only
	// brighten/darken the whole ray uniformly and never carves shafts), each sample's in-scatter is
	// composited front-to-back weighted by the transmittance T = exp(-optical) accumulated UP TO
	// that sample. scatterAll is the total (fully-lit) in-scatter integral; scatterVis is the same
	// integral gated by the per-sample shadow visibility. Both are bounded above by the fog opacity
	// (integral of T*sigma*dt == 1 - exp(-optical) <= 1), so the moon term is inherently LDR-scaled
	// by coverage instead of the unbounded mean of the old path. visRatio = scatterVis/scatterAll is
	// the transmittance-weighted mean visibility (debug mode 6); shafts appear because occluded
	// samples drop out of scatterVis while their neighbours stay lit.
	float scatterAll = 0.0; // fully-lit in-scatter integral (transmittance-weighted)
	float scatterVis = 0.0; // shadow-gated in-scatter integral (transmittance-weighted)
	int   sStride    = (u_shadowStride < 1) ? 1 : u_shadowStride; // tap shadow every Nth step
	// De-banded striding. The old code held one tap's visibility across the whole stride window
	// (sample-and-hold), which quantizes visibility into constant-visibility slabs along the ray --
	// the hard horizontal bands. Instead, a skipped sample's weight is SPLIT between the tap before
	// it and the tap after it in proportion to its position, which is algebraically identical to
	// linearly interpolating its visibility between the two bracketing taps:
	//     sum w_k * mix(visA, visB, a_k) == visA * sum w_k(1-a_k) + visB * sum w_k a_k
	// so two running scalars are enough -- no arrays, no lookahead, and the sample's weight w (and
	// therefore the front-to-back transmittance ordering) is still computed at its own position.
	float prevVis    = 1.0; // visibility at the most recent tap
	float pendW0     = 0.0; // pending weight attributed to the PREVIOUS tap
	float pendW1     = 0.0; // pending weight attributed to the NEXT tap
	float sJit       = dwShadowJitterFrac(); // per-pixel shadow-tap offset, in march-step fractions
	// Diagnostics (accumulated ONLY when u_debugMode != 0 -- a uniform branch, so normal rendering
	// pays nothing on mobile). insideAccum = transmittance-weighted in-scatter that fell inside the
	// shadow frustum; refAccum = its projected reference-depth, weighted the same. Modes 7/8 read them.
	float lastInside = 0.0; // frustum-membership of the last strided shadow tap (1 inside, 0 outside)
	float lastRef    = 0.0; // projected [0,1] reference depth of the last strided shadow tap
	float insideAccum = 0.0;
	float refAccum    = 0.0;
	// Step 6 march diagnostics. Also written ONLY under u_debugMode != 0 (a uniform branch), so
	// production rendering pays nothing. dbgSamples = samples actually marched; dbgOcc /
	// dbgSkip = occupied vs skipped world length of the analytic interval union; dbgEarlyExit =
	// whether this ray terminated on the transmittance threshold. Debug mode 9 reads them.
	float dbgSamples   = 0.0;
	float dbgOcc       = 0.0;
	float dbgSkip      = 0.0;
	float dbgEarlyExit = 0.0;

	if (u_fogMode == 1) {
		// Analytic ellipsoid pockets. Instead of marching the whole ray (which, with a
		// coarse fixed step, steps straight over a thin ground-hugging pocket and leaves
		// it invisible from a distance), each finite pocket is intersected with the view
		// ray and ONLY the [t0,t1] chord the ray spends inside it is marched. Every sample
		// lands within a pocket, so distant/scattered pockets resolve densely and composite
		// correctly whether the camera is OUTSIDE looking at them or already within one.
		//
		// Diagnostic ray setup, shared by every pocket. Direction is ALWAYS the far-plane
		// world ray (rayDir, computed above) -- the exact path proven to work with
		// ignoreSceneDepth:true. Only the available march distance differs: default
		// (u_ignoreSceneDepth == 0) clips at the reconstructed scene distance marchDist so
		// foreground geometry occludes the pocket; when enabled, ignore reconstructed scene
		// depth and use the full ray length (u_maxDistance) so the ray always reaches the
		// ellipsoids (fog then draws through geometry -- diagnostic only). The finite
		// density masks are unchanged either way (fog is still 0 outside every pocket).
		vec3  aDir      = rayDir;
		float availDist = (u_ignoreSceneDepth == 1) ? u_maxDistance : marchDist;

		// PASS 1 -- interval build. One cheap ray-ellipsoid test per pocket. The clipped
		// chord [t0,t1] of every pocket actually hit is cached, and a single union hull
		// [hullStart,hullEnd] is grown to span them all. Missed/degenerate pockets leave an
		// empty interval (t1 < t0) and cost only a handful of ALU ops (no march, no texture).
		// Accepted chords are ALSO inserted into sT0/sT1 in ascending-t0 order (insertion sort
		// over at most DW_FOG_MAX_POCKETS scalars, no texture work) so PASS 1.5 can merge them
		// into the exact union of occupied intervals in one linear sweep.
		float pT0[DW_FOG_MAX_POCKETS];
		float pT1[DW_FOG_MAX_POCKETS];
		float sT0[DW_FOG_MAX_POCKETS];
		float sT1[DW_FOG_MAX_POCKETS];
		float hullStart =  1e30;
		float hullEnd   = -1e30;
		int   activeCount = 0;
		for (int pi = 0; pi < DW_FOG_MAX_POCKETS; pi++) {
			pT0[pi] = 0.0;
			pT1[pi] = -1.0; // empty interval sentinel (t1 < t0 -> never contains any t)
			sT0[pi] = 0.0;
			sT1[pi] = -1.0;
			if (pi >= u_pocketCount) { continue; }

			vec3  radii  = u_pocketRadii[pi];
			if (!(radii.x > 0.0 && radii.y > 0.0 && radii.z > 0.0)) { continue; } // degenerate

			// Ellipsoid-local unit-sphere quadratic, solved in the pocket-LOCAL, camera-relative
			// frame. ocp is the camera expressed relative to the pocket center (small, well-
			// conditioned) so no absolute world sample position (u_cameraPos + aDir*t, magnitude
			// ~t) is ever formed and then differenced against center -- that cancellation of two
			// large coordinates is what lost precision on long rays to distant pockets. d is
			// intentionally NOT normalized, so the quadratic solves for the SAME world-distance
			// parameter t as aDir (consistent with availDist for both inside and outside cameras).
			// The only difference between an outside and inside camera is the sign of tNear
			// (>=0 outside, <0 inside); the integration below is otherwise identical.
			vec3 center = u_pocketCenters[pi];
			vec3 ocp = u_cameraPos - center;
			vec3 o = ocp / radii;
			vec3 d = aDir / radii;
			float a = dot(d, d);
			float b = dot(o, d);
			float c = dot(o, o) - 1.0;
			float disc = b * b - a * c;

			// cheap reject: a genuine miss or degenerate ray contributes nothing.
			if (disc < 0.0 || a <= 0.0) { continue; }
			float sq = sqrt(disc);
			float tNear = (-b - sq) / a;   // entry (negative when camera is inside)
			float tFar  = (-b + sq) / a;   // exit
			if (tFar <= 0.0) { continue; } // pocket wholly behind the camera

			// Unified chord for inside AND outside:
			//   segmentStart = max(tNear, 0)  -> outside: real entry; inside: the camera.
			//   segmentEnd   = min(tFar, availDist) -> clipped by the nearest opaque
			//   surface (or the pocket exit for sky/far pixels where availDist == maxDist).
			float segmentStart = max(tNear, 0.0);
			float segmentEnd   = min(tFar, availDist);
			if (segmentEnd <= segmentStart) { continue; } // no chord in front of the camera

			pT0[pi] = segmentStart;
			pT1[pi] = segmentEnd;
			hullStart = min(hullStart, segmentStart);
			hullEnd   = max(hullEnd,   segmentEnd);

			// Insertion sort by segmentStart into sT0/sT1[0..activeCount]. At the top of this
			// iteration activeCount <= pi, so the slot cleared above (index pi) is always at or
			// past the live tail and the shift below can never write past DW_FOG_MAX_POCKETS-1.
			int ins = activeCount;
			for (int k = DW_FOG_MAX_POCKETS - 1; k >= 0; k--) {
				if (k >= activeCount) { continue; }
				if (sT0[k] > segmentStart) { sT0[k + 1] = sT0[k]; sT1[k + 1] = sT1[k]; ins = k; }
			}
			sT0[ins] = segmentStart;
			sT1[ins] = segmentEnd;
			activeCount++;
		}

		// PASS 1.5 -- exact union of the occupied intervals. One linear sweep over the
		// ascending-t0 list coalesces every overlapping or touching chord, IN PLACE (the write
		// index uCount-1/uCount is always <= the read index k, and sT0[k]/sT1[k] are read before
		// either write, so reusing the arrays is safe). The result is the minimal set of disjoint
		// intervals the ray actually spends inside fog; occLen is their total world length and
		// skipLen is the empty gap length between separated pockets that the march will now step
		// OVER instead of sampling. Overlapping pockets collapse into one interval here, which is
		// exactly the previous behaviour -- per-sample density still SUMS every pocket whose own
		// cached chord (pT0/pT1, untouched by this merge) contains the sample.
		int   uCount = 0;
		float occLen = 0.0;
		for (int k = 0; k < DW_FOG_MAX_POCKETS; k++) {
			if (k >= activeCount) { break; }
			float kt0 = sT0[k];
			float kt1 = sT1[k];
			if (uCount == 0) {
				sT0[0] = kt0; sT1[0] = kt1; uCount = 1;
				continue;
			}
			if (kt0 <= sT1[uCount - 1]) {
				sT1[uCount - 1] = max(sT1[uCount - 1], kt1); // overlaps/touches the open interval
			} else {
				sT0[uCount] = kt0; sT1[uCount] = kt1; uCount++;
			}
		}
		for (int k = 0; k < DW_FOG_MAX_POCKETS; k++) {
			if (k >= uCount) { break; }
			occLen += max(sT1[k] - sT0[k], 0.0);
		}
		float skipLen = (activeCount > 0) ? max((hullEnd - hullStart) - occLen, 0.0) : 0.0;
		if (u_debugMode != 0) { dbgOcc = occLen; dbgSkip = skipLen; }

		// PASS 2 -- one spatially ordered front-to-back march across the OCCUPIED INTERVAL UNION.
		// The step grid is parameterised by arc length s along the union (0..occLen) rather than
		// by t along the hull, so:
		//   * empty gaps between separated pockets are stepped OVER, not sampled. A gap sample
		//     had sigma == 0 exactly, so it added 0 to optical, 0 to scatterAll/scatterVis and
		//     left maxMask untouched -- dropping it removes cost, not signal.
		//   * the SAME step budget now covers occLen instead of hullLen, and occLen <= hullLen,
		//     so the world-space step is equal to or FINER than before. Sampling density per
		//     occupied world length never decreases, and no samples are lost when the intervals
		//     are disjoint (each interval receives its share of the budget by length).
		// Everything else is unchanged: at each sample the density of ALL pockets covering that
		// world point is SUMMED via the per-pocket chords pT0/pT1 (overlaps add, order-independent,
		// identical where intervals overlap), the in-scatter is weighted by the transmittance
		// BEFORE the sample, and optical depth is advanced afterwards.
		if (uCount > 0 && occLen > 0.0) {
			int gSteps = u_pocketSteps;
			if (gSteps < 1) { gSteps = 1; }
			// OPT-IN adaptive budget. Off (u_stepWorldLength == 0) by default; when set it may
			// only LOWER the step count, never raise it, so quality can never regress silently.
			if (u_stepWorldLength > 0.0) {
				int want = int(ceil(occLen / u_stepWorldLength));
				if (want < 1) { want = 1; }
				if (want < gSteps) { gSteps = want; }
			}
			float segLen = occLen / float(gSteps);
			// Monotone cursor mapping arc length -> world t. s increases every iteration, so the
			// cursor only ever advances; the bounded inner loop is a walk, not a search.
			int   ui   = 0;   // index of the union interval currently being marched
			float base = 0.0; // arc length consumed by the intervals BEFORE ui
			for (int i = 0; i < DW_FOG_MAX_STEPS; i++) {
				if (i >= gSteps) { break; }
				float s = (float(i) + 0.5) * segLen;
				for (int k = 0; k < DW_FOG_MAX_POCKETS; k++) {
					if (ui >= uCount - 1) { break; }
					float L = max(sT1[ui] - sT0[ui], 0.0);
					if (s <= base + L) { break; }
					base += L;
					ui++;
				}
				float t = sT0[ui] + (s - base);
				// Stable WORLD-space sample position; the ONE noise fetch is shared by every
				// pocket at this sample (boundary displacement, density multiplier, edge erosion).
				// aT is hoisted out of the pocket loop below, which used to recompute aDir*t once
				// per pocket per sample. Same value, so the density result is bit-identical.
				vec3 aT   = aDir * t;
				vec3 wpos = u_cameraPos + aT;
				float nc  = dwFogNoise(wpos);
				if (u_debugMode != 0) { dbgSamples += 1.0; }

				// Sum every active pocket whose cached chord contains this sample.
				float sigma = 0.0;
				for (int pj = 0; pj < DW_FOG_MAX_POCKETS; pj++) {
					if (pj >= u_pocketCount) { break; }
					if (t < pT0[pj] || t > pT1[pj]) { continue; } // outside this pocket's chord
					vec3  radii = u_pocketRadii[pj];
					// Camera-relative, as before: the absolute world position is deliberately NOT
					// differenced against the center here (that cancellation of two large
					// coordinates is what lost precision on long rays to distant pockets).
					vec3  q = (u_cameraPos - u_pocketCenters[pj] + aT) / radii;
					float nd = length(q);
					float feather = clamp(u_pocketFeathers[pj], 1e-3, 1.0);
					// Displace the silhouette BEFORE the feather (broad lobes/dents/protrusions),
					// then feather the warped distance. shapeWarp==0 / noise off => exact round mask.
					float mask = 1.0 - smoothstep(1.0 - feather, 1.0, dwFogWarp(nd, nc));
					float densFactor = dwFogModulate(nc, mask);
					float dScale = max(u_pocketDensity[pj], 0.0);
					maxMask = max(maxMask, mask);
					sigma += max(u_density * dScale * mask * densFactor, 0.0);
				}

				// Front-to-back: T is the transmittance accumulated BEFORE this sample; weight the
				// in-scatter by it, THEN grow optical depth. Order follows space, not pocket index.
				float T = exp(-optical);
				optical += sigma * segLen;
				// Step 5A/5B: accumulate density-weighted moon visibility (RGB only; leaves optical
				// untouched). Shadow is tapped every sStride steps; the steps BETWEEN taps are not
				// held at a constant visibility -- their weight is split between the two bracketing
				// taps and resolved when the next tap lands, which is algebraically identical to
				// lerping each skipped sample's visibility but needs only two running scalars.
				// Negligible density skips the lookup entirely, so mobile cost stays modest.
				if (u_moonEnabled == 1) {
					// w is this sample's transmittance-weighted in-scatter (front-to-back, spatial
					// order). It is computed HERE, from this sample's own T, and never revised --
					// only the visibility factor applied to it may resolve one tap later.
					float w = T * sigma * segLen;
					scatterAll += w;
					if (u_shadowEnabled == 1 && sigma > 1e-5) {
						int ph = i - (i / sStride) * sStride;   // i % sStride
						if (ph == 0) {
							// tap: jittered along the ray by a fraction of a step (position only).
							float vNew = dwShadowVisEx(wpos + aDir * (sJit * segLen), lastInside, lastRef);
							scatterVis += prevVis * pendW0 + vNew * pendW1;  // resolve the bracketed samples
							pendW0 = 0.0; pendW1 = 0.0;
							prevVis = vNew;
							scatterVis += w * vNew;                          // this sample is exact
						} else {
							float a = float(ph) / float(sStride);            // 0<a<1 toward the NEXT tap
							pendW0 += w * (1.0 - a);
							pendW1 += w * a;
						}
					} else {
						scatterVis += w;   // shadows off / negligible density => fully lit
					}
					if (u_debugMode != 0) { insideAccum += w * lastInside; refAccum += w * lastRef * lastInside; }
				}
				// Safe early-out once the ray is effectively opaque: remaining samples add
				// nothing visible and each one costs a noise + shadow tap on mobile. The
				// threshold is now configurable and DEFAULTS to 0.001 -- exactly the constant
				// this line used to hard-code -- so the default path is unchanged. Setting
				// earlyExitTransmittance to 0 disables the early-out for a reference A/B.
				if (u_earlyExitT > 0.0 && exp(-optical) < u_earlyExitT) {
					if (u_debugMode != 0) { dbgEarlyExit = 1.0; }
					break;
				}
			}
		}
	} else {
		// weather-map / constant fog: per-sample march along the whole ray. Coverage is
		// evaluated at EVERY sample's world XZ, so a ray accumulates fog only while inside
		// a covered pocket and returns to clear air on the far side.
		float stepLen = marchDist / float(steps);
		for (int i = 0; i < DW_FOG_MAX_STEPS; i++) {
			if (i >= steps) { break; }
			float t = (float(i) + 0.5) * stepLen;          // sample at the segment midpoint
			vec3 samplePos = u_cameraPos + rayDir * t;

			// densityScale defaults to 1 (constant fog) so the map-not-ready path and the
			// mapInfluence=0 path both reproduce Layer 1 exactly.
			float densityScale = 1.0;
			if (u_useWeatherMap == 1) {
				// world origin -> UV (0.5, 0.5). Outside the map's [0,1] world footprint is
				// clear air: explicit bounds so the centered diagnostic pocket never tiles or
				// smears beyond its footprint (wrap is CLAMP_TO_EDGE as a second guard).
				vec2 wuv = (samplePos.xz + u_worldOffset) / u_mapWorldSize + 0.5;
				float mask = 0.0;
				if (all(greaterThanEqual(wuv, vec2(0.0))) && all(lessThanEqual(wuv, vec2(1.0)))) {
					float coverage = textureLod(u_weatherMap, wuv, 0.0).r;
					mask = smoothstep(u_coverageThreshold, u_coverageThreshold + softness, coverage);
				}
				densityScale = mix(1.0, mask, clamp(u_mapInfluence, 0.0, 1.0));
				maxMask = max(maxMask, mask);
			}
			// Same single world-space fetch modulates the weather/constant density too (and
			// erodes its coverage band); disabled -> densFactor 1, densityScale untouched.
			// (Boundary displacement is analytic-only: it warps the ellipsoid's normalized
			// distance, which the map-driven weather coverage does not have.)
			float nc = dwFogNoise(samplePos);
			float densFactor = dwFogModulate(nc, densityScale);
			// with mapInfluence=1, densityScale==mask, so clear samples (mask 0) contribute
			// no optical depth: the ray only thickens while inside a pocket.
			float sigma = max(u_density * densityScale * densFactor, 0.0);
			optical += sigma * stepLen;
			// Step 5A/5B in-scattering (RGB only; optical untouched) -- same discipline as the
			// analytic branch: strided, density-gated shadow sampling reused between taps.
			if (u_moonEnabled == 1) {
				float w = exp(-optical) * sigma * stepLen; // transmittance-weighted (front-to-back)
				scatterAll += w;
				if (u_shadowEnabled == 1 && sigma > 1e-5) {
					int ph = i - (i / sStride) * sStride;   // i % sStride
					if (ph == 0) {
						float vNew = dwShadowVisEx(samplePos + rayDir * (sJit * stepLen), lastInside, lastRef);
						scatterVis += prevVis * pendW0 + vNew * pendW1;   // resolve the bracketed samples
						pendW0 = 0.0; pendW1 = 0.0;
						prevVis = vNew;
						scatterVis += w * vNew;                          // this sample is exact
					} else {
						float a = float(ph) / float(sStride);
						pendW0 += w * (1.0 - a);
						pendW1 += w * a;
					}
				} else {
					scatterVis += w;   // shadows off / negligible density => fully lit
				}
				if (u_debugMode != 0) { insideAccum += w * lastInside; refAccum += w * lastRef * lastInside; }
			}
		}
	}
	// Flush any samples still waiting for their NEXT tap. This only happens with stride>1, only for
	// the up-to-(stride-1) samples that trail the final tap, and it is the one place a held value is
	// unavoidable (there is no later tap to interpolate toward). Those samples sit at the far end of
	// the ray where the accumulated transmittance is lowest, so their weight is the smallest of the
	// march. With the default stride 1 both accumulators are always 0 and this line is a no-op.
	scatterVis += (pendW0 + pendW1) * prevVis;

	float transmittance = exp(-optical);
	float fog = clamp(1.0 - transmittance, 0.0, 1.0);

	// Step 5A/5B: build the moon-scattered fog color from the transmittance-weighted in-scatter
	// integrals. scatterAmt is the composited in-scatter that actually reaches the eye: gated by the
	// shadow map when shadows are on (scatterVis), fully lit otherwise (scatterAll). Because both are
	// integrals of T*sigma*dt they are bounded above by the fog opacity (<=1), so the moon term is
	// coverage-scaled and cannot wash the frame the way the old ray-averaged mean could. visRatio is
	// the transmittance-weighted mean visibility (1.0 == fully lit; debug mode 6). The HG phase is
	// CLAMPED so the forward lobe (g=0.55 peaks ~7.6, enough to blow past bloom on its own) can no
	// longer over-drive the directional term into a white bloom. When the moon is disabled the color
	// is exactly u_fogColor (the prior path) and the alpha 'fog' above is unaffected in every case.
	// visRatio is the transmittance-weighted, per-sample-composited shadow visibility:
	// scatterVis (shadow-gated in-scatter integral) over scatterAll (fully-lit integral). It is the
	// physically-correct normaliser for the forced alpha composite below: the final output is
	// fogRGB*fog (straight-alpha "over"), and scatterAll == the in-scatter integral ~= fog, so
	// (moonColor*intensity*phase*visRatio)*fog == moonColor*intensity*phase*scatterVis == the true
	// composited in-scatter that reaches the eye. Each occluded sample drops out of scatterVis but
	// not scatterAll, so pixels whose rays graze the occluder darken relative to their neighbours ->
	// shafts, not a uniform wash. When shadows are OFF scatterVis==scatterAll => visRatio==1.0 and
	// this collapses byte-for-byte to the prior Step 5A term (fully-lit moon glow).
	float visRatio = (scatterAll > 1e-6) ? (scatterVis / scatterAll) : 1.0;
	vec3 fogRGB = u_fogColor;
	if (u_moonEnabled == 1) {
		float cosT  = dot(rayDir, u_moonDir); // both normalized; >0 means looking toward the moon
		float g     = clamp(u_moonAnisotropy, -0.9, 0.9);
		// Clamp the HG forward lobe (g=0.55 peaks ~7.6 -- enough to bloom to white on its own) so the
		// directional term stays LDR and silver-blue instead of clipping. visRatio (<=1) and the
		// downstream *fog composite keep it coverage-scaled.
		float phase = min(dwHGPhase(cosT, g), DW_FOG_MAX_PHASE);
		vec3  direct  = u_moonColor * (max(u_moonIntensity, 0.0) * phase) * visRatio;
		vec3  ambient = u_moonColor * max(u_moonAmbient, 0.0);
		fogRGB = u_fogColor + direct + ambient;
	}

	if (u_debugMode == 5) {
		// scattered fog color, shown opaque (isolates the Step 5A/5B RGB term from coverage/alpha).
		fragColor = vec4(fogRGB, 1.0);
		return;
	}
	if (u_debugMode == 6) {
		// transmittance-weighted per-sample shadow visibility (visRatio) as opaque grayscale:
		// white == fully lit fog, dark == the in-scatter along this ray was shadowed. Distinct
		// grey/black patches here (with shadows ON) confirm the shadow map is occluding samples;
		// with shadows disabled this is uniformly white (visRatio==1). Where the ray never enters
		// fog (scatterAll==0) it also reads white -- the moon term contributes nothing there anyway.
		fragColor = vec4(vec3(visRatio), 1.0);
		return;
	}
	if (u_debugMode == 7) {
		// Shadow-frustum COVERAGE: transmittance-weighted fraction of this ray's in-scatter that
		// landed INSIDE the [0,1] light frustum (green). Read together with mode 6 to localise a
		// solid-white shadow result: BLACK here (with shadows on) == the fog volume is entirely
		// OUTSIDE the shadow frustum, so every sample fails open to lit (visRatio==1, mode 6 white)
		// -- widen/re-aim the light ortho. GREEN here but WHITE in mode 6 == samples ARE tested but
		// nothing occludes them (depth-range/compare-state/occluder issue, checked with mode 8).
		float cover = (scatterAll > 1e-6) ? (insideAccum / scatterAll) : 0.0;
		fragColor = vec4(0.0, cover, 0.0, 1.0);
		return;
	}
	if (u_debugMode == 8) {
		// Projected REFERENCE DEPTH: transmittance-weighted mean of the [0,1] depth the inside-frustum
		// samples compared against the shadow map (blue). A healthy shadow frustum shows a smooth
		// mid-range gradient; all-black (~0) or all-white (~1) means the light near/far range does not
		// straddle the scene (compresses every ref to one end -> the compare can never resolve an
		// occluder). Black where the ray missed the frustum entirely (no inside samples).
		float refMean = (insideAccum > 1e-6) ? (refAccum / insideAccum) : 0.0;
		fragColor = vec4(0.0, 0.0, refMean, 1.0);
		return;
	}

	if (u_debugMode == 9) {
		// Step 6 MARCH COST (analytic mode). R = samples actually marched / the step budget, so a
		// bright red pixel used its whole budget and a dim one exited early or found a short chord.
		// G = occupied fraction of the union hull (occLen / (occLen+skipLen)): 1.0 means the hull is
		// solid fog, and anything below 1.0 is gap length the march now steps OVER -- so DARK green
		// is where interval skipping pays. B = 1 where the ray terminated on the transmittance
		// threshold. Black everywhere the ray never entered a pocket (no march at all).
		float budget = float(max(u_pocketSteps, 1));
		float used   = clamp(dbgSamples / budget, 0.0, 1.0);
		float hullAll = dbgOcc + dbgSkip;
		float occFrac = (hullAll > 1e-6) ? clamp(dbgOcc / hullAll, 0.0, 1.0) : 0.0;
		fragColor = vec4(used, occFrac, dbgEarlyExit, 1.0);
		return;
	}

	if (u_debugMode == 1) {
		float d = clamp(marchDist / u_maxDistance, 0.0, 1.0);
		fragColor = vec4(vec3(d), 1.0);
		return;
	}
	if (u_debugMode == 2) {
		fragColor = vec4(vec3(fog), 1.0);
		return;
	}
	if (u_debugMode == 3) {
		// pocket coverage encountered ALONG the ray (analytic ellipsoid mask, or weather
		// mask when in weather mode): green where the ray passed through the fog pocket
		// (strongest mask crossed), black where no pocket was intersected.
		fragColor = vec4(0.0, maxMask, 0.0, 1.0);
		return;
	}

	// premultiplied-free "over": result = fogRGB*fog + scene*(1-fog) via
	// blendFunc(SRC_ALPHA, ONE_MINUS_SRC_ALPHA). fogRGB == u_fogColor exactly when the moon is
	// disabled, so the composite is byte-for-byte the prior path; the alpha 'fog' is never altered.
	fragColor = vec4(fogRGB, fog);
}
`;
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxTransitionalPointField.js
//
// Reusable TRANSITIONAL point field: a cloud of points that begins as wind-blown smoke and CONDENSES
// into the shape of a scene object, then hands the pixels back to that object's normal rendering.
// First use is the centre logo materializing on touch, but nothing in this class knows about logos.
//
// THE BOUND NODE IS AUTHORITATIVE
//   bindNode(node) attaches this effect to a dwGfxNode, and from that moment the NODE -- not the
//   caller, not a matrix argument -- is the source of truth for:
//     - TRANSFORM:   node.getWorldMatrix() is the field's model matrix every frame, so the cloud
//                    rides the object's animated drift/hover/spin/tilt for free and is guaranteed to
//                    land exactly on the clean object at lock. There is no second copy of the
//                    transform to keep in sync, which is the entire reason this is a node binding
//                    rather than a modelMatrix parameter.
//     - RENDERABLE:  node.payload (a dwGfxModel when payloadType === "model") plus whatever texture
//                    handles the adapter needs. The effect never draws the payload itself.
//     - HANDOFF:     nodeAlpha() is the weight the scene should apply to the node's NORMAL render
//                    path. The scene keeps drawing the node exactly as it always did and simply
//                    scales its opacity by that number; this class never intercepts that draw.
//   Division of labour, stated once: THE EFFECT OWNS TIMING, WIND AND FORMATION. THE NODE OWNS
//   TRANSFORM, RENDERABLE AND ITS OWN RENDERING. Neither reaches into the other.
//
// SOURCE ADAPTERS select the BEHAVIOUR that turns the bound node into destination points. This is
// the extension point for surfels and geometry:
//     adapter.kind                      -> "texture-mask" | "surfel" | "mesh" | ...   (informational)
//     adapter.bind(node)                -> optional. Called when the adapter or the node changes, so
//                                          the adapter can pull handles off the node once.
//     adapter.build(node)               -> {
//         count:     int,
//         positions: Float32Array(count*3)   // destination, in the NODE'S LOCAL SPACE
//         colors:    Float32Array(count*4)   // r,g,b,a
//         sizes:     Float32Array(count)     // world units (NOT scaled by the node's model matrix)
//       } or null/undefined while assets are still loading. resolve() is safe to retry every frame.
//   - dwGfxLogoAlphaPointSource (shipped): texture alpha mask -> points on the node's quad.
//   - a surfel adapter returns existing surfel centres/colours/radii unchanged.
//   - a mesh adapter returns area-weighted samples of the node's model triangles.
//   All three differ ONLY in build(). Timing, wind, formation, blending, fog and handoff are shared.
//
// WHY THE MOTION IS ANALYTIC AND ON THE GPU
//   The existing CPU point paths repack every point into a dynamic buffer EVERY FRAME. That is fine
//   for a few hundred simulated creature points but not for thousands of mask points on a phone. So
//   the destination + a per-point seed are uploaded ONCE into a STATIC buffer and the entire
//   smoke -> shape motion is a closed-form function of (seed, progress, time) evaluated in the
//   vertex shader. A frame costs one uniform update and one drawArrays; zero per-point CPU. The
//   trade is that the motion cannot react to the scene, which a materialization sweep does not need.
//
// SHARED SAFETY, MIRRORING dwGfxMattePointRenderer EXACTLY (mirrored, never modified):
//   - own WebGL2 point-sprite program built lazily on first draw(), so headless construction is safe,
//   - depth-TESTs against the authoritative scene depth but NEVER writes depth (depthMask(false)),
//   - captures and restores every GL state it touches,
//   - the same tight soft-disc profile so it reads as material rather than light,
//   - default alpha-over blending keeps it below the bloom bright-pass threshold.
//
// Vertex layout: 12 floats/point, STATIC.
//     loc 0  a_dest  vec4 = destination xyz (node-local) + world-unit point size
//     loc 4  a_color vec4 = rgba                    (locations 0 and 4 match the engine convention)
//     loc 1  a_seed  vec4 = 3 decorrelated randoms + a per-point wake delay in 0..1
//
// m4 is used only for the view inverse and the wind direction transform.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

const DW_TPF_STRIDE = 12;   // floats per point (a_dest 4 + a_color 4 + a_seed 4)

// transition states
const DW_TPF_IDLE			= 0;   // fully dispersed smoke, waiting for trigger()
const DW_TPF_MATERIALIZING	= 1;   // condensing
const DW_TPF_LOCKED			= 2;   // fully condensed, field faded out, the node owns the pixels
const DW_TPF_DISSOLVING		= 3;   // condensed -> smoke (the reverse sweep)

class dwGfxTransitionalPointField
{
	constructor(gfx, options = {})
	{
		this.gfx = gfx;
		const o = options || {};

		this.maxPoints		= o.maxPoints		!== undefined ? o.maxPoints		: 16384;
		this.blend			= o.blend			!== undefined ? o.blend			: "alpha";   // "alpha" | "additive"
		this.coreSharpness	= o.coreSharpness	!== undefined ? o.coreSharpness	: 0.55;
		this.maxPointSize	= o.maxPointSize	!== undefined ? o.maxPointSize	: 1024.0;
		this.enabled		= o.enabled			!== undefined ? o.enabled		: true;

		// ---- TIMING (owned by the effect) ----
		this.duration	= o.duration	!== undefined ? o.duration	: 2.2;   // s, smoke -> locked
		this.stagger	= o.stagger		!== undefined ? o.stagger	: 0.45;  // 0..1 spread of per-point wake delays

		// ---- HANDOFF (owned by the effect): three ramps, deliberately NOT complementary ----
		// A single complementary pair (node = t, field = 1 - t) forced the points to fade out at
		// exactly the rate the node faded in. With a per-point wake delay of `stagger`, the latest
		// points are still well short of their destinations at that moment, so they dimmed out in
		// mid-flight and the shape appeared to assemble from nothing. Splitting the handoff into
		// three ramps over the SAME progress lets each consumer leave at the right time:
		//
		//   lockStart   colour ramp begins. By 0.80 the median point is ~84% of the way home and
		//               the latest ~78%, so the logo only starts tinting in once most points have
		//               effectively arrived.
		//   fieldHold   points hold FULL opacity until here, then fade over the remainder. At 0.88
		//               even the latest point is ~89% of the way to its node-local destination, so
		//               nothing dims while it is still visibly travelling.
		//   depthStart  the node does not become an OCCLUDER until it is nearly locked. Held last
		//               and shortest on purpose: it is the only one of the three whose early
		//               arrival is destructive rather than merely ugly (a half-formed logo would
		//               clip the fog, the leaves and the field's own points).
		//
		// The ramps overlap in [fieldHold, 1], where the points are essentially coincident with the
		// shape -- they read as the logo's own sparkle settling, which is the handoff, not a double
		// image. All three are pure functions of `progress` with no latching, so running progress
		// backwards runs each ramp backwards: on dissolve the depth ramp is the first to reach zero
		// and does so within (1 - depthStart) of the sweep, i.e. the node stops occluding almost at
		// once, while the colour keeps fading and the points detach behind it.
		this.lockStart	= o.lockStart	!== undefined ? o.lockStart	: 0.80;  // colour ramp start
		this.fieldHold	= o.fieldHold	!== undefined ? o.fieldHold	: 0.88;  // points stay full until here
		this.depthStart	= o.depthStart	!== undefined ? o.depthStart: 0.94;  // depth ramp start

		// ---- FORMATION (owned by the effect): the shape of the dispersed cloud ----
		// NOTE: these are NODE-LOCAL units, so they scale with the node. For the logo (quad local
		// +/-0.5, node scale 5) a spread of 0.9 disperses to roughly 4.5 world units around a
		// 5-world-unit logo -- a cloud about the size of the shape itself.
		this.spread		= o.spread		!== undefined ? o.spread	: 0.90;  // radial dispersion when fully smoke
		this.rise		= o.rise		!== undefined ? o.rise		: 0.40;  // upward bias, so it reads as smoke not an explosion
		this.smokeSize	= o.smokeSize	!== undefined ? o.smokeSize	: 3.2;   // size multiplier when fully smoke
		this.smokeAlpha	= o.smokeAlpha	!== undefined ? o.smokeAlpha: 0.35;  // alpha multiplier when fully smoke

		// ---- WIND (owned by the effect): how the dispersed cloud moves ----
		// windDir is given in WORLD space because that is how a scene thinks about wind; it is
		// rotated into node-local space once per frame so the cloud streams in a fixed world
		// direction even while the node spins underneath it.
		this.windDir	= o.windDir		!== undefined ? o.windDir	: [0.6, 0.25, 0.0];
		this.windSpeed	= o.windSpeed	!== undefined ? o.windSpeed	: 0.35;  // node-local units of steady offset
		this.gust		= o.gust		!== undefined ? o.gust		: 0.18;  // amplitude of the unsteady part
		this.gustRate	= o.gustRate	!== undefined ? o.gustRate	: 0.8;   // rad/s of the gust
		this.swirl		= o.swirl		!== undefined ? o.swirl		: 0.65;  // rad/s of the dispersed swirl
		this.drift		= o.drift		!== undefined ? o.drift		: 0.08;  // slow incoherent wander

		// ---- fog integration ----
		// Per-point exponential distance extinction is done in the VS (it already has the view-space
		// distance for the point size, so this is nearly free). The bounded ELLIPSOID POCKET term is
		// non-trivial in GLSL and the field occupies one small region of the scene, so it is sampled
		// ONCE per frame on the CPU at the bound node's world position and passed as a scalar. That
		// is a deliberate approximation, exact whenever no pocket overlaps the field.
		this.fogFloor	= o.fogFloor	!== undefined ? o.fogFloor	: 0.25;
		this.fogEnabled	= o.fogEnabled	!== undefined ? o.fogEnabled: true;
		this._fogDensity = 0.0;
		this._fogExtra   = 0.0;

		// ---- state ----
		this.state		= DW_TPF_IDLE;
		this.progress	= 0.0;
		this.count		= 0;
		this.time		= 0.0;

		// pooled static batch, allocated once at capacity. Never reallocated, never repacked per
		// frame -- resolve() is the only writer.
		this.batch		= new Float32Array(this.maxPoints * DW_TPF_STRIDE);
		this._dirty		= false;   // batch changed -> needs re-upload on next draw

		this.node		= null;    // authoritative bound object
		this.adapter	= null;    // selected source behaviour

		this._glReady		= false;
		this._programInfo	= null;
		this._vao			= null;
		this._vbo			= null;
	}

	// ---- node binding --------------------------------------------------------------------------

	// Bind the authoritative scene object. Everything spatial follows from this. Rebinding clears
	// the cached geometry, because destination points are expressed in the node's local space and a
	// different node means a different space.
	bindNode(node)
	{
		if (this.node === node) {
			return this;
		}
		this.node = node || null;
		this.count = 0;
		this._dirty = false;
		if (this.adapter && this.node && typeof this.adapter.bind === "function") {
			this.adapter.bind(this.node);
		}
		return this;
	}

	boundNode()
	{
		return this.node;
	}

	// The node's world matrix, or identity if nothing is bound yet. This is the field's model matrix
	// and the clean object's model matrix -- the same array, so they cannot diverge.
	nodeWorldMatrix()
	{
		if (this.node && typeof this.node.getWorldMatrix === "function") {
			return this.node.getWorldMatrix();
		}
		if (this.node && this.node.worldMatrix) {
			return this.node.worldMatrix;
		}
		return m4.identity();
	}

	// World-space position of the bound node, used for the fog pocket sample.
	nodeWorldPosition()
	{
		const m = this.nodeWorldMatrix();
		return [m[12], m[13], m[14]];
	}

	// The renderable handle the node carries, for adapters that need it (a mesh adapter reads the
	// dwGfxModel; a surfel adapter reads its own payload). Returns null for an empty group node.
	nodeRenderable()
	{
		return this.node ? this.node.payload : null;
	}

	// ---- source adapter ------------------------------------------------------------------------

	// Select the source BEHAVIOUR. Swapping adapters on a bound node re-derives the destination from
	// the same object -- that is how a later surfel or mesh adapter drops in with no other change.
	setAdapter(adapter)
	{
		this.adapter = adapter || null;
		this.count = 0;
		this._dirty = false;
		if (this.adapter && this.node && typeof this.adapter.bind === "function") {
			this.adapter.bind(this.node);
		}
		return this;
	}

	adapterKind()
	{
		return (this.adapter && this.adapter.kind) ? this.adapter.kind : "none";
	}

	// Pull destination points from the adapter and pack the static batch. Safe to call every frame
	// until it returns true: an adapter whose assets are still loading returns null and this is a
	// cheap no-op. Returns true once geometry is present.
	resolve(adapter)
	{
		const src = adapter || this.adapter;
		if (!src || typeof src.build !== "function") {
			return false;
		}
		const built = src.build(this.node);
		if (!built || !built.count) {
			return false;
		}

		let n = built.count | 0;
		if (n > this.maxPoints) { n = this.maxPoints; }

		const bt = this.batch;
		const P = built.positions;
		const C = built.colors;
		const S = built.sizes;

		for (let i = 0; i < n; i++) {
			const o = i * DW_TPF_STRIDE;
			bt[o + 0] = P[i * 3 + 0];
			bt[o + 1] = P[i * 3 + 1];
			bt[o + 2] = P[i * 3 + 2];
			bt[o + 3] = S ? S[i] : 0.02;
			bt[o + 4] = C ? C[i * 4 + 0] : 1.0;
			bt[o + 5] = C ? C[i * 4 + 1] : 1.0;
			bt[o + 6] = C ? C[i * 4 + 2] : 1.0;
			bt[o + 7] = C ? C[i * 4 + 3] : 1.0;
			// Deterministic per-point seeds derived from the index. A hash (not Math.random) keeps
			// the dispersal identical across reloads, which makes the effect reproducible and makes
			// the node tests meaningful.
			bt[o +  8] = this._hash01(i * 3 + 1);
			bt[o +  9] = this._hash01(i * 7 + 2);
			bt[o + 10] = this._hash01(i * 11 + 3);
			bt[o + 11] = this._hash01(i * 13 + 5);   // wake delay
		}

		this.count = n;
		this._dirty = true;
		return true;
	}

	hasGeometry()
	{
		return this.count > 0;
	}

	// ---- transition control --------------------------------------------------------------------

	// begin materializing. Ignored unless we are dispersed (idle) or already dissolving, so a
	// repeated touch during the sweep does not restart it.
	trigger()
	{
		if (this.state === DW_TPF_IDLE || this.state === DW_TPF_DISSOLVING) {
			this.state = DW_TPF_MATERIALIZING;
		}
		return this;
	}

	// reverse: condensed shape -> smoke.
	dissolve()
	{
		if (this.state === DW_TPF_LOCKED || this.state === DW_TPF_MATERIALIZING) {
			this.state = DW_TPF_DISSOLVING;
		}
		return this;
	}

	// jump straight to the clean object (used by the "off" toggle so disabling the effect can never
	// leave the node stuck invisible).
	lockNow()
	{
		this.state = DW_TPF_LOCKED;
		this.progress = 1.0;
		return this;
	}

	// back to fully dispersed smoke.
	resetToSmoke()
	{
		this.state = DW_TPF_IDLE;
		this.progress = 0.0;
		return this;
	}

	isLocked()
	{
		return this.state === DW_TPF_LOCKED;
	}

	stateName()
	{
		switch (this.state) {
			case DW_TPF_MATERIALIZING:	return "materializing";
			case DW_TPF_LOCKED:			return "locked";
			case DW_TPF_DISSOLVING:		return "dissolving";
			default:					return "smoke";
		}
	}

	update(dt)
	{
		let h = dt;
		if (!(h > 0.0)) { h = 0.0; }
		if (h > 0.1) { h = 0.1; }
		this.time += h;

		const rate = (this.duration > 1e-4) ? (h / this.duration) : 1.0;
		if (this.state === DW_TPF_MATERIALIZING) {
			this.progress += rate;
			if (this.progress >= 1.0) {
				this.progress = 1.0;
				this.state = DW_TPF_LOCKED;
			}
		}
		else if (this.state === DW_TPF_DISSOLVING) {
			this.progress -= rate;
			if (this.progress <= 0.0) {
				this.progress = 0.0;
				this.state = DW_TPF_IDLE;
			}
		}
		return this;
	}

	// ---- rendering handoff -----------------------------------------------------------------------
	// Three ramps over one progress, staged as described at the constructor. Every one is a pure
	// function of `progress`, is exactly 0 at progress 0 and exactly 1 at progress 1, and is smooth
	// (C1) at both ends -- so the steady states are bit-identical to a hard on/off and nothing pops
	// at either boundary of any ramp.

	// smoothstep of progress across [start, 1].
	_handoffRamp(start)
	{
		let t = (this.progress - start) / Math.max(1e-4, 1.0 - start);
		if (t <= 0.0) { return 0.0; }
		if (t >= 1.0) { return 1.0; }
		return t * t * (3.0 - 2.0 * t);
	}

	// Weight for the BOUND NODE'S NORMAL RENDERING -- its COLOUR only. The scene draws the node
	// exactly as it always did and multiplies its visual weights by this.
	colorAlpha()
	{
		return this._handoffRamp(this.lockStart);
	}

	// Weight for the node's participation in DEPTH. Held back until the shape is nearly locked, so a
	// half-formed logo never becomes an occluder -- and released first on the way out, so a
	// dissolving logo stops occluding almost immediately.
	depthAlpha()
	{
		return this._handoffRamp(this.depthStart);
	}

	// Back-compatible name: the node's colour weight is what every existing caller meant by this.
	nodeAlpha()
	{
		return this.colorAlpha();
	}

	// Weight for this point field. NOT 1 - nodeAlpha(): the points hold full opacity until they are
	// nearly home, which is the whole point of splitting the handoff.
	fieldAlpha()
	{
		return 1.0 - this._handoffRamp(this.fieldHold);
	}

	// One call for the scene's render path: what to do with the node this frame.
	handoff()
	{
		return {
			nodeAlpha: this.nodeAlpha(),
			colorAlpha: this.colorAlpha(),
			depthAlpha: this.depthAlpha(),
			fieldAlpha: this.fieldAlpha(),
			locked: this.isLocked(),
			drawField: !this.isIdleInvisible(),
		};
	}

	// true when there is nothing for this field to contribute, so the scene can skip the draw
	// entirely once the transition has finished.
	isIdleInvisible()
	{
		return (this.state === DW_TPF_LOCKED) || this.count <= 0 || !this.enabled;
	}

	// ---- fog -------------------------------------------------------------------------------------

	// Take the scene's existing overlay fog params. The reference point for the bounded pocket term
	// defaults to the bound node's world position, so callers no longer supply it.
	setFog(fogParams, refPoint)
	{
		if (!fogParams || !this.fogEnabled) {
			this._fogDensity = 0.0;
			this._fogExtra = 0.0;
			return this;
		}
		this._fogDensity = fogParams.density || 0.0;
		this._fogExtra = this._pocketOptical(fogParams, refPoint || this.nodeWorldPosition());
		return this;
	}

	// bounded ellipsoid-pocket extinction at a single reference point, using the SAME formulation as
	// dwGfxMattePointRenderer._fogTransmittance so the field matches the other point effects.
	_pocketOptical(fp, refPoint)
	{
		if (!refPoint || !fp.pocketCenters) {
			return 0.0;
		}
		const n = Math.min(fp.pocketCount | 0, 8);
		if (n <= 0) {
			return 0.0;
		}
		const cp = fp.cameraPos;
		let d = 0.0;
		if (cp) {
			const dx = refPoint[0] - cp[0], dy = refPoint[1] - cp[1], dz = refPoint[2] - cp[2];
			d = Math.sqrt(dx * dx + dy * dy + dz * dz);
			const maxD = fp.maxDistance !== undefined ? fp.maxDistance : 1e9;
			if (d > maxD) { d = maxD; }
		}
		let optical = 0.0;
		for (let i = 0; i < n; i++) {
			const rr = fp.pocketRadii ? fp.pocketRadii[i] : 0.0;
			if (rr <= 0.0) { continue; }
			const px = refPoint[0] - fp.pocketCenters[i * 3 + 0];
			const py = refPoint[1] - fp.pocketCenters[i * 3 + 1];
			const pz = refPoint[2] - fp.pocketCenters[i * 3 + 2];
			const pdist = Math.sqrt(px * px + py * py + pz * pz);
			const fe = fp.pocketFeathers ? fp.pocketFeathers[i] : 0.0;
			const pd = fp.pocketDensity ? fp.pocketDensity[i] : 0.0;
			const e0 = rr + fe, e1 = rr - fe;
			let inside;
			if (e0 === e1) {
				inside = pdist <= rr ? 1.0 : 0.0;
			}
			else {
				let tt = (pdist - e0) / (e1 - e0);
				tt = tt < 0.0 ? 0.0 : (tt > 1.0 ? 1.0 : tt);
				inside = tt * tt * (3.0 - 2.0 * tt);
			}
			optical += pd * inside * d * 0.5;
		}
		return optical;
	}

	// ---- diagnostics -----------------------------------------------------------------------------

	batchView()
	{
		return { data: this.batch, count: this.count };
	}

	activeCount()
	{
		return this.isIdleInvisible() ? 0 : this.count;
	}

	// ---- GL --------------------------------------------------------------------------------------

	_vsSource()
	{
		return "#version 300 es\n" +
			"layout(location = 0) in vec4 a_dest;\n" +    // xyz destination (node-local), w = world size
			"layout(location = 4) in vec4 a_color;\n" +
			"layout(location = 1) in vec4 a_seed;\n" +    // xyz random, w = wake delay
			"uniform mat4 u_model;\n" +
			"uniform mat4 u_view;\n" +
			"uniform mat4 u_projection;\n" +
			"uniform float u_sizeScale;\n" +
			"uniform float u_maxPointSize;\n" +
			"uniform float u_progress;\n" +
			"uniform float u_stagger;\n" +
			"uniform float u_time;\n" +
			"uniform float u_spread;\n" +
			"uniform float u_rise;\n" +
			"uniform float u_swirl;\n" +
			"uniform float u_drift;\n" +
			"uniform vec3  u_windLocal;\n" +   // world wind, already rotated into node-local space
			"uniform float u_windSpeed;\n" +
			"uniform float u_gust;\n" +
			"uniform float u_gustRate;\n" +
			"uniform float u_smokeSize;\n" +
			"uniform float u_smokeAlpha;\n" +
			"uniform float u_fieldAlpha;\n" +
			"uniform float u_fogDensity;\n" +
			"uniform float u_fogFloor;\n" +
			"uniform float u_fogExtra;\n" +
			"out vec3 v_color;\n" +
			"out float v_alpha;\n" +
			"void main() {\n" +
			// Per-point wake delay: points start condensing at different times, so the cloud gathers
			// progressively instead of collapsing as one rigid sheet.
			"  float w = a_seed.w * u_stagger;\n" +
			"  float pp = clamp((u_progress - w) / max(1e-4, 1.0 - w), 0.0, 1.0);\n" +
			"  float e = pp * pp * (3.0 - 2.0 * pp);\n" +
			"  float d = 1.0 - e;\n" +   // 1 = fully smoke, 0 = fully condensed
			// FORMATION: closed-form dispersal in node-local space, so the whole field rides the
			// node's animated world matrix exactly (no drift relative to the shape).
			"  float ang = a_seed.x * 6.2831853 + u_time * u_swirl * (0.5 + a_seed.y);\n" +
			"  float rad = u_spread * (0.35 + a_seed.z);\n" +
			"  vec3 off = vec3(cos(ang) * rad, sin(ang) * rad * 0.6, sin(ang * 1.7 + a_seed.y * 3.1) * rad);\n" +
			"  off.y += u_rise * (0.4 + a_seed.x);\n" +
			// WIND: a steady bias plus an unsteady gust, both per-point scaled so the cloud shears
			// instead of translating rigidly.
			"  float gust = u_gust * sin(u_time * u_gustRate + a_seed.z * 6.2831853);\n" +
			"  off += u_windLocal * ((u_windSpeed * (0.6 + 0.8 * a_seed.y)) + gust);\n" +
			"  off += u_drift * vec3(\n" +
			"      sin(u_time * 0.7 + a_seed.x * 6.2831853),\n" +
			"      sin(u_time * 0.9 + a_seed.y * 6.2831853),\n" +
			"      sin(u_time * 1.1 + a_seed.z * 6.2831853));\n" +
			"  vec3 local = a_dest.xyz + off * d;\n" +
			"  vec4 viewPos = u_view * (u_model * vec4(local, 1.0));\n" +
			"  gl_Position = u_projection * viewPos;\n" +
			"  float dist = max(0.0001, -viewPos.z);\n" +
			"  float sz = a_dest.w * mix(u_smokeSize, 1.0, e);\n" +
			"  gl_PointSize = clamp(sz * u_sizeScale / dist, 1.0, u_maxPointSize);\n" +
			// Bounded analytic fog, matching the other post-fog point effects: exponential distance
			// extinction remapped into [fogFloor, 1] so a distant field never fully vanishes.
			"  float fog = exp(-(u_fogDensity * dist + u_fogExtra));\n" +
			"  fog = u_fogFloor + (1.0 - u_fogFloor) * clamp(fog, 0.0, 1.0);\n" +
			"  v_color = a_color.rgb;\n" +
			"  v_alpha = a_color.a * mix(u_smokeAlpha, 1.0, e) * u_fieldAlpha * fog;\n" +
			"}\n";
	}

	_fsSource()
	{
		return "#version 300 es\n" +
			"precision highp float;\n" +
			"in vec3 v_color;\n" +
			"in float v_alpha;\n" +
			"uniform float u_coreSharpness;\n" +
			"out vec4 fragColor;\n" +
			"void main() {\n" +
			"  vec2 c = gl_PointCoord - vec2(0.5);\n" +
			"  float r = length(c) * 2.0;\n" +
			"  if (r > 1.0) { discard; }\n" +
			"  float disc = 1.0 - smoothstep(u_coreSharpness, 1.0, r);\n" +
			"  float a = v_alpha * disc;\n" +
			"  if (a <= 0.0) { discard; }\n" +
			"  fragColor = vec4(v_color, a);\n" +
			"}\n";
	}

	_initGL()
	{
		const gl = dwGfx.gl();
		this._programInfo = twgl.createProgramInfo(gl, [this._vsSource(), this._fsSource()], {
			attribLocations: { 'a_dest': 0, 'a_seed': 1, 'a_color': 4 },
		});

		this._vao = gl.createVertexArray();
		this._vbo = gl.createBuffer();

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		// STATIC_DRAW: written by resolve() only, not per frame.
		gl.bufferData(gl.ARRAY_BUFFER, this.batch.byteLength, gl.STATIC_DRAW);

		const stride = DW_TPF_STRIDE * 4;   // bytes
		gl.enableVertexAttribArray(0);
		gl.vertexAttribPointer(0, 4, gl.FLOAT, false, stride, 0);
		gl.enableVertexAttribArray(4);
		gl.vertexAttribPointer(4, 4, gl.FLOAT, false, stride, 16);
		gl.enableVertexAttribArray(1);
		gl.vertexAttribPointer(1, 4, gl.FLOAT, false, stride, 32);

		gl.bindVertexArray(null);
		gl.bindBuffer(gl.ARRAY_BUFFER, null);

		this._glReady = true;
		this._dirty = true;
	}

	// Rotate the world-space wind into the node's local space using the inverse model matrix, so the
	// cloud streams in a fixed world direction while the node spins underneath it. Re-normalised
	// afterwards, which also absorbs the node's scale (a direction is not a point, and for a
	// non-uniform scale the exact transform would need the inverse-transpose -- for a wind bias the
	// normalised inverse rotation is the right amount of correctness).
	_windLocal(model)
	{
		const w = this.windDir;
		const len = Math.sqrt(w[0] * w[0] + w[1] * w[1] + w[2] * w[2]);
		if (len < 1e-6) {
			return [0.0, 0.0, 0.0];
		}
		const inv = m4.inverse(model);
		const x = inv[0] * w[0] + inv[4] * w[1] + inv[8]  * w[2];
		const y = inv[1] * w[0] + inv[5] * w[1] + inv[9]  * w[2];
		const z = inv[2] * w[0] + inv[6] * w[1] + inv[10] * w[2];
		const n = Math.sqrt(x * x + y * y + z * z);
		if (n < 1e-6) {
			return [0.0, 0.0, 0.0];
		}
		return [x / n, y / n, z / n];
	}

	// Draw the field. The model matrix comes from the BOUND NODE; `modelMatrixOverride` exists only
	// for callers that drive the effect without a node at all.
	draw(cameraView, modelMatrixOverride)
	{
		if (!this.enabled || this.count <= 0 || this.isIdleInvisible()) {
			return;
		}
		const fieldA = this.fieldAlpha();
		if (fieldA <= 0.0) {
			return;
		}
		const gl = dwGfx.gl();
		if (!this._glReady) {
			this._initGL();
		}

		let count = this.count;
		if (count > this.maxPoints) { count = this.maxPoints; }

		const model = modelMatrixOverride || this.nodeWorldMatrix();

		// ---- capture prior GL state ----
		const prevProgram	= gl.getParameter(gl.CURRENT_PROGRAM);
		const prevVAO		= gl.getParameter(gl.VERTEX_ARRAY_BINDING);
		const prevArrayBuf	= gl.getParameter(gl.ARRAY_BUFFER_BINDING);
		const prevBlend		= gl.isEnabled(gl.BLEND);
		const prevDepthTest	= gl.isEnabled(gl.DEPTH_TEST);
		const prevCull		= gl.isEnabled(gl.CULL_FACE);
		const prevDepthMask	= gl.getParameter(gl.DEPTH_WRITEMASK);
		const prevDepthFunc	= gl.getParameter(gl.DEPTH_FUNC);
		const prevSrcRGB	= gl.getParameter(gl.BLEND_SRC_RGB);
		const prevDstRGB	= gl.getParameter(gl.BLEND_DST_RGB);
		const prevSrcAlpha	= gl.getParameter(gl.BLEND_SRC_ALPHA);
		const prevDstAlpha	= gl.getParameter(gl.BLEND_DST_ALPHA);

		const viewMatrix = m4.inverse(cameraView.worldMatrix);
		const projectionMatrix = cameraView.projectionMatrix;
		const sizeScale = projectionMatrix[5] * gl.canvas.height * 0.5;

		gl.useProgram(this._programInfo.program);
		twgl.setUniforms(this._programInfo, {
			u_model: model,
			u_view: viewMatrix,
			u_projection: projectionMatrix,
			u_sizeScale: sizeScale,
			u_maxPointSize: this.maxPointSize,
			u_progress: this.progress,
			u_stagger: this.stagger,
			u_time: this.time,
			u_spread: this.spread,
			u_rise: this.rise,
			u_swirl: this.swirl,
			u_drift: this.drift,
			u_windLocal: this._windLocal(model),
			u_windSpeed: this.windSpeed,
			u_gust: this.gust,
			u_gustRate: this.gustRate,
			u_smokeSize: this.smokeSize,
			u_smokeAlpha: this.smokeAlpha,
			u_fieldAlpha: fieldA,
			u_fogDensity: this._fogDensity,
			u_fogFloor: this.fogFloor,
			u_fogExtra: this._fogExtra,
			u_coreSharpness: this.coreSharpness,
		});

		gl.enable(gl.BLEND);
		if (this.blend === "additive") {
			gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ONE, gl.ONE);
		}
		else {
			gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
		}
		gl.enable(gl.DEPTH_TEST);
		// Set depthFunc EXPLICITLY. Enabling DEPTH_TEST without it inherits whatever the previous
		// pass left, which is not ours to assume -- the overlay passes run in a configurable order
		// and one of them leaving GREATER/ALWAYS would sort this whole cloud wrongly.
		gl.depthFunc(gl.LEQUAL);
		gl.depthMask(false);
		gl.disable(gl.CULL_FACE);

		gl.bindVertexArray(this._vao);
		gl.bindBuffer(gl.ARRAY_BUFFER, this._vbo);
		// Upload only when the geometry actually changed. In the steady state this is zero bytes of
		// per-frame buffer traffic -- the whole point of the analytic path.
		if (this._dirty) {
			gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.batch, 0, count * DW_TPF_STRIDE);
			this._dirty = false;
		}
		gl.drawArrays(gl.POINTS, 0, count);

		// ---- restore prior GL state exactly ----
		gl.bindBuffer(gl.ARRAY_BUFFER, prevArrayBuf);
		gl.bindVertexArray(prevVAO);
		gl.useProgram(prevProgram);
		gl.blendFuncSeparate(prevSrcRGB, prevDstRGB, prevSrcAlpha, prevDstAlpha);
		if (prevBlend) { gl.enable(gl.BLEND); } else { gl.disable(gl.BLEND); }
		if (prevDepthTest) { gl.enable(gl.DEPTH_TEST); } else { gl.disable(gl.DEPTH_TEST); }
		if (prevCull) { gl.enable(gl.CULL_FACE); } else { gl.disable(gl.CULL_FACE); }
		gl.depthMask(prevDepthMask);
		gl.depthFunc(prevDepthFunc);
	}

	// deterministic 0..1 hash: integer -> float. Cheap, decorrelated enough for dispersal seeds, and
	// stable across reloads and platforms (no Math.random, no Date).
	_hash01(i)
	{
		let x = (i | 0) * 374761393 + 668265263;
		x = (x ^ (x >>> 13)) | 0;
		x = (x * 1274126177) | 0;
		x = (x ^ (x >>> 16)) >>> 0;
		return x / 4294967296.0;
	}
}

if (typeof module !== "undefined" && module.exports) {
	module.exports = {
		dwGfxTransitionalPointField: dwGfxTransitionalPointField,
		DW_TPF_IDLE: DW_TPF_IDLE,
		DW_TPF_MATERIALIZING: DW_TPF_MATERIALIZING,
		DW_TPF_LOCKED: DW_TPF_LOCKED,
		DW_TPF_DISSOLVING: DW_TPF_DISSOLVING,
	};
}
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// dwGfxLogoAlphaPointSource.js
//
// First SOURCE ADAPTER for dwGfxTransitionalPointField: converts a texture's ALPHA MASK into
// destination points laid out on the quad that texture is drawn on. Used for the centre logo, but
// it is texture-generic -- nothing here is logo-specific beyond the defaults.
//
// ADAPTER CONTRACT (kind "texture-mask")
//   kind        -> "texture-mask", so the field and the HUD can report which behaviour is selected.
//   bind(node)  -> the field calls this whenever the authoritative dwGfxNode changes. The node owns
//                  the TRANSFORM and the RENDERABLE; this adapter only needs the node so it can pick
//                  up a mask URL the node carries (node.maskUrl / node.textureUrl) when one was not
//                  supplied to the constructor. The node is not consulted for geometry -- the mask
//                  lives in image pixels, not in the transform.
//   build(node) -> destination points in the NODE'S LOCAL SPACE. Returns null until decoded.
//   A later surfel or mesh adapter implements the same three members and drops straight in; only
//   build() differs, because timing, wind, formation and handoff all live in the effect.
//
// WHY IT RE-LOADS THE IMAGE INSTEAD OF READING THE ENGINE TEXTURE
//   dwGfxTexture does NOT retain the decoded bitmap. Its `this.img` is a placeholder dwImage created
//   in the constructor that only ever carries drawInfo (the GL handle, width, height); the real
//   HTMLImageElement in loadImage() is a local closure variable that is discarded once texImage2D
//   has consumed it. So there is no pixel data on the texture object to read, and pulling it back
//   out of GL would need a readPixels from a framebuffer we would have to create.
//   Instead this adapter loads the SAME URL itself. In the browser that is a memory-cache hit (the
//   engine already fetched it), so it costs no extra network round trip.
//
// CORS / TAINTING -- the actual answer
//   The engine's own rule is dwGfxTexture.requestCORSIfNotSameOrigin: set img.crossOrigin only when
//   the URL's origin differs from location.origin. This adapter mirrors that rule exactly, which
//   makes the outcome decidable without knowing the server config:
//     - SAME-ORIGIN  -> crossOrigin is never set, the canvas is never tainted, getImageData works.
//     - CROSS-ORIGIN -> crossOrigin is set. A cross-origin image with crossOrigin set and NO
//       Access-Control-Allow-Origin does not merely taint the canvas, it FAILS TO LOAD OUTRIGHT.
//       The demo's logo demonstrably renders, therefore ACAO must be present, therefore the same
//       anonymous request here also succeeds AND leaves the canvas untainted.
//   Either branch ends with a readable canvas, so no readPixels path is needed. Even so,
//   getImageData is wrapped: on SecurityError the adapter reports notReady/failed rather than
//   throwing, and the demo simply keeps the clean logo with no field. That is the graceful
//   degradation path, not the expected one.
//
// COORDINATE SPACE (verified against dwGfxModelQuad.build(1.0,"xy") + dwGfxModel.loadQuad)
//   The quad is local x,y in [-0.5,+0.5] at z=0, and its UVs are laid out so that v=0 is the TOP of
//   the image (corner (-0.5,-0.5) samples uv (0,1)). loadImage never sets UNPACK_FLIP_Y_WEBGL, so
//   texture v=0 is image row 0, which is also canvas row 0 from getImageData. The mapping is
//   therefore, for image pixel (px,py) of a w*h image:
//       u = (px + 0.5) / w        localX =  u - 0.5
//       v = (py + 0.5) / h        localY =  0.5 - v
//   Points are emitted in that LOCAL space; dwGfxTransitionalPointField multiplies by the BOUND
//   NODE'S animated world matrix, so they inherit the logo's drift/hover/spin/tilt for free and land
//   exactly on the clean logo at lock. That only holds because the node is authoritative: the field
//   reads the same matrix object the scene draws the quad with, so the two cannot drift apart.
///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'use strict';

class dwGfxLogoAlphaPointSource
{
	constructor(url, options = {})
	{
		const o = options || {};

		this.kind			= "texture-mask";
		this.node			= null;   // authoritative object, supplied by the field via bind()
		this.url			= url;
		this.sampleSize		= o.sampleSize		!== undefined ? o.sampleSize	: 160;   // mask raster edge, px
		this.targetCount	= o.targetCount		!== undefined ? o.targetCount	: 6000;  // desired emitted points
		this.alphaThreshold	= o.alphaThreshold	!== undefined ? o.alphaThreshold: 0.35;  // 0..1 on texel alpha
		this.pointSize		= o.pointSize		!== undefined ? o.pointSize		: 0.05;  // WORLD units (not scaled by u_model)
		this.jitter			= o.jitter			!== undefined ? o.jitter		: 0.6;   // fraction of a texel cell
		// warm tint matching the logo material's emissive; the albedo is greyscale so this is what
		// gives the condensing cloud the logo's colour rather than flat white.
		this.tint			= o.tint			!== undefined ? o.tint			: [1.0, 0.88, 0.55];
		this.alphaGamma		= o.alphaGamma		!== undefined ? o.alphaGamma	: 1.0;
		this.brightness		= o.brightness		!== undefined ? o.brightness	: 1.0;

		this.image		= null;
		this.loaded		= false;
		this.failed		= false;
		this.failReason	= "";
		this._built		= null;   // cached build() result: the mask is static, so build once

		if (url) {
			this.load(url);
		}
	}

	// mirrors dwGfxTexture.requestCORSIfNotSameOrigin so this adapter's request has exactly the same
	// CORS posture as the engine's own texture load (see header).
	_requestCORSIfNotSameOrigin(img, url)
	{
		if (typeof location === "undefined") {
			return;
		}
		try {
			if ((new URL(url, location.href)).origin !== location.origin) {
				img.crossOrigin = "";
			}
		}
		catch (e) {
			// malformed URL: leave crossOrigin unset, matching the engine's non-throwing behaviour.
		}
	}

	load(url)
	{
		this.url = url;
		this.loaded = false;
		this.failed = false;
		this._built = null;

		if (typeof Image === "undefined") {
			// headless (node tests): stay notReady rather than throwing.
			return this;
		}
		const self = this;
		const img = new Image();
		this._requestCORSIfNotSameOrigin(img, url);
		img.addEventListener("load", function() {
			self.image = img;
			self.loaded = true;
		});
		img.addEventListener("error", function() {
			self.failed = true;
			self.failReason = "image load failed";
		});
		img.src = url;
		return this;
	}

	// ADAPTER CONTRACT. Called by the field when the authoritative node is bound or changed. The
	// only thing this adapter wants from the node is a mask URL, and only if it was not constructed
	// with one -- everything spatial is the node's business, not the adapter's.
	bind(node)
	{
		this.node = node || null;
		if (!this.url && this.node) {
			const fromNode = this.node.maskUrl || this.node.textureUrl;
			if (fromNode) {
				this.load(fromNode);
			}
		}
		return this;
	}

	isReady()
	{
		return this.loaded && !this.failed;
	}

	// ADAPTER CONTRACT. Returns points in the bound node's LOCAL space, or null until the image is
	// decoded so the field can retry cheaply every frame. Result is cached: the mask never changes.
	// `node` is passed for symmetry with adapters that need it; this one already has it from bind().
	build(node)
	{
		if (node && node !== this.node) {
			this.bind(node);
		}
		if (this._built) {
			return this._built;
		}
		if (!this.isReady()) {
			return null;
		}

		const pixels = this._readMask();
		if (!pixels) {
			return null;
		}
		const w = pixels.width;
		const h = pixels.height;
		const data = pixels.data;
		const thr = this.alphaThreshold * 255.0;

		// Pass 1: how many texels qualify. Needed so pass 2 can pick a selection probability that
		// lands near targetCount regardless of how much of the mask is opaque.
		let qualifying = 0;
		for (let i = 0; i < w * h; i++) {
			if (data[i * 4 + 3] >= thr) { qualifying++; }
		}
		if (qualifying <= 0) {
			this.failed = true;
			this.failReason = "alpha mask is empty at this threshold";
			return null;
		}

		let want = this.targetCount;
		if (want > qualifying) { want = qualifying; }
		const keepP = want / qualifying;

		const positions	= new Float32Array(want * 3);
		const colors	= new Float32Array(want * 4);
		const sizes		= new Float32Array(want);

		const cellX = 1.0 / w;
		const cellY = 1.0 / h;
		let n = 0;

		// Pass 2: deterministic selection. A hash of the texel index (not Math.random) keeps the
		// point set identical across reloads, which makes the effect reproducible and the tests
		// meaningful.
		for (let py = 0; py < h && n < want; py++) {
			for (let px = 0; px < w && n < want; px++) {
				const i = py * w + px;
				const a8 = data[i * 4 + 3];
				if (a8 < thr) { continue; }
				if (this._hash01(i * 2654435761) >= keepP) { continue; }

				// texel centre -> uv -> quad local space (see the header for the derivation).
				const jx = (this._hash01(i * 40503 + 7) - 0.5) * this.jitter * cellX;
				const jy = (this._hash01(i * 40507 + 11) - 0.5) * this.jitter * cellY;
				const u = (px + 0.5) * cellX + jx;
				const v = (py + 0.5) * cellY + jy;

				positions[n * 3 + 0] = u - 0.5;
				positions[n * 3 + 1] = 0.5 - v;
				positions[n * 3 + 2] = 0.0;

				const r = data[i * 4 + 0] / 255.0;
				const g = data[i * 4 + 1] / 255.0;
				const b = data[i * 4 + 2] / 255.0;
				colors[n * 4 + 0] = r * this.tint[0] * this.brightness;
				colors[n * 4 + 1] = g * this.tint[1] * this.brightness;
				colors[n * 4 + 2] = b * this.tint[2] * this.brightness;
				let a = a8 / 255.0;
				if (this.alphaGamma !== 1.0) { a = Math.pow(a, this.alphaGamma); }
				colors[n * 4 + 3] = a;

				sizes[n] = this.pointSize;
				n++;
			}
		}

		this._built = { count: n, positions: positions, colors: colors, sizes: sizes };
		return this._built;
	}

	// Downsample the image into an offscreen 2D canvas and read it back. Returns null (and records
	// failReason) if the canvas turns out to be tainted -- see the CORS note in the header.
	_readMask()
	{
		if (typeof document === "undefined") {
			return null;
		}
		const iw = this.image.naturalWidth  || this.image.width;
		const ih = this.image.naturalHeight || this.image.height;
		if (!iw || !ih) {
			return null;
		}
		// preserve aspect ratio so a non-square logo is not stretched across the square quad.
		let w = this.sampleSize;
		let h = this.sampleSize;
		if (iw >= ih) { h = Math.max(1, Math.round(this.sampleSize * ih / iw)); }
		else          { w = Math.max(1, Math.round(this.sampleSize * iw / ih)); }

		const cv = document.createElement("canvas");
		cv.width = w;
		cv.height = h;
		const ctx = cv.getContext("2d", { willReadFrequently: true });
		if (!ctx) {
			return null;
		}
		ctx.clearRect(0, 0, w, h);
		ctx.drawImage(this.image, 0, 0, w, h);
		try {
			return ctx.getImageData(0, 0, w, h);
		}
		catch (e) {
			// SecurityError => the canvas was tainted after all. Degrade: the demo keeps the clean
			// logo and simply never shows the field.
			this.failed = true;
			this.failReason = "canvas tainted; alpha readback blocked (" + (e && e.name ? e.name : "error") + ")";
			return null;
		}
	}

	// same deterministic integer hash the point field uses.
	_hash01(i)
	{
		let x = (i | 0) * 374761393 + 668265263;
		x = (x ^ (x >>> 13)) | 0;
		x = (x * 1274126177) | 0;
		x = (x ^ (x >>> 16)) >>> 0;
		return x / 4294967296.0;
	}
}

if (typeof module !== "undefined" && module.exports) {
	module.exports = { dwGfxLogoAlphaPointSource: dwGfxLogoAlphaPointSource };
}