@geastack/native-webgl-angle 0.1.13 → 0.1.15

package/README.md

@@ -50,9 +50,36 @@ native/angle_webgl_host.mm
 
 ## Native sources in apps
 
-Gea app manifests currently accept only app-relative `nativeSources`. Until
-that resolver can consume package native sources directly, app consumers keep a
-small app-local `.mm` wrapper that includes this package's native implementation.
+Apple apps name the host in `gea.nativeSources`, either app-relative or by
+package path (`@geastack/native-webgl-angle/native/angle_webgl_host.mm`).
+
+The Windows desktop target needs nothing in the app: `gea-native.json`
+declares the host (`native/angle_webgl_host.mm` and `native/audio_host.mm`,
+compiled as C++) and `native/win32_webgl_surface.cpp`, a host extension that
+gives the program a child window filling the main window's content area,
+attaches the WebGL context to it before the program's top level runs, makes
+the context current around initialization and each frame, hands frame pacing
+to the presentation, and reports keys (as macOS virtual key codes, with a
+release held until a frame has seen the key down) and the pointer (in CSS
+pixels).
+
+The package requires a `gles` provider: an EGL and OpenGL ES 3
+implementation. The app configures it, for example
+
+```json
+"gea": { "targets": { "windows": { "providers": {
+  "gles": { "directory": "build/renderer", "files": { "egl": "GL.dll", "gles": "GL.dll" }, "runtimeFiles": ["d3d12/D3D12Core.dll"] }
+} } } }
+```
+
+or `"gles": "path/to/angle"` for a directory holding ANGLE's `libEGL.dll` and
+`libGLESv2.dll`. The build stages those files beside the executable and
+compiles their names in (`GEA_WEBGL_EGL_LIBRARY`, `GEA_WEBGL_GLES_LIBRARY`);
+the host loads them from the executable's directory. `GEA_ANGLE_EGL_DYLIB` and
+`GEA_ANGLE_GLES_DYLIB` still override the paths at run time. Without a
+provider the build stops and says so. Audio files resolve from
+`GEA_THREE_AUDIO_DIR`, else `Resources\Sounds` beside the executable, unless
+the app names a directory with `gea_three_audio_set_directory_uwp`.
 
 The bridge implementation itself lives here.
 
@@ -94,7 +121,7 @@ to change them. Any present value, including an empty string, enables them.
 
 ### Validation
 
-`npm run test:host-effects` checks 85 direct GL/input declarations and 15 audio
+`npm run test:host-effects` checks 87 direct GL/input declarations and 15 audio
 declarations against the compiler's host-mutation census. Their
 `@gea-host-inert` contracts permit native state changes while excluding script
 reference retention, script object mutation and script callbacks. The native

package/gea-native.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "What a GeaStack native target needs in order to build this package into an app. Paths are relative to the package root.",
+  "windows": {
+    "sources": ["native/angle_webgl_host.mm", "native/audio_host.mm", "native/resource_host.mm", "native/win32_webgl_surface.cpp"],
+    "includeDirs": ["native"],
+    "requires": {
+      "gles": {
+        "description": "an EGL and OpenGL ES 3 implementation (ANGLE's libEGL.dll and libGLESv2.dll, or one DLL exporting both)",
+        "files": {
+          "egl": { "define": "GEA_WEBGL_EGL_LIBRARY", "default": "libEGL.dll" },
+          "gles": { "define": "GEA_WEBGL_GLES_LIBRARY", "default": "libGLESv2.dll" }
+        }
+      }
+    }
+  }
+}

package/geatsc-plugin-uniforms.mjs

