@threenative/core 0.1.0 → 0.3.0

package/patches/three@0.185.1.patch

@@ -0,0 +1,287 @@
+diff --git a/build/three.cjs b/build/three.cjs
+index 8939a67d..b0f91724 100644
+--- a/build/three.cjs
++++ b/build/three.cjs
+@@ -26116,6 +26116,8 @@ function copyArrayContents( src, target ) {
+  */
+ class BatchedMesh extends Mesh {
+ 
++	static threeNativeBatchedVelocityPatch = true;
++
+ 	/**
+ 	 * Constructs a new batched mesh.
+ 	 *
+diff --git a/build/three.core.js b/build/three.core.js
+index 0bb9262c..868a634b 100644
+--- a/build/three.core.js
++++ b/build/three.core.js
+@@ -26136,6 +26136,8 @@ function copyArrayContents( src, target ) {
+  */
+ class BatchedMesh extends Mesh {
+ 
++	static threeNativeBatchedVelocityPatch = true;
++
+ 	/**
+ 	 * Constructs a new batched mesh.
+ 	 *
+diff --git a/build/three.webgpu.js b/build/three.webgpu.js
+index 2e490796..325b497a 100644
+--- a/build/three.webgpu.js
++++ b/build/three.webgpu.js
+@@ -18500,7 +18500,8 @@ const instance = /*@__PURE__*/ Fn( ( [ matrices, colors = null ], builder ) => {
+ 
+ 			const previousInstanceData = _previousInstanceMatrices.get( object );
+ 
+-			previousInstanceData.previousInstanceMatrix.array.set( matrices.array );
++			const scheduledPrevious = object[ Symbol.for( 'threenative.velocity.previousInstanceMatrices' ) ];
++			previousInstanceData.previousInstanceMatrix.array.set( scheduledPrevious ?? matrices.array );
+ 
+ 		} );
+ 
+@@ -18599,6 +18600,7 @@ const batch = /*@__PURE__*/ Fn( ( [ batchMesh ], builder ) => {
+ 	const indirectId = getIndirectIndex( batchMesh._indirectTexture, int( batchingIdNode ) );
+ 
+ 	const matricesTexture = batchMesh._matricesTexture;
++	const previousMatricesTexture = batchMesh._previousMatricesTexture ?? matricesTexture;
+ 
+ 	const size = int( textureSize( textureLoad( matricesTexture ), 0 ).x ).toConst();
+ 	const j = float( indirectId ).mul( 4 ).toInt().toConst();
+@@ -18626,6 +18628,19 @@ const batch = /*@__PURE__*/ Fn( ( [ batchMesh ], builder ) => {
+ 
+ 	positionLocal.assign( batchingMatrix.mul( positionLocal ) );
+ 
++	if ( builder.needsPreviousData() ) {
++
++		const previousBatchingMatrix = mat4(
++			textureLoad( previousMatricesTexture, ivec2( x, y ) ),
++			textureLoad( previousMatricesTexture, ivec2( x.add( 1 ), y ) ),
++			textureLoad( previousMatricesTexture, ivec2( x.add( 2 ), y ) ),
++			textureLoad( previousMatricesTexture, ivec2( x.add( 3 ), y ) )
++		);
++
++		positionPrevious.assign( previousBatchingMatrix.mul( positionPrevious ).xyz );
++
++	}
++
+ 	const transformedNormal = normalLocal.div( vec3( bm[ 0 ].dot( bm[ 0 ] ), bm[ 1 ].dot( bm[ 1 ] ), bm[ 2 ].dot( bm[ 2 ] ) ) );
+ 
+ 	const batchingNormal = bm.mul( transformedNormal ).xyz;
+@@ -18777,7 +18792,8 @@ const skinning = /*@__PURE__*/ Fn( ( [ skinnedMesh ], builder ) => {
+ 
+ 			if ( skeletonData !== undefined ) {
+ 
+-				skeletonData.previousBoneMatrices.set( skeleton.boneMatrices );
++				const scheduledPrevious = object[ Symbol.for( 'threenative.velocity.previousBoneMatrices' ) ];
++				skeletonData.previousBoneMatrices.set( scheduledPrevious ?? skeleton.boneMatrices );
+ 
+ 			}
+ 
+@@ -18844,7 +18860,8 @@ const computeSkinning = /*@__PURE__*/ Fn( ( [ skinnedMesh, toPosition = null ],
+ 
+ 			if ( state !== undefined ) {
+ 
+-				state.previousBoneMatrices.set( skeleton.boneMatrices );
++				const scheduledPrevious = skinnedMesh[ Symbol.for( 'threenative.velocity.previousBoneMatrices' ) ];
++				state.previousBoneMatrices.set( scheduledPrevious ?? skeleton.boneMatrices );
+ 
+ 			}
+ 
+@@ -39725,7 +39742,8 @@ class VelocityNode extends TempNode {
+ 
+ 		const previousModelMatrix = getPreviousMatrix( object );
+ 
+-		this.previousModelWorldMatrix.value.copy( previousModelMatrix );
++		const scheduledPrevious = object[ Symbol.for( 'threenative.velocity.previousWorldMatrix' ) ];
++		this.previousModelWorldMatrix.value.copy( scheduledPrevious ?? previousModelMatrix );
+ 
+ 		//
+ 
+@@ -53841,7 +53859,7 @@ class NodeBuilder {
+ 
+ 		const mrt = this.renderer.getMRT();
+ 
+-		return ( mrt && mrt.has( 'velocity' ) ) || getDataFromObject( this.object ).useVelocity === true;
++		return ( mrt && mrt.has( 'velocity' ) ) || getDataFromObject( this.object ).useVelocity === true || this.object.userData?.useVelocity === true;
+ 
+ 	}
+ 
+@@ -83814,6 +83832,14 @@ class WebGPUBackend extends Backend {
+ 		 */
+ 		this.compatibilityMode = null;
+ 
++		/**
++		 * A reference to the WebGPU instance that creates adapters.
++		 *
++		 * @type {?GPU}
++		 * @default null
++		 */
++		this.gpu = null;
++
+ 		/**
+ 		 * A reference to the device.
+ 		 *
+@@ -83926,7 +83952,9 @@ class WebGPUBackend extends Backend {
+ 				xrCompatible: renderer.xr.enabled
+ 			};
+ 
+-			const adapter = ( typeof navigator !== 'undefined' ) ? await navigator.gpu.requestAdapter( adapterOptions ) : null;
++			this.gpu = ( typeof navigator !== 'undefined' ) ? navigator.gpu : null;
++
++			const adapter = this.gpu !== null ? await this.gpu.requestAdapter( adapterOptions ) : null;
+ 
+ 			if ( adapter === null ) {
+ 
+diff --git a/src/nodes/accessors/Batch.js b/src/nodes/accessors/Batch.js
+index ab62e98d..2cf4bb60 100644
+--- a/src/nodes/accessors/Batch.js
++++ b/src/nodes/accessors/Batch.js
+@@ -1,6 +1,6 @@
+ 
+ import { normalLocal } from './Normal.js';
+-import { positionLocal } from './Position.js';
++import { positionLocal, positionPrevious } from './Position.js';
+ import { vec3, mat3, mat4, int, ivec2, float, Fn } from '../tsl/TSLBase.js';
+ import { textureLoad } from './TextureNode.js';
+ import { textureSize } from './TextureSizeNode.js';
+@@ -64,6 +64,7 @@ export const batch = /*@__PURE__*/ Fn( ( [ batchMesh ], builder ) => {
+ 	const indirectId = getIndirectIndex( batchMesh._indirectTexture, int( batchingIdNode ) );
+ 
+ 	const matricesTexture = batchMesh._matricesTexture;
++	const previousMatricesTexture = batchMesh._previousMatricesTexture ?? matricesTexture;
+ 
+ 	const size = int( textureSize( textureLoad( matricesTexture ), 0 ).x ).toConst();
+ 	const j = float( indirectId ).mul( 4 ).toInt().toConst();
+@@ -90,6 +91,19 @@ export const batch = /*@__PURE__*/ Fn( ( [ batchMesh ], builder ) => {
+ 	const bm = mat3( batchingMatrix );
+ 
+ 	positionLocal.assign( batchingMatrix.mul( positionLocal ) );
++	if ( builder.needsPreviousData() ) {
++
++		const previousBatchingMatrix = mat4(
++			textureLoad( previousMatricesTexture, ivec2( x, y ) ),
++			textureLoad( previousMatricesTexture, ivec2( x.add( 1 ), y ) ),
++			textureLoad( previousMatricesTexture, ivec2( x.add( 2 ), y ) ),
++			textureLoad( previousMatricesTexture, ivec2( x.add( 3 ), y ) )
++		);
++
++		positionPrevious.assign( previousBatchingMatrix.mul( positionPrevious ).xyz );
++
++	}
++
+ 
+ 	const transformedNormal = normalLocal.div( vec3( bm[ 0 ].dot( bm[ 0 ] ), bm[ 1 ].dot( bm[ 1 ] ), bm[ 2 ].dot( bm[ 2 ] ) ) );
+ 
+@@ -104,5 +118,3 @@ export const batch = /*@__PURE__*/ Fn( ( [ batchMesh ], builder ) => {
+ 	}
+ 
+ }, 'void' );
+-
+-
+diff --git a/src/nodes/accessors/Instance.js b/src/nodes/accessors/Instance.js
+index b89834b9..c7b7bdd7 100644
+--- a/src/nodes/accessors/Instance.js
++++ b/src/nodes/accessors/Instance.js
+@@ -220,7 +220,8 @@ export const instance = /*@__PURE__*/ Fn( ( [ matrices, colors = null ], builder
+ 
+ 			const previousInstanceData = _previousInstanceMatrices.get( object );
+ 
+-			previousInstanceData.previousInstanceMatrix.array.set( matrices.array );
++			const scheduledPrevious = object[ Symbol.for( 'threenative.velocity.previousInstanceMatrices' ) ];
++			previousInstanceData.previousInstanceMatrix.array.set( scheduledPrevious ?? matrices.array );
+ 
+ 		} );
+ 
+diff --git a/src/nodes/accessors/Skinning.js b/src/nodes/accessors/Skinning.js
+index 2356aed8..aaeea633 100644
+--- a/src/nodes/accessors/Skinning.js
++++ b/src/nodes/accessors/Skinning.js
+@@ -149,7 +149,8 @@ export const skinning = /*@__PURE__*/ Fn( ( [ skinnedMesh ], builder ) => {
+ 
+ 			if ( skeletonData !== undefined ) {
+ 
+-				skeletonData.previousBoneMatrices.set( skeleton.boneMatrices );
++				const scheduledPrevious = object[ Symbol.for( 'threenative.velocity.previousBoneMatrices' ) ];
++				skeletonData.previousBoneMatrices.set( scheduledPrevious ?? skeleton.boneMatrices );
+ 
+ 			}
+ 
+@@ -216,7 +217,8 @@ export const computeSkinning = /*@__PURE__*/ Fn( ( [ skinnedMesh, toPosition = n
+ 
+ 			if ( state !== undefined ) {
+ 
+-				state.previousBoneMatrices.set( skeleton.boneMatrices );
++				const scheduledPrevious = skinnedMesh[ Symbol.for( 'threenative.velocity.previousBoneMatrices' ) ];
++				state.previousBoneMatrices.set( scheduledPrevious ?? skeleton.boneMatrices );
+ 
+ 			}
+ 
+diff --git a/src/nodes/accessors/VelocityNode.js b/src/nodes/accessors/VelocityNode.js
+index 373548b0..c48002ab 100644
+--- a/src/nodes/accessors/VelocityNode.js
++++ b/src/nodes/accessors/VelocityNode.js
+@@ -106,7 +106,8 @@ class VelocityNode extends TempNode {
+ 
+ 		const previousModelMatrix = getPreviousMatrix( object );
+ 
+-		this.previousModelWorldMatrix.value.copy( previousModelMatrix );
++		const scheduledPrevious = object[ Symbol.for( 'threenative.velocity.previousWorldMatrix' ) ];
++		this.previousModelWorldMatrix.value.copy( scheduledPrevious ?? previousModelMatrix );
+ 
+ 		//
+ 
+diff --git a/src/nodes/core/NodeBuilder.js b/src/nodes/core/NodeBuilder.js
+index be00b81e..1990da8f 100644
+--- a/src/nodes/core/NodeBuilder.js
++++ b/src/nodes/core/NodeBuilder.js
+@@ -3450,7 +3450,7 @@ class NodeBuilder {
+ 
+ 		const mrt = this.renderer.getMRT();
+ 
+-		return ( mrt && mrt.has( 'velocity' ) ) || getDataFromObject( this.object ).useVelocity === true;
++		return ( mrt && mrt.has( 'velocity' ) ) || getDataFromObject( this.object ).useVelocity === true || this.object.userData?.useVelocity === true;
+ 
+ 	}
+ 
+diff --git a/src/objects/BatchedMesh.js b/src/objects/BatchedMesh.js
+index 2ef7cb25..35cc0ffe 100644
+--- a/src/objects/BatchedMesh.js
++++ b/src/objects/BatchedMesh.js
+@@ -181,6 +181,8 @@ function copyArrayContents( src, target ) {
+  */
+ class BatchedMesh extends Mesh {
+ 
++	static threeNativeBatchedVelocityPatch = true;
++
+ 	/**
+ 	 * Constructs a new batched mesh.
+ 	 *
+diff --git a/src/renderers/webgpu/WebGPUBackend.js b/src/renderers/webgpu/WebGPUBackend.js
+index 06e20369..37b5e0be 100644
+--- a/src/renderers/webgpu/WebGPUBackend.js
++++ b/src/renderers/webgpu/WebGPUBackend.js
+@@ -102,6 +102,14 @@ class WebGPUBackend extends Backend {
+ 		 */
+ 		this.compatibilityMode = null;
+ 
++		/**
++		 * A reference to the WebGPU instance that creates adapters.
++		 *
++		 * @type {?GPU}
++		 * @default null
++		 */
++		this.gpu = null;
++
+ 		/**
+ 		 * A reference to the device.
+ 		 *
+@@ -214,7 +222,9 @@ class WebGPUBackend extends Backend {
+ 				xrCompatible: renderer.xr.enabled
+ 			};
+ 
+-			const adapter = ( typeof navigator !== 'undefined' ) ? await navigator.gpu.requestAdapter( adapterOptions ) : null;
++			this.gpu = ( typeof navigator !== 'undefined' ) ? navigator.gpu : null;
++
++			const adapter = this.gpu !== null ? await this.gpu.requestAdapter( adapterOptions ) : null;
+ 
+ 			if ( adapter === null ) {
+ 

package/scripts/apply-three-patch.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const THREE_VERSION = "0.185.1";
+const PATCH_NAME = `three@${THREE_VERSION}.patch`;
+
+/** Apply the package-owned Three.js patch to the dependency resolved for the consumer. */
+export async function applyThreePatch(options = {}) {
+  const packageRoot =
+    options.packageRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const consumerRoot = path.resolve(
+    options.consumerRoot ??
+      process.env.INIT_CWD ??
+      process.env.npm_config_local_prefix ??
+      process.cwd(),
+  );
+  const threeRoot = options.threeRoot ?? resolveThreeRoot(consumerRoot, packageRoot);
+  const manifestPath = path.join(threeRoot, "package.json");
+  const manifest = await readJson(manifestPath, "Three.js package manifest");
+  if (manifest.name !== "three" || manifest.version !== THREE_VERSION) {
+    throw new Error(
+      `TN_THREE_PATCH_VERSION: expected three@${THREE_VERSION}, found ${String(manifest.name)}@${String(manifest.version)} at ${manifestPath}.`,
+    );
+  }
+
+  const patchPath = path.join(packageRoot, "patches", PATCH_NAME);
+  const patch = parsePatch(await readFile(patchPath, "utf8"), patchPath);
+  const plans = await planPatch(threeRoot, patch);
+  if (plans.every((plan) => plan.status === "patched")) return "unchanged";
+  if (plans.some((plan) => plan.status !== "stock")) {
+    throw new Error(
+      `TN_THREE_PATCH_PARTIAL: ${manifestPath} is neither stock nor fully patched; refusing to modify a partial installation.`,
+    );
+  }
+
+  for (const plan of plans) await writeFile(plan.file, plan.contents, "utf8");
+  return "patched";
+}
+
+function resolveThreeRoot(consumerRoot, packageRoot) {
+  const attempted = [];
+  for (const root of [packageRoot, consumerRoot]) {
+    try {
+      const resolver = createRequire(path.join(root, "package.json"));
+      const entry = resolver.resolve("three");
+      const resolvedRoot = findPackageRoot(entry);
+      if (!isWithinModuleSearchPath(resolvedRoot, root)) {
+        throw new Error(`resolved outside local module paths: ${resolvedRoot}`);
+      }
+      return resolvedRoot;
+    } catch (error) {
+      attempted.push(`${root}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  throw new Error(`TN_THREE_PATCH_MISSING: could not resolve three from ${attempted.join("; ")}.`);
+}
+
+function isWithinModuleSearchPath(candidate, root) {
+  return moduleSearchPaths(root).some((searchPath) => isWithinRoot(candidate, searchPath));
+}
+
+function moduleSearchPaths(root) {
+  const paths = [];
+  let current = path.resolve(root);
+  while (true) {
+    if (path.basename(current) !== "node_modules") paths.push(path.join(current, "node_modules"));
+    const parent = path.dirname(current);
+    if (parent === current) return paths;
+    current = parent;
+  }
+}
+
+function isWithinRoot(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+function findPackageRoot(entry) {
+  let current = path.dirname(entry);
+  while (true) {
+    if (existsSync(path.join(current, "package.json"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  throw new Error(`TN_THREE_PATCH_MISSING: resolved three entry has no package.json: ${entry}.`);
+}
+
+async function readJson(file, description) {
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    throw new Error(
+      `TN_THREE_PATCH_MISSING: could not read ${description} at ${file}: ${String(error)}.`,
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `TN_THREE_PATCH_INVALID: ${description} at ${file} is not valid JSON: ${String(error)}.`,
+    );
+  }
+}
+
+function parsePatch(text, patchPath) {
+  const files = parsePatchFiles(text, patchPath);
+  if (files.length === 0)
+    throw new Error(`TN_THREE_PATCH_INVALID: no file patches in ${patchPath}.`);
+  for (const file of files) {
+    validatePatchFile(file, patchPath);
+  }
+  return files;
+}
+
+function parsePatchFiles(text, patchPath) {
+  const files = [];
+  let current;
+  let hunk;
+  for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      if (current !== undefined) files.push(finishPatchFile(current, patchPath));
+      current = { hunks: [], oldPath: undefined, newPath: undefined };
+      hunk = undefined;
+      continue;
+    }
+    if (current === undefined) continue;
+    hunk = parsePatchLine(line, current, hunk, patchPath);
+  }
+  if (current !== undefined) files.push(finishPatchFile(current, patchPath));
+  return files;
+}
+
+function parsePatchLine(line, current, hunk, patchPath) {
+  if (line.startsWith("--- ")) {
+    current.oldPath = patchPathFromHeader(line.slice(4), patchPath);
+    return hunk;
+  }
+  if (line.startsWith("+++ ")) {
+    current.newPath = patchPathFromHeader(line.slice(4), patchPath);
+    return hunk;
+  }
+  const parsedHunk = parsePatchHunk(line);
+  if (parsedHunk !== undefined) {
+    current.hunks.push(parsedHunk);
+    return parsedHunk;
+  }
+  if (line !== "\" && hunk !== undefined && isPatchLine(line))
+    hunk.lines.push(line);
+  return hunk;
+}
+
+function finishPatchFile(file, patchPath) {
+  if (file.oldPath === undefined || file.newPath === undefined || file.hunks.length === 0) {
+    throw new Error(`TN_THREE_PATCH_INVALID: incomplete file patch in ${patchPath}.`);
+  }
+  if (file.oldPath !== file.newPath) {
+    throw new Error(`TN_THREE_PATCH_INVALID: rename patches are not supported in ${patchPath}.`);
+  }
+  return file;
+}
+
+function parsePatchHunk(line) {
+  const header = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/u.exec(line);
+  if (header === null) return undefined;
+  return {
+    lines: [],
+    newCount: Number(header[4] ?? 1),
+    newStart: Number(header[3]),
+    oldCount: Number(header[2] ?? 1),
+    oldStart: Number(header[1]),
+  };
+}
+
+function isPatchLine(line) {
+  return line[0] === " " || line[0] === "+" || line[0] === "-";
+}
+
+function validatePatchFile(file, patchPath) {
+  for (const candidate of file.hunks) {
+    const oldCount = candidate.lines.filter((line) => line[0] === " " || line[0] === "-").length;
+    const newCount = candidate.lines.filter((line) => line[0] === " " || line[0] === "+").length;
+    if (oldCount !== candidate.oldCount || newCount !== candidate.newCount) {
+      throw new Error(`TN_THREE_PATCH_INVALID: hunk line counts do not match in ${patchPath}.`);
+    }
+  }
+}
+
+function patchPathFromHeader(header, patchPath) {
+  const value = header.trim().split(/\s+/u)[0];
+  if (value === undefined || (!value.startsWith("a/") && !value.startsWith("b/"))) {
+    throw new Error(`TN_THREE_PATCH_INVALID: unsupported file path in ${patchPath}.`);
+  }
+  const relative = value.slice(2);
+  if (relative.length === 0 || relative.split("/").some((part) => part === ".." || part === "")) {
+    throw new Error(`TN_THREE_PATCH_INVALID: unsafe file path '${value}' in ${patchPath}.`);
+  }
+  return relative;
+}
+
+async function planPatch(threeRoot, files) {
+  const plans = [];
+  for (const file of files) {
+    const target = path.resolve(threeRoot, file.oldPath);
+    if (path.relative(threeRoot, target).startsWith(`..${path.sep}`)) {
+      throw new Error(
+        `TN_THREE_PATCH_INVALID: patch escapes the Three.js package: ${file.oldPath}.`,
+      );
+    }
+    const original = await readFile(target, "utf8");
+    const lines = original.replaceAll("\r\n", "\n").split("\n");
+    const status = classifyFile(lines, file.hunks);
+    if (status === "patched") {
+      plans.push({ contents: original, file: target, status });
+      continue;
+    }
+    if (status !== "stock") {
+      throw new Error(
+        `TN_THREE_PATCH_PARTIAL: hunk state is mixed in ${target}; refusing to modify a partial installation.`,
+      );
+    }
+    plans.push({ contents: applyFile(lines, file.hunks, target).join("\n"), file: target, status });
+  }
+  return plans;
+}
+
+function classifyFile(lines, hunks) {
+  let stock = true;
+  let patched = true;
+  let offset = 0;
+  for (const hunk of hunks) {
+    const oldLines = hunk.lines
+      .filter((line) => line[0] === " " || line[0] === "-")
+      .map((line) => line.slice(1));
+    const newLines = hunk.lines
+      .filter((line) => line[0] === " " || line[0] === "+")
+      .map((line) => line.slice(1));
+    if (locate(lines, oldLines, hunk.oldStart - 1 + offset) === undefined) stock = false;
+    if (locate(lines, newLines, hunk.newStart - 1) === undefined) patched = false;
+    offset += newLines.length - oldLines.length;
+  }
+  if (stock) return "stock";
+  if (patched) return "patched";
+  return "mixed";
+}
+
+function applyFile(lines, hunks, file) {
+  const result = [...lines];
+  let offset = 0;
+  for (const hunk of hunks) {
+    const oldLines = hunk.lines
+      .filter((line) => line[0] === " " || line[0] === "-")
+      .map((line) => line.slice(1));
+    const newLines = hunk.lines
+      .filter((line) => line[0] === " " || line[0] === "+")
+      .map((line) => line.slice(1));
+    const index = locate(result, oldLines, hunk.oldStart - 1 + offset);
+    if (index === undefined) {
+      throw new Error(`TN_THREE_PATCH_INVALID: stock hunk no longer matches ${file}.`);
+    }
+    result.splice(index, oldLines.length, ...newLines);
+    offset += newLines.length - oldLines.length;
+  }
+  return result;
+}
+
+function locate(lines, expected, preferred) {
+  const candidates = [];
+  for (let index = 0; index <= lines.length - expected.length; index += 1) {
+    if (expected.every((line, offset) => lines[index + offset] === line)) candidates.push(index);
+  }
+  if (candidates.length === 0) return undefined;
+  candidates.sort((left, right) => Math.abs(left - preferred) - Math.abs(right - preferred));
+  if (
+    candidates.length > 1 &&
+    Math.abs(candidates[0] - preferred) === Math.abs(candidates[1] - preferred)
+  ) {
+    throw new Error(
+      `TN_THREE_PATCH_INVALID: ambiguous hunk location near line ${String(preferred + 1)}.`,
+    );
+  }
+  return candidates[0];
+}
+
+const entry = process.argv[1];
+if (entry !== undefined && path.resolve(entry) === path.resolve(fileURLToPath(import.meta.url))) {
+  const result = await applyThreePatch();
+  process.stdout.write(`threenative: Three.js velocity patch ${result}\n`);
+}

package/scripts/bundle-engine-mcp.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const coreRoot = path.resolve(fileURLToPath(import.meta.url), "..", "..");
+const source = path.resolve(coreRoot, "..", "engine-mcp", "dist", "index.js");
+const target = path.join(coreRoot, "mcp", "engine-server.mjs");
+
+if (!existsSync(source)) {
+  throw new Error(
+    `TN_ENGINE_MCP_BUNDLE: build threenative-engine-mcp before core; missing ${source}`,
+  );
+}
+copyFileSync(source, target);

package/scripts/ensure-mcp.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+// Installing ThreeNative wires its MCP servers into the project. An agent authoring a game here
+// should not have to be told the asset, sculpt and capability tools exist, or run a setup command
+// to get them. `.mcp.json` serves compatible hosts; Codex reads project-scoped `.codex/config.toml`.
+// Set THREENATIVE_SKIP_MCP_SETUP=1 to opt out.
+import { ensureCodexMcpConfig, ensureMcpConfig, installTarget } from "../mcp/install.mjs";
+
+export function runMcpSetup(environment = process.env, cwd = process.cwd()) {
+  const skip = environment.THREENATIVE_SKIP_MCP_SETUP;
+  if (skip === "1" || skip === "true") return;
+  // Never fail an install over this. A game that cannot write .mcp.json still runs.
+  try {
+    const target = installTarget(environment, cwd);
+    if (target === undefined) return;
+    const outcome = ensureMcpConfig(target);
+    const codexOutcome = ensureCodexMcpConfig(target);
+    if (outcome === "created" || outcome === "updated") {
+      process.stdout.write(`threenative: ${outcome} .mcp.json with the ThreeNative MCP servers\n`);
+    } else if (outcome === "unreadable") {
+      process.stdout.write("threenative: .mcp.json is not valid JSON; left it alone\n");
+    }
+    if (codexOutcome === "created" || codexOutcome === "updated") {
+      process.stdout.write(
+        `threenative: ${codexOutcome} .codex/config.toml with the ThreeNative MCP servers\n`,
+      );
+    }
+  } catch (error) {
+    process.stdout.write(`threenative: could not wire .mcp.json (${error})\n`);
+  }
+}
+
+const entry = process.argv[1];
+if (entry !== undefined && pathToFileURL(path.resolve(entry)).href === import.meta.url)
+  runMcpSetup();

package/scripts/generate-version.mjs

@@ -0,0 +1,13 @@
+// Single owner of the core version (PRD-181): package.json is the source of truth and
+// src/version.ts is generated from it and checked in. A hand-edited constant goes stale the
+// moment the manifest bumps; the pinning spec turns that red.
+import { readFile, writeFile } from "node:fs/promises";
+
+const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+  throw new Error("generate-version: package.json has no version");
+}
+await writeFile(
+  new URL("../src/version.ts", import.meta.url),
+  `// Generated by scripts/generate-version.mjs - do not edit. Source: package.json.\nexport const CORE_VERSION = ${JSON.stringify(manifest.version)};\n`,
+);

package/scripts/postinstall.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { applyThreePatch } from "./apply-three-patch.mjs";
+import { runMcpSetup } from "./ensure-mcp.mjs";
+
+await applyThreePatch();
+runMcpSetup();

package/dist/audio-3vkjtiuo.d.ts

@@ -1,35 +0,0 @@
-import { AudioListener, Object3D, Audio, Vector3, PositionalAudio } from 'three';
-
-interface AudioBusOptions {
-    readonly camera: Object3D;
-    readonly gestureTarget?: EventTarget;
-    readonly listener?: AudioListener;
-    readonly source?: () => EventTarget | undefined;
-}
-interface AudioPlayOptions {
-    readonly fade?: number;
-    readonly loop?: boolean;
-    readonly volume?: number;
-}
-interface AudioRuntimeSnapshot {
-    readonly queued: number;
-    readonly voices: number;
-}
-declare class AudioBus {
-    #private;
-    readonly listener: AudioListener;
-    constructor(options: AudioBusOptions);
-    get queued(): number;
-    get voices(): number;
-    setCamera(camera: Object3D): void;
-    reparent(camera: Object3D): void;
-    unlock(): Promise<void>;
-    play(buffer: AudioBuffer, options?: AudioPlayOptions): Audio;
-    playAt(buffer: AudioBuffer, source: Object3D | Vector3, options?: AudioPlayOptions): PositionalAudio;
-    music(buffer: AudioBuffer, options?: AudioPlayOptions): Audio;
-    stop(): void;
-    dispose(): void;
-}
-declare function audioRuntimeSnapshot(): AudioRuntimeSnapshot;
-
-export { AudioBus as A, audioRuntimeSnapshot as a, type AudioBusOptions as b, type AudioPlayOptions as c };