@instruktlabs/kiln 1.2.2 → 1.2.3

package/src/uv.ts

@@ -15,6 +15,7 @@
  */
 
 import * as THREE from 'three';
+import { prepareUnwrap, remapUnwrapAttribute, validateAtlasRemap, type AtlasMesh } from './uv-data';
 
 // Lazy xatlas init — pays ~100-200ms on first call, then free.
 let _xatlasReady: Promise<unknown> | null = null;
@@ -41,17 +42,7 @@ type XatlasApi = {
     height: number;
     atlasCount: number;
     meshCount: number;
-    meshes: Array<{
-      mesh: string;
-      vertex: {
-        vertices: Float32Array | number[];
-        normals?: Float32Array | number[];
-        coords?: Float32Array | number[];
-        coords1?: Float32Array | number[];
-      };
-      index?: Uint32Array | number[];
-      oldIndexes: Uint32Array | number[];
-    }>;
+    meshes: AtlasMesh[];
   };
   destroyAtlas(): void;
 };
@@ -85,11 +76,11 @@ async function getXatlas(): Promise<XatlasApi> {
 }
 
 export interface AutoUnwrapOptions {
-  /** Atlas texture resolution (power-of-2). Default 1024. */
+  /** Target atlas resolution, integer 1..4096. Actual packed dimensions may differ. Default 1024. */
   resolution?: number;
   /** Padding between charts in texels. Default 2. */
   padding?: number;
-  /** Bake surface normals when determining seams. Default false (faster). */
+  /** Use and preserve source normals; otherwise recompute. Required for normal morphs. Default false. */
   useNormals?: boolean;
 }
 
