@deepblend/dsh-blender-tool 0.13.0 → 0.14.0

package/lib/assembly-origins.js

@@ -63,7 +63,7 @@ export function compareAssemblyOrigins(before, after) {
   })
   return { schemaVersion: 'deepblend.assembly-origin-comparison/v1', referenceSource: before.source, currentSource: after.source,
     pairs, comparedPairs: pairs.filter(pair => pair.worldOriginOffsetChangeMm !== undefined).length,
-    limitations: ['Changes are current minus reference; offset preservation does not establish surface contact or attachment correctness.', ...limitations] }
+    limitations: ['Object-local changes compare each object own scaled evaluated mesh axes. Changed local geometry orientation can change these spans. They are not world distances or semantic body dimensions.', 'Changes are current minus reference; offset preservation does not establish surface contact or attachment correctness.', ...limitations] }
 }
 
 /** Inputs have already passed source/selection/frame and native report verification. */
@@ -72,10 +72,13 @@ export function compareGeometryReports(reference, current) {
   const objects = current.objects.map((after, index) => {
     const before = reference.objects[index]
     if (before.entityId !== after.entityId) refuse('comparison entity identities differ.')
-    const values = object => object.available ? { status: 'measured', worldAxisExtentMm: object.worldAxisExtentMm, worldOriginMeters: origin(object) } :
+    const values = object => object.available ? { status: 'measured', worldAxisExtentMm: object.worldAxisExtentMm, worldOriginMeters: origin(object),
+      ...(object.objectAxisStatus ? { objectAxisStatus: object.objectAxisStatus } : {}),
+      ...(object.objectAxisExtentMm ? { objectAxisExtentMm: object.objectAxisExtentMm } : {}) } :
       { status: 'unavailable', reason: object.unavailableReason }
     const row = { entityId: after.entityId, before: values(before), after: values(after) }
     if (before.available && after.available) {
+      if (before.objectAxisExtentMm && after.objectAxisExtentMm) row.objectAxisExtentChangeMm = subtract(after.objectAxisExtentMm, before.objectAxisExtentMm)
       row.worldAxisExtentChangeMm = subtract(after.worldAxisExtentMm, before.worldAxisExtentMm)
       row.worldOriginChangeMm = subtractMm(row.after.worldOriginMeters, row.before.worldOriginMeters)
     }
@@ -83,5 +86,5 @@ export function compareGeometryReports(reference, current) {
   })
   return { schemaVersion: 'deepblend.geometry-comparison/v1', referenceInspection: reference, currentSource: identity(current), objects,
     summary: { requestedEntities: objects.length, comparedEntities: objects.filter(object => object.worldAxisExtentChangeMm !== undefined).length },
-    limitations: ['Changes are current minus reference for the same selected native parts and frame; their cause is not established.', ...limitations] }
+    limitations: ['Object-local changes compare each object own scaled evaluated mesh axes. Changed local geometry orientation can change these spans. They are not world distances or semantic body dimensions.', 'Changes are current minus reference for the same selected native parts and frame; their cause is not established.', ...limitations] }
 }

package/lib/entity-copies.js

