@deepblend/dsh-blender-contracts 0.2.20 → 0.3.1

package/lib/runtime-types.d.ts

@@ -0,0 +1,208 @@
+/** The current Host-facing execution seam; no process or service is created by this type module. */
+import type { Buffer } from 'node:buffer';
+import type { RenderProfile, Vec3 } from './schema-types.js';
+import type { BlenderError } from './sdk.js';
+
+export type EngineKey = RenderProfile['engine'];
+export interface RuntimeWarning { code: string; message: string; detail?: unknown }
+export interface BlenderExecutableReport { requested: string; resolved: string | null; found: boolean; advice?: string | null }
+export interface BlenderEngineProbe { assignable: boolean; readback: string | null; error: string | null }
+export interface BlenderGpuBackend { supported: boolean; gpuDevices: string[]; cpuDevices: string[]; error: string | null }
+export interface BlenderGpuReport {
+  availableBackends: string[]; preferredBackend: string | null; gpuDeviceNames: string[]; cpuDeviceNames: string[];
+  backendSupport: Record<string, BlenderGpuBackend>;
+}
+export interface BlenderRenderSmokeTest { attempted: boolean; engine: string | null; ok: boolean; bytes: number; error: string | null }
+export interface BlenderCapabilities {
+  protocolVersion: string; installed: boolean; executable: BlenderExecutableReport;
+  blenderVersion: string | null; blenderVersionTuple: number[] | null; pythonVersion: string | null;
+  buildHash: string | null; binaryPath: string | null; renderEngines: Record<string, BlenderEngineProbe>;
+  bestAvailableEngine: string | null; renderEngineEnumItems: string[]; gpu: BlenderGpuReport; gpuAvailable: boolean;
+  exportFormats: string[]; importFormats: string[]; unavailableFormats: string[];
+  renderSmokeTest: BlenderRenderSmokeTest | null; cyclesSmokeTest: BlenderRenderSmokeTest | null;
+  textBlockApi: boolean; frameApi: boolean; hostPlatform: string | null; warnings: RuntimeWarning[];
+  probedAt: number; durationMs: number; commandLine: string | null;
+}
+export interface BlenderBootstrapRequest { action: string; payload?: Record<string, unknown>; jobId?: string }
+export interface BlenderBootstrapEnvelope<Result = Record<string, unknown>> {
+  protocolVersion: string; jobId: string | null; action: string; status: 'success' | 'error';
+  capabilities: Record<string, unknown> | null; result: Result | null;
+  error: { code: string; message: string; detail?: unknown } | null;
+  warnings: RuntimeWarning[]; notices: RuntimeWarning[];
+}
+export interface RuntimeOptions { signal?: AbortSignal }
+export interface WorkingDirectory<Result = Record<string, unknown>> {
+  directory: string; envelope: BlenderBootstrapEnvelope<Result>; jobId: string | undefined;
+}
+export interface BootstrapWorkingDirectory extends WorkingDirectory { requestPath: string; resultPath: string }
+export type WorkingDirectoryCallback<Result = Record<string, unknown>> = (info: WorkingDirectory<Result>) => void | Promise<void>;
+export interface MaterialSlot { index: number; materialName: string | null; materialId?: string | null; usedPolygonCount?: number }
+export interface ImageFacts { width: number; height: number; channels: number; isFloat: boolean; colorSpace: string }
+export interface UvMapFacts<Source extends 'mesh-data' | 'evaluated-mesh'> {
+  name: string; activeRender: boolean; loopCount: number; finite: boolean; source: Source;
+}
+export interface CompiledObject {
+  name: string; type: string; deepblendId?: string | null; partId?: string; parentPartId?: string | null;
+  materialSlots?: MaterialSlot[]; sourceMaterialSlots?: Array<{ index: number; materialName: string | null }>;
+  worldBounds?: { min: Vec3; max: Vec3 } | null; boundsFrame?: number; renderVisible?: boolean;
+  uvMaps?: Array<UvMapFacts<'mesh-data'>>; evaluatedUvMaps?: Array<UvMapFacts<'evaluated-mesh'>> | null;
+  boundsUnavailable?: 'viewport-disabled' | 'empty-or-invalid-bounds'; evaluatedUvMapsUnavailable?: 'viewport-disabled';
+  [key: string]: unknown;
+}
+/** Blender's measured configuration; additional measured fields may be added. */
+export interface MeasuredRenderConfig {
+  engine: string; resolution: number[]; samples: number | null;
+  exposure?: number; viewTransform?: string; look?: string; gamma?: number;
+  [key: string]: unknown;
+}
+export interface CompileReport {
+  validation: { ok: boolean; errors: unknown[]; [key: string]: unknown };
+  sceneFingerprint: { totalPolygons: number; [key: string]: unknown };
+  objects?: CompiledObject[]; renderConfig?: MeasuredRenderConfig;
+  world?: { declared: boolean; color: number[]; strength: number;
+    environment?: { assetId: string; rotation?: number; image: ImageFacts; [key: string]: unknown }; [key: string]: unknown };
+  [key: string]: unknown;
+}
+export interface PreviewReport {
+  outputPath: string; bytes: number; width: number; height: number; frame: number; engine: string; cameraId: string;
+  fps?: number; frameStart?: number; frameEnd?: number; cameraName?: string; lens?: number;
+  renderConfig?: MeasuredRenderConfig; objects?: CompiledObject[]; [key: string]: unknown;
+}
+export interface RuntimeActionResult<Report> {
+  report: Report; envelope: BlenderBootstrapEnvelope<Report>; durationMs: number; stdout: string; stderr: string;
+}
+export interface CompileSceneRequest extends RuntimeOptions {
+  sceneSpecPath: string; projectRoot?: string; profile?: string; jobId?: string;
+  /** false runs a separate batch process, preserving a user's live Blender session. */
+  session?: boolean;
+  /** Copy or move result.blend before resolving; never retain a scratch path as a durable artifact. */
+  onWorkingDirectory?: WorkingDirectoryCallback<CompileReport>;
+}
+export interface RenderOverrides { engine?: EngineKey; width?: number; height?: number; samples?: number }
+export interface RenderPreviewRequest extends RuntimeOptions, RenderOverrides {
+  checkpointPath: string; outputPath: string; cameraId?: string; frame?: number; jobId?: string;
+  session?: boolean;
+  onWorkingDirectory?: (info: BootstrapWorkingDirectory) => void | Promise<void>;
+}
+export interface RenderView { id: string; role?: string | null; cameraId?: string; frame?: number }
+export interface ObjectMeasurement {
+  id: string; viewId: string; visiblePixels: number; silhouettePixels: number; visibleFraction: number;
+  occludedFraction: number; frameCoverage: number; silhouetteCoverage: number; inFrame: boolean;
+  bbox: unknown; centroid: unknown; occludedBy: unknown[]; part: boolean; [key: string]: unknown;
+}
+export interface ViewReport {
+  viewId: string; role: string | null; outputPath: string; bytes: number; width: number; height: number;
+  frame: number; cameraId: string; cameraName: string; lens: number; engine: string;
+  metrics: { width: number; height: number; objects: ObjectMeasurement[]; luminance: Record<string, unknown> };
+  /** Measured for this frame before diagnostic mask renders. */
+  renderConfig?: MeasuredRenderConfig;
+  cameraFacts?: MeasuredCameraFacts;
+}
+export interface MeasuredCameraFacts {
+  frame: number; matrixWorld: number[][]; type: 'PERSP' | 'ORTHO' | 'PANO'; lens: number; orthoScale: number;
+  sensorWidth: number; sensorHeight: number; sensorFit: string; shift: number[]; clip: number[];
+  dof: { enabled: boolean; focusDistance: number; focusObject: { name: string; entityId: string | null; matrixWorld: number[][] } | null;
+    focusSubtarget: string | null; apertureFstop: number; apertureBlades: number; apertureRotation: number; apertureRatio: number };
+}
+export interface ViewsReport { views: ViewReport[]; renderConfig?: MeasuredRenderConfig; objects?: CompiledObject[]; [key: string]: unknown }
+export interface RenderViewsRequest extends RuntimeOptions, RenderOverrides {
+  checkpointPath: string; views: RenderView[]; track?: string[]; parts?: string[]; jobId?: string;
+  /** false isolates both rendering and measurements from a user's live session. */
+  session?: boolean;
+}
+export interface RenderViewsResult {
+  report: ViewsReport; pngs: Record<string, Buffer>; envelope: BlenderBootstrapEnvelope<ViewsReport>; durationMs: number;
+}
+export interface CollectedOutputReader {
+  readFrom(fromByte: number): { text: string; nextOffset: number; lossy: boolean; spillPath?: string };
+}
+/** Host-required subset of the DSH subprocess handle; implementations may expose additional fields. */
+export interface FrameSequenceHandle {
+  readonly done: Promise<{ exitCode: number | null; signal: string | null }>;
+  readonly collected?: { readonly stdout?: CollectedOutputReader; readonly stderr?: CollectedOutputReader };
+  /** Synchronous, idempotent initiation of managed process termination. Await done afterwards. */
+  terminate(): void;
+  waitForExit?(signal?: AbortSignal): Promise<boolean>;
+}
+export interface FrameSequenceRequest extends RuntimeOptions {
+  checkpointPath: string; frames: number[]; jobDirectory: string; cameraId?: string; profileName?: string;
+  profile?: RenderProfile; frameRange?: [number, number]; jobId?: string; attemptToken?: string;
+  filePrefix?: string; padding?: number;
+}
+export interface FrameSequenceRun {
+  handle: FrameSequenceHandle; jobDirectory: string; framesDirectory: string; requestPath: string; planPath: string;
+  resultPath: string; eventsPath: string; processPath: string; argv: string[]; startedAt: number;
+  attemptToken: string | null; executable: string;
+}
+/** Optional fsynced journal extension for attribution; omitted evidence stays unknown. */
+export interface FrameConfiguredEvent {
+  type: 'render_config'; attemptToken: string; renderConfig: MeasuredRenderConfig;
+}
+export interface FrameWrittenEvent {
+  type: 'frame'; frame: number; bytes: number; ms: number;
+  /** The matching configured event must precede this completion record. */
+  attemptToken: string;
+  /** SHA256 of the complete PNG bytes after structural verification. */
+  sha256: string;
+}
+export type FrameProvenanceEvent = FrameConfiguredEvent | FrameWrittenEvent;
+/** Configuration read back by the renderer, with the launch identity that requested it. */
+export interface FrameRenderSource {
+  id: string; attempt: number; revisionId: string; cameraId: string | null; checkpointSha256: string | null;
+  requestedSamples: number | null; effectiveProfile: RenderProfile; renderConfig: MeasuredRenderConfig;
+}
+export interface FrameSourceBinding { frame: number; sourceId: string; sha256: string }
+/** Shared by canonical jobs and delivery manifests; known means configuration/PNG evidence, not per-pixel samples. */
+export interface FrameProvenanceSummary {
+  schemaVersion: 'deepblend.frame-sources/v1';
+  coverage: 'complete' | 'partial' | 'unknown'; configuration: 'uniform' | 'mixed' | 'unknown';
+  groups: Array<{ renderConfig: MeasuredRenderConfig; frames: number[]; sourceIds: string[] }>;
+  sources: FrameRenderSource[]; frames: FrameSourceBinding[]; unknownFrames: number[]; missingFrames: number[];
+  knownFrameCount: number; unknownFrameCount: number; missingFrameCount: number;
+  /** A bounded read/metadata limit deferred attribution; omitted frames are not called missing or corrupt. */
+  limited?: true;
+  limitation?: 'status-budget' | 'frame-limit' | 'source-byte-limit' | 'journal-byte-limit' | 'journal-line-limit';
+  uncheckedFrameCount?: number;
+}
+
+export interface FrameSequenceOutcome {
+  /** Parsed but not yet validated. The Host checks protocol, completion and durable frame evidence. */
+  envelope: unknown; stdout: string; stderr: string; exitCode: number | null; signal: string | null;
+  durationMs: number; spawnFailure: unknown;
+}
+export interface EngineResolution { blenderEngine: string | null; requested: string | null; downgraded: boolean; warning: RuntimeWarning | null }
+/** Required execution methods used by the current Host; see docs/public-api.md for lifecycle requirements. */
+export interface BlenderRuntime {
+  getCapabilities(options?: RuntimeOptions & { refresh?: boolean }): Promise<BlenderCapabilities>;
+  invalidateCapabilities(): void;
+  resolveEngineKey(engineKey: EngineKey, options?: RuntimeOptions): Promise<EngineResolution>;
+  compileScene(request: CompileSceneRequest): Promise<RuntimeActionResult<CompileReport>>;
+  renderPreview(request: RenderPreviewRequest): Promise<RuntimeActionResult<PreviewReport>>;
+  renderViews(request: RenderViewsRequest): Promise<RenderViewsResult>;
+  startFrameSequence(request: FrameSequenceRequest): Promise<FrameSequenceRun>;
+  awaitFrameSequence(run: FrameSequenceRun): Promise<FrameSequenceOutcome>;
+  dispose(): void;
+}
+export interface BootstrapOptions extends RuntimeOptions {
+  session?: boolean; args?: string[]; cwd?: string; projectRoot?: string;
+  prepareDirectory?: (info: { directory: string; jobId: string }) => void | Promise<void>;
+  onWorkingDirectory?: (info: BootstrapWorkingDirectory) => void | Promise<void>;
+}
+export interface BootstrapRunOutcome {
+  envelope: BlenderBootstrapEnvelope; stdout: string; stderr: string; exitCode: number | null; durationMs: number;
+  /** Present for batch runs; it usually names an already removed directory. */
+  workingDirectory?: string | null;
+}
+export interface BlenderSession {
+  readonly pid: number | null; readonly workspace: string | null;
+  run(request: BlenderBootstrapRequest & { args?: string[] }, options?: RuntimeOptions): Promise<BlenderBootstrapEnvelope>;
+  close(): Promise<void>;
+}
+/** Optional local transport extensions. Remote runtimes need only implement BlenderRuntime. */
+export interface LocalBlenderRuntime extends BlenderRuntime {
+  runBootstrap(request: BlenderBootstrapRequest, options?: BootstrapOptions): Promise<BootstrapRunOutcome>;
+  openSession(options?: RuntimeOptions & { cwd?: string; args?: string[] }): Promise<BlenderSession>;
+  attachSession(socketPath: string, options?: { timeoutMs?: number }): Promise<BlenderSession>;
+  closeSession(): Promise<void>;
+  resolveBlenderExecutable(options?: RuntimeOptions): Promise<{ requested: string; resolved: string | null; error: BlenderError | null; advice?: string }>;
+}

