@deepblend/dsh-blender-contracts 0.2.20 → 0.3.1

package/lib/sdk.d.ts

@@ -0,0 +1,101 @@
+/** Node.js authoring SDK. Validate untrusted JSON; TypeScript cannot check semantic constraints. */
+import type {
+  SceneSpec, ScenePatch, ScenePatchOperation, SceneSpecSchema, RecipeManifest, RecipeCapability,
+  BlenderErrorCodeMap, BlenderWarningCodeMap, Material, AnimationTrack, ReferenceImage,
+} from './schema-types.js';
+export type * from './schema-types.js';
+export type * from './runtime-types.js';
+
+export const BLENDER_PROTOCOL_VERSION: 'deepblend.blender/v1';
+export const SCENE_SCHEMA_VERSION: 'deepblend.scene/v1';
+export const SCENE_PATCH_VERSION: 'deepblend.scene-patch/v1';
+export const HOST_API_VERSION: 6;
+export const BlenderErrorCode: Readonly<BlenderErrorCodeMap>;
+export const BlenderWarningCode: Readonly<BlenderWarningCodeMap>;
+export class BlenderError extends Error {
+  constructor(code: string, message: string, options?: { detail?: unknown; cause?: unknown });
+  code: string;
+  detail?: unknown;
+  toJSON(): { code: string; message: string; detail?: unknown };
+}
+export function isBlenderError(value: unknown): value is BlenderError;
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export function canonicalStringify(value: unknown): string | undefined;
+export function canonicalPretty(value: unknown, indent?: number): string | undefined;
+export function sha256(value: string | Uint8Array): string;
+export function sha256Canonical(value: unknown): string;
+export interface ValidationIssue { code: string; path: string; message: string }
+export interface SceneSpecIssue extends ValidationIssue { severity: 'error' | 'notice' }
+export interface ValidationResult<Issue = ValidationIssue> { ok: boolean; errors: Issue[]; summary: string }
+export interface SceneSpecValidation extends ValidationResult<SceneSpecIssue> { notices: 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 function compileSceneSpec(spec: SceneSpec): {
+  spec: SceneSpec; notices: SceneSpecIssue[];
+  entityBounds: Record<string, { location: number[]; radius: number }>;
+};
+export function sceneSpecCanonicalText(spec: SceneSpec): string;
+export function sceneSpecDigest(spec: SceneSpec): string;
+export function specHash(spec: SceneSpec): string;
+export function reviewInputsDigest(spec: SceneSpec): string;
+export interface SceneSummary {
+  revision: string | null; revisionNumber: number | null; digest: string; schemaVersion: SceneSpec['schemaVersion'];
+  project: {
+    id: string; title: string; goal: string | null; referenceImages: ReferenceImage[]; reviewSubjectId: string | null;
+    fps: number; frameStart: number; frameEnd: number; aspectRatio: string; units: 'metric' | 'imperial'; activeCamera: string | null;
+  };
+  counts: { assets: number; entities: number; materials: number; lights: number; cameras: number; shots: number; animationTracks: number };
+  entities: Array<{ id: string; type: SceneSpecSchema.Entity['type']; shape: SceneSpecSchema.Generator['shape'] | null;
+    materialId: string | null; materialBindings?: SceneSpecSchema.MaterialBindings; location: number[]; visible: boolean; locked: boolean; tags: string[] }>;
+  materials: Array<{ id: string; shader: Material['shader']; parameters: NonNullable<Material['parameters']>; tangent?: Material['tangent'] }>;
+  lights: Array<{ id: string; type: SceneSpecSchema.Light['type']; energy: number; location: number[] }>;
+  cameras: Array<{ id: string; role: SceneSpecSchema.Camera['role'] | null; lens: number; location: number[]; rotationEuler: number[];
+    targetEntityId: string | null; targetPoint: SceneSpecSchema.Vec3 | null }>;
+  shots: Array<{ id: string; cameraId: string; frameRange: [number, number]; description: string | null }>;
+  animationTracks: Array<{ id: string; targetKind?: AnimationTrack['targetKind']; targetEntityId: string;
+    property: AnimationTrack['property']; keyframeCount: number; frameRange: [number | null, number | null] }>;
+  renderProfiles: SceneSpec['renderProfiles'];
+  world: { declared: boolean; color: SceneSpecSchema.Vec3; strength: number; environment?: SceneSpecSchema.World['environment'] };
+  bounds: { min: number[]; max: number[] }; subjectBounds: { min: number[]; max: number[] } | null;
+}
+export function summarizeSceneSpec(spec: SceneSpec, context?: { revision?: string; revisionNumber?: number; digest?: string }): SceneSummary;
+export const SCENE_OPERATION_NAMES: ReadonlyArray<ScenePatchOperation['op']>;
+export function validateScenePatch(input: unknown): ValidationResult;
+export function parseScenePatch(input: unknown): ScenePatch;
+export interface AppliedOperation { op: ScenePatchOperation['op']; target: string; summary: string; changedPaths: string[] }
+export interface AppliedPatch {
+  spec: SceneSpec; operations: AppliedOperation[]; digestBefore: string; digestAfter: string; specHashBefore: string; specHashAfter: string;
+}
+/** Requires compiled input and a validated patch. Revalidate the resulting scene before use. */
+export function applyPatchToSpec(spec: SceneSpec, patch: ScenePatch): AppliedPatch;
+export interface OperationManifest {
+  schemaVersion: 'deepblend.operation-manifest/v1'; revision: string; baseRevision: string;
+  digestBefore: string; digestAfter: string; specHashBefore: string | null; specHashAfter: string | null;
+  sceneChanged: boolean; specChanged: boolean; idempotencyKey: string | undefined;
+  actor: string | null; stage: string | null; note: string | null; savedCheckpoint: boolean; renderedPreview: boolean;
+  operationCount: number; operations: AppliedOperation[]; notices: SceneSpecIssue[];
+}
+export function buildOperationManifest(input: {
+  operations: AppliedOperation[]; notices: SceneSpecIssue[]; request: ScenePatch;
+  revision: { revision: string; baseRevision: string; digestBefore: string; digestAfter: string; specHashBefore?: string; specHashAfter?: string };
+}): OperationManifest;
+export const RECIPE_SCHEMA_VERSION: 'deepblend.recipe/v1';
+export const RECIPE_CAPABILITIES: ReadonlyArray<RecipeCapability>;
+export const RECIPE_LIMITS: Readonly<{ sceneBytes: number; previewBytes: number; previewPixels: number }>;
+export class RecipeError extends Error {
+  constructor(code: string, message: string, details?: Record<string, unknown>);
+  code: string; details: Record<string, unknown>;
+}
+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 function recipeCapabilitiesForScene(spec: SceneSpec): RecipeCapability[];
+export function validateRecipeManifest(manifest: unknown, options?: RecipeOptions): RecipeValidation;
+export function parseRecipeManifest(manifest: unknown, options?: RecipeOptions): RecipeManifest;
+export function validateRecipePackage(bundle: unknown, options?: RecipeOptions): RecipeValidation;
+export function instantiateRecipe(bundle: RecipeBundle, values?: RecipeValues, options?: RecipeOptions): {
+  spec: SceneSpec; values: RecipeValues; notices: SceneSpecIssue[];
+  recipe: { id: string; version: string; manifestSha256: string; inputSha256: string; previewSha256: string; valuesSha256: string };
+};

package/lib/sdk.js

@@ -0,0 +1,41 @@
+/** Stable Node.js authoring entry point. Runtime ports are described in sdk.d.ts. */
+import { validateSceneSpec } from './scene-spec.js'
+import { validateScenePatch } from './scene-patch.js'
+import { BlenderError, BlenderErrorCode } from './index.js'
+import { validateRecipeManifest, RecipeError } from './recipe.js'
+
+export {
+  BLENDER_PROTOCOL_VERSION, SCENE_SCHEMA_VERSION, SCENE_PATCH_VERSION, HOST_API_VERSION,
+  BlenderError, BlenderErrorCode, BlenderWarningCode, isBlenderError,
+} from './index.js'
+export { canonicalStringify, canonicalPretty, sha256, sha256Canonical } from './canonical.js'
+export {
+  validateSceneSpec, compileSceneSpec, sceneSpecCanonicalText, sceneSpecDigest, specHash,
+  reviewInputsDigest, summarizeSceneSpec,
+} 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,
+} from './recipe.js'
+
+/** Validate untrusted JSON and return a separate document; never assert a type without checking it. */
+export function parseSceneSpec(input) {
+  const checked = validateSceneSpec(input)
+  if (!checked.ok) throw new BlenderError(BlenderErrorCode.SCENE_SPEC_INVALID, checked.summary, { detail: checked.errors })
+  return structuredClone(input)
+}
+
+/** Structural patch validation; entity references and final scene validity need a scene. */
+export function parseScenePatch(input) {
+  const checked = validateScenePatch(input)
+  if (!checked.ok) throw new BlenderError(BlenderErrorCode.SCENE_PATCH_INVALID, checked.summary, { detail: checked.errors })
+  return structuredClone(input)
+}
+
+/** Check a recipe manifest's declarations; package bytes are checked by validateRecipePackage. */
+export function parseRecipeManifest(input, options = {}) {
+  const checked = validateRecipeManifest(input, options)
+  if (!checked.ok) throw new RecipeError(checked.errors[0].code, checked.summary, { errors: checked.errors })
+  return structuredClone(input)
+}

