@hraness/slopcamera 3.2.4

package/src/process-environment.ts

@@ -0,0 +1,17 @@
+const gatewayCredentialNames = new Set([
+  "AI_GATEWAY_API_KEY",
+  "VERCEL_OIDC_TOKEN",
+])
+
+/** Copy an environment for a non-Gateway child without delegating authority. */
+export function nonGatewayChildEnvironment(
+  source: Readonly<Record<string, string | undefined>> = process.env,
+): Record<string, string | undefined> {
+  const environment = { ...source }
+  for (const name of Object.keys(environment)) {
+    if (gatewayCredentialNames.has(name.toLocaleUpperCase("en-US"))) {
+      delete environment[name]
+    }
+  }
+  return environment
+}

package/src/render.ts

@@ -0,0 +1,437 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- packed source types must include Bun asset modules
+/// <reference path="./assets.d.ts" />
+
+import { readFile } from "node:fs/promises"
+import { extname, isAbsolute } from "node:path"
+import { fileURLToPath } from "node:url"
+import { Resvg } from "@resvg/resvg-js"
+import nebulaSansBoldOtfAsset from "./assets/fonts/nebula-sans/NebulaSans-Bold.otf" with { type: "file" }
+import nebulaSansBoldAsset from "./assets/fonts/nebula-sans/NebulaSans-Bold.woff2" with { type: "file" }
+import nebulaSansBookOtfAsset from "./assets/fonts/nebula-sans/NebulaSans-Book.otf" with { type: "file" }
+import nebulaSansBookAsset from "./assets/fonts/nebula-sans/NebulaSans-Book.woff2" with { type: "file" }
+import { sanitizeIcon } from "./icons.js"
+import { layoutBoxContent, wrapDiagramText } from "./label-layout.js"
+import { resolveTheme } from "./theme.js"
+import type {
+  Anchor,
+  BoxShape,
+  ColorMode,
+  DiagramConfig,
+  DiagramEdge,
+  DiagramShape,
+  DiagramSpec,
+  FontConfig,
+  IconDefinition,
+  RenderedDiagram,
+  TextShape,
+  ThemeColors,
+} from "./types.js"
+
+interface FontFamilies {
+  readonly default: string
+  readonly mono: string
+}
+
+const bundledAssetPath = (asset: string): string =>
+  isAbsolute(asset) ? asset : fileURLToPath(new URL(asset, import.meta.url))
+
+const defaultFont: FontConfig = Object.freeze({
+  family: "Nebula Sans",
+  files: Object.freeze([
+    Object.freeze({
+      embed: true,
+      path: bundledAssetPath(nebulaSansBookAsset),
+      style: "normal" as const,
+      weight: 400,
+    }),
+    Object.freeze({
+      embed: true,
+      path: bundledAssetPath(nebulaSansBoldAsset),
+      style: "normal" as const,
+      weight: 700,
+    }),
+    Object.freeze({
+      embed: false,
+      path: bundledAssetPath(nebulaSansBookOtfAsset),
+      style: "normal" as const,
+      weight: 400,
+    }),
+    Object.freeze({
+      embed: false,
+      path: bundledAssetPath(nebulaSansBoldOtfAsset),
+      style: "normal" as const,
+      weight: 700,
+    }),
+  ]),
+})
+
+const escapeXml = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;")
+
+function fontMime(filePath: string): string {
+  switch (extname(filePath).toLowerCase()) {
+    case ".otf":
+      return "font/otf"
+    case ".woff":
+      return "font/woff"
+    case ".woff2":
+      return "font/woff2"
+    default:
+      return "font/ttf"
+  }
+}
+
+async function fontCss(font: FontConfig): Promise<string> {
+  if (font.files === undefined) return ""
+  const faces = await Promise.all(
+    font.files
+      .filter((file) => file.embed === true)
+      .map(async (file) => {
+        const encoded = (await readFile(file.path)).toString("base64")
+        return `@font-face{font-family:"${escapeXml(font.family)}";src:url(data:${fontMime(file.path)};base64,${encoded});font-weight:${file.weight ?? 400};font-style:${file.style ?? "normal"};}`
+      }),
+  )
+  return faces.join("")
+}
+
+function textSvg(options: {
+  readonly text: string
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly fontSize: number
+  readonly weight: number
+  readonly align: "start" | "middle" | "end"
+  readonly color: string
+  readonly opacity: number
+  readonly family: string
+  readonly lineHeight?: number
+  readonly lines?: readonly string[]
+  readonly centerLineBoxes?: boolean
+}): string {
+  const lines = options.lines ?? wrapDiagramText(options.text, options.width, options.fontSize)
+  const lineHeight = options.lineHeight ?? options.fontSize * 1.25
+  const anchor = options.align
+  const x =
+    anchor === "middle"
+      ? options.x + options.width / 2
+      : anchor === "end"
+        ? options.x + options.width
+        : options.x
+  const dominantBaseline = options.centerLineBoxes ? "central" : "hanging"
+  return `<text x="${x}" y="${options.y}" text-anchor="${anchor}" dominant-baseline="${dominantBaseline}" fill="${options.color}" opacity="${options.opacity}" font-family="${escapeXml(options.family)}" font-size="${options.fontSize}" font-weight="${options.weight}">${lines
+    .map((line, index) =>
+      options.centerLineBoxes
+        ? `<tspan x="${x}" y="${options.y + (index + 0.5) * lineHeight}">${escapeXml(line)}</tspan>`
+        : `<tspan x="${x}" dy="${index === 0 ? 0 : lineHeight}">${escapeXml(line)}</tspan>`,
+    )
+    .join("")}</text>`
+}
+
+function iconSvg(options: {
+  readonly icon: IconDefinition
+  readonly x: number
+  readonly y: number
+  readonly size: number
+  readonly color: string
+  readonly opacity: number
+}): string {
+  const icon = sanitizeIcon(options.icon)
+  const parts = icon.viewBox.trim().split(/\s+/).map(Number)
+  const width = (parts[2] ?? 24) - (parts[0] ?? 0)
+  const height = (parts[3] ?? 24) - (parts[1] ?? 0)
+  const scale = options.size / Math.max(width, height)
+  return `<g color="${options.color}" opacity="${options.opacity}" transform="translate(${options.x} ${options.y}) scale(${scale}) translate(${-Number(parts[0] ?? 0)} ${-Number(parts[1] ?? 0)})">${icon.body}</g>`
+}
+
+function boxSvg(
+  shape: BoxShape,
+  theme: ThemeColors,
+  families: FontFamilies,
+  icons: Readonly<Record<string, IconDefinition>>,
+): string {
+  const tone = theme.tones[shape.tone ?? "neutral"]
+  const strokeWidth = shape.strokeWidth ?? 2
+  const opacity = shape.opacity ?? 1
+  const radius = shape.type === "ellipse" ? 0 : Math.min(shape.radius ?? 22, shape.height / 2)
+  const geometry =
+    shape.type === "ellipse"
+      ? `<ellipse cx="${shape.x + shape.width / 2}" cy="${shape.y + shape.height / 2}" rx="${shape.width / 2}" ry="${shape.height / 2}" fill="${shape.fill === false ? "none" : tone.fill}" stroke="${tone.stroke}" stroke-width="${strokeWidth}"/>`
+      : `<rect x="${shape.x}" y="${shape.y}" width="${shape.width}" height="${shape.height}" rx="${radius}" fill="${shape.fill === false ? "none" : tone.fill}" stroke="${tone.stroke}" stroke-width="${strokeWidth}"/>`
+  const icon = shape.icon === undefined ? undefined : icons[shape.icon]
+  if (shape.icon !== undefined && icon === undefined) {
+    throw new Error(`Unknown icon "${shape.icon}" on shape ${shape.id}`)
+  }
+  const iconSize = Math.min(shape.iconSize ?? 52, shape.height * 0.45, shape.width * 0.32)
+  const content = layoutBoxContent(shape, icon === undefined ? undefined : iconSize)
+  const iconMarkup =
+    icon === undefined || content.icon === undefined
+      ? ""
+      : iconSvg({
+          icon,
+          x: content.icon.x,
+          y: content.icon.y,
+          size: content.icon.size,
+          color: tone.text,
+          opacity: 1,
+        })
+  const labelMarkup = content.rows
+    .map((row) =>
+      textSvg({
+          text: row.text,
+          x: shape.x + 16,
+          y: row.y,
+          width: shape.width - 32,
+          fontSize: row.fontSize,
+          weight: row.weight,
+          align: "middle",
+          color: tone.text,
+          opacity: 1,
+          family: families[row.fontFamily],
+          lineHeight: row.lineHeight,
+          lines: row.lines,
+          centerLineBoxes: true,
+        }),
+    )
+    .join("")
+  return `<g data-shape-id="${escapeXml(shape.id)}" opacity="${opacity}">${geometry}${iconMarkup}${labelMarkup}</g>`
+}
+
+function pointForAnchor(
+  shape: BoxShape,
+  anchor: Anchor | undefined,
+  toward: { readonly x: number; readonly y: number },
+  position: number | undefined,
+): { readonly x: number; readonly y: number; readonly normalized: { readonly x: number; readonly y: number } } {
+  const center = { x: shape.x + shape.width / 2, y: shape.y + shape.height / 2 }
+  let resolved = anchor ?? "auto"
+  if (resolved === "auto") {
+    const dx = toward.x - center.x
+    const dy = toward.y - center.y
+    resolved =
+      Math.abs(dx / shape.width) >= Math.abs(dy / shape.height)
+        ? dx >= 0
+          ? "right"
+          : "left"
+        : dy >= 0
+          ? "bottom"
+          : "top"
+  }
+  const resolvedPosition = position ?? 0.5
+  if (shape.type === "ellipse") {
+    const projected = (resolvedPosition - 0.5) * 2
+    const radial = Math.sqrt(Math.max(0, 1 - projected * projected)) / 2
+    const normalized =
+      resolved === "top"
+        ? { x: resolvedPosition, y: 0.5 - radial }
+        : resolved === "bottom"
+          ? { x: resolvedPosition, y: 0.5 + radial }
+          : resolved === "left"
+            ? { x: 0.5 - radial, y: resolvedPosition }
+            : { x: 0.5 + radial, y: resolvedPosition }
+    return {
+      x: shape.x + shape.width * normalized.x,
+      y: shape.y + shape.height * normalized.y,
+      normalized,
+    }
+  }
+  switch (resolved) {
+    case "top":
+      return {
+        x: shape.x + shape.width * resolvedPosition,
+        y: shape.y,
+        normalized: { x: resolvedPosition, y: 0 },
+      }
+    case "right":
+      return {
+        x: shape.x + shape.width,
+        y: shape.y + shape.height * resolvedPosition,
+        normalized: { x: 1, y: resolvedPosition },
+      }
+    case "bottom":
+      return {
+        x: shape.x + shape.width * resolvedPosition,
+        y: shape.y + shape.height,
+        normalized: { x: resolvedPosition, y: 1 },
+      }
+    case "left":
+      return {
+        x: shape.x,
+        y: shape.y + shape.height * resolvedPosition,
+        normalized: { x: 0, y: resolvedPosition },
+      }
+  }
+}
+
+export interface ResolvedEdge {
+  readonly edge: DiagramEdge
+  readonly from: BoxShape
+  readonly to: BoxShape
+  readonly start: ReturnType<typeof pointForAnchor>
+  readonly end: ReturnType<typeof pointForAnchor>
+  readonly control: { readonly x: number; readonly y: number }
+}
+
+export function resolveEdge(spec: DiagramSpec, edge: DiagramEdge): ResolvedEdge {
+  const boxes = new Map(
+    spec.shapes
+      .filter((shape): shape is BoxShape => shape.type === "rect" || shape.type === "ellipse")
+      .map((shape) => [shape.id, shape]),
+  )
+  const from = boxes.get(edge.from)
+  const to = boxes.get(edge.to)
+  if (from === undefined || to === undefined) {
+    throw new Error(`Edge ${edge.id} references a missing box`)
+  }
+  const fromCenter = { x: from.x + from.width / 2, y: from.y + from.height / 2 }
+  const toCenter = { x: to.x + to.width / 2, y: to.y + to.height / 2 }
+  const start = pointForAnchor(from, edge.start, toCenter, edge.startPosition)
+  const end = pointForAnchor(to, edge.end, fromCenter, edge.endPosition)
+  const dx = end.x - start.x
+  const dy = end.y - start.y
+  const length = Math.hypot(dx, dy) || 1
+  const bend = edge.bend ?? 0
+  return {
+    edge,
+    from,
+    to,
+    start,
+    end,
+    control: {
+      x: (start.x + end.x) / 2 + (-dy / length) * bend,
+      y: (start.y + end.y) / 2 + (dx / length) * bend,
+    },
+  }
+}
+
+export function resolveEdgeLabel(resolved: ResolvedEdge): {
+  readonly x: number
+  readonly y: number
+} {
+  const { edge, start, end, control } = resolved
+  const t = edge.labelPosition ?? 0.5
+  const oneMinusT = 1 - t
+  const point = {
+    x: oneMinusT * oneMinusT * start.x + 2 * oneMinusT * t * control.x + t * t * end.x,
+    y: oneMinusT * oneMinusT * start.y + 2 * oneMinusT * t * control.y + t * t * end.y,
+  }
+  const tangent = {
+    x: 2 * oneMinusT * (control.x - start.x) + 2 * t * (end.x - control.x),
+    y: 2 * oneMinusT * (control.y - start.y) + 2 * t * (end.y - control.y),
+  }
+  const length = Math.hypot(tangent.x, tangent.y) || 1
+  const offset = edge.labelOffset ?? -14
+  return {
+    x: point.x + (-tangent.y / length) * offset,
+    y: point.y + (tangent.x / length) * offset,
+  }
+}
+
+function edgeSvg(resolved: ResolvedEdge, theme: ThemeColors, families: FontFamilies): string {
+  const { edge, start, end, control } = resolved
+  const toneName = edge.tone ?? "neutral"
+  const tone = theme.tones[toneName]
+  const marker =
+    edge.arrowhead === "none"
+      ? ""
+      : edge.arrowhead === "triangle"
+        ? `url(#arrow-triangle-${toneName})`
+        : `url(#arrow-open-${toneName})`
+  const path = `M ${start.x} ${start.y} Q ${control.x} ${control.y} ${end.x} ${end.y}`
+  const labelPoint = resolveEdgeLabel(resolved)
+  const label =
+    edge.label === undefined
+      ? ""
+      : `<text x="${labelPoint.x}" y="${labelPoint.y}" text-anchor="middle" dominant-baseline="central" fill="${tone.text}" stroke="${theme.background}" stroke-width="6" paint-order="stroke" font-family="${escapeXml(families[edge.labelFontFamily ?? "default"])}" font-size="${edge.labelFontSize ?? 18}" font-weight="${edge.labelWeight ?? 600}">${escapeXml(edge.label)}</text>`
+  return `<g data-edge-id="${escapeXml(edge.id)}"><path d="${path}" fill="none" stroke="${tone.stroke}" stroke-width="3" stroke-linecap="round" marker-end="${marker}"/>${label}</g>`
+}
+
+function shapeSvg(
+  shape: DiagramShape,
+  theme: ThemeColors,
+  families: FontFamilies,
+  icons: Readonly<Record<string, IconDefinition>>,
+): string {
+  if (shape.type === "rect" || shape.type === "ellipse") {
+    return boxSvg(shape, theme, families, icons)
+  }
+  if (shape.type === "line") {
+    return `<line data-shape-id="${escapeXml(shape.id)}" x1="${shape.x}" y1="${shape.y}" x2="${shape.x2}" y2="${shape.y2}" stroke="${theme.tones[shape.tone ?? "neutral"].stroke}" stroke-width="${shape.strokeWidth ?? 3}" stroke-linecap="round" opacity="${shape.opacity ?? 1}"/>`
+  }
+  const text = shape as TextShape
+  return textSvg({
+    text: text.text,
+    x: text.x,
+    y: text.y,
+    width: text.width ?? Math.max(text.text.length * (text.fontSize ?? 24) * 0.58, 12),
+    fontSize: text.fontSize ?? 24,
+    weight: text.weight ?? 500,
+    align: text.align ?? "start",
+    color: theme.tones[text.tone ?? "neutral"].text,
+    opacity: text.opacity ?? 1,
+    family: families[text.fontFamily ?? "default"],
+  })
+}
+
+export async function renderSvg(
+  spec: DiagramSpec,
+  mode: ColorMode,
+  config: DiagramConfig,
+): Promise<RenderedDiagram> {
+  const theme = resolveTheme(mode, config)
+  const font = config.font ?? defaultFont
+  const families: FontFamilies = {
+    default: font.family,
+    mono:
+      font.monoFamily ??
+      "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, monospace",
+  }
+  const icons = config.icons ?? {}
+  const embeddedFonts = await fontCss(font)
+  const markerDefinitions = Object.entries(theme.tones)
+    .map(
+      ([toneName, tone]) =>
+        `<marker id="arrow-open-${toneName}" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto" markerUnits="strokeWidth"><path d="M2 2 10 6 2 10" fill="none" stroke="${tone.stroke}" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></marker><marker id="arrow-triangle-${toneName}" markerWidth="11" markerHeight="11" refX="9" refY="5.5" orient="auto" markerUnits="strokeWidth"><path d="M1 1 10 5.5 1 10z" fill="${tone.stroke}"/></marker>`,
+    )
+    .join("")
+  const edgeMarkup = (spec.edges ?? [])
+    .map((edge) => edgeSvg(resolveEdge(spec, edge), theme, families))
+    .join("")
+  const shapeMarkup = spec.shapes
+    .map((shape) => shapeSvg(shape, theme, families, icons))
+    .join("")
+  const svg = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${spec.canvas.width}" height="${spec.canvas.height}" viewBox="0 0 ${spec.canvas.width} ${spec.canvas.height}" role="img" aria-labelledby="diagram-title" color-scheme="${mode}">`,
+    `<title id="diagram-title">${escapeXml(spec.name)}</title>`,
+    `<style>${embeddedFonts}text{font-kerning:normal;text-rendering:geometricPrecision}</style>`,
+    `<rect width="100%" height="100%" fill="${theme.background}"/>`,
+    `<defs>${markerDefinitions}</defs>`,
+    edgeMarkup,
+    shapeMarkup,
+    "</svg>",
+  ].join("")
+  return { mode, svg, width: spec.canvas.width, height: spec.canvas.height }
+}
+
+export function renderPng(
+  rendered: RenderedDiagram,
+  config: DiagramConfig,
+  scale = 2,
+): Uint8Array {
+  const font = config.font ?? defaultFont
+  const fontFiles = font.files?.map((file) => file.path) ?? []
+  const renderer = new Resvg(rendered.svg, {
+    fitTo: { mode: "zoom", value: scale },
+    font: {
+      loadSystemFonts: true,
+      ...(fontFiles.length === 0 ? {} : { fontFiles }),
+      defaultFontFamily: font.family,
+    },
+  })
+  return renderer.render().asPng()
+}