@@ -0,0 +1,59 @@
+import { BlenderError, BlenderErrorCode, sceneSpecDigest, sha256Canonical } from '@deepblend/dsh-blender-contracts'
+
+const validId = value => typeof value === 'string' && /^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/.test(value)
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+/** Expand bounded saved-data references into the ordinary atomic patch protocol. */
+export async function expandEntityCopies(studio, args) {
+  const invalid = message => { throw new BlenderError(BlenderErrorCode.SCENE_PATCH_INVALID, message) }
+  const offset = args.entityCopyOffset
+  if (offset !== undefined && (args.entityCopies === undefined || !Array.isArray(offset) || offset.length !== 3 ||
+      !offset.every(value => typeof value === 'number' && Number.isFinite(value)))) {
+    invalid('entityCopyOffset requires entityCopies and three finite world-metre translation components.')
+  }
+  if (args.entityCopies === undefined) return { operations: args.operations, copies: [] }
+  if (!Array.isArray(args.entityCopies) || args.entityCopies.length < 1 || args.entityCopies.length > 16) {
+    invalid('entityCopies must contain 1–16 explicit saved entity copies.')
+  }
+  if (args.operations.length + args.entityCopies.length > 500) invalid('Expanded patch exceeds the 500-operation limit.')
+  const ids = new Set()
+  for (const copy of args.entityCopies) {
+    if (!plain(copy) || Object.keys(copy).some(k => !['sourceEntityId', 'newEntityId', 'transform'].includes(k)) ||
+        !validId(copy.sourceEntityId) || !validId(copy.newEntityId) || ids.has(copy.newEntityId)) {
+      invalid('Each copy requires a saved sourceEntityId and distinct newEntityId; only transform may also be supplied.')
+    }
+    ids.add(copy.newEntityId)
+    if (offset !== undefined && copy.transform?.location !== undefined) invalid('entityCopyOffset cannot be combined with a copy absolute location override.')
+    if (copy.transform !== undefined && (!plain(copy.transform) || Object.keys(copy.transform).some(k =>
+      !['location', 'rotationEuler', 'scale'].includes(k) || !Array.isArray(copy.transform[k]) ||
+      copy.transform[k].length !== 3 || !copy.transform[k].every(v => typeof v === 'number' && Number.isFinite(v))))) {
+      invalid('Copy transform must contain only finite three-number location, rotationEuler or scale components.')
+    }
+  }
+  const data = await studio.getScene(args.projectId, { revision: args.baseRevision, full: true })
+  if (!data?.spec || !Array.isArray(data.spec.entities) || data.projectId !== args.projectId ||
+      data.revision !== args.baseRevision || data.digest !== sceneSpecDigest(data.spec)) {
+    throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'Host did not return the matching saved source revision for entity copies.')
+  }
+  const sources = new Map(data.spec.entities.map(entity => [entity.id, entity]))
+  const additions = [], copies = []
+  for (const copy of args.entityCopies) {
+    const source = sources.get(copy.sourceEntityId)
+    if (!source || sources.has(copy.newEntityId)) {
+      throw new BlenderError(BlenderErrorCode.SCENE_PATCH_REJECTED, 'Copy source must exist in baseRevision and newEntityId must not already exist.')
+    }
+    const entity = structuredClone(source)
+    entity.id = copy.newEntityId
+    if (copy.transform !== undefined) entity.transform = { ...entity.transform, ...structuredClone(copy.transform) }
+    if (offset !== undefined) {
+      const location = (source.transform?.location ?? [0, 0, 0]).map((value, index) => value + offset[index])
+      if (!location.every(Number.isFinite)) invalid('entityCopyOffset produced a non-finite position.')
+      entity.transform = { ...entity.transform, location }
+    }
+    additions.push({ op: 'entity.add', entity })
+    copies.push({ sourceRevision: data.revision, sourceDigest: data.digest, sourceEntityId: source.id,
+      sourceEntitySha256: sha256Canonical(source), newEntityId: entity.id })
+  }
+  // New entities are available to ordinary operations in this same atomic patch.
+  return { operations: [...additions, ...args.operations], copies }
+}

package/lib/scene-source.js

