@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/model-import/model-source-json-preflight.ts

@@ -0,0 +1,382 @@
+import { failModelSourceBundle } from "./model-source-bundle-error";
+
+export type ToolcraftGltfJsonPreflight = Readonly<{
+  arrayItems: number;
+  escapedStringCodeUnits: number;
+  estimatedWorkerBytes: number;
+  maxDepth: number;
+  maxTokenCodeUnits: number;
+  objectMembers: number;
+  stringCodeUnits: number;
+  structuralTokens: number;
+}>;
+
+type JsonFrame =
+  | {
+      kind: "array";
+      state: "comma-or-end" | "value" | "value-or-end";
+    }
+  | {
+      kind: "object";
+      state: "colon" | "comma-or-end" | "key" | "key-or-end" | "value";
+    };
+
+const MAX_JSON_NESTING_DEPTH = 128;
+
+function malformedJson(): never {
+  return failModelSourceBundle(
+    "format",
+    "malformed-gltf-json",
+    "The glTF root contains malformed JSON.",
+  );
+}
+
+function workerMemoryExceeded(): never {
+  return failModelSourceBundle(
+    "resource-limit",
+    "estimated-worker-memory-limit-exceeded",
+    "The glTF root exceeds the configured worker-memory limit.",
+  );
+}
+
+function checkedAdd(
+  current: number,
+  additional: number,
+  limit: number,
+): number {
+  if (
+    !Number.isSafeInteger(current) ||
+    !Number.isSafeInteger(additional) ||
+    current < 0 ||
+    additional < 0 ||
+    additional > limit ||
+    current > limit - additional
+  ) {
+    return workerMemoryExceeded();
+  }
+  return current + additional;
+}
+
+function checkedScale(value: number, factor: number): number {
+  if (
+    !Number.isSafeInteger(value) ||
+    value < 0 ||
+    value > Math.floor(Number.MAX_SAFE_INTEGER / factor)
+  ) {
+    return workerMemoryExceeded();
+  }
+  return value * factor;
+}
+
+function incrementCount(value: number, additional = 1): number {
+  if (value > Number.MAX_SAFE_INTEGER - additional)
+    return workerMemoryExceeded();
+  return value + additional;
+}
+
+function isDigit(code: number): boolean {
+  return code >= 48 && code <= 57;
+}
+
+function isNonZeroDigit(code: number): boolean {
+  return code >= 49 && code <= 57;
+}
+
+function isHexDigit(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) ||
+    (code >= 65 && code <= 70) ||
+    (code >= 97 && code <= 102)
+  );
+}
+
+function isWhitespace(code: number): boolean {
+  return code === 32 || code === 9 || code === 10 || code === 13;
+}
+
+export function preflightAndParseGltfJson(
+  bytes: Uint8Array,
+  maxEstimatedWorkerBytes: number,
+  parseJson: (text: string) => unknown = JSON.parse,
+): Readonly<{ preflight: ToolcraftGltfJsonPreflight; value: unknown }> {
+  let estimatedWorkerBytes = checkedAdd(
+    checkedAdd(
+      checkedAdd(0, bytes.byteLength, maxEstimatedWorkerBytes),
+      checkedScale(bytes.byteLength, 2),
+      maxEstimatedWorkerBytes,
+    ),
+    64,
+    maxEstimatedWorkerBytes,
+  );
+
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return malformedJson();
+  }
+
+  estimatedWorkerBytes = checkedAdd(
+    checkedAdd(0, bytes.byteLength, maxEstimatedWorkerBytes),
+    checkedScale(text.length, 2),
+    maxEstimatedWorkerBytes,
+  );
+  estimatedWorkerBytes = checkedAdd(
+    estimatedWorkerBytes,
+    64,
+    maxEstimatedWorkerBytes,
+  );
+
+  let arrayItems = 0;
+  let escapedStringCodeUnits = 0;
+  let index = 0;
+  let maxDepth = 0;
+  let maxTokenCodeUnits = 0;
+  let objectMembers = 0;
+  let stringCodeUnits = 0;
+  let structuralTokens = 0;
+  const stack: JsonFrame[] = [];
+
+  const addEstimate = (additional: number): void => {
+    estimatedWorkerBytes = checkedAdd(
+      estimatedWorkerBytes,
+      additional,
+      maxEstimatedWorkerBytes,
+    );
+  };
+  const countStructure = (): void => {
+    structuralTokens = incrementCount(structuralTokens);
+    addEstimate(4);
+  };
+  const skipWhitespace = (): void => {
+    while (index < text.length && isWhitespace(text.charCodeAt(index))) {
+      index += 1;
+    }
+  };
+  const countToken = (start: number): number => {
+    const length = index - start;
+    maxTokenCodeUnits = Math.max(maxTokenCodeUnits, length);
+    return length;
+  };
+  const parseString = (): void => {
+    const start = index;
+    let decodedCodeUnits = 0;
+    let escapedCodeUnits = 0;
+    index += 1;
+    while (index < text.length) {
+      const code = text.charCodeAt(index);
+      if (code === 34) {
+        index += 1;
+        const tokenLength = countToken(start);
+        stringCodeUnits = incrementCount(stringCodeUnits, decodedCodeUnits);
+        escapedStringCodeUnits = incrementCount(
+          escapedStringCodeUnits,
+          escapedCodeUnits,
+        );
+        addEstimate(48);
+        addEstimate(checkedScale(decodedCodeUnits, 2));
+        addEstimate(checkedScale(escapedCodeUnits, 4));
+        addEstimate(checkedScale(tokenLength, 2));
+        return;
+      }
+      if (code < 32) return malformedJson();
+      if (code !== 92) {
+        decodedCodeUnits = incrementCount(decodedCodeUnits);
+        index += 1;
+        continue;
+      }
+
+      index += 1;
+      if (index >= text.length) return malformedJson();
+      const escapeCode = text.charCodeAt(index);
+      escapedCodeUnits = incrementCount(escapedCodeUnits);
+      decodedCodeUnits = incrementCount(decodedCodeUnits);
+      if (escapeCode === 117) {
+        for (let offset = 1; offset <= 4; offset += 1) {
+          if (!isHexDigit(text.charCodeAt(index + offset))) {
+            return malformedJson();
+          }
+        }
+        index += 5;
+        continue;
+      }
+      if (
+        escapeCode !== 34 &&
+        escapeCode !== 47 &&
+        escapeCode !== 92 &&
+        escapeCode !== 98 &&
+        escapeCode !== 102 &&
+        escapeCode !== 110 &&
+        escapeCode !== 114 &&
+        escapeCode !== 116
+      ) {
+        return malformedJson();
+      }
+      index += 1;
+    }
+    return malformedJson();
+  };
+  const parseNumber = (): void => {
+    const start = index;
+    if (text.charCodeAt(index) === 45) index += 1;
+    if (text.charCodeAt(index) === 48) {
+      index += 1;
+      if (isDigit(text.charCodeAt(index))) return malformedJson();
+    } else {
+      if (!isNonZeroDigit(text.charCodeAt(index))) return malformedJson();
+      while (isDigit(text.charCodeAt(index))) index += 1;
+    }
+    if (text.charCodeAt(index) === 46) {
+      index += 1;
+      if (!isDigit(text.charCodeAt(index))) return malformedJson();
+      while (isDigit(text.charCodeAt(index))) index += 1;
+    }
+    const exponentCode = text.charCodeAt(index);
+    if (exponentCode === 69 || exponentCode === 101) {
+      index += 1;
+      const signCode = text.charCodeAt(index);
+      if (signCode === 43 || signCode === 45) index += 1;
+      if (!isDigit(text.charCodeAt(index))) return malformedJson();
+      while (isDigit(text.charCodeAt(index))) index += 1;
+    }
+    const tokenLength = countToken(start);
+    addEstimate(32);
+    addEstimate(checkedScale(tokenLength, 2));
+  };
+  const parseLiteral = (literal: "false" | "null" | "true"): void => {
+    const start = index;
+    for (let offset = 0; offset < literal.length; offset += 1) {
+      if (text.charCodeAt(index + offset) !== literal.charCodeAt(offset)) {
+        return malformedJson();
+      }
+    }
+    index += literal.length;
+    const tokenLength = countToken(start);
+    addEstimate(16);
+    addEstimate(checkedScale(tokenLength, 2));
+  };
+  const openContainer = (kind: "array" | "object"): void => {
+    index += 1;
+    countStructure();
+    if (kind === "array") {
+      stack.push({ kind, state: "value-or-end" });
+      addEstimate(64);
+    } else {
+      stack.push({ kind, state: "key-or-end" });
+      addEstimate(96);
+    }
+    maxDepth = Math.max(maxDepth, stack.length);
+    if (stack.length > MAX_JSON_NESTING_DEPTH) {
+      failModelSourceBundle(
+        "resource-limit",
+        "gltf-json-depth-limit-exceeded",
+        "The glTF root exceeds the protected JSON nesting limit.",
+      );
+    }
+  };
+  const parseValue = (): void => {
+    skipWhitespace();
+    const code = text.charCodeAt(index);
+    if (code === 123) return openContainer("object");
+    if (code === 91) return openContainer("array");
+    if (code === 34) return parseString();
+    if (code === 45 || isDigit(code)) return parseNumber();
+    if (code === 116) return parseLiteral("true");
+    if (code === 102) return parseLiteral("false");
+    if (code === 110) return parseLiteral("null");
+    return malformedJson();
+  };
+  const closeContainer = (): void => {
+    index += 1;
+    countStructure();
+    stack.pop();
+  };
+
+  skipWhitespace();
+  parseValue();
+  while (stack.length > 0) {
+    skipWhitespace();
+    const frame = stack.at(-1)!;
+    const code = text.charCodeAt(index);
+
+    if (frame.kind === "object") {
+      if (frame.state === "key-or-end" && code === 125) {
+        closeContainer();
+        continue;
+      }
+      if (frame.state === "key-or-end" || frame.state === "key") {
+        if (code !== 34) return malformedJson();
+        parseString();
+        objectMembers = incrementCount(objectMembers);
+        addEstimate(64);
+        frame.state = "colon";
+        continue;
+      }
+      if (frame.state === "colon") {
+        if (code !== 58) return malformedJson();
+        index += 1;
+        countStructure();
+        frame.state = "value";
+        continue;
+      }
+      if (frame.state === "value") {
+        frame.state = "comma-or-end";
+        parseValue();
+        continue;
+      }
+      if (code === 44) {
+        index += 1;
+        countStructure();
+        frame.state = "key";
+        continue;
+      }
+      if (code === 125) {
+        closeContainer();
+        continue;
+      }
+      return malformedJson();
+    }
+
+    if (frame.state === "value-or-end" && code === 93) {
+      closeContainer();
+      continue;
+    }
+    if (frame.state === "value-or-end" || frame.state === "value") {
+      arrayItems = incrementCount(arrayItems);
+      addEstimate(24);
+      frame.state = "comma-or-end";
+      parseValue();
+      continue;
+    }
+    if (code === 44) {
+      index += 1;
+      countStructure();
+      frame.state = "value";
+      continue;
+    }
+    if (code === 93) {
+      closeContainer();
+      continue;
+    }
+    return malformedJson();
+  }
+
+  skipWhitespace();
+  if (index !== text.length) return malformedJson();
+
+  const preflight = Object.freeze({
+    arrayItems,
+    escapedStringCodeUnits,
+    estimatedWorkerBytes,
+    maxDepth,
+    maxTokenCodeUnits,
+    objectMembers,
+    stringCodeUnits,
+    structuralTokens,
+  });
+  try {
+    return Object.freeze({ preflight, value: parseJson(text) });
+  } catch {
+    return malformedJson();
+  }
+}