package/lib/scene-patch.js

@@ -18,6 +18,7 @@
 
 import { compileSchema, formatIssues } from './json-schema.js'
 import { collectionForKind, sceneSpecDigest, specHash } from './scene-spec.js'
+import { referenceImageIssues } from './reference-images.js'
 import scenePatchSchema from './schemas/scene-patch.schema.json' with { type: 'json' }
 
 const validatePatchStructure = compileSchema(scenePatchSchema, { id: 'scene-patch.schema.json' })
@@ -53,6 +54,13 @@ export const SCENE_OPERATION_NAMES = Object.freeze([
   // accepted `material.texture.set` while this list (and therefore the manual and the tool's description) still
   // had 23 names, which `scene-patch.test.mjs`'s schema-vs-constant check is the only check able to see.
   'material.texture.set',
+  'entity.generator.set',
+  'entity.modifiers.set',
+  'material.images.set',
+  'entity.materialBindings.set',
+  'material.tangent.set',
+  'project.brief.set',
+  'project.reviewSubject.set',
 ])
 
 /** The `id` grammar shared with SceneSpec. */const ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9._-]*$/
@@ -105,6 +113,12 @@ export function validateScenePatch(patch) {
     const at = `operations[${position}]`
     const op = operation.op
 
+    if (op === 'project.brief.set') {
+      for (const issue of referenceImageIssues(operation.referenceImages)) {
+        errors.push({ code: 'PATCH_OPERATION_INVALID', path: `${at}.referenceImages${issue.path}`, message: issue.message })
+      }
+    }
+
     if (op === 'entity.transform.update') {
       const supplied = ['location', 'rotationEuler', 'scale'].filter(key => operation[key] !== undefined)
       if (supplied.length === 0) {
@@ -149,6 +163,11 @@ export function validateScenePatch(patch) {
         })
       }
     }
