@deepblend/dsh-blender-contracts 0.2.19 → 0.3.0

package/lib/artistic-review.js

@@ -0,0 +1,57 @@
+/** Model judgments stay separate from deterministic render measurements. */
+export const ARTISTIC_DIMENSIONS = Object.freeze(['geometry', 'materials', 'lighting', 'goalFit'])
+
+/** Validate evidence, confidence and the Host's actual reference image inventory.
+ * Passing must account for every reference for that dimension; one evidenced
+ * mismatch suffices for needs_work. Old callers without references remain valid.
+ */
+export function validateArtisticReview(raw, viewIds, minConfidence = 0.8, context = {}) {
+  const dimensions = {}
+  const problems = []
+  const subjectUnavailable = context.subject?.available === false
+  if (subjectUnavailable) problems.push(context.subject.reason ?? 'The review subject is unavailable.')
+  // This is the Host's actual attachment inventory, not a list proposed by the model.
+  const references = new Map((context.referenceImages ?? []).map(reference => [reference.id, reference]))
+  const referenceEvidenceValid = (entry, dimension) => {
+    const relevant = [...references.values()].filter(reference => reference.purposes?.includes(dimension))
+    const ids = entry?.referenceIds
+    if (ids === undefined) return relevant.length === 0 || entry?.status === 'unassessable'
+    if (!Array.isArray(ids) || new Set(ids).size !== ids.length || !ids.every(id =>
+      typeof id === 'string' && references.get(id)?.purposes?.includes(dimension))) return false
+    if (entry?.status === 'unassessable' || relevant.length === 0) return true
+    return entry?.status === 'pass' ? relevant.every(reference => ids.includes(reference.id)) : ids.length > 0
+  }
+  const evidenceValid = entry => entry && viewIds.has(entry.viewId) &&
+    typeof entry.evidence === 'string' && entry.evidence.trim().length >= 8 &&
+    entry.evidence.length <= 2000 && Number.isFinite(entry.confidence) &&
+    entry.confidence >= minConfidence && entry.confidence <= 1
+  for (const dimension of ARTISTIC_DIMENSIONS) {
+    const entry = raw?.dimensions?.[dimension]
+    const validReferences = referenceEvidenceValid(entry, dimension)
+    const valid = evidenceValid(entry) && validReferences && ['pass', 'needs_work', 'unassessable'].includes(entry.status)
+    if (!valid) problems.push(`${dimension}: ${validReferences ? 'missing, invalid or insufficiently confident evidence' : 'missing, unknown or inapplicable referenceIds'}`)
+    dimensions[dimension] = valid && !(subjectUnavailable && entry.status === 'pass') ? {
+      status: entry.status, viewId: entry.viewId, evidence: entry.evidence.trim(), confidence: entry.confidence,
+      ...(entry.referenceIds === undefined ? {} : { referenceIds: [...entry.referenceIds] }),
+    } : { status: 'unassessable', viewId: null, evidence: null, confidence: null }
+  }
+  const comparison = raw?.comparison
+  const validComparison = evidenceValid(comparison) && ['improved', 'equivalent', 'regressed', 'unassessable'].includes(comparison.verdict)
+  const statuses = Object.values(dimensions).map(entry => entry.status)
+  return {
+    status: statuses.every(status => status === 'pass') ? 'pass'
+      : statuses.includes('needs_work') ? 'needs_work' : 'unassessable',
+    dimensions,
+    comparison: validComparison && !subjectUnavailable ? {
+      verdict: comparison.verdict, viewId: comparison.viewId,
+      evidence: comparison.evidence.trim(), confidence: comparison.confidence,
+    } : { verdict: 'unassessable', viewId: null, evidence: null, confidence: null },
+    problems,
+  }
+}
+
+/** A newly failing dimension cannot be hidden by an optimistic overall comparison. */
+export function artisticRegressed(before, after) {
+  return after.comparison.verdict === 'regressed' || ARTISTIC_DIMENSIONS.some(dimension =>
+    before.dimensions[dimension].status === 'pass' && after.dimensions[dimension].status === 'needs_work')
+}

package/lib/asset-content.js

