@hraness/slopcamera 3.2.4

package/src/spatial-scene/identity.ts

@@ -0,0 +1,260 @@
+import type { z } from "zod"
+import { SlopcameraCodeError } from "../code/errors.js"
+import { createBoundedJsonSnapshot, createBoundedJsonValueSnapshot, deepFreezeJson } from "../code/json-snapshot.js"
+import {
+  SPATIAL_SCENE_LIMITS, SpatialAssetManifestSchema, SpatialEntitySchema,
+  SpatialGeneratorIdSchema, SpatialSceneV1Schema,
+  type SpatialAnimation, type SpatialAssetManifest, type SpatialEntity,
+  type SpatialOverride, type SpatialSceneV1,
+} from "./contracts.js"
+
+export class SpatialSceneError extends SlopcameraCodeError {
+  readonly path: string
+  constructor(code: "invalid-data" | "conflict" | "not-found", message: string, path = "scene") {
+    super(code, message, { path })
+    this.name = "SpatialSceneError"
+    this.path = path
+  }
+}
+
+const limits = { maximumDepth: SPATIAL_SCENE_LIMITS.sourceDepth, maximumValues: SPATIAL_SCENE_LIMITS.sourceValues }
+
+/** Foreign objects are captured without invoking getters before schema parsing. */
+export function parseSpatialValue<Schema extends z.ZodType>(schema: Schema, input: unknown, name: string): z.infer<Schema> {
+  try {
+    const captured = createBoundedJsonValueSnapshot(input, SPATIAL_SCENE_LIMITS.sourceBytes, name, limits)
+    const parsed = schema.safeParse(captured.value)
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0]
+      throw new SpatialSceneError("invalid-data", issue?.message ?? `Invalid ${name}.`, `${name}.${issue?.path.join(".") ?? ""}`)
+    }
+    return parsed.data
+  } catch (error) {
+    if (error instanceof SpatialSceneError) throw error
+    throw new SpatialSceneError("invalid-data", error instanceof Error ? error.message : `Invalid ${name}.`, name)
+  }
+}
+
+export function spatialValueSha256(input: unknown): string {
+  return createBoundedJsonSnapshot(input, SPATIAL_SCENE_LIMITS.sourceBytes, "spatial identity", limits).sha256
+}
+
+/** Derived matrices add at most 22 scalar/container values per authored entity. */
+export function spatialStateValueSha256(input: unknown): string {
+  return createBoundedJsonSnapshot(input, SPATIAL_SCENE_LIMITS.sourceBytes * 4, "spatial state identity", {
+    maximumDepth: SPATIAL_SCENE_LIMITS.sourceDepth + 4,
+    maximumValues: SPATIAL_SCENE_LIMITS.sourceValues + SPATIAL_SCENE_LIMITS.entities * 24,
+  }).sha256
+}
+
+function compare(a: string, b: string): number { return a < b ? -1 : a > b ? 1 : 0 }
+export function sortSpatialBy<T>(items: readonly T[], id: (item: T) => string): T[] {
+  return [...items].sort((a, b) => compare(id(a), id(b)))
+}
+
+function unique<T>(items: readonly T[], id: (item: T) => string, path: string): Map<string, T> {
+  const result = new Map<string, T>()
+  for (const item of items) {
+    const key = id(item)
+    if (result.has(key)) throw new SpatialSceneError("invalid-data", `Duplicate identity ${key}.`, path)
+    result.set(key, item)
+  }
+  return result
+}
+
+function requireReference<T>(map: ReadonlyMap<string, T>, id: string, path: string): T {
+  const result = map.get(id)
+  if (result === undefined) throw new SpatialSceneError("invalid-data", `Missing reference ${id}.`, path)
+  return result
+}
+
+/** Iterative traversal bounds hierarchy and dependency checks without recursive stack use. */
+export function spatialTopologicalIds(edges: ReadonlyMap<string, readonly string[]>, name: string): readonly string[] {
+  const done = new Set<string>()
+  const active = new Set<string>()
+  const result: string[] = []
+  for (const id of edges.keys()) {
+    const pending: { id: string; exit: boolean }[] = [{ id, exit: false }]
+    while (pending.length) {
+      const next = pending.pop()!
+      if (next.exit) { active.delete(next.id); done.add(next.id); result.push(next.id); continue }
+      if (done.has(next.id)) continue
+      if (active.has(next.id)) throw new SpatialSceneError("invalid-data", `Cycle at ${next.id}.`, name)
+      const dependencies = requireReference(edges, next.id, name)
+      active.add(next.id)
+      pending.push({ id: next.id, exit: true })
+      for (const dependency of dependencies) pending.push({ id: dependency, exit: false })
+    }
+  }
+  return Object.freeze(result)
+}
+
+export function generatedSpatialEntityId(generatorId: string, key: string): string {
+  SpatialGeneratorIdSchema.parse(generatorId)
+  if (typeof key !== "string" || key.length < 1 || key.length > 256) throw new SpatialSceneError("invalid-data", "Generator keys must contain 1–256 characters.")
+  return `entity_${spatialValueSha256({ domain: "slopcamera.generated-entity.v1", generatorId, key })}`
+}
+
+function normalizeEntity(entity: SpatialEntity): SpatialEntity {
+  if (entity.kind === "mesh") return { ...entity, material: { ...entity.material, color: entity.material.color.toLowerCase() } }
+  if (entity.kind === "text" || entity.kind === "light") return { ...entity, color: entity.color.toLowerCase() }
+  return entity
+}
+
+function normalizeAsset(asset: SpatialAssetManifest): SpatialAssetManifest {
+  if (asset.interpretation.kind !== "video") return asset
+  const rate = asset.interpretation.frameRate
+  let divisor = rate.numerator, remainder = rate.denominator
+  while (remainder !== 0) { const next = divisor % remainder; divisor = remainder; remainder = next }
+  return { ...asset, interpretation: { ...asset.interpretation, frameRate: { numerator: rate.numerator / divisor, denominator: rate.denominator / divisor } } }
+}
+
+/** Hash retained authored entities before overrides or evaluation; no source is executed. */
+export function spatialGeneratorOutputSha256(input: unknown): string {
+  const entities = parseSpatialValue(SpatialEntitySchema.array().max(SPATIAL_SCENE_LIMITS.entities), input, "generator output")
+  unique(entities, item => item.entityId, "generator output")
+  return spatialValueSha256({ domain: "slopcamera.generator-output.v1", entities: sortSpatialBy(entities.map(normalizeEntity), item => item.entityId) })
+}
+
+/** Locators and descriptive provenance are excluded; interpretation and dependency digests are bound. */
+export function spatialAssetManifestSha256(input: unknown, dependencyDigests: Readonly<Record<string, string>> = {}): string {
+  const asset = normalizeAsset(parseSpatialValue(SpatialAssetManifestSchema, input, "asset manifest"))
+  const captured = createBoundedJsonValueSnapshot(dependencyDigests, SPATIAL_SCENE_LIMITS.sourceBytes, "dependency identities", limits).value
+  if (captured === null || Array.isArray(captured) || typeof captured !== "object") throw new SpatialSceneError("invalid-data", "Dependency digests must be an object.")
+  unique(asset.dependencies, item => item, "asset.dependencies")
+  const dependencies = [...asset.dependencies].sort(compare).map(assetId => {
+    const sha256 = (captured as Readonly<Record<string, unknown>>)[assetId]
+    if (typeof sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(sha256)) throw new SpatialSceneError("invalid-data", `Missing dependency digest for ${assetId}.`)
+    return { assetId, sha256 }
+  })
+  return spatialValueSha256({ domain: "slopcamera.asset-manifest.v1", payload: { sha256: asset.payload.sha256, bytes: asset.payload.bytes }, interpretation: asset.interpretation, dependencies })
+}
+
+export function spatialAssetClosureDigests(assets: readonly SpatialAssetManifest[]): Readonly<Record<string, string>> {
+  const map = unique(assets, asset => asset.assetId, "assets")
+  const order = spatialTopologicalIds(new Map(assets.map(asset => [asset.assetId, asset.dependencies])), "asset dependencies")
+  const digests: Record<string, string> = Object.create(null) as Record<string, string>
+  for (const id of order) digests[id] = spatialAssetManifestSha256(map.get(id)!, digests)
+  return Object.freeze(digests)
+}
+
+export function spatialPropertySupported(entity: SpatialEntity, property: SpatialOverride["property"] | SpatialAnimation["property"]): boolean {
+  if ((property === "color" || property === "opacity") && entity.kind === "mesh"
+    && entity.geometry.kind === "asset" && entity.geometry.materialMode === "source") return false
+  if (property === "opacity") return ["mesh", "image", "video", "diagram"].includes(entity.kind)
+  if (property === "color") return ["mesh", "text", "light"].includes(entity.kind)
+  return true
+}
+
+/** One property writer per interval; a transform override owns position, rotation and scale. */
+export function validateSpatialOverrides(scene: SpatialSceneV1, overrides: readonly SpatialOverride[]): void {
+  const entities = new Map(scene.entities.map(entity => [entity.entityId, entity]))
+  const generators = new Map(scene.generators.map(generator => [generator.generatorId, generator]))
+  unique(overrides, override => `${override.entityId}:${override.property}`, "overrides")
+  for (const override of overrides) {
+    const entity = requireReference(entities, override.entityId, "overrides")
+    if (!spatialPropertySupported(entity, override.property)) throw new SpatialSceneError("conflict", `Entity ${entity.entityId} does not support ${override.property}.`, "overrides")
+    if (entity.origin.kind === "generated") {
+      const origin = entity.origin
+      const generator = requireReference(generators, origin.generatorId, "overrides")
+      if (!generator.editableKeys.some(item => item.key === origin.key && item.properties.includes(override.property))) {
+        throw new SpatialSceneError("conflict", `Undeclared override ${origin.key}.${override.property}.`, "overrides")
+      }
+    }
+    const properties = override.property === "transform" ? ["position", "rotation", "scale"] : [override.property]
+    if (scene.animations.some(channel => channel.targetId === entity.entityId && properties.includes(channel.property))) {
+      throw new SpatialSceneError("conflict", `Animation and override both write ${entity.entityId}.${override.property}.`, "overrides")
+    }
+  }
+}
+
+export function parseSpatialScene(input: unknown): SpatialSceneV1 {
+  const parsed = parseSpatialValue(SpatialSceneV1Schema, input, "scene")
+  const scene: SpatialSceneV1 = {
+    ...parsed,
+    entities: sortSpatialBy(parsed.entities.map(normalizeEntity), item => item.entityId),
+    cameras: sortSpatialBy(parsed.cameras, item => item.cameraId),
+    assets: sortSpatialBy(parsed.assets.map(normalizeAsset).map(asset => ({ ...asset, dependencies: [...asset.dependencies].sort(compare) })), item => item.assetId),
+    animations: sortSpatialBy(parsed.animations, item => item.channelId),
+    generators: sortSpatialBy(parsed.generators.map(generator => ({ ...generator, editableKeys: sortSpatialBy(generator.editableKeys.map(item => ({ ...item, properties: [...item.properties].sort(compare) })), item => item.key) })), item => item.generatorId),
+    overrides: sortSpatialBy(parsed.overrides.map(item => item.property === "color" ? { ...item, value: item.value.toLowerCase() } : item), item => `${item.entityId}:${item.property}`),
+  }
+  const entities = unique(scene.entities, entity => entity.entityId, "entities")
+  const cameras = unique(scene.cameras, camera => camera.cameraId, "cameras")
+  const assets = unique(scene.assets, asset => asset.assetId, "assets")
+  const generators = unique(scene.generators, generator => generator.generatorId, "generators")
+  unique(scene.animations, channel => channel.channelId, "animations")
+  unique(scene.animations, channel => `${channel.targetId}:${channel.property}`, "animation writers")
+  let payloadBytes = 0
+  for (const asset of scene.assets) {
+    unique(asset.dependencies, id => id, "asset dependencies")
+    payloadBytes += asset.payload.bytes
+    if (payloadBytes > 268_435_456) throw new SpatialSceneError("invalid-data", "Asset closure exceeds 256 MiB.", "assets")
+    if ((asset.interpretation.kind === "image" || asset.interpretation.kind === "video") && asset.interpretation.width * asset.interpretation.height > 33_554_432) throw new SpatialSceneError("invalid-data", "Asset exceeds the 32-megapixel limit.", "assets")
+    if (asset.interpretation.kind === "metadata" && asset.payload.bytes > 1_048_576) throw new SpatialSceneError("invalid-data", "Retained metadata exceeds one MiB.", "assets")
+  }
+  spatialTopologicalIds(new Map(scene.assets.map(asset => [asset.assetId, asset.dependencies])), "asset dependencies")
+  spatialTopologicalIds(new Map(scene.entities.map(entity => [entity.entityId, entity.parentId === null ? [] : [entity.parentId]])), "entity hierarchy")
+  const generatedKeys = new Set<string>()
+  for (const entity of scene.entities) {
+    if (entity.placement.kind === "view") requireReference(cameras, entity.placement.cameraId, "placement")
+    if (entity.parentId !== null) {
+      const parent = requireReference(entities, entity.parentId, "parent")
+      const a = parent.placement, b = entity.placement
+      if (a.kind !== b.kind || (a.kind === "view" && b.kind === "view" && (a.cameraId !== b.cameraId || a.units !== b.units))) throw new SpatialSceneError("invalid-data", "Parent and child must share their world or view coordinate domain.", "placement")
+    }
+    if (entity.origin.kind === "generated") {
+      const { generatorId, key } = entity.origin
+      requireReference(generators, generatorId, "origin")
+      if (entity.entityId !== generatedSpatialEntityId(generatorId, key)) throw new SpatialSceneError("invalid-data", "Generated entity identity must derive from its generator and stable key.", "origin")
+      const identity = `${generatorId}:${key}`
+      if (generatedKeys.has(identity)) throw new SpatialSceneError("invalid-data", "Duplicate generator output key.", "origin")
+      generatedKeys.add(identity)
+    }
+    const reference = entity.kind === "mesh" && entity.geometry.kind === "asset" ? { assetId: entity.geometry.assetId, kind: "gltf" }
+      : entity.kind === "text" ? { assetId: entity.fontAssetId, kind: "font" }
+      : "assetId" in entity ? { assetId: entity.assetId, kind: entity.kind } : undefined
+    if (reference) {
+      const asset = requireReference(assets, reference.assetId, "entity asset")
+      if (asset.interpretation.kind !== reference.kind) throw new SpatialSceneError("invalid-data", `Entity ${entity.entityId} requires a ${reference.kind} asset.`, "entity asset")
+      if (entity.kind === "video" && asset.interpretation.kind === "video" && entity.sourceOffsetUs >= asset.interpretation.durationUs) throw new SpatialSceneError("invalid-data", "Video source offset must precede its duration.", "sourceOffsetUs")
+    }
+  }
+  for (const generator of scene.generators) {
+    unique(generator.editableKeys, item => item.key, "generator editable keys")
+    for (const editable of generator.editableKeys) {
+      unique(editable.properties, item => item, "generator editable properties")
+      const entity = entities.get(generatedSpatialEntityId(generator.generatorId, editable.key))
+      if (!entity) throw new SpatialSceneError("conflict", `Orphan editable key ${editable.key}.`, "generators")
+      if (editable.properties.some(property => !spatialPropertySupported(entity, property))) throw new SpatialSceneError("invalid-data", `Editable key ${editable.key} declares an unsupported property.`, "generators")
+    }
+    const retained = scene.entities.filter(entity => entity.origin.kind === "generated" && entity.origin.generatorId === generator.generatorId)
+    if (spatialGeneratorOutputSha256(retained) !== generator.outputSha256) throw new SpatialSceneError("conflict", "Retained generator output does not match its pinned digest.", "generators")
+  }
+  for (const channel of scene.animations) {
+    const entity = entities.get(channel.targetId)
+    if (entity === undefined) {
+      requireReference(cameras, channel.targetId, "animation target")
+      if (channel.property !== "position" && channel.property !== "rotation") throw new SpatialSceneError("invalid-data", "Camera animation supports only position and rotation.", "animations")
+    } else {
+      if (!spatialPropertySupported(entity, channel.property)) throw new SpatialSceneError("invalid-data", `Unsupported ${channel.property} animation.`, "animations")
+      if (entity.origin.kind === "generated") {
+        const origin = entity.origin
+        const control = channel.property === "opacity" ? "opacity" : "transform"
+        if (!generators.get(origin.generatorId)!.editableKeys.some(item => item.key === origin.key && item.properties.includes(control))) throw new SpatialSceneError("conflict", `Generated animation requires declared ${control} control.`, "animations")
+      }
+    }
+    let previous = -1
+    for (const key of channel.keys) {
+      if (key.timeUs <= previous || key.timeUs > scene.durationUs) throw new SpatialSceneError("invalid-data", "Animation keys must be strictly ordered within scene duration.", "animations")
+      previous = key.timeUs
+    }
+  }
+  validateSpatialOverrides(scene, scene.overrides)
+  // Freeze the normalized, validated authored document without any renderer or host effects.
+  return deepFreezeJson(scene)
+}
+
+export function spatialSceneSha256(input: unknown): string {
+  return spatialValueSha256(parseSpatialScene(input))
+}