@@ -0,0 +1,36 @@
+import { BlenderError, BlenderErrorCode, sceneSpecDigest, sha256, sha256Canonical } from '@deepblend/dsh-blender-contracts'
+
+/** A bounded projection of saved entity data, never a filesystem reader. */
+export async function readEntitySource(studio, args) {
+  const invalid = message => { throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, message) }
+  if (typeof args.sourceEntityId !== 'string' || !/^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/.test(args.sourceEntityId)) {
+    invalid('sourceEntityId must be one saved entity ID (1–64 characters).')
+  }
+  const offset = args.sourceOffset === undefined ? 0 : args.sourceOffset
+  const limit = args.sourceLimit === undefined ? 2048 : args.sourceLimit
+  if (!Number.isSafeInteger(offset) || offset < 0) invalid('sourceOffset must be a non-negative safe integer.')
+  if (!Number.isInteger(limit) || limit < 1 || limit > 2048) invalid('sourceLimit must be an integer from 1 to 2048.')
+  if (offset > 0 && args.revision === undefined) invalid('Subsequent source chunks require the revision returned by the first chunk.')
+  if (args.full === true || Object.keys(args).some(key => key.startsWith('geometry') && args[key] !== undefined)) {
+    invalid('Entity source chunks cannot be combined with full:true or geometry options.')
+  }
+  const data = await studio.getScene(args.projectId, { ...(args.revision === undefined ? {} : { revision: args.revision }), full: true })
+  if (!data?.spec || !Array.isArray(data.spec.entities) || !/^r\d{4,}$/.test(data.revision ?? '') ||
+      data.projectId !== args.projectId || (args.revision !== undefined && data.revision !== args.revision) ||
+      data.digest !== sceneSpecDigest(data.spec)) {
+    throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'Host did not return a matching saved SceneSpec for bounded entity source reading.')
+  }
+  const matches = data.spec.entities.filter(entity => entity.id === args.sourceEntityId)
+  if (matches.length !== 1) invalid('sourceEntityId must identify exactly one entity in the selected saved revision.')
+  const source = JSON.stringify(matches[0])
+  if (offset > source.length) invalid('sourceOffset exceeds the entity source length.')
+  let end = Math.min(source.length, offset + limit)
+  // Escaped controls can cost six output characters each. Keep the rendered
+  // response safely below the preset's 8192-character spill threshold.
+  while (JSON.stringify(source.slice(offset, end)).length > 4096) end--
+  return { projectId: args.projectId, revision: data.revision, digest: data.digest, isCurrent: data.isCurrent,
+    documentSha256: sha256Canonical(data.spec), entityId: args.sourceEntityId, entityJsonSha256: sha256(source),
+    serialization: 'compact JSON; offsets are UTF-16 code units', totalChars: source.length,
+    sourceOffset: offset, sourceLength: end - offset, nextOffset: end < source.length ? end : null,
+    sourceText: source.slice(offset, end) }
+}

package/lib/tools.js

@@ -54,6 +54,8 @@ import {
   resolveStudio,
 } from './shared.js'
 import { compareSurfaceReports } from './geometry-comparison.js'
+import { readEntitySource } from './scene-source.js'
+import { expandEntityCopies } from './entity-copies.js'
 import { validateAssemblyPairs, readAssemblyOrigins, compareAssemblyOrigins, compareGeometryReports } from './assembly-origins.js'
 
 /** A short parameter description of a SceneSpec engine key. */
