feat(director): add authored camera directions and anchors

src/director/document.js

@@ -1,98 +1,21 @@
 /** Bounded, renderer-independent validation for authored scene documents. */
-export const SCENE_DOCUMENT_VERSION = 3;
-export const SCENE_DOCUMENT_LIMITS = Object.freeze({
-  bytes: 5 * 1024 * 1024,
-  scenes: 256,
-  shots: 10000,
-  collection: 10000,
-  depth: 24,
-  nodes: 200000,
-  string: 65536,
-});
+import {
+  SCENE_DOCUMENT_LIMITS,
+  fail,
+  object,
+  fields,
+  string,
+  number,
+  optional,
+  array,
+  ids,
+  uniqueId,
+  jsonTree,
+} from './documentFields.js';
+import { validateSceneCameras } from './cameraDocument.js';
+export { SCENE_DOCUMENT_LIMITS, SceneDocumentError } from './documentFields.js';
+export const SCENE_DOCUMENT_VERSION = 4;
 
-/** A project error identifies a field without echoing its supplied value. */
-export class SceneDocumentError extends Error {
-  constructor(path, reason) {
-    super(`${path}: ${reason}`);
-    this.name = 'SceneDocumentError';
-    this.path = path;
-  }
-}
-const fail = (path, reason) => {
-  throw new SceneDocumentError(path, reason);
-};
-const object = (value, path) => {
-  if (!value || typeof value !== 'object' || Array.isArray(value))
-    fail(path, 'expected an object');
-};
-function fields(value, path, allowed) {
-  object(value, path);
-  for (const key of Object.keys(value)) {
-    if (!allowed.includes(key)) fail(`${path}.${key}`, 'unsupported field');
-  }
-}
-function string(value, path, max = 256) {
-  if (typeof value !== 'string' || !value.trim() || value.length > max)
-    fail(path, `expected nonempty text, at most ${max} characters`);
-}
-function number(value, path, min, max, legacy) {
-  const numeric =
-    legacy && typeof value === 'string' && value.trim() ? Number(value) : value;
-  if (
-    typeof numeric !== 'number' ||
-    !Number.isFinite(numeric) ||
-    numeric < min ||
-    numeric > max
-  )
-    fail(path, `expected a number from ${min} to ${max}`);
-}
-function optional(value, key, path, check) {
-  if (Object.hasOwn(value, key)) check(value[key], `${path}.${key}`);
-}
-function array(value, path, max = SCENE_DOCUMENT_LIMITS.collection) {
-  if (!Array.isArray(value) || value.length > max)
-    fail(path, `expected an array of at most ${max} entries`);
-}
-function ids(value, path) {
-  array(value, path);
-  value.forEach((id, index) => string(id, `${path}[${index}]`));
-}
-function uniqueId(value, path, seen) {
-  if (!Object.hasOwn(value, 'id')) return; // Legacy omissions receive an ID once during migration.
-  string(value.id, `${path}.id`);
-  if (seen.has(value.id)) fail(`${path}.id`, 'duplicate ID');
-  seen.add(value.id);
-}
-function jsonTree(value, path, budget, depth = 0) {
-  if (
-    ++budget.nodes > SCENE_DOCUMENT_LIMITS.nodes ||
-    depth > SCENE_DOCUMENT_LIMITS.depth
-  )
-    fail(path, 'project complexity limit exceeded');
-  if (value === null || typeof value === 'boolean') return;
-  if (typeof value === 'string') {
-    if (value.length > SCENE_DOCUMENT_LIMITS.string)
-      fail(path, 'text is too long');
-    return;
-  }
-  if (typeof value === 'number' && Number.isFinite(value)) return;
-  if (!value || typeof value !== 'object') fail(path, 'expected a JSON value');
-  if (
-    Object.getPrototypeOf(value) !== Object.prototype &&
-    !Array.isArray(value) &&
-    Object.getPrototypeOf(value) !== null
-  )
-    fail(path, 'expected a JSON object');
-  const entries = Object.entries(value);
-  if (entries.length > SCENE_DOCUMENT_LIMITS.collection)
-    fail(path, 'too many entries');
-  for (const [key, child] of entries) {
-    if (['__proto__', 'constructor', 'prototype'].includes(key))
-      fail(path, 'unsafe object key');
-    if (key.length > 256) fail(path, 'field name is too long');
-    jsonTree(child, `${path}.${key}`, budget, depth + 1);
-  }
-}
 function visual(value, path, legacy) {
   fields(value, path, [
     'style',
@@ -141,8 +64,8 @@ export function validateSceneDocument(project) {
     'installedBuiltInSceneIds',
     'scenes',
   ]);
-  const version = project.version ?? 1;
-  if (![1, 2, 3].includes(version))
+  const version = Object.hasOwn(project, 'version') ? project.version : 1;
+  if (![1, 2, 3, 4].includes(version))
     fail('$.version', 'unsupported scene project version');
   const legacy = version < 3;
   for (const key of ['createdAt', 'updatedAt'])
@@ -159,6 +82,7 @@ export function validateSceneDocument(project) {
       'releaseLayerIds',
       'appliedShotPacks',
       'shots',
+      ...(version >= 4 ? ['anchors'] : []),
     ]);
     uniqueId(scene, path, sceneIds);
     optional(scene, 'title', path, (v, p) => string(v, p, 4096));
@@ -198,6 +122,7 @@ export function validateSceneDocument(project) {
         'layers',
         'sourcePackId',
         'sourcePackVersion',
+        ...(version >= 4 ? ['move'] : []),
       ]);
       uniqueId(shot, at, shotIds);
       optional(shot, 'title', at, (v, p) => string(v, p, 4096));
@@ -209,21 +134,6 @@ export function validateSceneDocument(project) {
         number(v, p, 0, 86400, legacy),
       );
       optional(shot, 'holdSec', at, (v, p) => number(v, p, 0, 86400, legacy));
-      optional(shot, 'camera', at, (camera, field) => {
-        const bounds = {
-          lat: [-90, 90],
-          lon: [-180, 180],
-          alt: [-12000, 1e9],
-          heading: [-360, 360],
-          pitch: [-90, 90],
-          roll: [-360, 360],
-        };
-        fields(camera, field, Object.keys(bounds));
-        for (const [key, range] of Object.entries(bounds))
-          optional(camera, key, field, (v, p) =>
-            number(v, p, ...range, legacy),
-          );
-      });
       optional(shot, 'visual', at, (v, p) => visual(v, p, legacy));
       optional(shot, 'layers', at, (layers, field) => {
         object(layers, field);
@@ -238,6 +148,7 @@ export function validateSceneDocument(project) {
         }
       });
     });
+    validateSceneCameras(scene, path, version);
   });
   return project;
 }