package/templates/runtime/model-import/model-source-lookup.ts

@@ -0,0 +1,134 @@
+import { failModelSourceBundle } from "./model-source-bundle-error";
+import type { ModelSourceFileSnapshot } from "./model-source-path";
+
+export type ModelSourceLookupObserver = Readonly<{
+  onCanonicalResolution?: () => void;
+  onIndexedFile?: () => void;
+}>;
+
+export type ModelSourceDependencyResolver = Readonly<{
+  resolve: (uriSegments: readonly string[]) => ModelSourceFileSnapshot;
+}>;
+
+export type ModelSourcePackageLookup<T extends Readonly<{ path: string }>> =
+  Readonly<{
+    resolveFrom: (
+      basePath: string,
+      uriSegments: readonly string[],
+    ) => T | undefined;
+  }>;
+
+export function createModelSourcePackageLookup<
+  T extends Readonly<{ path: string }>,
+>(
+  files: readonly T[],
+): ModelSourcePackageLookup<T> {
+  const filesByPath = new Map(files.map((file) => [file.path, file]));
+  return Object.freeze({
+    resolveFrom: (basePath, uriSegments) => {
+      const directory = basePath.split("/").slice(0, -1);
+      return filesByPath.get([...directory, ...uriSegments].join("/"));
+    },
+  });
+}
+
+function addCandidate(
+  index: Map<string, ModelSourceFileSnapshot[]>,
+  key: string,
+  file: ModelSourceFileSnapshot,
+): void {
+  const candidates = index.get(key);
+  if (candidates) {
+    candidates.push(file);
+  } else {
+    index.set(key, [file]);
+  }
+}
+
+function freezeCandidates(index: Map<string, ModelSourceFileSnapshot[]>): void {
+  for (const candidates of index.values()) Object.freeze(candidates);
+}
+
+function missingGeometryFile(): never {
+  return failModelSourceBundle(
+    "bundle",
+    "missing-buffer-file",
+    "The selected batch is missing a required local geometry buffer.",
+  );
+}
+
+function duplicateGeometryPath(
+  matches: readonly ModelSourceFileSnapshot[],
+): never {
+  const code =
+    new Set(matches.map(({ rawPath }) => rawPath)).size > 1
+      ? "ambiguous-normalized-path"
+      : "duplicate-source-path";
+  return failModelSourceBundle(
+    "bundle",
+    code,
+    "More than one selected source file resolves to required geometry.",
+  );
+}
+
+function selectCandidate(
+  candidates: readonly ModelSourceFileSnapshot[] | undefined,
+): ModelSourceFileSnapshot {
+  if (!candidates || candidates.length === 0) return missingGeometryFile();
+  if (candidates.length !== 1) return duplicateGeometryPath(candidates);
+  return candidates[0]!;
+}
+
+export function createModelSourceDependencyResolver(
+  root: ModelSourceFileSnapshot,
+  files: readonly ModelSourceFileSnapshot[],
+  observer?: ModelSourceLookupObserver,
+): ModelSourceDependencyResolver {
+  const provenPaths = new Map<string, ModelSourceFileSnapshot[]>();
+  const siblingBasenames = new Map<string, ModelSourceFileSnapshot[]>();
+  for (const file of files) {
+    addCandidate(
+      file.hasPathEvidence ? provenPaths : siblingBasenames,
+      file.path,
+      file,
+    );
+    observer?.onIndexedFile?.();
+  }
+  freezeCandidates(provenPaths);
+  freezeCandidates(siblingBasenames);
+
+  const rootDirectory = root.path.split("/").slice(0, -1);
+  const resolvedCanonicalPaths = new Map<string, ModelSourceFileSnapshot>();
+
+  const resolve = (uriSegments: readonly string[]): ModelSourceFileSnapshot => {
+    let canonicalPath: string;
+    let candidateKey: string;
+    let candidateIndex: ReadonlyMap<string, readonly ModelSourceFileSnapshot[]>;
+    if (!root.hasPathEvidence) {
+      if (uriSegments.length !== 1) {
+        return failModelSourceBundle(
+          "bundle",
+          "unproven-buffer-path",
+          "Nested glTF buffers require browser-provided relative path evidence.",
+        );
+      }
+      canonicalPath = `sibling:${uriSegments[0]}`;
+      candidateKey = uriSegments[0]!;
+      candidateIndex = siblingBasenames;
+    } else {
+      const targetPath = [...rootDirectory, ...uriSegments].join("/");
+      canonicalPath = `path:${targetPath}`;
+      candidateKey = targetPath;
+      candidateIndex = provenPaths;
+    }
+
+    const cached = resolvedCanonicalPaths.get(canonicalPath);
+    if (cached) return cached;
+    observer?.onCanonicalResolution?.();
+    const dependency = selectCandidate(candidateIndex.get(candidateKey));
+    resolvedCanonicalPaths.set(canonicalPath, dependency);
+    return dependency;
+  };
+
+  return Object.freeze({ resolve });
+}