@@ -75,7 +77,12 @@ const SCENE_SPEC_PARAMETER = {
     'shots[], animationTracks[], renderProfiles{preview,final}. project.reviewSubjectId optionally selects an existing non-empty main review entity without moving cameras. ' +
     'A generator entity is `{id,type:"generator",generator:{shape,size|radius|depth|majorRadius|minorRadius,bevel?},' +
     'materialId,transform:{location,rotationEuler,scale}}` where shape is one of ' +
-    'cube, rounded_box, uv_sphere, cylinder, cone, plane, torus, lathe, curve, handled_cup. handled_cup builds one closed cup/handle mesh with flared shared-boundary roots. ' +
+    'cube, rounded_box, uv_sphere, cylinder, cone, plane, torus, lathe, curve, handled_cup, mesh. ' +
+    'Mesh builds authored control geometry from vertices:[[x,y,z],...] in object-local space and faces:[[vertexIndex,...],...] with 3-32 distinct in-range indices per face; winding is preserved. ' +
+    'Limits: 32768 vertices, 32768 faces, 131072 total face corners, coordinates within +/-1000000. ' +
+    'Optional faceUvs supplies one [u,v] pair per face corner; omitted uses planar UVs. smooth:true interpolates normals without changing geometry. ' +
+    'Use mesh for asymmetric surfaces; it accepts data only, no formulas/scripts. Validate and inspect actual geometry, normals and renders; valid indices do not certify appearance or manifold topology. ' +
+    'handled_cup builds one closed cup/handle mesh with flared shared-boundary roots. ' +
     'Defaults are radius 0.04, height 0.105, wallThickness 0.003, baseThickness 0.005; optional handleRadius, handleLower, handleUpper, rootRadius, rootLength and mesh segments obey coupled constraints. Inspect root highlights; mesh checks do not certify aesthetic quality. Curve sweeps a round section ' +
     'of radius (default 0.01) along path:[[x,y,z],…]; pathInterpolation is poly or bezier, pathClosed closes ' +
     'the loop, and capEnds seals open endpoints. Lathe uses profile:[[radius,height],…] ' +
@@ -83,7 +90,15 @@ const SCENE_SPEC_PARAMETER = {
     'sections. Use enough profile points to describe smooth shoulders and rounded lips; points form straight segments. ' +
     'Entity modifiers[] apply in order: {type:"solidify",thickness,offset?}, {type:"mirror",axis:"x"|"y"|"z",merge?}, ' +
     '{type:"array",count,offset:[x,y,z]}, {type:"boolean",operation:"union"|"difference"|"intersect",targetEntityId}, ' +
-    'or {type:"bevel",width,segments?,angle?,miterInner?:"arc"|"sharp"}. Place bevel after boolean to round its new edges; segments default 4, angle defaults 30 degrees, miterInner defaults arc for compatibility; sharp can avoid inner-corner artifacts around curved bores. ' +
+    '{type:"subdivision",levels:1|2|3,scheme?:"catmull-clark"|"simple",boundaryMode?:"all"|"preserve-corners"}, ' +
+    'or {type:"bevel",width,segments?,angle?,miterInner?:"arc"|"sharp"}. Subdivision defaults to catmull-clark/all; simple refines without rounding. ' +
+    'Static closed-surface placement: {type:"surface_scatter",targetEntityIds:[ids],count:1..512,anchorVertexIndices:[indices],seed?,embedDepthMm?,scaleRange?:[min,max],upwardBias?}. ' +
+    'This must be last. Prototype and 1–8 targets must be static generated single meshes without rigs/physics/transform animation. Targets must be closed solids. ' +
+    'Anchor indices select 1–8 actual prototype vertices AFTER preceding modifiers, not just generator control indices. Local +Z points out of the attachment. Every selected vertex of every instance must embed inside a target; insufficient placements fail atomically. ' +
+    'Defaults seed=0, embedDepthMm=5 (0..100 exclusive zero), scaleRange=[1,1] (0.05..20 ordered), upwardBias=0 (0..1). Placement is deterministic and recomputed on rebuild, not live binding; it does not certify whole-mesh clearance or appearance. ' +
+    'All modifiers are bounded to 500000 output polygons per entity, with subdivision refused before allocating an excessive result. ' +
+    'Array offsets are object-local and are scaled/rotated with the object; a world displacement must use the full inverse transform, not just divide by scale. ' +
+    'Place bevel after boolean to round its new edges; segments default 4, angle defaults 30 degrees, miterInner defaults arc for compatibility; sharp can avoid inner-corner artifacts around curved bores. ' +
     'Boolean operands must be separate single-mesh entities; visible:false hides an operand while preserving its geometry for the operation. ' +
     'Material parameters use Blender 5 socket ' +
     'names: baseColor [r,g,b,a], metallic, roughness, ior, alpha, emissionColor, emissionStrength, ' +
@@ -392,13 +407,15 @@ function sceneGet(ctx) {
       'location and visibility, camera parameters, animation tracks and the render profiles. That is ' +
       'usually everything you need to decide what to change. Pass full:true to also get the complete ' +
       'SceneSpec document, which you should do only when you actually need exact field values. ' +
+      'For exact control vertices or other entity fields in a large scene, use sourceEntityId instead: bounded compact JSON chunks avoid output spill. ' +
+      'Continue with the returned revision and nextOffset, check entityJsonSha256 stays identical, concatenate sourceText in order, then parse JSON. The preset does not provide a generic read tool. ' +
       'To measure saved native parts, pass geometryEntityIds (1–8 IDs from this scene) and an explicit geometryFrame. ' +
       'This returns source-verified world-axis spans in millimeters and transforms without rendering or creating a revision. ' +
       'Spans include rotation, handles and protrusions; they are not body diameter, wall thickness, clearance or quality approval. ' +
       'Do not subtract shell/liner spans or radii to claim a gap, or use unchanged height/scale to certify wall thickness. ' +
       'Optional geometrySurfaceSamples measures 1–8 explicit local surface chords and pair separations on the same saved source. ' +
       'The chord runs from source entry to exit; separation runs from source EXIT to target entry and excludes that chord. ' +
-      'Use geometryOnly:true for a compact verified measurement receipt without the scene catalogue. ' +
+      'Use geometryObjectAxes:true for measured scaled object-axis extents. Do not invert a world AABB into local dimensions. Use geometryOnly:true for a compact verified measurement receipt without the scene catalogue. ' +
       'Add geometryAssemblyPairs to measure explicit ordered object-origin offsets in world XYZ, not surface clearances. When comparing revisions, geometryCompareRevision computes current-minus-reference native spans and origin moves; if surface samples are supplied, their existing local comparison is used. ' +
       'Choose outside world seeds and directions from the actual scene/bounds; missed or unsupported samples remain unavailable. ' +
       'Local samples do not prove full-surface minimum wall thickness, whole-assembly clearance, no collision or quality approval. ' +
@@ -406,10 +423,14 @@ 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.' },
+      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.' },
       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.',
@@ -438,6 +459,12 @@ function sceneGet(ctx) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
       try {
+        if (args.sourceEntityId !== undefined || args.sourceOffset !== undefined || args.sourceLimit !== undefined) {
+          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.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') {
           throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryOnly must be boolean.')
         }
@@ -456,19 +483,19 @@ 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.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) })
+          frame: args.geometryFrame, checkpointSha256: '0'.repeat(64), ...(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.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) }, signal: exec?.signal }),
+            ...(args.geometryObjectAxes === true ? { objectAxes: true } : {}), ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) }, signal: exec?.signal }),
         }), warning)