package/lib/ui-api.js

@@ -20,6 +20,8 @@
 
 import { RENDER_JOB_TERMINAL_STATUSES } from './render-job.js'
 import { redactHome } from './redact.js'
+import { resolveSubject } from './visual-composition.js'
+import { resolveHandledCup } from './handled-cup.js'
 
 // ---------------------------------------------------------------------------
 // Routes
@@ -57,6 +59,8 @@ export const UI_ROUTES = Object.freeze([
   // (`contract/workbench-page.test.mjs` is what holds that).
   { id: 'workbench.page', method: 'GET', path: '/deepblend/workbench', write: false, summary: 'The standalone fullscreen workbench document.' },
   { id: 'state', method: 'GET', path: '/deepblend/state', write: false, summary: 'Everything the panel needs to render itself from scratch.' },
+  { id: 'recipes.list', method: 'GET', path: '/deepblend/recipes', write: false, summary: 'Validated local recipes and their editable parameters.' },
+  { id: 'recipes.preview', method: 'GET', path: '/deepblend/recipes/:recipeId/:version/preview', write: false, summary: 'A hash-pinned recipe preview.' },
   { id: 'projects.list', method: 'GET', path: '/deepblend/projects', write: false, summary: 'Every project in the store.' },
   { id: 'projects.create', method: 'POST', path: '/deepblend/projects', write: true, summary: 'Create a project (title, optional seed scene).' },
   { id: 'project.overview', method: 'GET', path: '/deepblend/projects/:projectId', write: false, summary: 'One project: summary, revisions, current digest.' },
@@ -67,8 +71,19 @@ export const UI_ROUTES = Object.freeze([
   { id: 'project.qa', method: 'GET', path: '/deepblend/projects/:projectId/qa', write: false, summary: 'The QA view of a revision (?revision=).' },
   { id: 'project.previews', method: 'GET', path: '/deepblend/projects/:projectId/previews', write: false, summary: 'Preview sets per revision, for Preview Compare.' },
   { id: 'project.preview', method: 'POST', path: '/deepblend/projects/:projectId/preview', write: true, summary: 'Render the low-cost multi-view preview (and its contact sheet).' },
+  { id: 'project.referenceImage.upload', method: 'POST', path: '/deepblend/projects/:projectId/reference-images', write: true, summary: 'Upload a PNG or JPEG as a project asset; saving the brief creates its revision reference.' },
+  { id: 'project.assets.list', method: 'GET', path: '/deepblend/projects/:projectId/assets', write: false, summary: 'List staged assets and the selected revision references, with current Host limits.' },
+  { id: 'project.assets.upload', method: 'POST', path: '/deepblend/projects/:projectId/assets', write: true, summary: 'Upload local asset bytes into project storage without creating a scene revision.' },
+  { id: 'project.assetUploads.create', method: 'POST', path: '/deepblend/projects/:projectId/asset-uploads', write: true, summary: 'Create a bounded model resource upload from a relative-path manifest.' },
+  { id: 'project.assetUploads.get', method: 'GET', path: '/deepblend/projects/:projectId/asset-uploads/:uploadId', write: false, summary: 'Read received bytes or recover a completed asset upload receipt.' },
+  { id: 'project.assetUploads.file', method: 'POST', path: '/deepblend/projects/:projectId/asset-uploads/:uploadId/files/:fileId', write: true, summary: 'Receive the original bytes of one declared upload member.' },
+  { id: 'project.assetUploads.complete', method: 'POST', path: '/deepblend/projects/:projectId/asset-uploads/:uploadId/complete', write: true, summary: 'Register a complete model resource bundle without changing the scene revision.' },
+  { id: 'project.assetUploads.cancel', method: 'POST', path: '/deepblend/projects/:projectId/asset-uploads/:uploadId/cancel', write: true, summary: 'Cancel private upload work, or return its already committed asset receipt.' },
+  { id: 'project.assets.preview', method: 'POST', path: '/deepblend/projects/:projectId/assets/:assetId/preview', write: true, summary: 'Inspect and preview one hash-pinned asset in isolation without changing the scene.' },
+  { 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.restore', method: 'POST', path: '/deepblend/projects/:projectId/restore', write: true, summary: 'Restore an earlier revision as a new 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.' },
   { id: 'project.job.cancel', method: 'POST', path: '/deepblend/projects/:projectId/jobs/:jobId/cancel', write: true, summary: 'Cancel a running job and verify the process is gone.' },
@@ -304,7 +319,7 @@ export function buildRevisionDiff(from, to, context = {}) {
  * human looking for a collection that does not exist in the outliner.
  *
  * @param {object} spec - a SceneSpec document
- * @param {{ revision?: string, digest?: string, compiled?: object|null }} [context]
+ * @param {{ revision?: string, digest?: string, compiled?: object|null, assetParts?: object[] }} [context]
  * @returns {Record<string, unknown>}
  */
 export function buildSceneTree(spec, context = {}) {
@@ -315,6 +330,9 @@ export function buildSceneTree(spec, context = {}) {
   const shots = spec?.shots ?? []
   const tracks = spec?.animationTracks ?? []
   const assets = spec?.assets ?? []
+  // Only the compiled revision knows imported part selectors and original slots.
+  // A spec alone cannot supply an inventory, even when it declares bindings.
+  const assetParts = context.assetParts ?? []
 
   /** @type {Record<string, unknown[]>} */
   const nodes = {
@@ -322,9 +340,15 @@ export function buildSceneTree(spec, context = {}) {
       id: entity.id,
       kind: entity.type,
       shape: entity.generator?.shape ?? null,
+      generator: clone(entity.generator?.shape === 'handled_cup'
+        ? resolveHandledCup(entity.generator) : entity.generator ?? null),
+      modifiers: clone(entity.modifiers ?? []),
       assetId: entity.assetId ?? null,
       materialId: entity.materialId ?? null,
-      tags: entity.tags ?? [],
+      materialBindings: clone(entity.materialBindings ?? []),
+      assetParts: clone(assetParts.filter(part => part.entityId === entity.id)),
+      visible: entity.visible ?? true,
+      tags: clone(entity.tags ?? []),
       locked: entity.locked === true,
       transform: clone(entity.transform ?? null),
       detail: entity.detail ?? null,
@@ -333,17 +357,20 @@ export function buildSceneTree(spec, context = {}) {
       id: material.id,
       shader: material.shader ?? null,
       parameters: clone(material.parameters ?? null),
+      definition: clone(material),
     })),
     lights: lights.map(light => ({
       id: light.id,
       type: light.type ?? null,
       energy: light.energy ?? null,
+      definition: clone(light),
       transform: clone(light.transform ?? null),
     })),
     cameras: cameras.map(camera => ({
       id: camera.id,
       role: camera.role ?? null,
       lens: camera.lens ?? null,
+      definition: clone(camera),
       targetEntityId: camera.targetEntityId ?? null,
       isActive: (spec?.project?.activeCamera ?? null) === camera.id,
     })),
@@ -367,12 +394,17 @@ export function buildSceneTree(spec, context = {}) {
     project: {
       id: spec?.project?.id ?? null,
       title: spec?.project?.title ?? null,
+      goal: spec?.project?.goal ?? '',
+      referenceImages: clone(spec?.project?.referenceImages ?? []),
+      reviewSubjectId: spec?.project?.reviewSubjectId ?? null,
       fps: spec?.project?.fps ?? null,
       frameStart: spec?.project?.frameStart ?? null,
       frameEnd: spec?.project?.frameEnd ?? null,
       activeCamera: spec?.project?.activeCamera ?? null,
     },
     world: clone(spec?.world ?? null),
+    reviewSubject: clone(resolveSubject(spec)),
+    assetParts: clone(assetParts),
     counts: {
       entities: nodes.entities.length,
       materials: nodes.materials.length,
@@ -440,8 +472,13 @@ export function buildQaView({ projectId, revision, validation = null, review = n
       available: review !== null,
       score: review?.score ?? null,
       pass: review?.pass ?? null,
+      artistic: clone(review?.referenceInputError ? { status: 'unassessable', dimensions: {} } : review?.artistic ?? { status: 'unassessable', dimensions: {} }),
+      referenceImages: clone(review?.referenceImages ?? []),
+      reviewInputsDigest: review?.reviewInputsDigest ?? null,
+      referenceInputError: clone(review?.referenceInputError ?? null),
       iteration: review?.iteration ?? null,
       subjectId: review?.subjectId ?? null,
+      subject: clone(review?.subject ?? null),
       viewCount: review?.viewCount ?? null,
       sheet: clone(review?.sheet ?? null),
       measuredIssueCount: measured.length,
@@ -539,6 +576,33 @@ export function buildJobView(job, options) {
     deliverable: job.status === 'completed' && job.delivery !== null,
     approval: buildApprovalView({ record: { expectedFrames: expected, warnings: job.warnings ?? [] }, threshold: options?.threshold ?? Number.POSITIVE_INFINITY }),
     detail: describeJobForHuman(job),
+    provenanceDisplay: describeFrameProvenance(job.provenance),
+  }
+}
+
+/** Bounded display facts from the same source summary; the client localizes labels. */
+function describeFrameProvenance(provenance) {
+  if (!provenance) return null
+  const groups = provenance.groups ?? []
+  const framesLabel = frames => {
+    const ranges = []
+    for (let i = 0; i < frames.length;) {
+      const start = frames[i]; let end = start
+      while (frames[++i] === end + 1) end = frames[i]
+      ranges.push(start === end ? String(start) : `${start}–${end}`)
+    }
+    return ranges.slice(0, 8).join(', ') + (ranges.length > 8 ? '…' : '')
+  }
+  return {
+    mixed: provenance.configuration === 'mixed',
+    uncheckedCount: provenance.uncheckedFrameCount ?? 0,
+    groups: groups.slice(0, 8).map(group => ({
+      engine: group.renderConfig.engine, resolution: group.renderConfig.resolution?.join('×'),
+      samples: group.renderConfig.samples, frames: framesLabel(group.frames), frameCount: group.frames.length,
+    })),
+    moreGroups: Math.max(0, groups.length - 8),
+    unknownCount: provenance.unknownFrameCount ?? provenance.unknownFrames?.length ?? 0,
+    missingCount: provenance.missingFrameCount ?? provenance.missingFrames?.length ?? 0,
   }
 }
 
@@ -849,6 +913,7 @@ export function parseToolCallTarget(argsRaw) {
  */
 export const UI_TOOL_CARD_KEYS = Object.freeze([
   'blender_capabilities',
+  'blender_recipe_list',
   'blender_project_create',
   'blender_project_get',
   'blender_scene_get',

package/lib/visual-composition.js

@@ -282,8 +282,8 @@ export function buildViewPlan(input) {
  *
  * The subject is always tracked. The others matter because occlusion is only
  * visible as a comparison: without a hiding object's own numbers, "the subject is
- * 40% hidden" says nothing about what to move. They are ranked by bounding-box
- * volume, which is a proxy for "big enough to hide something" and costs nothing to
+ * 40% hidden" says nothing about what to move. They are ranked by bounding
+ * radius, which is a proxy for "big enough to hide something" and costs nothing to
  * compute — the alternative, tracking everything, would multiply the render count
  * of every view.
  *
@@ -293,7 +293,7 @@ export function buildViewPlan(input) {
  */
 export function trackedObjects(spec, subjectId) {
   const entities = Array.isArray(spec?.entities) ? spec.entities : []
-  // Every declared PART is tracked regardless of size. The volume ranking below is a
+  // Every declared PART is tracked regardless of size. The radius ranking below is a
   // guess about what might hide the subject; a declaration is not a guess, and a small
   // component that is missing is exactly the defect that a size ranking would skip.
   const declared = subjectParts(spec)
@@ -349,21 +349,35 @@ export function subjectParts(spec) {
  * The rule now has a stated order of evidence, and every step of it is a fact about
  * the file rather than a fact about the alphabet:
  *
- *   1. what the ACTIVE camera aims at — a camera exists to frame something, and
+ *   1. the explicitly saved project.reviewSubjectId, even if it is unavailable;
+ *   2. otherwise what the ACTIVE camera aims at — a camera exists to frame something, and
  *      `targetEntityId` is the author saying what;
- *   2. a `hero-product` tag when exactly one entity carries it;
- *   3. among several, the largest by volume, ties broken by id;
- *   4. with no tag at all, the largest visible entity, ties broken by id.
+ *   3. entities tagged `hero-product`, then entities tagged `subject`;
+ *   4. among several in the chosen tag group, the largest bounding radius,
+ *      ties broken by id;
+ *   5. with neither tag, the largest visible non-environment entity.
  *
- * Step 3 is deliberately "largest" rather than "first": a scene that tags four things
+ * Step 4 is deliberately "largest" rather than "first": a scene that tags four things
  * hero is ambiguous, and the biggest of them is the only defensible reading.
  *
  * @param {object} spec
- * @returns {{ id: string|null, source: string, candidates: string[] }}
+ * @returns {{ id: string|null, source: string, candidates: string[], mode: 'explicit'|'automatic', available: boolean, reason: string|null }}
  */
 export function resolveSubject(spec) {
   const entities = Array.isArray(spec?.entities) ? spec.entities : []
   const visible = entities.filter(entity => entity.visible !== false)
+  const result = (id, source, candidates, mode = 'automatic') => {
+    const entity = entities.find(entry => entry.id === id)
+    const reason = id === null ? 'No review subject is available.'
+      : !entity ? `Review subject "${id}" does not exist in this revision.`
+        : entity.type === 'empty' ? `Review subject "${id}" is an empty and cannot be measured.`
+          : entity.visible === false ? `Review subject "${id}" is hidden in this revision.` : null
+    return { id, source, candidates, mode, available: reason === null, reason }
+  }
+  if (spec?.project?.reviewSubjectId !== undefined) {
+    const id = spec.project.reviewSubjectId
+    return result(id, 'it is the explicitly saved review subject', [id], 'explicit')
+  }
 
   // 1. What the shot is actually framed on.
   const cameras = Array.isArray(spec?.cameras) ? spec.cameras : []
@@ -372,33 +386,33 @@ export function resolveSubject(spec) {
   if (active?.targetEntityId !== undefined) {
     const aimed = visible.find(entity => entity.id === active.targetEntityId)
     if (aimed !== undefined) {
-      return { id: aimed.id, source: `the active camera "${active.id}" aims at it`, candidates: [aimed.id] }
+      return result(aimed.id, `the active camera "${active.id}" aims at it`, [aimed.id])
     }
   }
 
-  const tagged = visible.filter(entity => Array.isArray(entity.tags) && entity.tags.includes('hero-product'))
+  const hero = visible.filter(entity => (entity.tags ?? []).includes('hero-product'))
+  const tag = hero.length > 0 ? 'hero-product' : 'subject'
+  const tagged = hero.length > 0 ? hero : visible.filter(entity => (entity.tags ?? []).includes('subject'))
   if (tagged.length === 1) {
-    return { id: tagged[0].id, source: 'it is the only entity tagged hero-product', candidates: [tagged[0].id] }
+    return result(tagged[0].id, `it is the only entity tagged ${tag}`, [tagged[0].id])
   }
 
-  const pool = tagged.length > 1 ? tagged : visible.filter(entity => entityExtent(entity) > 0)
-  if (pool.length === 0) return { id: null, source: 'this scene has no entity to be the subject of', candidates: [] }
+  const pool = tagged.length > 1 ? tagged : visible.filter(entity =>
+    !(entity.tags ?? []).includes('environment') && entityExtent(entity) > 0)
+  if (pool.length === 0) return result(null, 'this scene has no visible non-environment subject candidate', [])
 
-  // Descending volume, and the id only breaks exact ties — so two entities of equal
+  // Descending bounding radius, and the id only breaks exact ties — so two entities of equal
   // size resolve the same way on every machine and after every re-sort.
   const ranked = [...pool].sort((left, right) => {
-    const byVolume = entityExtent(right) - entityExtent(left)
-    if (byVolume !== 0) return byVolume
+    const byExtent = entityExtent(right) - entityExtent(left)
+    if (byExtent !== 0) return byExtent
     return left.id < right.id ? -1 : left.id > right.id ? 1 : 0
   })
   const candidates = ranked.map(entity => entity.id)
-  return {
-    id: ranked[0].id,
-    source: tagged.length > 1
-      ? `${tagged.length} entities are tagged hero-product, so the largest was taken; the ambiguity is reported`
-      : 'it is the largest visible entity and nothing is tagged hero-product',
-    candidates,
-  }
+  return result(ranked[0].id, tagged.length > 1
+      ? `${tagged.length} entities are tagged ${tag}, so the largest was taken; the ambiguity is reported`
+      : 'it is the largest visible non-environment entity and nothing is tagged hero-product or subject',
+    candidates)
 }
 
 /**

package/lib/visual-issue.js

@@ -87,8 +87,8 @@ export const VISUAL_SEVERITIES = Object.freeze(['minor', 'major', 'critical'])
 const SEVERITY_POINTS = Object.freeze({ minor: 4, major: 10, critical: 18 })
 
 /**
- * A perfect score. Below this the automated loop has something to fix; at or above
- * it the loop hands over instead of pretending there is work (see `shouldHandOver`).
+ * Technical passing threshold. Artistic quality is assessed separately; reaching
+ * this value does not establish that the work meets its visual goal.
  */
 export const VISUAL_PASS_SCORE = 90
 
@@ -216,7 +216,7 @@ export function scoreView(view, options = {}) {
   if (exposure !== null) add(exposure)
 
   for (const object of subjects) {
-    const composition = assessComposition(object)
+    const composition = assessComposition(object, options.subjectId)
     if (composition !== null) add(composition)
     const occlusion = assessOcclusion(object)
     if (occlusion !== null) add(occlusion)
@@ -412,9 +412,26 @@ function assessExposure(metrics, viewId, subject = null) {
  * Where the subject sits in the frame, and how big it is.
  *
  * @param {object} object - one object entry from the view's measurements.
+ * @param {string|null} subjectId - the selected primary subject, when supplied.
  * @returns {VisualIssue|null}
  */
-function assessComposition(object) {
+function assessComposition(object, subjectId) {
+  // No isolated silhouette is different from a silhouette hidden by another object.
+  // Require the provider's complete zero/out-of-frame reading rather than treating
+  // omitted legacy measurements or a tiny positive silhouette as proof of absence.
+  // A component may legitimately face away in this view; its presence is assessed
+  // across views below, unless the user explicitly selected that component itself.
+  if (object.silhouettePixels === 0 && object.visiblePixels === 0 && object.inFrame === false &&
+    (!isSubjectPart(object) || object.id === subjectId)) {
+    return buildIssue({
+      category: 'composition', code: 'SUBJECT_OUT_OF_FRAME', severity: 'critical',
+      viewId: object.viewId, objectId: object.id,
+      evidence: `"${object.id}" has no isolated silhouette in this view: silhouettePixels=0, ` +
+        'visiblePixels=0 and inFrame=false. The subject is absent from the measured frame, so its framing cannot pass.',
+      measurements: { silhouettePixels: 0, visiblePixels: 0, inFrame: 'false' },
+      buckets: ['absent'],
+    })
+  }
   if (object.visiblePixels === 0) return null // fully hidden is an occlusion finding
   const centroid = object.centroid
   if (!Array.isArray(centroid) || centroid.length !== 2) return null
@@ -642,7 +659,7 @@ export function validateFindings(raw, context) {
       continue
     }
     const category = entry.category
-    if (!VISUAL_ISSUE_CATEGORIES.includes(category)) {
+    if (![...VISUAL_ISSUE_CATEGORIES, 'geometry', 'materials', 'lighting', 'goalFit'].includes(category)) {
       rejected.push({ finding: entry, reason: `unknown category "${String(category)}"` })
       continue
     }
@@ -687,13 +704,14 @@ export function validateFindings(raw, context) {
  * Three ways to stop, and each one exists because the alternative is a loop that
  * spends money to make things worse:
  *
- *  - the score is already passing — there is no measured problem to improve;
+ *  - both the technical score and the separate artistic review pass;
  *  - the iteration cap is reached (SPEC §12.3 "达到最大迭代数后进入人工审查");
  *  - the same fingerprint has repeated `stopOnRepeatedIssueCount` times, which is
  *    the structural form of "同一问题两轮未改善则停止自动迭代".
  *
  * @param {object} input
  * @param {number} input.score
+ * @param {boolean} input.artisticPassed
  * @param {number} input.iteration
  * @param {number} input.maxIterations
  * @param {Map<string, number>} input.fingerprints - fingerprint -> consecutive count
@@ -701,8 +719,8 @@ export function validateFindings(raw, context) {
  * @returns {{ stop: boolean, reason: string|null }}
  */
 export function shouldHandOver(input) {
-  if (input.score >= VISUAL_PASS_SCORE) {
-    return { stop: true, reason: 'PASSING_SCORE' }
+  if (input.score >= VISUAL_PASS_SCORE && input.artisticPassed === true) {
+    return { stop: true, reason: 'PASSING_REVIEW' }
   }
   if (input.iteration >= input.maxIterations) {
     return { stop: true, reason: 'MAX_ITERATIONS' }