@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/runtime/model-import/formats/gltf-accessor-preflight.ts

@@ -0,0 +1,321 @@
+import type { GLTF } from "@gltf-transform/core";
+
+import type { ToolcraftModelImportLimits } from "../../schema/types";
+import {
+  checkedGltfScale,
+  checkedGltfTotal,
+  gltfDecodeCheckpoint,
+  gltfDecodeFailure,
+} from "./gltf-decode-safety";
+import {
+  assertGltfByteRange,
+  type GltfAccessorInfo,
+  type GltfBufferViewInfo,
+  GLTF_COMPONENT_BYTES,
+  getGltfElementByteLength,
+  gltfJsonArray,
+  gltfJsonIndexed,
+  gltfJsonInteger,
+  gltfJsonOptionalInteger,
+  gltfJsonRecord,
+} from "./gltf-json-inspection";
+
+function assertAligned(
+  view: GltfBufferViewInfo,
+  offset: number,
+  alignment: number,
+  label: string,
+): void {
+  if ((view.byteOffset + offset) % alignment !== 0) {
+    gltfDecodeFailure(
+      "format",
+      "invalid-gltf-accessor",
+      `${label} is not aligned to its component size.`,
+    );
+  }
+}
+
+function inspectSparseAccessor(
+  sparseValue: unknown,
+  accessorCount: number,
+  componentBytes: number,
+  elementBytes: number,
+  views: readonly GltfBufferViewInfo[],
+  label: string,
+  signal: AbortSignal,
+): number {
+  const sparse = gltfJsonRecord(
+    sparseValue,
+    "invalid-gltf-accessor",
+    `${label}.sparse`,
+  );
+  const count = gltfJsonInteger(
+    sparse.count,
+    "invalid-gltf-accessor",
+    `${label}.sparse.count`,
+    1,
+  );
+  if (count > accessorCount) {
+    return gltfDecodeFailure(
+      "format",
+      "invalid-gltf-accessor",
+      `${label}.sparse.count exceeds accessor count.`,
+    );
+  }
+
+  const indices = gltfJsonRecord(
+    sparse.indices,
+    "invalid-gltf-accessor",
+    `${label}.sparse.indices`,
+  );
+  const indexComponentType = gltfJsonInteger(
+    indices.componentType,
+    "invalid-gltf-accessor",
+    `${label}.sparse.indices.componentType`,
+  );
+  if (![5121, 5123, 5125].includes(indexComponentType)) {
+    return gltfDecodeFailure(
+      "format",
+      "invalid-sparse-indices",
+      `${label}.sparse indices must use an unsigned integer component type.`,
+    );
+  }
+  const indexComponentBytes = GLTF_COMPONENT_BYTES[indexComponentType]!;
+  const indexView = gltfJsonIndexed(
+    views,
+    indices.bufferView,
+    "invalid-gltf-accessor",
+    `${label}.sparse.indices.bufferView`,
+  );
+  const indexOffset = gltfJsonOptionalInteger(
+    indices.byteOffset,
+    "invalid-gltf-accessor",
+    `${label}.sparse.indices.byteOffset`,
+  );
+  assertAligned(indexView, indexOffset, indexComponentBytes, `${label}.sparse.indices`);
+  assertGltfByteRange(
+    indexOffset,
+    checkedGltfScale(
+      count,
+      indexComponentBytes,
+      "decoded-byte-limit-exceeded",
+    ),
+    indexView.byteLength,
+    "invalid-gltf-accessor",
+    `${label}.sparse.indices`,
+  );
+  if (indexView.meshoptCompressed) {
+    return gltfDecodeFailure(
+      "format",
+      "invalid-sparse-indices",
+      `${label}.sparse indices cannot be verified from a compressed bufferView before decode.`,
+    );
+  }
+  const indexBytes = indexView.readBytes();
+  const indexData = new DataView(
+    indexBytes.buffer,
+    indexBytes.byteOffset,
+    indexBytes.byteLength,
+  );
+  let previous = -1;
+  for (let index = 0; index < count; index += 1) {
+    gltfDecodeCheckpoint(signal, index);
+    const offset = indexOffset + index * indexComponentBytes;
+    const sparseIndex =
+      indexComponentType === 5121
+        ? indexData.getUint8(offset)
+        : indexComponentType === 5123
+          ? indexData.getUint16(offset, true)
+          : indexData.getUint32(offset, true);
+    if (sparseIndex >= accessorCount) {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-sparse-indices",
+        `${label}.sparse index is outside the accessor count.`,
+      );
+    }
+    if (sparseIndex <= previous) {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-sparse-indices",
+        `${label}.sparse indices must be strictly increasing and unique.`,
+      );
+    }
+    previous = sparseIndex;
+  }
+
+  const values = gltfJsonRecord(
+    sparse.values,
+    "invalid-gltf-accessor",
+    `${label}.sparse.values`,
+  );
+  const valueView = gltfJsonIndexed(
+    views,
+    values.bufferView,
+    "invalid-gltf-accessor",
+    `${label}.sparse.values.bufferView`,
+  );
+  const valueOffset = gltfJsonOptionalInteger(
+    values.byteOffset,
+    "invalid-gltf-accessor",
+    `${label}.sparse.values.byteOffset`,
+  );
+  assertAligned(valueView, valueOffset, componentBytes, `${label}.sparse.values`);
+  assertGltfByteRange(
+    valueOffset,
+    checkedGltfScale(count, elementBytes, "decoded-byte-limit-exceeded"),
+    valueView.byteLength,
+    "invalid-gltf-accessor",
+    `${label}.sparse.values`,
+  );
+  return checkedGltfScale(
+    count,
+    elementBytes + Uint32Array.BYTES_PER_ELEMENT,
+    "decoded-byte-limit-exceeded",
+  );
+}
+
+export function preflightGltfAccessors(
+  json: GLTF.IGLTF,
+  views: readonly GltfBufferViewInfo[],
+  limits: ToolcraftModelImportLimits,
+  signal: AbortSignal,
+): { accessors: GltfAccessorInfo[]; decodedBytes: number } {
+  const definitions = gltfJsonArray(
+    json.accessors,
+    "invalid-gltf-accessors",
+    "glTF accessors",
+  );
+  const accessors: GltfAccessorInfo[] = [];
+  let decodedBytes = 0;
+  definitions.forEach((value, index) => {
+    gltfDecodeCheckpoint(signal, index);
+    const label = `accessor ${index}`;
+    const definition = gltfJsonRecord(
+      value,
+      "invalid-gltf-accessor",
+      label,
+    );
+    const count = gltfJsonInteger(
+      definition.count,
+      "invalid-gltf-accessor",
+      `${label}.count`,
+      1,
+    );
+    const componentType = gltfJsonInteger(
+      definition.componentType,
+      "invalid-gltf-accessor",
+      `${label}.componentType`,
+    );
+    const type = definition.type;
+    const elementBytes =
+      typeof type === "string"
+        ? getGltfElementByteLength(componentType, type)
+        : undefined;
+    if (!elementBytes || typeof type !== "string") {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-gltf-accessor",
+        `${label} has an unsupported componentType or type.`,
+      );
+    }
+    if (
+      definition.normalized !== undefined &&
+      typeof definition.normalized !== "boolean"
+    ) {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-gltf-accessor",
+        `${label}.normalized must be boolean.`,
+      );
+    }
+    if (
+      definition.normalized === true &&
+      [5126, 5130, 5131].includes(componentType)
+    ) {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-gltf-accessor",
+        `${label} cannot normalize FLOAT components.`,
+      );
+    }
+    const byteLength = checkedGltfScale(
+      count,
+      elementBytes,
+      "decoded-byte-limit-exceeded",
+    );
+    if (definition.bufferView === undefined) {
+      if (definition.byteOffset !== undefined) {
+        return gltfDecodeFailure(
+          "format",
+          "invalid-gltf-accessor",
+          `${label}.byteOffset requires a bufferView.`,
+        );
+      }
+    } else {
+      const view = gltfJsonIndexed(
+        views,
+        definition.bufferView,
+        "invalid-gltf-accessor",
+        `${label}.bufferView`,
+      );
+      const offset = gltfJsonOptionalInteger(
+        definition.byteOffset,
+        "invalid-gltf-accessor",
+        `${label}.byteOffset`,
+      );
+      const componentBytes = GLTF_COMPONENT_BYTES[componentType]!;
+      assertAligned(view, offset, componentBytes, label);
+      const stride = view.byteStride ?? elementBytes;
+      if (stride < elementBytes || stride % componentBytes !== 0) {
+        return gltfDecodeFailure(
+          "format",
+          "invalid-gltf-accessor",
+          `${label} has an invalid byteStride.`,
+        );
+      }
+      const spanned = checkedGltfTotal(
+        checkedGltfScale(count - 1, stride, "decoded-byte-limit-exceeded"),
+        elementBytes,
+        Number.MAX_SAFE_INTEGER,
+        "decoded-byte-limit-exceeded",
+        label,
+      );
+      assertGltfByteRange(
+        offset,
+        spanned,
+        view.byteLength,
+        "invalid-gltf-accessor",
+        label,
+      );
+    }
+    const sparseBytes =
+      definition.sparse === undefined
+        ? 0
+        : inspectSparseAccessor(
+            definition.sparse,
+            count,
+            GLTF_COMPONENT_BYTES[componentType]!,
+            elementBytes,
+            views,
+            label,
+            signal,
+          );
+    decodedBytes = checkedGltfTotal(
+      decodedBytes,
+      byteLength + sparseBytes,
+      limits.maxDecodedBytes,
+      "decoded-byte-limit-exceeded",
+      "Decoded glTF accessors",
+    );
+    accessors.push({
+      byteLength,
+      componentType,
+      count,
+      normalized: definition.normalized === true,
+      record: definition,
+      type,
+    });
+  });
+  return { accessors, decodedBytes };
+}