-        const hasSamples = args.geometrySurfaceSamples !== undefined
+        const hasSamples = args.geometrySurfaceSamples !== undefined, hasObjectAxes = args.geometryObjectAxes === true
         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 !== (hasSamples ? 'deepblend.scene-geometry/v2' : 'deepblend.scene-geometry/v1') ||
+          if (args.geometryEntityIds !== undefined && (!data.geometryInspection || data.geometryInspection.schemaVersion !== (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) ||
@@ -476,16 +503,17 @@ 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: hasSamples ? 'deepblend.geometry-inspection/v2' : 'deepblend.geometry-inspection/v1',
+            schemaVersion: hasObjectAxes ? 'deepblend.geometry-inspection/v3' : hasSamples ? 'deepblend.geometry-inspection/v2' : 'deepblend.geometry-inspection/v1',
+            ...(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, ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) })
+            checkpointSha256: data.geometryInspection.sourceCheckpointSha256, ...(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, ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) }, signal: exec?.signal }), warning)
+            full: false, geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame, ...(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)
@@ -562,7 +590,7 @@ function sceneGet(ctx) {
     },
     presentCall: args => ({
       card: 'generic',
-      title: args?.full === true ? `Read full scene of "${args?.projectId ?? ''}"` : `Read scene of "${args?.projectId ?? ''}"`,
+      title: args?.sourceEntityId !== undefined ? `Read saved entity "${args.sourceEntityId}"` : args?.full === true ? `Read full scene of "${args?.projectId ?? ''}"` : `Read scene of "${args?.projectId ?? ''}"`,
       kind: 'read',
     }),
   })
