@nodaro/shared 2.27.0 → 3.1.0

package/src/__tests__/scene3d-v2-fixtures.ts

@@ -0,0 +1,232 @@
+/**
+ * Shared v2 fixtures. Deliberately generic (`e1`, `shot-1`, one car-ish
+ * assembly) — the contract has no opinion about what a scene contains, and a
+ * fixture that encodes one would quietly become a spec.
+ *
+ * The one non-arbitrary thing here is the SHAPE of the timeline: 720 frames at
+ * 24 fps cut into `[0,360) [360,432) [432,492) [492,720)`. That is the exact
+ * multi-shot arrangement the format has to carry, so every coverage test uses
+ * it rather than a two-shot toy.
+ */
+import {
+  SCENE3D_CAMERA_TRACK_FORMAT,
+  SCENE3D_CAMERA_TRACK_VERSION,
+  type Scene3DCameraSample,
+  type Scene3DCameraTrackV1,
+} from "../scene3d-camera-track.js"
+import { SCENE3D_SCHEMA_VERSION_V2, type Scene3DPlanV2, type Scene3DShot } from "../scene3d-v2.js"
+import { SCENE3D_PLAN_TYPE } from "../scene3d.js"
+
+export const FIXTURE_WIDTH = 1680
+export const FIXTURE_HEIGHT = 720
+export const FIXTURE_FPS = 24
+export const FIXTURE_FRAMES = 720
+
+/** The cut plan the format must be able to express exactly. */
+export const FIXTURE_CUTS: ReadonlyArray<readonly [number, number]> = [
+  [0, 360],
+  [360, 432],
+  [432, 492],
+  [492, 720],
+]
+
+const REVISION_ID = "6d5b0b64-2b6c-4d4a-9e4f-2f4b7f6a1c01"
+const PARENT_REVISION_ID = "6d5b0b64-2b6c-4d4a-9e4f-2f4b7f6a1c00"
+const HASH_A = "a".repeat(64)
+const HASH_B = "b".repeat(64)
+const HASH_C = "c".repeat(64)
+const HASH_D = "d".repeat(64)
+
+/**
+ * A symmetric column-major perspective matrix, exactly as Three.js and every
+ * glTF camera build one. `m[0]/m[5]` is `height/width`, which is what the
+ * manifest cross-check reads.
+ */
+export function perspectiveMatrix(
+  fovYDegrees: number,
+  aspect: number,
+  near: number,
+  far: number,
+): number[] {
+  const top = near * Math.tan((fovYDegrees * Math.PI) / 360)
+  const height = 2 * top
+  const width = height * aspect
+  const matrix = new Array<number>(16).fill(0)
+  matrix[0] = (2 * near) / width
+  matrix[5] = (2 * near) / height
+  matrix[10] = -(far + near) / (far - near)
+  matrix[11] = -1
+  matrix[14] = (-2 * far * near) / (far - near)
+  return matrix
+}
+
+/** An orthographic matrix — the thing the projection validator must NAME rather
+ *  than mis-read as a broken perspective. */
+export function orthographicMatrix(near: number, far: number): number[] {
+  const matrix = new Array<number>(16).fill(0)
+  matrix[0] = 1
+  matrix[5] = 1
+  matrix[10] = -2 / (far - near)
+  matrix[14] = -(far + near) / (far - near)
+  matrix[15] = 1
+  return matrix
+}
+
+export function cameraSample(overrides: Partial<Scene3DCameraSample> = {}): Scene3DCameraSample {
+  return {
+    position: [0, 1.5, 4],
+    quaternion: [0, 0, 0, 1],
+    projectionMatrix: perspectiveMatrix(35, FIXTURE_WIDTH / FIXTURE_HEIGHT, 0.1, 200),
+    near: 0.1,
+    far: 200,
+    ...overrides,
+  }
+}
+
+export function cameraTrack(
+  frameCount = FIXTURE_FRAMES,
+  overrides: Partial<Scene3DCameraTrackV1> = {},
+): Scene3DCameraTrackV1 {
+  return {
+    format: SCENE3D_CAMERA_TRACK_FORMAT,
+    version: SCENE3D_CAMERA_TRACK_VERSION,
+    frameStart: 0,
+    frameCount,
+    fps: FIXTURE_FPS,
+    samples: Array.from({ length: frameCount }, (_unused, frame) =>
+      cameraSample({ position: [frame / 100, 1.5, 4] }),
+    ),
+    ...overrides,
+  }
+}
+
+export function fixtureShots(): Scene3DShot[] {
+  return FIXTURE_CUTS.map(([startFrame, endFrameExclusive], index) => ({
+    id: `shot-${index + 1}`,
+    startFrame,
+    endFrameExclusive,
+    subjectEntityIds: ["e2"],
+    foregroundEntityIds: ["e3"],
+  }))
+}
+
+/**
+ * A complete, valid v2 manifest: one group assembly with an asset child and a
+ * primitive sibling, three renderer-visible assets plus a retained source, four
+ * contiguous shots, one of each override kind.
+ */
+export function planV2(overrides: Partial<Scene3DPlanV2> = {}): Scene3DPlanV2 {
+  return {
+    planType: SCENE3D_PLAN_TYPE,
+    schemaVersion: SCENE3D_SCHEMA_VERSION_V2,
+    revisionId: REVISION_ID,
+    parentRevisionId: PARENT_REVISION_ID,
+    width: FIXTURE_WIDTH,
+    height: FIXTURE_HEIGHT,
+    fps: FIXTURE_FPS,
+    durationInFrames: FIXTURE_FRAMES,
+    units: "meters",
+    upAxis: "Y",
+    handedness: "right",
+    objects: [
+      {
+        id: "e1",
+        name: "Assembly",
+        role: "other",
+        position: [0, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1],
+        visual: { kind: "group" },
+      },
+      {
+        id: "e2",
+        name: "Vehicle",
+        parentId: "e1",
+        role: "vehicle",
+        identityColor: "#3355ff",
+        anchors: [
+          { name: "roof", position: [0, 1.4, 0] },
+          { name: "wheel.frontLeft", position: [0.8, 0.3, 1.2] },
+        ],
+        capabilities: ["transform", "color", "visibility"],
+        materialBindings: [
+          { role: "bodyPaint", materialName: "Body Paint", color: "#3355ff" },
+          { role: "tires", materialName: "Rubber", roughness: 0.9 },
+        ],
+        visual: {
+          kind: "asset",
+          assetId: "asset-vehicle",
+          rootNodeId: "vehicle_root",
+          animation: { clipName: "drive", startFrame: 0, endFrameExclusive: 720 },
+        },
+      },
+      {
+        id: "e3",
+        name: "Marker",
+        role: "prop",
+        position: [2, 0, 0],
+        rotation: [0, 0, 0],
+        scale: [1, 1, 1],
+        visual: { kind: "primitive", primitive: "box", dimensions: [1, 1, 1], color: "#22cc88" },
+      },
+    ],
+    assets: [
+      { assetId: "asset-vehicle", kind: "glb", role: "entity-geometry", byteLength: 1_200_000, sha256: HASH_A },
+      { assetId: "asset-track", kind: "camera-track-json", role: "camera-track", byteLength: 640_000, sha256: HASH_B },
+      { assetId: "asset-poster", kind: "poster", role: "poster", byteLength: 90_000, sha256: HASH_C },
+      { assetId: "asset-source", kind: "blend-source", role: "source", byteLength: 40_000_000, sha256: HASH_D },
+    ],
+    cameraTrackAssetId: "asset-track",
+    shots: fixtureShots(),
+    lighting: {
+      preset: "clay-studio-v1",
+      ambientIntensity: 0.6,
+      keyIntensity: 2.4,
+      keyPosition: [4, 6, 3],
+    },
+    backgroundColor: "#101014",
+    overrides: [
+      {
+        id: "ov-1",
+        sourceRevisionId: PARENT_REVISION_ID,
+        sourceContentHash: HASH_A,
+        operationVersion: 1,
+        kind: "entity-transform",
+        entityId: "e2",
+        space: "world",
+        position: [1, 0, 0],
+      },
+      {
+        id: "ov-2",
+        sourceRevisionId: PARENT_REVISION_ID,
+        sourceContentHash: HASH_A,
+        operationVersion: 1,
+        kind: "entity-color",
+        entityId: "e2",
+        materialRole: "bodyPaint",
+        color: "#ff2200",
+      },
+      {
+        id: "ov-3",
+        sourceRevisionId: PARENT_REVISION_ID,
+        sourceContentHash: HASH_A,
+        operationVersion: 1,
+        kind: "camera-shot-offset",
+        shotId: "shot-2",
+        positionOffset: [0, 0.1, 0],
+      },
+    ],
+    provenance: {
+      engine: "blender-cloud",
+      engineVersion: "1.4.0",
+      recipeVersion: "1.0.0",
+      compilerVersion: "0.9.2",
+      exporterVersion: "0.9.2",
+      rendererVersion: "3.1.0",
+      sourceRevisionId: PARENT_REVISION_ID,
+      sourceArtifactId: "asset-source",
+      contentHash: "0".repeat(64),
+    },
+    ...overrides,
+  }
+}

