@hraness/slopcamera 3.2.8 → 3.3.1

package/src/spatial-scene/probe.ts

@@ -0,0 +1,137 @@
+import type { SpatialAssetManifest, SpatialSceneV1 } from "./contracts.js"
+import { parseSpatialScene } from "./identity.js"
+
+/**
+ * The gallery probe scene is a fixed checked-in template — never
+ * caller-authored — that substitutes one admitted candidate asset so a
+ * rendered still proves how it behaves in a scene: on lit geometry for a
+ * texture, as `scene.background`/`scene.environment` lighting for a skybox,
+ * or as a flat backdrop surface behind a lit subject.
+ */
+export type SlopcameraGalleryProbeMode = "texture" | "skybox" | "backdrop"
+
+const transform = (position: readonly [number, number, number]) => ({
+  position,
+  rotation: [0, 0, 0, 1] as const,
+  scale: [1, 1, 1] as const,
+})
+
+const entityBase = {
+  parentId: null,
+  placement: { kind: "world" as const },
+  origin: { kind: "authored" as const },
+  visible: true,
+}
+
+const neutral = {
+  kind: "standard" as const,
+  color: "#8b95a7",
+  opacity: 1,
+  roughness: 0.55,
+  metalness: 0.05,
+}
+
+export function galleryProbeScene(
+  mode: SlopcameraGalleryProbeMode,
+  asset: SpatialAssetManifest,
+): SpatialSceneV1 {
+  const subjectMaterial = mode === "texture"
+    ? { kind: "standard" as const, color: "#ffffff", opacity: 1, roughness: 0.75, metalness: 0, map: asset.assetId }
+    : mode === "skybox"
+      // A reflective sphere shows what the environment actually lights.
+      ? { kind: "standard" as const, color: "#cfd6e4", opacity: 1, roughness: 0.18, metalness: 0.85 }
+      : neutral
+  const entities: unknown[] = [
+    {
+      ...entityBase, entityId: "entity_subject", name: "Subject", kind: "mesh",
+      transform: transform([0, 0.15, 0]),
+      geometry: { kind: "sphere", radius: 0.9 },
+      material: subjectMaterial,
+    },
+    {
+      ...entityBase, entityId: "entity_ground", name: "Ground", kind: "mesh",
+      transform: {
+        position: [0, -0.75, 0],
+        rotation: [-0.7071067811865476, 0, 0, 0.7071067811865476],
+        scale: [1, 1, 1],
+      },
+      geometry: { kind: "plane", width: 10, height: 10 },
+      material: { ...neutral, roughness: 0.9 },
+    },
+    {
+      ...entityBase, entityId: "entity_fill", name: "Fill", kind: "light",
+      transform: transform([0, 0, 0]),
+      light: "ambient", color: "#ffffff", intensity: 1.6,
+    },
+    {
+      ...entityBase, entityId: "entity_key", name: "Key", kind: "light",
+      transform: transform([3, 4, 5]),
+      light: "directional", color: "#ffffff", intensity: 3,
+    },
+  ]
+  if (mode === "texture") {
+    const wallTiles = [
+      [-2.5, 0.2, -3],
+      [2.5, 0.2, -3],
+      [-2.5, 3, -3],
+      [2.5, 3, -3],
+    ] as const
+    for (const [index, position] of wallTiles.entries()) {
+      entities.push({
+        ...entityBase,
+        entityId: `entity_wall_${String(index + 1)}`,
+        name: `Wall tile ${String(index + 1)}`,
+        kind: "mesh",
+        transform: transform(position),
+        geometry: { kind: "plane", width: 5, height: 2.8 },
+        material: {
+          kind: "standard", color: "#ffffff", opacity: 1, roughness: 0.85,
+          metalness: 0, map: asset.assetId,
+        },
+      })
+    }
+  }
+  if (mode === "skybox") {
+    entities.push({
+      ...entityBase, entityId: "entity_environment", name: "Environment",
+      kind: "environment", transform: transform([0, 0, 0]),
+      assetId: asset.assetId, role: "both", intensity: 1,
+    })
+  }
+  if (mode === "backdrop") {
+    entities.push({
+      ...entityBase, entityId: "entity_backdrop", name: "Backdrop", kind: "image",
+      transform: transform([0, 1.6, -3]),
+      assetId: asset.assetId, width: 12, height: 6.75, fit: "cover", opacity: 1,
+    })
+  }
+  return parseSpatialScene({
+    kind: "slopcamera.spatial-scene",
+    schemaVersion: 1,
+    sceneId: "scene_gallery_probe",
+    coordinates: "right-handed-y-up-meters",
+    durationUs: 4_000_000,
+    entities,
+    cameras: [{
+      cameraId: "camera_probe",
+      name: "Probe",
+      pose: { position: [0, 0.5, 4.4], 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,
+      },
+    }],
+    assets: [asset],
+    animations: [],
+    generators: [],
+    overrides: [],
+  })
+}
+
+export function galleryProbeRenderRequest() {
+  return {
+    cameraId: "camera_probe",
+    mode: { kind: "beauty" as const },
+    selection: { kind: "frame" as const, timeUs: 0 },
+  }
+}