package/src/spatial-scene/index.ts

@@ -0,0 +1,10 @@
+export * from "./contracts.js"
+export * from "./identity.js"
+export * from "./patch.js"
+export * from "./inspect.js"
+export * from "./evaluate.js"
+export * from "./math.js"
+export * from "./time.js"
+export * from "./authoring.js"
+export * from "./gltf.js"
+export * from "./camera-track.js"

package/src/spatial-scene/inspect.ts

@@ -0,0 +1,68 @@
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import type { SpatialEntity, SpatialOverride, SpatialSceneV1 } from "./contracts.js"
+import { evaluateSpatialScene } from "./evaluate.js"
+import { parseSpatialScene, spatialAssetClosureDigests, spatialPropertySupported, spatialValueSha256 } from "./identity.js"
+import { transformBounds, type Bounds, type Vec3 } from "./math.js"
+
+export type SpatialInspectedBounds =
+  | { readonly status: "authored-enclosure"; readonly coordinateDomain: SpatialEntity["placement"]; readonly atTimeUs: 0; readonly bounds: Bounds }
+  | { readonly status: "unknown"; readonly reason: "requires-asset-decoding" | "requires-text-layout" | "no-surface" }
+
+export interface SpatialSceneInspection {
+  readonly sceneId: string
+  readonly sceneSha256: string
+  readonly durationUs: number
+  readonly entities: readonly {
+    readonly entityId: string
+    readonly name: string
+    readonly kind: SpatialEntity["kind"]
+    readonly origin: SpatialEntity["origin"]
+    readonly parentId: string | null
+    readonly placement: SpatialEntity["placement"]
+    readonly editableControls: readonly SpatialOverride["property"][]
+    readonly animatedProperties: readonly string[]
+    readonly assetIds: readonly string[]
+    readonly bounds: SpatialInspectedBounds
+  }[]
+  readonly cameras: SpatialSceneV1["cameras"]
+  readonly assets: readonly { readonly assetId: string; readonly manifestSha256: string; readonly manifest: SpatialSceneV1["assets"][number] }[]
+  readonly generators: SpatialSceneV1["generators"]
+}
+
+function localBounds(entity: SpatialEntity): Bounds | SpatialInspectedBounds {
+  let half: Vec3
+  if (entity.kind === "mesh") {
+    switch (entity.geometry.kind) {
+      case "asset": return { status: "unknown", reason: "requires-asset-decoding" }
+      case "box": half = entity.geometry.size.map(value => value / 2) as unknown as Vec3; break
+      case "plane": half = [entity.geometry.width / 2, entity.geometry.height / 2, 0]; break
+      case "sphere": half = [entity.geometry.radius, entity.geometry.radius, entity.geometry.radius]; break
+      case "cylinder": half = [entity.geometry.radius, entity.geometry.height / 2, entity.geometry.radius]; break
+    }
+  } else if (entity.kind === "image" || entity.kind === "diagram" || entity.kind === "video") half = [entity.width / 2, entity.height / 2, 0]
+  else return { status: "unknown", reason: entity.kind === "text" ? "requires-text-layout" : entity.kind === "splat" ? "requires-asset-decoding" : "no-surface" }
+  return { min: [-half[0], -half[1], -half[2]], max: half }
+}
+
+/** Authored enclosures are labelled explicitly; inspection never decodes or invents imported bounds. */
+export function inspectSpatialScene(input: unknown): SpatialSceneInspection {
+  const scene = parseSpatialScene(input)
+  const snapshot = evaluateSpatialScene(scene, { timeUs: 0, cameraId: scene.cameras[0]!.cameraId })
+  const digests = spatialAssetClosureDigests(scene.assets)
+  return deepFreezeJson({
+    sceneId: scene.sceneId, sceneSha256: spatialValueSha256(scene), durationUs: scene.durationUs,
+    entities: snapshot.entities.map(({ entity, worldMatrix }) => {
+      const origin = entity.origin
+      const declared = origin.kind === "generated"
+        ? scene.generators.find(generator => generator.generatorId === origin.generatorId)!.editableKeys.find(item => item.key === origin.key)?.properties ?? []
+        : (["color", "opacity", "transform"] as const).filter(property => spatialPropertySupported(entity, property))
+      const animatedProperties = scene.animations.filter(channel => channel.targetId === entity.entityId).map(channel => channel.property)
+      const editableControls = declared.filter(property => !animatedProperties.some(animated => animated === property || (property === "transform" && ["position", "rotation", "scale"].includes(animated))))
+      const local = localBounds(entity)
+      const bounds: SpatialInspectedBounds = "status" in local ? local : { status: "authored-enclosure", coordinateDomain: entity.placement, atTimeUs: 0, bounds: transformBounds(worldMatrix, local) }
+      const assetIds = entity.kind === "mesh" && entity.geometry.kind === "asset" ? [entity.geometry.assetId] : entity.kind === "text" ? [entity.fontAssetId] : "assetId" in entity ? [entity.assetId] : []
+      return { entityId: entity.entityId, name: entity.name, kind: entity.kind, origin, parentId: entity.parentId, placement: entity.placement, editableControls, animatedProperties, assetIds, bounds }
+    }),
+    cameras: scene.cameras, assets: scene.assets.map(manifest => ({ assetId: manifest.assetId, manifestSha256: digests[manifest.assetId]!, manifest })), generators: scene.generators,
+  })
+}

