@deepblend/dsh-blender-tool 0.15.0 → 0.18.0

package/lib/render-tools.js

@@ -62,7 +62,7 @@ export function describeRenderCost(frames) {
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 
-import { BlenderErrorCode, HOST_API_VERSION, warning } from '@deepblend/dsh-blender-contracts'
+import { BlenderError, BlenderErrorCode, HOST_API_VERSION, warning } from '@deepblend/dsh-blender-contracts'
 
 import {
   TOOL_OUTPUT,
@@ -171,6 +171,7 @@ export function describeJobLines(job) {
     `status:   ${job.status}`,
     `frames:   ${job.completedFrames}/${job.expectedFrames} complete (${job.percent}%) in range ${job.frameStart}..${job.frameEnd}`,
   ]
+  if (job.cameraSelection?.mode === 'shots') lines.push(`cameras:  saved shot sequence (${job.cameraSelection.shots.length} shots)`)
   if (job.pid !== null && job.pid !== undefined) lines.push(`pid:      ${job.pid}`)
   if (job.meanMsPerFrame !== null && job.meanMsPerFrame !== undefined) {
     const remaining = job.estimatedRemainingMs === null || job.estimatedRemainingMs === undefined
@@ -216,6 +217,7 @@ function finalRender(ctx) {
     description:
       'Start a DELIVERY render: every frame of the project\'s range (or a sub-range you name) at the ' +
       'SceneSpec\'s "final" render profile, then encode it to MP4 and publish the delivery package. ' +
+      'The default still renders one camera; saved shots alone do not switch it. Set useShotCameras:true to follow the saved shots, with exactly one shot covering each rendered frame. This freezes the camera/range selection for restart and records actual per-frame camera evidence. Never combine it with cameraId; on resume omit it and use the existing job selection. ' +
       'This is the expensive operation — measured on this machine at 19.6-41.4 s PER FRAME for a ' +
       '1920x1080 / Cycles / 256-sample delivery, so a 450-frame animation is about 3.4 hours. ' +
       '\n\nIt RETURNS IMMEDIATELY with a jobId; the render continues in the background while you keep ' +
@@ -244,10 +246,10 @@ function finalRender(ctx) {
         type: 'array',
         items: { type: 'number' },
         description:
-          'An explicit list of frames instead of a contiguous range — useful for a spot check of a few ' +
-          'expensive frames. Frames outside the project\'s own range are dropped with a warning.',
+          'An explicit list of frames forming a contiguous interval. Frames outside the project\'s own range are dropped with a warning; remaining gaps are refused before rendering because the MP4 encoder requires consecutive frames. Use blender_preview_render for separated spot checks.',
       },
       cameraId: { type: 'string', description: 'Camera to render from. Defaults to the camera with role "active-camera".' },
+      useShotCameras: { type: 'boolean', description: 'Explicit true: follow the saved shots and their frameRange/cameraId. Requires supported Host/runtime, at most64 nonoverlapping ranged shots and complete coverage of requested frames. Cannot combine with cameraId or resumeJobId. Omit on resume to keep the job’s frozen selection. Default single-camera behavior is unchanged.' },
       profileName: { type: 'string', description: 'SceneSpec render profile name. Defaults to "final".' },
       samples: {
         type: 'number',
@@ -263,6 +265,10 @@ function finalRender(ctx) {
         return { ok: false, text: `Delivery render unavailable.\n${resolved.unavailable.text}`, data: resolved.unavailable.data }
       }
       try {
+        if (args.useShotCameras !== undefined && typeof args.useShotCameras !== 'boolean') throw new BlenderError(
+          BlenderErrorCode.SCENE_SPEC_INVALID, 'useShotCameras must be boolean.')
+        if (args.useShotCameras === true && (args.cameraId !== undefined || args.resumeJobId !== undefined)) throw new BlenderError(
+          BlenderErrorCode.SCENE_SPEC_INVALID, 'Saved-shot rendering cannot also select cameraId or resumeJobId; resume with the recorded selection instead.')
         if (typeof args?.resumeJobId === 'string' && args.resumeJobId.length > 0) {
           const stale = hostPlaneIsCurrent(resolved.studio, ['resumeRenderJob', 'getJob'])
           if (stale !== null) return { ok: false, ...stale }
@@ -296,8 +302,13 @@ function finalRender(ctx) {
           }
         }
 
-        const stale = hostPlaneIsCurrent(resolved.studio, ['startFinalRender', 'listJobs', 'getJob'])
+        const startMethod = args.useShotCameras === true ? 'startShotSequenceRender' : 'startFinalRender'
+        const stale = hostPlaneIsCurrent(resolved.studio, [startMethod, 'listJobs', 'getJob'])
         if (stale !== null) return { ok: false, ...stale }
+        if (typeof resolved.studio[startMethod] !== 'function') throw new BlenderError(
+          BlenderErrorCode.RUNTIME_UNAVAILABLE,
+          'The running Host does not support explicit shot-camera rendering. Upgrade/restart the profile; no single-camera fallback was started.')
+        const start = request => resolved.studio[startMethod](request)
 
         const startRequest = {
           projectId: args.projectId,
@@ -312,7 +323,7 @@ function finalRender(ctx) {
 
         let started
         try {
-          started = await canonicalCall(resolved.studio.startFinalRender(definedFields(startRequest)), warning)
+          started = await canonicalCall(start(definedFields(startRequest)), warning)
         } catch (cause) {
           // ── the approval gate (SPEC §15.1, architecture-decisions Q7) ────────
           //
@@ -367,7 +378,7 @@ function finalRender(ctx) {
           // between is enough. The refusal names the revision it measured, and that is the one this renders.
           const approvedRevision = cause.detail?.revision ?? startRequest.revision
           started = await canonicalCall(
-            resolved.studio.startFinalRender(definedFields({
+            start(definedFields({
               ...startRequest,
               ...approvedRevision === undefined ? {} : { revision: approvedRevision },
               approved: true,

package/lib/tools.js

@@ -33,6 +33,8 @@ import { attachCommittedPreview } from './committed-preview.js'
 
 import {
   SCENE_OPERATION_NAMES,
+  CAMERA_UPDATE_FIELDS,
+  CAMERA_TARGET_UPDATE_HINT,
   BlenderError,
   BlenderErrorCode,
   CREATION_REQUEST_VERSION,
@@ -423,14 +425,17 @@ function sceneGet(ctx) {
     parameters: {
       projectId: { type: 'string', required: true, description: 'The project id.' },
       revision: { type: 'string', description: 'Read a specific revision instead of the current one.' },
-      sourceEntityId: { type: 'string', description: 'Read exact saved JSON for one entity (1–64 character ID), without the scene catalogue. Cannot combine with full:true or geometry options.' },
+      sourceEntityId: { type: 'string', description: 'Read exact saved JSON for one entity (1–64 character ID), without the scene catalogue. This is an entity ID, not an animation-track, camera or asset-descriptor ID; use the scene catalogue/full:true to read those instead, without sourceEntityId. Cannot combine with full:true or geometry options.' },
       sourceOffset: { type: 'integer', description: 'UTF-16 character offset in compact entity JSON, default 0. Requires sourceEntityId; offsets above zero require the revision returned by the first chunk.' },
       sourceLimit: { type: 'integer', description: 'Maximum source characters in this chunk, 1–2048 (default 2048). Escaped text may return fewer. Requires sourceEntityId.' },
       geometryEntityIds: { type: 'array', items: { type: 'string' },
         description: 'Optional: measure 1–8 distinct saved native entity IDs. Requires geometryFrame. Hidden viewport objects and non-mesh roots are explicitly unavailable.' },
       geometryFrame: { type: 'integer',
         description: 'Explicit integer frame from 0 to 1000000 for native geometry measurement. Use the frame of the preview being checked. Requires geometryEntityIds.' },
-      geometryObjectAxes: { type: 'boolean', description: 'Optional true: also measure actual evaluated vertices in physical orthogonal axes of each selected object, including native scale. Requires geometryEntityIds and geometryFrame. Returns objectAxisBoundsMeters/objectAxisExtentMm/objectAxisWorldMatrix and an explicit basis, separate from world-axis spans. Sheared/degenerate bases are unavailable. Never invert a world AABB to recover local extents.' },
+      geometryCameraId: { type: 'string', description: 'Optional saved perspective camera ID: project selected actual vertices into its frame using native camera shift and render aspect. Returns normalized image bounds, containedInFrame (default 3% margin) and depth/clip evidence at geometryFrame only. Combine with geometryAssetInstanceIds for entire imported subjects. Does not certify occlusion, collision or an animation path; inspect pixels and every shot. Cannot combine with geometryObjectAxes or geometrySurfaceSamples. No camera is changed.' },
+      geometryCameraMargin: { type: 'number', description: 'Optional normalized border margin 0..0.25 (default 0.03); requires geometryCameraId.' },
+      geometryAssetInstanceIds: { type: 'array', items: { type: 'string' }, description: 'Optional distinct imported asset-instance IDs, also in geometryEntityIds. Measures the WHOLE evaluated mesh hierarchy as ASSET_MESH_SET, not the empty container origin. Requires geometryFrame. Up to 128 meshes and 2M vertices/polygons per instance; hidden/unsupported/empty hierarchies are unavailable as a whole. Cannot combine with geometryObjectAxes or geometrySurfaceSamples. Use world min Z/max Z to check a horizontal pedestal, then inspect pixels; bounds do not certify contact or clearance. Does not modify assets or transforms.' },
+      geometryObjectAxes: { type: 'boolean', description: 'Optional true: also measure actual evaluated vertices in physical orthogonal axes of each selected object, including native scale. Requires geometryEntityIds and geometryFrame; do not combine with geometryAssetInstanceIds or geometryCameraId. Returns objectAxisBoundsMeters/objectAxisExtentMm/objectAxisWorldMatrix and an explicit basis, separate from world-axis spans. Sheared/degenerate bases are unavailable. Never invert a world AABB to recover local extents.' },
       geometryOnly: { type: 'boolean', description: 'Return only source identity and verified geometry evidence, without the scene catalogue. Requires geometryEntityIds and geometryFrame; cannot be combined with full:true. Ordinary reads keep their existing shape.' },
       geometryCompareRevision: { type: 'string', description: 'Optional explicit reference revision (e.g. r0004). Requires geometryEntityIds and geometryFrame. Re-measures identical selected parts/frame and computes current-minus-reference native world-axis spans and origin moves. If geometrySurfaceSamples is supplied, compares those same local samples instead. Requested geometryAssemblyPairs also return origin-offset changes. Unavailable evidence stays unavailable; no clearance, global minima or change cause is established.' },
       geometryAssemblyPairs: { type: 'array', description: 'Optional 1–8 ordered native object-origin pairs. Requires geometryEntityIds containing both ends and geometryFrame. Offsets use world XYZ in millimeters; they are not surface protrusion, contact, clearance or whole-assembly certification.',
@@ -463,6 +468,8 @@ function sceneGet(ctx) {
           const receipt = await readEntitySource(resolved.studio, args)
           return { ok: true, text: renderSuccess('Saved entity source chunk. Continue at nextOffset using this revision; verify entityJsonSha256 before concatenating.', receipt, { compact: true }), data: receipt }
         }
+        if ((args.geometryCameraId !== undefined || args.geometryCameraMargin !== undefined) && args.geometryEntityIds === undefined) throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'Camera framing requires geometryEntityIds and geometryFrame.')
+        if (args.geometryAssetInstanceIds !== undefined && args.geometryEntityIds === undefined) throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'Asset bounds require geometryEntityIds and geometryFrame.')
         if (args.geometryObjectAxes !== undefined && typeof args.geometryObjectAxes !== 'boolean') throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryObjectAxes must be boolean.')
         if (args.geometryObjectAxes === true && args.geometryEntityIds === undefined) throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'Object-local bounds require geometryEntityIds and geometryFrame.')
         if (args.geometryOnly !== undefined && typeof args.geometryOnly !== 'boolean') {
@@ -483,19 +490,20 @@ function sceneGet(ctx) {
         }
         if (args.geometryAssemblyPairs !== undefined) validateAssemblyPairs(args.geometryAssemblyPairs, args.geometryEntityIds)
         if (args.geometryEntityIds !== undefined) validateGeometrySelection({ entityIds: args.geometryEntityIds,
-          frame: args.geometryFrame, checkpointSha256: '0'.repeat(64), ...(args.geometryObjectAxes === true ? { objectAxes: true } : {}), ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) })
+          frame: args.geometryFrame, checkpointSha256: '0'.repeat(64), ...(args.geometryAssetInstanceIds === undefined ? {} : { assetInstanceIds: args.geometryAssetInstanceIds }), ...(args.geometryCameraId === undefined ? {} : { cameraId: args.geometryCameraId }), ...(args.geometryCameraMargin === undefined ? {} : { cameraMargin: args.geometryCameraMargin }), ...(args.geometryObjectAxes === true ? { objectAxes: true } : {}), ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) })
         const { data, canonicalWarnings } = await canonicalCall(resolved.studio.getScene(args.projectId, {
           ...definedFields({ revision: args.revision }),
           full: args.full === true,
           ...(args.geometryEntityIds === undefined ? {} : { geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame,
+            ...(args.geometryAssetInstanceIds === undefined ? {} : { assetInstanceIds: args.geometryAssetInstanceIds }), ...(args.geometryCameraId === undefined ? {} : { cameraId: args.geometryCameraId }), ...(args.geometryCameraMargin === undefined ? {} : { cameraMargin: args.geometryCameraMargin }),
             ...(args.geometryObjectAxes === true ? { objectAxes: true } : {}), ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) }, signal: exec?.signal }),
         }), warning)
-        const hasSamples = args.geometrySurfaceSamples !== undefined, hasObjectAxes = args.geometryObjectAxes === true
+        const hasSamples = args.geometrySurfaceSamples !== undefined, hasObjectAxes = args.geometryObjectAxes === true, hasV4Evidence = args.geometryAssetInstanceIds !== undefined || args.geometryCameraId !== undefined
         const verifyScene = (data, expectedRevision) => {
           if (expectedRevision !== undefined && data.revision !== expectedRevision) {
             throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Host returned a different saved revision than requested.')
           }
-          if (args.geometryEntityIds !== undefined && (!data.geometryInspection || data.geometryInspection.schemaVersion !== (hasObjectAxes ? 'deepblend.scene-geometry/v3' : hasSamples ? 'deepblend.scene-geometry/v2' : 'deepblend.scene-geometry/v1') ||
+          if (args.geometryEntityIds !== undefined && (!data.geometryInspection || data.geometryInspection.schemaVersion !== (hasV4Evidence ? 'deepblend.scene-geometry/v4' : hasObjectAxes ? 'deepblend.scene-geometry/v3' : hasSamples ? 'deepblend.scene-geometry/v2' : 'deepblend.scene-geometry/v1') ||
               data.geometryInspection.projectId !== args.projectId || data.geometryInspection.sourceRevision !== data.revision ||
               data.geometryInspection.sourceDigest !== data.digest || data.geometryInspection.sourceUnchanged !== true || data.geometryInspection.frame !== args.geometryFrame ||
               !Array.isArray(data.geometryInspection.limitations) ||
@@ -503,17 +511,19 @@ function sceneGet(ctx) {
             throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Host did not return measurements for the requested source and frame. Upgrade DeepBlend before measuring; ordinary scene reads remain available.')
           }
           if (data.geometryInspection) verifyGeometryReport({ frame: data.geometryInspection.frame, blenderVersion: data.geometryInspection.blenderVersion, objects: data.geometryInspection.objects,
-            schemaVersion: hasObjectAxes ? 'deepblend.geometry-inspection/v3' : hasSamples ? 'deepblend.geometry-inspection/v2' : 'deepblend.geometry-inspection/v1',
+            schemaVersion: hasV4Evidence ? 'deepblend.geometry-inspection/v4' : hasObjectAxes ? 'deepblend.geometry-inspection/v3' : hasSamples ? 'deepblend.geometry-inspection/v2' : 'deepblend.geometry-inspection/v1',
+            ...(args.geometryCameraId === undefined ? {} : { camera: data.geometryInspection.camera }),
             ...(hasObjectAxes ? { objectAxisBasis: data.geometryInspection.objectAxisBasis } : {}),
             ...(hasSamples ? { surfaceSamples: data.geometryInspection.surfaceSamples } : {}), checkpointSha256: data.geometryInspection.sourceCheckpointSha256,
             checkpointUnchanged: data.geometryInspection.sourceUnchanged }, { entityIds: args.geometryEntityIds, frame: args.geometryFrame,
-            checkpointSha256: data.geometryInspection.sourceCheckpointSha256, ...(hasObjectAxes ? { objectAxes: true } : {}), ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) })
+            checkpointSha256: data.geometryInspection.sourceCheckpointSha256, ...(args.geometryAssetInstanceIds === undefined ? {} : { assetInstanceIds: args.geometryAssetInstanceIds }), ...(args.geometryCameraId === undefined ? {} : { cameraId: args.geometryCameraId }), ...(args.geometryCameraMargin === undefined ? {} : { cameraMargin: args.geometryCameraMargin }), ...(hasObjectAxes ? { objectAxes: true } : {}), ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) })
         }
         verifyScene(data, args.revision)
         if (args.geometryAssemblyPairs !== undefined) data.geometryAssemblyOrigins = readAssemblyOrigins(data.geometryInspection, args.geometryAssemblyPairs)
         if (args.geometryCompareRevision !== undefined) {
           const reference = await canonicalCall(resolved.studio.getScene(args.projectId, { revision: args.geometryCompareRevision,
-            full: false, geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame, ...(hasObjectAxes ? { objectAxes: true } : {}), ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) }, signal: exec?.signal }), warning)
+            full: false, geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame,
+            ...(args.geometryAssetInstanceIds === undefined ? {} : { assetInstanceIds: args.geometryAssetInstanceIds }), ...(args.geometryCameraId === undefined ? {} : { cameraId: args.geometryCameraId }), ...(args.geometryCameraMargin === undefined ? {} : { cameraMargin: args.geometryCameraMargin }), ...(hasObjectAxes ? { objectAxes: true } : {}), ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) }, signal: exec?.signal }), warning)
           verifyScene(reference.data, args.geometryCompareRevision)
           canonicalWarnings.push(...reference.canonicalWarnings)
           data.geometryComparison = hasSamples ? compareSurfaceReports(reference.data.geometryInspection, data.geometryInspection) : compareGeometryReports(reference.data.geometryInspection, data.geometryInspection)
@@ -613,7 +623,7 @@ const OPERATION_SUMMARY = [
   'light.update                 {lightId, energy?, color?, size?, transform?, spotSize?, spotBlend?, angle?}',
   'light.remove                 {lightId}',
   'camera.add                   {camera}',
-  'camera.update                {cameraId, lens?, transform?, targetEntityId?, targetPoint?, clipping?, fStop?}',
+  `camera.update                {cameraId, ${CAMERA_UPDATE_FIELDS.map(field => `${field}?`).join(', ')}}`,
   'camera.remove                {cameraId}',
   'animation.track.set          {track}                                        — {id, targetEntityId, targetKind?, property, keyframes[]}',
   'animation.track.remove       {trackId}',
@@ -645,6 +655,9 @@ function scenePatch(ctx) {
       'fails, no revision is created and the current revision is untouched, so a failed patch is always safe ' +
       'to correct and retry. Retrying an identical patch is also safe — it returns the original outcome ' +
       'instead of committing twice.\n\n' +
+      'For complex authored geometry, prefer 1–6 coherent operations per call and reuse entityCopies instead of repeating long vertex arrays. This is guidance, not a transaction limit: keep dependent changes atomic. Send strict JSON with complete arrays/objects; never execute a truncated or repaired argument. Read returned validation paths before retrying. ' +
+      'asset.add.asset.license is an object {source,commercialUse,attribution}, unlike the ingestion tool license string. A cube generator size is one scalar, not a three-component vector; use dimensions/transform according to its declared schema.\n\n' +
+      CAMERA_TARGET_UPDATE_HINT + '\n\n' +
       'Optional entityCopies creates 1–16 explicit copies of single saved entities from baseRevision, before operations. ' +
       'Use {sourceEntityId,newEntityId,transform?} to reuse exact geometry and manual details without repeating vertices; operations may then be []. ' +
       'Transform components are absolute overrides. All other entity fields and external references are preserved; animation tracks, child assemblies and reference remapping are NOT copied. ' +
@@ -1192,7 +1205,7 @@ function assetIngest(ctx) {
       },
       license: {
         type: 'string',
-        description: 'Licence string recorded with the asset. Worth setting for anything downloaded: an ' +
+        description: 'Ingestion licence string (for example CC0). In a later asset.add patch, asset.license must instead be an object with source/commercialUse/attribution; retain the returned descriptor. Worth setting for anything downloaded: an ' +
           'asset whose provenance is unrecorded is one nobody can safely ship.',
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-tool",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "type": "module",
   "description": "Agent-preset tool consumer: registers the model-visible DeepBlend Blender tools. Publishes no service.",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.15.0"
+    "@deepblend/dsh-blender-contracts": "0.18.0"
   },
   "license": "MIT",
   "repository": {