@instruktlabs/kiln 1.2.1 → 1.2.3

package/lib/procedural-texture.js

@@ -37,179 +37,52 @@
  * still catches.
  */
 import * as THREE from 'three';
-import { ProceduralTextureError, canonicalProceduralTextureJsonV2, canonicalizeProceduralTextureSpecV2, hashProceduralTextureSpecV2, } from "./procedural-material-v2.js";
+import { compileProceduralTextureSpecV2 } from "./procedural-texture-v2-compiler.js";
+import { compileProceduralTextureSpecV3 } from "./procedural-texture-v3.js";
+import { ProceduralTextureError, } from "./procedural-material-v2.js";
 export { MAX_NOISE_OCTAVES, MAX_PORTABLE_MATERIAL_TEXELS, MAX_PORTABLE_MATERIAL_TEXTURES, MAX_PROCEDURAL_LAYERS, MAX_PROCEDURAL_NAME_LENGTH, MAX_PROCEDURAL_PATTERN_COUNT, MAX_PROCEDURAL_SIZE, MIN_PROCEDURAL_SIZE, PORTABLE_MATERIAL_SPEC_VERSION, PROCEDURAL_TEXTURE_SPEC_VERSION, ProceduralTextureError, canonicalProceduralTextureJsonV2, canonicalizePortableMaterialSpecV2, canonicalizeProceduralTextureSpecV2, hashProceduralTextureSpecV2, migrateProceduralTextureSpecV1, } from "./procedural-material-v2.js";
