@instruktlabs/kiln 1.2.2 → 1.2.3

package/plugins/kiln-engine/package-provenance.json

@@ -1,20 +1,20 @@
 {
   "schemaVersion": 1,
   "kind": "kiln-local-plugin",
-  "pluginVersion": "1.2.2",
-  "engineVersion": "1.2.2",
+  "pluginVersion": "1.2.3",
+  "engineVersion": "1.2.3",
   "executables": [
     "bin/kiln-setup-workspace.mjs"
   ],
   "files": {
     ".claude-plugin/icon.png": "sha256:b4b651c402793b7e27cab780f04b14f80daec6d0cd5b7e4e90313930581a54e9",
-    ".claude-plugin/plugin.json": "sha256:8f4586ed437f4a0478de900547cdf5ace59f0e125a0f0b8d7e717e44061509e9",
+    ".claude-plugin/plugin.json": "sha256:af0bc7b37b75ce5e4ab52230eded4d3e4ee999dd324b67665d57d5ce30ef56cf",
     "bin/kiln-setup-workspace.mjs": "sha256:3d9a30236919a6ca91acb6b26f808cec442e6edc3dd88fe010645b010d76e838",
     "LICENSE": "sha256:cdba278ebf1d6de618869936226bf03be4887179c128efc7aaa13d22034826a5",
-    "plugin.json": "sha256:937211437e673cef141599c5ec5e99902596a9bedf6d772694f50a39f9d8e6dd",
+    "plugin.json": "sha256:2e646847a58364094a9cd12c602553d73bda68785dfc216dbae9c07dafecd819",
     "PRIVACY.md": "sha256:5f58d981667e40441e21c2dec411f269a9a67a6141cec61976d27088fb12573b",
-    "README.md": "sha256:2224bb16ed6645a1861fce4fbcf6801e4b81a0cb918970ad95c21e75be511eb7",
-    "runtime.json": "sha256:cbb2367a7435583074f589e44162739db5f972d8e6656f6f1fb4b790ad6eddcc",
+    "README.md": "sha256:fcc6364d1b08689fd531a154383cf752a3d21cb26aa5623ac0acfc11057a9fb3",
+    "runtime.json": "sha256:797090aec0b46f4f6220a5b85ab58eebd1b82d7079ece0258c94c975021fdc7f",
     "skills/kiln-setup-workspace/references/plugin-install.md": "sha256:c338fb792e7fad0364c3e1a13c94c506afa1395489ec1b6e83b36d04728935fb",
     "skills/kiln-setup-workspace/references/renderer-setup.md": "sha256:b743b1b2827fa814385990e1e5b849391cb427413e9c016d273aa19cebd46031",
     "skills/kiln-setup-workspace/SKILL.md": "sha256:65ed926b3503a33f4fe793e84e4a045ce36e3967f0e6b340e456a15dd010ce54"

package/plugins/kiln-engine/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kiln-engine",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
   "author": {
     "name": "Instrukt Labs",

package/plugins/kiln-engine/runtime.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruktlabs/kiln",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "harnesses": [
     "claude",
     "codex",

package/skills/kiln-author-asset/references/geometry-recipes.md

@@ -17,6 +17,18 @@ and release. Matching endpoints can still produce a path through the payload or
 support. Keep joints, contact markers and payload motion in the intended hierarchy;
 repair the geometry or path where the swept volumes collide.
 
+Measure a resting or mounting frame against the exported geometry, including
+angled feet, supports and small protrusions. A nominal primitive bottom or a
+locator called `ground` can differ from the actual lowest surface after rotation.
+Preserve intentional hanging origins and provide a separate resting socket when
+both placements are useful; do not silently move every asset to its bounds.
+
+For directional repeated surfaces, preserve grain direction and texel scale while
+varying the phase between neighboring pieces. Identical knots aligned in columns
+can make separate boards read as one repeated stamp. Compare a single module with
+an assembled span. Random rotation is inappropriate for directional grain and
+must not change named atlas regions or their sampling margins.
+
 For ears, handles or other details attached to a rotated or lofted body, derive
 their bases from the carrier's local surface and transform them through the same
 frame. A nearby world-space point can leave a visible gap after the body rotates.
@@ -62,6 +74,15 @@ winding or missing geometry rather than hiding the defect with double-sided shad
 deliberate thin sheets may need it. Check ceiling and trim extents against the actual sloping roof, including
 the eaves, rather than its bounding box.
 
+Choose sidedness deliberately: an inward-facing tunnel lining can use `FrontSide`
+with inward triangle winding; a leaf card viewed from both sides can use
+`DoubleSide`. GLB has no back-only material flag, so Kiln rejects a used `BackSide`
+material instead of exporting it as front-only. Reversing normals alone does not
+reverse winding. Double-sided shading adds neither thickness nor end caps. A
+negative node scale mirrors the front-face convention; baking that reflection into
+vertex positions is a different operation and requires consistent winding and
+normal/tangent data. Inspect both sides after export in the intended consumer.
+
 For a pane or panel fitted into a sloping frame, derive its corners and surface
 normal in the frame's coordinates. A bar's long axis and a sheet's plane may use
 different local axes, so copying a slope angle does not align them. Check all
@@ -125,11 +146,51 @@ joint each pivot represents before reversing its bend direction. Correct exposed
 attachment caps, gaps and snapping through the motion, without assuming every
 stylized creature needs one rigging or deformation technique.
 
+Choose the mechanism deliberately: rigid armor plates or robot links can follow
+`createJointChain` pivots; a continuous elbow or flexible appendage can use
+`createBoneChain` plus `createSkinnedPart` when the installed Discovery exposes
+them. Both chains carry the same joint roles and local rest frames. Bones are
+opt-in; rigid pivots do not become bones merely because their names say `Joint_`.
+
+For explicit skinning, assemble the bones under the asset root in the rest pose
+before binding. Finish topology and UV operations first where practical. Supply
+four indices and weights for every final vertex, including duplicated UV seam
+vertices; use valid indices even for zero-weight lanes. Weights should sum to one.
+`normalizeWeights:true` normalizes a positive sum but cannot infer missing weights
+or repair a zero sum. The helper owns cloned geometry and inverse bind matrices;
+the caller still owns the bones and shared materials. Changing rest geometry or
+reparenting afterward needs deliberate rebinding, not just another animation pose.
+
+If export reports `SKIN_*` integrity findings, repair the named mesh, joint or
+vertex range before another render. A missing inverse matrix needs the intended
+rest binding restored; an invalid joint index needs the bone order and influence
+lanes corrected. Normalizing weights cannot repair either. These source-data
+checks also run on review derivatives and in QA warning mode. A valid current-pose
+bound does not prove all animation poses, good deformation or collision clearance.
+
+A two-bone ramp is useful for a simple strip or tube, not a general anatomical
+weighting rule: for a chosen local transition interval `[startY, endY]`, with
+`endY > startY`, use `t = Math.max(0, Math.min(1, (y-startY)/(endY-startY)))`,
+indices `[baseIndex, tipIndex, baseIndex, baseIndex]` and weights `[1-t,t,0,0]`.
+Keep the interval, joint placement and profile appropriate to the asset. Inspect
+rest, intermediate and extreme poses under the actual parent transforms; correct
+volume loss, exposed caps and pinching in the geometry/weights. Verify the chosen
+converter preserves skinning: the explicit Three exporter supports this path,
+while the legacy converter remains the default and does not preserve skins.
+
 Before mirroring a hand, inspect its local frame, palm, thumb web and any tool grip.
 Weak anatomical cues can look reversed without a left/right frame error. Refine the
 shape while preserving a correct wrist pivot and attachment frame, then check hand
 clearance through the relevant motion and against the complete carried tool.
 
+Define the palm normal, finger direction and thumb side in each hand's local frame.
+A grip marker reaching a handle does not establish a natural grip orientation.
+Solve reach with elbow and torso clearance as well as wrist alignment, distributing
+rotation through the forearm when appropriate. Inspect finger wrap and the actual
+skinned wrist and shoulder surfaces between keys; a correct joint frame can still
+produce a stretched sleeve cap. Neutral palm direction and pose belong to the
+asset brief, rather than a universal character default.
+
 For a shield or other broad carried plate, define the intended support pose as
 well as its mounting frame: which way the plate faces, where the grip lies, and
 how the forearm runs along the inner surface. Solve the elbow within a plausible
@@ -152,6 +213,12 @@ in the host). Recheck what each
 lookup controls, clip targets and intermediate poses after export; fewer meshes
 alone does not establish a successful optimization.
 
+In custom consolidation, a scalar mesh material applies to every geometry group.
+Group `materialIndex` selects an entry only when `mesh.material` is an array;
+indexing a one-element array for box face groups can silently create default
+materials on some faces. Preserve valid material assignments, then inspect the
+exported faces rather than relying on a successful merge or export.
+
 Budget materials within each rigid group. Reuse the parent's material for tiny
 fixed details when it gives the intended appearance; a separate material adds a
 potential draw even when the detail is small. One material does not guarantee
@@ -159,6 +226,15 @@ one draw: vertex layouts, protected parts, transparency and vertex-limit splits
 also constrain merging. Available `drawDiagnostics` can help locate these costs;
 read its scope and skip reasons, then measure in the destination.
 
+Budget skinned mesh count as well as triangles. A small articulated asset can
+still submit many draws when each segment is a separate skin, even if the parts
+share one texture. Where the authoring/export path supports it, combine
+compatible surfaces into a skin with a shared skeleton and material. A skin-aware
+consolidation must preserve bind transforms, joint indices and weights, normals,
+UVs, morph channels and attachment frames. Keep separate skins when their
+materials, skeletons or visibility controls require them. Do not send skins
+through a rigid merge by weakening its rejection checks.
+
 Avoid unintentionally overlapping coplanar faces on separate parts. Merging can
 change which face wins a depth tie even when geometry and colours are preserved.
 Use a shared surface, remove hidden duplicate faces or give a deliberate overlay
@@ -174,6 +250,36 @@ material capabilities before choosing a delivery resource, then inspect GPU view
 and destination filtering/backfaces. Raw `THREE.DataTexture` is not an available
 authoring route. Solid leaves and custom surfaces remain valid alternatives.
 
+For original cutouts, `proceduralTexture` V3 authors rectangular RGBA pixels;
+`textureAtlas` combines named fixed regions from V3 recipes or exact saved map
+revisions. Discover their full contracts before authoring. Atlas regions do not
+pack or resize themselves. Reserve nonoverlapping gutters and choose edge copying
+or transparent RGB dilation for the actual filtering and alpha policy.
+
+Map unit UVs with
+`remapUVToAtlas(geometry, atlas, 'region-name', {inputOrigin:'bottom-left', mode:'texel-center'})`.
+Choose `inputOrigin` from the source UV convention and `mode` deliberately:
+`texel-center` insets to edge texel centers, while `content-boundary` uses the
+content rectangle boundary. Finish topology and then remap the correct region;
+do not rotate arbitrary charts over a painted atlas and expect the artwork to
+follow. A geometry-wide region binding does not assign separate regions to
+material groups. For repeating grass or directional wood, preserve or project
+UVs and tile a standalone texture instead of forcing every surface into an atlas.
+Neither atlas remapping nor `autoUnwrap` creates painted detail.
+
+For repeated boards or other directional surfaces, align UV length with the
+physical grain direction and retain the chosen texel density. Repeating the same
+narrow UV band can miss a texture's authored detail even when the map is bound.
+Use deliberate deterministic offsets when variation is intended, and inspect a
+close perspective view as well as the assembly; a low-contrast surface alone
+does not prove missing textures or a rendering defect.
+
+When projecting along a chosen grain axis, use an alternate projection for faces
+whose normal is parallel to that axis; otherwise their UV area can collapse to a
+line. Check exported nondegenerate faces for usable UV area, including end faces
+and caps. A separate visible end-grain cap can be intentional, but does not repair
+the underlying face's UVs or justify claiming every chart is valid.
+
 For lengthwise grain or stripes through bends, discover `recipe:directional-sweep-v1`.
 It demonstrates sweep side U around the profile and V along path distance. Preserve
 that convention when editing the path; arbitrary atlas rotations suit baked detail
@@ -337,3 +443,21 @@ box or cylindrical mapping in a geometry-local frame. Fetch its exact Discovery
 contract for rotated frames, partial angular ranges, caps and seam sampling.
 `autoUnwrap` is the separate atlas operation. Removed shape unwrap names do not
 select a preservation or projection fallback.
+
+For a packed baked texture, `await autoUnwrap(geometry, options)` returns new
+buffers and leaves the source unchanged. It duplicates seam vertices and remaps
+vertex colors, skin indices/weights, extra UVs, custom per-vertex attributes
+(1..4 components), and position/normal/color morphs. It retains triangle groups,
+draw range and JSON metadata. It replaces UV0 and drops stale tangents; recompute
+tangents after the final UV layout. Skin bindings and animation remain on the
+mesh/skeleton, so verify an exported posed mesh before relying on deformation.
+
+Default unwrapping recomputes normals. Use `useNormals: true` to preserve authored
+normals and when normal morphs need their original reference frame. The installed
+xatlas adapter supports at most 65,536 vertices both before and after seam
+splitting; split larger geometry. Instanced data and unsupported morph semantics
+fail explicitly. Read the returned `userData.atlas.width/height`; requested
+`resolution` is a target and the packed image can be rectangular. Unwrapping
+cannot preserve the appearance of a texture painted for the old UV0: rebake it.
+For directional wood grain or a tiled wall, prefer existing primitive UVs or
+`projectUV` rather than an arbitrarily rotated atlas.

package/skills/kiln-author-asset/references/projects-and-materials.md

@@ -46,7 +46,25 @@ For library materials, use CLI `material create-preset --file options.json`, the
 `material get MATERIAL_ID REVISION` for the code-ready `portableSpec`. Custom recipes
 use `material procedural --file draft.json`. These CLI paths do not need an internal
 `dist/` import or an extra TypeScript loader. Copy the returned spec into source,
-compile it with `compilePortableMaterialSpecV2`, and supply the exact pins below.
+compile schemaVersion 2 with `compilePortableMaterialSpecV2` or schemaVersion 3
+with `compilePortableMaterialSpecV3`, and supply the exact pins below.
+
+For a texture without geometry, create the material directly; do not invent a
+mesh or project just to save PNG maps. Read `shape:material-draft` with Discovery.
+Unversioned layered drafts keep their existing V1 records. Opt-in
+`schemaVersion:2` material drafts add explicit samplers and a `procedural` V3
+RGBA recipe or `atlas` recipe per map. The material-record version and texture-
+recipe version describe different contracts. V3 recipes support rectangular
+surfaces and alpha; a mask material still needs actual opaque and transparent
+texels to produce a cutout.
+
+An atlas resource source names an exact map `resourceId` plus its material
+revision pin. It does not load arbitrary URLs or paths. Save sources first,
+reuse returned identifiers, then create the atlas. The library resolves the
+transitive closure. Export a saved material with
+`node kiln.mjs material export MATERIAL_ID REVISION --out material.json` and
+import that complete payload with `material import --file material.json`;
+copying only the atlas PNG loses editable sources and named regions.
 
 ## Create and revise a project when useful
 
@@ -104,7 +122,7 @@ editable design guidance, not trusted requirements or release authorization.
 Inspect `kiln_material` with `action: "presets"`, `"list"` or `"get"`. CLI equivalents
 are `material presets`, `material list`, and `material get ID REVISION`. Creation
 and import preserve creator, license, recipe/seed and source provenance. Copy the
-returned `portableSpec` into source and call `compilePortableMaterialSpecV2(spec)`;
+returned `portableSpec` into source and select its matching V2 or V3 compiler;
 the host provides the selected immutable map bytes before evaluating source.
 
 A pin uses the returned material ID as `resourceId`; both hashes equal its returned
@@ -129,9 +147,21 @@ already pins replaces the project's for that call. Update the lock deliberately
 changing shared art direction. A missing resource or mismatched hash must be resolved
 before building; neither source URLs nor material names authorize an implicit download.
 
+Keep project defaults to a deliberate shared authoring palette, not every material
+used anywhere in a growing inventory. An evaluation currently resolves at most 16
+resources, including transitive dependencies; call-level pins replace matching
+defaults but do not remove unrelated defaults. If that merged context exceeds the
+budget, use an explicit standalone operation with the asset's complete small pin
+set, then link the exact saved revision to the project. Refine the project defaults
+through a deliberate revision update. Saved asset closures retain their own exact
+materials independently of those authoring defaults.
+
 Material records carry physical repeat scale, but the author controls mesh UV scale.
 Review seams, repeats, roughness and normal strength on representative geometry with
 actual GPU views. A project palette is guidance, not automatic recoloring.
+Keep explicit nearest sampling for a requested pixel texture local to that
+material. Smooth or physically based materials may need linear filtering and
+mipmaps; neither a project nor an atlas implies one sampling policy.
 
 ## Retain and deliver the work
 

package/skills/kiln-compose-scene/references/runtime-scenes.md

@@ -38,6 +38,19 @@ Check closed, open and moving door states and safe dismounts. A path over a rive
 needs a real supporting collision surface. Broad-phase bounds alone do not prove
 that a person can pass through an opening.
 
+Exercise each one-shot interaction at least twice, including after its action has
+finished and clamped. In Three AnimationMixer, seeking a completed paused action
+does not restart it; explicitly reset/play for a new use while preserving the
+action during the same use. Tie damage or resource consumption to the reviewed
+contact event and check range or interruption again there.
+
+Visual gaps and gameplay barriers are different scene contracts. A sparse gate
+or boarded opening can have visible gaps while blocking an actor or melee reach.
+Use the chosen interaction rule and the opening's actual frame for that test;
+a single ray through decorative triangles cannot establish protection. Keep
+project-specific damage, collision and barrier rules out of standalone asset
+requirements. Compare the actor path, visual geometry and interaction result.
+
 For a follow camera, run its actual update and controls during passage checks.
 A controller-only loop can pass while the rendered camera hides the actor behind
 an eave or lintel. Inspect the animated head and accessories, not only a clear
@@ -240,6 +253,12 @@ placements the application knows will remain fixed. Keep animated and controlled
 hierarchies live, and restore or rebuild the cache before placement or variant
 changes. Check exact world transforms, visibility and culling in the consumer.
 
+For spatial instance batches, changing a source root's visibility must also
+update its batch membership and culling bounds. Synchronize on a relevant change;
+avoid scanning every immutable source each frame. Test hidden and restored
+instances, preserving interactive or independently moving objects outside the
+static batch.
+
 Hiding draws does not necessarily stop CPU animation. Count evaluated rigs and
 motion owners as well as visible actors. A projected-error selector may demand
 exact poses behind the camera. For a qualified shared clip, the consumer can

package/skills/kiln-qa-asset/references/integration-checks.md

@@ -19,6 +19,27 @@ Kiln authors metres, +X forward, +Y up, +Z right. Confirm importer conversion in
 
 Source refs name source revisions. They do not identify arbitrary externally modified GLB bytes. Track the exact exported file used for integration.
 
+For a first-person presentation, review the held assembly from its actual animated
+eye frame at the destination field of view and aspect ratio. Inspect ready, lift,
+contact and recovery; an external pose can fit both hands while obscuring the
+crosshair or passing through the camera. Keep any view-specific presentation in
+the asset or consuming scene selected by the brief, not in universal rig defaults.
+
+Measure deformed surface vertices as well as contact locators. Planted foot markers
+do not rule out a sole, claw or swinging hand passing below the ground. Sample
+between animation keys and between the usual quarter poses; record the sampling
+density and tolerance rather than claiming a continuous guarantee from a few views.
+
+For atlas cutouts, first inspect the exact saved sheet on light, dark and checker
+backgrounds for alpha, edge RGB and region placement. Raw map pixels establish
+image content, not shaded material appearance. Then inspect the exported asset
+with the destination's actual sampler, alpha cutoff, sidedness and lighting,
+including receding and moving views. A still nearest-filtered preview cannot
+clear mip bleed, shimmering or disappearing thin details. Keep material revision,
+atlas region and compiler identity with the reviewed file. Structural UV-domain
+checks cannot prove intended corner orientation without source correspondence;
+use an asymmetric corner fixture when qualifying a mapping pipeline.
+
 `composeSceneGLB` defaults to static composition (`keepAnimations: false`). Explicitly keep animations when required. Its material optimization policy can change scene material organization; choose it deliberately, then inspect the result. Warnings can report skipped inputs, so successful export alone does not prove every required asset was included.
 
 Do not invent a universal performance cap. State the destination, tested conditions, and material limits of the evidence.
@@ -40,8 +61,13 @@ closure; flush rest-pose joins can separate or expose caps during motion.
 
 For articulated actors carrying equipment, inspect the limb bend as well as hand
 attachment closure. A hand can reach its target while the elbow folds through the
-body. Include headgear and carried items in intermediate-pose clearance checks,
-and inspect cables or strings at their moving attachment points. A convincing
+body. Include headgear and carried items in intermediate-pose clearance checks.
+Verify palm/finger orientation and wrist continuity against the full handle.
+Sample the interpolated skinned surfaces as well as joint centres; shoulder
+weights can create a pointed cap or a sleeve crossing the torso despite valid
+attachment distances. Inspect the actual first-person view when the destination
+requires it, without treating camera offsets as a repair for an invalid grip.
+Also inspect cables or strings at their moving attachment points. A convincing
 draw or tensioning action needs compatible equipment deformation, not just a
 moving hand and an arbitrarily stretched connector. Keep controller choices and
 equipment fit in the destination; a scene repair need not change the saved master.
@@ -79,6 +105,15 @@ instancing, so it does not predict complete `full` output or GPU speed. Check
 Measure actual destination draws by anchor, material and pass after export, then
 exercise the interactions and attachments those anchors protect.
 
+For a composed scene, inventory every placed asset family and conditional visible
+state, then verify actual submitted draws from representative views. Report
+pack-only assets separately. A source primitive count is not a visible draw
+count; one mesh may have several material groups, and repeated geometry may be
+instanced into spatial batches. Compare skin counts and material/texture variants
+when a low-triangle asset still contributes many submissions. Separate coverage
+snapshots from timed benchmarks and preserve exact camera, viewport and quality
+settings when comparing runtime derivatives.
+
 Read each observation's `evidence` and sampling/omission counts.
 `mirroredTangents` identifies static tangent-bearing parts with mirrored transforms;
 it does not establish a shading defect. `coplanarParts` samples triangle overlaps

package/src/asset-materials-node.ts

@@ -1,43 +1,25 @@
 /** Exact saved material closure, shared by standalone asset and project delivery. */
 import type { AssetRecord } from './assets';
-import { validateAssetMaterialClosure } from './assets';
+import { assetMaterialRootManifests, validateAssetMaterialClosure } from './assets';
 import {
-  canonicalMaterialJson,
   MATERIAL_LIBRARY_LIMITS,
   type MaterialLibrary,
-  type MaterialManifestV1,
-  type MaterialRecordV1,
+  type MaterialManifest,
+  type MaterialRecord,
 } from './material-library';
 import {
   decodeMaterialLibraryPayload,
-  validateMaterialManifestIdentity,
+  validateMaterialManifestIdentityAny,
+  resolveMaterialRecordClosure,
 } from './material-library-node';
 
-export function dependencyManifests(asset: AssetRecord): MaterialManifestV1[] {
-  const result = new Map<string, MaterialManifestV1>();
-  for (const raw of asset.manifest.build?.dependencies ?? []) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-      throw new Error('Invalid saved asset dependency');
-    const dependency = raw as Record<string, unknown>;
-    if (dependency.kind === 'kiln.material.v1') {
-      if (dependency.delivery !== 'runtime')
-        throw new Error('Invalid material dependency delivery');
-      const manifest = validateMaterialManifestIdentity(dependency.manifest);
-      result.set(`${manifest.materialId}/${manifest.revisionId}`, manifest);
-      if (result.size > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
-        throw new Error('Saved asset material dependency count exceeds limit');
-    } else if (dependency.delivery === 'runtime')
-      throw new Error(
-        `Unsupported runtime dependency: ${String(dependency.resourceId ?? 'unknown')}`,
-      );
-    else if (dependency.delivery !== 'embedded')
-      throw new Error('Unsupported saved asset dependency');
-  }
-  if (asset.manifest.build?.rebuild === 'external-dependencies-required' && !result.size)
+export function dependencyManifests(asset: AssetRecord): MaterialManifest[] {
+  const result = assetMaterialRootManifests(asset).map(validateMaterialManifestIdentityAny);
+  if (asset.manifest.build?.rebuild === 'external-dependencies-required' && !result.length)
     throw new Error('Saved asset has unrecorded external dependencies');
   let bytes = 0;
   let pixels = 0;
-  for (const manifest of result.values())
+  for (const manifest of result)
     for (const map of manifest.maps) {
       bytes += map.bytes;
       pixels += map.width * map.height;
@@ -47,32 +29,43 @@ export function dependencyManifests(asset: AssetRecord): MaterialManifestV1[] {
     pixels > MATERIAL_LIBRARY_LIMITS.maxPayloadPixels
   )
     throw new Error('Saved asset material allocation exceeds limit');
-  return [...result.values()];
+  return result;
 }
 
 export async function resolveSavedAssetMaterials(
   asset: AssetRecord,
   library?: MaterialLibrary,
-): Promise<MaterialRecordV1[]> {
+): Promise<MaterialRecord[]> {
   const dependencies = dependencyManifests(asset);
   if (asset.materialResources) {
     validateAssetMaterialClosure(asset, true);
     return decodeMaterialLibraryPayload(asset.materialResources);
   }
-  return Promise.all(
-    dependencies.map(async (manifest) => {
-      try {
-        if (!library) throw new Error('No material library configured');
-        const record = await library.read(manifest.materialId, manifest.revisionId);
-        if (canonicalMaterialJson(record.manifest) !== canonicalMaterialJson(manifest))
-          throw new Error('Saved dependency manifest mismatch');
-        return record;
-      } catch (error) {
-        throw new Error(
-          `Locked asset material unavailable: ${manifest.materialId} at ${manifest.revisionId}`,
-          { cause: error },
-        );
-      }
-    }),
-  );
+  if (!dependencies.length) return [];
+  if (!library)
+    throw new Error('Locked asset material unavailable: No material library configured');
+  const roots = new Map(dependencies.map((m) => [`${m.materialId}/${m.revisionId}`, m]));
+  const wrap = async <T>(id: string, revision: string, load: () => Promise<T>): Promise<T> => {
+    try {
+      return await load();
+    } catch (error) {
+      throw new Error(`Locked asset material unavailable: ${id} at ${revision}`, { cause: error });
+    }
+  };
+  return resolveMaterialRecordClosure(dependencies, {
+    readManifest: async (id, revision) =>
+      wrap(id, revision, async () => {
+        const root = roots.get(`${id}/${revision}`);
+        if (root) return root;
+        if (!library.readManifest)
+          throw new Error('Material library requires manifest-first dependency capability');
+        return library.readManifest(id, revision);
+      }),
+    read: async (id, revision) =>
+      wrap(id, revision, () =>
+        library.readRecordFiles
+          ? library.readRecordFiles(id, revision)
+          : library.read(id, revision),
+      ),
+  });
 }

package/src/assets-node.ts

@@ -18,7 +18,11 @@ import {
   type AssetManifest,
   type AssetRecord,
 } from './assets';
-import type { MaterialLibrary, MaterialRecordV1 } from './material-library';
+import {
+  canonicalMaterialJson,
+  type MaterialLibrary,
+  type MaterialRecord,
+} from './material-library';
 import { FileMaterialLibrary, createMaterialLibraryPayload } from './material-library-node';
 import { dependencyManifests, resolveSavedAssetMaterials } from './asset-materials-node';
 import { renameDirectoryAtomically } from './atomic-directory';
@@ -230,7 +234,9 @@ export class FileAssetLibrary implements AssetLibrary {
             (raw) =>
               raw &&
               typeof raw === 'object' &&
-              (raw as Record<string, unknown>).kind === 'kiln.material.v1',
+              ['kiln.material.v1', 'kiln.material.v2'].includes(
+                String((raw as Record<string, unknown>).kind),
+              ),
           ),
       ),
     );
@@ -243,7 +249,7 @@ export class FileAssetLibrary implements AssetLibrary {
     if (resourceBytes > ASSET_LIMIT)
       throw new Error('Asset material import exceeds allocation limit');
     const prepared: AssetRecord[] = [];
-    const resources = new Map<string, MaterialRecordV1>();
+    const resources = new Map<string, MaterialRecord>();
     // Validate the whole input before writing anything; per-revision commits are atomic.
     for (const record of records) {
       await verifyAssetRecord(record);
@@ -256,11 +262,22 @@ export class FileAssetLibrary implements AssetLibrary {
             (raw) =>
               raw &&
               typeof raw === 'object' &&
-              (raw as Record<string, unknown>).kind === 'kiln.material.v1',
+              ['kiln.material.v1', 'kiln.material.v2'].includes(
+                String((raw as Record<string, unknown>).kind),
+              ),
           ))
       ) {
         const materials = await resolveSavedAssetMaterials(record, this.materials);
-        for (const material of materials) resources.set(material.manifest.revisionId, material);
+        for (const material of materials) {
+          const key = `${material.manifest.materialId}/${material.manifest.revisionId}`;
+          const previous = resources.get(key);
+          if (
+            previous &&
+            canonicalMaterialJson(previous.manifest) !== canonicalMaterialJson(material.manifest)
+          )
+            throw new Error('Conflicting asset material dependencies');
+          resources.set(key, material);
+        }
         prepared.push({
           ...record,
           materialResources: await createMaterialLibraryPayload(materials),