@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/model-import/topology/apply-model-repair.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from "vitest";
+
+import { digestToolcraftModelDocument } from "../canonical/model-document-digest";
+import {
+  createModelMaterial,
+  createModelTexture,
+  createValidModelDocumentV2,
+} from "../canonical/model-document-test-support";
+import { validateToolcraftModelDocument } from "../canonical/model-document-validation";
+import { applyToolcraftModelRepair } from "./apply-model-repair";
+import { analyzeToolcraftModel } from "./model-topology-analysis";
+import { digestToolcraftTopologyDocument } from "./model-topology-digest";
+import {
+  boundsForPositions,
+  createClosedSolidWithDuplicatePrimitive,
+  createOpenPlanePrimitive,
+  createRepairablePrimitive,
+  createTopologyDocument,
+  createTopologyPrimitive,
+} from "./model-topology-test-support";
+
+describe("applyToolcraftModelRepair", () => {
+  it("proves a duplicate-triangle solid repair clean after application", () => {
+    const document = createTopologyDocument([
+      createClosedSolidWithDuplicatePrimitive(),
+    ]);
+    const analysis = analyzeToolcraftModel(document, "solid-mesh");
+    const repaired = applyToolcraftModelRepair(document, analysis.repairPlan!);
+
+    expect(repaired.primitives[0]!.indices.length / 3).toBe(4);
+    const proof = analyzeToolcraftModel(repaired, "solid-mesh");
+    expect(proof.outcome).toBe("clean");
+    expect(proof.repairPlan).toBeUndefined();
+  });
+
+  it("applies only the exact compiled operations and recalculates geometry", () => {
+    const document = createTopologyDocument([createRepairablePrimitive()]);
+    const analysis = analyzeToolcraftModel(document, "realtime-mesh");
+    const repaired = applyToolcraftModelRepair(document, analysis.repairPlan!);
+
+    expect(repaired.primitives[0]!.indices).toEqual(
+      new Uint32Array([0, 1, 2, 0, 2, 3]),
+    );
+    expect(repaired.primitives[0]!.positions.length).toBe(12);
+    expect(repaired.primitives[0]!.normals?.length).toBe(12);
+    expect([...repaired.primitives[0]!.normals!].every(Number.isFinite)).toBe(true);
+    expect(repaired.bounds).toEqual({ min: [0, 0, 0], max: [1, 1, 0] });
+    expect(repaired.provenance.repair?.operations).toEqual([
+      "remove-invalid-triangles",
+      "remove-duplicate-triangles",
+      "compact-unused-vertices",
+      "regenerate-normals",
+      "recalculate-bounds",
+    ]);
+    expect(validateToolcraftModelDocument(repaired)).toEqual({ ok: true });
+    expect(analyzeToolcraftModel(repaired, "realtime-mesh").outcome).toBe("clean");
+  });
+
+  it("repairs deterministic local winding", () => {
+    const document = createTopologyDocument([
+      createOpenPlanePrimitive({ indices: new Uint32Array([0, 1, 2, 0, 3, 2]) }),
+    ]);
+    const analysis = analyzeToolcraftModel(document, "realtime-mesh");
+    const repaired = applyToolcraftModelRepair(document, analysis.repairPlan!);
+
+    expect(repaired.primitives[0]!.indices).toEqual(
+      new Uint32Array([0, 1, 2, 0, 2, 3]),
+    );
+    expect(analyzeToolcraftModel(repaired, "realtime-mesh").diagnostics)
+      .not.toContainEqual(expect.objectContaining({ code: "inconsistent-local-winding" }));
+  });
+
+  it("preserves matrices, source scale, authored seams, and canonical input arrays", () => {
+    const positions = new Float32Array([
+      0, 0, 0, 1, 0, 0, 0, 1, 0,
+      0, 0, 0, 1, 0, 0, 0, -1, 0,
+    ]);
+    const primitive = createTopologyPrimitive({
+      bounds: boundsForPositions(positions),
+      indices: new Uint32Array([0, 1, 2, 3, 4, 5]),
+      normals: undefined,
+      positions,
+    });
+    const matrix = [
+      2, 0, 0, 0,
+      0, 3, 0, 0,
+      0, 0, 4, 0,
+      10, 20, 30, 1,
+    ] as const;
+    const document = createTopologyDocument([primitive], { localMatrix: matrix });
+    const originalPositions = primitive.positions.slice();
+    const originalIndices = primitive.indices.slice();
+    const originalBounds = structuredClone(document.bounds);
+    const repaired = applyToolcraftModelRepair(
+      document,
+      analyzeToolcraftModel(document, "realtime-mesh").repairPlan!,
+    );
+
+    expect(repaired.nodes[0]!.localMatrix).toEqual(matrix);
+    expect(repaired.primitives[0]!.positions).toEqual(positions);
+    expect(repaired.primitives[0]!.positions.length / 3).toBe(6);
+    expect(repaired.primitives[0]!.positions).not.toBe(primitive.positions);
+    expect(repaired.primitives[0]!.indices).not.toBe(primitive.indices);
+    expect(primitive.positions).toEqual(originalPositions);
+    expect(primitive.indices).toEqual(originalIndices);
+    expect(document.bounds).toEqual(originalBounds);
+  });
+
+  it("compacts every appearance vertex channel and preserves material bindings", () => {
+    const sourcePrimitive = createRepairablePrimitive();
+    const normals = new Float32Array([
+      0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1,
+      0, 0, 1, 0, 0, 1, 0, 0, 1,
+    ]);
+    const uv0 = new Float32Array([
+      0, 0, 1, 0, 1, 1, 0, 1, 2, 0, 3, 0, 5, 5,
+    ]);
+    const uv1 = new Float32Array([
+      0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8,
+      0.2, 0.3, 0.4, 0.5, 0.9, 0.9,
+    ]);
+    const colors = new Float32Array([
+      1, 0, 0, 1, 0, 1, 0, 0.9, 0, 0, 1, 0.8, 1, 1, 0, 0.7,
+      1, 0, 1, 0.6, 0, 1, 1, 0.5, 0.25, 0.5, 0.75, 0.4,
+    ]);
+    const texture = createModelTexture();
+    const material = createModelMaterial();
+    const document = createValidModelDocumentV2({
+      bounds: sourcePrimitive.bounds,
+      materials: [material],
+      primitives: [{
+        ...sourcePrimitive,
+        colors: { components: 4, values: colors },
+        materialId: material.id,
+        normals,
+        textureCoordinates: [
+          { set: 0, values: uv0 },
+          { set: 1, values: uv1 },
+        ],
+      }],
+      textures: [texture],
+    });
+    const analysis = analyzeToolcraftModel(document, "realtime-mesh");
+    const repaired = applyToolcraftModelRepair(document, analysis.repairPlan!);
+
+    expect(repaired.version).toBe(2);
+    if (repaired.version !== 2) throw new Error("Expected repaired appearance document.");
+    expect(repaired.primitives[0]!.positions.length / 3).toBe(4);
+    expect(repaired.primitives[0]!.normals).toEqual(normals.slice(0, 12));
+    expect(repaired.primitives[0]!.colors).toEqual({
+      components: 4,
+      values: colors.slice(0, 16),
+    });
+    expect(repaired.primitives[0]!.textureCoordinates).toEqual([
+      { set: 0, values: uv0.slice(0, 8) },
+      { set: 1, values: uv1.slice(0, 8) },
+    ]);
+    expect(repaired.primitives[0]!.materialId).toBe(material.id);
+    expect(repaired.materials).toEqual([material]);
+    expect(repaired.textures).toEqual([texture]);
+    expect(validateToolcraftModelDocument(repaired)).toEqual({ ok: true });
+  });
+
+  it("keeps topology identity independent from appearance schema and bindings", () => {
+    const geometry = createTopologyDocument();
+    const appearance = createValidModelDocumentV2({
+      bounds: geometry.bounds,
+      nodes: geometry.nodes,
+      primitives: geometry.primitives,
+      rootNodeIds: geometry.rootNodeIds,
+    });
+
+    expect(digestToolcraftTopologyDocument(appearance)).toBe(
+      digestToolcraftTopologyDocument(geometry),
+    );
+    expect(digestToolcraftModelDocument(appearance)).not.toBe(
+      digestToolcraftModelDocument(geometry),
+    );
+  });
+
+  it("produces deterministic plan digests, recipe ids, and repair provenance", () => {
+    const firstDocument = createTopologyDocument([createRepairablePrimitive()]);
+    const secondDocument = createTopologyDocument([createRepairablePrimitive()]);
+    const firstAnalysis = analyzeToolcraftModel(firstDocument, "realtime-mesh");
+    const secondAnalysis = analyzeToolcraftModel(secondDocument, "realtime-mesh");
+
+    expect(firstAnalysis.repairPlan?.planDigest).toMatch(/^sha256:[0-9a-f]{64}$/u);
+    expect(firstAnalysis.repairPlan?.planDigest).toBe(secondAnalysis.repairPlan?.planDigest);
+    expect(firstAnalysis.repairPlan?.recipeId).toBe(secondAnalysis.repairPlan?.recipeId);
+
+    const first = applyToolcraftModelRepair(firstDocument, firstAnalysis.repairPlan!);
+    const second = applyToolcraftModelRepair(secondDocument, secondAnalysis.repairPlan!);
+    expect(first.provenance.repair).toEqual(second.provenance.repair);
+    expect(first.provenance.repair).toMatchObject({
+      algorithmVersion: expect.any(String),
+      planDigest: firstAnalysis.repairPlan?.planDigest,
+      recipeId: firstAnalysis.repairPlan?.recipeId,
+    });
+    expect(first.primitives[0]!.positions).toEqual(second.primitives[0]!.positions);
+    expect(first.primitives[0]!.indices).toEqual(second.primitives[0]!.indices);
+    expect(first.primitives[0]!.normals).toEqual(second.primitives[0]!.normals);
+  });
+
+  it("contains no unsupported repair vocabulary or effects", () => {
+    const document = createTopologyDocument([createRepairablePrimitive()]);
+    const plan = analyzeToolcraftModel(document, "realtime-mesh").repairPlan!;
+    const serialized = JSON.stringify(plan);
+
+    for (const unsupported of [
+      "weld", "fill-hole", "remesh", "decimate", "subdivide", "smooth",
+      "merge-shell", "source-scale", "node-transform", "guess-index",
+    ]) {
+      expect(serialized).not.toContain(unsupported);
+    }
+    expect(new Set(plan.operations.map(({ type }) => type))).toEqual(new Set([
+      "remove-invalid-triangles",
+      "remove-duplicate-triangles",
+      "compact-unused-vertices",
+      "regenerate-normals",
+      "recalculate-bounds",
+    ]));
+  });
+
+  it("rejects a plan compiled for a different source document", () => {
+    const source = createTopologyDocument([createRepairablePrimitive()]);
+    const plan = analyzeToolcraftModel(source, "realtime-mesh").repairPlan!;
+    const other = createTopologyDocument([createRepairablePrimitive()]);
+    other.nodes[0]!.localMatrix = [
+      1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1,
+    ];
+
+    expect(() => applyToolcraftModelRepair(other, plan)).toThrow(
+      /source document digest/u,
+    );
+  });
+});