-// -----------------------------------------------------------------------------
-// Deterministic value noise
-// -----------------------------------------------------------------------------
-/**
- * Integer hash of a lattice coordinate. Not a cryptographic hash — it only has
- * to decorrelate neighbouring integers and return the same value forever.
- */
-function hash2(x, y, seed) {
-    let h = (Math.imul(x, 374761393) + Math.imul(y, 668265263) + Math.imul(seed, 1274126177)) | 0;
-    h = h ^ (h >>> 13);
-    h = Math.imul(h, 1274126177) | 0;
-    h = h ^ (h >>> 16);
-    return (h >>> 0) / 4294967296;
-}
-const smoothstep = (t) => t * t * (3 - 2 * t);
-/**
- * Value noise on a lattice that wraps at `period`, so the result tiles.
- * `period` is in lattice cells, and both axes use the same one.
- */
-function valueNoise(u, v, period, seed) {
-    const x = u * period;
-    const y = v * period;
-    const xi = Math.floor(x);
-    const yi = Math.floor(y);
-    const xf = x - xi;
-    const yf = y - yi;
-    // Wrapping the lattice index (not the sample point) is what makes it tile:
-    // the cell to the right of the last one is the first one again.
-    const wrap = (n) => ((n % period) + period) % period;
-    const x0 = wrap(xi);
-    const y0 = wrap(yi);
-    const x1 = wrap(xi + 1);
-    const y1 = wrap(yi + 1);
-    const sx = smoothstep(xf);
-    const sy = smoothstep(yf);
-    const n00 = hash2(x0, y0, seed);
-    const n10 = hash2(x1, y0, seed);
-    const n01 = hash2(x0, y1, seed);
-    const n11 = hash2(x1, y1, seed);
-    const top = n00 + sx * (n10 - n00);
-    const bottom = n01 + sx * (n11 - n01);
-    return top + sy * (bottom - top);
-}
-function fbm(u, v, period, octaves, seed) {
-    let sum = 0;
-    let amplitude = 1;
-    let total = 0;
-    let p = period;
-    for (let o = 0; o < octaves; o++) {
-        sum += valueNoise(u, v, p, seed + o * 101) * amplitude;
-        total += amplitude;
-        amplitude *= 0.5;
-        // Doubling the period keeps every octave tileable at the base period.
-        p *= 2;
-    }
-    return total > 0 ? sum / total : 0;
-}
-// -----------------------------------------------------------------------------
-// Layer evaluation
-// -----------------------------------------------------------------------------
-const rgbOf = (color) => [
-    (color >> 16) & 0xff,
-    (color >> 8) & 0xff,
-    color & 0xff,
-];
-const lerp = (a, b, t) => a + (b - a) * t;
-/** Rotate normalized coords about the center so angled patterns stay centered. */
-function project(u, v, angleDeg) {
-    const a = (angleDeg * Math.PI) / 180;
-    return (u - 0.5) * Math.cos(a) + (v - 0.5) * Math.sin(a) + 0.5;
-}
-/** Evaluate one layer at a normalized coordinate, returning 0-255 RGB. */
-function evalLayer(layer, u, v) {
-    switch (layer.op) {
-        case 'solid':
-            return rgbOf(layer.color);
-        case 'checker': {
-            const cx = Math.floor(u * layer.squares);
-            const cy = Math.floor(v * layer.squares);
-            return rgbOf((cx + cy) % 2 === 0 ? layer.colorA : layer.colorB);
-        }
-        case 'stripes': {
-            const t = project(u, v, layer.angleDeg);
-            return rgbOf(Math.floor(t * layer.count) % 2 === 0 ? layer.colorA : layer.colorB);
-        }
-        case 'gradient': {
-            const t = Math.min(1, Math.max(0, project(u, v, layer.angleDeg)));
-            const from = rgbOf(layer.from);
-            const to = rgbOf(layer.to);
-            return [lerp(from[0], to[0], t), lerp(from[1], to[1], t), lerp(from[2], to[2], t)];
-        }
-        case 'bricks': {
-            const row = Math.floor(v * layer.rows);
-            // Offset alternate rows, wrapping into [0,1) so the pattern still tiles.
-            const shifted = (u + (row % 2 === 0 ? 0 : layer.stagger / layer.cols) + 1) % 1;
-            const inCol = (shifted * layer.cols) % 1;
-            const inRow = (v * layer.rows) % 1;
-            const isMortar = inCol < layer.mortarWidth ||
-                inCol > 1 - layer.mortarWidth ||
-                inRow < layer.mortarWidth ||
-                inRow > 1 - layer.mortarWidth;
-            return rgbOf(isMortar ? layer.mortar : layer.brick);
-        }
-        case 'noise': {
-            const n = fbm(u, v, layer.scale, layer.octaves, layer.seed);
-            const a = rgbOf(layer.colorA);
-            const b = rgbOf(layer.colorB);
-            return [lerp(a[0], b[0], n), lerp(a[1], b[1], n), lerp(a[2], b[2], n)];
-        }
-    }
-}
-function blendChannel(mode, base, top) {
-    const b = base / 255;
-    const t = top / 255;
-    let out;
-    switch (mode) {
-        case 'multiply':
-            out = b * t;
-            break;
-        case 'screen':
-            out = 1 - (1 - b) * (1 - t);
-            break;
-        case 'overlay':
-            out = b < 0.5 ? 2 * b * t : 1 - 2 * (1 - b) * (1 - t);
-            break;
-        default:
-            out = t;
-    }
-    return out * 255;
-}
-/** Validate, canonicalize, and compile one texture without constructing Three.js state. */
-export function compileProceduralTextureSpecV2(input) {
-    const spec = canonicalizeProceduralTextureSpecV2(input);
-    const { size, layers } = spec;
-    const data = new Uint8Array(size * size * 4);
-    for (let y = 0; y < size; y++) {
-        // Sample at texel centers so a pattern with N divisions lands on exact
-        // boundaries instead of drifting half a texel.
-        const v = (y + 0.5) / size;
-        for (let x = 0; x < size; x++) {
-            const u = (x + 0.5) / size;
-            let r = 0;
-            let g = 0;
-            let b = 0;
-            for (const [i, layer] of layers.entries()) {
-                const [lr, lg, lb] = evalLayer(layer, u, v);
-                if (i === 0) {
-                    r = lr;
-                    g = lg;
-                    b = lb;
-                    continue;
-                }
-                r = lerp(r, blendChannel(layer.blend, r, lr), layer.opacity);
-                g = lerp(g, blendChannel(layer.blend, g, lg), layer.opacity);
-                b = lerp(b, blendChannel(layer.blend, b, lb), layer.opacity);
-            }
-            const o = (y * size + x) * 4;
-            data[o] = Math.max(0, Math.min(255, Math.round(r)));
-            data[o + 1] = Math.max(0, Math.min(255, Math.round(g)));
-            data[o + 2] = Math.max(0, Math.min(255, Math.round(b)));
-            data[o + 3] = 255;
-        }
-    }
-    return {
-        spec,
-        pixels: data,
-        canonicalJson: canonicalProceduralTextureJsonV2(spec),
-        recipeHash: hashProceduralTextureSpecV2(spec),
-    };
+export * from "./procedural-texture-v3.js";
+/** Dispatch never invokes an input accessor; absent/undefined retains V1 compatibility. */
+export function proceduralTextureSchemaVersion(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new ProceduralTextureError('proceduralTexture requires a plain JSON object.', 'PROCEDURAL_TEXTURE_V3_CONTRACT');
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new ProceduralTextureError('proceduralTexture requires a plain JSON object.', 'PROCEDURAL_TEXTURE_V3_CONTRACT');
+    const descriptor = Object.getOwnPropertyDescriptor(input, 'schemaVersion');
+    if (descriptor && (!descriptor.enumerable || !('value' in descriptor)))
+        throw new ProceduralTextureError('proceduralTexture.schemaVersion must be a JSON data field.', 'PROCEDURAL_TEXTURE_V3_CONTRACT');
+    const version = descriptor?.value;
+    if (version === undefined || version === 1)
+        return 1;
+    if (version === 2 || version === 3)
+        return version;
+    throw new ProceduralTextureError('proceduralTexture.schemaVersion must be 1, 2 or 3.', 'PROCEDURAL_TEXTURE_V3_CONTRACT');
 }
+export { compileProceduralTextureSpecV2 } from "./procedural-texture-v2-compiler.js";
 export function proceduralTexture(spec) {
+    if (proceduralTextureSchemaVersion(spec) === 3) {
+        const compiled = compileProceduralTextureSpecV3(spec);
+        const { width, height, usage, name } = compiled.spec;
+        const tex = new THREE.DataTexture(compiled.pixels, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+        if (name)
+            tex.name = name;
+        tex.colorSpace =
+            usage === 'albedo' || usage === 'emissive' ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+        tex.wrapS = THREE.RepeatWrapping;
+        tex.wrapT = THREE.RepeatWrapping;
+        tex.minFilter = THREE.LinearMipmapLinearFilter;
+        tex.magFilter = THREE.LinearFilter;
+        tex.generateMipmaps = true;
+        tex.needsUpdate = true;
+        tex.userData['kilnProcedural'] = {
+            ...compiled.spec,
+            canonicalJson: compiled.canonicalJson,
+            recipeHash: compiled.recipeHash,
+            compilerId: compiled.compilerId,
+        };
+        return tex;
+    }
     const compiled = compileProceduralTextureSpecV2(spec);
     const { size, usage, name, layers } = compiled.spec;
     const tex = new THREE.DataTexture(compiled.pixels, size, size, THREE.RGBAFormat, THREE.UnsignedByteType);

package/lib/project-bundle-node.d.ts

@@ -1,7 +1,7 @@
 import type { AssetLibrary, AssetRecord } from "./assets.js";
 import type { FileWorkspace } from "./workspace-node.js";
 import { type ProjectRevision } from "./projects.js";
-export declare function resolveAssetMaterialPayload(workspace: FileWorkspace, asset: AssetRecord): Promise<import("./material-library.js").MaterialLibraryPayloadV1>;
+export declare function resolveAssetMaterialPayload(workspace: FileWorkspace, asset: AssetRecord): Promise<import("./material-library.js").MaterialLibraryPayload>;
 export declare function exportWorkspaceProjectBundle(workspace: FileWorkspace, library: AssetLibrary, projectId: string, options?: {
     revisionId?: string;
     profile?: 'editable' | 'runtime';

package/lib/project-bundle-node.js

@@ -4,9 +4,9 @@ import { link, lstat, mkdir, readFile, realpath, unlink, writeFile } from 'node:
 import { join, relative, resolve, sep } from 'node:path';
 import { verifyAssetRecord } from "./assets-node.js";
 import { projectDraftSchema, projectIdSchema, ProjectExistsError, ProjectNotFoundError, } from "./projects.js";
-import { canonicalMaterialJson } from "./material-library.js";
+import { canonicalMaterialJson, MATERIAL_LIBRARY_LIMITS, } from "./material-library.js";
 import { dependencyManifests, resolveSavedAssetMaterials } from "./asset-materials-node.js";
-import { createMaterialLibraryPayload, verifyMaterialRecordV1 } from "./material-library-node.js";
+import { createMaterialLibraryPayload, verifyMaterialRecord, resolveMaterialRecordClosure, validateMaterialManifestIdentityAny, } from "./material-library-node.js";
 import { PROJECT_BUNDLE_LIMITS, decodeProjectBundle, encodeProjectBundle, projectBundleHash, } from "./project-bundle.js";
 async function assetMaterials(workspace, asset) {
     return resolveSavedAssetMaterials(asset, workspace.materials);
@@ -32,25 +32,76 @@ export async function exportWorkspaceProjectBundle(workspace, library, projectId
             record: await library.read(item.asset.collectionId, item.asset.assetId, item.asset.revisionId),
         });
     }
-    const materials = new Map();
+    let materials = [];
     if (profile === 'editable') {
+        const roots = new Map();
+        const assetRoots = new Set();
+        const embedded = new Map();
+        const addRoot = (manifest) => {
+            const key = `${manifest.materialId}/${manifest.revisionId}`;
+            const previous = roots.get(key);
+            if (previous && canonicalMaterialJson(previous) !== canonicalMaterialJson(manifest))
+                throw new Error('Conflicting project material identity');
+            roots.set(key, manifest);
+        };
         for (const dependency of project.materialDependencies) {
             if (dependency.sha256 !== dependency.revisionId)
                 throw new Error(`Material lock hash mismatch: ${dependency.resourceId}`);
-            let record;
+            let manifest;
             try {
-                record = await workspace.materials.read(dependency.resourceId, dependency.revisionId);
+                manifest = await workspace.materials.readManifest(dependency.resourceId, dependency.revisionId);
             }
             catch (error) {
                 throw new Error(`Locked project material unavailable: ${dependency.resourceId} at ${dependency.revisionId}`, { cause: error });
             }
-            materials.set(`${record.manifest.materialId}/${record.manifest.revisionId}`, record);
+            addRoot(manifest);
         }
-        for (const asset of assets)
-            for (const record of await assetMaterials(workspace, asset.record))
-                materials.set(`${record.manifest.materialId}/${record.manifest.revisionId}`, record);
+        for (const asset of assets) {
+            for (const manifest of dependencyManifests(asset.record)) {
+                addRoot(manifest);
+                assetRoots.add(`${manifest.materialId}/${manifest.revisionId}`);
+            }
+            for (const wire of asset.record.materialResources?.records ?? []) {
+                const manifest = validateMaterialManifestIdentityAny(wire.manifest);
+                const key = `${manifest.materialId}/${manifest.revisionId}`;
+                const previous = embedded.get(key);
+                if (previous &&
+                    (canonicalMaterialJson(previous.manifest) !== canonicalMaterialJson(manifest) ||
+                        canonicalMaterialJson(previous.files) !== canonicalMaterialJson(wire.files)))
+                    throw new Error('Conflicting embedded material identity');
+                embedded.set(key, { manifest, files: wire.files });
+            }
+        }
+        const lockedRead = async (id, revision, read) => {
+            try {
+                return await read();
+            }
+            catch (error) {
+                throw new Error(`Locked ${assetRoots.has(`${id}/${revision}`) ? 'asset' : 'project'} material unavailable: ${id} at ${revision}`, { cause: error });
+            }
+        };
+        materials = await resolveMaterialRecordClosure([...roots.values()], {
+            readManifest: async (id, revision) => embedded.get(`${id}/${revision}`)?.manifest ??
+                lockedRead(id, revision, () => workspace.materials.readManifest(id, revision)),
+            read: async (id, revision) => {
+                const wire = embedded.get(`${id}/${revision}`);
+                if (!wire)
+                    return lockedRead(id, revision, () => workspace.materials.readRecordFiles(id, revision));
+                return {
+                    manifest: wire.manifest,
+                    files: Object.fromEntries(Object.entries(wire.files).map(([name, value]) => [
+                        name,
+                        new Uint8Array(Buffer.from(value, 'base64')),
+                    ])),
+                };
+            },
+        }, {
+            maxRecords: 1024,
+            maxBytes: PROJECT_BUNDLE_LIMITS.maxBytes,
+            maxPixels: 1024 * MATERIAL_LIBRARY_LIMITS.maxRecordPixels,
+        });
     }
-    return encodeProjectBundle({ project, assets, materials: [...materials.values()] }, profile);
+    return encodeProjectBundle({ project, assets, materials }, profile);
 }
 async function retainArchive(workspace, bytes, digest) {
     const root = resolve(workspace.root);
@@ -117,7 +168,7 @@ export async function importWorkspaceProjectBundle(workspace, library, bytes, op
         record,
     ]));
     for (const record of decoded.materials)
-        await verifyMaterialRecordV1(record);
+        await verifyMaterialRecord(record, { materials: decoded.materials });
     for (const asset of decoded.assets) {
         await verifyAssetRecord(asset.record);
         for (const manifest of dependencyManifests(asset.record)) {
@@ -166,8 +217,14 @@ export async function importWorkspaceProjectBundle(workspace, library, bytes, op
     // Nothing above performs writes. Verified immutable resources can safely survive a
     // later disk failure or project-ID conflict; imports never overwrite other revisions.
     await retainArchive(workspace, snapshot, digest);
-    for (let i = 0; i < decoded.materials.length; i += 100)
-        await workspace.materials.import(decoded.materials.slice(i, i + 100));
+    const newMaterialContext = decoded.materials.some((record) => record.manifest.schemaVersion === 2);
+    for (let i = 0; i < decoded.materials.length; i += 100) {
+        const batch = decoded.materials.slice(i, i + 100);
+        if (newMaterialContext)
+            await workspace.materials.import(batch, { materials: decoded.materials });
+        else
+            await workspace.materials.import(batch);
+    }
     const records = [...destinationRecords.values()];
     for (let i = 0; i < records.length; i += 100)
         await library.import(options.collectionId, records.slice(i, i + 100));

package/lib/project-bundle.d.ts

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 import { type AssetRecord } from "./assets.js";
 import { type ProjectRevision } from "./projects.js";
-import { type MaterialRecordV1 } from "./material-library.js";
+import { type MaterialRecord } from "./material-library.js";
 export declare const PROJECT_BUNDLE_LIMITS: Readonly<{
     maxBytes: number;
     maxArchiveBytes: number;
@@ -38,7 +38,95 @@ export declare const projectBundleManifestSchema: z.ZodObject<{
         bytes: z.ZodNumber;
     }, z.core.$strict>>;
 }, z.core.$strict>;
-export type ProjectBundleManifest = z.infer<typeof projectBundleManifestSchema>;
+export declare const projectBundleManifestV2Schema: z.ZodObject<{
+    profile: z.ZodEnum<{
+        editable: "editable";
+        runtime: "runtime";
+    }>;
+    editable: z.ZodBoolean;
+    resourceClosure: z.ZodEnum<{
+        "embedded-runtime-only": "embedded-runtime-only";
+        "normalized-maps-and-procedural-recipes": "normalized-maps-and-procedural-recipes";
+    }>;
+    referenceMediaIncluded: z.ZodLiteral<false>;
+    originalAcquisitionFilesIncluded: z.ZodLiteral<false>;
+    assets: z.ZodArray<z.ZodObject<{
+        inventoryId: z.ZodString;
+        collectionId: z.ZodString;
+        assetId: z.ZodString;
+        revisionId: z.ZodString;
+        canonicalGlbSha256: z.ZodString;
+    }, z.core.$strict>>;
+    materials: z.ZodArray<z.ZodObject<{
+        materialId: z.ZodString;
+        revisionId: z.ZodString;
+    }, z.core.$strict>>;
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>>;
+    version: z.ZodLiteral<"kiln.project-bundle.v2">;
+}, z.core.$strict>;
+export declare const projectBundleManifestAnySchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<"kiln.project-bundle.v1">;
+    profile: z.ZodEnum<{
+        editable: "editable";
+        runtime: "runtime";
+    }>;
+    editable: z.ZodBoolean;
+    resourceClosure: z.ZodEnum<{
+        "embedded-runtime-only": "embedded-runtime-only";
+        "normalized-maps-and-procedural-recipes": "normalized-maps-and-procedural-recipes";
+    }>;
+    referenceMediaIncluded: z.ZodLiteral<false>;
+    originalAcquisitionFilesIncluded: z.ZodLiteral<false>;
+    assets: z.ZodArray<z.ZodObject<{
+        inventoryId: z.ZodString;
+        collectionId: z.ZodString;
+        assetId: z.ZodString;
+        revisionId: z.ZodString;
+        canonicalGlbSha256: z.ZodString;
+    }, z.core.$strict>>;
+    materials: z.ZodArray<z.ZodObject<{
+        materialId: z.ZodString;
+        revisionId: z.ZodString;
+    }, z.core.$strict>>;
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    profile: z.ZodEnum<{
+        editable: "editable";
+        runtime: "runtime";
+    }>;
+    editable: z.ZodBoolean;
+    resourceClosure: z.ZodEnum<{
+        "embedded-runtime-only": "embedded-runtime-only";
+        "normalized-maps-and-procedural-recipes": "normalized-maps-and-procedural-recipes";
+    }>;
+    referenceMediaIncluded: z.ZodLiteral<false>;
+    originalAcquisitionFilesIncluded: z.ZodLiteral<false>;
+    assets: z.ZodArray<z.ZodObject<{
+        inventoryId: z.ZodString;
+        collectionId: z.ZodString;
+        assetId: z.ZodString;
+        revisionId: z.ZodString;
+        canonicalGlbSha256: z.ZodString;
+    }, z.core.$strict>>;
+    materials: z.ZodArray<z.ZodObject<{
+        materialId: z.ZodString;
+        revisionId: z.ZodString;
+    }, z.core.$strict>>;
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>>;
+    version: z.ZodLiteral<"kiln.project-bundle.v2">;
+}, z.core.$strict>]>;
+export type ProjectBundleManifestV1 = z.infer<typeof projectBundleManifestSchema>;
+export type ProjectBundleManifestV2 = z.infer<typeof projectBundleManifestV2Schema>;
+export type ProjectBundleManifest = ProjectBundleManifestV1 | ProjectBundleManifestV2;
 export interface ProjectBundleAsset {
     inventoryId: string;
     collectionId: string;
@@ -46,7 +134,7 @@ export interface ProjectBundleAsset {
 }
 export interface ProjectBundleInput {
     project: ProjectRevision;
-    materials: MaterialRecordV1[];
+    materials: MaterialRecord[];
     assets: ProjectBundleAsset[];
 }
 export interface DecodedProjectBundle extends ProjectBundleInput {

package/lib/project-bundle.js

@@ -4,7 +4,7 @@ import { zipSync, unzipSync } from 'three/addons/libs/fflate.module.js';
 import { assetIdSchema, assetManifestSchema, validateRecordShape, validateAssetGlb, } from "./assets.js";
 import { exportAssetGlb } from "./asset-export.js";
 import { MAX_PROJECT_REVISIONS, projectRevisionSchema } from "./projects.js";
-import { canonicalMaterialJson, materialManifestSchema, validateMaterialRecordShape, } from "./material-library.js";
+import { canonicalMaterialJson, materialManifestSchema, materialManifestAnySchema, materialRecordDependencyPins, validateMaterialRecordShapeAny, } from "./material-library.js";
 export const PROJECT_BUNDLE_LIMITS = Object.freeze({
     maxBytes: 256 * 1024 * 1024,
     maxArchiveBytes: 264 * 1024 * 1024,
@@ -49,6 +49,13 @@ export const projectBundleManifestSchema = z
         .strict()),
 })
     .strict();
+export const projectBundleManifestV2Schema = projectBundleManifestSchema.extend({
+    version: z.literal('kiln.project-bundle.v2'),
+});
+export const projectBundleManifestAnySchema = z.union([
+    projectBundleManifestSchema,
+    projectBundleManifestV2Schema,
+]);
 const encoder = new TextEncoder();
 const decoder = new TextDecoder('utf-8', { fatal: true });
 const bytesOf = (value) => encoder.encode(JSON.stringify(value));
@@ -77,7 +84,7 @@ async function verifyAsset(record) {
             throw new Error('Asset file hash mismatch');
 }
 async function verifyMaterial(record) {
-    const manifest = validateMaterialRecordShape(record);
+    const manifest = validateMaterialRecordShapeAny(record);
     const { revisionId, ...payload } = manifest;
     if ((await projectBundleHash(encoder.encode(canonicalMaterialJson(payload)))) !== revisionId)
         throw new Error('Material revision hash mismatch');
@@ -100,13 +107,42 @@ function assertAssetSelection(project, entries) {
     }
 }
 function assertMaterialClosure(project, records) {
-    const identities = records.map((record) => `${record.manifest.materialId}/${record.manifest.revisionId}`);
+    const manifests = records.map((record) => validateMaterialRecordShapeAny(record));
+    const identities = manifests.map((manifest) => `${manifest.materialId}/${manifest.revisionId}`);
     if (new Set(identities).size !== identities.length)
         throw new Error('Duplicate material revision');
     for (const dependency of project.materialDependencies)
         if (dependency.sha256 !== dependency.revisionId ||
             !identities.includes(`${dependency.resourceId}/${dependency.revisionId}`))
             throw new Error(`Missing locked material: ${dependency.resourceId}`);
+    const byKey = new Map(manifests.map((manifest) => [`${manifest.materialId}/${manifest.revisionId}`, manifest]));
+    const visited = new Set();
+    for (const key of identities) {
+        const active = new Set();
+        const stack = [{ key, exit: false }];
+        while (stack.length) {
+            const frame = stack.pop();
+            if (frame.exit) {
+                active.delete(frame.key);
+                visited.add(frame.key);
+                continue;
+            }
+            if (active.has(frame.key))
+                throw new Error('Cyclic project material closure');
+            if (visited.has(frame.key))
+                continue;
+            const manifest = byKey.get(frame.key);
+            if (!manifest)
+                throw new Error('Missing transitive project material');
+            active.add(frame.key);
+            stack.push({ key: frame.key, exit: true });
+            for (const pin of materialRecordDependencyPins(manifest)) {
+                if (pin.sha256 !== pin.revisionId)
+                    throw new Error('Transitive material lock hash mismatch');
+                stack.push({ key: `${pin.resourceId}/${pin.revisionId}`, exit: false });
+            }
+        }
+    }
 }
 /** Editable includes normalized rebuild resources; runtime intentionally excludes source/recipes. */
 export async function encodeProjectBundle(input, profile = 'editable') {
@@ -175,8 +211,11 @@ export async function encodeProjectBundle(input, profile = 'editable') {
                 add(prefix + name, bytes);
         }
     }
-    const manifest = projectBundleManifestSchema.parse({
-        version: 'kiln.project-bundle.v1',
+    const version = profile === 'editable' && input.materials.some((record) => record.manifest.schemaVersion === 2)
+        ? 'kiln.project-bundle.v2'
+        : 'kiln.project-bundle.v1';
+    const manifest = projectBundleManifestAnySchema.parse({
+        version,
         profile,
         editable: profile === 'editable',
         resourceClosure: profile === 'editable' ? 'normalized-maps-and-procedural-recipes' : 'embedded-runtime-only',
@@ -232,7 +271,7 @@ export async function decodeProjectBundle(bytes) {
         }
         return value;
     };
-    const manifest = projectBundleManifestSchema.parse(json('bundle.json', PROJECT_BUNDLE_LIMITS.maxManifestBytes));
+    const manifest = projectBundleManifestAnySchema.parse(json('bundle.json', PROJECT_BUNDLE_LIMITS.maxManifestBytes));
     if (manifest.editable !== (manifest.profile === 'editable') ||
         manifest.resourceClosure !==
             (manifest.editable ? 'normalized-maps-and-procedural-recipes' : 'embedded-runtime-only'))
@@ -298,7 +337,9 @@ export async function decodeProjectBundle(bytes) {
         throw new Error('Runtime profile contains editable material records');
     for (const identity of manifest.materials) {
         const prefix = materialPrefix(identity);
-        const materialManifest = materialManifestSchema.parse(json(`${prefix}manifest.json`, 256 * 1024));
+        const materialManifest = (manifest.version === 'kiln.project-bundle.v1'
+            ? materialManifestSchema
+            : materialManifestAnySchema).parse(json(`${prefix}manifest.json`, 256 * 1024));
         used.add(`${prefix}manifest.json`);
         if (materialManifest.materialId !== identity.materialId ||
             materialManifest.revisionId !== identity.revisionId)

package/lib/qa/atlas.d.ts

@@ -0,0 +1,21 @@
+import type { QaFinding } from "./types.js";
+export declare const ATLAS_QA_LIMITS: Readonly<{
+    nodes: 4096;
+    depth: 128;
+    textures: 128;
+    bindings: 1024;
+    uvVisits: 1048576;
+    findings: 64;
+    metadataBytes: 4194304;
+}>;
+export interface AtlasStructuralInspectionV1 {
+    schemaVersion: 1;
+    findings: QaFinding[];
+    coverage: 'none' | 'complete' | 'partial';
+    texturesChecked: number;
+    bindingsChecked: number;
+    uvVerticesChecked: number;
+    nodesChecked: number;
+    truncated: boolean;
+}
+export declare function inspectAtlasScene(root: unknown): AtlasStructuralInspectionV1;