@geastack/native-webgl-angle 0.1.6

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,184 @@
+# Native WebGL ANGLE
+
+`@geastack/native-webgl-angle` owns the native WebGL compatibility layer used by
+the real Three.js macOS path.
+
+## Installation
+
+Install `@geastack/native-webgl-angle` and its Three.js peer. The package
+requires compiler 1.0.9 or later within the 1.x line and Three.js 0.185.x, and
+resolves Apple bindings from npm; it does not require a sibling Apple
+checkout.
+
+```sh
+npm install @geastack/native-webgl-angle three
+```
+
+The exports intentionally contain TypeScript sources for geatsc compilation,
+not precompiled browser JavaScript. Load the compiler plugin from
+`@geastack/native-webgl-angle/geatsc-plugin`. Native source files ship under
+`native/` and can be located with, for example,
+`require.resolve('@geastack/native-webgl-angle/native/angle_webgl_host.mm')`.
+The platform build still supplies the generated host headers, platform SDK,
+and ANGLE libraries; this package does not bundle those binaries.
+
+The experimental BatchedMesh plugin is excluded from the npm archive.
+Packaging validation loads the plugin and all of its eager imports directly
+from the npm archive in memory, without falling back to the source checkout.
+Run it with `npm run test:package -- <archive.tgz>`.
+
+```text
+upstream three
+  -> WebGLRenderingContext / WebGL2RenderingContext facade
+  -> geatsc host shims
+  -> native ANGLE host
+  -> Metal
+```
+
+This package is infrastructure. Examples should consume it; they should not
+define their own ANGLE/WebGL bridge.
+
+## Contents
+
+```text
+src/nativeWebGL.ts       current TS WebGL facade used by Three.WebGLRenderer
+src/nativeWebGLHost.ts   typed declarations for geatsc native host functions
+geatsc-plugin.mjs        host shim metadata for geatsc
+native/angle_webgl_host.mm
+                         Objective-C++ ANGLE/Metal host implementation
+```
+
+## Current Compromise
+
+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.
+
+The bridge implementation itself lives here.
+
+## Direction
+
+The current TS facade still routes many WebGL calls through transitional
+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
+preserves their native array carriers; the plugin owns the physical element
+format and buffer/texture dispatch in `geatsc-plugin-uploads.mjs`.
+
+`HostNumericArgument<E>` converts ordinary arrays directly to the requested
+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
+JavaScript number-array temporary. Sparse arrays fail closed.
+
+These hosts must consume the input synchronously without reentering JavaScript
+or retaining pointers. Reentrant hosts must use the compiler's separate owned
+snapshot protocol. Rebuild generated declarations and native objects together
+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.
+
+`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
+and uniform paths. Set them before the first host call and restart the process
+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
+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
+implementations in `angle_webgl_host.mm` and `audio_host.mm` were audited for
+those effects; audio channel uploads copy samples synchronously into native
+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.
+
+`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
+compiler comes from a checkout of
+[geastack/compiler](https://github.com/geastack/compiler) with `dist/` built.
+`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
+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.
+
+### Streaming diagnostics and uniform names
+
+Windows builds can select `GEA_WEBGL_BUFFER_STREAMING=0..9` to compare original
+subdata, orphaning, replacement, dynamic usage, and a three-buffer staging ring.
+Modes 1–4 qualify complete ARRAY_BUFFER updates. Modes 5/6 extend dynamic
+replacement/staging rotation to complete ELEMENT_ARRAY_BUFFER updates; mode 7
+streams indices alone; mode 8 combines vertex staging with dynamic indices.
+Mode 9 uses uniform-buffer staging for eligible small full vertex updates.
+Although its measured upload wait is shorter, total CPU cost increased;
+it remains a diagnostic option and mode 8 remains the default.
+Partial writes always preserve existing storage.
+Windows defaults to the hybrid policy (8); mode 0 keeps the original path and
+bypasses streaming bookkeeping in normal builds. Other platforms retain the
+original path. Per-upload timing rows compile only with allocation or native
+frame profiling.
+
+Common renderer uniforms use fixed-name typed setters that still read the map
+on every call. Replacing/deleting entries remains observable. Shadow-map
+setters also forward the texture allocator so sampler ordering is preserved.
+General uploads classify built-in long names once when the program's uniform
+nodes are created, then read the current material value cell through a named
+lookup. Custom names retain dynamic dictionary lookup. No material value cell
+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
+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
+`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
+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;
+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
+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-batched-probe.mjs

@@ -0,0 +1,98 @@
+// Verification-only wrapper plugin for BatchedMesh native typing work.
+//
+// It imports the base plugin's default export, wraps `configure()` so its
+// `hostShims.transformSource` runs first (every other transform the base
+// plugin applies still happens), and then layers these adaptations on top:
+//
+//   - `core/Object3D.js` -> expose the documented native callback arguments
+//   - `math/FrustumArray.js` -> check pool extent before native element reads
+//   - `objects/BatchedMesh.js`  -> `transformBatchedMesh`
+//   - `renderers/WebGLRenderer.js` -> `transformBatchedRendererBranch`
+//     (replacing the base plugin's current "BatchedMesh is not supported"
+//     stub with the typed uniform branch)
+//
+// These rewrites remain experimental until native execution and renderer
+// callback dispatch pass. This wrapper is excluded from the published package.
+
+import basePlugin from './geatsc-plugin.mjs'
+import { transformBatchedMesh, transformBatchedRendererBranch } from './geatsc-plugin-batched-mesh.mjs'
+
+const replaceOne = (text, before, after, fileName, description) => {
+  if (!text.includes(before)) throw new Error(`Three ${description} source at ${fileName} no longer matches the native adaptation`)
+  return text.replace(before, after)
+}
+
+export default {
+  name: 'native-webgl-angle-host-batched-probe',
+  configure() {
+    const base = basePlugin.configure()
+    const baseTransformSource = base.hostShims.transformSource
+
+    const transformSource = ({ fileName, text }) => {
+      const normalized = fileName.replaceAll('\\', '/')
+      const baseResult = baseTransformSource({ fileName, text })
+      let transformed = baseResult === null ? text : baseResult
+
+      if (process.env.GEA_WEBGL_AUTO_INSTANCE_TEST === '1' && normalized.endsWith('/three-batched-mesh/index.tsx')) {
+        transformed = replaceOne(transformed, 'native-webgl-angle/test/batched-render-scene',
+          'native-webgl-angle/test/auto-instanced-render-scene', fileName, 'automatic instancing validation scene');
+      }
+
+      // Three documents these callback arguments but comments them out of the
+      // base no-op definitions. Keep the real callback ABI visible to native
+      // override dispatch and to callers holding an Object3D reference.
+      if (normalized.endsWith('/three/src/core/Object3D.js')) {
+        transformed = transformed.replaceAll('@param {Object} group - The geometry group data.',
+          '@param {{start:number,count:number,materialIndex?:number}|null} group - The geometry group data.')
+        for (const name of ['onBeforeRender', 'onAfterRender', 'onBeforeShadow', 'onAfterShadow']) {
+          const shadow = name.endsWith('Shadow')
+          const parameters = shadow
+            ? 'renderer, object, camera, shadowCamera, geometry, depthMaterial, group'
+            : 'renderer, scene, camera, geometry, material, group'
+          transformed = replaceOne(transformed, `${name}( /* ${parameters} */ ) {}`,
+            `${name}( ${parameters} ) {}`, fileName, `Object3D ${name} declared callback arguments`)
+          if (!shadow) {
+            // Scene calls this inherited no-op with a render target in slot
+            // four and omits material/group. Mesh calls supply all six slots.
+            const signature = `${name}( ${parameters} ) {}`
+            const start = transformed.lastIndexOf('/**', transformed.indexOf(signature))
+            const end = transformed.indexOf(signature)
+            const comment = transformed.slice(start, end)
+              .replace('@param {BufferGeometry} geometry', "@param {BufferGeometry|import('../renderers/WebGLRenderTarget.js').WebGLRenderTarget|null} geometry")
+              .replace('@param {Material} material', '@param {Material} [material]')
+              .replace('} group -', '} [group] -')
+            transformed = transformed.slice(0, start) + comment + transformed.slice(end)
+          }
+        }
+      }
+
+      if (normalized.endsWith('/three/src/objects/BatchedMesh.js')) {
+        transformed = transformBatchedMesh(transformed, fileName, replaceOne)
+      }
+
+      if (normalized.endsWith('/three/src/math/FrustumArray.js')) {
+        // The pool grows sequentially. Test its extent before reading a native
+        // element; retain Three's missing-entry test for existing JS slots.
+        const before = 'if ( frustums[ i ] === undefined ) frustums[ i ] = new Frustum();'
+        const after = 'if ( i >= frustums.length || frustums[ i ] === undefined ) frustums[ i ] = new Frustum();'
+        for (let occurrence = 0; occurrence < 2; occurrence++) {
+          transformed = replaceOne(transformed, before, after, fileName, 'FrustumArray pool extent before element read')
+        }
+      }
+
+      if (normalized.endsWith('/three/src/renderers/WebGLRenderer.js')) {
+        transformed = transformBatchedRendererBranch(transformed, fileName, replaceOne)
+      }
+
+      return transformed === text ? null : transformed
+    }
+
+    return {
+      ...base,
+      hostShims: {
+        ...base.hostShims,
+        transformSource,
+      },
+    }
+  },
+}

package/geatsc-plugin-instancing.mjs

@@ -0,0 +1,160 @@
+// Generic, opt-in render-list instancing. Only already-adjacent opaque draws
+// with the same native geometry/material are candidates. No scene mutation.
+export const nativeInstanceHelpers = `
+/** @param {import('../core/Object3D.js').Object3D} object @return {boolean} */
+function nativeInstanceTransformSupported( object ) {
+	const e = object.matrixWorld.elements;
+	const x = e[0]*e[0] + e[1]*e[1] + e[2]*e[2];
+	const y = e[4]*e[4] + e[5]*e[5] + e[6]*e[6];
+	const z = e[8]*e[8] + e[9]*e[9] + e[10]*e[10];
+	// Three's instanced normal transform supports positive TRS, not shear.
+	return e[3] === 0 && e[7] === 0 && e[11] === 0 && e[15] === 1 &&
+		x > 0 && y > 0 && z > 0 && object.matrixWorld.determinant() > 0 &&
+		Math.abs(e[0]*e[4] + e[1]*e[5] + e[2]*e[6]) <= 1e-10 * Math.sqrt(x*y) &&
+		Math.abs(e[0]*e[8] + e[1]*e[9] + e[2]*e[10]) <= 1e-10 * Math.sqrt(x*z) &&
+		Math.abs(e[4]*e[8] + e[5]*e[9] + e[6]*e[10]) <= 1e-10 * Math.sqrt(y*z);
+}
+`;
+
+export function transformAutomaticInstancing(text, fileName, replaceOne, renderItemType) {
+  text = `import { nativeInstanceBeforeRender, nativeInstanceAfterRender } from '../core/Object3D.js';\nimport { nativeInstanceMaterialBeforeRender, nativeInstanceBeforeCompile, nativeInstanceProgramCacheKey } from '../materials/Material.js';\nimport { InstancedBufferAttribute } from '../core/InstancedBufferAttribute.js';\nimport { InterleavedBufferAttribute } from '../core/InterleavedBufferAttribute.js';\nimport { InstancedInterleavedBuffer } from '../core/InstancedInterleavedBuffer.js';\nimport { InstancedMesh } from '../objects/InstancedMesh.js';\nimport { Mesh } from '../objects/Mesh.js';\n${nativeInstanceHelpers}\n` + text;
+  const before = `\t\tfunction renderObjects( renderList, scene, camera ) {`;
+  const start = text.indexOf(before);
+  const end = text.indexOf('\n\t\tfunction renderObject(', start);
+  if (start < 0 || end < 0) throw new Error(`Three renderObjects source at ${fileName} no longer matches`);
+  const replacement = `
+		const nativeInstanceMatrix = new Matrix4();
+		let nativeInstanceUsed = 0;
+		/** @type {InstancedMesh[]} */
+		const nativeInstancePool = [];
+		/** @param {${renderItemType}} item */
+		function nativeCanInstanceMaterial( item ) {
+			const material = item.material;
+			// The pooled mesh must not inherit callbacks installed specifically
+			// on InstancedMesh, even when the source meshes keep canonical hooks.
+			if (InstancedMesh.prototype.onBeforeRender !== nativeInstanceBeforeRender ||
+				InstancedMesh.prototype.onAfterRender !== nativeInstanceAfterRender) return false;
+			if (material.isShaderMaterial || material.isRawShaderMaterial || material.isNodeMaterial ||
+				// Object-space normal maps use only the uniform normalMatrix in
+				// Three's fragment shader, bypassing per-instance normal transforms.
+				(material.normalMap && material.normalMapType === 1 /* ObjectSpaceNormalMap */) ||
+				material.transparent || !material.depthWrite || !material.depthTest ||
+				material.stencilWrite || material.wireframe || material.blending !== 1 ||
+				material.onBeforeRender !== nativeInstanceMaterialBeforeRender ||
+				material.onBeforeCompile !== nativeInstanceBeforeCompile ||
+				material.customProgramCacheKey !== nativeInstanceProgramCacheKey) return false;
+			if (!(material.type === 'MeshBasicMaterial' || material.type === 'MeshLambertMaterial' ||
+				material.type === 'MeshPhongMaterial' || material.type === 'MeshStandardMaterial')) return false;
+			if (item.geometry.isInstancedBufferGeometry || Object.keys(item.geometry.morphAttributes).length !== 0) return false;
+			const names = Object.keys(item.geometry.attributes);
+			if (names.length > 8) return false;
+			for (let i = 0; i < names.length; i++) {
+				const attribute = item.geometry.getAttribute(names[i]);
+				if (attribute instanceof InstancedBufferAttribute ||
+					(attribute instanceof InterleavedBufferAttribute && attribute.data instanceof InstancedInterleavedBuffer)) return false;
+			}
+			return true;
+		}
+		/** @param {${renderItemType}} item @param {import('../cameras/Camera.js').Camera} camera */
+		function nativeCanInstance( item, camera ) {
+			const object = item.object;
+			return object instanceof Mesh && !(object instanceof InstancedMesh) && !object.isSkinnedMesh && !object.isBatchedMesh && object.type === 'Mesh' &&
+				item.group === null && object.layers.test(camera.layers) &&
+				object.onBeforeRender === nativeInstanceBeforeRender &&
+				object.onAfterRender === nativeInstanceAfterRender &&
+				object.morphTargetInfluences === undefined && nativeInstanceTransformSupported(object);
+		}
+
+		/** @param {${renderItemType}[]} renderList */
+		function renderObjects( renderList, scene, camera ) {
+			const overrideMaterial = scene.isScene === true ? scene.overrideMaterial : null;
+			let batchIndex = 0;
+			for (let i = 0, l = renderList.length; i < l; i++) {
+				const item = renderList[i];
+				const object = item.object;
+				const geometry = item.geometry;
+				const group = item.group;
+				let material = item.material;
+				if (material.allowOverride === true && overrideMaterial !== null) material = overrideMaterial;
+				if (!object.layers.test(camera.layers)) continue;
+				let end = i + 1;
+				// Reject singleton runs before inspecting attributes. Those checks
+				// enumerate keys and would otherwise allocate for every ordinary draw.
+				if (end < l && renderList[end].geometry === geometry && renderList[end].material === material &&
+					overrideMaterial === null && !_this.localClippingEnabled && currentRenderState.state.lightProbeGridArray.length === 0 && nativeCanInstanceMaterial(item) && nativeCanInstance(item, camera)) {
+					while (end < l) {
+						const next = renderList[end];
+						if (next.geometry !== geometry || next.material !== material ||
+							next.groupOrder !== item.groupOrder || next.renderOrder !== item.renderOrder ||
+							next.object.receiveShadow !== object.receiveShadow || !nativeCanInstance(next, camera)) break;
+						end++;
+					}
+				}
+				const count = end - i;
+				if (count < 2) {
+					renderObject(object, scene, camera, geometry, material, group);
+					continue;
+				}
+				if (batchIndex >= nativeInstancePool.length) {
+					nativeInstancePool.push(new InstancedMesh(geometry, material, Math.max(16, count)));
+				}
+				let batch = nativeInstancePool[batchIndex];
+				if (batch.instanceMatrix.count < count) {
+					batch.dispose();
+					batch = new InstancedMesh(geometry, material, Math.max(count, batch.instanceMatrix.count * 2));
+					nativeInstancePool[batchIndex] = batch;
+				}
+				batchIndex++;
+				nativeInstanceUsed = Math.max(nativeInstanceUsed, batchIndex);
+				batch.geometry = geometry;
+				batch.material = material;
+				batch.count = count;
+				batch.receiveShadow = object.receiveShadow;
+				// Keep visible coordinates near the camera before Float32 upload.
+				// A distant first instance must not quantize nearby later instances.
+				const origin = camera.matrixWorld.elements;
+				const originX = origin[12], originY = origin[13], originZ = origin[14];
+				batch.matrixWorld.makeTranslation(originX, originY, originZ);
+				for (let j = i; j < end; j++) {
+					const original = renderList[j].object;
+					nativeInstanceMatrix.copy(original.matrixWorld);
+					const relative = nativeInstanceMatrix.elements;
+					relative[12] -= originX;
+					relative[13] -= originY;
+					relative[14] -= originZ;
+					batch.setMatrixAt(j - i, nativeInstanceMatrix);
+					// Retain Three's observable per-object camera matrices.
+					original.modelViewMatrix.multiplyMatrices(camera.matrixWorldInverse, original.matrixWorld);
+					original.normalMatrix.getNormalMatrix(original.modelViewMatrix);
+				}
+				batch.instanceMatrix.needsUpdate = true;
+				objects.update(batch);
+				// A renderer can submit several views in one frame. WebGLObjects'
+				// once-per-frame guard must not hide updated instance matrices.
+				attributes.update(batch.instanceMatrix, _gl.ARRAY_BUFFER);
+				renderObject(batch, scene, camera, geometry, material, null);
+				i = end - 1;
+			}
+		}
+`;
+  text = text.slice(0, start) + replacement + text.slice(end);
+  text = replaceOne(text, '\t\tthis.render = /** @this {WebGLRenderer} */ function ( scene, camera ) {',
+    '\t\tthis.render = /** @this {WebGLRenderer} */ function ( scene, camera ) {\n\t\t\tif (renderListStack.length === 0) nativeInstanceUsed = 0;', fileName, 'instance pool per-render usage');
+  text = replaceOne(text, '\t\t\tbindingStates.resetDefaultState();',
+    '\t\t\tif (renderListStack.length === 1) {\n\t\t\t\twhile (nativeInstancePool.length > nativeInstanceUsed) {\n\t\t\t\t\tnativeInstancePool[nativeInstancePool.length - 1].dispose();\n\t\t\t\t\tnativeInstancePool.pop();\n\t\t\t\t}\n\t\t\t}\n\t\t\tbindingStates.resetDefaultState();', fileName, 'unused instance pool disposal');
+  return replaceOne(text, '\t\tthis.dispose = function () {',
+    '\t\tthis.dispose = function () {\n\t\t\tfor (let i = 0; i < nativeInstancePool.length; i++) nativeInstancePool[i].dispose();\n\t\t\tnativeInstancePool.length = 0;', fileName, 'renderer instance pool disposal');
+}
+
+export function transformCanonicalInstanceHooks(text, fileName) {
+  if (fileName.endsWith('/three/src/core/Object3D.js')) {
+    return text + `\nexport const nativeInstanceBeforeRender = Object3D.prototype.onBeforeRender;
+export const nativeInstanceAfterRender = Object3D.prototype.onAfterRender;\n`;
+  }
+  if (fileName.endsWith('/three/src/materials/Material.js')) {
+    return text + `\nexport const nativeInstanceMaterialBeforeRender = Material.prototype.onBeforeRender;
+export const nativeInstanceBeforeCompile = Material.prototype.onBeforeCompile;
+export const nativeInstanceProgramCacheKey = Material.prototype.customProgramCacheKey;\n`;
+  }
+  return text;
+}