@@ -49,8 +49,11 @@ const SIGNATURES = Object.freeze([
   // Everything else that is common enough to name, all of it a contradiction for any of the
   // six importable types.
   { format: null, magic: 'PK\u0003\u0004', at: 0, label: 'a ZIP archive' },
-  { format: null, magic: '\u0089PNG\r\n\u001a\n', at: 0, label: 'a PNG image' },
-  { format: null, magic: '\u00ff\u00d8\u00ff', at: 0, label: 'a JPEG image' },
+  { format: 'png', magic: '\u0089PNG\r\n\u001a\n', at: 0, label: 'a PNG image' },
+  { format: 'jpg', magic: '\u00ff\u00d8\u00ff', at: 0, label: 'a JPEG image' },
+  { format: 'hdr', magic: '#?RADIANCE', at: 0, label: 'a Radiance HDR image' },
+  { format: 'hdr', magic: '#?RGBE', at: 0, label: 'a Radiance HDR image' },
+  { format: 'exr', magic: '\u0076\u002f\u0031\u0001', at: 0, label: 'an OpenEXR image' },
   { format: null, magic: '%PDF', at: 0, label: 'a PDF' },
   { format: null, magic: '\u007fELF', at: 0, label: 'an ELF binary' },
   { format: null, magic: 'MZ', at: 0, label: 'a Windows executable' },
@@ -124,7 +127,7 @@ export function assetContentVerdict(head, type) {
     // for another importable type, which is how a `.obj` holding a `.blend` reads, and
     // including for a format this product cannot import at all, which is how a ZIP named
     // `.glb` reads.
-    return described.signature.format === type ? 'agrees' : 'contradicts'
+    return described.signature.format === (type === 'jpeg' ? 'jpg' : type) ? 'agrees' : 'contradicts'
   }
   // No signature. Text formats are satisfied by text; a binary format is not satisfied by
   // anything (its magic was required and did not match), but it is not contradicted either,

package/lib/handled-cup.js

@@ -0,0 +1,55 @@
+/** Dimensions are local scene units; mesh validity is checked again in Blender. */
+export const HANDLED_CUP_FIELDS = ['height', 'wallThickness', 'baseThickness', 'footRound', 'handleRadius',
+  'handleLower', 'handleUpper', 'rootRadius', 'rootLength', 'rootTension', 'sectionSegments', 'handleSegments', 'rootSegments', 'wallRows']
+
+export function resolveHandledCup(spec = {}) {
+  const radius = spec.radius ?? .04
+  const height = spec.height ?? radius * 2.625
+  const wallThickness = spec.wallThickness ?? radius * .075
+  const baseThickness = spec.baseThickness ?? radius * .125
+  return { ...spec, radius, height, wallThickness, baseThickness,
+    footRound: spec.footRound ?? Math.min(wallThickness, baseThickness * .8),
+    handleRadius: spec.handleRadius ?? radius * .1375,
+    handleLower: spec.handleLower ?? height * (4 / 15),
+    handleUpper: spec.handleUpper ?? height * (26 / 35),
+    rootRadius: spec.rootRadius ?? radius * .2625, rootLength: spec.rootLength ?? radius * .2,
+    rootTension: spec.rootTension ?? 1,
+    segments: spec.segments ?? 192, sectionSegments: spec.sectionSegments ?? 96,
+    handleSegments: spec.handleSegments ?? 96, rootSegments: spec.rootSegments ?? 32, wallRows: spec.wallRows ?? 40 }
+}
+
+export function handledCupIssues(spec) {
+  const inputFields = ['radius', 'segments', ...HANDLED_CUP_FIELDS]
+  for (const key of inputFields) if (spec[key] !== undefined &&
+      (typeof spec[key] !== 'number' || !Number.isFinite(spec[key]) || spec[key] <= 0)) {
+    return [`${key} must be a finite positive number`]
+  }
+  const p = resolveHandledCup(spec)
+  const errors = []
+  const within = (value, low, high) => value >= low - 1e-12 && value <= high + 1e-12
+  const ratios = [
+    ['radius', p.radius, .02, .08], ['height/radius', p.height / p.radius, 1.8, 4],
+    ['wallThickness/radius', p.wallThickness / p.radius, .025, .15],
+    ['baseThickness/radius', p.baseThickness / p.radius, .05, .25],
+    ['handleRadius/radius', p.handleRadius / p.radius, .05, .2],
+    ['rootRadius/radius', p.rootRadius / p.radius, .12, .35],
+    ['rootRadius/handleRadius', p.rootRadius / p.handleRadius, 1.4, 3],
+    ['rootLength/rootRadius', p.rootLength / p.rootRadius, .4, 1.2],
+    ['footRound/radius', p.footRound / p.radius, .01, .15],
+  ]
+  for (const [name, value, low, high] of ratios) if (!Number.isFinite(value) || !within(value, low, high)) {
+    errors.push(`${name} must be within ${low}–${high}`)
+  }
+  if (p.rootTension < 1 || p.rootTension > 2.5) errors.push('rootTension must be within 1–2.5')
+  const gap = (p.handleUpper - p.handleLower) / 2
+  if (gap <= 0 || p.rootLength / gap > .8 + 1e-12) errors.push('handleUpper must exceed handleLower; rootLength/half-gap must be <=0.8')
+  if (gap + p.radius * 1e-12 < Math.max(1.1 * p.rootRadius, 2 * p.handleRadius)) errors.push('attachment half-gap must be >=1.1*rootRadius and >=2*handleRadius')
+  if (p.handleLower - p.rootRadius + p.radius * 1e-12 < p.footRound + .01 * p.radius) errors.push('lower root footprint must clear the rounded foot by 0.01*radius')
+  if (p.handleUpper + p.rootRadius > p.height - p.wallThickness / 2 - .01 * p.radius + p.radius * 1e-12) errors.push('upper root footprint must clear the rounded lip by 0.01*radius')
+  for (const [key, low, high, multiple] of [['segments',64,256,4], ['sectionSegments',32,96,4],
+    ['handleSegments',24,128,4], ['rootSegments',8,48,1], ['wallRows',16,64,1]]) {
+    if (!Number.isInteger(p[key]) || p[key] < low || p[key] > high || p[key] % multiple) errors.push(`${key} must be an integer within ${low}–${high}, divisible by ${multiple}`)
+  }
+  if (p.footRound > Math.min(p.wallThickness, p.baseThickness * .8) + p.radius * 1e-12) errors.push('footRound must not exceed wallThickness or 0.8*baseThickness')
+  return errors
+}

package/lib/index.js

@@ -374,9 +374,11 @@ export const BlenderWarningCode = Object.freeze({
  * before. 3 is M3 (the persistent render job). 4 is M4, which added the UI plane's
  * read/aggregate methods — the browser half faces the same half-upgraded deployment
  * the tools do, and it has to say so instead of painting a blank panel over a
- * `TypeError` (D59).
+ * `TypeError` (D59). 5 adds the asset library's upload, inventory and isolated
+ * preview methods; an older Host cannot serve that UI workflow. 6 adds isolated
+ * beauty/clay diagnostics; an older Host must not silently ignore that mode.
  */
-export const HOST_API_VERSION = 4
+export const HOST_API_VERSION = 6
 
 /** Formats the product intends to support (SPEC §2.2). Used to emit warnings. */
 export const EXPECTED_IMPORT_FORMATS = Object.freeze(['gltf', 'fbx', 'obj', 'usd'])
@@ -528,14 +530,19 @@ export function warning(code, message, detail) {
  * They hold NO business state machine — orchestration belongs to
  * `BlenderOrchestrator` and persistence to the project/revision stores.
  *
- * M0 implements `getCapabilities` and the shared `runBootstrap` transport.
- * The remaining methods are declared here as the frozen target shape and are
- * implemented in M1+. Calling an unimplemented one throws
- * `BlenderErrorCode.UNSUPPORTED_ACTION`, never silently succeeds.
+ * The complete, current Host-facing interface and optional local transport
+ * extensions are exported as TypeScript types from the public `/sdk` entry.
+ * See `deepblend/docs/public-api.md` for cancellation and artifact ownership.
  *
  * @typedef {object} BlenderRuntime
- * @property {(signal?: AbortSignal) => Promise<BlenderCapabilities>} getCapabilities
- * @property {(request: BlenderBootstrapRequest, options?: { signal?: AbortSignal }) => Promise<BlenderBootstrapEnvelope>} runBootstrap
+ * @property {(options?: {refresh?: boolean, signal?: AbortSignal}) => Promise<BlenderCapabilities>} getCapabilities
+ * @property {() => void} invalidateCapabilities
+ * @property {import('./runtime-types.js').BlenderRuntime['resolveEngineKey']} resolveEngineKey
+ * @property {import('./runtime-types.js').BlenderRuntime['compileScene']} compileScene
+ * @property {import('./runtime-types.js').BlenderRuntime['renderPreview']} renderPreview
+ * @property {import('./runtime-types.js').BlenderRuntime['renderViews']} renderViews
+ * @property {import('./runtime-types.js').BlenderRuntime['startFrameSequence']} startFrameSequence
+ * @property {import('./runtime-types.js').BlenderRuntime['awaitFrameSequence']} awaitFrameSequence
  * @property {() => void} dispose
  */
 
@@ -553,17 +560,20 @@ export function warning(code, message, detail) {
  * @property {'success'|'error'} status
  * @property {string} protocolVersion
  * @property {string|null} jobId
- * @property {BlenderCapabilities|null} capabilities
- * @property {{ code: string, message: string }|null} error
- * @property {string[]} warnings
+ * @property {string} action
+ * @property {Record<string, unknown>|null} capabilities - raw probe; normalized by getCapabilities.
+ * @property {Record<string, unknown>|null} result
+ * @property {{ code: string, message: string, detail?: unknown }|null} error
+ * @property {{code: string, message: string, detail?: unknown}[]} warnings
+ * @property {{code: string, message: string, detail?: unknown}[]} notices
  */
 
 /**
  * The model- and UI-facing business facade (SPEC §7.2).
  *
- * M0 implements `getCapabilities` only. Everything else is the frozen M1+ target
- * and throws `UNSUPPORTED_ACTION` until implemented, so the model can never
- * believe a not-yet-built capability worked.
+ * The Host implements project/revision transactions, reviews, assets and render
+ * jobs. This historical typedef is a minimal view, not the full facade contract;
+ * the SDK's BlenderRuntime types describe the separate execution seam.
  *
  * @typedef {object} BlenderStudio
  * @property {(request?: { refresh?: boolean }) => Promise<BlenderCapabilities>} getCapabilities
@@ -676,12 +686,15 @@ export {
   SCENE_ENGINES,
   BLENDER_ENGINE_BY_KEY,
   IMPORT_OPERATOR_BY_ASSET_TYPE,
+  IMAGE_ASSET_TYPES,
+  ENVIRONMENT_ASSET_TYPES,
   validateSceneSpec,
   compileSceneSpec,
   entityBoundingRadius,
   sceneProjection,
   sceneSpecDigest,
   specHash,
+  reviewInputsDigest,
   summarizeSceneSpec,
   sceneSpecCanonicalText,
 } from './scene-spec.js'
@@ -760,6 +773,8 @@ export {
   runVisualLoop,
 } from './visual-loop.js'
 
+export { ARTISTIC_DIMENSIONS, validateArtisticReview, artisticRegressed } from './artistic-review.js'
+
 // ---------------------------------------------------------------------------
 // M3 surface
 //
@@ -852,3 +867,5 @@ export {
   resolveProjectsRoot,
   managedBlenderCandidates,
 } from './deployment-paths.js'
+
+export { RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError, recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe } from './recipe.js'

package/lib/recipe.js

@@ -0,0 +1,253 @@
+/** Portable data recipes. No filesystem, network, dynamic imports or code execution. */
+import { inflateSync } from 'node:zlib'
+import { sha256, sha256Canonical } from './canonical.js'
+import { compileSchema } from './json-schema.js'
+import { decodePng } from './png.js'
+import { validateSceneSpec, compileSceneSpec } from './scene-spec.js'
+import recipeSchema from './schemas/recipe.schema.json' with { type: 'json' }
+
+export const RECIPE_SCHEMA_VERSION = 'deepblend.recipe/v1'
+export const RECIPE_CAPABILITIES = Object.freeze([
+  'geometry.primitive', 'geometry.lathe', 'geometry.curve', 'geometry.handled_cup', 'geometry.handled_cup.tension', 'geometry.handled_cup.tension.extended', 'geometry.modifiers',
+  'material.principled', 'material.glass', 'material.emission', 'material.procedural', 'material.procedural.uv', 'material.anisotropy',
+  'animation.transform', 'animation.material',
+])
+export const RECIPE_LIMITS = Object.freeze({ sceneBytes: 2 * 1024 * 1024, previewBytes: 4 * 1024 * 1024, previewPixels: 4 * 1024 * 1024 })
+const structural = compileSchema(recipeSchema, { id: 'recipe.schema.json' })
+const RESERVED = new Set(['__proto__', 'prototype', 'constructor'])
+const plain = value => value !== null && typeof value === 'object' &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+const issue = (code, path, message) => ({ code, path, message })
+const result = (errors, extra = {}) => ({ ok: errors.length === 0, errors, notices: [],
+  summary: errors.length ? errors.map(error => `${error.path}: ${error.message}`).join('; ') : 'Recipe valid', ...extra })
+
+export class RecipeError extends Error {
+  constructor(code, message, details = {}) {
+    super(message); this.name = 'RecipeError'; this.code = code; this.details = details
+  }
+}
+
+/** Capabilities describe what the input actually uses, rather than its author's claims. */
+export function recipeCapabilitiesForScene(spec) {
+  const used = new Set()
+  for (const entity of spec.entities ?? []) {
+    if (entity.type === 'generator') used.add(['lathe', 'curve', 'handled_cup'].includes(entity.generator.shape)
+      ? `geometry.${entity.generator.shape}` : 'geometry.primitive')
+    if (entity.modifiers?.length || entity.generator?.bevel) used.add('geometry.modifiers')
+    if (entity.generator?.shape === 'handled_cup' && (entity.generator.rootTension ?? 1) !== 1) used.add('geometry.handled_cup.tension')
+    if (entity.generator?.shape === 'handled_cup' && (entity.generator.rootTension ?? 1) > 1.5) used.add('geometry.handled_cup.tension.extended')
+  }
+  for (const material of spec.materials ?? []) {
+    used.add(`material.${material.shader}`)
+    if (material.texture) used.add('material.procedural')
+    if (material.texture?.coordinates === 'uv') used.add('material.procedural.uv')
+    if (material.tangent !== undefined || material.parameters?.anisotropic !== undefined || material.parameters?.anisotropicRotation !== undefined) used.add('material.anisotropy')
+  }
+  for (const track of spec.animationTracks ?? []) {
+    used.add(track.targetKind === 'material' ? 'animation.material' : 'animation.transform')
+    if (track.targetKind === 'material' && ['anisotropic', 'anisotropicRotation'].includes(track.property)) used.add('material.anisotropy')
+  }
+  return [...used].sort()
+}
+
+function parameterValueIssue(parameter, value, path) {
+  if (parameter.type === 'color') {
+    if (!Array.isArray(value) || value.length !== 3 || Array.from(value).some(channel => !Number.isFinite(channel) || channel < 0 || channel > 1)) {
+      return issue('RECIPE_PARAMETER_INVALID', path, 'Expected three scene-linear RGB channels in [0, 1]')
+    }
+  } else if (!Number.isFinite(value) || value < parameter.minimum || value > parameter.maximum) {
+    return issue('RECIPE_PARAMETER_INVALID', path, `Expected a finite number in [${parameter.minimum}, ${parameter.maximum}]`)
+  }
+  return null
+}
+
+export function validateRecipeManifest(manifest, options = {}) {
+  const errors = structural(manifest).map(error => issue('RECIPE_MANIFEST_INVALID', error.path, error.message))
+  if (errors.length) return result(errors)
+  if (RESERVED.has(manifest.id)) errors.push(issue('RECIPE_MANIFEST_INVALID', 'id', 'Reserved object keys are not recipe IDs'))
+  for (const [path, value] of [['title', manifest.title], ['description', manifest.description], ['license', manifest.license], ['author.name', manifest.author.name]]) {
+    if (!value.trim()) errors.push(issue('RECIPE_MANIFEST_INVALID', path, 'A non-empty declaration is required'))
+  }
+  for (const [path, address] of [['source.url', manifest.source.url], ['author.url', manifest.author.url]]) {
+    if (address === undefined) continue
+    try {
+      const parsed = new URL(address)
+      if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password) throw new Error()
+    } catch { errors.push(issue('RECIPE_MANIFEST_INVALID', path, 'Expected an HTTP(S) source reference without credentials; URLs are never fetched')) }
+  }
+  const supported = new Set(options.supportedCapabilities ?? RECIPE_CAPABILITIES)
+  const declared = new Set()
+  for (const capability of manifest.compatibility.capabilities) {
+    if (declared.has(capability)) errors.push(issue('RECIPE_MANIFEST_INVALID', 'compatibility.capabilities', `Duplicate capability ${capability}`))
+    declared.add(capability)
+    if (!supported.has(capability)) errors.push(issue('RECIPE_INCOMPATIBLE', 'compatibility.capabilities', `Unsupported capability ${capability}`))
+  }
+  const ids = new Set(), targets = new Set()
+  for (const parameter of manifest.parameters) {
+    const path = `parameters.${parameter.id}`
+    if (ids.has(parameter.id) || RESERVED.has(parameter.id)) errors.push(issue('RECIPE_PARAMETER_INVALID', path, 'Parameter IDs must be unique and must not be reserved object keys'))
+    ids.add(parameter.id)
+    if (parameter.type === 'number' && parameter.minimum > parameter.maximum) errors.push(issue('RECIPE_PARAMETER_INVALID', path, 'minimum must not exceed maximum'))
+    const valueIssue = parameterValueIssue(parameter, parameter.default, `${path}.default`)
+    if (valueIssue) errors.push(valueIssue)
+    for (const binding of parameter.bindings) {
+      const target = binding.kind === 'material' ? `material:${binding.materialId}:${binding.property}` : `render-profile:${binding.profile}:exposure`
+      if (targets.has(target)) errors.push(issue('RECIPE_BINDING_INVALID', path, `Target ${target} is bound more than once`))
+      targets.add(target)
+      const color = binding.kind === 'material' && binding.property === 'baseColor'
+      if ((parameter.type === 'color') !== color) errors.push(issue('RECIPE_BINDING_INVALID', path, 'Parameter type does not match the allowlisted property'))
+      if (parameter.type === 'number') {
+        const range = binding.kind === 'material' ? [0, 1] : [-10, 10]
+        if (parameter.minimum < range[0] || parameter.maximum > range[1]) errors.push(issue('RECIPE_BINDING_INVALID', path, `Binding range must stay within [${range}]`))
+      }
+    }
+  }
+  return result(errors)
+}
+
+function asBytes(value, limit, path) {
+  if (!(value instanceof Uint8Array) && typeof value !== 'string') throw new RecipeError('RECIPE_INPUT_INVALID', `${path}: expected bytes or UTF-8 text`)
+  const bytes = typeof value === 'string' ? Buffer.from(value, 'utf8') : Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+  if (!bytes.length || bytes.length > limit) throw new RecipeError('RECIPE_INPUT_INVALID', `${path}: byte count must be in [1, ${limit}]`)
+  return bytes
+}
+
+// Bound PNG expansion before the shared decoder inflates it. A preview is data,
+// but its declared hash alone must not grant it unbounded decompression memory.
+const PNG_CRC_TABLE = Array.from({ length: 256 }, (_, index) => {
+  let value = index
+  for (let bit = 0; bit < 8; bit++) value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
+  return value >>> 0
+})
+function pngCrc(bytes, start, end) {
+  let value = 0xffffffff
+  for (let index = start; index < end; index++) value = PNG_CRC_TABLE[(value ^ bytes[index]) & 255] ^ (value >>> 8)
+  return (value ^ 0xffffffff) >>> 0
+}
+function validatePreview(bytes) {
+  if (bytes.length < 33 || !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) throw new Error('Expected PNG bytes')
+  let at = 8, width = 0, height = 0, channels = 0, ended = false
+  const data = []
+  while (at < bytes.length) {
+    if (at + 12 > bytes.length) throw new Error('Truncated PNG chunk')
+    const size = bytes.readUInt32BE(at), kind = bytes.toString('ascii', at + 4, at + 8), end = at + 8 + size
+    if (end + 4 > bytes.length) throw new Error('Truncated PNG payload')
+    if (pngCrc(bytes, at + 4, end) !== bytes.readUInt32BE(end)) throw new Error('PNG chunk checksum mismatch')
+    if (at === 8 && kind !== 'IHDR') throw new Error('PNG must start with IHDR')
+    if (kind === 'IHDR') {
+      if (at !== 8 || size !== 13) throw new Error('Invalid PNG IHDR')
+      width = bytes.readUInt32BE(at + 8); height = bytes.readUInt32BE(at + 12)
+      const depth = bytes[at + 16], color = bytes[at + 17]
+      if (depth !== 8 || ![2, 6].includes(color) || bytes[at + 18] || bytes[at + 19] || bytes[at + 20]) throw new Error('Preview must be a non-interlaced 8-bit RGB/RGBA PNG')
+      channels = color === 6 ? 4 : 3
+      if (!width || !height || width * height > RECIPE_LIMITS.previewPixels) throw new Error('Preview pixel limit exceeded')
+    }
+    if (kind === 'IDAT') data.push(bytes.subarray(at + 8, end))
+    if (kind === 'IEND') {
+      if (size !== 0 || end + 4 !== bytes.length) throw new Error('Invalid PNG end or trailing content')
+      ended = true
+    }
+    at = end + 4
+  }
+  if (!ended || !data.length) throw new Error('PNG is missing image data or IEND')
+  const expected = height * (1 + width * channels)
+  if (inflateSync(Buffer.concat(data), { maxOutputLength: expected }).length !== expected) throw new Error('PNG scanline length differs from IHDR')
+  decodePng(bytes)
+}
+
+function bindingsAgainstScene(manifest, spec) {
+  const errors = []
+  for (const parameter of manifest.parameters) for (const binding of parameter.bindings) {
+    const path = `parameters.${parameter.id}.bindings`
+    if (binding.kind === 'material') {
+      const material = spec.materials?.find(item => item.id === binding.materialId)
+      if (!material || !['principled', 'glass'].includes(material.shader) || material.parameters?.[binding.property] === undefined) {
+        errors.push(issue('RECIPE_BINDING_INVALID', path, `Material ${binding.materialId} must explicitly declare ${binding.property} on principled/glass`))
+      } else {
+        const current = parameter.type === 'color' ? material.parameters.baseColor.slice(0, 3) : material.parameters[binding.property]
+        if (JSON.stringify(current) !== JSON.stringify(parameter.default)) errors.push(issue('RECIPE_BINDING_INVALID', path, 'Parameter default must match the input scene property'))
+      }
+      if (spec.animationTracks?.some(track => track.targetKind === 'material' && track.targetEntityId === binding.materialId &&
+        (track.property === binding.property || track.property.startsWith(`${binding.property}.`)))) {
+        errors.push(issue('RECIPE_BINDING_INVALID', path, 'A parameter must not compete with animation on the same material property'))
+      }
+    } else if (spec.renderProfiles?.[binding.profile]?.colorManagement?.exposure !== parameter.default) {
+      errors.push(issue('RECIPE_BINDING_INVALID', path, `Profile ${binding.profile} must explicitly declare exposure equal to the parameter default`))
+    }
+  }
+  return errors
+}
+
+/** Hash actual loaded bytes; the manifest is a claim, never a verification receipt. */
+export function validateRecipePackage(bundle, options = {}) {
+  const checked = validateRecipeManifest(bundle?.manifest, options)
+  if (!checked.ok) return checked
+  const { manifest } = bundle
+  const errors = []
+  let sceneSpec
+  try {
+    const sceneBytes = asBytes(bundle.sceneBytes, RECIPE_LIMITS.sceneBytes, 'input')
+    const previewBytes = asBytes(bundle.previewBytes, RECIPE_LIMITS.previewBytes, 'preview')
+    if (sha256(sceneBytes) !== manifest.input.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'input.sha256', 'Loaded SceneSpec bytes differ from the declared hash'))
+    if (sha256(previewBytes) !== manifest.preview.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'preview.sha256', 'Loaded preview bytes differ from the declared hash'))
+    if (errors.length) return result(errors)
+    try { validatePreview(previewBytes) } catch (error) { return result([issue('RECIPE_PREVIEW_INVALID', 'preview', error.message)]) }
+    try { sceneSpec = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(sceneBytes)) }
+    catch { return result([issue('RECIPE_INPUT_INVALID', 'input', 'SceneSpec must be valid UTF-8 JSON')]) }
+    const scene = validateSceneSpec(sceneSpec)
+    if (!scene.ok) return result(scene.errors.map(error => issue('RECIPE_SCENE_INVALID', `input.${error.path}`, error.message)))
+    if (sceneSpec.assets?.length || sceneSpec.entities.some(entity => entity.type === 'asset-instance') ||
+        sceneSpec.materials?.some(material => material.images) || sceneSpec.world?.environment ||
+        sceneSpec.armatures?.length || sceneSpec.simulation ||
+        sceneSpec.entities.some(entity => entity.rigidBody || entity.cloth || entity.softBody || entity.fluid || entity.armatureId) ||
+        sceneSpec.animationTracks?.some(track => track.targetKind === 'bone')) {
+      errors.push(issue('RECIPE_INPUT_UNSUPPORTED', 'input', 'Recipe v1 supports self-contained procedural scenes without files, rigs or simulations'))
+    }
+    const declared = new Set(manifest.compatibility.capabilities)
+    for (const capability of recipeCapabilitiesForScene(sceneSpec)) {
+      if (!declared.has(capability)) errors.push(issue('RECIPE_CAPABILITY_UNDECLARED', 'compatibility.capabilities', `Scene uses undeclared capability ${capability}`))
+    }
+    errors.push(...bindingsAgainstScene(manifest, sceneSpec))
+    if (errors.length) return result(errors)
+    const compiled = compileSceneSpec(sceneSpec)
+    const compiledCheck = validateSceneSpec(compiled.spec)
+    if (!compiledCheck.ok) return result(compiledCheck.errors.map(error => issue('RECIPE_SCENE_INVALID', error.path, error.message)))
+    return result([], { sceneSpec, notices: [...scene.notices, ...compiled.notices] })
+  } catch (error) { return result([issue(error.code ?? 'RECIPE_INPUT_INVALID', 'input', error.message)]) }
+}
+
+/** Return a fresh resolved SceneSpec; only explicit scalar/color slots can change. */
+export function instantiateRecipe(bundle, values = {}, options = {}) {
+  const checked = validateRecipePackage(bundle, options)
+  if (!checked.ok) throw new RecipeError(checked.errors[0].code, checked.summary, { errors: checked.errors })
+  if (!plain(values)) throw new RecipeError('RECIPE_PARAMETER_INVALID', 'Parameter values must be a plain object')
+  const { manifest } = bundle
+  const known = new Set(manifest.parameters.map(parameter => parameter.id))
+  const errors = Object.keys(values).filter(key => !known.has(key) || RESERVED.has(key))
+    .map(key => issue('RECIPE_PARAMETER_UNKNOWN', `values.${key}`, 'Unknown parameter'))
+  const resolvedValues = {}
+  for (const parameter of manifest.parameters) {
+    const value = Object.hasOwn(values, parameter.id) ? values[parameter.id] : parameter.default
+    const valueIssue = parameterValueIssue(parameter, value, `values.${parameter.id}`)
+    if (valueIssue) errors.push(valueIssue)
+    else resolvedValues[parameter.id] = structuredClone(value)
+  }
+  if (errors.length) throw new RecipeError(errors[0].code, errors.map(error => error.message).join('; '), { errors })
+  const spec = structuredClone(checked.sceneSpec)
+  for (const parameter of manifest.parameters) for (const binding of parameter.bindings) {
+    const value = resolvedValues[parameter.id]
+    if (binding.kind === 'material') {
+      const material = spec.materials.find(item => item.id === binding.materialId)
+      material.parameters[binding.property] = parameter.type === 'color'
+        ? [...value, material.parameters.baseColor[3] ?? 1] : value
+    } else spec.renderProfiles[binding.profile].colorManagement.exposure = value
+  }
+  const validation = validateSceneSpec(spec)
+  if (!validation.ok) throw new RecipeError('RECIPE_SCENE_INVALID', validation.summary, { errors: validation.errors })
+  const compiled = compileSceneSpec(spec)
+  const finalCheck = validateSceneSpec(compiled.spec)
+  if (!finalCheck.ok) throw new RecipeError('RECIPE_SCENE_INVALID', finalCheck.summary, { errors: finalCheck.errors })
+  return { spec: compiled.spec, values: resolvedValues, notices: [...validation.notices, ...compiled.notices],
+    recipe: { id: manifest.id, version: manifest.version, manifestSha256: sha256Canonical(manifest),
+      inputSha256: manifest.input.sha256, previewSha256: manifest.preview.sha256, valuesSha256: sha256Canonical(resolvedValues) } }
+}

package/lib/reference-images.js

@@ -0,0 +1,28 @@
+/** Semantic checks shared by a SceneSpec and a project.brief.set operation.
+ * Shape validation runs first. With assets omitted, only local invariants apply.
+ */
+export function referenceImageIssues(references, assets) {
+  const issues = []
+  const ids = new Set()
+  for (const [index, reference] of references.entries()) {
+    const add = (field, message, code = 'SCENE_SPEC_INVALID') =>
+      issues.push({ path: `[${index}].${field}`, message, code })
+    if (ids.has(reference.id)) add('id', `duplicate reference image id "${reference.id}"`, 'SCENE_ID_DUPLICATE')
+    ids.add(reference.id)
+    if (new Set(reference.purposes).size !== reference.purposes.length) {
+      add('purposes', 'reference image purposes must be unique')
+    }
+    if (assets === undefined) continue
+    const asset = assets.find(entry => entry.id === reference.assetId)
+    if (!asset) {
+      add('assetId', `reference image asset "${reference.assetId}" does not exist`, 'SCENE_REFERENCE_MISSING')
+      continue
+    }
+    if (!['png', 'jpg', 'jpeg'].includes(asset.type)) add('assetId', 'reference images require a PNG or JPEG asset')
+    if (asset.sha256 !== reference.sha256) add('sha256', 'reference image sha256 must match its declared asset sha256')
+    if (asset.path !== `assets/raw/${reference.sha256}.${asset.type}`) {
+      add('assetId', 'reference image assets require the immutable assets/raw/<sha256>.<type> path')
+    }
+  }
+  return issues
+}