@@ -100,7 +91,13 @@ export interface AutoUnwrapOptions {
  * sampling, and (usually) a different vertex count than the input: xatlas
  * duplicates vertices along UV seams so each shell gets its own chart.
  *
- * Returns a *new* BufferGeometry; the input is left untouched.
+ * Returns a *new* BufferGeometry; the input is left untouched. Seam remapping
+ * preserves per-vertex attributes, position/normal/color morphs, groups and JSON
+ * userData. Replaces UV0 and removes stale tangents. Normal behavior is unchanged:
+ * recompute by default, preserve source normals with useNormals: true.
+ * The current xatlasjs adapter supports at most 65,536 input AND output vertices;
+ * split larger meshes. Instancing, multi-page atlases and changed face order are
+ * rejected rather than returning corrupt attribute correspondence.
  *
  * @example
  * const raw = boxGeo(1, 2, 1);
@@ -111,125 +108,73 @@ export async function autoUnwrap(
   geometry: THREE.BufferGeometry,
   opts: AutoUnwrapOptions = {},
 ): Promise<THREE.BufferGeometry> {
+  const prepared = prepareUnwrap(geometry, opts);
   const xa = await getXatlas();
-
-  // xatlas needs an indexed BufferGeometry. Convert if necessary.
-  const src = geometry.index ? geometry : toIndexed(geometry);
-  const posAttr = src.getAttribute('position') as THREE.BufferAttribute | undefined;
-  const normAttr = src.getAttribute('normal') as THREE.BufferAttribute | undefined;
-  const idxAttr = src.getIndex();
-  if (!posAttr || !idxAttr) {
-    throw new Error('autoUnwrap: geometry requires position attribute and an index');
-  }
-  // T2.4: measured — xatlas accepts an empty mesh and returns an empty atlas
-  // without complaint, so a zero-triangle geometry used to come back with zero
-  // vertices and NO uv attribute, and the failure only surfaced later as a
-  // texture that would not appear. The realistic upstream cause is a CSG result
-  // that collapsed to nothing.
-  if (idxAttr.count === 0 || posAttr.count === 0) {
-    throw new Error(
-      'autoUnwrap: geometry has no triangles. Nothing can be unwrapped — check the operation that produced it (an empty CSG result is the usual cause).',
+  xa.createAtlas();
+  try {
+    const added = xa.addMesh(
+      prepared.index,
+      prepared.positions,
+      prepared.normals,
+      null,
+      'kiln-mesh',
+      prepared.useNormals,
+      false,
+      1,
     );
-  }
-  if (idxAttr.count % 3 !== 0) {
-    throw new Error(
-      `autoUnwrap: geometry has ${idxAttr.count} indices, which is not a whole number of triangles.`,
+    if (!added)
+      throw new Error('autoUnwrap: xatlas.addMesh failed (non-manifold or degenerate geometry?).');
+    const result = xa.generateAtlas(
+      {},
+      { resolution: prepared.resolution, padding: prepared.padding },
+      true,
     );
-  }
-
-  xa.createAtlas();
-
-  const useNormals = Boolean(opts.useNormals && normAttr);
-  const indexArray =
-    idxAttr.array instanceof Uint32Array
-      ? idxAttr.array
-      : new Uint32Array(idxAttr.array as ArrayLike<number>);
-
-  const addRes = xa.addMesh(
-    indexArray,
-    new Float32Array(posAttr.array),
-    useNormals && normAttr ? new Float32Array(normAttr.array) : null,
-    null,
-    'kiln-mesh',
-    useNormals,
-    false,
-    1,
-  );
-  if (!addRes) {
-    xa.destroyAtlas();
-    throw new Error('autoUnwrap: xatlas.addMesh failed (non-manifold or degenerate geometry?)');
-  }
-
-  const result = xa.generateAtlas(
-    {},
-    { resolution: opts.resolution ?? 1024, padding: opts.padding ?? 2 },
-    true,
-  );
-
-  const mesh = result.meshes[0];
-  if (!mesh) {
-    xa.destroyAtlas();
-    throw new Error('autoUnwrap: xatlas returned no meshes');
-  }
-
-  const out = new THREE.BufferGeometry();
-  out.setAttribute(
-    'position',
-    new THREE.BufferAttribute(new Float32Array(mesh.vertex.vertices), 3),
-  );
-  if (mesh.vertex.normals) {
-    out.setAttribute('normal', new THREE.BufferAttribute(new Float32Array(mesh.vertex.normals), 3));
-  }
-  if (mesh.vertex.coords1) {
-    out.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(mesh.vertex.coords1), 2));
-  }
-  if (mesh.index) {
-    out.setIndex(new THREE.BufferAttribute(new Uint32Array(mesh.index), 1));
-  }
-
-  // Atlas metadata lives on userData so downstream tools (texture baking,
-  // projection painting) can sample the atlas resolution.
-  //
-  // T2.4 — read `width`/`height`, do NOT assume `resolution` squared. `resolution`
-  // is an upper bound xatlas packs within, not the atlas it returns: a CSG'd box
-  // at resolution 1024 measured 917x1085. A baker that allocated a square
-  // `resolution x resolution` target would sample the wrong texels along one
-  // axis, which reads as a subtle uniform stretch rather than an obvious break.
-  out.userData['atlas'] = {
-    width: result.width,
-    height: result.height,
-    atlasCount: result.atlasCount,
-  };
-
-  if (!out.getAttribute('normal')) out.computeVertexNormals();
-  repairZeroNormals(out);
-
-  // xatlas can pack every chart and still hand back a mesh with no coords1 when
-  // the input degenerates. Better to say so than to return a geometry whose
-  // missing `uv` only shows up as an untextured surface much later.
-  if (!out.getAttribute('uv')) {
+    const mesh = result.meshes[0];
+    if (!mesh || result.meshCount !== 1)
+      throw new Error('autoUnwrap: xatlas returned no single mesh.');
+    if (
+      result.atlasCount !== 1 ||
+      !Number.isSafeInteger(result.width) ||
+      result.width <= 0 ||
+      !Number.isSafeInteger(result.height) ||
+      result.height <= 0
+    )
+      throw new Error(
+        'autoUnwrap: xatlas must return one valid atlas; multiple atlas pages are unsupported.',
+      );
+    const remap = validateAtlasRemap(mesh, prepared.index, geometry.getAttribute('position').count);
+    const out = new THREE.BufferGeometry();
+    for (const [name, attribute] of Object.entries(geometry.attributes)) {
+      if (name === 'uv' || name === 'tangent' || (name === 'normal' && !prepared.useNormals))
+        continue;
+      out.setAttribute(name, remapUnwrapAttribute(attribute, remap.oldIndexes));
+    }
+    for (const [name, targets] of Object.entries(geometry.morphAttributes)) {
+      // Three's declaration lists standard keys, although its runtime uses a dictionary.
+      (out.morphAttributes as Record<string, THREE.BufferAttribute[]>)[name] = targets.map(
+        (attribute) => remapUnwrapAttribute(attribute, remap.oldIndexes),
+      );
+    }
+    out.morphTargetsRelative = geometry.morphTargetsRelative;
+    out.setIndex(new THREE.BufferAttribute(new Uint32Array(remap.index), 1));
+    out.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(remap.uv), 2));
+    out.name = geometry.name;
+    // Triangle correspondence was checked before retaining material groups and draw range.
+    out.groups = geometry.groups.map((group) => ({ ...group }));
+    out.setDrawRange(geometry.drawRange.start, geometry.drawRange.count);
+    out.userData = JSON.parse(JSON.stringify(geometry.userData));
+    // xatlas's requested resolution is not the returned width/height (often rectangular).
+    out.userData['atlas'] = {
+      width: result.width,
+      height: result.height,
+      atlasCount: result.atlasCount,
+    };
+    if (!out.getAttribute('normal')) out.computeVertexNormals();
+    repairZeroNormals(out);
+    return out;
+  } finally {
     xa.destroyAtlas();
-    throw new Error(
-      'autoUnwrap: xatlas produced no UV coordinates for this geometry (degenerate or zero-area triangles?).',
-    );
   }
-
-  xa.destroyAtlas();
-  return out;
-}
-
-/**
- * Convert a non-indexed BufferGeometry to an indexed one via naive
- * sequential indexing. Sufficient for xatlas input (it re-indexes anyway
- * during chart generation).
- */
-function toIndexed(geo: THREE.BufferGeometry): THREE.BufferGeometry {
-  const posAttr = geo.getAttribute('position') as THREE.BufferAttribute;
-  const indices = new Uint32Array(posAttr.count);
-  for (let i = 0; i < posAttr.count; i++) indices[i] = i;
-  const out = geo.clone();
-  out.setIndex(new THREE.BufferAttribute(indices, 1));
-  return out;
 }
 
 /**

package/src/viewer/app.ts

@@ -5,6 +5,7 @@ import {
   encodeAssetBundle,
   type AssetManifest,
   type AssetRecord,
+  assetMaterialRootManifests,
 } from '../assets';
 import { assetAttributionRows } from './attribution';
 import { createAssetStage } from './scene';
@@ -16,6 +17,7 @@ import { mountPerformanceControl } from './performance-control';
 import type { ProjectRevision } from '../projects';
 import { assetIdentity, entriesForProject } from './library-state';
 import { mountMembership } from './membership-panel';
+import { materialViewerHref } from './material-preview';
 
 const el = <T extends HTMLElement = HTMLElement>(id: string) => document.getElementById(id)! as T;
 const node = <K extends keyof HTMLElementTagNameMap>(tag: K, text?: string, className?: string) => {
@@ -347,6 +349,41 @@ async function openDetail(entry: Entry) {
     attribution.append(item);
   }
   attribution.hidden = !attribution.childElementCount;
+  let materialInputs = document.getElementById('asset-material-inputs');
+  if (!materialInputs) {
+    materialInputs = node('section', undefined, 'asset-material-inputs');
+    materialInputs.id = 'asset-material-inputs';
+    attribution.after(materialInputs);
+  }
+  materialInputs.replaceChildren();
+  try {
+    const dependencies = assetMaterialRootManifests({ manifest: entry.manifest, files: {} });
+    if (dependencies.length) {
+      materialInputs.append(
+        node('h3', 'Exact material build inputs'),
+        node(
+          'p',
+          'Open the saved revision to inspect its raw maps, sampling declaration and atlas regions. Declared inputs do not prove every map was used.',
+          'subtle',
+        ),
+      );
+      for (const material of dependencies) {
+        const link = node('a', `${material.name} · ${material.materialId}`);
+        link.href = materialViewerHref(material);
+        link.target = '_blank';
+        link.rel = 'noopener';
+        materialInputs.append(link, node('p', material.revisionId, 'mono'));
+      }
+    }
+  } catch (error) {
+    materialInputs.append(
+      node(
+        'p',
+        `Material revision links unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        'subtle',
+      ),
+    );
+  }
   el('provenance').textContent = entry.loose
     ? 'Standalone GLB. No source or build provenance supplied.'
     : JSON.stringify(entry.manifest, null, 2);

package/src/viewer/live-panel.ts

@@ -15,6 +15,8 @@ import type { AssetManifest } from '../assets';
 import { mountPerformanceControl } from './performance-control';
 import { mountMembership } from './membership-panel';
 import { el, node, request, empty, notice, remember, recall, shortId } from './dom';
+import { materialEvaluationDependencies } from './material-preview';
+import { materialPreviewPanel } from './material-preview-panel';
 
 export function mountLiveReview() {
   let state: ReviewState = { following: true, crossRunContinuity: true, operations: [] };
@@ -35,6 +37,7 @@ export function mountLiveReview() {
   let compareGeneration = 0;
   let wire = false;
   let recoveredPreference = false;
+  let materialInspection: { key: string; card: HTMLElement } | undefined;
   const projectSelect = el<HTMLSelectElement>('live-project');
   const sourceSelect = el<HTMLSelectElement>('live-source');
   const livePath = (path: string) =>
@@ -179,7 +182,10 @@ export function mountLiveReview() {
     target.replaceChildren();
     downloads.replaceChildren();
     const operation = state.displayed;
-    if (!operation?.artifact) return;
+    if (!operation?.artifact) {
+      materialInspection = undefined;
+      return;
+    }
     const identity = node('div', undefined, 'evidence-card');
     identity.append(
       node('h3', 'Selected observed artifact'),
@@ -188,6 +194,56 @@ export function mountLiveReview() {
       node('p', `Source: ${operation.programRef ?? 'See authored source download'}`, 'mono'),
     );
     target.append(identity, fidelityCard(operation));
+    const materialKey = `${sourceSelect.value}/${operation.operationId}/${operation.artifact.sha256}`;
+    if (materialInspection?.key !== materialKey) {
+      const card = node('div', undefined, 'evidence-card live-material-inspection'),
+        button = node('button', 'Inspect exact material inputs', 'secondary');
+      card.append(
+        node('h3', 'Materials and atlas sheets'),
+        node(
+          'p',
+          'Declared inputs for this displayed artifact. Raw sheets are unshaded; capture fidelity is reported separately.',
+        ),
+        button,
+      );
+      materialInspection = { key: materialKey, card };
+      button.onclick = async () => {
+        button.disabled = true;
+        const status = node('p', 'Reading the displayed artifact evaluation…');
+        status.setAttribute('role', 'status');
+        card.append(status);
+        try {
+          const evaluation = await request<unknown>(
+            livePath(`/api/live/${encodeURIComponent(operation.operationId)}/evaluation.json`),
+          );
+          if (materialInspection?.key !== materialKey) return;
+          const dependencies = materialEvaluationDependencies(
+            evaluation,
+            operation.artifact!.sha256,
+          );
+          status.textContent = dependencies.length
+            ? 'Exact declared revisions. Map images require the matching record in this local material library.'
+            : 'No saved material resource declarations in this artifact. Embedded textures can still be viewed in the viewport.';
+          for (const material of dependencies) {
+            const details = node('details');
+            details.append(node('summary', `${material.name} · ${material.revisionId}`));
+            let loaded = false;
+            details.ontoggle = () => {
+              if (details.open && !loaded) {
+                loaded = true;
+                details.append(materialPreviewPanel(material));
+              }
+            };
+            card.append(details);
+          }
+        } catch (error) {
+          if (materialInspection?.key !== materialKey) return;
+          status.textContent = `Material inspection unavailable for this exact artifact: ${error instanceof Error ? error.message : String(error)}`;
+          button.disabled = false;
+        }
+      };
+    }
+    target.append(materialInspection.card);
     if (operation.captures.length) {
       for (const capture of operation.captures) {
         const card = node('div', undefined, 'evidence-card');

package/src/viewer/material-preview-panel.ts

@@ -0,0 +1,140 @@
+/// <reference lib="dom" />
+import type { MaterialManifest } from '../material-library';
+import { node } from './dom';
+import {
+  materialPreviewModel,
+  materialViewerHref,
+  type MaterialPreviewMap,
+} from './material-preview';
+
+/** Raw PNG inspection only. Recorded capture fidelity belongs to the asset/operation. */
+export function materialPreviewPanel(manifest: MaterialManifest) {
+  const model = materialPreviewModel(manifest),
+    panel = node('section', undefined, 'material-inspection');
+  panel.setAttribute('aria-label', `${model.name}: exact material maps`);
+  panel.append(
+    node('p', `${model.materialId} · ${model.revisionId}`, 'mono'),
+    node('p', model.fidelity, 'subtle'),
+  );
+  const controls = node('div', undefined, 'material-inspection-controls');
+  const field = (label: string, select: HTMLSelectElement) => {
+    const wrapper = node('label', label, 'inline-field');
+    wrapper.append(select);
+    controls.append(wrapper);
+    return select;
+  };
+  const mapSelect = field('Map', node('select'));
+  for (const map of model.maps)
+    mapSelect.append(new Option(`${map.slot}${map.atlas ? ' · atlas' : ''}`, map.slot));
+  const backdrop = field('Backdrop', node('select'));
+  for (const value of ['checker', 'light', 'dark'])
+    backdrop.append(new Option(value[0]!.toUpperCase() + value.slice(1), value));
+  const zoom = field('Pixel zoom', node('select'));
+  for (const scale of [1, 2, 4]) zoom.append(new Option(`${scale}×`, String(scale)));
+  const frame = node('div', undefined, 'material-pixel-frame'),
+    sheet = node('div', undefined, 'material-pixel-sheet');
+  frame.dataset.backdrop = 'checker';
+  frame.tabIndex = 0;
+  const image = node('img');
+  image.className = 'material-pixel-image';
+  image.loading = 'lazy';
+  image.draggable = false;
+  const overlay = node('div', undefined, 'material-region-overlay');
+  const overlayControl = node('label', 'Region overlays', 'inline-field');
+  const overlayToggle = node('input');
+  overlayToggle.type = 'checkbox';
+  overlayToggle.checked = false;
+  overlayControl.append(overlayToggle);
+  controls.append(overlayControl);
+  overlayToggle.onchange = () => {
+    overlay.hidden = !overlayToggle.checked;
+  };
+  sheet.append(image, overlay);
+  frame.append(sheet);
+  const status = node('p', undefined, 'subtle');
+  status.setAttribute('role', 'status');
+  const facts = node('dl'),
+    regions = node('div', undefined, 'material-region-list');
+  const exact = node('a', 'Open this saved material revision');
+  exact.href = materialViewerHref(model);
+  exact.target = '_blank';
+  exact.rel = 'noopener';
+  panel.append(controls, frame, status, facts, regions, exact);
+  let current: MaterialPreviewMap = model.maps[0]!;
+  const size = () => {
+    sheet.style.width = `${current.width * Number(zoom.value)}px`;
+    sheet.style.height = `${current.height * Number(zoom.value)}px`;
+  };
+  const show = () => {
+    current = model.maps.find((map) => map.slot === mapSelect.value) ?? model.maps[0]!;
+    overlayControl.hidden = !current.atlas;
+    overlay.hidden = !current.atlas || !overlayToggle.checked;
+    status.textContent = 'Loading exact saved map…';
+    image.alt = `${model.name}: ${current.slot}${current.atlas ? ' atlas sheet' : ''}, raw unshaded pixels`;
+    image.width = current.width;
+    image.height = current.height;
+    image.src = current.url;
+    size();
+    facts.replaceChildren();
+    const fact = (label: string, value: string) =>
+      facts.append(node('dt', label), node('dd', value));
+    fact(
+      'Image',
+      `${current.width} × ${current.height} · ${current.colorSpace} · nearest pixel display`,
+    );
+    fact(
+      'Sampling declaration',
+      current.sampler
+        ? `${current.sampler.minFilter} / ${current.sampler.magFilter} · ${current.sampler.wrapS} / ${current.sampler.wrapT}`
+        : 'Not recorded in V1',
+    );
+    fact('PNG hash', current.imageSha256);
+    if (current.pixelHash) fact('Decoded RGBA hash', current.pixelHash);
+    if (current.compilerId) fact('Compiler', current.compilerId);
+    if (current.manifestHash) fact('Atlas manifest hash', current.manifestHash);
+    overlay.replaceChildren();
+    regions.replaceChildren();
+    if (current.atlas) {
+      regions.append(node('h4', 'Atlas regions · top-left pixel coordinates'));
+      for (const region of current.regions) {
+        const box = node('span', undefined, 'material-region-box');
+        box.style.left = `${region.leftPercent}%`;
+        box.style.top = `${region.topPercent}%`;
+        box.style.width = `${region.widthPercent}%`;
+        box.style.height = `${region.heightPercent}%`;
+        box.append(node('span', region.name));
+        box.setAttribute('aria-hidden', 'true');
+        overlay.append(box);
+        const item = node(
+          'button',
+          `${region.name}: content ${region.content.x},${region.content.y} ${region.content.width}×${region.content.height}; allocation ${region.allocation.x},${region.allocation.y} ${region.allocation.width}×${region.allocation.height}`,
+          'secondary',
+        );
+        item.type = 'button';
+        item.setAttribute('aria-pressed', 'false');
+        item.onclick = () => {
+          for (const candidate of overlay.children) candidate.classList.remove('selected');
+          for (const button of regions.querySelectorAll('button'))
+            button.setAttribute('aria-pressed', 'false');
+          box.classList.add('selected');
+          item.setAttribute('aria-pressed', 'true');
+          if (!overlay.hidden) box.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+        };
+        regions.append(item);
+      }
+    }
+  };
+  image.onload = () => {
+    status.textContent = 'Raw map loaded. These pixels are not a shaded capture.';
+  };
+  image.onerror = () => {
+    status.textContent = `Exact ${model.materialId} revision map unavailable. No newer revision was substituted.`;
+  };
+  mapSelect.onchange = show;
+  backdrop.onchange = () => {
+    frame.dataset.backdrop = backdrop.value;
+  };
+  zoom.onchange = size;
+  show();
+  return panel;
+}