package/src/spatial-scene/recipe-pack.ts

@@ -0,0 +1,86 @@
+import { z } from "zod"
+
+import {
+  SpatialCameraIdSchema,
+  SpatialDigestSchema,
+  SpatialTimeUsSchema,
+} from "./contracts.js"
+import { SpatialDirectionSchema } from "./direction.js"
+import { SpatialRenderPlanSchema } from "./effects.js"
+import { SpatialGalleryAxisSchema } from "./gallery.js"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { parseSpatialValue, spatialValueSha256 } from "./identity.js"
+import { SpatialParticleSystemSchema } from "./particle.js"
+import { SpatialSimulationBakeReceiptSchema } from "./simulation.js"
+import { SpatialTemporalContactSchema } from "./temporal-audit.js"
+
+/**
+ * Declarative recipe packs for Phase 13.
+ *
+ * A recipe pack is the bounded, inert, content-addressed document a coding
+ * agent authors to parameterize the built-in `cinematic-world` workflow. It
+ * names an admitted scene by digest, one authored direction document, the
+ * gallery axes to explore, preview render requests, optional effect systems to
+ * bind, and optional sampled temporal-audit settings. A pack is data, never
+ * code: admission parses it from `unknown`, and the workflow independently
+ * revalidates every embedded render request before planning.
+ */
+export const SPATIAL_RECIPE_PACK_LIMITS = Object.freeze({
+  axes: 6,
+  previews: 4,
+  timesUs: 64,
+})
+
+export const SpatialRecipePackPreviewSchema = z.strictObject({
+  name: z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9-]*$/u),
+  /** Validated again by the host render-request schema at workflow admission. */
+  request: z.unknown(),
+})
+export type SpatialRecipePackPreview = Readonly<z.infer<typeof SpatialRecipePackPreviewSchema>>
+
+export const SpatialRecipePackEffectsSchema = z.strictObject({
+  particleSystems: z.array(SpatialParticleSystemSchema).max(64).default([]),
+  renderPlan: SpatialRenderPlanSchema,
+  simulationBakes: z.array(SpatialSimulationBakeReceiptSchema).max(64).default([]),
+})
+export type SpatialRecipePackEffects = Readonly<z.infer<typeof SpatialRecipePackEffectsSchema>>
+
+export const SpatialRecipePackAuditSchema = z.strictObject({
+  contacts: z.array(SpatialTemporalContactSchema).max(64).default([]),
+  cutBeforeUs: z.array(SpatialTimeUsSchema).max(64).default([]),
+  timesUs: z.array(SpatialTimeUsSchema).min(2).max(SPATIAL_RECIPE_PACK_LIMITS.timesUs).optional(),
+})
+export type SpatialRecipePackAudit = Readonly<z.infer<typeof SpatialRecipePackAuditSchema>>
+
+export const SpatialRecipePackSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-recipe-pack"),
+  schemaVersion: z.literal(1),
+  packId: z.string().regex(/^recipe_[a-zA-Z0-9_-]{1,64}$/u),
+  sceneSha256: SpatialDigestSchema,
+  direction: SpatialDirectionSchema,
+  cameraId: SpatialCameraIdSchema.optional(),
+  axes: z.array(SpatialGalleryAxisSchema).min(1).max(SPATIAL_RECIPE_PACK_LIMITS.axes),
+  previews: z.array(SpatialRecipePackPreviewSchema).max(SPATIAL_RECIPE_PACK_LIMITS.previews).default([]),
+  effects: SpatialRecipePackEffectsSchema.optional(),
+  temporalAudit: SpatialRecipePackAuditSchema.optional(),
+}).superRefine((pack, context) => {
+  if (new Set(pack.axes).size !== pack.axes.length) {
+    context.addIssue({ code: "custom", message: "Recipe pack gallery axes must be unique.", path: ["axes"] })
+  }
+  const names = pack.previews.map(preview => preview.name)
+  if (new Set(names).size !== names.length) {
+    context.addIssue({ code: "custom", message: "Recipe pack preview names must be unique.", path: ["previews"] })
+  }
+  if (pack.temporalAudit !== undefined && pack.cameraId === undefined) {
+    context.addIssue({ code: "custom", message: "A temporal audit requires the pack cameraId.", path: ["temporalAudit"] })
+  }
+})
+export type SpatialRecipePack = Readonly<z.infer<typeof SpatialRecipePackSchema>>
+
+export function parseSpatialRecipePack(input: unknown): SpatialRecipePack {
+  return deepFreezeJson(parseSpatialValue(SpatialRecipePackSchema, input, "spatial recipe pack"))
+}
+
+export function spatialRecipePackSha256(pack: SpatialRecipePack): string {
+  return spatialValueSha256(pack)
+}