package/src/skill-install.ts

@@ -0,0 +1,49 @@
+import { cp, mkdir, rm } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { pathExists } from "./fs.js"
+
+export type SkillTarget = "codex" | "claude" | "agents"
+export type SkillScope = "user" | "project"
+
+export function bundledSkillPath(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../skills/slopcamera")
+}
+
+function targetRoot(target: SkillTarget, scope: SkillScope, projectDirectory: string): string {
+  const directory =
+    target === "codex" ? ".codex" : target === "claude" ? ".claude" : ".agents"
+  return scope === "user" ? join(homedir(), directory, "skills") : join(projectDirectory, directory, "skills")
+}
+
+export async function installSkill(options: {
+  readonly target: SkillTarget
+  readonly scope: SkillScope
+  readonly projectDirectory?: string
+  readonly force?: boolean
+}): Promise<string> {
+  const source = bundledSkillPath()
+  if (!(await pathExists(source))) throw new Error(`Bundled skill is missing: ${source}`)
+  const root = targetRoot(
+    options.target,
+    options.scope,
+    resolve(options.projectDirectory ?? process.cwd()),
+  )
+  const legacy = join(root, "diagram")
+  if (await pathExists(legacy)) {
+    throw new Error(
+      `Legacy diagram skill found at ${legacy}. Remove or move that directory, then rerun "slopcamera skill install --target ${options.target} --scope ${options.scope}". Slopcamera will not install both skills side by side.`,
+    )
+  }
+  const destination = join(root, "slopcamera")
+  if (await pathExists(destination)) {
+    if (!options.force) {
+      throw new Error(`Skill already exists at ${destination}; pass --force to replace it`)
+    }
+    await rm(destination, { recursive: true, force: true })
+  }
+  await mkdir(dirname(destination), { recursive: true })
+  await cp(source, destination, { recursive: true, errorOnExist: true })
+  return destination
+}