package/src/viewer/material-preview.ts

@@ -0,0 +1,138 @@
+/** Browser-safe presentation of saved raw maps. No renderer or source loading. */
+import {
+  canonicalMaterialJson,
+  validateMaterialManifestAny,
+  type MaterialManifest,
+} from '../material-library';
+import type { PortableSamplerV1 } from '../portable-sampler';
+export const RAW_MAP_FIDELITY = 'Raw map pixels · unshaded · not GPU capture evidence';
+export interface MaterialViewerSelection {
+  materialId: string;
+  revisionId: string;
+}
+const id = /^[a-z][a-z0-9_-]{0,79}$/;
+const revision = /^sha256:[a-f0-9]{64}$/;
+export function materialViewerSelection(search: string): MaterialViewerSelection | undefined {
+  const query = new URLSearchParams(
+    search.startsWith('?') ? search : search.slice(search.indexOf('?') + 1),
+  );
+  const materialId = query.get('material'),
+    revisionId = query.get('materialRevision');
+  if (
+    query.getAll('material').length !== 1 ||
+    query.getAll('materialRevision').length !== 1 ||
+    !materialId ||
+    !revisionId ||
+    !id.test(materialId) ||
+    !revision.test(revisionId)
+  )
+    return undefined;
+  return { materialId, revisionId };
+}
+export function materialViewerHref(selection: MaterialViewerSelection): string {
+  if (!id.test(selection.materialId) || !revision.test(selection.revisionId))
+    throw new Error('Invalid exact material selection');
+  return `/?${new URLSearchParams({ material: selection.materialId, materialRevision: selection.revisionId })}`;
+}
+export function materialApiBase(selection: MaterialViewerSelection): string {
+  if (!id.test(selection.materialId) || !revision.test(selection.revisionId))
+    throw new Error('Invalid exact material selection');
+  return `/api/materials/${encodeURIComponent(selection.materialId)}/${encodeURIComponent(selection.revisionId)}`;
+}
+interface Rectangle {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface MaterialPreviewRegion {
+  name: string;
+  content: Rectangle;
+  allocation: Rectangle;
+  leftPercent: number;
+  topPercent: number;
+  widthPercent: number;
+  heightPercent: number;
+}
+export interface MaterialPreviewMap {
+  slot: string;
+  file: string;
+  url: string;
+  width: number;
+  height: number;
+  colorSpace: string;
+  imageSha256: string;
+  pixelHash?: string;
+  sampler?: PortableSamplerV1;
+  atlas: boolean;
+  compilerId?: string;
+  manifestHash?: string;
+  regions: MaterialPreviewRegion[];
+}
+export function materialPreviewModel(value: MaterialManifest) {
+  const material = validateMaterialManifestAny(value);
+  const base = materialApiBase(material);
+  const maps: MaterialPreviewMap[] = material.maps.map((map) => {
+    const modern = 'recipe' in map ? map : undefined;
+    const atlas = modern?.recipe?.kind === 'atlas' ? modern.recipe : undefined;
+    return {
+      slot: map.slot,
+      file: map.file,
+      url: `${base}/${encodeURIComponent(map.file)}`,
+      width: map.width,
+      height: map.height,
+      colorSpace: map.colorSpace,
+      imageSha256: map.sha256,
+      ...('pixelHash' in map ? { pixelHash: map.pixelHash } : {}),
+      ...('sampler' in map ? { sampler: { ...map.sampler } } : {}),
+      atlas: !!atlas,
+      ...(modern?.recipe ? { compilerId: modern.recipe.compilerId } : {}),
+      ...(atlas ? { manifestHash: atlas.manifest.manifestHash } : {}),
+      regions: atlas
+        ? atlas.manifest.regions.map((region) => ({
+            name: region.name,
+            content: { ...region.content },
+            allocation: { ...region.allocation },
+            leftPercent: (region.content.x / map.width) * 100,
+            topPercent: (region.content.y / map.height) * 100,
+            widthPercent: (region.content.width / map.width) * 100,
+            heightPercent: (region.content.height / map.height) * 100,
+          }))
+        : [],
+    };
+  });
+  return {
+    materialId: material.materialId,
+    revisionId: material.revisionId,
+    name: material.name,
+    fidelity: RAW_MAP_FIDELITY,
+    maps,
+  };
+}
+/** The retained evaluation and artifact are independently hash-bound by the host. */
+export function materialEvaluationDependencies(
+  value: unknown,
+  artifactSha256: string,
+): MaterialManifest[] {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    (value as Record<string, unknown>)['artifactGlbSha256'] !== artifactSha256
+  )
+    throw new Error('Retained evaluation does not identify the displayed artifact');
+  const dependencies = (value as Record<string, unknown>)['materialLibraryDependencies'];
+  if (dependencies === undefined) return [];
+  if (!Array.isArray(dependencies) || dependencies.length > 16)
+    throw new Error('Invalid retained material dependency list');
+  const result = new Map<string, MaterialManifest>();
+  for (const raw of dependencies) {
+    const manifest = validateMaterialManifestAny(raw),
+      key = `${manifest.materialId}/${manifest.revisionId}`,
+      existing = result.get(key);
+    if (existing && canonicalMaterialJson(existing) !== canonicalMaterialJson(manifest))
+      throw new Error('Conflicting retained material identity');
+    result.set(key, manifest);
+  }
+  return [...result.values()];
+}