package/templates/runtime/model-import/model-source-package-normalization.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+
+import { createToolcraftModelFormatAdapterRegistry } from "./formats/model-format-adapter";
+import { getToolcraftModelPackageMimeType } from "./model-package-path";
+import type { ToolcraftExtractedModelPackageEntry } from "./model-package-types";
+import {
+  createToolcraftModelSourceBundleSnapshotFromExtractedPackage,
+} from "./model-source-bundle";
+import {
+  createModelSourceTestBundle as bundle,
+  modelSourceTestAdapter as adapter,
+  modelSourceTestBinaryFile as binaryFile,
+  modelSourceTestGltfWithBuffers as gltfWithBuffers,
+  modelSourceTestTextFile as textFile,
+} from "./model-source-bundle-test-support";
+import {
+  createModelSourceResourceRef,
+  digestModelSourceBytes,
+} from "./model-source-digest";
+
+describe("model source package normalization", () => {
+  it("canonicalizes equivalent selected-folder and ZIP packages identically", async () => {
+    const rootText = gltfWithBuffers(["buffers/mesh.bin"]);
+    const rootBytes = new TextEncoder().encode(rootText);
+    const meshBytes = new Uint8Array([1, 2, 3]);
+    const textureBytes = new Uint8Array([4, 5, 6]);
+    const selected = await bundle([
+      textFile("scene.gltf", rootText, {
+        path: "package/scene.gltf",
+        type: "model/gltf+json",
+      }),
+      binaryFile("mesh.bin", meshBytes, {
+        path: "package/buffers/mesh.bin",
+      }),
+      binaryFile("albedo.png", textureBytes, {
+        path: "package/textures/albedo.png",
+        type: "image/png",
+      }),
+    ]);
+    const extracted = [
+      ["package/textures/albedo.png", textureBytes],
+      ["package/buffers/mesh.bin", meshBytes],
+      ["package/scene.gltf", rootBytes],
+    ].map(([path, bytes]) => {
+      const owned = bytes as Uint8Array;
+      return Object.freeze({
+        bytes: owned.slice().buffer,
+        compressedBytes: owned.byteLength,
+        contentDigest: digestModelSourceBytes(owned),
+        mimeType: getToolcraftModelPackageMimeType(path as string),
+        path: path as string,
+        uncompressedBytes: owned.byteLength,
+      }) satisfies ToolcraftExtractedModelPackageEntry;
+    });
+    const archiveDigest = `sha256:${"f".repeat(64)}`;
+    const zipped = await createToolcraftModelSourceBundleSnapshotFromExtractedPackage(
+      extracted,
+      {
+        archive: {
+          byteLength: 99,
+          contentDigest: archiveDigest,
+          displayName: "package.zip",
+          mimeType: "application/zip",
+          resourceRef: createModelSourceResourceRef(
+            archiveDigest,
+            "application/zip",
+          ),
+        },
+        kind: "zip",
+      },
+      { registry: createToolcraftModelFormatAdapterRegistry([
+        adapter("gltf", ".gltf"),
+      ]) },
+    );
+
+    expect(zipped.bundle.rootPath).toBe(selected.rootPath);
+    expect(zipped.bundle.sourceFiles).toEqual(selected.sourceFiles);
+    expect(zipped.bundle.aggregateDigest).toBe(selected.aggregateDigest);
+    expect(selected.packageSource).toEqual({ kind: "selected-files" });
+    expect(zipped.bundle.packageSource).toMatchObject({ kind: "zip" });
+  });
+
+  it("selects the first normalized root and summarizes ignored roots", async () => {
+    const result = await bundle([
+      binaryFile("z.glb", [2], { path: "package/z.glb" }),
+      binaryFile("a.glb", [1], { path: "package/a.glb" }),
+      binaryFile("preview.png", [3], {
+        path: "package/preview.png",
+        type: "image/png",
+      }),
+    ]);
+
+    expect(result.rootPath).toBe("package/a.glb");
+    expect(result.sourceFiles.map(({ path }) => path)).toEqual([
+      "package/a.glb",
+      "package/preview.png",
+    ]);
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({
+        affectedCount: 1,
+        code: "ignored-model-root",
+        severity: "info",
+      }),
+    ]);
+  });
+});