@deepblend/dsh-blender-contracts 0.4.0 → 0.6.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,
@@ -874,4 +877,5 @@ export {
   managedBlenderCandidates,
 } from './deployment-paths.js'
 
-export { RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError, recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe } from './recipe.js'
+export { RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError, recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe, instantiateRecipeLock } from './recipe.js'
+export { planRecipeGeometryEdit, recipeGeometryParameters } from './recipe-parameters.js'

package/lib/recipe-parameters.js

@@ -0,0 +1,107 @@
+/** Plan existing-assembly edits as ordinary, bounded ScenePatch operations. */
+import { canonicalStringify, sha256Canonical } from './canonical.js'
+import { instantiateRecipeLock, RecipeError } from './recipe.js'
+import { validateSceneSpec } from './scene-spec.js'
+
+const axisOf = binding => ['x', 'y', 'z'].indexOf(binding.axis)
+const structural = parameter => parameter.bindings.some(binding => binding.kind === 'entity')
+  && parameter.bindings.every(binding => ['entity', 'camera'].includes(binding.kind))
+const entity = (spec, id) => spec.entities.find(item => item.id === id)
+const vector = (target, property) => property === 'dimensions' ? target?.generator?.dimensions
+  : property === 'targetPoint' ? target?.targetPoint : target?.transform?.location
+const close = (a, b) => Number.isFinite(a) && Number.isFinite(b)
+  && Math.abs(a - b) <= 1e-9 * Math.max(1, Math.abs(b))
+
+export function recipeGeometryParameters(manifest) {
+  return manifest.parameters.filter(structural)
+}
+
+export function planRecipeGeometryEdit(lock, currentSpec, parameterState, changes) {
+  const origin = instantiateRecipeLock(lock)
+  const scene = validateSceneSpec(currentSpec)
+  if (!scene.ok) throw new RecipeError('RECIPE_SCENE_INVALID', scene.summary, { errors: scene.errors })
+  let currentLock = lock
+  if (parameterState !== undefined) {
+    if (parameterState?.schemaVersion !== 'deepblend.recipe-parameters/v1'
+        || parameterState.manifestSha256 !== lock.manifestSha256) {
+      throw new RecipeError('RECIPE_LOCK_INVALID', 'Parameter state belongs to a different recipe')
+    }
+    currentLock = { ...lock, values: parameterState.values, valuesSha256: parameterState.valuesSha256 }
+  }
+  const before = parameterState === undefined ? origin : instantiateRecipeLock(currentLock)
+  const after = instantiateRecipeLock(currentLock, changes)
+  const parameters = recipeGeometryParameters(lock.manifest)
+  for (const id of Object.keys(changes)) {
+    if (!parameters.some(parameter => parameter.id === id)) {
+      throw new RecipeError('RECIPE_PARAMETER_INVALID', `Parameter ${id} is not an assembly geometry control`)
+    }
+  }
+  const conflicts = []
+  for (const parameter of parameters) for (const binding of parameter.bindings) {
+    if (binding.kind !== 'entity') continue
+    const expected = vector(entity(before.spec, binding.entityId), binding.property)?.[axisOf(binding)]
+    const actual = vector(entity(currentSpec, binding.entityId), binding.property)?.[axisOf(binding)]
+    if (!close(actual, expected)) conflicts.push({ parameterId: parameter.id, entityId: binding.entityId,
+      property: binding.property, axis: binding.axis, expected, actual })
+    if (binding.property === 'dimensions') {
+      const oldScale = entity(before.spec, binding.entityId).transform.scale
+      const scale = entity(currentSpec, binding.entityId)?.transform.scale
+      if (!scale?.every((value, axis) => close(value, oldScale[axis]))) {
+        conflicts.push({ parameterId: parameter.id, entityId: binding.entityId,
+          property: 'scale', expected: oldScale, actual: scale })
+      }
+    }
+  }
+  if (conflicts.length) throw new RecipeError('RECIPE_PARAMETER_CONFLICT',
+    'Recipe-controlled geometry was independently edited; resolve these fields before resizing', { conflicts })
+
+  const changed = parameters.filter(parameter => before.values[parameter.id] !== after.values[parameter.id])
+  const generators = new Map(), locations = new Map(), cameras = new Map(), tracks = new Map(), animationOffsets = new Map()
+  const protectedCameras = new Set()
+  for (const parameter of changed) for (const binding of parameter.bindings) {
+    const axis = axisOf(binding)
+    if (binding.kind === 'camera') {
+      const actual = currentSpec.cameras?.find(item => item.id === binding.cameraId)
+      const original = before.spec.cameras?.find(item => item.id === binding.cameraId)
+      // Independently authored photography remains intact, including deleted cameras.
+      if (!actual || canonicalStringify(actual) !== canonicalStringify(original)) {
+        protectedCameras.add(binding.cameraId); continue
+      }
+      if (!cameras.has(binding.cameraId)) cameras.set(binding.cameraId, { op: 'camera.update', cameraId: binding.cameraId })
+      const operation = cameras.get(binding.cameraId)
+      const target = after.spec.cameras.find(item => item.id === binding.cameraId)
+      if (binding.property === 'targetPoint') operation.targetPoint = structuredClone(target.targetPoint)
+      else operation.transform = { location: structuredClone(target.transform.location) }
+      continue
+    }
+    const actual = entity(currentSpec, binding.entityId), target = entity(after.spec, binding.entityId)
+    if (binding.property === 'dimensions') {
+      if (!generators.has(actual.id)) generators.set(actual.id, structuredClone(actual.generator))
+      generators.get(actual.id).dimensions[axis] = target.generator.dimensions[axis]
+    } else {
+      if (!locations.has(actual.id)) locations.set(actual.id, structuredClone(actual.transform.location))
+      const delta = target.transform.location[axis] - entity(before.spec, actual.id).transform.location[axis]
+      locations.get(actual.id)[axis] = target.transform.location[axis]
+      if (binding.offsetAnimation === true) animationOffsets.set(`${actual.id}:${binding.axis}`, {
+        entityId: actual.id, property: `location.${binding.axis}`, delta,
+      })
+    }
+  }
+  for (const offset of animationOffsets.values()) for (const track of currentSpec.animationTracks ?? []) {
+    if ((track.targetKind ?? 'entity') !== 'entity' || track.targetEntityId !== offset.entityId
+        || track.property !== offset.property) continue
+    if (!tracks.has(track.id)) tracks.set(track.id, structuredClone(track))
+    for (const keyframe of tracks.get(track.id).keyframes) keyframe.value += offset.delta
+  }
+  const operations = [
+    ...[...generators].map(([entityId, generator]) => ({ op: 'entity.generator.set', entityId, generator })),
+    ...[...locations].map(([entityId, location]) => ({ op: 'entity.transform.update', entityId, location })),
+    ...cameras.values(),
+    ...[...tracks.values()].map(track => ({ op: 'animation.track.set', track })),
+  ]
+  return { operations, changedParameters: changed.map(parameter => parameter.id),
+    preservedCameraIds: [...protectedCameras], parameterState: {
+      schemaVersion: 'deepblend.recipe-parameters/v1', manifestSha256: lock.manifestSha256,
+      values: after.values, valuesSha256: sha256Canonical(after.values),
+    } }
+}

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,27 +190,55 @@ 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
 }
 
