@deepblend/dsh-blender-contracts 0.4.0 → 0.5.0

package/lib/index.js

@@ -73,6 +73,7 @@ export const BlenderErrorCode = Object.freeze({
   PROTOCOL_VERSION_MISMATCH: 'BLENDER_PROTOCOL_VERSION_MISMATCH',
   /** bootstrap.py reported an action it does not implement. */
   UNSUPPORTED_ACTION: 'BLENDER_UNSUPPORTED_ACTION',
+  SCENE_FEATURE_UNSUPPORTED: 'BLENDER_SCENE_FEATURE_UNSUPPORTED',
   /** The collection of capabilities threw unexpectedly inside Blender. */
   CAPABILITY_PROBE_FAILED: 'BLENDER_CAPABILITY_PROBE_FAILED',
   /** The configured bootstrap script is missing or unreadable. */
@@ -696,6 +697,8 @@ export {
   ENVIRONMENT_ASSET_TYPES,
   validateSceneSpec,
   compileSceneSpec,
+  BOX_DIMENSIONS_FEATURE,
+  requiredSceneFeatures,
   entityBoundingRadius,
   sceneProjection,
   sceneSpecDigest,

package/lib/recipe.js

@@ -3,14 +3,15 @@ import { inflateSync } from 'node:zlib'
 import { sha256, sha256Canonical } from './canonical.js'
 import { compileSchema } from './json-schema.js'
 import { decodePng } from './png.js'
-import { validateSceneSpec, compileSceneSpec } from './scene-spec.js'
+import { validateSceneSpec, compileSceneSpec, BOX_DIMENSIONS_FEATURE, requiredSceneFeatures } from './scene-spec.js'
 import recipeSchema from './schemas/recipe.schema.json' with { type: 'json' }
 
 export const RECIPE_SCHEMA_VERSION = 'deepblend.recipe/v1'
 export const RECIPE_CAPABILITIES = Object.freeze([
-  'geometry.primitive', 'geometry.lathe', 'geometry.curve', 'geometry.handled_cup', 'geometry.handled_cup.tension', 'geometry.handled_cup.tension.extended', 'geometry.modifiers',
+  'geometry.primitive', BOX_DIMENSIONS_FEATURE, 'geometry.lathe', 'geometry.curve', 'geometry.handled_cup', 'geometry.handled_cup.tension', 'geometry.handled_cup.tension.extended', 'geometry.modifiers',
   'material.principled', 'material.glass', 'material.emission', 'material.procedural', 'material.procedural.uv', 'material.anisotropy',
   'animation.transform', 'animation.material',
+  'recipe.geometry-bindings',
 ])
 export const RECIPE_LIMITS = Object.freeze({ sceneBytes: 2 * 1024 * 1024, previewBytes: 4 * 1024 * 1024, previewPixels: 4 * 1024 * 1024 })
 const structural = compileSchema(recipeSchema, { id: 'recipe.schema.json' })
@@ -20,6 +21,12 @@ const plain = value => value !== null && typeof value === 'object' &&
 const issue = (code, path, message) => ({ code, path, message })
 const result = (errors, extra = {}) => ({ ok: errors.length === 0, errors, notices: [],
   summary: errors.length ? errors.map(error => `${error.path}: ${error.message}`).join('; ') : 'Recipe valid', ...extra })
+const bindingAxis = binding => ['x', 'y', 'z'].indexOf(binding.axis)
+const bindingTarget = (spec, binding) => binding.kind === 'camera' ? spec.cameras?.find(item => item.id === binding.cameraId) : spec.entities.find(item => item.id === binding.entityId)
+const bindingVector = (target, binding) => binding.property === 'dimensions' ? target?.generator?.dimensions
+  : binding.property === 'targetPoint' ? target?.targetPoint : target?.transform?.location
+const bindingTracks = (spec, binding) => (spec.animationTracks ?? []).filter(track => (track.targetKind ?? 'entity') === binding.kind
+  && track.targetEntityId === (binding.entityId ?? binding.cameraId) && track.property === `location.${binding.axis}`)
 
 export class RecipeError extends Error {
   constructor(code, message, details = {}) {
@@ -47,6 +54,7 @@ export function recipeCapabilitiesForScene(spec) {
     used.add(track.targetKind === 'material' ? 'animation.material' : 'animation.transform')
     if (track.targetKind === 'material' && ['anisotropic', 'anisotropicRotation'].includes(track.property)) used.add('material.anisotropy')
   }
+  for (const feature of requiredSceneFeatures(spec)) used.add(feature)
   return [...used].sort()
 }
 
@@ -82,7 +90,7 @@ export function validateRecipeManifest(manifest, options = {}) {
     declared.add(capability)
     if (!supported.has(capability)) errors.push(issue('RECIPE_INCOMPATIBLE', 'compatibility.capabilities', `Unsupported capability ${capability}`))
   }
-  const ids = new Set(), targets = new Set()
+  const ids = new Set(), targets = new Map()
   for (const parameter of manifest.parameters) {
     const path = `parameters.${parameter.id}`
     if (ids.has(parameter.id) || RESERVED.has(parameter.id)) errors.push(issue('RECIPE_PARAMETER_INVALID', path, 'Parameter IDs must be unique and must not be reserved object keys'))
@@ -91,12 +99,23 @@ export function validateRecipeManifest(manifest, options = {}) {
     const valueIssue = parameterValueIssue(parameter, parameter.default, `${path}.default`)
     if (valueIssue) errors.push(valueIssue)
     for (const binding of parameter.bindings) {
-      const target = binding.kind === 'material' ? `material:${binding.materialId}:${binding.property}` : `render-profile:${binding.profile}:exposure`
-      if (targets.has(target)) errors.push(issue('RECIPE_BINDING_INVALID', path, `Target ${target} is bound more than once`))
-      targets.add(target)
+      const target = binding.kind === 'material' ? `material:${binding.materialId}:${binding.property}`
+        : ['entity', 'camera'].includes(binding.kind) ? `${binding.kind}:${binding.entityId ?? binding.cameraId}:${binding.property}.${binding.axis}` : `render-profile:${binding.profile}:exposure`
+      const prior = targets.get(target)
+      // Camera framing may add independent width/depth/height deltas. Repeating a
+      // slot inside one parameter, or overwriting any other target, remains invalid.
+      if (prior && (binding.kind !== 'camera' || prior.has(parameter.id))) errors.push(issue('RECIPE_BINDING_INVALID', path, `Target ${target} is bound more than once`))
+      if (!prior) targets.set(target, new Set([parameter.id]))
+      else prior.add(parameter.id)
       const color = binding.kind === 'material' && binding.property === 'baseColor'
       if ((parameter.type === 'color') !== color) errors.push(issue('RECIPE_BINDING_INVALID', path, 'Parameter type does not match the allowlisted property'))
       if (parameter.type === 'number') {
+        if (['entity', 'camera'].includes(binding.kind)) {
+          if (!Number.isFinite(binding.multiplier) || binding.multiplier === 0) errors.push(issue('RECIPE_BINDING_INVALID', path, 'Entity binding multiplier must be finite and nonzero'))
+          if (!declared.has('recipe.geometry-bindings')) errors.push(issue('RECIPE_CAPABILITY_UNDECLARED', path, 'Entity bindings require recipe.geometry-bindings'))
+          if (binding.property !== 'location' && binding.offsetAnimation !== undefined) errors.push(issue('RECIPE_BINDING_INVALID', path, 'Animation offsets are only valid on location bindings'))
+          continue
+        }
         const range = binding.kind === 'material' ? [0, 1] : [-10, 10]
         if (parameter.minimum < range[0] || parameter.maximum > range[1]) errors.push(issue('RECIPE_BINDING_INVALID', path, `Binding range must stay within [${range}]`))
       }
@@ -156,7 +175,7 @@ function validatePreview(bytes) {
 }
 
 function bindingsAgainstScene(manifest, spec) {
-  const errors = []
+  const errors = [], cameraRanges = new Map()
   for (const parameter of manifest.parameters) for (const binding of parameter.bindings) {
     const path = `parameters.${parameter.id}.bindings`
     if (binding.kind === 'material') {
@@ -171,10 +190,44 @@ function bindingsAgainstScene(manifest, spec) {
         (track.property === binding.property || track.property.startsWith(`${binding.property}.`)))) {
         errors.push(issue('RECIPE_BINDING_INVALID', path, 'A parameter must not compete with animation on the same material property'))
       }
+    } else if (['entity', 'camera'].includes(binding.kind)) {
+      const entity = bindingTarget(spec, binding)
+      const vector = bindingVector(entity, binding), axis = bindingAxis(binding)
+      if (!entity || (binding.property === 'dimensions' && (!['cube', 'rounded_box'].includes(entity.generator?.shape) || entity.generator.size !== undefined))
+        || !Array.isArray(vector) || vector.length !== 3 || !Number.isFinite(vector[axis])) {
+        errors.push(issue('RECIPE_BINDING_INVALID', path, 'Structural binding requires an explicit supported dimension, position or aim point'))
+        continue
+      }
+      const ends = [parameter.minimum, parameter.maximum].map(value => vector[axis] + (value - parameter.default) * binding.multiplier)
+      if (ends.some(value => !Number.isFinite(value) || (binding.property === 'dimensions' && value <= 0))) {
+        errors.push(issue('RECIPE_BINDING_INVALID', path, 'The entire parameter range must produce finite values and positive dimensions'))
+      }
+      if (binding.kind === 'camera') {
+        const key = `${binding.cameraId}:${binding.property}.${binding.axis}`
+        const range = cameraRanges.get(key) ?? [vector[axis], vector[axis]]
+        const deltas = [parameter.minimum, parameter.maximum].map(value => (value - parameter.default) * binding.multiplier)
+        range[0] += Math.min(...deltas); range[1] += Math.max(...deltas)
+        cameraRanges.set(key, range)
+      }
+      if (binding.property === 'location') {
+        const tracks = bindingTracks(spec, binding)
+        if (tracks.length && binding.offsetAnimation !== true) errors.push(issue('RECIPE_BINDING_INVALID', path, 'An animated location requires an explicit animation offset'))
+        if (binding.offsetAnimation === true && tracks.some(track => track.keyframes.some(keyframe => [parameter.minimum, parameter.maximum]
+          .some(value => !Number.isFinite(keyframe.value + (value - parameter.default) * binding.multiplier))))) {
+          errors.push(issue('RECIPE_BINDING_INVALID', path, 'Animation offsets must remain finite throughout the parameter range'))
+        }
+      }
+      if (binding.kind === 'camera' && binding.property === 'targetPoint' && (entity.targetEntityId !== undefined
+        || spec.animationTracks?.some(track => track.targetKind === 'camera' && track.targetEntityId === entity.id && track.property.startsWith('rotationEuler.')))) {
+        errors.push(issue('RECIPE_BINDING_INVALID', path, 'A bound camera aim point must not compete with an entity target or animated rotation'))
+      }
     } else if (spec.renderProfiles?.[binding.profile]?.colorManagement?.exposure !== parameter.default) {
       errors.push(issue('RECIPE_BINDING_INVALID', path, `Profile ${binding.profile} must explicitly declare exposure equal to the parameter default`))
     }
   }
+  for (const [key, range] of cameraRanges) if (range.some(value => !Number.isFinite(value))) {
+    errors.push(issue('RECIPE_BINDING_INVALID', 'parameters', `Combined camera binding range must remain finite: ${key}`))
+  }
   return errors
 }
 
@@ -240,6 +293,14 @@ export function instantiateRecipe(bundle, values = {}, options = {}) {
       const material = spec.materials.find(item => item.id === binding.materialId)
       material.parameters[binding.property] = parameter.type === 'color'
         ? [...value, material.parameters.baseColor[3] ?? 1] : value
+    } else if (['entity', 'camera'].includes(binding.kind)) {
+      const vector = bindingVector(bindingTarget(spec, binding), binding)
+      // Preserve the input's exact default bytes and avoid cumulative edits.
+      if (value !== parameter.default) {
+        const delta = (value - parameter.default) * binding.multiplier
+        vector[bindingAxis(binding)] += delta
+        if (binding.offsetAnimation === true) for (const track of bindingTracks(spec, binding)) for (const keyframe of track.keyframes) keyframe.value += delta
+      }
     } else spec.renderProfiles[binding.profile].colorManagement.exposure = value
   }
   const validation = validateSceneSpec(spec)

package/lib/runtime-types.d.ts

@@ -21,6 +21,8 @@ export interface BlenderCapabilities {
   exportFormats: string[]; importFormats: string[]; unavailableFormats: string[];
   renderSmokeTest: BlenderRenderSmokeTest | null; cyclesSmokeTest: BlenderRenderSmokeTest | null;
   textBlockApi: boolean; frameApi: boolean; hostPlatform: string | null; warnings: RuntimeWarning[];
+  /** Compiler vocabulary extensions; absent means unsupported. */
+  sceneFeatures?: string[];
   probedAt: number; durationMs: number; commandLine: string | null;
 }
 export interface BlenderBootstrapRequest { action: string; payload?: Record<string, unknown>; jobId?: string }

package/lib/scene-spec.js

@@ -29,6 +29,14 @@ import sceneSpecSchema from './schemas/scene-spec.schema.json' with { type: 'jso
 /** The one schema version this module understands. */
 export const SCENE_SCHEMA_VERSION = 'deepblend.scene/v1'
 
+export const BOX_DIMENSIONS_FEATURE = 'geometry.primitive.dimensions'
+
+/** Features whose absence must refuse compilation rather than reinterpret the scene. */
+export function requiredSceneFeatures(spec) {
+  return spec.entities?.some(entity => entity.type === 'generator' && entity.generator?.dimensions !== undefined)
+    ? [BOX_DIMENSIONS_FEATURE] : []
+}
+
 /**
  * What a scene with no `world` block is lit by.
  *
@@ -360,6 +368,11 @@ export function validateSceneSpec(spec) {
         selectors.add(key)
       }
     }
+    if (entity.generator?.dimensions !== undefined &&
+      (!['cube', 'rounded_box'].includes(entity.generator.shape) || entity.generator.size !== undefined)) {
+      errors.push({ severity: 'error', code: 'SCENE_GENERATOR_PARAMETERS_INVALID', path: `${at}.generator`,
+        message: 'axis dimensions require cube or rounded_box and cannot be combined with scalar size' })
+    }
     if (entity.generator?.shape === 'handled_cup') {
       for (const message of handledCupIssues(entity.generator)) errors.push({ severity: 'error',
         code: 'SCENE_GENERATOR_PARAMETERS_INVALID', path: `${at}.generator`, message })
@@ -780,12 +793,12 @@ function resolveGenerator(generator) {
   const base = { shape }
   switch (shape) {
     case 'cube':
-      return { ...base, ...generator, size: generator.size ?? 2 }
+      return { ...base, ...generator, ...(generator.dimensions === undefined ? { size: generator.size ?? 2 } : {}) }
     case 'rounded_box':
       return {
         ...base,
         ...generator,
-        size: generator.size ?? 2,
+        ...(generator.dimensions === undefined ? { size: generator.size ?? 2 } : {}),
         bevel: { width: generator.bevel?.width ?? 0.08, segments: generator.bevel?.segments ?? 4 },
       }
     case 'uv_sphere':
@@ -862,8 +875,10 @@ export function entityBoundingRadius(entity) {
   const generator = entity?.generator
   if (generator !== undefined) {
     switch (generator.shape) {
-      case 'cube': radius = (generator.size / 2) * Math.sqrt(3); break
-      case 'rounded_box': radius = (generator.size / 2) * Math.sqrt(3); break
+      case 'cube':
+      case 'rounded_box':
+        radius = generator.dimensions === undefined ? (generator.size / 2) * Math.sqrt(3) : Math.hypot(...generator.dimensions) / 2
+        break
       case 'uv_sphere': radius = generator.radius; break
       case 'cylinder': radius = Math.hypot(generator.radius, generator.depth / 2); break
       case 'cone': radius = Math.hypot(generator.radius, generator.depth / 2); break

package/lib/schema-types.d.ts

@@ -1,7 +1,7 @@
 /** Generated by deepblend/tools/generate-sdk-types.mjs. Do not edit.
  * Types describe JSON shape. Numeric bounds, ID grammar and references still require validation. */
 
-/** Source SHA-256: e1d0fab58ba2263925efdee9e2489f205fde30e957b62b128c085f4706d6c11d */
+/** Source SHA-256: 2fe4251bf80fa6f10a5c8b6d877250776c4b305a172c28224821d0082252c3a6 */
 export namespace SceneSpecSchema {
   export type Id = string;
   export type World = { "color"?: SceneSpecSchema.UnitColor; "strength"?: number; "environment"?: { "assetId": SceneSpecSchema.Id; "rotation"?: number; }; };
@@ -15,7 +15,7 @@ export namespace SceneSpecSchema {
   export type ProceduralTexture = ({ "type": "noise" | "wave" | "voronoi"; "scale": number; "detail"?: number; "distortion"?: number; "stretch"?: [number, number, number]; "bump"?: number; "roughnessVariation"?: number; "colorVariation"?: number; "coordinates"?: "object"; }) | ({ "type": "noise" | "wave" | "voronoi"; "scale": number; "detail"?: number; "distortion"?: number; "stretch"?: [number, number, number]; "bump"?: number; "roughnessVariation"?: number; "colorVariation"?: number; "coordinates": "uv"; "uvMap"?: string; });
   export type Material = { "id": SceneSpecSchema.Id; "shader": "principled" | "emission" | "glass"; "parameters"?: { "baseColor"?: SceneSpecSchema.UnitColor; "metallic"?: number; "roughness"?: number; "ior"?: number; "alpha"?: number; "emissionColor"?: SceneSpecSchema.UnitColor; "emissionStrength"?: SceneSpecSchema.NonNegativeNumber; "coatWeight"?: number; "transmissionWeight"?: number; "anisotropic"?: number; "anisotropicRotation"?: number; }; "texture"?: SceneSpecSchema.ProceduralTexture; "images"?: SceneSpecSchema.MaterialImages; "tangent"?: SceneSpecSchema.MaterialTangent; };
   export type Transform = { "location"?: SceneSpecSchema.Vec3; "rotationEuler"?: SceneSpecSchema.Vec3; "scale"?: SceneSpecSchema.Vec3; };
-  export type Generator = { "shape": "cube" | "uv_sphere" | "cylinder" | "cone" | "plane" | "torus" | "rounded_box" | "lathe" | "curve" | "handled_cup"; "size"?: SceneSpecSchema.PositiveNumber; "radius"?: SceneSpecSchema.PositiveNumber; "depth"?: SceneSpecSchema.PositiveNumber; "segments"?: number; "ringCount"?: number; "majorRadius"?: SceneSpecSchema.PositiveNumber; "minorRadius"?: SceneSpecSchema.PositiveNumber; "bevel"?: { "width"?: SceneSpecSchema.PositiveNumber; "segments"?: number; }; "profile"?: Array<[number, number]>; "closedProfile"?: boolean; "capEnds"?: boolean; "path"?: Array<SceneSpecSchema.Vec3>; "pathClosed"?: boolean; "pathInterpolation"?: "poly" | "bezier"; "curveResolution"?: number; "bevelResolution"?: number; "height"?: SceneSpecSchema.PositiveNumber; "wallThickness"?: SceneSpecSchema.PositiveNumber; "baseThickness"?: SceneSpecSchema.PositiveNumber; "footRound"?: SceneSpecSchema.PositiveNumber; "handleRadius"?: SceneSpecSchema.PositiveNumber; "handleLower"?: SceneSpecSchema.PositiveNumber; "handleUpper"?: SceneSpecSchema.PositiveNumber; "rootRadius"?: SceneSpecSchema.PositiveNumber; "rootLength"?: SceneSpecSchema.PositiveNumber; "sectionSegments"?: number; "handleSegments"?: number; "rootSegments"?: number; "wallRows"?: number; "rootTension"?: number; };
+  export type Generator = { "shape": "cube" | "uv_sphere" | "cylinder" | "cone" | "plane" | "torus" | "rounded_box" | "lathe" | "curve" | "handled_cup"; "size"?: SceneSpecSchema.PositiveNumber; "radius"?: SceneSpecSchema.PositiveNumber; "depth"?: SceneSpecSchema.PositiveNumber; "segments"?: number; "ringCount"?: number; "majorRadius"?: SceneSpecSchema.PositiveNumber; "minorRadius"?: SceneSpecSchema.PositiveNumber; "bevel"?: { "width"?: SceneSpecSchema.PositiveNumber; "segments"?: number; }; "profile"?: Array<[number, number]>; "closedProfile"?: boolean; "capEnds"?: boolean; "path"?: Array<SceneSpecSchema.Vec3>; "pathClosed"?: boolean; "pathInterpolation"?: "poly" | "bezier"; "curveResolution"?: number; "bevelResolution"?: number; "height"?: SceneSpecSchema.PositiveNumber; "wallThickness"?: SceneSpecSchema.PositiveNumber; "baseThickness"?: SceneSpecSchema.PositiveNumber; "footRound"?: SceneSpecSchema.PositiveNumber; "handleRadius"?: SceneSpecSchema.PositiveNumber; "handleLower"?: SceneSpecSchema.PositiveNumber; "handleUpper"?: SceneSpecSchema.PositiveNumber; "rootRadius"?: SceneSpecSchema.PositiveNumber; "rootLength"?: SceneSpecSchema.PositiveNumber; "sectionSegments"?: number; "handleSegments"?: number; "rootSegments"?: number; "wallRows"?: number; "rootTension"?: number; "dimensions"?: [SceneSpecSchema.PositiveNumber, SceneSpecSchema.PositiveNumber, SceneSpecSchema.PositiveNumber]; };
   export type Entity = { "id": SceneSpecSchema.Id; "type": "asset-instance" | "generator" | "empty"; "assetId"?: string; "armatureId"?: string; "rigidBody"?: SceneSpecSchema.RigidBody; "cloth"?: SceneSpecSchema.Cloth; "softBody"?: SceneSpecSchema.SoftBody; "fluid"?: SceneSpecSchema.Fluid; "generator"?: SceneSpecSchema.Generator; "materialId"?: string; "transform"?: SceneSpecSchema.Transform; "tags"?: Array<string>; "locked"?: boolean; "visible"?: boolean; "modifiers"?: Array<SceneSpecSchema.ModelModifier>; "materialBindings"?: SceneSpecSchema.MaterialBindings; };
   export type Light = { "id": SceneSpecSchema.Id; "type": "area" | "point" | "spot" | "sun"; "transform"?: SceneSpecSchema.Transform; "energy"?: SceneSpecSchema.NonNegativeNumber; "color"?: SceneSpecSchema.UnitColor; "size"?: SceneSpecSchema.PositiveNumber; "spotSize"?: number; "spotBlend"?: number; "angle"?: number; };
   export type Camera = { "id": SceneSpecSchema.Id; "role"?: "active-camera" | "three-quarter" | "top" | "detail"; "lens"?: SceneSpecSchema.PositiveNumber; "sensorWidth"?: SceneSpecSchema.PositiveNumber; "clipping"?: [SceneSpecSchema.PositiveNumber, SceneSpecSchema.PositiveNumber]; "transform"?: SceneSpecSchema.Transform; "targetEntityId"?: string; "targetPoint"?: SceneSpecSchema.Vec3; "fStop"?: SceneSpecSchema.PositiveNumber; };
@@ -42,7 +42,7 @@ export namespace SceneSpecSchema {
 }
 export type SceneSpec = SceneSpecSchema.Document;
 
-/** Source SHA-256: bb1e7ee67ba552fff1a14e9eb87fae015ccd40d3c13cd21982e8a2b1674a019e */
+/** Source SHA-256: b34ca16667f6771bdcc5ec7c503fe3ded71acadf2175e5e52e9f52ea7d532230 */
 export namespace ScenePatchSchema {
   export type Id = string;
   export type License = { "source"?: string; "commercialUse"?: boolean; "attribution"?: string; };
@@ -54,7 +54,7 @@ export namespace ScenePatchSchema {
   export type TransformPatch = { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; };
   export type MaterialParameters = { "baseColor"?: ScenePatchSchema.UnitColor; "metallic"?: number; "roughness"?: number; "ior"?: number; "alpha"?: number; "emissionColor"?: ScenePatchSchema.UnitColor; "emissionStrength"?: ScenePatchSchema.NonNegativeNumber; "coatWeight"?: number; "transmissionWeight"?: number; "anisotropic"?: number; "anisotropicRotation"?: number; };
   export type ProceduralTexture = ({ "type": "noise" | "wave" | "voronoi"; "scale": number; "detail"?: number; "distortion"?: number; "stretch"?: [number, number, number]; "bump"?: number; "roughnessVariation"?: number; "colorVariation"?: number; "coordinates"?: "object"; }) | ({ "type": "noise" | "wave" | "voronoi"; "scale": number; "detail"?: number; "distortion"?: number; "stretch"?: [number, number, number]; "bump"?: number; "roughnessVariation"?: number; "colorVariation"?: number; "coordinates": "uv"; "uvMap"?: string; });
-  export type Generator = { "shape": "cube" | "uv_sphere" | "cylinder" | "cone" | "plane" | "torus" | "rounded_box" | "lathe" | "curve" | "handled_cup"; "size"?: ScenePatchSchema.PositiveNumber; "radius"?: ScenePatchSchema.PositiveNumber; "depth"?: ScenePatchSchema.PositiveNumber; "segments"?: number; "ringCount"?: number; "majorRadius"?: ScenePatchSchema.PositiveNumber; "minorRadius"?: ScenePatchSchema.PositiveNumber; "bevel"?: { "width"?: ScenePatchSchema.PositiveNumber; "segments"?: number; }; "profile"?: Array<[number, number]>; "closedProfile"?: boolean; "capEnds"?: boolean; "path"?: Array<ScenePatchSchema.Vec3>; "pathClosed"?: boolean; "pathInterpolation"?: "poly" | "bezier"; "curveResolution"?: number; "bevelResolution"?: number; "height"?: ScenePatchSchema.PositiveNumber; "wallThickness"?: ScenePatchSchema.PositiveNumber; "baseThickness"?: ScenePatchSchema.PositiveNumber; "footRound"?: ScenePatchSchema.PositiveNumber; "handleRadius"?: ScenePatchSchema.PositiveNumber; "handleLower"?: ScenePatchSchema.PositiveNumber; "handleUpper"?: ScenePatchSchema.PositiveNumber; "rootRadius"?: ScenePatchSchema.PositiveNumber; "rootLength"?: ScenePatchSchema.PositiveNumber; "sectionSegments"?: number; "handleSegments"?: number; "rootSegments"?: number; "wallRows"?: number; "rootTension"?: number; };
+  export type Generator = { "shape": "cube" | "uv_sphere" | "cylinder" | "cone" | "plane" | "torus" | "rounded_box" | "lathe" | "curve" | "handled_cup"; "size"?: ScenePatchSchema.PositiveNumber; "radius"?: ScenePatchSchema.PositiveNumber; "depth"?: ScenePatchSchema.PositiveNumber; "segments"?: number; "ringCount"?: number; "majorRadius"?: ScenePatchSchema.PositiveNumber; "minorRadius"?: ScenePatchSchema.PositiveNumber; "bevel"?: { "width"?: ScenePatchSchema.PositiveNumber; "segments"?: number; }; "profile"?: Array<[number, number]>; "closedProfile"?: boolean; "capEnds"?: boolean; "path"?: Array<ScenePatchSchema.Vec3>; "pathClosed"?: boolean; "pathInterpolation"?: "poly" | "bezier"; "curveResolution"?: number; "bevelResolution"?: number; "height"?: ScenePatchSchema.PositiveNumber; "wallThickness"?: ScenePatchSchema.PositiveNumber; "baseThickness"?: ScenePatchSchema.PositiveNumber; "footRound"?: ScenePatchSchema.PositiveNumber; "handleRadius"?: ScenePatchSchema.PositiveNumber; "handleLower"?: ScenePatchSchema.PositiveNumber; "handleUpper"?: ScenePatchSchema.PositiveNumber; "rootRadius"?: ScenePatchSchema.PositiveNumber; "rootLength"?: ScenePatchSchema.PositiveNumber; "sectionSegments"?: number; "handleSegments"?: number; "rootSegments"?: number; "wallRows"?: number; "rootTension"?: number; "dimensions"?: [ScenePatchSchema.PositiveNumber, ScenePatchSchema.PositiveNumber, ScenePatchSchema.PositiveNumber]; };
   export type Entity = { "id": ScenePatchSchema.Id; "type": "asset-instance" | "generator" | "empty"; "assetId"?: string; "generator"?: ScenePatchSchema.Generator; "materialId"?: string; "transform"?: { "location"?: ScenePatchSchema.Vec3; "rotationEuler"?: ScenePatchSchema.Vec3; "scale"?: ScenePatchSchema.Vec3; }; "tags"?: Array<string>; "locked"?: boolean; "visible"?: boolean; "modifiers"?: Array<ScenePatchSchema.ModelModifier>; "materialBindings"?: ScenePatchSchema.MaterialBindings; };
   export type Light = { "id": ScenePatchSchema.Id; "type": "area" | "point" | "spot" | "sun"; "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; };
   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; };
@@ -73,12 +73,12 @@ export namespace ScenePatchSchema {
 }
 export type ScenePatch = ScenePatchSchema.Document;
 
-/** Source SHA-256: d1f5b189bbf0e5cab018be87ce52757acfd208c24b1fa07d087947ed98e20ad5 */
+/** Source SHA-256: c166cbaef86b7bd59f85536c9f04acd645b69e9cd614a6ea9de93f7b6a698917 */
 export namespace RecipeSchema {
-  export type Binding = ({ "kind": "material"; "materialId": string; "property": "baseColor" | "roughness"; }) | ({ "kind": "render-profile"; "profile": "preview" | "final"; "property": "exposure"; });
+  export type Binding = ({ "kind": "material"; "materialId": string; "property": "baseColor" | "roughness"; }) | ({ "kind": "render-profile"; "profile": "preview" | "final"; "property": "exposure"; }) | ({ "kind": "entity"; "entityId": string; "property": "dimensions" | "location"; "axis": "x" | "y" | "z"; "multiplier": number; "offsetAnimation"?: boolean; }) | ({ "kind": "camera"; "cameraId": string; "property": "location" | "targetPoint"; "axis": "x" | "y" | "z"; "multiplier": number; });
   export type ColorParameter = { "id": string; "title": string; "description"?: string; "bindings": Array<RecipeSchema.Binding>; "type": "color"; "default": [number, number, number]; };
   export type NumberParameter = { "id": string; "title": string; "description"?: string; "bindings": Array<RecipeSchema.Binding>; "type": "number"; "default": number; "minimum": number; "maximum": number; };
-  export type Document = { "schemaVersion": "deepblend.recipe/v1"; "id": string; "version": string; "title": string; "description": string; "author": { "name": string; "url"?: string; }; "license": string; "source": { "url": string; "note"?: string; }; "compatibility": { "sceneSchemaVersion": "deepblend.scene/v1"; "capabilities": Array<"geometry.primitive" | "geometry.lathe" | "geometry.curve" | "geometry.handled_cup" | "geometry.handled_cup.tension" | "geometry.handled_cup.tension.extended" | "geometry.modifiers" | "material.principled" | "material.glass" | "material.emission" | "material.procedural" | "material.procedural.uv" | "material.anisotropy" | "animation.transform" | "animation.material">; }; "input": { "path": "scene-spec.json"; "sha256": string; }; "preview": { "path": "preview.png"; "sha256": string; "mediaType": "image/png"; "alt": string; }; "parameters": Array<(RecipeSchema.ColorParameter) | (RecipeSchema.NumberParameter)>; };
+  export type Document = { "schemaVersion": "deepblend.recipe/v1"; "id": string; "version": string; "title": string; "description": string; "author": { "name": string; "url"?: string; }; "license": string; "source": { "url": string; "note"?: string; }; "compatibility": { "sceneSchemaVersion": "deepblend.scene/v1"; "capabilities": Array<"geometry.primitive" | "geometry.primitive.dimensions" | "geometry.lathe" | "geometry.curve" | "geometry.handled_cup" | "geometry.handled_cup.tension" | "geometry.handled_cup.tension.extended" | "geometry.modifiers" | "material.principled" | "material.glass" | "material.emission" | "material.procedural" | "material.procedural.uv" | "material.anisotropy" | "animation.transform" | "animation.material" | "recipe.geometry-bindings">; }; "input": { "path": "scene-spec.json"; "sha256": string; }; "preview": { "path": "preview.png"; "sha256": string; "mediaType": "image/png"; "alt": string; }; "parameters": Array<(RecipeSchema.ColorParameter) | (RecipeSchema.NumberParameter)>; };
 }
 export type RecipeManifest = RecipeSchema.Document;
 export type Entity = SceneSpecSchema.Entity;
@@ -110,6 +110,7 @@ export interface BlenderErrorCodeMap {
   readonly SCRIPT_ERROR: "BLENDER_SCRIPT_ERROR";
   readonly PROTOCOL_VERSION_MISMATCH: "BLENDER_PROTOCOL_VERSION_MISMATCH";
   readonly UNSUPPORTED_ACTION: "BLENDER_UNSUPPORTED_ACTION";
+  readonly SCENE_FEATURE_UNSUPPORTED: "BLENDER_SCENE_FEATURE_UNSUPPORTED";
   readonly CAPABILITY_PROBE_FAILED: "BLENDER_CAPABILITY_PROBE_FAILED";
   readonly BOOTSTRAP_MISSING: "BLENDER_BOOTSTRAP_MISSING";
   readonly ENGINE_UNAVAILABLE: "BLENDER_ENGINE_UNAVAILABLE";

package/lib/schemas/recipe.schema.json

@@ -97,10 +97,11 @@
         "capabilities": {
           "type": "array",
           "minItems": 1,
-          "maxItems": 15,
+          "maxItems": 17,
           "items": {
             "enum": [
               "geometry.primitive",
+              "geometry.primitive.dimensions",
               "geometry.lathe",
               "geometry.curve",
               "geometry.handled_cup",
@@ -114,7 +115,8 @@
               "material.procedural.uv",
               "material.anisotropy",
               "animation.transform",
-              "animation.material"
+              "animation.material",
+              "recipe.geometry-bindings"
             ]
           }
         }
@@ -228,6 +230,88 @@
               "const": "exposure"
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "entityId",
+            "property",
+            "axis",
+            "multiplier"
+          ],
+          "description": "Apply a bounded parameter delta to an explicit local box dimension or entity location. No expressions or arbitrary paths.",
+          "properties": {
+            "kind": {
+              "const": "entity"
+            },
+            "entityId": {
+              "type": "string",
+              "pattern": "^[a-zA-Z][a-zA-Z0-9._-]{0,63}$"
+            },
+            "property": {
+              "enum": [
+                "dimensions",
+                "location"
+              ]
+            },
+            "axis": {
+              "enum": [
+                "x",
+                "y",
+                "z"
+              ]
+            },
+            "multiplier": {
+              "type": "number",
+              "minimum": -1000,
+              "maximum": 1000
+            },
+            "offsetAnimation": {
+              "type": "boolean",
+              "description": "Explicitly translate keyframe values on the bound location axis by the same delta, preserving the motion. Only valid for location bindings."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "cameraId",
+            "property",
+            "axis",
+            "multiplier"
+          ],
+          "properties": {
+            "kind": {
+              "const": "camera"
+            },
+            "cameraId": {
+              "type": "string",
+              "pattern": "^[a-zA-Z][a-zA-Z0-9._-]{0,63}$"
+            },
+            "property": {
+              "enum": [
+                "location",
+                "targetPoint"
+              ]
+            },
+            "axis": {
+              "enum": [
+                "x",
+                "y",
+                "z"
+              ]
+            },
+            "multiplier": {
+              "type": "number",
+              "minimum": -1000,
+              "maximum": 1000
+            }
+          },
+          "description": "Apply a bounded parameter delta to an explicit camera position or aim point; animated camera channels are refused."
         }
       ]
     },
@@ -309,7 +393,7 @@
         "bindings": {
           "type": "array",
           "minItems": 1,
-          "maxItems": 8,
+          "maxItems": 128,
           "items": {
             "$ref": "#/$defs/binding"
           }

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

@@ -519,6 +519,15 @@
           "minimum": 1,
           "maximum": 2.5,
           "description": "Dimensionless scale of both endpoint tangent speeds for the quintic attachment. Missing or 1 preserves the original surface. Values above 1.5 require the extended recipe capability. Native output validation still applies."
+        },
+        "dimensions": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "$ref": "#/$defs/positiveNumber"
+          },
+          "description": "Explicit local width, depth and height for cube or rounded_box, in scene units, before object transform and bevel. Mutually exclusive with scalar size."
         }
       },
       "description": "Deterministic procedural geometry. Lathe revolves a radius/height profile; handled_cup constructs a closed cup with shared-boundary flared handle roots. Coupled parameter constraints are checked before generation and the discrete output is validated."

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

@@ -702,6 +702,15 @@
           "minimum": 1,
           "maximum": 2.5,
           "description": "Dimensionless scale of both endpoint tangent speeds for the quintic attachment. Missing or 1 preserves the original surface. Values above 1.5 require the extended recipe capability. Native output validation still applies."
+        },
+        "dimensions": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "$ref": "#/$defs/positiveNumber"
+          },
+          "description": "Explicit local width, depth and height for cube or rounded_box, in scene units, before object transform and bevel. Mutually exclusive with scalar size."
         }
       }
     },