@@ -44,7 +44,9 @@ export const nativeLightUniformClassNames = [
 export const nativeUniformTypedefs = `/**
  * Every value a shader uniform slot can hold, as ONE disjoint union: the math
  * classes three's setters duck-type (\`v.x\`, \`v.r\`, \`v.elements\`), textures,
- * the flat numeric arrays, and the light-uniform arrays \`WebGLLights\` builds.
+ * the flat numeric arrays, the vector and matrix arrays a custom
+ * \`ShaderMaterial\` declares (\`uniform vec4 u[ N ]\`, flattened by
+ * \`copyUniformElement\`), and the light-uniform arrays \`WebGLLights\` builds.
  * A slot is therefore one native tagged union, and every consumer narrows it
  * with \`instanceof\`/\`typeof\`/\`Array.isArray\` instead of reading a box.
  * @typedef {number|boolean|null|undefined
@@ -57,7 +59,9 @@ export const nativeUniformTypedefs = `/**
  *   |import('../../math/Matrix4.js').Matrix4
  *   |import('../../textures/Texture.js').Texture
  *   |number[]|Float32Array|Int32Array|Uint32Array
+ *   |Array<import('../../math/Vector2.js').Vector2>
  *   |Array<import('../../math/Vector3.js').Vector3>
+ *   |Array<import('../../math/Vector4.js').Vector4>
  *   |Array<import('../../math/Matrix4.js').Matrix4>
  *   |Array<import('../../textures/Texture.js').Texture|null>
 ${nativeLightUniformClassNames.map((name) => ` *   |${name}|${name}[]`).join('\n')}
@@ -345,6 +349,13 @@ export function isUniformNumberArray( value ) {
 
 }
 
+/** @param {NativeUniformValue} value @return {value is Vector2[]} */
+function isVector2Array( value ) {
+
+\treturn Array.isArray( value ) && value.length > 0 && value[ 0 ] instanceof Vector2;
+
+}
+
 /** @param {NativeUniformValue} value @return {value is Vector3[]} */
 function isVector3Array( value ) {
 
@@ -352,6 +363,13 @@ function isVector3Array( value ) {
 
 }
 
+/** @param {NativeUniformValue} value @return {value is Vector4[]} */
+function isVector4Array( value ) {
+
+\treturn Array.isArray( value ) && value.length > 0 && value[ 0 ] instanceof Vector4;
+
+}
+
 /** @param {NativeUniformValue} value @return {value is Matrix4[]} */
 function isMatrix4Array( value ) {
 
@@ -405,6 +423,17 @@ export function cloneUniformValue( value ) {
 
 \tif ( isUniformNumberArray( value ) ) return value.slice();
 
+\tif ( isVector2Array( value ) ) {
+
+\t\t/** @type {Vector2[]} */
+\t\tconst cloned = [];
+
+\t\tfor ( let i = 0, l = value.length; i < l; i ++ ) cloned.push( value[ i ].clone() );
+
+\t\treturn cloned;
+
+\t}
+
 \tif ( isVector3Array( value ) ) {
 
 \t\t/** @type {Vector3[]} */
@@ -416,6 +445,17 @@ export function cloneUniformValue( value ) {
 
 \t}
 
+\tif ( isVector4Array( value ) ) {
+
+\t\t/** @type {Vector4[]} */
+\t\tconst cloned = [];
+
+\t\tfor ( let i = 0, l = value.length; i < l; i ++ ) cloned.push( value[ i ].clone() );
+
+\t\treturn cloned;
+
+\t}
+
 \tif ( isMatrix4Array( value ) ) {
 
 \t\t/** @type {Matrix4[]} */

package/geatsc-plugin-uploads.mjs

@@ -1,16 +1,21 @@
+// A texture upload hands GL the view's own bytes, and the GL type names the view
+// (WebGL 2 3.7.6, OES_texture_half_float): UNSIGNED_SHORT, HALF_FLOAT and the
+// packed 16-bit types read a Uint16Array; UNSIGNED_INT and the packed 32-bit
+// types a Uint32Array; BYTE, SHORT and INT their signed views; FLOAT a Float32Array.
+const textureElementKind = '(type == 0x1401 ? 4 : type == 0x1400 ? 5 : type == 0x1402 ? 6 : type == 0x1404 ? 7 : ' +
+  'type == 0x1403 || type == 0x140B || type == 0x8D61 || type == 0x8033 || type == 0x8034 || type == 0x8363 ? 2 : ' +
+  'type == 0x1405 || type == 0x8368 || type == 0x8C3B || type == 0x8C3E || type == 0x84FA ? 3 : 1)'
+
 // The host owns the physical upload format. The compiler only preserves the
 // native carriers at these explicitly registered synchronous boundaries.
-// Element type of the client pixels, by GL type: half floats travel as their
-// 16-bit patterns, never widened to float32.
-const pixelKind = '(type == 0x1403 || type == 0x140B || type == 0x8D61 ? 2 : type == 0x1405 ? 3 : type == 0x1401 ? 4 : type == 0x1400 ? 5 : type == 0x1402 ? 6 : type == 0x1404 ? 7 : 1)';
 export const nativeUploadFunctions = [
   ['threeWebGLBufferData', 'gea_three_webgl_buffer_data_native', ['target', 'usage', 'typeCode'], 'gea_three_webgl_buffer_data_bytes', ['target', 'usage'], 'typeCode'],
   ['threeWebGLBufferSubData', 'gea_three_webgl_buffer_sub_data_native', ['target', 'offset', 'typeCode'], 'gea_three_webgl_buffer_sub_data_bytes', ['target', 'offset'], 'typeCode'],
   ['threeWebGLBufferSubDataRange', 'gea_three_webgl_buffer_sub_data_range_native', ['target', 'offset', 'typeCode'], 'gea_three_webgl_buffer_sub_data_bytes', ['target', 'offset'], 'typeCode', true],
-  ['threeWebGLTexImage2D', 'gea_three_webgl_tex_image_2d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_image_2d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], pixelKind],
-  ['threeWebGLTexImage3D', 'gea_three_webgl_tex_image_3d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_image_3d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], pixelKind],
-  ['threeWebGLTexSubImage3D', 'gea_three_webgl_tex_sub_image_3d_native', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_sub_image_3d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], pixelKind],
-  ['threeWebGLTexSubImage2D', 'gea_three_webgl_tex_sub_image_2d_native', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_sub_image_2d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], pixelKind],
+  ['threeWebGLTexImage2D', 'gea_three_webgl_tex_image_2d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_image_2d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'format', 'type'], textureElementKind],
+  ['threeWebGLTexImage3D', 'gea_three_webgl_tex_image_3d_native', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_image_3d_bytes', ['target', 'level', 'internalFormat', 'width', 'height', 'depth', 'format', 'type'], textureElementKind],
+  ['threeWebGLTexSubImage3D', 'gea_three_webgl_tex_sub_image_3d_native', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], 'gea_three_webgl_tex_sub_image_3d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'zoffset', 'width', 'height', 'depth', 'format', 'type'], textureElementKind],
+  ['threeWebGLTexSubImage2D', 'gea_three_webgl_tex_sub_image_2d_native', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], 'gea_three_webgl_tex_sub_image_2d_bytes', ['target', 'level', 'xoffset', 'yoffset', 'width', 'height', 'format', 'type'], textureElementKind],
 ].map(([name, binding, parameters, raw, rawParameters, kind, range]) => {
   const declaration = `extern "C" void ${raw}(${rawParameters.map(p => `double ${p}`).join(', ')}, const void* bytes, double byteLength);
   template <typename Source> inline void ${binding}(${parameters.map(p => `double ${p}`).join(', ')}, const Source& values${range ? ', double sourceOffset, double length' : ''}) {

package/geatsc-plugin.mjs

@@ -97,6 +97,14 @@ const hostFunctions = [
   ],
   ...nativeUploadFunctions,
   ...nativeReadbackFunctions,
+  // Resources files (native/resource_host.mm): read whole, in place, into the caller's Uint8Array.
+  ['threeResourceSize','gea_three_resource_size','double','extern "C" double gea_three_resource_size(std::string name);'],
+  ['threeResourceRead','gea_three_resource_read_native','double',`
+extern "C" double gea_three_resource_read_bytes(std::string name, void* bytes, double byteLength);
+inline double gea_three_resource_read_native(std::string name, const gea::Ref<gea::TypedArray<std::uint8_t>>& destination) {
+  if (!destination) return -1;
+  return gea_three_resource_read_bytes(std::move(name), destination->data(), static_cast<double>(destination->size()));
+}`],
   ['threeWebGLBlitFramebuffer','gea_three_webgl_blit_framebuffer','void','extern "C" void gea_three_webgl_blit_framebuffer(double,double,double,double,double,double,double,double,double,double);'],
   ['threeWebGLReadPixelsPack','gea_three_webgl_read_pixels_pack','void','extern "C" void gea_three_webgl_read_pixels_pack(double,double,double,double,double,double,double);'],
   ['threeWebGLFenceSync','gea_three_webgl_fence_sync','double','extern "C" double gea_three_webgl_fence_sync();'],
@@ -148,6 +156,12 @@ const hostFunctions = [
     "void",
     'extern "C" void gea_three_webgl_swap();',
   ],
+  [
+    "threeWebGLSetVsync",
+    "gea_three_webgl_set_vsync",
+    "void",
+    'extern "C" void gea_three_webgl_set_vsync(double on);',
+  ],
   [
     "threeAngleSmokeLog",
     "gea_three_angle_smoke_log",
@@ -222,6 +236,12 @@ const hostFunctions = [
     "double",
     'extern "C" double gea_three_webgl_get_shader_parameter(double shader, double pname);',
   ],
+  [
+    "threeWebGLGetShaderInfoLog",
+    "gea_three_webgl_get_shader_info_log",
+    "std::string",
+    'extern "C" std::string gea_three_webgl_get_shader_info_log(double shader);',
+  ],
   [
     "threeWebGLDeleteShader",
     "gea_three_webgl_delete_shader",
@@ -253,6 +273,12 @@ const hostFunctions = [
     "double",
     'extern "C" double gea_three_webgl_get_program_parameter(double program, double pname);',
   ],
+  [
+    "threeWebGLGetProgramInfoLog",
+    "gea_three_webgl_get_program_info_log",
+    "std::string",
+    'extern "C" std::string gea_three_webgl_get_program_info_log(double program);',
+  ],
   [
     "threeWebGLDeleteProgram",
     "gea_three_webgl_delete_program",
@@ -1698,6 +1724,12 @@ const nativeDataTextureOverlayUnpackAlignmentSource =
   "\t/** @type {number} */\n\tunpackAlignment;";
 const overlayToJSONParameterSource =
   /(\/\*\*\n\t \* @param )\{[^\n]+\}( \[meta\]\n\t \*\/\n\ttoJSON\( meta \) \{)/g;
+const nativeObject3DJSONType =
+  "{ metadata?: { version: number, type: string, generator: string }, geometries?: Array<Object>, materials?: Array<Object>, textures?: Array<Object>, images?: Array<Object>, shapes?: Array<Object>, skeletons?: Array<Object>, animations?: Array<Object>, nodes?: Array<Object>, object: Object }";
+const nativeBufferGeometryJSONType =
+  "{ metadata: { version: number, type: string, generator: string }, uuid?: string, type?: string, name?: string, userData?: Object, data?: Object, instanceCount?: number, isInstancedBufferGeometry?: boolean, [key: string]: any }";
+const nativeFogJSONType =
+  "{ type: string, name: string, color: number, near?: number, far?: number, density?: number }";
 const rendererReceiverMethods = [
   "setPixelRatio",
   "setSize",
@@ -2032,6 +2064,37 @@ const transformSource = ({ fileName, text }) => {
       object3DRaycastSource,
       nativeObject3DRaycastSource,
     );
+    // `JSON.stringify` on a declared-any value keeps every class's `toJSON`
+    // (three's own `copy()` deep-copies `userData` that way), so these bodies
+    // compile whenever a material or texture is cloned. `@return {Object}`
+    // states nothing, so every `super.toJSON( meta )`, `child.toJSON( meta )`
+    // and `camera.toJSON( false )` result boxed and then had to be read back
+    // as the record the body builds, which no conversion can do. The envelope
+    // is the record the body builds; `object` stays `Object` because each
+    // subclass adds its own fields to it (`data.object.fov = ...`).
+    transformed = replaceOne(
+      transformed,
+      "\t * @return {Object} A JSON object representing the serialized 3D object.",
+      `\t * @return {${nativeObject3DJSONType}} A JSON object representing the serialized 3D object.`,
+      fileName,
+      "Object3D.toJSON envelope",
+    );
+  }
+  if (
+    normalized.endsWith("/three/src/scenes/Fog.js") ||
+    normalized.endsWith("/three/src/scenes/FogExp2.js")
+  ) {
+    // `Scene.toJSON` calls `toJSON` on `?(Fog|FogExp2)`. Each body's own
+    // literal made the two methods two function types, and the read over the
+    // union had to convert one into the other. One record both literals fit,
+    // spelled once, makes them one type.
+    transformed = replaceOne(
+      transformed,
+      "\t * @return {Object} A JSON object representing the serialized fog",
+      `\t * @return {${nativeFogJSONType}} A JSON object representing the serialized fog`,
+      fileName,
+      "Fog toJSON shared record",
+    );
   }
   if (normalized.endsWith("/three/src/renderers/WebGLRenderer.js")) {
     transformed =
@@ -2215,6 +2278,15 @@ class WebGLRenderer {
       rendererCompileReturnSource,
       nativeRendererCompileReturnSource,
     );
+    // `if ( targetScene === null ) targetScene = scene;` stores the Object3D
+    // being compiled; every use after it is an Object3D use.
+    transformed = replaceOne(
+      transformed,
+      `@param {?Scene} [targetScene=null] - The target scene.\n\t\t * ${nativeRendererCompileReturnSource}`,
+      `@param {?Object3D} [targetScene=null] - The target scene.\n\t\t * ${nativeRendererCompileReturnSource}`,
+      fileName,
+      "WebGLRenderer compile target root",
+    );
     transformed = transformed.replace(
       rendererCompileAssignmentSource,
       nativeRendererCompileAssignmentSource,
@@ -3718,6 +3790,33 @@ class BufferGeometry extends EventDispatcher {`,
       fileName,
       "BufferGeometry morph-attribute table",
     );
+    // `toJSON` fills each morph entry from `const array = []`, which the
+    // checker types `any[]` (the table's entry type) while the census lays it
+    // out from its pushes, the union of the two attribute `toJSON` records.
+    // Two carriers for one array, and an array cannot be converted in place.
+    // State the element three's attribute `toJSON`s state: `Object`.
+    transformed = replaceOne(
+      transformed,
+      "\t\t\tconst attributeArray = this.morphAttributes[ key ];\n\n\t\t\tconst array = [];",
+      "\t\t\tconst attributeArray = this.morphAttributes[ key ];\n\n\t\t\t/** @type {Array<Object>} */\n\t\t\tconst array = [];",
+      fileName,
+      "BufferGeometry.toJSON morph entry array",
+    );
+    // `JSON.stringify` on a declared-any value keeps every `toJSON` (see
+    // Object3D's envelope), so this envelope is published to dynamic code,
+    // which may write any of its fields. Laid out from the body, its `data`
+    // field is the record `data.data = { attributes: {} }` and the writes
+    // after it build, and a dynamic value has no reader into that record.
+    // State the envelope, with `data` left `Object` as Object3D's `object`
+    // is: the body fills it key by key. The index signature is the
+    // parameters branch, which copies each parameter in by name.
+    transformed = replaceOne(
+      transformed,
+      "\t * @return {Object} A JSON object representing the serialized geometry.\n\t */\n\ttoJSON() {\n\n\t\tconst data = {",
+      `\t * @return {${nativeBufferGeometryJSONType}} A JSON object representing the serialized geometry.\n\t */\n\ttoJSON() {\n\n\t\t/** @type {${nativeBufferGeometryJSONType}} */\n\t\tconst data = {`,
+      fileName,
+      "BufferGeometry.toJSON envelope",
+    );
     transformed = replaceOne(
       transformed,
       `\tgetAttribute( name ) {
@@ -5455,6 +5554,18 @@ function requireWebGLStateTextureImageSource( value ) {
       fileName,
       "WebGLBindingStates interleaved attribute import",
     );
+    // The binding-state fast paths below test `object instanceof InstancedMesh`; three's own
+    // file reads `object.isInstancedMesh` and imports no InstancedMesh. An app that patches
+    // three on disk may have added the import already.
+    if (!transformed.includes("import { InstancedMesh } from '../../objects/InstancedMesh.js';")) {
+      transformed = replaceOne(
+        transformed,
+        "import { IntType } from '../../constants.js';",
+        "import { IntType } from '../../constants.js';\nimport { InstancedMesh } from '../../objects/InstancedMesh.js';",
+        fileName,
+        "WebGLBindingStates instanced mesh import",
+      );
+    }
     transformed = replaceOne(
       transformed,
       "\t\t\tif ( index !== null ) {\n\n\t\t\t\tgl.bindBuffer( gl.ELEMENT_ARRAY_BUFFER, attributes.get( index ).buffer );",
@@ -5641,7 +5752,7 @@ function requireWebGLStateTextureImageSource( value ) {
     transformed = replaceOne(
       transformed,
       "\tfunction get( scene, renderCallDepth ) {",
-      "\t/** @param {import('../../scenes/Scene.js').Scene} scene @param {number} renderCallDepth */\n\tfunction get( scene, renderCallDepth ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene @param {number} renderCallDepth */\n\tfunction get( scene, renderCallDepth ) {",
       fileName,
       "WebGLRenderLists lookup inputs",
     );
@@ -6373,7 +6484,10 @@ function WebGLShadowMap( renderer, objects, capabilities ) {`,
     transformed = replaceOne(
       transformed,
       "this.render = function ( lights, scene, camera ) {",
-      "this.render = /** @this {WebGLShadowMap} @param {Array<import('../../lights/Light.js').Light>} lights */ function ( lights, scene, camera ) {",
+      // `scene` is the root WebGLRenderer.render was handed, any Object3D;
+      // the body only traverses it. This inline block outranks the
+      // declaration overlay's `@param {Scene} scene` above the assignment.
+      "this.render = /** @this {WebGLShadowMap} @param {Array<import('../../lights/Light.js').Light>} lights @param {import('../../core/Object3D.js').Object3D} scene */ function ( lights, scene, camera ) {",
       fileName,
       "WebGLShadowMap.render receiver",
     );
@@ -6741,21 +6855,21 @@ class WebGLBackgroundPlaneMaterial extends ShaderMaterial {
     transformed = replaceOne(
       transformed,
       "\tfunction getBackground( scene ) {",
-      "\t/** @param {Scene} scene */\n\tfunction getBackground( scene ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene */\n\tfunction getBackground( scene ) {",
       fileName,
       "WebGLBackground background scene input",
     );
     transformed = replaceOne(
       transformed,
       "\tfunction render( scene ) {",
-      "\t/** @param {Scene} scene */\n\tfunction render( scene ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene */\n\tfunction render( scene ) {",
       fileName,
       "WebGLBackground scene input",
     );
     transformed = replaceOne(
       transformed,
       "\tfunction addToRenderList( renderList, scene ) {",
-      "\t/** @param {Scene} scene */\n\tfunction addToRenderList( renderList, scene ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene */\n\tfunction addToRenderList( renderList, scene ) {",
       fileName,
       "WebGLBackground render-list scene input",
     );
@@ -7092,6 +7206,15 @@ class WebGLBackgroundPlaneMaterial extends ShaderMaterial {
       backgroundRotation: "uniformMatrix3",
       uvTransform: "uniformMatrix3",
     });
+    // The renderer renders any Object3D (WebGLRenderer.render states
+    // `@param {Object3D} scene`), so the scene inputs above state Object3D.
+    // Only a Scene has a background: each read sits behind
+    // `scene.isScene === true`, or behind a background only a Scene yields,
+    // and names the Scene it reads.
+    transformed = transformed.replaceAll(
+      "scene.background",
+      "/** @type {Scene} */ ( scene ).background",
+    );
   }
   if (normalized.endsWith("/three/src/renderers/shaders/UniformsLib.js")) {
     transformed = transformUniformsLib(transformed, fileName, replaceOne);
@@ -8511,17 +8634,6 @@ function WebGLProperties() {
 
 \t}
 
-\t/**
-\t * @param {WebGLPropertyOwner} object
-\t * @param {keyof NativeWebGLPropertyBag} key
-\t * @param {NativeWebGLPropertyBag[keyof NativeWebGLPropertyBag]} value
-\t */
-\tfunction update( object, key, value ) {
-
-\t\tget( object )[ key ] = value;
-
-\t}
-
 \tfunction dispose() {
 
 \t\tmaterials.clear();
@@ -8533,7 +8645,12 @@ function WebGLProperties() {
 
 \t}
 
-\treturn { has, get, remove, update, dispose };
+\t// Three's \`update( object, key, value )\` is left out: nothing in three
+\t// calls it, and its \`get( object )[ key ] = value\` stores a union of every
+\t// slot's type into the one slot \`key\` names. TypeScript rejects that store
+\t// (the target is \`never\`), and geatsc certifies no conversion from the
+\t// union into a single slot, so the C++ emitter refused the body.
+\treturn { has, get, remove, dispose };
 
 }
 
@@ -9238,7 +9355,7 @@ function WebGLRenderState( extensions ) {`,
     transformed = replaceOne(
       transformed,
       "\tfunction get( scene, renderCallDepth = 0 ) {",
-      "\t/** @param {import('../../scenes/Scene.js').Scene} scene @param {number} [renderCallDepth=0] */\n\tfunction get( scene, renderCallDepth = 0 ) {",
+      "\t/** @param {import('../../core/Object3D.js').Object3D} scene @param {number} [renderCallDepth=0] */\n\tfunction get( scene, renderCallDepth = 0 ) {",
       fileName,
       "WebGLRenderStates lookup inputs",
     );

package/native/angle_webgl_host.mm

@@ -1,4 +1,13 @@
 #include "webgl_readback.h"
+#if defined(_WIN32)
+// The EGL and OpenGL ES libraries the Windows host loads beside the executable.
+#ifndef GEA_WEBGL_EGL_LIBRARY
+#define GEA_WEBGL_EGL_LIBRARY "libEGL.dll"
+#endif
+#ifndef GEA_WEBGL_GLES_LIBRARY
+#define GEA_WEBGL_GLES_LIBRARY "libGLESv2.dll"
+#endif
+#endif
 // GEA_WEBGL_STATIC_GLES: EGL/GLES are statically linked into the program, so
 // nothing is loaded and entry points resolve through eglGetProcAddress.
 #if defined(_WIN32)
@@ -319,6 +328,7 @@ static constexpr GLenum GL_UNSIGNED_INT = 0x1405;
 static constexpr GLenum GL_RGBA_VALUE = 0x1908;
 static constexpr GLenum GL_VIEWPORT_VALUE = 0x0BA2;
 static constexpr GLenum GL_FRAMEBUFFER_BINDING_VALUE = 0x8CA6;
+static constexpr GLenum GL_INFO_LOG_LENGTH_VALUE = 0x8B84;
 
 using PFNEGLGETPROCADDRESS = void *(*)(const char *);
 using PFNEGLGETPLATFORMDISPLAYEXTPROC = EGLDisplay (*)(EGLenum, void *, const EGLint *);
@@ -393,6 +403,7 @@ using PFNGLGETINTEGERVPROC = void (*)(GLenum, GLint *);
 using PFNGLGETPROGRAMIVPROC = void (*)(GLuint, GLenum, GLint *);
 using PFNGLGETSHADERIVPROC = void (*)(GLuint, GLenum, GLint *);
 using PFNGLGETSHADERINFOLOGPROC = void (*)(GLuint, GLsizei, GLsizei *, GLchar *);
+using PFNGLGETPROGRAMINFOLOGPROC = void (*)(GLuint, GLsizei, GLsizei *, GLchar *);
 using PFNGLGETSTRINGPROC = const unsigned char *(*)(GLenum);
 using PFNGLGETUNIFORMLOCATIONPROC = GLint (*)(GLuint, const GLchar *);
 using PFNGLLINEWIDTHPROC = void (*)(GLfloat);
@@ -540,6 +551,7 @@ struct AngleWebGLState {
   PFNGLGETPROGRAMIVPROC glGetProgramiv = nullptr;
   PFNGLGETSHADERIVPROC glGetShaderiv = nullptr;
   PFNGLGETSHADERINFOLOGPROC glGetShaderInfoLog = nullptr;
+  PFNGLGETPROGRAMINFOLOGPROC glGetProgramInfoLog = nullptr;
   PFNGLGETSTRINGPROC glGetString = nullptr;
   PFNGLGETUNIFORMLOCATIONPROC glGetUniformLocation = nullptr;
   PFNGLLINEWIDTHPROC glLineWidth = nullptr;
@@ -618,6 +630,10 @@ struct AngleWebGLState {
 };
 
 static AngleWebGLState gWebGL;
+// Vertical sync as the program chose it (nativeWebGLSetVsync): 1 on, 0 off, -1 not chosen
+// (then GEA_ANGLE_SWAP_INTERVAL, else 0; see makeCurrent).
+static int gVsyncChoice = -1;
+extern "C" void gea_three_webgl_set_vsync(double on) { gVsyncChoice = on != 0 ? 1 : 0; }
 static GLenum hostReadbackError = 0;
 static std::chrono::steady_clock::time_point gProfileSizeSync;
 static bool gProfileSizeSyncPending = false;
@@ -933,9 +949,19 @@ static bool makeCurrent(const char *label) {
   // reintroduced because the layer still syncs its own present.
   // `GEA_ANGLE_SWAP_INTERVAL` overrides it (set `1` to restore the old
   // double-paced behaviour) so both arms can be measured from one binary.
+  // A program's choice (nativeWebGLSetVsync) wins: off is interval 0; on is
+  // interval 1 where nothing else paces the frames (a desktop window with no
+  // display link), and the default above on Apple platforms, where the display
+  // link and the layer's own sync already do.
   if (gWebGL.eglSwapInterval) {
     const char *requested = std::getenv("GEA_ANGLE_SWAP_INTERVAL");
-    const EGLint interval = requested ? static_cast<EGLint>(std::atoi(requested)) : 0;
+    const EGLint fallback = requested ? static_cast<EGLint>(std::atoi(requested)) : 0;
+#if defined(__APPLE__)
+    const EGLint paced = fallback;
+#else
+    const EGLint paced = 1;
+#endif
+    const EGLint interval = gVsyncChoice == 0 ? 0 : gVsyncChoice == 1 ? paced : fallback;
     gWebGL.eglSwapInterval(gWebGL.display, interval);
   }
   if (gWebGL.eglMakeCurrent(gWebGL.display, gWebGL.surface, gWebGL.surface, gWebGL.context) == EGL_FALSE_VALUE) {
@@ -1060,6 +1086,7 @@ static bool loadGlSymbols() {
   LOAD_GL(glGetProgramiv, PFNGLGETPROGRAMIVPROC)
   LOAD_GL(glGetShaderiv, PFNGLGETSHADERIVPROC)
   LOAD_GL(glGetShaderInfoLog, PFNGLGETSHADERINFOLOGPROC)
+  LOAD_GL(glGetProgramInfoLog, PFNGLGETPROGRAMINFOLOGPROC)
   LOAD_GL(glGetString, PFNGLGETSTRINGPROC)
   LOAD_GL(glGetUniformLocation, PFNGLGETUNIFORMLOCATIONPROC)
   LOAD_GL(glLineWidth, PFNGLLINEWIDTHPROC)
@@ -1151,22 +1178,42 @@ extern "C" bool gea_three_webgl_attach(
   gWebGL.egl = &staticGles;
   gWebGL.gles = &staticGles;
 #elif defined(_WIN32)
-  // An override (e.g. threejs-rendozer's GeaRendozerGLES.dll) first, then the
-  // packaged ANGLE of a UWP app, then a plain desktop load next to the exe.
-  auto openWin32 = [](const wchar_t *overrideEnv, const wchar_t *name) -> HMODULE {
+  // An override path from the environment first, then the packaged library of
+  // a UWP app, then the file beside the executable. The file names default to
+  // ANGLE's; a build that stages another EGL/GLES implementation names its
+  // files through GEA_WEBGL_EGL_LIBRARY / GEA_WEBGL_GLES_LIBRARY (paths
+  // relative to the executable's directory; one DLL may implement both).
+  auto openWin32 = [](const wchar_t *overrideEnv, const char *name) -> HMODULE {
     wchar_t overridePath[MAX_PATH];
     const DWORD n = GetEnvironmentVariableW(overrideEnv, overridePath, MAX_PATH);
     if (n > 0 && n < MAX_PATH) {
       if (HMODULE m = LoadLibraryW(overridePath)) return m;
+      smokeLog("[native-webgl-angle] %ls names a library that does not load (error %lu)", overrideEnv, GetLastError());
     }
+    std::wstring file;
+    for (const char *c = name; *c; ++c) file.push_back(*c == '/' ? L'\\' : static_cast<wchar_t>(static_cast<unsigned char>(*c)));
 #if defined(WINAPI_FAMILY) && WINAPI_FAMILY == WINAPI_FAMILY_APP
-    return LoadPackagedLibrary(name, 0);
+    return LoadPackagedLibrary(file.c_str(), 0);
 #else
-    return LoadLibraryW(name);
+    wchar_t module[MAX_PATH] = {};
+    const DWORD length = GetModuleFileNameW(nullptr, module, MAX_PATH);
+    std::wstring beside(module, length < MAX_PATH ? length : 0);
+    const size_t slash = beside.find_last_of(L"\\/");
+    if (slash != std::wstring::npos) {
+      beside.resize(slash + 1);
+      beside += file;
+      // Altered search path: the library's own dependencies resolve from its directory.
+      if (HMODULE m = LoadLibraryExW(beside.c_str(), nullptr, LOAD_WITH_ALTERED_SEARCH_PATH)) return m;
+    }
+    return LoadLibraryW(file.c_str());
 #endif
   };
-  gWebGL.egl = openWin32(L"GEA_ANGLE_EGL_DYLIB", L"libEGL.dll");
-  gWebGL.gles = openWin32(L"GEA_ANGLE_GLES_DYLIB", L"libGLESv2.dll");
+  gWebGL.egl = openWin32(L"GEA_ANGLE_EGL_DYLIB", GEA_WEBGL_EGL_LIBRARY);
+  gWebGL.gles = openWin32(L"GEA_ANGLE_GLES_DYLIB", GEA_WEBGL_GLES_LIBRARY);
+  if (!gWebGL.egl || !gWebGL.gles) {
+    smokeLog("[native-webgl-angle] EGL/GLES implementation not found: %s and %s beside the executable "
+             "(GEA_ANGLE_EGL_DYLIB / GEA_ANGLE_GLES_DYLIB override them)", GEA_WEBGL_EGL_LIBRARY, GEA_WEBGL_GLES_LIBRARY);
+  }
 #elif defined(__APPLE__)
   static const char *const eglPaths[] = {
     "/Applications/Visual Studio Code.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Libraries/libEGL.dylib",
@@ -2017,6 +2064,28 @@ extern "C" double gea_three_webgl_get_program_parameter(double program, double p
   gWebGL.glGetProgramiv(asGLuint(program), asGLenum(pname), &value);
   return value;
 }
+// The driver's compile or link log, as WebGL's getShaderInfoLog and
+// getProgramInfoLog return it.
+static std::string geaInfoLog(double object, PFNGLGETSHADERIVPROC queryLength, PFNGLGETSHADERINFOLOGPROC readLog) {
+  GLint length = 0;
+  queryLength(asGLuint(object), GL_INFO_LOG_LENGTH_VALUE, &length);
+  if (length <= 0) return std::string();
+  std::string log(static_cast<std::size_t>(length), '\0');
+  GLsizei written = 0;
+  readLog(asGLuint(object), length, &written, log.data());
+  log.resize(static_cast<std::size_t>(std::clamp(written, 0, length)));
+  return log;
+}
+extern "C" std::string gea_three_webgl_get_shader_info_log(double shader) {
+  geaTrapCheck("gea_three_webgl_get_shader_info_log");
+  if (!ensureWebGLCurrent("getShaderInfoLog")) return std::string();
+  return geaInfoLog(shader, gWebGL.glGetShaderiv, gWebGL.glGetShaderInfoLog);
+}
+extern "C" std::string gea_three_webgl_get_program_info_log(double program) {
+  geaTrapCheck("gea_three_webgl_get_program_info_log");
+  if (!ensureWebGLCurrent("getProgramInfoLog")) return std::string();
+  return geaInfoLog(program, gWebGL.glGetProgramiv, gWebGL.glGetProgramInfoLog);
+}
 extern "C" void gea_three_webgl_delete_program(double program) {
   geaTrapCheck("gea_three_webgl_delete_program"); GEA_WEBGL_VOID("deleteProgram"); gWebGL.glDeleteProgram(asGLuint(program)); }
 extern "C" void gea_three_webgl_use_program(double program) {

package/native/audio_host.mm

@@ -21,6 +21,9 @@
 #if defined(_WIN32)
 #define _USE_MATH_DEFINES
 #include "audio_uwp.h"
+// Legacy Win16 macros are not C++ identifiers and must not leak into the runtime.
+#undef near
+#undef far
 #else
 #import <AVFoundation/AVFoundation.h>
 #import <Foundation/Foundation.h>
@@ -44,8 +47,30 @@
 
 #if defined(_WIN32)
 static std::wstring geaAudioAssetDirectory;
+static bool geaAudioAssetDirectorySet = false;
 extern "C" void gea_three_audio_set_directory_uwp(const wchar_t *path) {
   geaAudioAssetDirectory = path ? path : L"";
+  geaAudioAssetDirectorySet = true;
+}
+// Without a driver naming the directory: GEA_THREE_AUDIO_DIR, else the
+// Resources\Sounds folder beside the executable (where the desktop target
+// stages an app's sounds), matching the macOS host's bundle lookup.
+static const std::wstring &geaAudioDirectory() {
+  if (!geaAudioAssetDirectorySet) {
+    geaAudioAssetDirectorySet = true;
+    wchar_t value[MAX_PATH] = {};
+    const DWORD n = GetEnvironmentVariableW(L"GEA_THREE_AUDIO_DIR", value, MAX_PATH);
+    if (n > 0 && n < MAX_PATH) {
+      geaAudioAssetDirectory = value;
+    } else {
+      wchar_t module[MAX_PATH] = {};
+      const DWORD length = GetModuleFileNameW(nullptr, module, MAX_PATH);
+      std::wstring directory(module, length < MAX_PATH ? length : 0);
+      const size_t slash = directory.find_last_of(L"\\/");
+      if (slash != std::wstring::npos) geaAudioAssetDirectory = directory.substr(0, slash) + L"\\Resources\\Sounds";
+    }
+  }
+  return geaAudioAssetDirectory;
 }
 #endif
 
@@ -427,7 +452,7 @@ struct GeaAudioEngine {
   long loadBufferFile(const std::string &name) {
     if (name.empty() || name.find('/') != std::string::npos || name.find("..") != std::string::npos) return 0;
 #if defined(_WIN32)
-    if (name.find('\\') != std::string::npos || geaAudioAssetDirectory.empty()) return 0;
+    if (name.find('\\') != std::string::npos || geaAudioDirectory().empty()) return 0;
     const int length = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, name.data(), static_cast<int>(name.size()), nullptr, 0);
     if (length <= 0) return 0;
     std::wstring base(static_cast<size_t>(length), L'\0');

package/native/resource_host.mm

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// Files an app ships in its Resources folder, read whole into a typed array the
+// program allocated (src/nativeResources.ts). Resources is the app bundle's
+// resource directory on macOS and iOS, and the Resources folder beside the
+// executable elsewhere (where the desktop targets stage an app's
+// nativeResources); GEA_RESOURCE_DIR names another directory.
+//
+// A name is relative to that directory, with '/' between its parts; an
+// absolute name, a backslash or a '..' part is refused, so a name never reaches
+// outside it.
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <string>
+
+#if defined(_WIN32)
+#include <windows.h>
+#elif defined(__APPLE__)
+#import <Foundation/Foundation.h>
+#else
+#include <unistd.h>
+#include <climits>
+#endif
+
+namespace {
+
+bool geaResourceNameValid(const std::string &name) {
+  if (name.empty() || name.front() == '/' || name.find('\\') != std::string::npos || name.find(':') != std::string::npos) return false;
+  size_t start = 0;
+  while (start <= name.size()) {
+    const size_t end = name.find('/', start);
+    const std::string part = name.substr(start, end == std::string::npos ? std::string::npos : end - start);
+    if (part.empty() || part == "." || part == "..") return false;
+    if (end == std::string::npos) break;
+    start = end + 1;
+  }
+  return true;
+}
+
+#if defined(_WIN32)
+const std::wstring &geaResourceDirectory() {
+  static const std::wstring directory = [] {
+    wchar_t value[MAX_PATH] = {};
+    const DWORD n = GetEnvironmentVariableW(L"GEA_RESOURCE_DIR", value, MAX_PATH);
+    if (n > 0 && n < MAX_PATH) return std::wstring(value);
+    wchar_t module[MAX_PATH] = {};
+    const DWORD length = GetModuleFileNameW(nullptr, module, MAX_PATH);
+    std::wstring path(module, length < MAX_PATH ? length : 0);
+    const size_t slash = path.find_last_of(L"\\/");
+    return slash == std::wstring::npos ? std::wstring() : path.substr(0, slash) + L"\\Resources";
+  }();
+  return directory;
+}
+
+FILE *geaOpenResource(const std::string &name) {
+  if (!geaResourceNameValid(name) || geaResourceDirectory().empty()) return nullptr;
+  const int length = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, name.data(), static_cast<int>(name.size()), nullptr, 0);
+  if (length <= 0) return nullptr;
+  std::wstring relative(static_cast<size_t>(length), L'\0');
+  MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, name.data(), static_cast<int>(name.size()), relative.data(), length);
+  for (wchar_t &c : relative) if (c == L'/') c = L'\\';
+  FILE *file = nullptr;
+  return _wfopen_s(&file, (geaResourceDirectory() + L"\\" + relative).c_str(), L"rb") == 0 ? file : nullptr;
+}
+#else
+const std::string &geaResourceDirectory() {
+  static const std::string directory = [] {
+    if (const char *value = std::getenv("GEA_RESOURCE_DIR")) return std::string(value);
+#if defined(__APPLE__)
+    @autoreleasepool {
+      NSString *resources = [[NSBundle mainBundle] resourcePath];
+      return resources ? std::string(resources.UTF8String) : std::string();
+    }
+#else
+    char path[PATH_MAX] = {};
+    const ssize_t length = readlink("/proc/self/exe", path, sizeof(path) - 1);
+    if (length <= 0) return std::string();
+    const std::string executable(path, static_cast<size_t>(length));
+    const size_t slash = executable.find_last_of('/');
+    return slash == std::string::npos ? std::string() : executable.substr(0, slash) + "/Resources";
+#endif
+  }();
+  return directory;
+}
+
+FILE *geaOpenResource(const std::string &name) {
+  if (!geaResourceNameValid(name) || geaResourceDirectory().empty()) return nullptr;
+  return std::fopen((geaResourceDirectory() + "/" + name).c_str(), "rb");
+}
+#endif
+
+long long geaResourceLength(FILE *file) {
+  if (std::fseek(file, 0, SEEK_END) != 0) return -1;
+#if defined(_WIN32)
+  const long long length = _ftelli64(file);
+#else
+  const long long length = static_cast<long long>(ftello(file));
+#endif
+  if (length < 0 || std::fseek(file, 0, SEEK_SET) != 0) return -1;
+  return length;
+}
+
+}  // namespace
+
+// The file's size in bytes, or -1 when it is missing or the name is refused.
+extern "C" double gea_three_resource_size(std::string name) {
+  FILE *file = geaOpenResource(name);
+  if (!file) return -1;
+  const long long length = geaResourceLength(file);
+  std::fclose(file);
+  return static_cast<double>(length);
+}
+
+// Reads the whole file into `bytes` when it holds exactly `byteLength` bytes.
+// Answers the bytes read, or -1 (missing file, refused name, other size, short read).
+extern "C" double gea_three_resource_read_bytes(std::string name, void *bytes, double byteLength) {
+  if (!bytes && byteLength != 0) return -1;
+  FILE *file = geaOpenResource(name);
+  if (!file) return -1;
+  const long long length = geaResourceLength(file);
+  double result = -1;
+  if (length >= 0 && static_cast<double>(length) == byteLength) {
+    const size_t wanted = static_cast<size_t>(length);
+    if (wanted == 0 || std::fread(bytes, 1, wanted, file) == wanted) result = static_cast<double>(length);
+  }
+  std::fclose(file);
+  return result;
+}

package/native/win32_webgl_surface.cpp

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: Apache-2.0
+// The WebGL surface of a Windows desktop build: a child window filling the
+// main window's content area, which the native WebGL host renders into, and
+// the input the host reports to the program.
+//
+// It plugs into the Windows target as a host extension (gea_win32_host.h):
+// the target attaches it before the program's top level runs -- the program
+// creates its WebGL context while it initializes -- and brackets the
+// initialization and every frame with begin/end, which is when the host's
+// EGL context is current. Keys reach the host as macOS virtual key codes, the
+// code space the program's key polling uses on every platform; pointer
+// positions are in CSS pixels of the surface.
+#include "gea_win32_host.h"
+
+#include <windowsx.h>
+
+#include <algorithm>
+#include <cstdio>
+#include <cstdlib>
+
+extern "C" bool gea_three_webgl_attach_uwp(void *nativeWindow, double width, double height, double devicePixelRatio);
+extern "C" void gea_three_webgl_update_size_uwp(double width, double height, double devicePixelRatio);
+extern "C" bool gea_three_webgl_begin_frame_uwp();
+extern "C" void gea_three_webgl_end_frame_uwp();
+extern "C" void gea_three_set_key_state(int code, bool down);
+extern "C" void gea_three_set_pointer_state(double x, double y, double width, double height, bool down);
+
+namespace {
+
+HWND gSurface = nullptr;
+HWND gMainWindow = nullptr;
+double gScale = 1.0;
+bool gPointerDown = false;
+// The program polls key state once per frame, so a tap whose key-down and
+// key-up both arrive between two frames would never be seen. A release waits
+// here until a frame has run with the key down.
+bool gReleasePending[256] = {};
+
+// macOS virtual key codes (Carbon kVK_*), for the keys a game typically polls.
+int macKeyCode(WPARAM vk)
+{
+	switch (vk) {
+	case VK_LEFT: return 123;
+	case VK_RIGHT: return 124;
+	case VK_DOWN: return 125;
+	case VK_UP: return 126;
+	case VK_SPACE: return 49;
+	case VK_RETURN: return 36;
+	case VK_ESCAPE: return 53;
+	case VK_TAB: return 48;
+	case VK_BACK: return 51;
+	case VK_DELETE: return 117;
+	case VK_HOME: return 115;
+	case VK_END: return 119;
+	case VK_PRIOR: return 116;
+	case VK_NEXT: return 121;
+	case VK_SHIFT: case VK_LSHIFT: return 56;
+	case VK_RSHIFT: return 60;
+	case VK_CONTROL: case VK_LCONTROL: return 59;
+	case VK_RCONTROL: return 62;
+	case VK_MENU: case VK_LMENU: return 58;
+	case VK_RMENU: return 61;
+	case VK_OEM_MINUS: return 27;
+	case VK_OEM_PLUS: return 24;
+	case VK_OEM_COMMA: return 43;
+	case VK_OEM_PERIOD: return 47;
+	case VK_OEM_1: return 41;   // ;
+	case VK_OEM_2: return 44;   // /
+	case VK_OEM_3: return 50;   // `
+	case VK_OEM_4: return 33;   // [
+	case VK_OEM_5: return 42;   // backslash
+	case VK_OEM_6: return 30;   // ]
+	case VK_OEM_7: return 39;   // '
+	default: break;
+	}
+	static const int letters[26] = {0, 11, 8, 2, 14, 3, 5, 4, 34, 38, 40, 37, 46, 45, 31, 35, 12, 15, 1, 17, 32, 9, 13, 7, 16, 6};
+	if (vk >= 'A' && vk <= 'Z') return letters[vk - 'A'];
+	static const int digits[10] = {29, 18, 19, 20, 21, 23, 22, 26, 28, 25};
+	if (vk >= '0' && vk <= '9') return digits[vk - '0'];
+	static const int functions[12] = {122, 120, 99, 118, 96, 97, 98, 100, 101, 109, 103, 111};
+	if (vk >= VK_F1 && vk <= VK_F12) return functions[vk - VK_F1];
+	return -1;
+}
+
+void releaseAllKeys()
+{
+	for (int code = 0; code < 256; ++code) {
+		gReleasePending[code] = false;
+		gea_three_set_key_state(code, false);
+	}
+}
+
+void reportPointer(LPARAM lParam)
+{
+	RECT client{};
+	GetClientRect(gSurface, &client);
+	gea_three_set_pointer_state(GET_X_LPARAM(lParam) / gScale, GET_Y_LPARAM(lParam) / gScale, std::max<LONG>(1, client.right) / gScale,
+	                            std::max<LONG>(1, client.bottom) / gScale, gPointerDown);
+}
+
+LRESULT CALLBACK surfaceProc(HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
+{
+	switch (message) {
+	case WM_KEYDOWN:
+	case WM_SYSKEYDOWN:
+		if (message == WM_SYSKEYDOWN && wParam == VK_F4) break;  // Alt+F4 closes the window
+		if (const int code = macKeyCode(wParam); code >= 0) {
+			gReleasePending[code] = false;
+			gea_three_set_key_state(code, true);
+		}
+		return 0;  // no menu activation on Alt or F10
+	case WM_KEYUP:
+	case WM_SYSKEYUP:
+		if (const int code = macKeyCode(wParam); code >= 0) gReleasePending[code] = true;
+		return 0;
+	case WM_SYSCHAR:
+		return 0;  // no beep for Alt+key
+	case WM_KILLFOCUS:
+		gPointerDown = false;
+		ReleaseCapture();
+		releaseAllKeys();
+		return 0;
+	case WM_LBUTTONDOWN:
+		SetFocus(hwnd);
+		gPointerDown = true;
+		SetCapture(hwnd);
+		reportPointer(lParam);
+		return 0;
+	case WM_LBUTTONUP:
+		gPointerDown = false;
+		ReleaseCapture();
+		reportPointer(lParam);
+		return 0;
+	case WM_MOUSEMOVE:
+		reportPointer(lParam);
+		return 0;
+	case WM_ERASEBKGND:
+		return 1;  // the swap chain owns every pixel
+	case WM_PAINT:
+		ValidateRect(hwnd, nullptr);
+		return 0;
+	default:
+		break;
+	}
+	return DefWindowProcW(hwnd, message, wParam, lParam);
+}
+
+int attach(HWND window, RECT area, double scale)
+{
+	gMainWindow = window;
+	gScale = scale > 0 ? scale : 1.0;
+	HINSTANCE instance = GetModuleHandleW(nullptr);
+	WNDCLASSEXW cls{};
+	cls.cbSize = sizeof(cls);
+	cls.style = CS_OWNDC | CS_DBLCLKS;
+	cls.lpfnWndProc = surfaceProc;
+	cls.hInstance = instance;
+	cls.hCursor = LoadCursorW(nullptr, IDC_ARROW);
+	cls.lpszClassName = L"GeaWebGLSurface";
+	RegisterClassExW(&cls);
+	// The main window must not paint over its swap-chain child.
+	SetWindowLongPtrW(window, GWL_STYLE, GetWindowLongPtrW(window, GWL_STYLE) | WS_CLIPCHILDREN);
+	const int width = std::max<int>(1, area.right - area.left);
+	const int height = std::max<int>(1, area.bottom - area.top);
+	gSurface = CreateWindowExW(0, cls.lpszClassName, L"", WS_CHILD | WS_VISIBLE | WS_CLIPSIBLINGS, area.left, area.top, width, height, window, nullptr,
+	                           instance, nullptr);
+	if (!gSurface) {
+		std::fprintf(stderr, "[native-webgl-angle] could not create the surface window (error %lu)\n", GetLastError());
+		return 0;
+	}
+	SetWindowPos(gSurface, HWND_TOP, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);
+	// Present with vsync unless the environment says otherwise.
+	if (!std::getenv("GEA_ANGLE_SWAP_INTERVAL")) _putenv_s("GEA_ANGLE_SWAP_INTERVAL", "1");
+	if (!gea_three_webgl_attach_uwp(gSurface, width, height, gScale)) {
+		std::fprintf(stderr, "[native-webgl-angle] the WebGL surface could not start: no usable EGL/OpenGL ES implementation\n");
+		return 0;
+	}
+	// eglSwapBuffers paces the loop: it waits for the refresh with vsync on and
+	// renders unthrottled with it off (GEA_ANGLE_SWAP_INTERVAL=0).
+	gea_win32_set_frame_pacing(GEA_WIN32_FRAME_PACING_PRESENT);
+	SetFocus(gSurface);
+	return 1;
+}
+
+void layout(RECT area, double scale)
+{
+	if (!gSurface) return;
+	gScale = scale > 0 ? scale : 1.0;
+	const int width = std::max<int>(1, area.right - area.left);
+	const int height = std::max<int>(1, area.bottom - area.top);
+	SetWindowPos(gSurface, nullptr, area.left, area.top, width, height, SWP_NOZORDER | SWP_NOACTIVATE);
+	gea_three_webgl_update_size_uwp(width, height, gScale);
+}
+
+int beginFrame() { return gea_three_webgl_begin_frame_uwp() ? 1 : 0; }
+
+void endFrame()
+{
+	gea_three_webgl_end_frame_uwp();
+	for (int code = 0; code < 256; ++code) {
+		if (!gReleasePending[code]) continue;
+		gReleasePending[code] = false;
+		gea_three_set_key_state(code, false);
+	}
+}
+
+int windowMessage(HWND, UINT message, WPARAM, LPARAM, LRESULT *result)
+{
+	// Activating the main window gives it the keyboard focus; the surface is
+	// where keys are read.
+	if (message == WM_SETFOCUS && gSurface) {
+		SetFocus(gSurface);
+		*result = 0;
+		return 1;
+	}
+	return 0;
+}
+
+void detach()
+{
+	if (gSurface) DestroyWindow(gSurface);
+	gSurface = nullptr;
+}
+
+const gea_win32_host_extension kSurfaceExtension = {
+	GEA_WIN32_HOST_EXTENSION_VERSION, "The WebGL surface", attach, layout, beginFrame, endFrame, windowMessage, detach,
+};
+const bool kRegistered = (gea_win32_register_host_extension(&kSurfaceExtension), true);
+
+}  // namespace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/native-webgl-angle",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Typed native WebGL compatibility layer backed by ANGLE/Metal",
   "license": "Apache-2.0",
   "repository": {
@@ -21,6 +21,7 @@
     "./nativeWebXRManager": "./src/nativeWebXRManager.ts",
     "./troika-three-text": "./src/troika-three-text.ts",
     "./inflate": "./src/inflate.ts",
+    "./nativeResources": "./src/nativeResources.ts",
     "./geatsc-plugin": "./geatsc-plugin.mjs",
     "./native/*": "./native/*",
     "./package.json": "./package.json",
@@ -28,7 +29,8 @@
     "./text/native-text-types": "./src/text/native-text-types.ts",
     "./geatsc-plugin-batched-probe": "./geatsc-plugin-batched-probe.mjs",
     "./test/batched-render-scene": "./test/batched-render-scene.ts",
-    "./test/auto-instanced-render-scene": "./test/auto-instanced-render-scene.ts"
+    "./test/auto-instanced-render-scene": "./test/auto-instanced-render-scene.ts",
+    "./gea-native.json": "./gea-native.json"
   },
   "files": [
     "src",
@@ -40,7 +42,8 @@
     "geatsc-plugin-batched-probe.mjs",
     "test/batched-render-scene.ts",
     "test/auto-instanced-render-scene.ts",
-    "geatsc-plugin-readback.mjs"
+    "geatsc-plugin-readback.mjs",
+    "gea-native.json"
   ],
   "publishConfig": {
     "access": "public",
@@ -51,7 +54,7 @@
     "test:host-effects": "node test/native-host-effects-contract.test.mjs",
     "test:allocation-contracts": "node test/render-sort-contract.test.mjs && node test/upload-array-contract.test.mjs && node test/draw-dispatch-contract.test.mjs && node test/native-upload-transport.test.mjs && node test/fixed-uniform-contract.test.mjs && node test/uniform-binding-contract.test.mjs && node test/buffer-streaming-contract.test.mjs",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "node test/native-blending-contract.test.mjs && node test/native-transform-contract.test.mjs && node test/troika-three-text.test.mjs && node test/typed-void-contract.test.mjs && node test/instancing-transport-contract.test.mjs && node test/automatic-instancing-contract.test.mjs && node test/jsdoc-fold-contract.test.mjs",
+    "test": "node test/native-blending-contract.test.mjs && node test/native-transform-contract.test.mjs && node test/troika-three-text.test.mjs && node test/typed-void-contract.test.mjs && node test/info-log-contract.test.mjs && node test/resource-host-contract.test.mjs && node test/instancing-transport-contract.test.mjs && node test/automatic-instancing-contract.test.mjs && node test/jsdoc-fold-contract.test.mjs && node test/gea-native-declaration.test.mjs",
     "test:package": "node --experimental-vm-modules test/package.test.mjs"
   },
   "dependencies": {

package/src/nativeResources.ts

@@ -0,0 +1,22 @@
+// Files the app ships in its Resources folder (native/resource_host.mm): the
+// app bundle's resource directory on macOS, the Resources folder beside the
+// executable elsewhere. Names are relative to it, with '/' between parts.
+
+/** @gea-host-inert Reads its argument and the file system only; never calls back into script. */
+declare function threeResourceSize(name: string): number
+/** @gea-host-typed-array-element-writes Stores the file's bytes into the destination typed array's elements only; no other property of any object, no callbacks. */
+declare function threeResourceRead(name: string, destination: Uint8Array): number
+
+/** The size in bytes of a file in Resources, or -1 when there is none. */
+export function nativeResourceSize(name: string): number {
+  return threeResourceSize(name)
+}
+
+/** Reads a whole file from Resources; throws when it is missing or cannot be read. */
+export function nativeReadResource(name: string): Uint8Array {
+  const size = threeResourceSize(name)
+  if (size < 0) throw new Error(`Missing resource: ${name}`)
+  const bytes = new Uint8Array(size)
+  if (threeResourceRead(name, bytes) !== size) throw new Error(`Could not read resource: ${name}`)
+  return bytes
+}

package/src/nativeWebGL.ts

@@ -59,7 +59,9 @@ import {
   nativeWebGLGetError,
   nativeWebGLGetActiveAttribInfo,
   nativeWebGLGetActiveUniformInfo,
+  nativeWebGLGetProgramInfoLog,
   nativeWebGLGetProgramParameter,
+  nativeWebGLGetShaderInfoLog,
   nativeWebGLGetShaderParameter,
   nativeWebGLGetUniformLocation,
   nativeWebGLHeight,
@@ -1036,7 +1038,7 @@ export class NativeWebGL2RenderingContext {
     if (pname === this.DELETE_STATUS) return false
     return nativeWebGLGetShaderParameter(nativeHandle(shader), pname) !== 0
   }
-  getShaderInfoLog(_shader: NativeHandle | null): string { return '' }
+  getShaderInfoLog(shader: NativeShader): string { return nativeWebGLGetShaderInfoLog(nativeHandle(shader)) }
   getShaderSource(shader: NativeShader): string { return shaderSourceFor(shader) }
   deleteShader(shader: NativeShader | null): void { if (shader) { shaderSourceByHandle.delete(nativeHandle(shader)); nativeWebGLDeleteShader(nativeHandle(shader)) } }
 
@@ -1065,7 +1067,7 @@ export class NativeWebGL2RenderingContext {
     if (pname === this.VALIDATE_STATUS) return true
     return nativeWebGLGetProgramParameter(nativeHandle(program), pname) !== 0
   }
-  getProgramInfoLog(_program: NativeProgram | null): string { return '' }
+  getProgramInfoLog(program: NativeProgram): string { return nativeWebGLGetProgramInfoLog(nativeHandle(program)) }
   deleteProgram(program: NativeProgram | null): void { if (program) { nativeWebGLDeleteProgram(nativeHandle(program)) } }
   validateProgram(_program: NativeProgram): void {}
   getAttachedShaders(program: NativeProgram): NativeShader[] { return program.shaders }

package/src/nativeWebGLHost.ts

@@ -35,6 +35,16 @@ export function nativeWebGLSwap(): void {
   threeWebGLSwap()
 }
 
+/**
+ * Vertical sync from the next frame on. Off presents at once, so the frame rate shows what
+ * a frame costs. On paces presents to the display: interval 1 where nothing else paces the
+ * frames (a desktop window with no display link), the host's own pacing on Apple platforms,
+ * where a second waiter would only make frames miss refreshes.
+ */
+export function nativeWebGLSetVsync(on: boolean): void {
+  threeWebGLSetVsync(on ? 1 : 0)
+}
+
 // GPU time-elapsed timers (GL_EXT_disjoint_timer_query): begin returns a timer id (0 when
 // unsupported), end closes the open timer, and result is the elapsed nanoseconds, or -1 while the
 // GPU has not finished it. A timer is released once its result has been read.
@@ -88,12 +98,14 @@ export function nativeWebGLCreateShader(type: number): number { return threeWebG
 export function nativeWebGLShaderSource(shader: number, source: string): void { threeWebGLShaderSource(shader, source) }
 export function nativeWebGLCompileShader(shader: number): void { threeWebGLCompileShader(shader) }
 export function nativeWebGLGetShaderParameter(shader: number, pname: number): number { return threeWebGLGetShaderParameter(shader, pname) }
+export function nativeWebGLGetShaderInfoLog(shader: number): string { return threeWebGLGetShaderInfoLog(shader) }
 export function nativeWebGLDeleteShader(shader: number): void { threeWebGLDeleteShader(shader) }
 
 export function nativeWebGLCreateProgram(): number { return threeWebGLCreateProgram() }
 export function nativeWebGLAttachShader(program: number, shader: number): void { threeWebGLAttachShader(program, shader) }
 export function nativeWebGLLinkProgram(program: number): void { threeWebGLLinkProgram(program) }
 export function nativeWebGLGetProgramParameter(program: number, pname: number): number { return threeWebGLGetProgramParameter(program, pname) }
+export function nativeWebGLGetProgramInfoLog(program: number): string { return threeWebGLGetProgramInfoLog(program) }
 export function nativeWebGLDeleteProgram(program: number): void { threeWebGLDeleteProgram(program) }
 export function nativeWebGLUseProgram(program: number): void { threeWebGLUseProgram(program) }
 export function nativeWebGLGetAttribLocation(program: number, name: string): number { return threeWebGLGetAttribLocation(program, name) }
@@ -187,6 +199,8 @@ declare function threeWebGLDevicePixelRatio(): number
 /** Lifecycle entry: presents the native surface and may run platform hooks; not an inert call. */
 declare function threeWebGLSwap(): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLSetVsync(on: number): void
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeAngleSmokeLog(message: string): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeKeyPressed(code: number): boolean
@@ -207,6 +221,8 @@ declare function threeWebGLCompileShader(shader: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLGetShaderParameter(shader: number, pname: number): number
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLGetShaderInfoLog(shader: number): string
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLDeleteShader(shader: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLCreateProgram(): number
@@ -217,6 +233,8 @@ declare function threeWebGLLinkProgram(program: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLGetProgramParameter(program: number, pname: number): number
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
+declare function threeWebGLGetProgramInfoLog(program: number): string
+/** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLDeleteProgram(program: number): void
 /** @gea-host-inert Native state only; retains no script references and invokes no script. */
 declare function threeWebGLUseProgram(program: number): void