package/src/__tests__/scene3d-v2-resources.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest"
+import { SCENE3D_V2_LIMITS, type Scene3DEntityV2 } from "../scene3d-v2.js"
+import {
+  SCENE3D_V2_CONTENT_HASH_EXCLUDED,
+  canonicalScene3DPlanV2Json,
+  computeScene3DPlanV2ContentHash,
+  parseScene3DPlanV2Json,
+  scene3DV2AdmissionIssues,
+  scene3DV2HierarchyDepth,
+  scene3DV2NormalizationIssues,
+  scene3DV2ResourceUsage,
+  verifyScene3DPlanV2ContentHash,
+  type Scene3DNormalizedAssetStats,
+} from "../scene3d-v2-resources.js"
+import { FIXTURE_FRAMES, planV2 } from "./scene3d-v2-fixtures.js"
+
+function stats(overrides: Partial<Scene3DNormalizedAssetStats>[] = []): Scene3DNormalizedAssetStats[] {
+  const plan = planV2()
+  const base: Scene3DNormalizedAssetStats[] = plan.assets.map((asset) => ({
+    assetId: asset.assetId,
+    kind: asset.kind,
+    byteLength: asset.byteLength,
+    sha256: asset.sha256,
+    ...(asset.kind === "glb" ? { meshNodes: 40, triangles: 12_000, maxNodeDepth: 4 } : {}),
+    ...(asset.kind === "poster" ? { imageWidth: 1680, imageHeight: 720 } : {}),
+  }))
+  overrides.forEach((patch, index) => {
+    if (base[index]) base[index] = { ...base[index], ...patch }
+  })
+  return base
+}
+
+describe("scene3d v2 resources — declared usage", () => {
+  it("reports what the manifest claims", () => {
+    const usage = scene3DV2ResourceUsage(planV2())
+    expect(usage.entities).toBe(3)
+    expect(usage.assets).toBe(4)
+    expect(usage.shots).toBe(4)
+    expect(usage.overrides).toBe(3)
+    expect(usage.frames).toBe(FIXTURE_FRAMES)
+    expect(usage.durationSeconds).toBe(30)
+    expect(usage.hierarchyDepth).toBe(2)
+    // The native source is excluded from the renderer budget.
+    expect(usage.rendererAssetBytes).toBe(1_200_000 + 640_000 + 90_000)
+    expect(usage.blendSourceBytes).toBe(40_000_000)
+    expect(usage.cameraTrackBytes).toBe(640_000)
+  })
+
+  it("measures hierarchy depth without looping on a cyclic plan", () => {
+    const cyclic: Scene3DEntityV2[] = [
+      { id: "a", name: "a", parentId: "b", visual: { kind: "group" }, position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1] },
+      { id: "b", name: "b", parentId: "a", visual: { kind: "group" }, position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1] },
+    ]
+    expect(scene3DV2HierarchyDepth(cyclic)).toBe(2)
+  })
+})
+
+describe("scene3d v2 resources — pre-allocation gate", () => {
+  it("passes the fixture", () => {
+    expect(scene3DV2AdmissionIssues(planV2())).toEqual([])
+    expect(scene3DV2AdmissionIssues(planV2(), 40_000)).toEqual([])
+  })
+
+  it("refuses an oversized manifest", () => {
+    const issues = scene3DV2AdmissionIssues(planV2(), SCENE3D_V2_LIMITS.maxManifestBytes + 1)
+    expect(issues.map((issue) => issue.message).join(" ")).toContain("manifest is")
+  })
+
+  it("refuses a scene past either duration ceiling", () => {
+    expect(
+      scene3DV2AdmissionIssues(planV2({ durationInFrames: 3601 })).map((issue) => issue.message).join(" "),
+    ).toContain("3601 frames")
+    expect(
+      scene3DV2AdmissionIssues(planV2({ fps: 15, durationInFrames: 3000 })).map((issue) => issue.message).join(" "),
+    ).toContain("the limit is 60s")
+  })
+
+  it("refuses declared asset bytes past the download budget", () => {
+    const plan = planV2()
+    plan.assets[0] = { ...plan.assets[0], byteLength: SCENE3D_V2_LIMITS.maxRendererAssetBytes }
+    expect(scene3DV2AdmissionIssues(plan).map((issue) => issue.message).join(" ")).toContain(
+      "downloaded scene assets total",
+    )
+  })
+
+  it("refuses too many entities or shots", () => {
+    const many = Array.from({ length: 101 }, (_unused, index) => ({
+      id: `n${index}`,
+      name: `n${index}`,
+      position: [0, 0, 0] as [number, number, number],
+      rotation: [0, 0, 0] as [number, number, number],
+      scale: [1, 1, 1] as [number, number, number],
+      visual: { kind: "group" as const },
+    }))
+    expect(scene3DV2AdmissionIssues(planV2({ objects: many })).map((i) => i.message).join(" ")).toContain(
+      "101 entities",
+    )
+  })
+})
+
+describe("scene3d v2 resources — post-decode gate", () => {
+  it("passes matching stats", () => {
+    expect(scene3DV2NormalizationIssues(planV2(), stats())).toEqual([])
+  })
+
+  it("catches bytes that do not match the manifest", () => {
+    const issues = scene3DV2NormalizationIssues(planV2(), stats([{ byteLength: 999 }]))
+    expect(issues.map((issue) => issue.message).join(" ")).toContain("is 999 bytes; the manifest declares")
+  })
+
+  it("catches a digest that does not match", () => {
+    const issues = scene3DV2NormalizationIssues(planV2(), stats([{ sha256: "9".repeat(64) }]))
+    expect(issues.map((issue) => issue.message).join(" ")).toContain("digest does not match")
+  })
+
+  it("catches an undeclared asset and a kind that changed after decode", () => {
+    const foreign = scene3DV2NormalizationIssues(planV2(), [
+      { assetId: "asset-ghost", kind: "glb", byteLength: 10 },
+    ])
+    expect(foreign.map((issue) => issue.message).join(" ")).toContain("is not declared in the manifest")
+
+    const wrongKind = scene3DV2NormalizationIssues(planV2(), stats([{ kind: "poster" }]))
+    expect(wrongKind.map((issue) => issue.message).join(" ")).toContain("decoded as")
+  })
+
+  it("sums triangles and mesh nodes across assets — compression waives nothing", () => {
+    // A small file that decodes past the geometry budget is still refused.
+    const overTriangles = scene3DV2NormalizationIssues(
+      planV2(),
+      stats([{ triangles: SCENE3D_V2_LIMITS.maxTriangles + 1 }]),
+    )
+    expect(overTriangles.map((issue) => issue.message).join(" ")).toContain("triangles; the limit is 200000")
+
+    const overNodes = scene3DV2NormalizationIssues(planV2(), stats([{ meshNodes: 2001 }]))
+    expect(overNodes.map((issue) => issue.message).join(" ")).toContain("2001 mesh nodes")
+  })
+
+  it("bounds node depth and image dimensions", () => {
+    const deep = scene3DV2NormalizationIssues(planV2(), stats([{ maxNodeDepth: 17 }]))
+    expect(deep.map((issue) => issue.message).join(" ")).toContain("nests 17 levels")
+
+    const huge = scene3DV2NormalizationIssues(planV2(), stats([{}, {}, { imageWidth: 9000 }]))
+    expect(huge.map((issue) => issue.message).join(" ")).toContain("imageWidth is 9000")
+  })
+
+  it("bounds decoded renderer bytes even when the manifest lied consistently", () => {
+    const plan = planV2()
+    plan.assets[0] = { ...plan.assets[0], byteLength: 70 * 1024 * 1024 }
+    const issues = scene3DV2NormalizationIssues(plan, stats([{ byteLength: 70 * 1024 * 1024 }]))
+    expect(issues.map((issue) => issue.message).join(" ")).toContain("decoded to")
+  })
+})
+
+describe("scene3d v2 resources — manifest admission", () => {
+  it("accepts a valid manifest payload", () => {
+    const result = parseScene3DPlanV2Json(JSON.stringify(planV2()))
+    expect(result.ok).toBe(true)
+    expect(result.ok && result.value.schemaVersion).toBe(2)
+  })
+
+  it("refuses an oversized manifest before parsing", () => {
+    const result = parseScene3DPlanV2Json("x".repeat(SCENE3D_V2_LIMITS.maxManifestBytes + 1))
+    expect(result.ok).toBe(false)
+    expect(result.ok ? "" : result.issues[0].message).toContain("manifest is")
+  })
+
+  it("reports malformed JSON and schema failures as issues", () => {
+    expect(parseScene3DPlanV2Json("{{").ok).toBe(false)
+    const broken = parseScene3DPlanV2Json(JSON.stringify(planV2({ shots: [] })))
+    expect(broken.ok).toBe(false)
+    expect(broken.ok ? [] : broken.issues.length).toBeGreaterThan(0)
+  })
+})
+
+describe("scene3d v2 resources — content hash", () => {
+  it("excludes identity, includes content", () => {
+    expect([...SCENE3D_V2_CONTENT_HASH_EXCLUDED]).toEqual(["revisionId", "parentRevisionId"])
+    const canonical = canonicalScene3DPlanV2Json(planV2())
+    expect(canonical).not.toContain("revisionId")
+    expect(canonical).not.toContain("contentHash")
+    expect(canonical).toContain("bodyPaint")
+    expect(canonical).toContain("shot-2")
+  })
+
+  it("is stable under key reordering and identity changes", async () => {
+    const a = planV2()
+    const reordered = JSON.parse(JSON.stringify({ ...a })) as typeof a
+    // Rebuild the top level in reverse key order.
+    const shuffled = Object.fromEntries(
+      Object.entries(reordered).reverse(),
+    ) as unknown as typeof a
+    expect(canonicalScene3DPlanV2Json(shuffled)).toBe(canonicalScene3DPlanV2Json(a))
+
+    const otherRevision = planV2({ revisionId: "7d5b0b64-2b6c-4d4a-9e4f-2f4b7f6a1c99" })
+    expect(await computeScene3DPlanV2ContentHash(otherRevision)).toBe(
+      await computeScene3DPlanV2ContentHash(a),
+    )
+  })
+
+  it("changes when any content changes", async () => {
+    const base = await computeScene3DPlanV2ContentHash(planV2())
+    const recoloured = planV2()
+    recoloured.objects[1].materialBindings = [
+      { role: "bodyPaint", materialName: "Body Paint", color: "#00ff00" },
+      { role: "tires", materialName: "Rubber", roughness: 0.9 },
+    ]
+    expect(await computeScene3DPlanV2ContentHash(recoloured)).not.toBe(base)
+
+    const withoutOverride = planV2({ overrides: [] })
+    expect(await computeScene3DPlanV2ContentHash(withoutOverride)).not.toBe(base)
+
+    const differentDigest = planV2()
+    differentDigest.assets[0] = { ...differentDigest.assets[0], sha256: "1".repeat(64) }
+    expect(await computeScene3DPlanV2ContentHash(differentDigest)).not.toBe(base)
+  })
+
+  it("normalizes -0 so it cannot fork the hash", () => {
+    const zero = planV2()
+    zero.objects[2].position = [0, 0, 0]
+    const negativeZero = planV2()
+    negativeZero.objects[2].position = [-0, 0, 0]
+    expect(canonicalScene3DPlanV2Json(negativeZero)).toBe(canonicalScene3DPlanV2Json(zero))
+  })
+
+  it("produces 64 lowercase hex characters, and verifies a declared hash", async () => {
+    const plan = planV2()
+    const hash = await computeScene3DPlanV2ContentHash(plan)
+    expect(hash).toMatch(/^[0-9a-f]{64}$/)
+    expect(await verifyScene3DPlanV2ContentHash(plan)).toBe(false)
+    expect(
+      await verifyScene3DPlanV2ContentHash({ ...plan, provenance: { ...plan.provenance, contentHash: hash } }),
+    ).toBe(true)
+  })
+
+  it("omits undefined-valued keys instead of emitting them", () => {
+    const withUndefined = { ...planV2(), parentRevisionId: undefined }
+    expect(canonicalScene3DPlanV2Json(withUndefined)).toBe(canonicalScene3DPlanV2Json(planV2()))
+  })
+})