-/** Hash actual loaded bytes; the manifest is a claim, never a verification receipt. */
-export function validateRecipePackage(bundle, options = {}) {
-  const checked = validateRecipeManifest(bundle?.manifest, options)
-  if (!checked.ok) return checked
-  const { manifest } = bundle
+/** Shared input validation; locked recipes do not retain original preview pixels. */
+function validateRecipeInput(manifest, input) {
   const errors = []
   let sceneSpec
   try {
-    const sceneBytes = asBytes(bundle.sceneBytes, RECIPE_LIMITS.sceneBytes, 'input')
-    const previewBytes = asBytes(bundle.previewBytes, RECIPE_LIMITS.previewBytes, 'preview')
+    const sceneBytes = asBytes(input, RECIPE_LIMITS.sceneBytes, 'input')
     if (sha256(sceneBytes) !== manifest.input.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'input.sha256', 'Loaded SceneSpec bytes differ from the declared hash'))
-    if (sha256(previewBytes) !== manifest.preview.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'preview.sha256', 'Loaded preview bytes differ from the declared hash'))
     if (errors.length) return result(errors)
-    try { validatePreview(previewBytes) } catch (error) { return result([issue('RECIPE_PREVIEW_INVALID', 'preview', error.message)]) }
     try { sceneSpec = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(sceneBytes)) }
     catch { return result([issue('RECIPE_INPUT_INVALID', 'input', 'SceneSpec must be valid UTF-8 JSON')]) }
     const scene = validateSceneSpec(sceneSpec)