package/src/spatial-scene/authoring.ts

@@ -0,0 +1,27 @@
+import { parseSpatialScene } from "./identity.js"
+import type { SpatialSceneV1 } from "./contracts.js"
+
+/** A complete editable source with stable part names and a calibrated camera. */
+export function createSpatialSceneStarter(): SpatialSceneV1 {
+  const transform = { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] }
+  const common = { parentId: null, placement: { kind: "world" }, origin: { kind: "authored" }, visible: true }
+  return parseSpatialScene({
+    kind: "slopcamera.spatial-scene", schemaVersion: 1, sceneId: "scene_starter",
+    coordinates: "right-handed-y-up-meters", durationUs: 4_000_000,
+    entities: [
+      { ...common, entityId: "entity_product", name: "Product", kind: "mesh", transform,
+        geometry: { kind: "box", size: [1.4, 1.4, 1.4] }, material: { kind: "standard", color: "#3674ee", opacity: 1, roughness: 0.35, metalness: 0.1 } },
+      { ...common, entityId: "entity_pedestal", name: "Pedestal", kind: "mesh", transform: { ...transform, position: [0, -0.9, 0] },
+        geometry: { kind: "cylinder", radius: 1.15, height: 0.35 }, material: { kind: "standard", color: "#cbd5e1", opacity: 1, roughness: 0.7, metalness: 0 } },
+      { ...common, entityId: "entity_fill", name: "Fill", kind: "light", transform,
+        light: "ambient", color: "#ffffff", intensity: 2 },
+      { ...common, entityId: "entity_key", name: "Key", kind: "light", transform: { ...transform, position: [3, 4, 5] },
+        light: "directional", color: "#ffffff", intensity: 3 },
+    ],
+    cameras: [{ cameraId: "camera_hero", name: "Hero", pose: { position: [0, 0.3, 5], rotation: [0, 0, 0, 1] },
+      projection: { kind: "perspective", width: 960, height: 540, fx: 650, fy: 650, cx: 480, cy: 270, near: 0.1, far: 100 } }],
+    animations: [{ channelId: "channel_turn", targetId: "entity_product", property: "rotation", interpolation: "slerp",
+      keys: [{ timeUs: 0, value: [0, 0, 0, 1] }, { timeUs: 2_000_000, value: [0, 0.7071067811865475, 0, 0.7071067811865476] }, { timeUs: 4_000_000, value: [0, 1, 0, 0] }] }],
+    assets: [], generators: [], overrides: [],
+  })
+}