package/templates/runtime/model-import/formats/gltf-attribute-encoding.ts

@@ -0,0 +1,65 @@
+import type { GltfAccessorInfo } from "./gltf-json-inspection";
+import { gltfDecodeFailure } from "./gltf-decode-safety";
+
+function isRequired(
+  extensions: ReadonlySet<string>,
+  extensionName: string,
+): boolean {
+  return extensions.has(extensionName);
+}
+
+function isSupportedFloatEncoding(
+  accessor: GltfAccessorInfo,
+  requiredExtensions: ReadonlySet<string>,
+): boolean {
+  if (accessor.normalized) return false;
+  if (accessor.componentType === 5126) return true;
+  if (accessor.componentType === 5131) {
+    return isRequired(requiredExtensions, "KHR_accessor_float16");
+  }
+  if (accessor.componentType === 5130) {
+    return isRequired(requiredExtensions, "KHR_accessor_float64");
+  }
+  return false;
+}
+
+export function validateGltfPositionEncoding(
+  accessor: GltfAccessorInfo,
+  requiredExtensions: ReadonlySet<string>,
+): void {
+  const quantized =
+    isRequired(requiredExtensions, "KHR_mesh_quantization") &&
+    [5120, 5121, 5122, 5123].includes(accessor.componentType);
+  if (
+    accessor.type !== "VEC3" ||
+    (!isSupportedFloatEncoding(accessor, requiredExtensions) && !quantized)
+  ) {
+    return gltfDecodeFailure(
+      "geometry",
+      "invalid-position-accessor",
+      "POSITION must be VEC3 FLOAT, required float16/float64, or an allowed KHR_mesh_quantization integer encoding.",
+    );
+  }
+}
+
+export function validateGltfNormalEncoding(
+  accessor: GltfAccessorInfo,
+  positionCount: number,
+  requiredExtensions: ReadonlySet<string>,
+): void {
+  const quantized =
+    isRequired(requiredExtensions, "KHR_mesh_quantization") &&
+    accessor.normalized &&
+    [5120, 5122].includes(accessor.componentType);
+  if (
+    accessor.type !== "VEC3" ||
+    accessor.count !== positionCount ||
+    (!isSupportedFloatEncoding(accessor, requiredExtensions) && !quantized)
+  ) {
+    return gltfDecodeFailure(
+      "geometry",
+      "invalid-normal-accessor",
+      "NORMAL must match POSITION count and use VEC3 FLOAT or normalized signed BYTE/SHORT with required KHR_mesh_quantization.",
+    );
+  }
+}

