@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/model-import/formats/obj-model-format-adapter.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+
+import { decodeToolcraftModelDocument } from "../canonical/model-document-codec";
+import { validateToolcraftModelDocument } from "../canonical/model-document-validation";
+import { TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS } from "../model-import-limits";
+import { digestModelSourceBytes } from "../model-source-digest";
+import {
+  contextFor,
+  OBJ_STATIC_GEOMETRY_FIXTURE,
+  transferForStaticModelBytes,
+} from "../test-fixtures/model-fixtures";
+import { createObjAppearanceTransfer } from "../test-fixtures/obj-appearance-fixtures";
+import { createToolcraftModelWorkerRuntime } from "../worker/model-import-worker-runtime";
+import type { ToolcraftModelWorkerResponse } from "../worker/model-import-worker-protocol";
+import { createToolcraftModelFormatAdapterRegistry } from "./model-format-adapter";
+import {
+  TOOLCRAFT_OBJ_ADAPTER_VERSION,
+  toolcraftObjModelFormatAdapter,
+} from "./obj-model-format-adapter";
+import { TOOLCRAFT_PRODUCTION_MODEL_FORMAT_ADAPTER_REGISTRY } from "./production-model-format-registry";
+
+const encoder = new TextEncoder();
+
+function context(bytes = OBJ_STATIC_GEOMETRY_FIXTURE) {
+  return contextFor(
+    transferForStaticModelBytes(bytes, "models/scene.obj", "model/obj"),
+  );
+}
+
+describe("OBJ model format adapter", () => {
+  it("is an immutable worker-capable production adapter", () => {
+    expect(toolcraftObjModelFormatAdapter).toMatchObject({
+      adapterVersion: TOOLCRAFT_OBJ_ADAPTER_VERSION,
+      format: "obj",
+      rootExtensions: [".obj"],
+      workerCapable: true,
+    });
+    expect(Object.isFrozen(toolcraftObjModelFormatAdapter)).toBe(true);
+    expect(
+      createToolcraftModelFormatAdapterRegistry([
+        toolcraftObjModelFormatAdapter,
+      ]).adapters,
+    ).toEqual([toolcraftObjModelFormatAdapter]);
+    const productionFormats =
+      TOOLCRAFT_PRODUCTION_MODEL_FORMAT_ADAPTER_REGISTRY.adapters.map(
+        ({ format }) => format,
+      );
+    expect(productionFormats).toEqual([
+      "glb", "gltf", "fbx", "obj", "stl", "ply",
+    ]);
+  });
+
+  it("preserves OBJ object hierarchy, separate geometry, and source coordinates", async () => {
+    const decodeContext = context();
+    expect(decodeContext.bundle.rootPath).toBe("models/scene.obj");
+    expect(decodeContext.bundle.sourceFiles[0]!.path).toBe("models/scene.obj");
+    expect(decodeContext.bundle.sourceFiles[0]!.bytes.byteLength).toBeGreaterThan(0);
+    const result = await toolcraftObjModelFormatAdapter.decode(decodeContext);
+
+    expect(validateToolcraftModelDocument(result.document)).toEqual({ ok: true });
+    expect(result.document.rootNodeIds).toEqual(["node:0"]);
+    expect(result.document.nodes.map(({ id, name, primitiveIds }) => ({ id, name, primitiveIds }))).toEqual([
+      { id: "node:0", name: "", primitiveIds: [] },
+      { id: "node:1", name: "First", primitiveIds: ["primitive:0"] },
+      { id: "node:2", name: "Second", primitiveIds: ["primitive:1"] },
+    ]);
+    expect(result.document.primitives[0]!.positions).toEqual(
+      new Float32Array([10, 20, 30, 12, 20, 30, 10, 23, 30]),
+    );
+    expect(result.document.primitives[1]!.positions).toEqual(
+      new Float32Array([-4, -2, 1, -2, -2, 1, -4, -1, 1]),
+    );
+    expect(result.document.bounds).toEqual({
+      max: [12, 23, 30],
+      min: [-4, -2, 1],
+    });
+    expect(result.document.provenance).toEqual({
+      adapterVersion: TOOLCRAFT_OBJ_ADAPTER_VERSION,
+      canonicalSchemaVersion: 2,
+      operations: ["sequential-indexing"],
+      sourceFormat: "obj",
+    });
+    expect(result.document.version).toBe(2);
+    if (result.document.version !== 2) throw new Error("Expected v2 document.");
+    expect(result.document.materials).toEqual([]);
+    expect(result.document.textures).toEqual([]);
+    expect(result.diagnostics.map(({ code }) => code)).toEqual([
+      "missing-material-library",
+      "missing-material-definition",
+      "missing-material-definition",
+    ]);
+  });
+
+  it("preserves MTL material groups, UVs, and local texture resources", async () => {
+    const result = await toolcraftObjModelFormatAdapter.decode(
+      contextFor(createObjAppearanceTransfer()),
+    );
+
+    expect(validateToolcraftModelDocument(result.document)).toEqual({ ok: true });
+    expect(result.document.version).toBe(2);
+    if (result.document.version !== 2) throw new Error("Expected v2 document.");
+    expect(result.document.nodes.map(({ name, primitiveIds }) => ({
+      name,
+      primitiveIds,
+    }))).toEqual([
+      { name: "", primitiveIds: [] },
+      { name: "Painted", primitiveIds: ["primitive:0", "primitive:1"] },
+    ]);
+    expect(result.document.primitives).toHaveLength(2);
+    expect(result.document.primitives.map(({ materialId }) => materialId)).toEqual([
+      "material:0",
+      "material:1",
+    ]);
+    expect(result.document.primitives[0]!.textureCoordinates?.[0]?.values).toEqual(
+      new Float32Array([0, 0, 1, 0, 0, 1]),
+    );
+    expect(result.document.primitives[1]!.positions).toEqual(
+      new Float32Array([2, 0, 0, 3, 0, 0, 2, 1, 0]),
+    );
+    expect(result.document.materials[0]).toMatchObject({
+      alphaMode: "blend",
+      baseColor: [0.2, 0.3, 0.4],
+      emissive: [0.1, 0.2, 0.3],
+      normalTexture: { scale: 0.4 },
+      opacity: 0.75,
+      roughness: 0.1,
+    });
+    expect(result.document.materials[1]).toMatchObject({
+      baseColor: [0.9, 0.8, 0.7],
+      opacity: 0.75,
+      roughness: 1,
+    });
+    expect(result.document.materials[1]!.baseColorTexture).toBeUndefined();
+    expect(result.document.textures).toHaveLength(2);
+    expect(result.appearanceResources).toHaveLength(2);
+    expect(result.diagnostics).toContainEqual(expect.objectContaining({
+      code: "missing-appearance-resource",
+      severity: "warning",
+    }));
+  });
+
+  it.each([
+    ["empty", encoder.encode("# no geometry\n")],
+    ["non-finite", encoder.encode("v 0 0 0\nv 1 0 0\nv NaN 1 0\nf 1 2 3\n")],
+    ["malformed face", encoder.encode("v 0 0 0\nv 1 0 0\nf 1 2 9\n")],
+  ])("rejects %s OBJ structures", async (_name, bytes) => {
+    await expect(toolcraftObjModelFormatAdapter.decode(context(bytes))).rejects.toMatchObject({
+      category: "geometry",
+    });
+  });
+
+  it("records deterministic polygon triangulation and sequential indexing", async () => {
+    const result = await toolcraftObjModelFormatAdapter.decode(
+      context(
+        encoder.encode(
+          "v 0 0 0\nv 2 0 0\nv 2 2 0\nv 0 2 0\nf 1 2 3 4\n",
+        ),
+      ),
+    );
+    expect(result.document.primitives[0]!.indices).toEqual(
+      new Uint32Array([0, 1, 2, 3, 4, 5]),
+    );
+    expect(result.document.provenance.operations).toEqual([
+      "deterministic-triangulation",
+      "sequential-indexing",
+    ]);
+  });
+
+  it("enforces cancellation and canonical limits", async () => {
+    const aborted = new AbortController();
+    aborted.abort();
+    await expect(
+      toolcraftObjModelFormatAdapter.decode(
+        contextFor(transferForStaticModelBytes(OBJ_STATIC_GEOMETRY_FIXTURE, "scene.obj"), {
+          signal: aborted.signal,
+        }),
+      ),
+    ).rejects.toMatchObject({ name: "AbortError" });
+
+    await expect(
+      toolcraftObjModelFormatAdapter.decode({
+        ...context(),
+        limits: { ...context().limits, maxPrimitives: 1 },
+      }),
+    ).rejects.toMatchObject({
+      category: "resource-limit",
+      code: "max-primitives-exceeded",
+    });
+
+    await expect(
+      toolcraftObjModelFormatAdapter.decode({
+        ...context(),
+        limits: {
+          ...context().limits,
+          maxSourceBytes: OBJ_STATIC_GEOMETRY_FIXTURE.byteLength - 1,
+        },
+      }),
+    ).rejects.toMatchObject({
+      category: "resource-limit",
+      code: "source-byte-limit-exceeded",
+    });
+  });
+
+  it("decodes through the existing worker runtime when explicitly injected", async () => {
+    const sourceCopy = new Uint8Array(OBJ_STATIC_GEOMETRY_FIXTURE.byteLength);
+    sourceCopy.set(OBJ_STATIC_GEOMETRY_FIXTURE);
+    const bytes = sourceCopy.buffer;
+    const responses: ToolcraftModelWorkerResponse[] = [];
+    const runtime = createToolcraftModelWorkerRuntime({
+      adapters: [toolcraftObjModelFormatAdapter],
+      geometryDecoderVersions: { obj: "three@0.185.1" },
+      post: (response) => responses.push(response),
+    });
+
+    await runtime.handleMessage({
+      generation: 1,
+      jobId: "obj-worker-fixture",
+      kind: "decode-and-analyze",
+      payload: {
+        adapterVersion: TOOLCRAFT_OBJ_ADAPTER_VERSION,
+        bundle: {
+          aggregateDigest: "fixture-obj-worker",
+          rootPath: "scene.obj",
+          sourceFiles: [{
+            bytes,
+            contentDigest: digestModelSourceBytes(new Uint8Array(bytes)),
+            mimeType: "model/obj",
+            path: "scene.obj",
+          }],
+        },
+        format: "obj",
+        geometryDecoderVersion: "three@0.185.1",
+        limits: TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS,
+        topologyProfile: "realtime-mesh",
+      },
+    });
+
+    expect(responses.find(({ kind }) => kind === "error")).toBeUndefined();
+    expect(responses.some(({ kind }) => kind === "draft")).toBe(true);
+    const terminal = responses.find(({ kind }) => kind === "result");
+    expect(terminal?.kind).toBe("result");
+    if (terminal?.kind !== "result") throw new Error("Missing worker result.");
+    expect(
+      decodeToolcraftModelDocument(
+        new Uint8Array(terminal.result.canonicalDocument),
+        TOOLCRAFT_DEFAULT_MODEL_IMPORT_LIMITS,
+      ).provenance.sourceFormat,
+    ).toBe("obj");
+    runtime.dispose();
+  });
+});