package/templates/runtime/model-import/topology/apply-model-repair.ts

@@ -0,0 +1,31 @@
+import type { ToolcraftModelDocument } from "../canonical/model-document";
+import { deriveToolcraftModelRepair } from "./model-repair-execution";
+import { analyzeToolcraftModelWithoutRepairPlanning } from "./model-topology-analysis";
+import type {
+  ToolcraftModelRepairOperation,
+  ToolcraftModelRepairPlan,
+} from "./model-repair-plan";
+
+export function applyToolcraftModelRepair(
+  document: ToolcraftModelDocument,
+  plan: ToolcraftModelRepairPlan,
+): ToolcraftModelDocument {
+  const repaired = deriveToolcraftModelRepair(document, plan);
+  const proof = analyzeToolcraftModelWithoutRepairPlanning(
+    repaired,
+    plan.profile,
+  );
+  const hasUnresolvedRepair = proof.diagnostics.some(({ severity }) =>
+    severity === "fatal" || severity === "repairable"
+  );
+  if (hasUnresolvedRepair ||
+      (plan.profile === "solid-mesh" && proof.outcome !== "clean")) {
+    throw new Error(`Repair plan did not prove ${plan.profile} compliance.`);
+  }
+  return repaired;
+}
+
+export type {
+  ToolcraftModelRepairOperation,
+  ToolcraftModelRepairPlan,
+};

