@deepblend/dsh-blender-contracts 0.3.8 → 0.4.0

package/lib/scene-patch.js

@@ -155,11 +155,12 @@ export function validateScenePatch(patch) {
           message: `camera.update must supply at least one field to change: ${CAMERA_UPDATE_FIELDS.join(', ')}`,
         })
       }
-      if (operation.targetEntityId !== undefined && operation.targetPoint !== undefined) {
+      if ((operation.targetEntityId !== undefined && operation.targetPoint !== undefined)
+        || (operation.clearTarget === true && (operation.targetEntityId !== undefined || operation.targetPoint !== undefined))) {
         errors.push({
           code: 'PATCH_CAMERA_TARGET_AMBIGUOUS',
           path: at,
-          message: 'camera.update must set either targetEntityId or targetPoint, not both',
+          message: 'camera.update must choose one of targetEntityId, targetPoint or clearTarget',
         })
       }
     }
@@ -191,7 +192,7 @@ export function validateScenePatch(patch) {
  * not a crash — it is a rejection that names the wrong problem.
  */
 export const CAMERA_UPDATE_FIELDS = Object.freeze([
-  'lens', 'sensorWidth', 'clipping', 'transform', 'targetEntityId', 'targetPoint', 'fStop', 'role',
+  'lens', 'sensorWidth', 'clipping', 'transform', 'targetEntityId', 'targetPoint', 'clearTarget', 'fStop', 'role',
 ])
 
 /** Build an anchored error for a failed operation. */
@@ -719,7 +720,7 @@ export function applyPatchToSpec(spec, patch) {
           fail('PATCH_REFERENCE_MISSING', `camera "${operation.cameraId}" targets entity "${operation.targetEntityId}", which does not exist`)
         }
         const camera = next.cameras[at]
-        const { op: _op, cameraId: _cameraId, transform, ...scalars } = operation
+        const { op: _op, cameraId: _cameraId, clearTarget, transform, ...scalars } = operation
         /** @type {Record<string, unknown>} */
         const patchFields = {}
         for (const [key, value] of Object.entries(scalars)) {
@@ -745,7 +746,8 @@ export function applyPatchToSpec(spec, patch) {
         const clearedAim = operation.targetEntityId !== undefined
           ? 'targetPoint'
           : operation.targetPoint !== undefined ? 'targetEntityId' : null
-        const mergedAim = clearedAim === null ? camera : withoutKey(camera, clearedAim)
+        const mergedAim = clearTarget === true ? withoutKey(withoutKey(camera, 'targetEntityId'), 'targetPoint')
+          : clearedAim === null ? camera : withoutKey(camera, clearedAim)
         next.cameras = [...next.cameras]
         next.cameras[at] = { ...mergedAim, ...patchFields }
         applied.push({
@@ -755,7 +757,8 @@ export function applyPatchToSpec(spec, patch) {
             (clearedAim === null ? '' : `, cleared ${clearedAim}`),
           changedPaths: [
             ...Object.keys(patchFields).map(key => `cameras.${camera.id}.${key}`),
-            ...clearedAim === null ? [] : [`cameras.${camera.id}.${clearedAim}`],
+            ...clearTarget === true ? ['targetEntityId', 'targetPoint'].filter(key => camera[key] !== undefined).map(key => `cameras.${camera.id}.${key}`)
+              : clearedAim === null ? [] : [`cameras.${camera.id}.${clearedAim}`],
           ],
         })
         break

package/lib/schema-types.d.ts

@@ -42,7 +42,7 @@ export namespace SceneSpecSchema {
 }
 export type SceneSpec = SceneSpecSchema.Document;
 
-/** Source SHA-256: e71dceb0a4aa93c664dbb8d894a1ffb156f4db13bc34ae4f0fdb2b10db386c06 */
+/** Source SHA-256: bb1e7ee67ba552fff1a14e9eb87fae015ccd40d3c13cd21982e8a2b1674a019e */
 export namespace ScenePatchSchema {
   export type Id = string;
   export type License = { "source"?: string; "commercialUse"?: boolean; "attribution"?: string; };
@@ -60,7 +60,7 @@ export namespace ScenePatchSchema {
   export type Camera = { "id": ScenePatchSchema.Id; "role"?: "active-camera" | "three-quarter" | "top" | "detail"; "lens"?: ScenePatchSchema.PositiveNumber; "sensorWidth"?: ScenePatchSchema.PositiveNumber; "clipping"?: [ScenePatchSchema.PositiveNumber, ScenePatchSchema.PositiveNumber]; "transform"?: { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }; "targetEntityId"?: string; "targetPoint"?: ScenePatchSchema.Vec3; "fStop"?: ScenePatchSchema.PositiveNumber; };
   export type AnimationTrack = { "id": ScenePatchSchema.Id; "targetKind"?: "entity" | "camera" | "material"; "targetEntityId": string; "property": "location.x" | "location.y" | "location.z" | "rotationEuler.x" | "rotationEuler.y" | "rotationEuler.z" | "scale.x" | "scale.y" | "scale.z" | "emissionStrength" | "roughness" | "metallic" | "ior" | "alpha" | "coatWeight" | "transmissionWeight" | "baseColor.r" | "baseColor.g" | "baseColor.b" | "emissionColor.r" | "emissionColor.g" | "emissionColor.b" | "anisotropic" | "anisotropicRotation"; "keyframes": Array<{ "frame": number; "value": number; "interpolation"?: "constant" | "linear" | "bezier" | "ease_in" | "ease_out" | "ease_in_out"; }>; };
   export type RenderProfile = { "engine"?: "eevee" | "cycles" | "workbench"; "resolution"?: [number, number]; "samples"?: number; "filmTransparent"?: boolean; "colorManagement"?: { "viewTransform"?: "Standard" | "AgX" | "Filmic" | "False Color" | "Raw"; "look"?: string; "exposure"?: number; }; "maxSamplesBudget"?: number; "raytracing"?: boolean; };
-  export type Operation = ({ "op": "entity.transform.update"; "entityId": ScenePatchSchema.Id; "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }) | ({ "op": "entity.visibility.set"; "entityId": ScenePatchSchema.Id; "visible": boolean; }) | ({ "op": "entity.tags.set"; "entityId": ScenePatchSchema.Id; "tags": Array<string>; }) | ({ "op": "entity.add"; "entity": ScenePatchSchema.Entity; }) | ({ "op": "entity.remove"; "entityId": ScenePatchSchema.Id; }) | ({ "op": "entity.material.set"; "entityId": ScenePatchSchema.Id; "materialId": string | null; }) | ({ "op": "material.texture.set"; "materialId": ScenePatchSchema.Id; "texture": (ScenePatchSchema.ProceduralTexture) | (null); }) | ({ "op": "material.add"; "material": { "id": ScenePatchSchema.Id; "shader": "principled" | "emission" | "glass"; "parameters"?: ScenePatchSchema.MaterialParameters; "texture"?: ScenePatchSchema.ProceduralTexture; "images"?: ScenePatchSchema.MaterialImages; "tangent"?: ScenePatchSchema.MaterialTangent; }; }) | ({ "op": "material.parameter.update"; "materialId": ScenePatchSchema.Id; "parameter": "baseColor" | "metallic" | "roughness" | "ior" | "alpha" | "emissionColor" | "emissionStrength" | "coatWeight" | "transmissionWeight" | "anisotropic" | "anisotropicRotation"; "value": (number) | (ScenePatchSchema.UnitColor); }) | ({ "op": "light.add"; "light": ScenePatchSchema.Light; }) | ({ "op": "light.update"; "lightId": ScenePatchSchema.Id; "transform"?: { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }; "energy"?: ScenePatchSchema.NonNegativeNumber; "color"?: ScenePatchSchema.UnitColor; "size"?: ScenePatchSchema.PositiveNumber; "spotSize"?: number; "spotBlend"?: number; "angle"?: number; }) | ({ "op": "light.remove"; "lightId": ScenePatchSchema.Id; }) | ({ "op": "camera.add"; "camera": ScenePatchSchema.Camera; }) | ({ "op": "camera.update"; "cameraId": ScenePatchSchema.Id; "role"?: "active-camera" | "three-quarter" | "top" | "detail"; "lens"?: ScenePatchSchema.PositiveNumber; "sensorWidth"?: ScenePatchSchema.PositiveNumber; "clipping"?: [ScenePatchSchema.PositiveNumber, ScenePatchSchema.PositiveNumber]; "transform"?: { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }; "targetEntityId"?: string; "targetPoint"?: ScenePatchSchema.Vec3; "fStop"?: ScenePatchSchema.PositiveNumber; }) | ({ "op": "camera.remove"; "cameraId": ScenePatchSchema.Id; }) | ({ "op": "animation.track.set"; "track": ScenePatchSchema.AnimationTrack; }) | ({ "op": "animation.track.remove"; "trackId": ScenePatchSchema.Id; }) | ({ "op": "shot.set"; "shot": { "id": ScenePatchSchema.Id; "cameraId": string; "frameRange"?: [number, number]; "description"?: string; }; }) | ({ "op": "shot.remove"; "shotId": ScenePatchSchema.Id; }) | ({ "op": "project.frameRange.set"; "frameStart": number; "frameEnd": number; "fps"?: number; }) | ({ "op": "render.profile.set"; "profileName": "preview" | "final"; "profile": ScenePatchSchema.RenderProfile; }) | ({ "op": "world.set"; "world": ScenePatchSchema.World; }) | ({ "op": "asset.add"; "asset": { "id": ScenePatchSchema.Id; "type": "glb" | "gltf" | "fbx" | "obj" | "usd" | "blend" | "png" | "jpg" | "jpeg" | "hdr" | "exr"; "path": string; "sha256"?: string; "license"?: ScenePatchSchema.License; }; }) | ({ "op": "asset.remove"; "assetId": ScenePatchSchema.Id; }) | ({ "op": "entity.generator.set"; "entityId": ScenePatchSchema.Id; "generator": ScenePatchSchema.Generator; }) | ({ "op": "entity.modifiers.set"; "entityId": ScenePatchSchema.Id; "modifiers": Array<ScenePatchSchema.ModelModifier>; }) | ({ "op": "material.images.set"; "materialId": ScenePatchSchema.Id; "images": (ScenePatchSchema.MaterialImages) | (null); }) | ({ "op": "entity.materialBindings.set"; "entityId": ScenePatchSchema.Id; "materialBindings": ScenePatchSchema.MaterialBindings; }) | ({ "op": "material.tangent.set"; "materialId": ScenePatchSchema.Id; "tangent": (ScenePatchSchema.MaterialTangent) | (null); }) | ({ "op": "project.brief.set"; "goal": string; "referenceImages": ScenePatchSchema.ReferenceImages; }) | ({ "op": "project.reviewSubject.set"; "entityId": (ScenePatchSchema.Id) | (null); });
+  export type Operation = ({ "op": "entity.transform.update"; "entityId": ScenePatchSchema.Id; "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }) | ({ "op": "entity.visibility.set"; "entityId": ScenePatchSchema.Id; "visible": boolean; }) | ({ "op": "entity.tags.set"; "entityId": ScenePatchSchema.Id; "tags": Array<string>; }) | ({ "op": "entity.add"; "entity": ScenePatchSchema.Entity; }) | ({ "op": "entity.remove"; "entityId": ScenePatchSchema.Id; }) | ({ "op": "entity.material.set"; "entityId": ScenePatchSchema.Id; "materialId": string | null; }) | ({ "op": "material.texture.set"; "materialId": ScenePatchSchema.Id; "texture": (ScenePatchSchema.ProceduralTexture) | (null); }) | ({ "op": "material.add"; "material": { "id": ScenePatchSchema.Id; "shader": "principled" | "emission" | "glass"; "parameters"?: ScenePatchSchema.MaterialParameters; "texture"?: ScenePatchSchema.ProceduralTexture; "images"?: ScenePatchSchema.MaterialImages; "tangent"?: ScenePatchSchema.MaterialTangent; }; }) | ({ "op": "material.parameter.update"; "materialId": ScenePatchSchema.Id; "parameter": "baseColor" | "metallic" | "roughness" | "ior" | "alpha" | "emissionColor" | "emissionStrength" | "coatWeight" | "transmissionWeight" | "anisotropic" | "anisotropicRotation"; "value": (number) | (ScenePatchSchema.UnitColor); }) | ({ "op": "light.add"; "light": ScenePatchSchema.Light; }) | ({ "op": "light.update"; "lightId": ScenePatchSchema.Id; "transform"?: { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }; "energy"?: ScenePatchSchema.NonNegativeNumber; "color"?: ScenePatchSchema.UnitColor; "size"?: ScenePatchSchema.PositiveNumber; "spotSize"?: number; "spotBlend"?: number; "angle"?: number; }) | ({ "op": "light.remove"; "lightId": ScenePatchSchema.Id; }) | ({ "op": "camera.add"; "camera": ScenePatchSchema.Camera; }) | ({ "op": "camera.update"; "cameraId": ScenePatchSchema.Id; "role"?: "active-camera" | "three-quarter" | "top" | "detail"; "lens"?: ScenePatchSchema.PositiveNumber; "sensorWidth"?: ScenePatchSchema.PositiveNumber; "clipping"?: [ScenePatchSchema.PositiveNumber, ScenePatchSchema.PositiveNumber]; "transform"?: { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }; "targetEntityId"?: string; "targetPoint"?: ScenePatchSchema.Vec3; "fStop"?: ScenePatchSchema.PositiveNumber; "clearTarget"?: true; }) | ({ "op": "camera.remove"; "cameraId": ScenePatchSchema.Id; }) | ({ "op": "animation.track.set"; "track": ScenePatchSchema.AnimationTrack; }) | ({ "op": "animation.track.remove"; "trackId": ScenePatchSchema.Id; }) | ({ "op": "shot.set"; "shot": { "id": ScenePatchSchema.Id; "cameraId": string; "frameRange"?: [number, number]; "description"?: string; }; }) | ({ "op": "shot.remove"; "shotId": ScenePatchSchema.Id; }) | ({ "op": "project.frameRange.set"; "frameStart": number; "frameEnd": number; "fps"?: number; }) | ({ "op": "render.profile.set"; "profileName": "preview" | "final"; "profile": ScenePatchSchema.RenderProfile; }) | ({ "op": "world.set"; "world": ScenePatchSchema.World; }) | ({ "op": "asset.add"; "asset": { "id": ScenePatchSchema.Id; "type": "glb" | "gltf" | "fbx" | "obj" | "usd" | "blend" | "png" | "jpg" | "jpeg" | "hdr" | "exr"; "path": string; "sha256"?: string; "license"?: ScenePatchSchema.License; }; }) | ({ "op": "asset.remove"; "assetId": ScenePatchSchema.Id; }) | ({ "op": "entity.generator.set"; "entityId": ScenePatchSchema.Id; "generator": ScenePatchSchema.Generator; }) | ({ "op": "entity.modifiers.set"; "entityId": ScenePatchSchema.Id; "modifiers": Array<ScenePatchSchema.ModelModifier>; }) | ({ "op": "material.images.set"; "materialId": ScenePatchSchema.Id; "images": (ScenePatchSchema.MaterialImages) | (null); }) | ({ "op": "entity.materialBindings.set"; "entityId": ScenePatchSchema.Id; "materialBindings": ScenePatchSchema.MaterialBindings; }) | ({ "op": "material.tangent.set"; "materialId": ScenePatchSchema.Id; "tangent": (ScenePatchSchema.MaterialTangent) | (null); }) | ({ "op": "project.brief.set"; "goal": string; "referenceImages": ScenePatchSchema.ReferenceImages; }) | ({ "op": "project.reviewSubject.set"; "entityId": (ScenePatchSchema.Id) | (null); });
   export type ModelModifier = ({ "type": "solidify"; "thickness": number; "offset"?: number; }) | ({ "type": "mirror"; "axis": "x" | "y" | "z"; "merge"?: boolean; }) | ({ "type": "array"; "count": number; "offset": ScenePatchSchema.Vec3; }) | ({ "type": "boolean"; "operation": "union" | "difference" | "intersect"; "targetEntityId": ScenePatchSchema.Id; }) | ({ "type": "bevel"; "width": number; "segments"?: number; "angle"?: number; "miterInner"?: "arc" | "sharp"; });
   export type ImageBinding = { "assetId": ScenePatchSchema.Id; "scale"?: ScenePatchSchema.Vec3; "offset"?: ScenePatchSchema.Vec3; "uvMap"?: string; "channel"?: "r" | "g" | "b" | "a"; "strength"?: number; };
   export type MaterialImages = { "baseColor"?: ScenePatchSchema.ImageBinding; "roughness"?: ScenePatchSchema.ImageBinding; "metallic"?: ScenePatchSchema.ImageBinding; "normal"?: ScenePatchSchema.ImageBinding; "alpha"?: ScenePatchSchema.ImageBinding; "emissionColor"?: ScenePatchSchema.ImageBinding; };

package/lib/schemas/scene-patch.schema.json

@@ -1291,6 +1291,11 @@
             },
             "fStop": {
               "$ref": "#/$defs/positiveNumber"
+            },
+            "clearTarget": {
+              "type": "boolean",
+              "const": true,
+              "description": "Explicitly return to free rotation by removing both aim targets. Cannot accompany targetEntityId or targetPoint."
             }
           }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-contracts",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "type": "module",
   "description": "DeepBlend Studio Service Definition, protocol contracts, and stable error codes.",
   "main": "lib/index.js",