@@ -216,12 +263,55 @@ export function validateRecipePackage(bundle, options = {}) {
   } catch (error) { return result([issue(error.code ?? 'RECIPE_INPUT_INVALID', 'input', error.message)]) }
 }
 
+/** Hash actual loaded bytes; the manifest is a claim, never a verification receipt. */
+export function validateRecipePackage(bundle, options = {}) {
+  const checked = validateRecipeManifest(bundle?.manifest, options)
+  if (!checked.ok) return checked
+  const { manifest } = bundle
+  try {
+    const sceneBytes = asBytes(bundle.sceneBytes, RECIPE_LIMITS.sceneBytes, 'input')
+    const previewBytes = asBytes(bundle.previewBytes, RECIPE_LIMITS.previewBytes, 'preview')
+    const errors = []
+    if (sha256(sceneBytes) !== manifest.input.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'input.sha256', 'Loaded SceneSpec bytes differ from the declared hash'))
+    if (sha256(previewBytes) !== manifest.preview.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'preview.sha256', 'Loaded preview bytes differ from the declared hash'))
+    if (errors.length) return result(errors)
+    try { validatePreview(previewBytes) } catch (error) { return result([issue('RECIPE_PREVIEW_INVALID', 'preview', error.message)]) }
+    return validateRecipeInput(manifest, sceneBytes)
+  } catch (error) { return result([issue(error.code ?? 'RECIPE_INPUT_INVALID', 'input', error.message)]) }
+}
+
 /** Return a fresh resolved SceneSpec; only explicit scalar/color slots can change. */
 export function instantiateRecipe(bundle, values = {}, options = {}) {
   const checked = validateRecipePackage(bundle, options)
   if (!checked.ok) throw new RecipeError(checked.errors[0].code, checked.summary, { errors: checked.errors })
+  return resolveRecipe(bundle.manifest, checked, values)
+}
+
+/** Resolve a saved origin without inventing or accepting replacement preview bytes. */
+export function instantiateRecipeLock(lock, changes = {}, options = {}) {
+  const fail = message => { throw new RecipeError('RECIPE_LOCK_INVALID', message) }
+  if (!plain(lock) || lock.schemaVersion !== 'deepblend.recipe-lock/v1') fail('Unsupported recipe lock')
+  const manifestCheck = validateRecipeManifest(lock.manifest, options)
+  if (!manifestCheck.ok) throw new RecipeError(manifestCheck.errors[0].code, manifestCheck.summary, { errors: manifestCheck.errors })
+  const { manifest } = lock
+  if (lock.id !== manifest.id || lock.version !== manifest.version
+      || lock.manifestSha256 !== sha256Canonical(manifest) || lock.packageDigest !== lock.manifestSha256
+      || lock.inputSha256 !== manifest.input.sha256 || lock.previewSha256 !== manifest.preview.sha256) {
+    fail('Recipe lock identity or manifest hashes differ')
+  }
+  if (typeof lock.sceneSource !== 'string' || lock.sceneSource.length > RECIPE_LIMITS.sceneBytes
+      || !plain(lock.values)) fail('Recipe lock must retain bounded exact input and resolved values')
+  const checked = validateRecipeInput(manifest, new TextEncoder().encode(lock.sceneSource))
+  if (!checked.ok) throw new RecipeError(checked.errors[0].code, checked.summary, { errors: checked.errors })
+  const original = resolveRecipe(manifest, checked, lock.values)
+  if (sha256Canonical(original.values) !== lock.valuesSha256
+      || sha256Canonical(lock.values) !== lock.valuesSha256) fail('Recipe lock values differ from their resolved hash')
+  if (!plain(changes)) throw new RecipeError('RECIPE_PARAMETER_INVALID', 'Parameter values must be a plain object')
+  return resolveRecipe(manifest, checked, { ...original.values, ...changes })
+}
+
+function resolveRecipe(manifest, checked, values) {
   if (!plain(values)) throw new RecipeError('RECIPE_PARAMETER_INVALID', 'Parameter values must be a plain object')
-  const { manifest } = bundle
   const known = new Set(manifest.parameters.map(parameter => parameter.id))
   const errors = Object.keys(values).filter(key => !known.has(key) || RESERVED.has(key))
     .map(key => issue('RECIPE_PARAMETER_UNKNOWN', `values.${key}`, 'Unknown parameter'))
@@ -240,6 +330,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 }>;
@@ -92,6 +94,19 @@ export type RecipeValues = Record<string, number | [number, number, number]>;
 export interface RecipeBundle { manifest: RecipeManifest; sceneBytes: string | Uint8Array; previewBytes: string | Uint8Array }
 export interface RecipeOptions { supportedCapabilities?: Iterable<RecipeCapability> }
 export interface RecipeValidation extends ValidationResult { notices: SceneSpecIssue[]; sceneSpec?: SceneSpec }