package/templates/runtime/model-import/formats/obj-model-format-adapter.ts

@@ -0,0 +1,85 @@
+import { OBJLoader } from "three/examples/jsm/loaders/OBJLoader.js";
+
+import type {
+  ToolcraftModelDecodeContext,
+  ToolcraftModelDecodeResult,
+  ToolcraftModelFormatAdapter,
+} from "../model-import-types";
+import {
+  threeStaticGeometryFailure,
+  throwIfThreeStaticGeometryAborted,
+  ToolcraftThreeStaticGeometryError,
+} from "./obj-stl-ply-model-format-adapter-support";
+import { loadObjMaterialLibrary } from "./obj-material-library";
+import { readThreeStaticGeometryBundle } from "./three-static-source-bundle";
+import { canonicalizeThreeStaticGeometry } from "./three-static-geometry-canonicalizer";
+import { TOOLCRAFT_OBJ_ADAPTER_VERSION } from "./production-model-format-manifest";
+
+export { TOOLCRAFT_OBJ_ADAPTER_VERSION } from "./production-model-format-manifest";
+
+function sourceUsesPolygonFaces(source: string): boolean {
+  return source.split(/\r\n|\r|\n/u).some((line) => {
+    const tokens = line.trim().split(/\s+/u);
+    return tokens[0] === "f" && tokens.length > 4;
+  });
+}
+
+async function decodeObj(
+  context: ToolcraftModelDecodeContext,
+): Promise<ToolcraftModelDecodeResult> {
+  const bundle = readThreeStaticGeometryBundle(context, "obj");
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bundle.root.bytes);
+  } catch {
+    return threeStaticGeometryFailure(
+      "format",
+      "invalid-obj-encoding",
+      "OBJ text must use valid UTF-8 encoding.",
+    );
+  }
+  throwIfThreeStaticGeometryAborted(context.signal);
+  try {
+    const materialLibrary = loadObjMaterialLibrary(
+      text,
+      bundle,
+      context.limits,
+      context.signal,
+    );
+    const object = new OBJLoader().parse(text);
+    throwIfThreeStaticGeometryAborted(context.signal);
+    return canonicalizeThreeStaticGeometry(object, {
+      adapterVersion: TOOLCRAFT_OBJ_ADAPTER_VERSION,
+      appearance: {
+        diagnostics: materialLibrary.diagnostics,
+        resolveMaterial: (material) => material
+          ? materialLibrary.materialsByName.get(material.name)
+          : undefined,
+      },
+      limits: context.limits,
+      operations: sourceUsesPolygonFaces(text)
+        ? ["deterministic-triangulation"]
+        : [],
+      signal: context.signal,
+      sourceByteLength: bundle.sourceByteLength,
+      sourceFormat: "obj",
+    });
+  } catch (error) {
+    throwIfThreeStaticGeometryAborted(context.signal);
+    if (error instanceof ToolcraftThreeStaticGeometryError) throw error;
+    return threeStaticGeometryFailure(
+      "format",
+      "obj-decode-failed",
+      "The OBJ geometry could not be decoded safely.",
+    );
+  }
+}
+
+export const toolcraftObjModelFormatAdapter: ToolcraftModelFormatAdapter =
+  Object.freeze({
+    adapterVersion: TOOLCRAFT_OBJ_ADAPTER_VERSION,
+    decode: decodeObj,
+    format: "obj",
+    rootExtensions: Object.freeze([".obj"]),
+    workerCapable: true,
+  });