package/templates/runtime/model-import/formats/gltf-buffer-preflight.ts

@@ -0,0 +1,320 @@
+import {
+  BufferUtils,
+  GLB_BUFFER,
+  type GLTF,
+  type JSONDocument,
+} from "@gltf-transform/core";
+
+import type { ToolcraftModelImportLimits } from "../../schema/types";
+import { inspectBufferDataUri } from "../model-source-data-uri";
+import {
+  checkedGltfScale,
+  checkedGltfTotal,
+  gltfDecodeCheckpoint,
+  gltfDecodeFailure,
+} from "./gltf-decode-safety";
+import {
+  assertGltfByteRange,
+  type GltfBufferViewInfo,
+  type GltfJsonRecord,
+  gltfJsonArray,
+  gltfJsonIndexed,
+  gltfJsonInteger,
+  gltfJsonOptionalInteger,
+  gltfJsonRecord,
+} from "./gltf-json-inspection";
+
+export type GltfBufferPreflight = Readonly<{
+  bufferViews: GltfBufferViewInfo[];
+  embeddedBytes: number;
+  meshoptBytes: number;
+}>;
+
+type GltfBufferInfo = Readonly<{
+  byteLength: number;
+  readBytes: () => Uint8Array;
+}>;
+
+function dataUriReader(uri: string, expectedByteLength: number): () => Uint8Array {
+  let bytes: Uint8Array | undefined;
+  return () => {
+    bytes ??= BufferUtils.createBufferFromDataURI(uri);
+    if (bytes.byteLength !== expectedByteLength) {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-buffer-data-uri",
+        "An embedded glTF buffer did not match its preflighted byte length.",
+      );
+    }
+    return bytes;
+  };
+}
+
+function inspectBuffers(
+  json: GLTF.IGLTF,
+  resources: JSONDocument["resources"],
+  limits: ToolcraftModelImportLimits,
+  signal: AbortSignal,
+): { buffers: GltfBufferInfo[]; embeddedBytes: number } {
+  const definitions = gltfJsonArray(
+    json.buffers,
+    "invalid-gltf-buffers",
+    "glTF buffers",
+  );
+  if (definitions.length === 0) {
+    return gltfDecodeFailure(
+      "geometry",
+      "no-renderable-static-geometry",
+      "glTF geometry requires at least one buffer.",
+    );
+  }
+  const buffers: GltfBufferInfo[] = [];
+  let embeddedBytes = 0;
+  definitions.forEach((value, index) => {
+    gltfDecodeCheckpoint(signal, index);
+    const definition = gltfJsonRecord(
+      value,
+      "invalid-gltf-buffer",
+      `buffer ${index}`,
+    );
+    const declared = gltfJsonInteger(
+      definition.byteLength,
+      "invalid-gltf-buffer",
+      `buffer ${index}.byteLength`,
+      1,
+    );
+    const uri = definition.uri;
+    let actual: number;
+    let readBytes: () => Uint8Array;
+    if (uri === undefined) {
+      const resource = resources[GLB_BUFFER];
+      actual = resource?.byteLength ?? 0;
+      readBytes = () => resource!;
+    } else if (typeof uri === "string") {
+      const dataBytes = inspectBufferDataUri(uri, limits.maxDecodedBytes);
+      if (dataBytes === undefined) {
+        const resource = resources[uri];
+        actual = resource?.byteLength ?? 0;
+        readBytes = () => resource!;
+      } else {
+        actual = dataBytes;
+        readBytes = dataUriReader(uri, dataBytes);
+        embeddedBytes = checkedGltfTotal(
+          embeddedBytes,
+          dataBytes,
+          limits.maxDecodedBytes,
+          "decoded-byte-limit-exceeded",
+          "Embedded glTF buffers",
+        );
+      }
+    } else {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-gltf-buffer",
+        `buffer ${index}.uri must be a string when provided.`,
+      );
+    }
+    if (actual < declared) {
+      return gltfDecodeFailure(
+        "format",
+        "buffer-byte-length-mismatch",
+        `buffer ${index} is shorter than its declared byteLength.`,
+      );
+    }
+    buffers.push({ byteLength: declared, readBytes });
+  });
+  return { buffers, embeddedBytes };
+}
+
+function inspectMeshoptExtension(
+  extensionValue: unknown,
+  destinationLength: number,
+  buffers: readonly GltfBufferInfo[],
+): number {
+  const extension = gltfJsonRecord(
+    extensionValue,
+    "invalid-meshopt-extension",
+    "EXT_meshopt_compression",
+  );
+  const sourceBuffer = gltfJsonIndexed(
+    buffers,
+    extension.buffer,
+    "invalid-meshopt-extension",
+    "Meshopt buffer",
+  );
+  const sourceOffset = gltfJsonOptionalInteger(
+    extension.byteOffset,
+    "invalid-meshopt-extension",
+    "Meshopt byteOffset",
+  );
+  const sourceLength = gltfJsonInteger(
+    extension.byteLength,
+    "invalid-meshopt-extension",
+    "Meshopt byteLength",
+    1,
+  );
+  assertGltfByteRange(
+    sourceOffset,
+    sourceLength,
+    sourceBuffer.byteLength,
+    "invalid-meshopt-extension",
+    "Meshopt compressed range",
+  );
+  const count = gltfJsonInteger(
+    extension.count,
+    "invalid-meshopt-extension",
+    "Meshopt count",
+    1,
+  );
+  const stride = gltfJsonInteger(
+    extension.byteStride,
+    "invalid-meshopt-extension",
+    "Meshopt byteStride",
+    1,
+  );
+  if (stride > 256) {
+    return gltfDecodeFailure(
+      "format",
+      "invalid-meshopt-extension",
+      "Meshopt byteStride exceeds 256 bytes.",
+    );
+  }
+  if (
+    !["ATTRIBUTES", "TRIANGLES", "INDICES"].includes(
+      String(extension.mode),
+    )
+  ) {
+    return gltfDecodeFailure(
+      "format",
+      "invalid-meshopt-extension",
+      "Meshopt mode is not supported by EXT_meshopt_compression.",
+    );
+  }
+  const expanded = checkedGltfScale(
+    count,
+    stride,
+    "decoded-byte-limit-exceeded",
+  );
+  if (expanded !== destinationLength) {
+    return gltfDecodeFailure(
+      "format",
+      "invalid-meshopt-extension",
+      "Meshopt expansion must match its destination bufferView.",
+    );
+  }
+  return expanded;
+}
+
+function inspectBufferViews(
+  json: GLTF.IGLTF,
+  buffers: readonly GltfBufferInfo[],
+  limits: ToolcraftModelImportLimits,
+  signal: AbortSignal,
+): { meshoptBytes: number; views: GltfBufferViewInfo[] } {
+  const definitions = gltfJsonArray(
+    json.bufferViews,
+    "invalid-buffer-views",
+    "glTF bufferViews",
+  );
+  const views: GltfBufferViewInfo[] = [];
+  let meshoptBytes = 0;
+  definitions.forEach((value, index) => {
+    gltfDecodeCheckpoint(signal, index);
+    const definition = gltfJsonRecord(
+      value,
+      "invalid-buffer-view",
+      `bufferView ${index}`,
+    );
+    const buffer = gltfJsonIndexed(
+      buffers,
+      definition.buffer,
+      "invalid-buffer-view",
+      `bufferView ${index}.buffer`,
+    );
+    const byteOffset = gltfJsonOptionalInteger(
+      definition.byteOffset,
+      "invalid-buffer-view",
+      `bufferView ${index}.byteOffset`,
+    );
+    const byteLength = gltfJsonInteger(
+      definition.byteLength,
+      "invalid-buffer-view",
+      `bufferView ${index}.byteLength`,
+      1,
+    );
+    assertGltfByteRange(
+      byteOffset,
+      byteLength,
+      buffer.byteLength,
+      "invalid-buffer-view",
+      `bufferView ${index}`,
+    );
+    const byteStride =
+      definition.byteStride === undefined
+        ? undefined
+        : gltfJsonInteger(
+            definition.byteStride,
+            "invalid-buffer-view",
+            `bufferView ${index}.byteStride`,
+            4,
+          );
+    if (byteStride !== undefined && (byteStride > 252 || byteStride % 4 !== 0)) {
+      return gltfDecodeFailure(
+        "format",
+        "invalid-buffer-view",
+        `bufferView ${index}.byteStride is invalid.`,
+      );
+    }
+    const extensions = definition.extensions;
+    const meshopt =
+      typeof extensions === "object" && extensions !== null
+        ? (extensions as GltfJsonRecord).EXT_meshopt_compression
+        : undefined;
+    views.push({
+      byteLength,
+      byteOffset,
+      ...(byteStride ? { byteStride } : {}),
+      meshoptCompressed: meshopt !== undefined,
+      readBytes: () =>
+        buffer.readBytes().subarray(byteOffset, byteOffset + byteLength),
+    });
+    if (meshopt !== undefined) {
+      meshoptBytes = checkedGltfTotal(
+        meshoptBytes,
+        inspectMeshoptExtension(meshopt, byteLength, buffers),
+        limits.maxDecodedBytes,
+        "decoded-byte-limit-exceeded",
+        "Meshopt expansion",
+      );
+    }
+  });
+  return { meshoptBytes, views };
+}
+
+export function preflightGltfBuffers(
+  json: GLTF.IGLTF,
+  resources: JSONDocument["resources"],
+  retainedWorkerBytes: number,
+  limits: ToolcraftModelImportLimits,
+  signal: AbortSignal,
+): GltfBufferPreflight {
+  const buffers = inspectBuffers(json, resources, limits, signal);
+  checkedGltfTotal(
+    retainedWorkerBytes,
+    buffers.embeddedBytes,
+    limits.maxEstimatedWorkerBytes,
+    "estimated-worker-memory-limit-exceeded",
+    "Embedded glTF buffer memory",
+  );
+  const bufferViews = inspectBufferViews(
+    json,
+    buffers.buffers,
+    limits,
+    signal,
+  );
+  return {
+    bufferViews: bufferViews.views,
+    embeddedBytes: buffers.embeddedBytes,
+    meshoptBytes: bufferViews.meshoptBytes,
+  };
+}