package/src/spatial-scene/render-effects.ts

@@ -0,0 +1,240 @@
+import { z } from "zod"
+
+import { canonicalJsonSha256 } from "../code/canonical-json.js"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialDigestSchema, SpatialSceneV1Schema } from "./contracts.js"
+import { spatialRenderPlanAssetIds, SpatialRenderPlanSchema, spatialRenderPlanSha256 } from "./effects.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+import { spatialParticleAssetIds, SpatialParticleSystemSchema, spatialParticleSystemSha256 } from "./particle.js"
+import { SpatialSimulationBakeReceiptSchema } from "./simulation.js"
+
+export const SPATIAL_RENDER_EFFECTS_LIMITS = Object.freeze({
+  particleSystems: 64,
+  simulationBakes: 64,
+})
+
+const particleBindingSchema = z.strictObject({
+  system: SpatialParticleSystemSchema,
+  systemSha256: SpatialDigestSchema,
+})
+
+export const SpatialRenderEffectsDocumentSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-render-effects"),
+  particleSystems: z.array(particleBindingSchema).max(SPATIAL_RENDER_EFFECTS_LIMITS.particleSystems),
+  renderPlan: SpatialRenderPlanSchema,
+  renderPlanSha256: SpatialDigestSchema,
+  sceneSha256: SpatialDigestSchema,
+  schemaVersion: z.literal(1),
+  simulationBakes: z.array(SpatialSimulationBakeReceiptSchema).max(SPATIAL_RENDER_EFFECTS_LIMITS.simulationBakes),
+}).superRefine((document, context) => {
+  if (spatialRenderPlanSha256(document.renderPlan) !== document.renderPlanSha256) {
+    context.addIssue({ code: "custom", path: ["renderPlanSha256"], message: "Render-plan digest does not match the canonical render plan." })
+  }
+  const particleEntities = new Set<string>()
+  for (const [index, binding] of document.particleSystems.entries()) {
+    if (spatialParticleSystemSha256(binding.system) !== binding.systemSha256) {
+      context.addIssue({ code: "custom", path: ["particleSystems", index, "systemSha256"], message: "Particle-system digest does not match its canonical system." })
+    }
+    if (particleEntities.has(binding.system.entityId)) {
+      context.addIssue({ code: "custom", path: ["particleSystems", index, "system", "entityId"], message: `Duplicate particle-system entity ${binding.system.entityId}.` })
+    }
+    particleEntities.add(binding.system.entityId)
+  }
+  const caches = new Set<string>()
+  for (const [index, receipt] of document.simulationBakes.entries()) {
+    const { receiptSha256, ...body } = receipt
+    if (canonicalJsonSha256(body) !== receiptSha256) {
+      context.addIssue({ code: "custom", path: ["simulationBakes", index, "receiptSha256"], message: "Simulation bake receipt digest does not match its canonical body." })
+    }
+    if (receipt.sourceDigest !== document.sceneSha256) {
+      context.addIssue({ code: "custom", path: ["simulationBakes", index, "sourceDigest"], message: "Simulation bake receipt belongs to a different scene source." })
+    }
+    if (caches.has(receipt.cacheId)) {
+      context.addIssue({ code: "custom", path: ["simulationBakes", index, "cacheId"], message: `Duplicate simulation cache ${receipt.cacheId}.` })
+    }
+    caches.add(receipt.cacheId)
+  }
+  const particleCount = document.particleSystems.reduce((sum, binding) => sum + binding.system.maxCount, 0)
+  if (document.renderPlan.quality.particleCount !== particleCount) {
+    context.addIssue({ code: "custom", path: ["renderPlan", "quality", "particleCount"], message: "Render quality must declare the exact aggregate particle-state count." })
+  }
+  const simulationSteps = document.simulationBakes.reduce((sum, receipt) => sum + receipt.stepCount, 0)
+  if (document.renderPlan.quality.simulationSteps !== simulationSteps) {
+    context.addIssue({ code: "custom", path: ["renderPlan", "quality", "simulationSteps"], message: "Render quality must declare the exact aggregate simulation-step count." })
+  }
+})
+
+export const SpatialRenderEffectsBindingSchema = z.strictObject({
+  document: SpatialRenderEffectsDocumentSchema,
+  documentSha256: SpatialDigestSchema,
+}).superRefine((binding, context) => {
+  if (spatialRenderEffectsSha256(binding.document) !== binding.documentSha256) {
+    context.addIssue({ code: "custom", path: ["documentSha256"], message: "Render-effects digest does not match the canonical document." })
+  }
+})
+
+export type SpatialRenderEffectsDocument = Readonly<z.infer<typeof SpatialRenderEffectsDocumentSchema>>
+export type SpatialRenderEffectsBinding = Readonly<z.infer<typeof SpatialRenderEffectsBindingSchema>>
+
+export function parseSpatialRenderEffectsDocument(input: unknown): SpatialRenderEffectsDocument {
+  return deepFreezeJson(parseSpatialValue(SpatialRenderEffectsDocumentSchema, input, "render effects"))
+}
+
+export function spatialRenderEffectsAssetIds(document: SpatialRenderEffectsDocument): readonly string[] {
+  return Object.freeze([...new Set([
+    ...spatialRenderPlanAssetIds(document.renderPlan),
+    ...document.particleSystems.flatMap(binding => spatialParticleAssetIds(binding.system)),
+  ])].sort())
+}
+
+export function spatialRenderEffectsSha256(document: SpatialRenderEffectsDocument): string {
+  return spatialValueSha256(document)
+}
+
+export const SPATIAL_EFFECTS_CHECK_LIMITS = Object.freeze({
+  findings: 256,
+})
+
+export const SpatialEffectsCheckFindingSchema = z.strictObject({
+  code: z.enum(["stale-scene", "unresolved-entity", "unresolved-asset"]),
+  severity: z.enum(["error", "warning"]),
+  referenceId: z.string().min(1).max(128).optional(),
+  detail: z.string().min(1).max(240),
+})
+export type SpatialEffectsCheckFinding = Readonly<z.infer<typeof SpatialEffectsCheckFindingSchema>>
+
+export const SpatialEffectsCheckReportSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-render-effects-check"),
+  schemaVersion: z.literal(1),
+  documentSha256: SpatialDigestSchema,
+  sceneSha256: SpatialDigestSchema,
+  findings: z.array(SpatialEffectsCheckFindingSchema).max(SPATIAL_EFFECTS_CHECK_LIMITS.findings),
+  counts: z.strictObject({
+    particleSystems: z.number().int().min(0),
+    simulationBakes: z.number().int().min(0),
+    postProcessSteps: z.number().int().min(0),
+    errors: z.number().int().min(0),
+    warnings: z.number().int().min(0),
+  }),
+})
+export type SpatialEffectsCheckReport = Readonly<z.infer<typeof SpatialEffectsCheckReportSchema>>
+
+const effectsCheckInputSchema = z.strictObject({
+  effects: z.unknown(),
+  scene: z.unknown(),
+})
+
+const parseEffectsInput = (input: unknown): { document: SpatialRenderEffectsDocument; documentSha256: string } => {
+  if (input !== null && typeof input === "object" && "document" in input) {
+    const binding = parseSpatialValue(SpatialRenderEffectsBindingSchema, input, "render effects binding")
+    return { document: binding.document, documentSha256: binding.documentSha256 }
+  }
+  const document = parseSpatialRenderEffectsDocument(input)
+  return { document, documentSha256: spatialRenderEffectsSha256(document) }
+}
+
+/**
+ * Validates an effects document or {document, documentSha256} binding against
+ * one scene: stale scene digests and unresolved entity/asset references report
+ * as errors before any host work begins.
+ */
+export function checkSpatialRenderEffects(input: unknown): SpatialEffectsCheckReport {
+  const options = parseSpatialValue(effectsCheckInputSchema, input, "render effects check")
+  const scene = parseSpatialValue(SpatialSceneV1Schema, options.scene, "scene")
+  const sceneSha256 = spatialValueSha256(scene)
+  const { document, documentSha256 } = parseEffectsInput(options.effects)
+  const findings: SpatialEffectsCheckFinding[] = []
+  const finding = (code: SpatialEffectsCheckFinding["code"], detail: string, referenceId?: string): void => {
+    findings.push(deepFreezeJson(referenceId === undefined
+      ? { code, severity: "error", detail }
+      : { code, severity: "error", referenceId, detail }))
+  }
+
+  if (document.sceneSha256 !== sceneSha256) {
+    finding("stale-scene", `Effects document binds scene ${document.sceneSha256} but the checked scene digests to ${sceneSha256}.`)
+  }
+  const entityIds = new Set(scene.entities.map((entity) => entity.entityId))
+  for (const binding of document.particleSystems) {
+    if (!entityIds.has(binding.system.entityId)) {
+      finding("unresolved-entity", `Particle system on ${binding.system.entityId} does not resolve to a scene entity.`, binding.system.entityId)
+    }
+  }
+  const assetIds = new Set(scene.assets.map((asset) => asset.assetId))
+  for (const assetId of spatialRenderEffectsAssetIds(document)) {
+    if (!assetIds.has(assetId)) {
+      finding("unresolved-asset", `Effects document references asset ${assetId} absent from the scene manifest.`, assetId)
+    }
+  }
+
+  const errors = findings.filter((item) => item.severity === "error").length
+  return deepFreezeJson(SpatialEffectsCheckReportSchema.parse({
+    kind: "slopcamera.spatial-render-effects-check",
+    schemaVersion: 1,
+    documentSha256,
+    sceneSha256,
+    findings,
+    counts: {
+      particleSystems: document.particleSystems.length,
+      simulationBakes: document.simulationBakes.length,
+      postProcessSteps: document.renderPlan.postProcess?.steps.length ?? 0,
+      errors,
+      warnings: findings.length - errors,
+    },
+  }))
+}
+
+const effectsPlanInputSchema = z.strictObject({
+  scene: z.unknown(),
+  renderPlan: z.unknown(),
+  particleSystems: z.array(z.unknown()).max(SPATIAL_RENDER_EFFECTS_LIMITS.particleSystems).default([]),
+  simulationBakes: z.array(z.unknown()).max(SPATIAL_RENDER_EFFECTS_LIMITS.simulationBakes).default([]),
+})
+
+/**
+ * Assembles a canonical {document, documentSha256} effects binding for one
+ * scene. Entity and asset closure reject before the document is formed; the
+ * scene digest binds here, never by caller assertion.
+ */
+export function planSpatialRenderEffects(input: unknown): SpatialRenderEffectsBinding {
+  const options = parseSpatialValue(effectsPlanInputSchema, input, "render effects plan")
+  const scene = parseSpatialValue(SpatialSceneV1Schema, options.scene, "scene")
+  const sceneSha256 = spatialValueSha256(scene)
+  const renderPlan = parseSpatialValue(SpatialRenderPlanSchema, options.renderPlan, "render plan")
+  const particleSystems = options.particleSystems.map((system) =>
+    parseSpatialValue(SpatialParticleSystemSchema, system, "particle system"))
+  const simulationBakes = options.simulationBakes.map((receipt) =>
+    parseSpatialValue(SpatialSimulationBakeReceiptSchema, receipt, "simulation bake receipt"))
+
+  const entityIds = new Set(scene.entities.map((entity) => entity.entityId))
+  for (const system of particleSystems) {
+    if (!entityIds.has(system.entityId)) {
+      throw new SpatialSceneError("invalid-data", `Particle system on ${system.entityId} does not resolve to a scene entity.`, "particleSystems")
+    }
+  }
+  const assetIds = new Set(scene.assets.map((asset) => asset.assetId))
+  const referenced = [...spatialRenderPlanAssetIds(renderPlan), ...particleSystems.flatMap((system) => spatialParticleAssetIds(system))]
+  for (const assetId of new Set(referenced)) {
+    if (!assetIds.has(assetId)) {
+      throw new SpatialSceneError("invalid-data", `Effects input references asset ${assetId} absent from the scene manifest.`, "effects")
+    }
+  }
+  for (const receipt of simulationBakes) {
+    if (receipt.sourceDigest !== sceneSha256) {
+      throw new SpatialSceneError("invalid-data", `Simulation bake ${receipt.cacheId} belongs to scene ${receipt.sourceDigest}, not ${sceneSha256}.`, "simulationBakes")
+    }
+  }
+
+  const document = parseSpatialRenderEffectsDocument({
+    kind: "slopcamera.spatial-render-effects",
+    schemaVersion: 1,
+    sceneSha256,
+    renderPlan,
+    renderPlanSha256: spatialRenderPlanSha256(renderPlan),
+    particleSystems: particleSystems.map((system) => ({ system, systemSha256: spatialParticleSystemSha256(system) })),
+    simulationBakes,
+  })
+  return deepFreezeJson(SpatialRenderEffectsBindingSchema.parse({
+    document,
+    documentSha256: spatialRenderEffectsSha256(document),
+  }))
+}