@@ -617,6 +645,12 @@ 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' +
+      '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. ' +
+      'New IDs must be absent from the saved scene; sources must exist in baseRevision (not earlier copies in this request). Inspect real placement/contact and renders.\n\n' +
+      'entityCopyOffset:[dx,dy,dz] optionally translates all selected copies by the same world-metre offset, preserving their relative positions. ' +
+      'Do not combine it with any copy transform.location; rotation/scale overrides remain absolute per entity. References and unselected dependencies do not move automatically.\n\n' +
       'saveCheckpoint (default true) compiles this revision now. If false, the first preview compiles ' +
       'the revision lazily before rendering.\n\n' +
       'Operations (each object needs an "op" key):\n  ' + OPERATION_SUMMARY,
@@ -637,8 +671,19 @@ function scenePatch(ctx) {
         description:
           'Ordered list of operations. Each needs an "op" key naming the operation (see the tool description). ' +
           'Later operations see the result of earlier ones: remove or retarget every shot that uses a camera ' +
-          'before removing that camera.',
+          'before removing that camera. May be [] only when entityCopies supplies additions first.',
       },
+      entityCopies: { type: 'array', description: 'Optional 1–16 copies from baseRevision, expanded to entity.add before operations. Existing IDs cannot be overwritten; all non-transform entity details and references are preserved. No automatic assembly/animation copying or placement.',
+        items: { type: 'object', additionalProperties: false, properties: {
+          sourceEntityId: { type: 'string', required: true, description: 'Existing single entity in baseRevision.' },
+          newEntityId: { type: 'string', required: true, description: 'Distinct new entity ID, 1–64 characters.' },
+          transform: { type: 'object', additionalProperties: false, description: 'Optional absolute overrides; omitted components retain source values.', properties: {
+            location: { type: 'array', items: { type: 'number' } },
+            rotationEuler: { type: 'array', items: { type: 'number' } },
+            scale: { type: 'array', items: { type: 'number' } },
+          } },
+        } } },
+      entityCopyOffset: { type: 'array', items: { type: 'number' }, description: 'Optional common world translation [dx,dy,dz] in metres for entityCopies. Requires three finite numbers and entityCopies. Preserves selected source relative positions; cannot combine with any copy absolute transform.location. Does not move referenced/unselected objects or copy animations.' },
       note: {
         type: 'string',
         description:
@@ -672,7 +717,7 @@ function scenePatch(ctx) {
     async execute(args, exec) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
-      if (!Array.isArray(args.operations) || args.operations.length === 0) {
+      if (!Array.isArray(args.operations) || (args.operations.length === 0 && args.entityCopies === undefined)) {
         return {
           ok: false,
           text:
@@ -683,6 +728,7 @@ function scenePatch(ctx) {
         }
       }
       try {
+        const expanded = await expandEntityCopies(resolved.studio, args)
         // `definedFields` is load-bearing here, not tidiness: forwarding
         // `note: undefined` puts an own `note` key on the patch document, and the
         // host's schema validation rejects that as a wrong TYPE. A correct call
@@ -691,7 +737,7 @@ function scenePatch(ctx) {
           ...definedFields({
             projectId: args.projectId,
             baseRevision: args.baseRevision,
-            operations: args.operations,
+            operations: expanded.operations,
             note: args.note,
             actor: args.actor,
             stage: args.stage,
@@ -701,6 +747,8 @@ function scenePatch(ctx) {
           renderPreview: args.renderPreview === true,
           signal: exec.signal,
         }), warning)
+        if (expanded.copies.length) data.entityCopies = expanded.copies
+        if (args.entityCopyOffset !== undefined) data.entityCopyOffset = [...args.entityCopyOffset]
         const notes = [
           `Revision: ${describeRevision(data)}`,
           `Digest:   ${data.revision ? data.revision : data.digest}`,
@@ -742,7 +790,7 @@ function scenePatch(ctx) {
     },
     presentCall: args => ({
       card: 'generic',
-      title: `Patch scene of "${args?.projectId ?? ''}" (${Array.isArray(args?.operations) ? args.operations.length : 0} ops)`,
+      title: `Patch scene of "${args?.projectId ?? ''}" (${(Array.isArray(args?.operations) ? args.operations.length : 0) + (Array.isArray(args?.entityCopies) ? args.entityCopies.length : 0)} ops)`,
       kind: 'edit',
     }),
   })

package/lib/visual-tools.js

@@ -43,7 +43,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { attachVerifiedRenderedImage } from './committed-preview.js'
 import { imageForCallingModel } from './image-delivery.js'
 
-import { BlenderWarningCode, warning } from '@deepblend/dsh-blender-contracts'
+import { BlenderError, BlenderErrorCode, BlenderWarningCode, warning } from '@deepblend/dsh-blender-contracts'
 
 import {
   TOOL_OUTPUT,
@@ -64,6 +64,10 @@ const MEASUREMENT_GLOSSARY =
   'the way), its visible pixel count, the visible fraction (occlusion), its frame coverage, its bounding ' +
   'box and its centroid. These come from the rendered pixels, not from the SceneSpec.'
 
+const PREVIEW_FRAMING_GLOSSARY =
+  'frameBoundaryContacts names tracked silhouettes touching an image edge; that is a framing warning, ' +
+  'not proof of how much geometry lies outside. No contacts proves nothing about untracked parts.'
+
 /**
  * Register the M2 visual tools for the calling agent scope.
  *
@@ -91,10 +95,12 @@ function previewViews(ctx) {
       'the saved images, a verified contact sheet attached for the calling model, and per-view measurements. Rendering does NOT create a ' +
       'revision — a preview observes a scene rather than changing it — so this is always safe to call and ' +
       'never needs a baseRevision. Use it to look at a scene; use blender_visual_review when you also want a ' +
-      'score and a judgment.\n\n' + MEASUREMENT_GLOSSARY,
+      'score and a judgment.\n\n' + MEASUREMENT_GLOSSARY + '\n\n' + PREVIEW_FRAMING_GLOSSARY,
     parameters: {
       projectId: { type: 'string', required: true, description: 'The project id.' },
       revision: { type: 'string', description: 'Revision to render. Defaults to the current one.' },
+      subjectId: { type: 'string', description: 'Optional explicit entity to measure as the subject of this call (for example the cabinet shell instead of an automatically selected cable). Does not edit saved tags or the project subject.' },
+      track: { type: 'array', items: { type: 'string' }, description: 'Optional 1–8 distinct entity IDs to measure by pixel isolation; the selected subject is always included. These selected silhouettes are not whole-assembly framing certification.' },
       roles: {
         type: 'array',
         items: { type: 'string' },
@@ -120,10 +126,19 @@ function previewViews(ctx) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
       try {
+        if (args.subjectId !== undefined && (typeof args.subjectId !== 'string' || !args.subjectId.trim())) {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'subjectId must be a non-empty entity ID.')
+        }
+        if (args.track !== undefined && (!Array.isArray(args.track) || args.track.length < 1 || args.track.length > 8 ||
+            new Set(args.track).size !== args.track.length || args.track.some(id => typeof id !== 'string' || !id.trim()))) {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'track must contain 1–8 distinct non-empty entity IDs.')
+        }
         const { data, canonicalWarnings } = await canonicalCall(Promise.resolve(resolved.studio.renderViews({
           ...definedFields({
             projectId: args.projectId,
             revision: args.revision,
+            subjectId: args.subjectId,
+            track: args.track,
             roles: args.roles,
             frame: args.frame,
             width: args.width,
@@ -133,6 +148,20 @@ function previewViews(ctx) {
           signal: exec.signal,
         })).then(({ pngs, ...metadata }) => metadata), warning)
         const scored = resolved.studio.scoreVisualViews({ views: data.views, subjectId: data.subjectId })
+        // Isolation masks are clipped to the image. Edge contact cannot establish how
+        // much is missing, but must not disappear behind the primary subject's score.
+        const frameBoundaryContacts = []
+        for (const view of data.views ?? []) for (const object of view.metrics?.objects ?? []) {
+          const box = object.bbox
+          if (object.inFrame !== false || !(object.silhouettePixels > 0) || !Array.isArray(box) || box.length !== 4 ||
+              !box.every(n => Number.isFinite(n) && n >= 0 && n <= 1) || box[0] > box[2] || box[1] > box[3]) continue
+          const edges = [['left', box[0] === 0], ['top', box[1] === 0], ['right', box[2] === 1], ['bottom', box[3] === 1]]
+            .filter(([, touches]) => touches).map(([edge]) => edge)
+          if (edges.length) frameBoundaryContacts.push(definedFields({ viewId: view.viewId, cameraId: view.cameraId,
+            frame: view.frame, entityId: object.id, bbox: box, edges }))
+        }
+        const framingScope = 'Tracked isolated silhouettes at each returned camera/frame/resolution only. Edge contact means complete framing is unverified; no contacts cannot certify untracked parts, depth clipping, occlusion or aesthetic quality.'
+
         const notes = [
           `Revision: ${data.revision}`,
           `Subject:  ${data.subjectId ?? '(none tagged)'}`,
@@ -147,6 +176,11 @@ function previewViews(ctx) {
               `${view.width}x${view.height}) — ${view.purpose ?? ''}`,
           )
         }
+        notes.push('', 'Frame boundary contacts (including tracked objects other than the selected subject):')
+        for (const contact of frameBoundaryContacts) notes.push(
+          `  ${contact.viewId}: ${contact.entityId} touches ${contact.edges.join(', ')} — complete framing is unverified.`)
+        if (!frameBoundaryContacts.length) notes.push('  No reported edge contacts; this is not a complete assembly framing certificate.')
+        notes.push(framingScope)
         const sheet = (data.revisionPreviews ?? data.contactSheets ?? [])
         notes.push('')
         notes.push('The paths are relative to the project directory. The measured score is what the automated')
@@ -154,8 +188,8 @@ function previewViews(ctx) {
         notes.push('when you need a separate vision reviewer judgement, not just to obtain these images.')
         return await attachVerifiedRenderedImage(ctx, exec, resolved, {
           ok: true,
-          text: renderSuccess(`Rendered ${data.views.length} view(s) of ${data.revision}.`, { ...data, score: scored.score, issues: scored.issues }, { notes, warnings: [...(data.warnings ?? []), ...canonicalWarnings] }),
-          data: { ...data, score: scored.score, issues: scored.issues, sheet },
+          text: renderSuccess(`Rendered ${data.views.length} view(s) of ${data.revision}.`, { ...data, score: scored.score, issues: scored.issues, frameBoundaryContacts, framingScope }, { notes, warnings: [...(data.warnings ?? []), ...canonicalWarnings] }),
+          data: { ...data, score: scored.score, issues: scored.issues, frameBoundaryContacts, framingScope, sheet },
         }, { projectId: args.projectId, revision: data.revision, digest: data.digest,
           artifact: data.previewSheets?.current, kind: 'contact-sheet' })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-tool",
-  "version": "0.13.0",
+  "version": "0.14.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.13.0"
+    "@deepblend/dsh-blender-contracts": "0.14.0"
   },
   "license": "MIT",
   "repository": {