package/templates/runtime/model-import/formats/obj-stl-ply-model-format-adapter-support.ts

@@ -0,0 +1,335 @@
+import {
+  Matrix4,
+  type BufferAttribute,
+  type InterleavedBufferAttribute,
+  type Object3D,
+} from "three";
+
+import type { ToolcraftModelFormat } from "../../schema/types";
+import type { ToolcraftSourceAssetFeedback } from "../../source-assets/source-asset-types";
+import type {
+  ToolcraftModelBounds,
+  ToolcraftModelDocument,
+  ToolcraftModelPrimitiveV2,
+} from "../canonical/model-document";
+import { TOOLCRAFT_MODEL_IMPORT_LIMIT_CEILINGS } from "../model-import-limit-values";
+import type { ToolcraftModelDecodeContext } from "../model-import-types";
+
+export type ThreeStaticGeometryFormat = Extract<
+  ToolcraftModelFormat,
+  "fbx" | "obj" | "ply" | "stl"
+>;
+export type ThreeStaticGeometryAttribute =
+  | BufferAttribute
+  | InterleavedBufferAttribute;
+export type ThreeStaticGeometryPrimitivePlan = Readonly<{
+  color?: ThreeStaticGeometryAttribute;
+  drawCount: number;
+  drawStart: number;
+  index: BufferAttribute | null;
+  normal?: ThreeStaticGeometryAttribute;
+  position: ThreeStaticGeometryAttribute;
+  primitiveId: string;
+  textureCoordinates?: readonly Readonly<{
+    attribute: ThreeStaticGeometryAttribute;
+    set: 0 | 1;
+  }>[];
+}>;
+
+export class ToolcraftThreeStaticGeometryError
+  extends Error
+  implements ToolcraftSourceAssetFeedback
+{
+  readonly category: ToolcraftSourceAssetFeedback["category"];
+  readonly code: string;
+
+  constructor(
+    category: ToolcraftSourceAssetFeedback["category"],
+    code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ToolcraftThreeStaticGeometryError";
+    this.category = category;
+    this.code = code;
+  }
+}
+
+export function threeStaticGeometryFailure(
+  category: ToolcraftSourceAssetFeedback["category"],
+  code: string,
+  message: string,
+): never {
+  throw new ToolcraftThreeStaticGeometryError(category, code, message);
+}
+
+export function throwIfThreeStaticGeometryAborted(signal: AbortSignal): void {
+  if (!signal.aborted) return;
+  throw signal.reason ?? new DOMException("Model decode was cancelled.", "AbortError");
+}
+
+function checkpoint(signal: AbortSignal, index: number): void {
+  if ((index & 255) === 0) throwIfThreeStaticGeometryAborted(signal);
+}
+
+export function getThreeStaticGeometryAttributeArray(
+  attribute: ThreeStaticGeometryAttribute,
+): ArrayBufferView {
+  return "isInterleavedBufferAttribute" in attribute &&
+      attribute.isInterleavedBufferAttribute
+    ? attribute.data.array
+    : attribute.array;
+}
+
+function boundsForPositions(positions: Float32Array): ToolcraftModelBounds {
+  const min: [number, number, number] = [positions[0]!, positions[1]!, positions[2]!];
+  const max: [number, number, number] = [...min];
+  for (let offset = 3; offset < positions.length; offset += 3) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis], positions[offset + axis]!);
+      max[axis] = Math.max(max[axis], positions[offset + axis]!);
+    }
+  }
+  return { max, min };
+}
+
+function sourceIndex(
+  plan: ThreeStaticGeometryPrimitivePlan,
+  drawOffset: number,
+): number {
+  return plan.index?.getX(plan.drawStart + drawOffset) ??
+    plan.drawStart + drawOffset;
+}
+
+export function countThreeStaticGeometryPrimitiveVertices(
+  plan: ThreeStaticGeometryPrimitivePlan,
+  signal: AbortSignal,
+): number {
+  const indices = new Set<number>();
+  for (let drawOffset = 0; drawOffset < plan.drawCount; drawOffset += 1) {
+    checkpoint(signal, drawOffset);
+    const index = sourceIndex(plan, drawOffset);
+    if (!Number.isInteger(index) || index < 0 || index >= plan.position.count) {
+      return threeStaticGeometryFailure(
+        "geometry",
+        "index-out-of-range",
+        "Decoded triangle indices must be integers within the position range.",
+      );
+    }
+    indices.add(index);
+  }
+  return indices.size;
+}
+
+function createVertexRemap(
+  plan: ThreeStaticGeometryPrimitivePlan,
+  signal: AbortSignal,
+): Readonly<{ indices: Uint32Array; sourceIndices: readonly number[] }> {
+  const usedSources = new Set<number>();
+  for (let drawOffset = 0; drawOffset < plan.drawCount; drawOffset += 1) {
+    checkpoint(signal, drawOffset);
+    usedSources.add(sourceIndex(plan, drawOffset));
+  }
+  const sourceIndices = [...usedSources].sort((left, right) => left - right);
+  const canonicalBySource = new Map(
+    sourceIndices.map((source, canonical) => [source, canonical]),
+  );
+  const indices = new Uint32Array(plan.drawCount);
+  for (let drawOffset = 0; drawOffset < plan.drawCount; drawOffset += 1) {
+    checkpoint(signal, drawOffset);
+    indices[drawOffset] = canonicalBySource.get(sourceIndex(plan, drawOffset))!;
+  }
+  return { indices, sourceIndices };
+}
+
+function copyVec3(
+  attribute: ThreeStaticGeometryAttribute,
+  label: "normal" | "position",
+  sourceIndices: readonly number[],
+  signal: AbortSignal,
+): Float32Array {
+  const copy = new Float32Array(sourceIndices.length * 3);
+  for (let index = 0; index < sourceIndices.length; index += 1) {
+    checkpoint(signal, index);
+    const source = sourceIndices[index]!;
+    const values = [
+      attribute.getX(source),
+      attribute.getY(source),
+      attribute.getZ(source),
+    ];
+    for (let axis = 0; axis < 3; axis += 1) {
+      const value = values[axis]!;
+      copy[index * 3 + axis] = value;
+      if (!Number.isFinite(value) || !Number.isFinite(copy[index * 3 + axis])) {
+        return threeStaticGeometryFailure(
+          "geometry",
+          `non-finite-${label}`,
+          `Decoded ${label} data must contain only finite Float32 values.`,
+        );
+      }
+    }
+  }
+  return copy;
+}
+
+function copyTextureCoordinates(
+  attribute: ThreeStaticGeometryAttribute,
+  sourceIndices: readonly number[],
+  signal: AbortSignal,
+): Float32Array {
+  const values = new Float32Array(sourceIndices.length * 2);
+  for (let index = 0; index < sourceIndices.length; index += 1) {
+    checkpoint(signal, index);
+    const source = sourceIndices[index]!;
+    const u = attribute.getX(source);
+    const v = attribute.getY(source);
+    if (!Number.isFinite(u) || !Number.isFinite(v)) {
+      return threeStaticGeometryFailure(
+        "geometry",
+        "non-finite-texture-coordinate",
+        "Decoded texture coordinates must be finite.",
+      );
+    }
+    values[index * 2] = u;
+    values[index * 2 + 1] = v;
+  }
+  return values;
+}
+
+function copyColors(
+  attribute: ThreeStaticGeometryAttribute,
+  sourceIndices: readonly number[],
+  signal: AbortSignal,
+): ToolcraftModelPrimitiveV2["colors"] {
+  const components = attribute.itemSize === 3 ? 3 : 4;
+  const values = new Float32Array(sourceIndices.length * components);
+  for (let index = 0; index < sourceIndices.length; index += 1) {
+    checkpoint(signal, index);
+    const source = sourceIndices[index]!;
+    const channels = [
+      attribute.getX(source),
+      attribute.getY(source),
+      attribute.getZ(source),
+      attribute.getW(source),
+    ];
+    for (let channel = 0; channel < components; channel += 1) {
+      const value = channels[channel]!;
+      if (!Number.isFinite(value) || value < 0 || value > 1) {
+        return threeStaticGeometryFailure(
+          "geometry",
+          "invalid-vertex-color",
+          "Decoded vertex colors must be finite values from 0 through 1.",
+        );
+      }
+      values[index * components + channel] = value;
+    }
+  }
+  return { components, values };
+}
+
+export function copyThreeStaticGeometryPrimitive(
+  plan: ThreeStaticGeometryPrimitivePlan,
+  signal: AbortSignal,
+  materialId?: string,
+): ToolcraftModelPrimitiveV2 {
+  const remap = createVertexRemap(plan, signal);
+  const positions = copyVec3(
+    plan.position,
+    "position",
+    remap.sourceIndices,
+    signal,
+  );
+  return {
+    bounds: boundsForPositions(positions),
+    ...(plan.color
+      ? { colors: copyColors(plan.color, remap.sourceIndices, signal) }
+      : {}),
+    id: plan.primitiveId,
+    indices: remap.indices,
+    ...(materialId ? { materialId } : {}),
+    ...(plan.normal
+      ? {
+          normals: copyVec3(
+            plan.normal,
+            "normal",
+            remap.sourceIndices,
+            signal,
+          ),
+        }
+      : {}),
+    positions,
+    ...(plan.textureCoordinates
+      ? {
+          textureCoordinates: plan.textureCoordinates.map(({ attribute, set }) => ({
+            set,
+            values: copyTextureCoordinates(
+              attribute,
+              remap.sourceIndices,
+              signal,
+            ),
+          })),
+        }
+      : {}),
+  };
+}
+
+export function getThreeStaticGeometryLocalMatrix(
+  node: Object3D,
+): ToolcraftModelDocument["nodes"][number]["localMatrix"] {
+  const matrix = node.matrixAutoUpdate
+    ? new Matrix4().compose(node.position, node.quaternion, node.scale)
+    : node.matrix;
+  const values = matrix.toArray();
+  if (values.some((value) => !Number.isFinite(value))) {
+    return threeStaticGeometryFailure(
+      "geometry",
+      "non-finite-node-transform",
+      "Decoded node transforms must contain only finite values.",
+    );
+  }
+  return values as ToolcraftModelDocument["nodes"][number]["localMatrix"];
+}
+
+export function checkedThreeStaticGeometryTotal(
+  current: number,
+  additional: number,
+  limit: number,
+  code: string,
+  label: string,
+): number {
+  if (
+    !Number.isSafeInteger(current) ||
+    !Number.isSafeInteger(additional) ||
+    current < 0 ||
+    additional < 0 ||
+    current > limit - additional
+  ) {
+    return threeStaticGeometryFailure(
+      "resource-limit",
+      code,
+      `${label} exceeds the configured limit ${limit}.`,
+    );
+  }
+  return current + additional;
+}
+
+export function validateThreeStaticGeometryLimits(
+  limits: ToolcraftModelDecodeContext["limits"],
+): void {
+  for (const name of Object.keys(
+    TOOLCRAFT_MODEL_IMPORT_LIMIT_CEILINGS,
+  ) as Array<keyof typeof TOOLCRAFT_MODEL_IMPORT_LIMIT_CEILINGS>) {
+    const value = limits[name];
+    if (
+      !Number.isSafeInteger(value) ||
+      value <= 0 ||
+      value > TOOLCRAFT_MODEL_IMPORT_LIMIT_CEILINGS[name]
+    ) {
+      return threeStaticGeometryFailure(
+        "resource-limit",
+        "invalid-import-limits",
+        `Model import limit ${name} is outside its protected integer range.`,
+      );
+    }
+  }
+}