package/templates/runtime/model-import/topology/model-repair-execution.ts

@@ -0,0 +1,364 @@
+import type {
+  ToolcraftModelBounds,
+  ToolcraftModelDocument,
+  ToolcraftModelDocumentV1,
+  ToolcraftModelDocumentV2,
+  ToolcraftModelNode,
+  ToolcraftModelPrimitive,
+  ToolcraftModelPrimitiveV2,
+  ToolcraftModelRepairOperationType,
+} from "../canonical/model-document";
+import { getValidatedToolcraftModelDocumentSnapshot } from "../canonical/model-document-validation";
+import {
+  calculateRequiredBounds,
+  regenerateAreaWeightedNormals,
+} from "./model-repair-geometry";
+import {
+  digestToolcraftRepairPlanPayload,
+  digestToolcraftTopologyDocument,
+} from "./model-topology-digest";
+import {
+  TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION,
+  type ToolcraftCompactVerticesRepairOperation,
+  type ToolcraftModelRepairOperation,
+  type ToolcraftModelRepairPlan,
+  type ToolcraftRemoveTrianglesRepairOperation,
+} from "./model-repair-plan";
+
+type WorkingPrimitive = {
+  bounds: ToolcraftModelPrimitive["bounds"];
+  id: string;
+  indices: Uint32Array;
+  materialId?: string;
+  normals?: Float32Array;
+  positions: Float32Array;
+  sourceTriangleIndices: number[];
+  colors?: ToolcraftModelPrimitiveV2["colors"];
+  textureCoordinates?: ToolcraftModelPrimitiveV2["textureCoordinates"];
+};
+
+function clonePrimitive(primitive: ToolcraftModelPrimitiveV2): WorkingPrimitive {
+  return {
+    bounds: { max: [...primitive.bounds.max], min: [...primitive.bounds.min] },
+    ...(primitive.colors ? {
+      colors: {
+        components: primitive.colors.components,
+        values: primitive.colors.values.slice(),
+      },
+    } : {}),
+    id: primitive.id,
+    indices: primitive.indices.slice(),
+    ...(primitive.materialId ? { materialId: primitive.materialId } : {}),
+    normals: primitive.normals?.slice(),
+    positions: primitive.positions.slice(),
+    sourceTriangleIndices: Array.from(
+      { length: primitive.indices.length / 3 },
+      (_, index) => index,
+    ),
+    ...(primitive.textureCoordinates ? {
+      textureCoordinates: primitive.textureCoordinates.map(({ set, values }) => ({
+        set,
+        values: values.slice(),
+      })),
+    } : {}),
+  };
+}
+
+function compactAttribute(
+  values: Float32Array,
+  components: number,
+  retained: readonly number[],
+): Float32Array {
+  const compacted = new Float32Array(retained.length * components);
+  retained.forEach((sourceVertex, targetVertex) => {
+    compacted.set(
+      values.subarray(
+        sourceVertex * components,
+        sourceVertex * components + components,
+      ),
+      targetVertex * components,
+    );
+  });
+  return compacted;
+}
+
+function assertOperationContext(
+  primitive: WorkingPrimitive,
+  primitiveIndex: number,
+  operation: ToolcraftModelRepairOperation,
+): void {
+  if (operation.primitiveIndex !== primitiveIndex ||
+      operation.primitiveId !== primitive.id) {
+    throw new Error(`Repair operation ${operation.type} has stale primitive context.`);
+  }
+}
+
+function removeTriangles(
+  primitive: WorkingPrimitive,
+  operation: ToolcraftRemoveTrianglesRepairOperation,
+): void {
+  const removed = new Set(operation.triangleIndices);
+  if (removed.size !== operation.triangleIndices.length) {
+    throw new Error(`${operation.type} contains duplicate triangle inputs.`);
+  }
+  const indices: number[] = [];
+  const sourceTriangleIndices: number[] = [];
+  let removedCount = 0;
+  primitive.sourceTriangleIndices.forEach((sourceTriangleIndex, currentIndex) => {
+    if (removed.has(sourceTriangleIndex)) {
+      removedCount += 1;
+      return;
+    }
+    indices.push(
+      primitive.indices[currentIndex * 3]!,
+      primitive.indices[currentIndex * 3 + 1]!,
+      primitive.indices[currentIndex * 3 + 2]!,
+    );
+    sourceTriangleIndices.push(sourceTriangleIndex);
+  });
+  if (removedCount !== removed.size ||
+      operation.expectedCountDelta.triangles !== -removedCount) {
+    throw new Error(`${operation.type} triangle inputs no longer match the source.`);
+  }
+  primitive.indices = new Uint32Array(indices);
+  primitive.sourceTriangleIndices = sourceTriangleIndices;
+}
+
+function repairWinding(
+  primitive: WorkingPrimitive,
+  operation: Extract<ToolcraftModelRepairOperation, { type: "repair-local-winding" }>,
+): void {
+  const flipped = new Set(operation.flippedTriangleIndices);
+  let flipCount = 0;
+  primitive.sourceTriangleIndices.forEach((sourceTriangleIndex, currentIndex) => {
+    if (!flipped.has(sourceTriangleIndex)) return;
+    const offset = currentIndex * 3;
+    const second = primitive.indices[offset + 1]!;
+    primitive.indices[offset + 1] = primitive.indices[offset + 2]!;
+    primitive.indices[offset + 2] = second;
+    flipCount += 1;
+  });
+  if (flipCount !== flipped.size) {
+    throw new Error("repair-local-winding triangle inputs no longer match the source.");
+  }
+}
+
+function compactVertices(
+  primitive: WorkingPrimitive,
+  operation: ToolcraftCompactVerticesRepairOperation,
+): void {
+  const retained = operation.retainedVertexIndices;
+  const removed = new Set(operation.removedVertexIndices);
+  if (retained.length + removed.size !== primitive.positions.length / 3 ||
+      operation.expectedCountDelta.vertices !== -removed.size) {
+    throw new Error("compact-unused-vertices inputs do not partition source vertices.");
+  }
+  const remap = new Map<number, number>();
+  const positions = new Float32Array(retained.length * 3);
+  const canCompactNormals = primitive.normals?.length === primitive.positions.length;
+  const normals = canCompactNormals ? new Float32Array(retained.length * 3) : undefined;
+  retained.forEach((sourceVertex, targetVertex) => {
+    if (removed.has(sourceVertex) || remap.has(sourceVertex) ||
+        sourceVertex < 0 || sourceVertex >= primitive.positions.length / 3) {
+      throw new Error("compact-unused-vertices has an invalid retained vertex input.");
+    }
+    remap.set(sourceVertex, targetVertex);
+    positions.set(
+      primitive.positions.subarray(sourceVertex * 3, sourceVertex * 3 + 3),
+      targetVertex * 3,
+    );
+    if (normals !== undefined && primitive.normals !== undefined) {
+      normals.set(
+        primitive.normals.subarray(sourceVertex * 3, sourceVertex * 3 + 3),
+        targetVertex * 3,
+      );
+    }
+  });
+  const indices = new Uint32Array(primitive.indices.length);
+  for (let index = 0; index < primitive.indices.length; index += 1) {
+    const mapped = remap.get(primitive.indices[index]!);
+    if (mapped === undefined) {
+      throw new Error("compact-unused-vertices would discard a referenced vertex.");
+    }
+    indices[index] = mapped;
+  }
+  primitive.positions = positions;
+  primitive.indices = indices;
+  primitive.normals = normals;
+  if (primitive.colors) {
+    primitive.colors = {
+      components: primitive.colors.components,
+      values: compactAttribute(
+        primitive.colors.values,
+        primitive.colors.components,
+        retained,
+      ),
+    };
+  }
+  if (primitive.textureCoordinates) {
+    primitive.textureCoordinates = primitive.textureCoordinates.map(
+      ({ set, values }) => ({
+        set,
+        values: compactAttribute(values, 2, retained),
+      }),
+    );
+  }
+}
+
+function applyOperation(
+  primitives: WorkingPrimitive[],
+  operation: ToolcraftModelRepairOperation,
+): void {
+  const primitive = primitives[operation.primitiveIndex];
+  if (primitive === undefined) {
+    throw new Error(`Repair operation ${operation.type} references a missing primitive.`);
+  }
+  assertOperationContext(primitive, operation.primitiveIndex, operation);
+  switch (operation.type) {
+    case "remove-invalid-triangles":
+    case "remove-duplicate-triangles":
+      removeTriangles(primitive, operation);
+      return;
+    case "repair-local-winding":
+      repairWinding(primitive, operation);
+      return;
+    case "compact-unused-vertices":
+      compactVertices(primitive, operation);
+      return;
+    case "regenerate-normals": {
+      if (primitive.positions.length / 3 !== operation.vertexCount) {
+        throw new Error("regenerate-normals vertex count no longer matches the plan.");
+      }
+      const normals = regenerateAreaWeightedNormals(
+        primitive.positions,
+        primitive.indices,
+      );
+      if (normals === undefined) {
+        throw new Error("regenerate-normals safety preconditions were not satisfied.");
+      }
+      primitive.normals = normals;
+      return;
+    }
+    case "recalculate-bounds":
+      primitive.bounds = calculateRequiredBounds(primitive.positions);
+      return;
+  }
+}
+
+function verifyPlanDigest(plan: ToolcraftModelRepairPlan): void {
+  const payload = {
+    algorithmVersion: plan.algorithmVersion,
+    analyzerVersion: plan.analyzerVersion,
+    operations: plan.operations,
+    profile: plan.profile,
+    sourceDocumentDigest: plan.sourceDocumentDigest,
+  };
+  if (digestToolcraftRepairPlanPayload(payload) !== plan.planDigest) {
+    throw new Error("Repair plan digest does not match its compiled operations.");
+  }
+  if (plan.algorithmVersion !== TOOLCRAFT_MODEL_REPAIR_ALGORITHM_VERSION ||
+      plan.recipeId !== `${plan.algorithmVersion}:${plan.planDigest}`) {
+    throw new Error("Repair plan recipe identity is unsupported.");
+  }
+}
+
+function aggregatePrimitiveBounds(
+  primitives: readonly ToolcraftModelPrimitive[],
+): ToolcraftModelDocument["bounds"] {
+  const min: [number, number, number] = [...primitives[0]!.bounds.min];
+  const max: [number, number, number] = [...primitives[0]!.bounds.max];
+  for (const primitive of primitives.slice(1)) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis], primitive.bounds.min[axis]);
+      max[axis] = Math.max(max[axis], primitive.bounds.max[axis]);
+    }
+  }
+  return { max, min };
+}
+
+function uniqueOperationTypes(
+  operations: readonly ToolcraftModelRepairOperation[],
+): readonly ToolcraftModelRepairOperationType[] {
+  const seen = new Set<ToolcraftModelRepairOperationType>();
+  const types: ToolcraftModelRepairOperationType[] = [];
+  for (const operation of operations) {
+    if (!seen.has(operation.type)) {
+      seen.add(operation.type);
+      types.push(operation.type);
+    }
+  }
+  return Object.freeze(types);
+}
+
+export function deriveToolcraftModelRepair(
+  document: ToolcraftModelDocument,
+  plan: ToolcraftModelRepairPlan,
+): ToolcraftModelDocument {
+  verifyPlanDigest(plan);
+  if (digestToolcraftTopologyDocument(document) !== plan.sourceDocumentDigest) {
+    throw new Error("Repair plan source document digest does not match the supplied document.");
+  }
+  const working = document.primitives.map(clonePrimitive);
+  for (const operation of plan.operations) applyOperation(working, operation);
+  const primitives: readonly ToolcraftModelPrimitiveV2[] = working.map((primitive) => {
+    const bounds: ToolcraftModelBounds = Object.freeze({
+      max: Object.freeze([...primitive.bounds.max]) as ToolcraftModelBounds["max"],
+      min: Object.freeze([...primitive.bounds.min]) as ToolcraftModelBounds["min"],
+    });
+    const result: ToolcraftModelPrimitiveV2 = {
+      bounds,
+      ...(primitive.colors ? { colors: primitive.colors } : {}),
+      id: primitive.id,
+      indices: primitive.indices,
+      ...(primitive.materialId ? { materialId: primitive.materialId } : {}),
+      ...(primitive.normals === undefined ? {} : { normals: primitive.normals }),
+      positions: primitive.positions,
+      ...(primitive.textureCoordinates
+        ? { textureCoordinates: primitive.textureCoordinates }
+        : {}),
+    };
+    return Object.freeze(result);
+  });
+  const repair = Object.freeze({
+    algorithmVersion: plan.algorithmVersion,
+    operations: uniqueOperationTypes(plan.operations),
+    planDigest: plan.planDigest,
+    recipeId: plan.recipeId,
+  });
+  const nodes: readonly ToolcraftModelNode[] = document.nodes.map((node) =>
+    Object.freeze({
+      ...node,
+      children: Object.freeze([...node.children]),
+      localMatrix: Object.freeze([...node.localMatrix]) as ToolcraftModelNode["localMatrix"],
+      primitiveIds: Object.freeze([...node.primitiveIds]),
+    })
+  );
+  const base = {
+    bounds: Object.freeze(aggregatePrimitiveBounds(primitives)),
+    nodes: Object.freeze(nodes),
+    primitives: Object.freeze(primitives),
+    rootNodeIds: Object.freeze([...document.rootNodeIds]),
+  };
+  const repaired: ToolcraftModelDocument = document.version === 1
+    ? ({
+        ...base,
+        provenance: Object.freeze({
+          ...document.provenance,
+          operations: Object.freeze([...document.provenance.operations]),
+          repair,
+        }),
+        version: 1,
+      } satisfies ToolcraftModelDocumentV1)
+    : ({
+        ...base,
+        materials: document.materials,
+        provenance: Object.freeze({
+          ...document.provenance,
+          operations: Object.freeze([...document.provenance.operations]),
+          repair,
+        }),
+        textures: document.textures,
+        version: 2,
+      } satisfies ToolcraftModelDocumentV2);
+  return getValidatedToolcraftModelDocumentSnapshot(repaired);
+}