package/lib/sdk.d.ts

@@ -32,6 +32,8 @@ export interface SceneSpecValidation extends ValidationResult<SceneSpecIssue> {
 export function validateSceneSpec(input: unknown): SceneSpecValidation;
 export function parseSceneSpec(input: unknown): SceneSpec;
 /** Does not validate first. Call parseSceneSpec or check validateSceneSpec before compiling. */
+export const BOX_DIMENSIONS_FEATURE: 'geometry.primitive.dimensions';
+export function requiredSceneFeatures(spec: SceneSpec): string[];
 export function compileSceneSpec(spec: SceneSpec): {
   spec: SceneSpec; notices: SceneSpecIssue[];
   entityBounds: Record<string, { location: number[]; radius: number }>;

package/lib/sdk.js

@@ -12,6 +12,7 @@ export { canonicalStringify, canonicalPretty, sha256, sha256Canonical } from './
 export {
   validateSceneSpec, compileSceneSpec, sceneSpecCanonicalText, sceneSpecDigest, specHash,
   reviewInputsDigest, summarizeSceneSpec,
+  BOX_DIMENSIONS_FEATURE, requiredSceneFeatures,
 } from './scene-spec.js'
 export { SCENE_OPERATION_NAMES, validateScenePatch, applyPatchToSpec, buildOperationManifest } from './scene-patch.js'
 export {

package/package.json

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