+export interface RecipeLock {
+  schemaVersion: 'deepblend.recipe-lock/v1'; id: string; version: string;
+  manifestSha256: string; packageDigest: string; inputSha256: string; previewSha256: string;
+  valuesSha256: string; manifest: RecipeManifest; values: RecipeValues; sceneSource: string;
+}
+export interface RecipeParameterState {
+  schemaVersion: 'deepblend.recipe-parameters/v1'; manifestSha256: string;
+  values: RecipeValues; valuesSha256: string; originRevision?: string;
+}
+export interface RecipeGeometryPlan {
+  operations: ScenePatchOperation[]; changedParameters: string[]; preservedCameraIds: string[];
+  parameterState: RecipeParameterState;
+}
 export function recipeCapabilitiesForScene(spec: SceneSpec): RecipeCapability[];
 export function validateRecipeManifest(manifest: unknown, options?: RecipeOptions): RecipeValidation;
 export function parseRecipeManifest(manifest: unknown, options?: RecipeOptions): RecipeManifest;
@@ -100,3 +115,7 @@ export function instantiateRecipe(bundle: RecipeBundle, values?: RecipeValues, o
   spec: SceneSpec; values: RecipeValues; notices: SceneSpecIssue[];
   recipe: { id: string; version: string; manifestSha256: string; inputSha256: string; previewSha256: string; valuesSha256: string };
 };
+export function instantiateRecipeLock(lock: RecipeLock, changes?: RecipeValues, options?: RecipeOptions): ReturnType<typeof instantiateRecipe>;
+export function recipeGeometryParameters(manifest: RecipeManifest): RecipeManifest['parameters'];
+export function planRecipeGeometryEdit(lock: RecipeLock, currentSpec: SceneSpec,
+  parameterState: RecipeParameterState | undefined, changes: Record<string, number>): RecipeGeometryPlan;

package/lib/sdk.js

@@ -12,12 +12,14 @@ 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 {
   RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError,
-  recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe,
+  recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe, instantiateRecipeLock,
 } from './recipe.js'
+export { planRecipeGeometryEdit, recipeGeometryParameters } from './recipe-parameters.js'
 
 /** Validate untrusted JSON and return a separate document; never assert a type without checking it. */
 export function parseSceneSpec(input) {

package/lib/ui-api.js

@@ -83,6 +83,8 @@ export const UI_ROUTES = Object.freeze([
   { id: 'project.review', method: 'POST', path: '/deepblend/projects/:projectId/review', write: true, summary: 'Explicitly render and consult the visual reviewer for one revision.' },
   { id: 'project.autofix', method: 'POST', path: '/deepblend/projects/:projectId/autofix', write: true, summary: 'Explicitly run a bounded visual correction loop for one revision.' },
   { id: 'project.patch', method: 'POST', path: '/deepblend/projects/:projectId/patch', write: true, summary: 'Apply a ScenePatch as one atomic revision.' },
+  { id: 'project.recipeParameters', method: 'GET', path: '/deepblend/projects/:projectId/recipe-parameters', write: false, summary: 'Read saved assembly controls at one revision.' },
+  { id: 'project.recipeParameters.update', method: 'POST', path: '/deepblend/projects/:projectId/recipe-parameters', write: true, summary: 'Save bounded assembly dimensions as an atomic revision.' },
   { id: 'project.restore', method: 'POST', path: '/deepblend/projects/:projectId/restore', write: true, summary: 'Move the current revision pointer to a saved revision, preserving history without creating a new revision.' },
   { id: 'project.jobs', method: 'GET', path: '/deepblend/projects/:projectId/jobs', write: false, summary: 'Render/export jobs of a project.' },
   { id: 'project.job', method: 'GET', path: '/deepblend/projects/:projectId/jobs/:jobId', write: false, summary: 'One job with its live progress.' },
@@ -930,4 +932,5 @@ export const UI_TOOL_CARD_KEYS = Object.freeze([
   'blender_export',
   'blender_job_status',
   'blender_job_cancel',
+  'blender_recipe_parameters',
 ])

package/package.json

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