package/templates/runtime/model-import/topology/model-repair-geometry.ts

@@ -0,0 +1,60 @@
+import type { ToolcraftModelBounds } from "../canonical/model-document";
+import { calculatePositionBounds } from "./model-topology-math";
+
+export function regenerateAreaWeightedNormals(
+  positions: Float32Array,
+  indices: Uint32Array,
+): Float32Array | undefined {
+  const normals = new Float64Array(positions.length);
+  let coordinateScale = 0;
+  for (const value of positions) coordinateScale = Math.max(coordinateScale, Math.abs(value));
+  if (coordinateScale === 0 || !Number.isFinite(coordinateScale)) return undefined;
+
+  for (let offset = 0; offset < indices.length; offset += 3) {
+    const a = indices[offset]!;
+    const b = indices[offset + 1]!;
+    const c = indices[offset + 2]!;
+    const ax = positions[a * 3]! / coordinateScale;
+    const ay = positions[a * 3 + 1]! / coordinateScale;
+    const az = positions[a * 3 + 2]! / coordinateScale;
+    const abx = positions[b * 3]! / coordinateScale - ax;
+    const aby = positions[b * 3 + 1]! / coordinateScale - ay;
+    const abz = positions[b * 3 + 2]! / coordinateScale - az;
+    const acx = positions[c * 3]! / coordinateScale - ax;
+    const acy = positions[c * 3 + 1]! / coordinateScale - ay;
+    const acz = positions[c * 3 + 2]! / coordinateScale - az;
+    const cross = [
+      aby * acz - abz * acy,
+      abz * acx - abx * acz,
+      abx * acy - aby * acx,
+    ] as const;
+    for (const vertex of [a, b, c]) {
+      normals[vertex * 3] += cross[0];
+      normals[vertex * 3 + 1] += cross[1];
+      normals[vertex * 3 + 2] += cross[2];
+    }
+  }
+
+  const result = new Float32Array(positions.length);
+  for (let offset = 0; offset < normals.length; offset += 3) {
+    const x = normals[offset]!;
+    const y = normals[offset + 1]!;
+    const z = normals[offset + 2]!;
+    const length = Math.hypot(x, y, z);
+    if (length === 0 || !Number.isFinite(length)) return undefined;
+    result[offset] = x / length;
+    result[offset + 1] = y / length;
+    result[offset + 2] = z / length;
+  }
+  return result;
+}
+
+export function calculateRequiredBounds(
+  positions: Float32Array,
+): ToolcraftModelBounds {
+  const bounds = calculatePositionBounds(positions);
+  if (bounds === undefined) {
+    throw new Error("Repair produced positions without finite XYZ bounds.");
+  }
+  return bounds;
+}