@threenative/procedural-animals 0.0.0-stage → 0.1.1

package/LICENSES/Procedural-Animals-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Majid Manzarpour and procedural-animals contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @threenative/procedural-animals
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional bake-first wolf content. The build entry pins Procedural Animals at
+`c95ae49346aa8e140a924376cec6cf0073d99512` and Node 20.19.6. Runtime imports contain
+no generator, worker or Node dependency. Frozen installed browser/Linux correctness
+runs passed; paired frame budgets and fifty GPU lifecycle cycles remain unqualified.
+See the [owning PRD](../../docs/PRDs/done/PRD-procedural-animal-content.md).
+
+The installed engine MCP discovers this optional package through
+`engine_search_capabilities` and `engine_capability_detail`, using the ordinary
+generated capability manifest. Runtime capabilities are `createAnimalActor`,
+`createAnimalGeometry`, `loadAnimalBake` and `parseAnimalBake` from
+`@threenative/procedural-animals`. Build capabilities are `animalBakePass`,
+`bakeWolf` and `bakeWolfToFile` from `@threenative/procedural-animals/build`.
+Each entry reports the optional dependency, an example and its constraints.
+
+At build time, call `bakeWolfToFile({ seed: 7, tier: "crowd" }, destination)` from
+`@threenative/procedural-animals/build`, then pass `animalBakePass()` to the normal
+`@threenative/assets` compiler. High and crowd bakes share individual parameters.
+Each source is validated before a same-directory atomic rename; the asset compiler
+owns the hashed manifest. Timing statistics are excluded from deterministic bytes.
+
+At runtime, `loadAnimalBake(ctx.assets, logicalPath, { signal })` resolves the cooked
+file and validates the complete PANM payload before constructing resources. Limits:
+64 MiB, 250,000 vertices, 1.5 million indices and 256 bones. Unknown revisions,
+malformed offsets/indices, non-finite values and unnormalized weights fail by name.
+The corruption checksum is not an authenticity signature.
+
+`createAnimalActor(bake, { motion, material, ground })` owns instance geometry, pose,
+bounds and lifetime. Supply editable game motion and a DQS material from `src/render/`.
+Call `follow(acceptedState, dt)` in `afterPhysics`; accepted position/velocity and
+heading are the only root authority. An identity parent is required. A named
+`visualOriginOffset` accommodates centred physics capsules and remains reported.
+Pause freezes the pose; teleport replaces motion history; disposal settles pending
+actions and attempts every resource cleanup. The first action set is stand/sit/lie.
+
+The example contains the pinned wolf's editable motion closure and a base-surface
+TSL DQS material with normal/shadow skinning. Fur, fins, eyes, runtime generation,
+other species and AnimationMixer/composer ownership are outside this slice.
+
+The [pinned donor](https://github.com/majidmanzarpour/threejs-procedural-animals/tree/c95ae49346aa8e140a924376cec6cf0073d99512)
+MIT notice is retained in `LICENSES/Procedural-Animals-MIT.txt`. Focused tests use
+actual generation, the ordinary asset cook, real fixed-step Rapier, an independent
+CPU DQS oracle and lifecycle fault controls. These are CPU evidence only.

package/dist/build.d.ts

@@ -0,0 +1,53 @@
+import { A as AnimalTier } from './format-BRFFv-ws.js';
+
+declare const ANIMAL_BUILD_NODE = "20.19.6";
+interface IWolfBakeOptions {
+    readonly seed: number;
+    readonly tier: AnimalTier;
+    readonly sex?: "male" | "female";
+    readonly age?: "adult" | "juvenile";
+    readonly variant?: "grey" | "black" | "pale" | "tawny";
+}
+/**
+ * Bake the pinned wolf on the build machine, never on the portable runtime path.
+ * @situation bake high and crowd wolf geometry before the ordinary asset cook
+ * @constraint exact pinned Node runtime, donor revision, options and generated bytes are validated; no worker is created
+ * @requires npm i @threenative/procedural-animals
+ * @example const bytes = await bakeWolf({ seed: 7, tier: "crowd" });
+ */
+declare function bakeWolf(options: IWolfBakeOptions): Promise<ArrayBuffer>;
+/**
+ * Stage a validated source bake with a same-directory atomic rename, then use compileAssets.
+ * @situation publish a generated wolf without replacing the last valid bake on interruption
+ * @constraint validation and generation complete before the destination is touched; temporary files are removed on failure
+ * @requires npm i @threenative/procedural-animals
+ * @example await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
+ */
+declare function bakeWolfToFile(options: IWolfBakeOptions, destination: string): Promise<string>;
+/**
+ * Validate staged PANM sources inside the existing asset compiler; it owns the hashed manifest.
+ * @situation cook staged animal bakes through the ordinary asset pipeline
+ * @constraint only .animal inputs are interpreted; corruption fails the cook, without regeneration
+ * @requires npm i @threenative/procedural-animals
+ * @example await compileAssets({ passes: [animalBakePass()] });
+ */
+declare function animalBakePass(): {
+    name: string;
+    appliesTo: readonly ["other"];
+    cacheKey: string;
+    apply(input: Buffer, logicalPath: string): Buffer<ArrayBufferLike> | {
+        buffer: Buffer<ArrayBufferLike>;
+        entry: {
+            animal: {
+                species: "wolf";
+                seed: number;
+                tier: AnimalTier;
+                vertices: number;
+                bones: number;
+                sha256: string;
+            };
+        };
+    };
+};
+
+export { ANIMAL_BUILD_NODE, type IWolfBakeOptions, animalBakePass, bakeWolf, bakeWolfToFile };

package/dist/build.js

@@ -0,0 +1,367 @@
+import { randomUUID, createHash } from 'crypto';
+import { readFile, mkdir, writeFile, rename, rm } from 'fs/promises';
+import { createRequire } from 'module';
+import path from 'path';
+import { clearBuildCache, buildAnimalData, writeBake } from 'procedural-animals';
+import wolf from 'procedural-animals/species/wolf';
+
+// src/build.ts
+
+// src/format.ts
+var ANIMAL_DONOR_REVISION = "c95ae49346aa8e140a924376cec6cf0073d99512";
+var ANIMAL_ADAPTER_VERSION = 1;
+var ANIMAL_LIMITS = Object.freeze({
+  bytes: 64 * 1024 * 1024,
+  vertices: 25e4,
+  indices: 15e5,
+  bones: 256,
+  headerBytes: 1024 * 1024
+});
+var ANIMAL_ARRAYS = {
+  pos: [Float32Array, 3],
+  nrm: [Float32Array, 3],
+  index: [Uint32Array, 0],
+  skinIndex: [Uint16Array, 4],
+  skinWeight: [Float32Array, 4],
+  comb: [Float32Array, 3],
+  tint: [Float32Array, 4],
+  coat: [Float32Array, 4],
+  pat: [Float32Array, 4],
+  surf: [Float32Array, 4]
+};
+function bakeIntegrity(buffer) {
+  const view = new DataView(buffer);
+  const headerBytes = view.getUint32(8, true);
+  const start = Math.ceil((12 + headerBytes) / 8) * 8;
+  const bytes = new Uint8Array(buffer);
+  const header = JSON.parse(new TextDecoder().decode(bytes.subarray(12, 12 + headerBytes)));
+  const { integrity: _integrity, ...metadata } = header.threenative;
+  let hash = 2166136261;
+  for (const section of [
+    new TextEncoder().encode(JSON.stringify({ ...header, threenative: metadata })),
+    bytes.subarray(start)
+  ])
+    for (const byte of section) hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+  return hash.toString(16).padStart(8, "0");
+}
+var validatedBakes = /* @__PURE__ */ new WeakSet();
+function animalError(code, detail) {
+  return new Error(`TN_ANIMAL_${code}: ${detail}`);
+}
+function record(value, name2) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw animalError("HEADER", `${name2} must be an object`);
+  }
+  return value;
+}
+function integer(value, min, max, name2) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+    throw animalError("LIMIT", `${name2} must be an integer in [${min}, ${max}]`);
+  }
+  return value;
+}
+function name(value, label) {
+  if (typeof value !== "string" || !/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/u.test(value)) {
+    throw animalError("RIG", `${label} must be a joint or bone name`);
+  }
+  return value;
+}
+function joints(value, label) {
+  const entries = Object.entries(record(value, label));
+  integer(entries.length, 2, 4096, `${label} count`);
+  for (const [key, point] of entries) {
+    name(key, label);
+    if (!Array.isArray(point) || point.length !== 3 || !point.every(Number.isFinite)) {
+      throw animalError("RIG", `${label}.${key} must be a finite point`);
+    }
+  }
+  return value;
+}
+function validateHeader(header) {
+  if (header.version !== 1 || header.species !== "wolf" || header.quality !== "high" && header.quality !== "crowd") {
+    throw animalError("REVISION", "expected version 1, wolf, and high or crowd geometry");
+  }
+  integer(header.seed, 0, 4294967295, "seed");
+  integer(header.nV, 3, ANIMAL_LIMITS.vertices, "vertex count");
+  const metadata = record(header.threenative, "threenative");
+  if (metadata.donorRevision !== ANIMAL_DONOR_REVISION || metadata.adapterVersion !== ANIMAL_ADAPTER_VERSION) {
+    throw animalError("REVISION", "unknown donor revision or adapter version");
+  }
+  if (typeof metadata.buildRuntime !== "string" || metadata.buildRuntime !== "node-v20.19.6" || typeof metadata.cacheKey !== "string" || !/^[a-f0-9]{64}$/u.test(metadata.cacheKey) || typeof metadata.integrity !== "string" || !/^[a-f0-9]{8}$/u.test(metadata.integrity)) {
+    throw animalError("HEADER", "missing pinned build runtime or SHA-256 cache key");
+  }
+  const params = record(header.params, "params");
+  if (typeof params.size !== "number" || !Number.isFinite(params.size) || params.size <= 0) {
+    throw animalError("RIG", "params.size must be finite and positive");
+  }
+  if (params.seed !== void 0 && params.seed !== header.seed)
+    throw animalError("OPTIONS", "individual seed contradicts bake seed");
+  const points = joints(header.joints, "joints");
+  joints(header.refJoints, "refJoints");
+  if (!Array.isArray(header.bones)) throw animalError("RIG", "bones must be an array");
+  integer(header.bones.length, 1, ANIMAL_LIMITS.bones, "bone count");
+  const parents = /* @__PURE__ */ new Map();
+  for (const value of header.bones) {
+    const bone = record(value, "bone");
+    const key = name(bone.name, "bone.name");
+    if (parents.has(key)) throw animalError("RIG", `duplicate bone ${key}`);
+    const parent = bone.parent === null ? null : name(bone.parent, `${key}.parent`);
+    parents.set(key, parent);
+    const headName = name(bone.headJ, `${key}.headJ`);
+    const tailName = name(bone.tailJ, `${key}.tailJ`);
+    const head = Object.hasOwn(points, headName) ? points[headName] : void 0;
+    const tail = Object.hasOwn(points, tailName) ? points[tailName] : void 0;
+    const length = head && tail ? Math.hypot(head[0] - tail[0], head[1] - tail[1], head[2] - tail[2]) : Number.NaN;
+    if (!Number.isFinite(length) || length < 1e-8) {
+      throw animalError("RIG", `${key} has missing joints or zero length`);
+    }
+  }
+  for (const key of parents.keys()) {
+    const seen = /* @__PURE__ */ new Set();
+    let current = key;
+    while (current !== null) {
+      if (seen.has(current) || !parents.has(current))
+        throw animalError("RIG", `${key} has a cyclic or missing parent`);
+      seen.add(current);
+      current = parents.get(current) ?? null;
+    }
+  }
+}
+function validateArrayData(arrays, vertices, boneCount) {
+  for (const key of Object.keys(ANIMAL_ARRAYS)) {
+    const array = arrays[key];
+    const [Constructor, width] = ANIMAL_ARRAYS[key];
+    if (!(array instanceof Constructor) || !array || (key === "index" ? array.length < 3 || array.length > ANIMAL_LIMITS.indices || array.length % 3 !== 0 : array.length !== vertices * width))
+      throw animalError("SECTIONS", `${key} changed after validation`);
+    for (const value of array) {
+      if (!Number.isFinite(value))
+        throw animalError("FINITE", `${key} contains a non-finite value`);
+      if (key === "index" && value >= vertices)
+        throw animalError("INDEX", `vertex index ${value} exceeds vertex count`);
+      if (key === "skinIndex" && value >= boneCount)
+        throw animalError("BONE_INDEX", `bone index ${value} exceeds bone count`);
+    }
+  }
+  const weights = arrays.skinWeight;
+  for (let i = 0; i < weights.length; i += 4) {
+    const group = weights.subarray(i, i + 4);
+    if (group.some((weight) => weight < 0 || weight > 1) || Math.abs(group.reduce((a, b) => a + b, 0) - 1) > 1e-4) {
+      throw animalError("WEIGHTS", `vertex ${i / 4} has non-normalized skin weights`);
+    }
+  }
+}
+function parseAnimalBake(buffer) {
+  if (!(buffer instanceof ArrayBuffer) || buffer.byteLength < 16 || buffer.byteLength > ANIMAL_LIMITS.bytes) {
+    throw animalError("LIMIT", `payload must contain 16..${ANIMAL_LIMITS.bytes} bytes`);
+  }
+  const bytes = new Uint8Array(buffer);
+  const view = new DataView(buffer);
+  if (view.getUint32(0, false) !== 1346457165) throw animalError("MAGIC", "expected PANM");
+  if (view.getUint32(4, true) !== 1) throw animalError("REVISION", "unknown PANM version");
+  const headerBytes = integer(
+    view.getUint32(8, true),
+    8,
+    ANIMAL_LIMITS.headerBytes,
+    "header bytes"
+  );
+  const start = Math.ceil((12 + headerBytes) / 8) * 8;
+  if (headerBytes % 8 !== 0 || start > buffer.byteLength)
+    throw animalError("SECTIONS", "truncated or unaligned header");
+  let header;
+  try {
+    header = record(
+      JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(12, 12 + headerBytes))
+      ),
+      "header"
+    );
+  } catch (error) {
+    throw animalError("HEADER", `invalid UTF-8/JSON header: ${String(error)}`);
+  }
+  const pending = [{ value: header, depth: 0 }];
+  let visited = 0;
+  while (pending.length > 0) {
+    if (++visited > 1e5)
+      throw animalError("LIMIT", "header exceeds the structural traversal limit");
+    const entry = pending.pop();
+    if (!entry) break;
+    const { value, depth } = entry;
+    if (depth > 64) throw animalError("LIMIT", "header nesting exceeds 64 levels");
+    if (typeof value === "number" && !Number.isFinite(value))
+      throw animalError("FINITE", "header contains a non-finite number");
+    if (value !== null && typeof value === "object")
+      for (const child of Object.values(value)) pending.push({ value: child, depth: depth + 1 });
+  }
+  validateHeader(header);
+  if (!Array.isArray(header.arrays) || header.arrays.length !== Object.keys(ANIMAL_ARRAYS).length) {
+    throw animalError("SECTIONS", "expected every supported array exactly once");
+  }
+  const arrays = {};
+  const ranges = [];
+  for (const value of header.arrays) {
+    const section = record(value, "section");
+    if (typeof section.key !== "string")
+      throw animalError("SECTIONS", "section key must be a string");
+    const key = section.key;
+    if (!Object.hasOwn(ANIMAL_ARRAYS, key) || arrays[key] !== void 0)
+      throw animalError("SECTIONS", `unknown or duplicate section ${String(key)}`);
+    const [Constructor, width] = ANIMAL_ARRAYS[key];
+    if (section.type !== Constructor.name)
+      throw animalError("SECTIONS", `${key} must contain ${Constructor.name}`);
+    const length = integer(
+      section.length,
+      1,
+      key === "index" ? ANIMAL_LIMITS.indices : ANIMAL_LIMITS.vertices * width,
+      `${key} length`
+    );
+    if (key === "index" && length % 3 !== 0 || key !== "index" && length !== Number(header.nV) * width) {
+      throw animalError("SECTIONS", `${key} length contradicts the vertex or triangle count`);
+    }
+    const offset = integer(section.offset, 0, ANIMAL_LIMITS.bytes, `${key} offset`);
+    const end2 = start + offset + Math.ceil(length * Constructor.BYTES_PER_ELEMENT / 8) * 8;
+    if (offset % 8 !== 0 || end2 > buffer.byteLength)
+      throw animalError("SECTIONS", `${key} is unaligned or truncated`);
+    ranges.push([start + offset, end2]);
+    arrays[key] = new Constructor(buffer, start + offset, length);
+  }
+  let end = start;
+  for (const range of ranges.sort((a, b) => a[0] - b[0])) {
+    if (range[0] !== end) throw animalError("SECTIONS", "sections overlap or contain gaps");
+    end = range[1];
+  }
+  if (end !== buffer.byteLength)
+    throw animalError("SECTIONS", "byte length contradicts section extents");
+  validateArrayData(arrays, Number(header.nV), header.bones.length);
+  if (bakeIntegrity(buffer) !== header.threenative.integrity)
+    throw animalError("INTEGRITY", "baked header or array bytes changed");
+  for (const key of Object.keys(arrays)) arrays[key] = arrays[key]?.slice();
+  const { arrays: _sections, ...data } = header;
+  const objects = [data];
+  while (objects.length > 0) {
+    const object = objects.pop();
+    if (!object) break;
+    for (const value of Object.values(object))
+      if (value !== null && typeof value === "object") objects.push(value);
+    Object.freeze(object);
+  }
+  const bake = Object.freeze({ ...data, ...arrays });
+  validatedBakes.add(bake);
+  return bake;
+}
+
+// src/build.ts
+var ANIMAL_BUILD_NODE = "20.19.6";
+var donorRoot = path.dirname(
+  createRequire(import.meta.url).resolve("procedural-animals/package.json")
+);
+var digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function normalized(options) {
+  if (!process.versions.node.startsWith(`${ANIMAL_BUILD_NODE.split(".")[0]}.`))
+    throw animalError(
+      "BUILD_RUNTIME",
+      `baking requires Node ${ANIMAL_BUILD_NODE.split(".")[0]}.x (reference ${ANIMAL_BUILD_NODE}); found ${process.versions.node}`
+    );
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw animalError("OPTIONS", "wolf options must be an object");
+  for (const key of Object.keys(options))
+    if (!["seed", "tier", "sex", "age", "variant"].includes(key))
+      throw animalError("OPTIONS", `unknown wolf option ${key}`);
+  if (!Number.isSafeInteger(options.seed) || options.seed < 0 || options.seed > 4294967295)
+    throw animalError("OPTIONS", "seed must be an unsigned 32-bit integer");
+  if (options.tier !== "high" && options.tier !== "crowd")
+    throw animalError("OPTIONS", "tier must be high or crowd");
+  for (const [key, allowed] of [
+    ["sex", ["male", "female"]],
+    ["age", ["adult", "juvenile"]],
+    ["variant", ["grey", "black", "pale", "tawny"]]
+  ]) {
+    const value = options[key];
+    if (value !== void 0 && !allowed.includes(value))
+      throw animalError("OPTIONS", `unsupported ${key}`);
+  }
+  return {
+    seed: options.seed,
+    tier: options.tier,
+    sex: options.sex,
+    age: options.age,
+    variant: options.variant
+  };
+}
+async function bakeWolf(options) {
+  const o = normalized(options);
+  const definitionHash = digest(await readFile(path.join(donorRoot, "src/species/wolf/index.js")));
+  const cacheKey = digest(
+    JSON.stringify({
+      donor: ANIMAL_DONOR_REVISION,
+      adapter: ANIMAL_ADAPTER_VERSION,
+      runtime: `node-v${ANIMAL_BUILD_NODE}`,
+      definitionHash,
+      species: "wolf",
+      options: o
+    })
+  );
+  clearBuildCache();
+  const generated = await buildAnimalData(wolf, {
+    seed: o.seed,
+    quality: o.tier,
+    sex: o.sex,
+    age: o.age,
+    variant: o.variant,
+    worker: false
+  });
+  const stats = { ...generated.stats };
+  for (const key of ["weightsMs", "coatMs", "buildMs"]) delete stats[key];
+  const metadata = {
+    donorRevision: ANIMAL_DONOR_REVISION,
+    adapterVersion: ANIMAL_ADAPTER_VERSION,
+    buildRuntime: `node-v${ANIMAL_BUILD_NODE}`,
+    cacheKey
+  };
+  const data = { ...generated, stats, threenative: metadata };
+  const integrity = bakeIntegrity(writeBake(data));
+  const bytes = writeBake({ ...data, threenative: { ...metadata, integrity } });
+  const bake = parseAnimalBake(bytes);
+  if (bake.quality === "crowd" && (bake.nV > 8e3 || bake.bones.length > 128))
+    throw animalError("CROWD_LIMIT", `wolf has ${bake.nV} vertices/${bake.bones.length} bones`);
+  return bytes;
+}
+async function bakeWolfToFile(options, destination) {
+  if (!destination.endsWith(".animal"))
+    throw animalError("OPTIONS", "destination must end in .animal");
+  const bytes = await bakeWolf(options);
+  await mkdir(path.dirname(destination), { recursive: true });
+  const temporary = `${destination}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, new Uint8Array(bytes), { flag: "wx" });
+    await rename(temporary, destination);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return digest(new Uint8Array(bytes));
+}
+function animalBakePass() {
+  return {
+    name: "animal-bake",
+    appliesTo: ["other"],
+    cacheKey: `${ANIMAL_DONOR_REVISION}:${ANIMAL_ADAPTER_VERSION}:node-v${ANIMAL_BUILD_NODE}`,
+    apply(input, logicalPath) {
+      if (!logicalPath.endsWith(".animal")) return input;
+      const bake = parseAnimalBake(Uint8Array.from(input).buffer);
+      return {
+        buffer: input,
+        entry: {
+          animal: {
+            species: bake.species,
+            seed: bake.seed,
+            tier: bake.quality,
+            vertices: bake.nV,
+            bones: bake.bones.length,
+            sha256: digest(input)
+          }
+        }
+      };
+    }
+  };
+}
+
+export { ANIMAL_BUILD_NODE, animalBakePass, bakeWolf, bakeWolfToFile };

package/dist/format-BRFFv-ws.d.ts

@@ -0,0 +1,44 @@
+declare const ANIMAL_DONOR_REVISION = "c95ae49346aa8e140a924376cec6cf0073d99512";
+declare const ANIMAL_ADAPTER_VERSION = 1;
+type AnimalTier = "high" | "crowd";
+type AnimalPoint = readonly [number, number, number];
+interface IAnimalBone {
+    readonly name: string;
+    readonly parent: string | null;
+    readonly headJ: string;
+    readonly tailJ: string;
+    readonly region?: string;
+    readonly group?: string;
+}
+interface IAnimalBake {
+    readonly version: 1;
+    readonly species: "wolf";
+    readonly seed: number;
+    readonly quality: AnimalTier;
+    readonly nV: number;
+    readonly bones: readonly IAnimalBone[];
+    readonly joints: Readonly<Record<string, AnimalPoint>>;
+    readonly refJoints: Readonly<Record<string, AnimalPoint>>;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly threenative: {
+        readonly donorRevision: typeof ANIMAL_DONOR_REVISION;
+        readonly adapterVersion: typeof ANIMAL_ADAPTER_VERSION;
+        readonly buildRuntime: string;
+        readonly cacheKey: string;
+        readonly integrity: string;
+    };
+    readonly pos: Float32Array;
+    readonly nrm: Float32Array;
+    readonly index: Uint32Array;
+    readonly skinIndex: Uint16Array;
+    readonly skinWeight: Float32Array;
+    readonly comb: Float32Array;
+    readonly tint: Float32Array;
+    readonly coat: Float32Array;
+    readonly pat: Float32Array;
+    readonly surf: Float32Array;
+}
+/** Validate all PANM bytes before a caller creates any Three.js/GPU object. */
+declare function parseAnimalBake(buffer: ArrayBuffer): IAnimalBake;
+
+export { type AnimalTier as A, type IAnimalBake as I, type IAnimalBone as a, parseAnimalBake as p };

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { I as IAnimalBake } from './format-BRFFv-ws.js';
+export { A as AnimalTier, a as IAnimalBone, p as parseAnimalBake } from './format-BRFFv-ws.js';
+import * as three from 'three';
+import { BufferGeometry, Bone, Matrix4, DataTexture, Vector3, Material, Object3D, Group, Mesh } from 'three';
+
+interface IAnimalAssetResolver {
+    resolve(path: string): Promise<readonly string[]>;
+}
+/** Resolve a cooked logical asset with ctx.assets and load only a validated bake. */
+declare function loadAnimalBake(assets: IAnimalAssetResolver, logicalPath: string, options?: {
+    readonly signal?: AbortSignal;
+}): Promise<IAnimalBake>;
+/** Create geometry only after the complete binary has passed validation. */
+declare function createAnimalGeometry(buffer: ArrayBuffer): {
+    readonly bake: IAnimalBake;
+    readonly geometry: BufferGeometry;
+};
+
+interface IAnimalSkeleton {
+    readonly bones: readonly Bone[];
+    readonly bind: readonly Matrix4[];
+    readonly inverses: readonly Matrix4[];
+}
+interface IAnimalPose {
+    readonly skeleton: IAnimalSkeleton;
+    readonly data: Float32Array;
+    readonly texture: DataTexture;
+    update(worldToLocal: Matrix4): void;
+    dispose(): void;
+}
+
+type AnimalActionResult = "done" | "interrupted" | "stopped" | "refused" | "disposed";
+interface IAnimalMotion {
+    readonly input: {
+        speed: number;
+        target: unknown;
+        heading: number;
+        follow: {
+            position: Vector3;
+            velocity: Vector3;
+            heading: number;
+        } | null;
+    };
+    update(dt: number): void;
+    reset(position: Vector3, heading: number): void;
+    play(name: string): Promise<AnimalActionResult>;
+    dispose(): void;
+}
+interface IAnimalMotionContext {
+    readonly data: IAnimalBake;
+    readonly skeleton: IAnimalSkeleton;
+    readonly ground: (x: number, z: number) => number;
+    readonly position: Vector3;
+    readonly heading: number;
+    readonly emit: (name: string, data: unknown) => void;
+}
+interface IAnimalAcceptedState {
+    readonly position: Readonly<Pick<Vector3, "x" | "y" | "z">>;
+    readonly velocity: Readonly<Pick<Vector3, "x" | "y" | "z">>;
+    readonly heading: number;
+}
+interface IAnimalActorOptions {
+    readonly motion: (context: IAnimalMotionContext) => IAnimalMotion;
+    readonly material: (pose: IAnimalPose) => Material;
+    readonly ground: (x: number, z: number) => number;
+    readonly parent?: Object3D;
+    /** Game's rig origin relative to the physics origin (capsules are centred). Reported verbatim. */
+    readonly visualOriginOffset?: Readonly<Pick<Vector3, "x" | "y" | "z">>;
+}
+/**
+ * Own one actor's pose/lifetime, accepting the completed physics state as its only root writer.
+ * @situation follow a baked animal from accepted fixed-step Rapier state
+ * @constraint identity parent required; material and motion are editable game source; no move/Mixer/composer writer exists
+ * @requires npm i @threenative/procedural-animals
+ * @example const wolf = createAnimalActor(bake, { motion, material, ground });
+ */
+declare function createAnimalActor(bake: IAnimalBake, options: IAnimalActorOptions): {
+    object: Group<three.Object3DEventMap>;
+    mesh: Mesh<three.BufferGeometry<three.NormalBufferAttributes, three.BufferGeometryEventMap>, Material<three.MaterialEventMap>, three.Object3DEventMap>;
+    pose: IAnimalPose;
+    bounds: {
+        sphere: three.Sphere;
+        box: three.Box3;
+        update(data: Float32Array): void;
+    };
+    /** Measurement survives the explicit origin override. */
+    visualOriginOffset: Vector3;
+    paused: boolean;
+    follow(state: IAnimalAcceptedState, dt: number): void;
+    teleport(state: IAnimalAcceptedState): void;
+    play(name: "stand" | "sit" | "lie"): Promise<AnimalActionResult>;
+    dispose: () => void;
+};
+
+export { type AnimalActionResult, type IAnimalAcceptedState, type IAnimalActorOptions, type IAnimalAssetResolver, IAnimalBake, type IAnimalMotion, type IAnimalMotionContext, type IAnimalPose, type IAnimalSkeleton, createAnimalActor, createAnimalGeometry, loadAnimalBake };