+    if (op === 'material.parameter.update' && ['anisotropic', 'anisotropicRotation'].includes(operation.parameter) &&
+        (!Number.isFinite(operation.value) || operation.value < 0 || operation.value > 1)) {
+      errors.push({ code: 'PATCH_OPERATION_INVALID', path: `${at}.value`,
+        message: `${operation.parameter} must be a finite scalar in [0, 1]` })
+    }
     for (const key of ['entityId', 'materialId', 'lightId', 'cameraId', 'trackId', 'shotId']) {
       const value = operation[key]
       if (typeof value === 'string' && !ID_PATTERN.test(value)) {
@@ -402,6 +421,51 @@ export function applyPatchToSpec(spec, patch) {
         break
       }
 
+      case 'entity.materialBindings.set': {
+        const at = indexOfId(next.entities, operation.entityId)
+        if (at < 0) fail('PATCH_TARGET_MISSING', `no entity "${operation.entityId}" exists in this scene`)
+        const entity = next.entities[at]
+        if (entity.type !== 'asset-instance') fail('PATCH_OPERATION_INVALID', `${op} requires an asset-instance entity`)
+        const selectors = new Set()
+        for (const binding of operation.materialBindings) {
+          if (indexOfId(next.materials, binding.materialId) < 0) fail('PATCH_REFERENCE_MISSING', `no material "${binding.materialId}" exists`)
+          const key = JSON.stringify([binding.partId, binding.slotIndex ?? null])
+          if (selectors.has(key)) fail('PATCH_OPERATION_INVALID', 'duplicate part and slot material binding')
+          selectors.add(key)
+        }
+        const changed = JSON.stringify(entity.materialBindings ?? []) !== JSON.stringify(operation.materialBindings)
+        if (changed) {
+          const updated = { ...entity, materialBindings: structuredClone(operation.materialBindings) }
+          if (!updated.materialBindings.length) delete updated.materialBindings
+          next.entities[at] = updated
+        }
+        applied.push({ op, target: entity.id, summary: `set material bindings on entity "${entity.id}"`,
+          changedPaths: changed ? [`entities.${entity.id}.materialBindings`] : [] })
+        break
+      }
+
+      case 'entity.generator.set':
+      case 'entity.modifiers.set': {
+        const at = indexOfId(next.entities, operation.entityId)
+        if (at < 0) fail('PATCH_TARGET_MISSING', `no entity "${operation.entityId}" exists in this scene`)
+        const entity = next.entities[at]
+        const field = op === 'entity.generator.set' ? 'generator' : 'modifiers'
+        if ((field === 'generator' && entity.type !== 'generator') || entity.type === 'empty') {
+          fail('PATCH_OPERATION_INVALID', `${op} cannot edit a ${entity.type} entity`)
+        }
+        const before = entity[field] ?? (field === 'modifiers' ? [] : undefined)
+        const value = structuredClone(operation[field])
+        const changed = JSON.stringify(before) !== JSON.stringify(value)
+        if (changed) {
+          const updated = { ...entity, [field]: value }
+          if (field === 'modifiers' && value.length === 0) delete updated.modifiers
+          next.entities[at] = updated
+        }
+        applied.push({ op, target: entity.id, summary: `set ${field} on entity "${entity.id}"`,
+          changedPaths: changed ? [`entities.${entity.id}.${field}`] : [] })
+        break
+      }
+
       case 'entity.add': {
         if (indexOfId(next.entities, operation.entity.id) >= 0) {
           fail('PATCH_TARGET_EXISTS', `entity "${operation.entity.id}" already exists; use entity.transform.update instead`)
@@ -428,6 +492,11 @@ export function applyPatchToSpec(spec, patch) {
           fail('PATCH_TARGET_MISSING', `no entity "${operation.entityId}" exists in this scene`)
         }
         const dependents = []
+        if (next.project.reviewSubjectId === operation.entityId) dependents.push('review subject')
+        if (next.entities.some(entity => (entity.modifiers ?? []).some(modifier =>
+          modifier.type === 'boolean' && modifier.targetEntityId === operation.entityId))) {
+          dependents.push('boolean operand')
+        }
         if (next.cameras.some(camera => camera.targetEntityId === operation.entityId)) {
           dependents.push('camera target')
         }
@@ -516,6 +585,34 @@ export function applyPatchToSpec(spec, patch) {
         break
       }
 
+      case 'material.tangent.set': {
+        const at = indexOfId(next.materials, operation.materialId)
+        if (at < 0) fail('PATCH_TARGET_MISSING', `no material "${operation.materialId}" exists in this scene`)
+        const material = { ...next.materials[at] }
+        if (operation.tangent === null) delete material.tangent
+        else material.tangent = structuredClone(operation.tangent)
+        next.materials = [...next.materials]
+        next.materials[at] = material
+        applied.push({ op, target: material.id, summary: `set anisotropic tangent on material "${material.id}"`,
+          changedPaths: [`materials.${material.id}.tangent`] })
+        break
+      }
+
+      case 'material.images.set': {
+        const at = indexOfId(next.materials, operation.materialId)
+        if (at < 0) fail('PATCH_TARGET_MISSING', `no material "${operation.materialId}" exists in this scene`)
+        const material = { ...next.materials[at] }
+        for (const binding of Object.values(operation.images ?? {})) {
+          if (indexOfId(next.assets, binding.assetId) < 0) fail('PATCH_REFERENCE_MISSING', `no image asset "${binding.assetId}" exists`)
+        }
+        if (operation.images === null) delete material.images
+        else material.images = structuredClone(operation.images)
+        next.materials[at] = material
+        applied.push({ op, target: material.id, summary: `set image maps on material "${material.id}"`,
+          changedPaths: [`materials.${material.id}.images`] })
+        break
+      }
+
       case 'material.texture.set': {
         const at = indexOfId(next.materials, operation.materialId)
         if (at < 0) fail('PATCH_TARGET_MISSING', `no material "${operation.materialId}" exists in this scene`)
@@ -758,6 +855,29 @@ export function applyPatchToSpec(spec, patch) {
       }
 
       // ---- project and profiles -------------------------------------------
+      case 'project.reviewSubject.set': {
+        const entity = next.entities.find(entry => entry.id === operation.entityId)
+        if (operation.entityId !== null && !entity) fail('PATCH_REFERENCE_MISSING', `review subject "${operation.entityId}" does not exist`)
+        if (entity?.type === 'empty') fail('PATCH_OPERATION_INVALID', 'The review subject must be a renderable entity, not an empty.')
+        const project = { ...next.project }
+        if (operation.entityId === null) delete project.reviewSubjectId
+        else project.reviewSubjectId = operation.entityId
+        next = { ...next, project }
+        applied.push({ op, target: project.id,
+          summary: operation.entityId === null ? 'restored automatic review subject selection' : `set review subject to "${operation.entityId}"`,
+          changedPaths: ['project.reviewSubjectId'] })
+        break
+      }
+      case 'project.brief.set': {
+        const issues = referenceImageIssues(operation.referenceImages, next.assets ?? [])
+        if (issues.length > 0) fail(issues[0].code === 'SCENE_REFERENCE_MISSING'
+          ? 'PATCH_REFERENCE_MISSING' : 'PATCH_OPERATION_INVALID', issues[0].message)
+        next = { ...next, project: { ...next.project, goal: operation.goal,
+          referenceImages: structuredClone(operation.referenceImages) } }
+        applied.push({ op, target: next.project.id, summary: 'replaced the authored goal and visual references',
+          changedPaths: ['project.goal', 'project.referenceImages'] })
+        break
+      }
       case 'project.frameRange.set': {
         if (operation.frameEnd <= operation.frameStart) {
           fail('PATCH_FRAME_RANGE_INVALID', `frameEnd (${operation.frameEnd}) must be greater than frameStart (${operation.frameStart})`)
@@ -817,6 +937,9 @@ export function applyPatchToSpec(spec, patch) {
       }
 
       case 'world.set': {
+        if (operation.world.environment && indexOfId(next.assets, operation.world.environment.assetId) < 0) {
+          fail('PATCH_REFERENCE_MISSING', `no environment asset "${operation.world.environment.assetId}" exists`)
+        }
         // The world REPLACES rather than merges, matching how a caller thinks about
         // "make the background black": a half-updated world is how the hidden grey
         // constant survived this long in the first place.
@@ -869,6 +992,12 @@ export function applyPatchToSpec(spec, patch) {
       }
 
       case 'asset.remove': {
+        if ((next.project.referenceImages ?? []).some(reference => reference.assetId === operation.assetId)) {
+          fail('PATCH_TARGET_IN_USE', `asset "${operation.assetId}" is still used by project.referenceImages`)
+        }
+        if (next.world?.environment?.assetId === operation.assetId) {
+          fail('PATCH_TARGET_IN_USE', `asset "${operation.assetId}" is still used by world.environment`)
+        }
         if (indexOfId(next.assets, operation.assetId) < 0) {
           fail('PATCH_TARGET_MISSING', `no asset "${operation.assetId}" exists in this scene`)
         }
@@ -876,6 +1005,9 @@ export function applyPatchToSpec(spec, patch) {
         // instantiates this asset would be left pointing at nothing, and the compiler
         // would then refuse a scene the patch claimed to have produced.
         const dependents = next.entities.filter(entity => entity.assetId === operation.assetId)
+        if ((next.materials ?? []).some(material => Object.values(material.images ?? {}).some(binding => binding.assetId === operation.assetId))) {
+          fail('PATCH_TARGET_IN_USE', `asset "${operation.assetId}" is still referenced by material image maps`)
+        }
         if (dependents.length > 0) {
           fail(
             'PATCH_TARGET_IN_USE',
@@ -929,7 +1061,7 @@ export function buildOperationManifest({ operations, request, revision, notices
     specHashBefore: revision.specHashBefore ?? null,
     specHashAfter: revision.specHashAfter ?? null,
     // Two different questions, two different answers. `sceneChanged` excludes
-    // project.title/goal by design (see sceneSpecDigest); `specChanged` covers the
+    // project metadata and brief by design (see sceneSpecDigest); `specChanged` covers the
     // whole document, so the frame range counts.
     sceneChanged: revision.digestBefore !== revision.digestAfter,
     specChanged: (revision.specHashBefore ?? null) !== null