@geastack/native-webgl-angle 0.1.8 → 0.1.9

package/README.md

@@ -1,7 +1,7 @@
 # Native WebGL ANGLE
 
 `@geastack/native-webgl-angle` owns the native WebGL compatibility layer used by
-the real Three.js macOS path.
+the Three.js macOS path.
 
 ## Installation
 
@@ -48,7 +48,7 @@ native/angle_webgl_host.mm
                          Objective-C++ ANGLE/Metal host implementation
 ```
 
-## Current Compromise
+## 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
@@ -63,7 +63,6 @@ opcode-style host functions. The intended end state is direct typed native
 methods and typed WebGL handles, with no `gea_cpp_value`/`gea_cpp_key` in the
 bridge hot path.
 
-
 ### Synchronous numeric uploads
 
 GL upload functions opt into `hostShims.hostNativeArrayFunctions`. The compiler
@@ -74,7 +73,7 @@ format and buffer/texture dispatch in `geatsc-plugin-uploads.mjs`.
 float/integer format, using inline storage through 16 elements and one heap
 allocation beyond that. Matching typed arrays retain and borrow their backing
 storage, preserving view offsets. Shared views use synchronized reads into an
-owned copy. Uniform arrays and buffer subranges no longer pass through a
+owned copy. Uniform arrays and buffer subranges are passed without a
 JavaScript number-array temporary. Sparse arrays fail closed.
 
 These hosts must consume the input synchronously without reentering JavaScript
@@ -85,8 +84,8 @@ when changing this ABI; unmarked hosts retain their original vector ABI.
 Profiling builds (`GEA_PROFILE_ALLOCATIONS` or `GEA_PROFILE_NATIVE_FRAMES`)
 aggregate native GL call scopes and scene-transform markers. The frame-only
 option requires defining the macro only for `angle_webgl_host.mm` and avoids
-allocation instrumentation. Their elapsed times include instrumentation and
-any driver wait; they are attribution data, not uninstrumented CPU speedups.
+allocation instrumentation. Elapsed times include instrumentation overhead and
+driver waits, so use them to attribute time, not as CPU timings.
 
 `GEA_WEBGL_TRAP`, `GEA_WEBGL_BLEND_DEBUG`, and `GEA_WEBGL_SHADOW_COLOR_AUDIT`
 are launch settings, cached on first use to avoid environment lookups in draw
@@ -105,10 +104,9 @@ storage. Removing a scalar or typed-array contract must restore conservative
 prototype taint in the test.
 
 View attachment, size synchronization and presentation remain outside that
-contract pending a separate lifecycle/reentry audit. A native function's name
-or numeric return type alone does not establish its effects. These contracts
-remove false opaque-call edges; they do not establish zero boxing for an
-application as a whole.
+contract pending a separate lifecycle/reentry audit. These contracts remove
+false opaque-call edges; they do not make an application as a whole free of
+boxing.
 
 `npm test` includes the native void-call regression. Three.js comes from this
 package's own `three` devDependency, so `npm install` here is enough; the
@@ -117,14 +115,12 @@ compiler comes from a checkout of
 `clang++` (or `CXX`) supplies ASan/UBSan. `GEATSC_COMPILER_ROOT` and
 `GEASTACK_ROOT` point at that checkout when it is not beside this repo.
 
-The test extracts Three.js's actual `bindVertexArrayObject` function before
-and after the plugin transform, then compiles each against the real native
-WebGL facade and host bridge. It checks certified direct calls, physical void
+The test extracts Three.js's `bindVertexArrayObject` function before and
+after the plugin transform, then compiles each against the native WebGL facade and host bridge. It checks certified direct calls, physical void
 results, absence of executable boxing, nullable handle forwarding, and the
 observable `undefined` return. Only the external GL functions are mocked for
 execution. Source fixtures stay in memory; the test executable uses the
-compiler's existing ignored build output. No archived compiler APIs or scratch
-directories are needed.
+compiler's existing ignored build output.
 
 ### Streaming diagnostics and uniform names
 
@@ -153,23 +149,21 @@ is cached; replacement, deletion and `needsUpdate` remain observable.
 `GEA_WEBGL_UNIFORM_BINDINGS=baseline` disables the new name classification and
 shadow setters for comparison with the previous implementation.
 `GEA_WEBGL_UNIFORM_NAMES=baseline` disables fixed-name renderer setters.
-An earlier explicit local ID snapshot increased allocations by discarding
-reusable native string capacity; this implementation does not repeat it.
 `npm run test:allocation-contracts` covers streaming, fixed uniforms and live
 uniform bindings. `node test/uniform-binding-native.test.mjs` additionally
-executes the actual lookup helpers under ASan/UBSan and requires no emitted
+executes the lookup helpers under ASan/UBSan and requires no emitted
 boxing.
 
 The experimental BatchedMesh adaptation remains separate from the standard
 plugin. `node test/batched-mesh-contract.test.mjs` checks its generic geometry,
 transform, color, resize and clone behavior. Clones receive independent texture
-sources and arrays. Native callback, clone and visibility checks now pass;
-the full ANGLE comparison also matches ordinary mesh pixels exactly. Without
+sources and arrays. Native callback, clone and visibility checks pass, and
+the full ANGLE comparison matches ordinary mesh pixels exactly. Without
 `WEBGL_multi_draw`, its fallback retains separate draw calls. See
 [the native validation record](test/BATCHED-MESH-NATIVE.md) for evidence.
 
 The separate `GEA_WEBGL_AUTO_INSTANCE=1` experiment groups adjacent compatible
-opaque meshes into actual instanced draws. It is disabled by default while
+opaque meshes into instanced draws. It is disabled by default while
 end-to-end validation and platform measurements continue. Its eligibility rules,
 fallbacks and validation commands are documented in
 [the instancing contract](test/INSTANCING.md). Both experiments are generic;
@@ -177,8 +171,8 @@ the plugin contains no application-specific batching logic.
 
 ## License
 
-Apache-2.0 (see `LICENSE`). Use it, change it, ship closed-source products on
-it, no strings attached. The only GeaStack code under a different license is
+Apache-2.0 (see `LICENSE`). You can ship closed-source products
+built on it. The only GeaStack code under a different license is
 the embedded board support (`targets` and `@geastack/chips`, GPL-3.0-only):
 shipping closed-source firmware through those needs a commercial license.
 Contact [contact@geastack.com](mailto:contact@geastack.com) for commercial terms, support and hosted builds.

package/geatsc-plugin.mjs

@@ -1719,6 +1719,31 @@ function ${name}( template, input ) {
 
 }`;
 