package/src/spatial-scene/camera-track.ts

@@ -0,0 +1,83 @@
+import { z } from "zod"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialCameraIdSchema, SpatialCameraSchema, SpatialDigestSchema, SpatialFrameRateSchema, SpatialTimeUsSchema } from "./contracts.js"
+import { evaluateSpatialScene } from "./evaluate.js"
+import { parseSpatialScene, parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+import { reduceSpatialFrameRate, spatialFrameSample } from "./time.js"
+
+/** Export in bounded shot-sized chunks; source, sampling and projection stay explicit. */
+export const SPATIAL_CAMERA_TRACK_MAX_FRAMES = 2_048
+const clockSchema = z.strictObject({
+  startUs: SpatialTimeUsSchema,
+  frameRate: SpatialFrameRateSchema,
+  frameCount: z.number().int().min(1).max(SPATIAL_CAMERA_TRACK_MAX_FRAMES),
+})
+const rationalSchema = z.strictObject({
+  numerator: z.string().regex(/^(0|[1-9][0-9]{0,19})$/u),
+  denominator: z.string().regex(/^[1-9][0-9]{0,6}$/u),
+})
+export const SpatialCameraTrackSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-camera-track"), schemaVersion: z.literal(1),
+  sceneSha256: SpatialDigestSchema, cameraId: SpatialCameraIdSchema, clock: clockSchema,
+  samples: z.array(z.strictObject({
+    frameIndex: z.number().int().min(0).max(SPATIAL_CAMERA_TRACK_MAX_FRAMES - 1),
+    timeUs: SpatialTimeUsSchema, exactTimeUs: rationalSchema, camera: SpatialCameraSchema,
+  })).min(1).max(SPATIAL_CAMERA_TRACK_MAX_FRAMES),
+})
+type DeepReadonly<T> = T extends object ? { readonly [Key in keyof T]: DeepReadonly<T[Key]> } : T
+export type SpatialCameraTrack = DeepReadonly<z.infer<typeof SpatialCameraTrackSchema>>
+const optionsSchema = clockSchema.extend({ cameraId: SpatialCameraIdSchema })
+export type SampleSpatialCameraTrackOptions = z.infer<typeof optionsSchema>
+
+function absoluteSample(frameIndex: number, clock: z.infer<typeof clockSchema>) {
+  const sample = spatialFrameSample(frameIndex, 3_600_000_000, clock.frameRate)
+  const denominator = BigInt(sample.exactTimeUs.denominator)
+  return { frameIndex, timeUs: clock.startUs + sample.timeUs, exactTimeUs: {
+    numerator: String(BigInt(clock.startUs) * denominator + BigInt(sample.exactTimeUs.numerator)),
+    denominator: String(denominator),
+  } }
+}
+
+/** Inert admission also rejects reordered frames, clock drift and mixed cameras. */
+export function parseSpatialCameraTrack(input: unknown): SpatialCameraTrack {
+  const track = parseSpatialValue(SpatialCameraTrackSchema, input, "camera track")
+  const rate = reduceSpatialFrameRate(track.clock.frameRate)
+  if (rate.numerator !== track.clock.frameRate.numerator || rate.denominator !== track.clock.frameRate.denominator
+      || track.samples.length !== track.clock.frameCount) throw new SpatialSceneError("invalid-data", "Camera track clock or coverage is not canonical.")
+  const first = track.samples[0]!.camera.projection
+  for (const [index, sample] of track.samples.entries()) {
+    const expected = absoluteSample(index, track.clock)
+    if (sample.frameIndex !== index || sample.timeUs !== expected.timeUs
+      || sample.exactTimeUs.numerator !== expected.exactTimeUs.numerator
+      || sample.exactTimeUs.denominator !== expected.exactTimeUs.denominator
+      || sample.camera.cameraId !== track.cameraId
+      || sample.camera.projection.width !== first.width || sample.camera.projection.height !== first.height) {
+      throw new SpatialSceneError("invalid-data", "Camera track must preserve exact clock, camera identity, order and image dimensions.")
+    }
+  }
+  return deepFreezeJson(track)
+}
+
+/** Pure camera exchange. No assets are decoded and no native source is executed. */
+export function sampleSpatialCameraTrack(sceneInput: unknown, optionsInput: unknown): SpatialCameraTrack {
+  const scene = parseSpatialScene(sceneInput)
+  const { cameraId, ...inputClock } = parseSpatialValue(optionsSchema, optionsInput, "camera track options")
+  const clock = { ...inputClock, frameRate: reduceSpatialFrameRate(inputClock.frameRate) }
+  const last = absoluteSample(clock.frameCount - 1, clock)
+  if (BigInt(last.exactTimeUs.numerator) >= BigInt(scene.durationUs) * BigInt(last.exactTimeUs.denominator)) {
+    throw new SpatialSceneError("invalid-data", "Camera samples exceed the half-open scene duration.")
+  }
+  const camera = scene.cameras.find(item => item.cameraId === cameraId)
+  if (!camera) throw new SpatialSceneError("not-found", `Unknown camera ${cameraId}.`)
+  // Camera channels have no entity/asset dependencies. Validate the original
+  // scene once, then evaluate only this closed subset at each absolute time.
+  const cameraScene = { ...scene, cameras: [camera], entities: [], assets: [], generators: [], overrides: [],
+    animations: scene.animations.filter(channel => channel.targetId === cameraId) }
+  return parseSpatialCameraTrack({ kind: "slopcamera.spatial-camera-track", schemaVersion: 1,
+    sceneSha256: spatialValueSha256(scene), cameraId, clock,
+    samples: Array.from({ length: clock.frameCount }, (_, frameIndex) => {
+      const sample = absoluteSample(frameIndex, clock)
+      return { ...sample, camera: evaluateSpatialScene(cameraScene, { cameraId, timeUs: sample.timeUs }).camera }
+    }),
+  })
+}