package/src/spatial-scene/math.ts

@@ -0,0 +1,280 @@
+import type { SpatialCamera } from "./contracts.js"
+
+/**
+ * Portable affine and calibrated-camera math.
+ * Right-handed meters, Y-up; cameras face local -Z. Column vectors, column-major
+ * matrices, quaternion [x,y,z,w]. Pixel origin is the top-left image boundary;
+ * pixel (i,j)'s center is [i + 0.5, j + 0.5]. No distortion or implicit resize.
+ */
+export type Vec2 = readonly [number, number];
+export type Vec3 = readonly [number, number, number];
+export type Quaternion = readonly [number, number, number, number];
+export type Mat4 = readonly [
+  number, number, number, number,
+  number, number, number, number,
+  number, number, number, number,
+  number, number, number, number,
+];
+export type Transform = Readonly<{ position: Vec3; rotation: Quaternion; scale: Vec3 }>;
+type View = Readonly<{ width: number; height: number; near: number; far: number }>;
+export type Perspective = View & Readonly<{ kind: "perspective"; fx: number; fy: number; cx: number; cy: number }>;
+export type Orthographic = View & Readonly<{ kind: "orthographic"; left: number; right: number; bottom: number; top: number }>;
+export type Projection = Perspective | Orthographic;
+export type Camera = Readonly<{ projection: Projection; cameraToWorld: Mat4 }>;
+export type ProjectedPoint = Readonly<{ pixel: Vec2; depthMeters: number; insideImage: boolean; insideClip: boolean }>;
+export type Ray = Readonly<{ origin: Vec3; direction: Vec3; nearDistanceMeters: number; farDistanceMeters: number }>;
+export type Bounds = Readonly<{ min: Vec3; max: Vec3 }>;
+
+// Explicit numerical guardrails for intermediate affine calculations.
+export const MAX_ABS_COMPONENT = 1e12;
+export const MAX_IMAGE_DIMENSION = 1_000_000;
+const AFFINE_TOLERANCE = 1e-12;
+const RIGID_TOLERANCE = 1e-8;
+const MIN_RELATIVE_DETERMINANT = 1e-12;
+
+function number(value: number, label: string): number {
+  if (!Number.isFinite(value) || Math.abs(value) > MAX_ABS_COMPONENT) {
+    throw new RangeError(`${label} must be finite with magnitude <= ${MAX_ABS_COMPONENT}`);
+  }
+  return value;
+}
+
+function values(value: readonly number[], length: number, label: string): void {
+  if (!Array.isArray(value) || value.length !== length) throw new RangeError(`${label} must have ${length} components`);
+  for (let index = 0; index < length; index++) number(value[index]!, `${label}[${index}]`);
+}
+
+function vec2(x: number, y: number): Vec2 {
+  return Object.freeze([number(x, "x"), number(y, "y")]);
+}
+
+function vec3(x: number, y: number, z: number): Vec3 {
+  return Object.freeze([number(x, "x"), number(y, "y"), number(z, "z")]);
+}
+
+function matrix(value: number[]): Mat4 {
+  values(value, 16, "matrix");
+  return Object.freeze(value) as unknown as Mat4;
+}
+
+function affine(value: Mat4): void {
+  values(value, 16, "transform");
+  if (Math.abs(value[3]) > AFFINE_TOLERANCE || Math.abs(value[7]) > AFFINE_TOLERANCE
+    || Math.abs(value[11]) > AFFINE_TOLERANCE || Math.abs(value[15] - 1) > AFFINE_TOLERANCE) {
+    throw new RangeError("transform must be affine with bottom row [0,0,0,1]");
+  }
+}
+
+export const IDENTITY_MATRIX: Mat4 = matrix([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+/** Normalizes nonzero input, without selecting an arbitrary quaternion sign. */
+export function normalizeQuaternion(q: Quaternion): Quaternion {
+  values(q, 4, "quaternion");
+  const length = Math.hypot(...q);
+  if (length === 0) throw new RangeError("quaternion must be nonzero");
+  return Object.freeze([q[0] / length, q[1] / length, q[2] / length, q[3] / length]);
+}
+
+/** T * R * S: scale in local axes, rotate, then translate. Zero scale is allowed. */
+export function composeTransform(transform: Transform): Mat4 {
+  values(transform.position, 3, "position");
+  values(transform.scale, 3, "scale");
+  const [x, y, z, w] = normalizeQuaternion(transform.rotation);
+  const [sx, sy, sz] = transform.scale;
+  return matrix([
+    (1 - 2 * (y*y + z*z)) * sx, 2 * (x*y + z*w) * sx, 2 * (x*z - y*w) * sx, 0,
+    2 * (x*y - z*w) * sy, (1 - 2 * (x*x + z*z)) * sy, 2 * (y*z + x*w) * sy, 0,
+    2 * (x*z + y*w) * sz, 2 * (y*z - x*w) * sz, (1 - 2 * (x*x + y*y)) * sz, 0,
+    ...transform.position, 1,
+  ]);
+}
+
+/** Parent * local; preserves affine shear introduced by a scaled parent. */
+export function multiplyTransforms(parent: Mat4, local: Mat4): Mat4 {
+  affine(parent);
+  affine(local);
+  const output = new Array<number>(16).fill(0);
+  for (let col = 0; col < 4; col++) {
+    for (let row = 0; row < 3; row++) {
+      output[col * 4 + row] = parent[row]! * local[col * 4]!
+        + parent[4 + row]! * local[col * 4 + 1]!
+        + parent[8 + row]! * local[col * 4 + 2]!
+        + (col === 3 ? parent[12 + row]! : 0);
+    }
+  }
+  output[15] = 1;
+  return matrix(output);
+}
+
+/**
+ * Inverts an affine transform including shear/reflection. Rejects singular and
+ * ill-conditioned bases: determinant after scaling by max basis entry <= 1e-12.
+ */
+export function invertTransform(transform: Mat4): Mat4 {
+  affine(transform);
+  const scale = Math.max(...[0, 1, 2, 4, 5, 6, 8, 9, 10].map((index) => Math.abs(transform[index]!)));
+  if (scale === 0) throw new RangeError("transform is singular");
+  const [a, b, c, d, e, f, g, h, i] = [0, 4, 8, 1, 5, 9, 2, 6, 10].map((index) => transform[index]! / scale) as [number, number, number, number, number, number, number, number, number];
+  const det = a*(e*i-f*h) - b*(d*i-f*g) + c*(d*h-e*g);
+  if (Math.abs(det) <= MIN_RELATIVE_DETERMINANT) throw new RangeError("transform is singular or ill-conditioned");
+  const factor = 1 / det / scale;
+  const r00 = (e*i-f*h)*factor, r01 = (c*h-b*i)*factor, r02 = (b*f-c*e)*factor;
+  const r10 = (f*g-d*i)*factor, r11 = (a*i-c*g)*factor, r12 = (c*d-a*f)*factor;
+  const r20 = (d*h-e*g)*factor, r21 = (b*g-a*h)*factor, r22 = (a*e-b*d)*factor;
+  const [tx, ty, tz] = [transform[12], transform[13], transform[14]];
+  return matrix([
+    r00, r10, r20, 0, r01, r11, r21, 0, r02, r12, r22, 0,
+    -(r00*tx+r01*ty+r02*tz), -(r10*tx+r11*ty+r12*tz), -(r20*tx+r21*ty+r22*tz), 1,
+  ]);
+}
+
+export function transformPoint(transform: Mat4, point: Vec3): Vec3 {
+  affine(transform);
+  values(point, 3, "point");
+  return apply(transform, point, true);
+}
+
+/** Transforms a displacement/direction; does not normalize it or transform normals. */
+export function transformDirection(transform: Mat4, direction: Vec3): Vec3 {
+  affine(transform);
+  values(direction, 3, "direction");
+  return apply(transform, direction, false);
+}
+
+function apply(m: Mat4, v: Vec3, translate: boolean): Vec3 {
+  return vec3(
+    m[0]*v[0] + m[4]*v[1] + m[8]*v[2] + (translate ? m[12] : 0),
+    m[1]*v[0] + m[5]*v[1] + m[9]*v[2] + (translate ? m[13] : 0),
+    m[2]*v[0] + m[6]*v[1] + m[10]*v[2] + (translate ? m[14] : 0),
+  );
+}
+
+/** Shortest-arc interpolation; q and -q describe the same rotation. t in [0,1]. */
+export function slerpQuaternion(from: Quaternion, to: Quaternion, t: number): Quaternion {
+  number(t, "t");
+  if (t < 0 || t > 1) throw new RangeError("t must be in [0,1]");
+  const a = normalizeQuaternion(from);
+  const normalizedTo = normalizeQuaternion(to);
+  let dot = a.reduce((sum, value, index) => sum + value * normalizedTo[index]!, 0);
+  const b = dot < 0 ? normalizedTo.map((value) => -value) : normalizedTo;
+  dot = Math.min(1, Math.max(0, Math.abs(dot)));
+  let left = 1 - t, right = t;
+  if (dot < 0.9995) {
+    const angle = Math.acos(dot), sine = Math.sin(angle);
+    left = Math.sin((1-t)*angle) / sine;
+    right = Math.sin(t*angle) / sine;
+  }
+  return normalizeQuaternion([
+    left*a[0] + right*b[0]!, left*a[1] + right*b[1]!,
+    left*a[2] + right*b[2]!, left*a[3] + right*b[3]!,
+  ]);
+}
+
+function projection(p: Projection): void {
+  for (const value of [p.width, p.height]) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_IMAGE_DIMENSION) throw new RangeError("image dimensions must be positive bounded integers");
+  }
+  number(p.near, "near");
+  number(p.far, "far");
+  if (p.near <= 0 || p.far <= p.near) throw new RangeError("clipping requires 0 < near < far");
+  if (p.kind === "perspective") {
+    for (const key of ["fx", "fy", "cx", "cy"] as const) number(p[key], key);
+    if (p.fx <= 0 || p.fy <= 0) throw new RangeError("focal lengths in pixels must be positive");
+  } else if (p.kind === "orthographic") {
+    for (const key of ["left", "right", "bottom", "top"] as const) number(p[key], key);
+    if (p.left >= p.right || p.bottom >= p.top) throw new RangeError("orthographic extents must be ordered");
+  } else {
+    throw new RangeError("unsupported projection");
+  }
+}
+
+/** Camera scale/shear/reflection would change the meaning of axial-meter depth. */
+function camera(camera: Camera): void {
+  projection(camera.projection);
+  const m = camera.cameraToWorld;
+  affine(m);
+  const columns: Vec3[] = [[m[0], m[1], m[2]], [m[4], m[5], m[6]], [m[8], m[9], m[10]]];
+  for (let i = 0; i < 3; i++) {
+    for (let j = i; j < 3; j++) {
+      const dot = columns[i]!.reduce((sum, value, index) => sum + value*columns[j]![index]!, 0);
+      if (Math.abs(dot - (i === j ? 1 : 0)) > RIGID_TOLERANCE) throw new RangeError("camera pose must be rigid without scale or shear");
+    }
+  }
+  const determinant = m[0]*(m[5]*m[10]-m[9]*m[6]) - m[4]*(m[1]*m[10]-m[9]*m[2]) + m[8]*(m[1]*m[6]-m[5]*m[2]);
+  if (determinant <= 0) throw new RangeError("camera pose must preserve handedness");
+}
+
+/**
+ * Returns null on/behind the camera plane. Positive-depth offscreen or clipped
+ * points remain projectable, with separate flags. Image bounds are half-open;
+ * near/far depth boundaries are inclusive. No rasterization epsilon is implied.
+ */
+export function projectPoint(view: Camera, worldPoint: Vec3): ProjectedPoint | null {
+  camera(view);
+  values(worldPoint, 3, "world point");
+  const local = apply(invertTransform(view.cameraToWorld), worldPoint, true);
+  const depthMeters = -local[2];
+  if (depthMeters <= 0) return null;
+  const p = view.projection;
+  const pixel = p.kind === "perspective"
+    ? vec2(p.fx*local[0]/depthMeters+p.cx, p.cy-p.fy*local[1]/depthMeters)
+    : vec2((local[0]-p.left)/(p.right-p.left)*p.width, (p.top-local[1])/(p.top-p.bottom)*p.height);
+  return Object.freeze({ pixel, depthMeters,
+    insideImage: pixel[0] >= 0 && pixel[0] < p.width && pixel[1] >= 0 && pixel[1] < p.height,
+    insideClip: depthMeters >= p.near && depthMeters <= p.far });
+}
+
+/** Pixel and depth may lie outside image/clip bounds; depth must remain positive. */
+export function unprojectPixel(view: Camera, pixel: Vec2, depthMeters: number): Vec3 {
+  camera(view);
+  values(pixel, 2, "pixel");
+  number(depthMeters, "depth");
+  if (depthMeters <= 0) throw new RangeError("axial depth must be positive");
+  const p = view.projection;
+  const local: Vec3 = p.kind === "perspective"
+    ? [(pixel[0]-p.cx)/p.fx*depthMeters, (p.cy-pixel[1])/p.fy*depthMeters, -depthMeters]
+    : [p.left+pixel[0]/p.width*(p.right-p.left), p.top-pixel[1]/p.height*(p.top-p.bottom), -depthMeters];
+  values(local, 3, "unprojected local point");
+  return apply(view.cameraToWorld, local, true);
+}
+
+/**
+ * A normalized world-space ray. Perspective origin is the optical center;
+ * orthographic origin is the corresponding point on the camera plane (depth 0).
+ * near/far distances are along the ray, NOT positive axial depth for perspective.
+ */
+export function pixelRay(view: Camera, pixel: Vec2): Ray {
+  camera(view);
+  values(pixel, 2, "pixel");
+  const p = view.projection;
+  const x = p.kind === "perspective" ? (pixel[0]-p.cx)/p.fx : p.left+pixel[0]/p.width*(p.right-p.left);
+  const y = p.kind === "perspective" ? (p.cy-pixel[1])/p.fy : p.top-pixel[1]/p.height*(p.top-p.bottom);
+  const length = p.kind === "perspective" ? Math.hypot(x, y, 1) : 1;
+  const origin = apply(view.cameraToWorld, p.kind === "perspective" ? [0, 0, 0] : vec3(x, y, 0), true);
+  const direction = apply(view.cameraToWorld, p.kind === "perspective" ? vec3(x/length, y/length, -1/length) : [0, 0, -1], false);
+  return Object.freeze({ origin, direction,
+    nearDistanceMeters: number(p.near*length, "near ray distance"),
+    farDistanceMeters: number(p.far*length, "far ray distance") });
+}
+
+/** World-axis-aligned enclosure of all eight corners, including shear/reflection. */
+export function transformBounds(transform: Mat4, bounds: Bounds): Bounds {
+  affine(transform);
+  values(bounds.min, 3, "bounds min");
+  values(bounds.max, 3, "bounds max");
+  if (bounds.min.some((value, index) => value > bounds.max[index]!)) throw new RangeError("bounds must have min <= max");
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+  for (let mask = 0; mask < 8; mask++) {
+    const point = apply(transform, [mask&1 ? bounds.max[0] : bounds.min[0], mask&2 ? bounds.max[1] : bounds.min[1], mask&4 ? bounds.max[2] : bounds.min[2]], true);
+    for (let index = 0; index < 3; index++) {
+      min[index] = Math.min(min[index]!, point[index]!);
+      max[index] = Math.max(max[index]!, point[index]!);
+    }
+  }
+  return Object.freeze({ min: vec3(min[0]!, min[1]!, min[2]!), max: vec3(max[0]!, max[1]!, max[2]!) });
+}
+
+/** Convert a validated authored camera pose to an explicit camera-to-world matrix. */
+export function cameraMathView(camera: SpatialCamera): Camera {
+  return Object.freeze({ projection: camera.projection, cameraToWorld: composeTransform({ ...camera.pose, scale: [1, 1, 1] }) });
+}