+/**
+ * `array.constructor.name` over the nine typed-array kinds, spelled as the
+ * `instanceof` dispatch the native typed-array carriers lower. A `.constructor`
+ * read off a sum of typed arrays names a class evaluation no carrier holds.
+ */
+export const nativeTypedArrayName = `/**
+ * @param {${nativeTypedArrayType}} array
+ * @return {string}
+ */
+function typedArrayTypeName( array ) {
+
+\tif ( array instanceof Int8Array ) return 'Int8Array';
+\tif ( array instanceof Uint8Array ) return 'Uint8Array';
+\tif ( array instanceof Uint8ClampedArray ) return 'Uint8ClampedArray';
+\tif ( array instanceof Int16Array ) return 'Int16Array';
+\tif ( array instanceof Uint16Array ) return 'Uint16Array';
+\tif ( array instanceof Int32Array ) return 'Int32Array';
+\tif ( array instanceof Uint32Array ) return 'Uint32Array';
+\tif ( array instanceof Float32Array ) return 'Float32Array';
+\tif ( array instanceof Float64Array ) return 'Float64Array';
+
+\tthrow new Error( 'Unsupported typed array.' );
+
+}`;
+
 const replaceOne = (text, before, after, fileName, description) => {
   if (!text.includes(before))
     throw new Error(
@@ -3292,6 +3317,17 @@ function createColorManagement() {`,
       fileName,
       "ColorManagement typed built-in definitions close",
     );
+    // `define` merges a table of definitions into `spaces`. An untyped
+    // parameter is `any`, which made `Object.assign( this.spaces, colorSpaces )`
+    // copy a dynamic object into a typed dictionary; stating the table's type
+    // is what every caller already passes.
+    transformed = replaceOne(
+      transformed,
+      "\t\tdefine: function ( colorSpaces ) {",
+      "\t\t/** @param {Record<string, NativeColorSpaceDefinition>} colorSpaces */\n\t\tdefine: function ( colorSpaces ) {",
+      fileName,
+      "ColorManagement.define parameter type",
+    );
     const propertyFunction = /^(\s*)([A-Za-z_$][A-Za-z0-9_$]*): function \(/gm;
     const matches = transformed.match(propertyFunction)?.length ?? 0;
     if (matches !== 13)
@@ -3427,6 +3463,8 @@ function createColorManagement() {`,
       "class BufferGeometry extends EventDispatcher {",
       `${nativeTypedArrayFactory("createTypedArrayWithLength", "number")}
 
+${nativeTypedArrayName}
+
 /** @param {BufferAttribute|InterleavedBufferAttribute} attribute @param {number} index @param {number} x @param {number} y @param {number} z */
 function setNativeAttributeXYZ( attribute, index, x, y, z ) {
 
@@ -3445,6 +3483,13 @@ class BufferGeometry extends EventDispatcher {`,
       fileName,
       "BufferGeometry typed-array factory",
     );
+    transformed = replaceOne(
+      transformed,
+      'type: index.array.constructor.name,',
+      'type: typedArrayTypeName( index.array ),',
+      fileName,
+      'BufferGeometry typed-array name',
+    );
     for (const attributeName of [
       "positionAttribute",
       "normalAttribute",
@@ -3537,10 +3582,17 @@ class BufferGeometry extends EventDispatcher {`,
     transformed = replaceOne(
       transformed,
       "class InterleavedBuffer {",
-      `${nativeTypedArrayFactory("createTypedArrayFromBuffer", "ArrayBuffer")}\n\nclass InterleavedBuffer {`,
+      `${nativeTypedArrayFactory("createTypedArrayFromBuffer", "ArrayBuffer")}\n\n${nativeTypedArrayName}\n\nclass InterleavedBuffer {`,
       fileName,
       "InterleavedBuffer typed-array factory",
     );
+    transformed = replaceOne(
+      transformed,
+      'type: this.array.constructor.name,',
+      'type: typedArrayTypeName( this.array ),',
+      fileName,
+      'InterleavedBuffer typed-array name',
+    );
     transformed = replaceOne(
       transformed,
       "\t\tconst array = new this.array.constructor( data.arrayBuffers[ this.array.buffer._uuid ] );",
@@ -3567,10 +3619,17 @@ class BufferGeometry extends EventDispatcher {`,
     transformed = replaceOne(
       transformed,
       "class InterleavedBufferAttribute {",
-      `${nativeTypedArrayFactory("createTypedArrayFromValues", "number[]")}\n\nclass InterleavedBufferAttribute {`,
+      `${nativeTypedArrayFactory("createTypedArrayFromValues", "number[]")}\n\n${nativeTypedArrayName}\n\nclass InterleavedBufferAttribute {`,
       fileName,
       "InterleavedBufferAttribute typed-array factory",
     );
+    transformed = replaceOne(
+      transformed,
+      'type: this.array.constructor.name,',
+      'type: typedArrayTypeName( this.array ),',
+      fileName,
+      'InterleavedBufferAttribute typed-array name',
+    );
     transformed = replaceOne(
       transformed,
       "\t\t\tconst array = [];",
@@ -4377,6 +4436,37 @@ import { Euler } from '../math/Euler.js';`,
       fileName,
       "Material exact setValues value imports",
     );
+    // `toJSON` serializes whichever colour fields a subclass declared, behind
+    // the duck test `x.isColor`. The field census sums every writer of a
+    // colour field (`Color`, and the number/string `setValues` stores), so the
+    // duck test leaves the sum un-narrowed and `getHex` is called on it.
+    // `instanceof Color` is the same test over the one class that has the
+    // method, and narrows the sum to that arm.
+    for (const field of ["color", "sheenColor", "emissive", "specular", "specularColor"]) {
+      transformed = replaceOne(
+        transformed,
+        `if ( this.${field} && this.${field}.isColor ) data.${field} = this.${field}.getHex();`,
+        `if ( this.${field} instanceof Color ) data.${field} = this.${field}.getHex();`,
+        fileName,
+        `Material.toJSON ${field} narrowing`,
+      );
+    }
+    for (const field of ["blendColor"]) {
+      transformed = replaceOne(
+        transformed,
+        `if ( this.${field} && this.${field}.isColor ) data.${field} = this.${field}.getHex();`,
+        `if ( this.${field} instanceof Color ) data.${field} = this.${field}.getHex();`,
+        fileName,
+        `Material.toJSON ${field} narrowing`,
+      );
+    }
+    transformed = replaceOne(
+      transformed,
+      "if ( this.attenuationColor !== undefined ) data.attenuationColor = this.attenuationColor.getHex();",
+      "if ( this.attenuationColor instanceof Color ) data.attenuationColor = this.attenuationColor.getHex();",
+      fileName,
+      "Material.toJSON attenuationColor narrowing",
+    );
     transformed = replaceOne(
       transformed,
       `\t\t\tif ( currentValue && currentValue.isColor ) {
@@ -9718,6 +9808,20 @@ class PMREMGenerator {`,
     }
   }
   if (normalized.endsWith("/three/src/core/BufferAttribute.js")) {
+    transformed = replaceOne(
+      transformed,
+      "class BufferAttribute extends EventDispatcher {",
+      `${nativeTypedArrayName}\n\nclass BufferAttribute extends EventDispatcher {`,
+      fileName,
+      "BufferAttribute typed-array type name helper",
+    );
+    transformed = replaceOne(
+      transformed,
+      "type: this.array.constructor.name,",
+      "type: typedArrayTypeName( this.array ),",
+      fileName,
+      "BufferAttribute toJSON typed-array type name",
+    );
     const rawCopyArrayParameter =
       "@param {(TypedArray|Array)} array - The array to copy.";
     const realizedCopyArrayParameter =
@@ -9979,6 +10083,19 @@ class Texture extends EventDispatcher {`,
       "Plane normal-matrix input",
     );
   }
+  if (normalized.endsWith("/three/src/math/Matrix3.js")) {
+    // `x.isVector2` is a duck test on a `number|Vector2` parameter. The checker
+    // does not narrow a union by the presence of a property one arm lacks, so
+    // the `else` arm kept the whole union where `set` takes numbers. The
+    // `typeof` form accepts exactly the same two inputs and narrows both arms.
+    transformed = replaceOne(
+      transformed,
+      "\tmakeTranslation( x, y ) {\n\n\t\tif ( x.isVector2 ) {",
+      "\tmakeTranslation( x, y ) {\n\n\t\tif ( typeof x !== 'number' ) {",
+      fileName,
+      "Matrix3.makeTranslation vector narrowing",
+    );
+  }
   if (normalized.endsWith("/three/src/math/Matrix4.js")) {
     transformed = replaceOne(
       transformed,
@@ -9987,6 +10104,20 @@ class Texture extends EventDispatcher {`,
       fileName,
       "Matrix4.fromArray native array input",
     );
+    transformed = replaceOne(
+      transformed,
+      "\tsetPosition( x, y, z ) {\n\n\t\tconst te = this.elements;\n\n\t\tif ( x.isVector3 ) {",
+      "\tsetPosition( x, y, z ) {\n\n\t\tconst te = this.elements;\n\n\t\tif ( typeof x !== 'number' ) {",
+      fileName,
+      "Matrix4.setPosition vector narrowing",
+    );
+    transformed = replaceOne(
+      transformed,
+      "\tmakeTranslation( x, y, z ) {\n\n\t\tif ( x.isVector3 ) {",
+      "\tmakeTranslation( x, y, z ) {\n\n\t\tif ( typeof x !== 'number' ) {",
+      fileName,
+      "Matrix4.makeTranslation vector narrowing",
+    );
     transformed = replaceOne(
       transformed,
       "@param {Array<number>} [array=[]] - The target array holding the matrix elements in column-major order.\n\t * @param {number} [offset=0] - Index of the first element in the array.\n\t * @return {Array<number>} The matrix elements in column-major order.",
@@ -10198,7 +10329,9 @@ class Texture extends EventDispatcher {`,
     transformed = replaceOne(
       transformed,
       "class Source {",
-      `/** @typedef {Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array} NativeTextureData */
+      `${nativeTypedArrayName}
+
+/** @typedef {Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array} NativeTextureData */
 /** @typedef {{ data?: NativeTextureData, width?: number, height?: number, depth?: number }} NativeTextureImage */
 /** @typedef {NativeTextureImage|NativeTextureImage[]|null} NativeTextureSourceData */
 class Source {
@@ -10208,6 +10341,13 @@ class Source {
       fileName,
       "Source native image types",
     );
+    transformed = replaceOne(
+      transformed,
+      "type: image.data.constructor.name",
+      "type: typedArrayTypeName( image.data )",
+      fileName,
+      "Source serializeImage typed-array type name",
+    );
     transformed = transformed.replace(
       "@param {any} [data=null] - The data definition of a texture.",
       "@param {NativeTextureSourceData} data - The data definition of a texture.",
@@ -10249,6 +10389,16 @@ class Source {
       fileName,
       "Source image serialization input",
     );
+    // `let url;` declares an evolving type: the checker reads each branch's
+    // assignment, but the cube branch's `url = []` is an evolving `any[]` the
+    // program cannot type. Name the union the two branches produce.
+    transformed = replaceOne(
+      transformed,
+      "\t\t\tlet url;\n",
+      "\t\t\t/** @type {ReturnType<typeof serializeImage>|Array<ReturnType<typeof serializeImage>>} */\n\t\t\tlet url;\n",
+      fileName,
+      "Source.toJSON serialized url type",
+    );
   }
   // An unannotated override receives a precise declaration-overlay parameter,
   // while Object3D's source explicitly accepts either the metadata object or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/native-webgl-angle",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Typed native WebGL compatibility layer backed by ANGLE/Metal",
   "license": "Apache-2.0",
   "repository": {
@@ -53,18 +53,20 @@
     "test:package": "node --experimental-vm-modules test/package.test.mjs"
   },
   "dependencies": {
-    "@geastack/apple": "^0.2.13"
+    "@geastack/apple": "^0.2.14"
   },
   "peerDependencies": {
     "three": "^0.185.0",
-    "@geastack/compiler": "^1.0.17"
+    "@geastack/compiler": "^1.0.22"
   },
   "devDependencies": {
-    "@geastack/compiler": "^1.0.17",
-    "@geastack/core": "^0.1.23",
-    "@geastack/engine": "^0.1.5",
+    "@geastack/compiler": "^1.0.22",
+    "@geastack/core": "^0.1.37",
+    "@geastack/engine": "^0.1.13",
     "@types/three": "^0.185.0",
     "three": "^0.185.0",
-    "typescript": "^5.9.3"
+    "troika-three-text": "^0.52.4",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0"
   }
 }