@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/asset-materials-node.js

@@ -1,30 +1,13 @@
-import { validateAssetMaterialClosure } from "./assets.js";
-import { canonicalMaterialJson, MATERIAL_LIBRARY_LIMITS, } from "./material-library.js";
-import { decodeMaterialLibraryPayload, validateMaterialManifestIdentity, } from "./material-library-node.js";
+import { assetMaterialRootManifests, validateAssetMaterialClosure } from "./assets.js";
+import { MATERIAL_LIBRARY_LIMITS, } from "./material-library.js";
+import { decodeMaterialLibraryPayload, validateMaterialManifestIdentityAny, resolveMaterialRecordClosure, } from "./material-library-node.js";
 export function dependencyManifests(asset) {
-    const result = new Map();
-    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;
-        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)
+    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;
@@ -32,7 +15,7 @@ export function dependencyManifests(asset) {
     if (bytes > MATERIAL_LIBRARY_LIMITS.maxPayloadBytes ||
         pixels > MATERIAL_LIBRARY_LIMITS.maxPayloadPixels)
         throw new Error('Saved asset material allocation exceeds limit');
-    return [...result.values()];
+    return result;
 }
 export async function resolveSavedAssetMaterials(asset, library) {
     const dependencies = dependencyManifests(asset);
@@ -40,17 +23,30 @@ export async function resolveSavedAssetMaterials(asset, library) {
         validateAssetMaterialClosure(asset, true);
         return decodeMaterialLibraryPayload(asset.materialResources);
     }
-    return Promise.all(dependencies.map(async (manifest) => {
+    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 (id, revision, load) => {
         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;
+            return await load();
         }
         catch (error) {
-            throw new Error(`Locked asset material unavailable: ${manifest.materialId} at ${manifest.revisionId}`, { cause: 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/lib/assets-node.d.ts

@@ -1,5 +1,5 @@
 import { type AssetDraft, type AssetLibrary, type AssetManifest, type AssetRecord } from "./assets.js";
-import type { MaterialLibrary } from "./material-library.js";
+import { type MaterialLibrary } from "./material-library.js";
 export { resolveSavedAssetMaterials } from "./asset-materials-node.js";
 export declare function verifyAssetRecord(record: AssetRecord): Promise<void>;
 export declare class FileAssetLibrary implements AssetLibrary {

package/lib/assets-node.js

@@ -6,6 +6,7 @@ import { homedir, platform } from 'node:os';
 import { dirname, join, relative, resolve, sep, win32 } from 'node:path';
 import { localWorkspaceRoot } from "./workspace-location.js";
 import { assetIdSchema, assetManifestSchema, ASSET_LIMIT, ASSET_MATERIAL_BYTES, ASSET_MATERIAL_FILE, encodeAssetBundle, validateRecordShape, } from "./assets.js";
+import { canonicalMaterialJson, } from "./material-library.js";
 import { FileMaterialLibrary, createMaterialLibraryPayload } from "./material-library-node.js";
 import { dependencyManifests, resolveSavedAssetMaterials } from "./asset-materials-node.js";
 import { renameDirectoryAtomically } from "./atomic-directory.js";
@@ -201,7 +202,7 @@ export class FileAssetLibrary {
         assertMaterialAllocation(records.filter((record) => record.materialResources ||
             record.manifest.build?.dependencies?.some((raw) => raw &&
                 typeof raw === 'object' &&
-                raw.kind === 'kiln.material.v1')));
+                ['kiln.material.v1', 'kiln.material.v2'].includes(String(raw.kind)))));
         let resourceBytes = 0;
         for (const record of records) {
             validateRecordShape(record);
@@ -222,10 +223,16 @@ export class FileAssetLibrary {
                 (this.materials &&
                     record.manifest.build?.dependencies?.some((raw) => raw &&
                         typeof raw === 'object' &&
-                        raw.kind === 'kiln.material.v1'))) {
+                        ['kiln.material.v1', 'kiln.material.v2'].includes(String(raw.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),

package/lib/assets.d.ts

@@ -1,6 +1,6 @@
 /** Portable asset records. No filesystem, renderer, or server dependencies. */
 import { z } from 'zod';
-import { type MaterialLibraryPayloadV1 } from "./material-library.js";
+import { type MaterialLibraryPayload, type MaterialManifest } from "./material-library.js";
 export declare const ASSET_LIMIT: number;
 export declare const assetIdSchema: z.ZodString;
 export declare const assetManifestSchema: z.ZodObject<{
@@ -50,7 +50,7 @@ export interface AssetRecord {
     manifest: AssetManifest;
     files: Record<string, Uint8Array>;
     /** Editable delivery closure; not part of the canonical asset manifest or revision identity. */
-    materialResources?: MaterialLibraryPayloadV1;
+    materialResources?: MaterialLibraryPayload;
 }
 export interface AssetDraft {
     name: string;
@@ -82,6 +82,8 @@ export interface AssetLibrary {
 }
 export declare const ASSET_MATERIAL_FILE = "materials.kiln.json";
 export declare const ASSET_MATERIAL_BYTES: number;
+/** Pure declaration boundary shared by portable delivery and host hash verification. */
+export declare function assetMaterialRootManifests(record: AssetRecord): MaterialManifest[];
 /** Shape and closure checks are portable; hosts verify hashes and PNG/recipe bytes before import. */
 export declare function validateAssetMaterialClosure(record: AssetRecord, required?: boolean): void;
 export declare function validateRecordShape(record: AssetRecord): void;

package/lib/assets.js

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 import { BACKDROP_IDS } from "./views/background.js";
 import { zipSync, unzipSync } from 'three/addons/libs/fflate.module.js';
-import { assertMaterialJson, canonicalMaterialJson, materialLibraryPayloadSchema, validateMaterialManifest, MATERIAL_LIBRARY_LIMITS, } from "./material-library.js";
+import { assertMaterialJson, canonicalMaterialJson, materialLibraryPayloadAnySchema, materialRecordDependencyPins, validateMaterialManifestAny, MATERIAL_LIBRARY_LIMITS, } from "./material-library.js";
 export const ASSET_LIMIT = 64 * 1024 * 1024;
 export const assetIdSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/);
 const hash = z.string().regex(/^sha256:[a-f0-9]{64}$/);
@@ -47,32 +47,59 @@ export const assetManifestSchema = z.object({
 });
 export const ASSET_MATERIAL_FILE = 'materials.kiln.json';
 export const ASSET_MATERIAL_BYTES = 24 * 1024 * 1024;
-/** Shape and closure checks are portable; hosts verify hashes and PNG/recipe bytes before import. */
-export function validateAssetMaterialClosure(record, required = false) {
-    const dependencies = (record.manifest.build?.dependencies ?? []).filter((raw) => raw &&
-        typeof raw === 'object' &&
-        raw.kind === 'kiln.material.v1');
-    const expected = new Map(dependencies.map((dependency) => {
+/** Pure declaration boundary shared by portable delivery and host hash verification. */
+export function assetMaterialRootManifests(record) {
+    const roots = new Map();
+    for (const raw of record.manifest.build?.dependencies ?? []) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error('Invalid saved asset dependency');
+        const dependency = raw;
+        if (dependency.kind !== 'kiln.material.v1' && dependency.kind !== 'kiln.material.v2') {
+            if (dependency.delivery === 'runtime')
+                throw new Error('Unsupported runtime dependency');
+            if (dependency.delivery !== 'embedded')
+                throw new Error('Unsupported saved asset dependency');
+            continue;
+        }
         if (dependency.delivery !== 'runtime')
             throw new Error('Invalid saved material dependency');
-        const manifest = validateMaterialManifest(dependency.manifest);
-        return [`${manifest.materialId}/${manifest.revisionId}`, canonicalMaterialJson(manifest)];
-    }));
+        const manifest = validateMaterialManifestAny(dependency.manifest);
+        if (dependency.kind !== `kiln.material.v${manifest.schemaVersion}`)
+            throw new Error('Saved material dependency kind/version mismatch');
+        const key = `${manifest.materialId}/${manifest.revisionId}`;
+        const existing = roots.get(key);
+        if (existing && canonicalMaterialJson(existing) !== canonicalMaterialJson(manifest))
+            throw new Error('Conflicting saved material dependency manifests');
+        roots.set(key, manifest);
+        if (roots.size > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
+            throw new Error('Saved asset material dependency count exceeds limit');
+    }
+    return [...roots.values()];
+}
+/** Shape and closure checks are portable; hosts verify hashes and PNG/recipe bytes before import. */
+export function validateAssetMaterialClosure(record, required = false) {
+    const dependencies = assetMaterialRootManifests(record);
+    const expected = new Map(dependencies.map((manifest) => [
+        `${manifest.materialId}/${manifest.revisionId}`,
+        canonicalMaterialJson(manifest),
+    ]));
     if (!record.materialResources) {
         if (required && expected.size)
             throw new Error('Editable asset material closure unavailable');
         return;
     }
     assertMaterialJson(record.materialResources);
-    const payload = materialLibraryPayloadSchema.parse(record.materialResources);
+    const payload = materialLibraryPayloadAnySchema.parse(record.materialResources);
     let bytes = 0;
     let pixels = 0;
-    const seen = new Set();
+    const available = new Map();
     for (const wire of payload.records) {
+        const manifest = validateMaterialManifestAny(wire.manifest);
         const key = `${wire.manifest.materialId}/${wire.manifest.revisionId}`;
-        if (seen.has(key) || expected.get(key) !== canonicalMaterialJson(wire.manifest))
+        if (available.has(key) ||
+            (expected.has(key) && expected.get(key) !== canonicalMaterialJson(manifest)))
             throw new Error('Asset material closure mismatch');
-        seen.add(key);
+        available.set(key, manifest);
         if (Object.keys(wire.files).length !== wire.manifest.maps.length)
             throw new Error('Asset material map inventory mismatch');
         for (const map of wire.manifest.maps) {
@@ -82,11 +109,29 @@ export function validateAssetMaterialClosure(record, required = false) {
             pixels += map.width * map.height;
         }
     }
-    if (seen.size !== expected.size)
-        throw new Error('Asset material closure incomplete');
     if (bytes > MATERIAL_LIBRARY_LIMITS.maxPayloadBytes ||
         pixels > MATERIAL_LIBRARY_LIMITS.maxPayloadPixels)
         throw new Error('Asset material closure exceeds allocation limits');
+    const visited = new Set();
+    const active = new Set();
+    const visit = (key) => {
+        if (active.has(key))
+            throw new Error('Asset material closure contains a cycle');
+        if (visited.has(key))
+            return;
+        const manifest = available.get(key);
+        if (!manifest)
+            throw new Error('Asset material closure incomplete');
+        active.add(key);
+        for (const pin of materialRecordDependencyPins(manifest))
+            visit(`${pin.resourceId}/${pin.revisionId}`);
+        active.delete(key);
+        visited.add(key);
+    };
+    for (const key of expected.keys())
+        visit(key);
+    if (visited.size !== available.size)
+        throw new Error('Asset material closure has unrelated records');
 }
 const allowedFiles = new Set(['asset.glb', 'source.kiln.js', 'preview.png']);
 export function validateRecordShape(record) {

package/lib/atlas-provenance.d.ts

@@ -0,0 +1,86 @@
+/** Internal atlas metadata owner. TextureInfo, rather than an image, owns each sampler use. */
+import type { Document, Texture as GltfTexture, TextureInfo } from '@gltf-transform/core';
+import * as THREE from 'three';
+import { type CanonicalTextureAtlasSpecV1 } from "./texture-atlas-contract.js";
+import type { TextureAtlasManifestV1 } from "./texture-atlas-pixels.js";
+export declare const ATLAS_PROVENANCE_VERSION: 'kiln.atlas-provenance.v1';
+export declare const ATLAS_PROVENANCE_LIMITS: Readonly<{
+    atlases: 128;
+    bytes: 4194304;
+    bindings: 1024;
+    entryBytes: 262144;
+    encodedBytes: 16777216;
+    aggregateEncodedBytes: 67108864;
+    bakeDecodedBytes: 67108864;
+}>;
+export interface AtlasProvenanceV1 {
+    spec: CanonicalTextureAtlasSpecV1;
+    manifest: TextureAtlasManifestV1;
+}
+export interface AtlasProvenanceTableV1 {
+    version: typeof ATLAS_PROVENANCE_VERSION;
+    atlases: (AtlasProvenanceV1 & {
+        id: string;
+    })[];
+}
+export interface AtlasReferenceV1 {
+    version: typeof ATLAS_PROVENANCE_VERSION;
+    id: string;
+    effectiveSampler?: {
+        minFilter: number | null;
+        magFilter: number | null;
+        wrapS: number;
+        wrapT: number;
+    };
+    finalMime?: string;
+    finalImageSha256?: string;
+}
+export interface AtlasBindingV1 {
+    version: typeof ATLAS_PROVENANCE_VERSION;
+    atlasId: string;
+    region: string;
+    inputOrigin: 'top-left' | 'bottom-left';
+    mode: 'content-boundary' | 'texel-center';
+}
+/** Reads only engine metadata data descriptors; author metadata and encoded arrays are not serialized. */
+export declare function readAtlasTextureProvenance(texture: THREE.Texture): AtlasProvenanceV1 | undefined;
+export declare function validateAtlasProvenanceTable(input: unknown): AtlasProvenanceTableV1;
+export declare function expandAtlasBinding(input: unknown, table: AtlasProvenanceTableV1): {
+    manifestHash: `sha256:${string}`;
+    specHash: `sha256:${string}`;
+    layoutHash: `sha256:${string}`;
+    region: string;
+    content: import("./texture-atlas-contract.js").AtlasRectangleV1;
+    allocation: import("./texture-atlas-contract.js").AtlasRectangleV1;
+    inputOrigin: unknown;
+    mode: unknown;
+    scale: number[];
+    offset: number[];
+};
+/** A geometry-wide stamp can be associated only with the exact primary atlas supplied here. */
+export declare function readAtlasGeometryBinding(geometry: THREE.BufferGeometry, provenance: AtlasProvenanceV1): AtlasBindingV1 | undefined;
+export interface AtlasProvenanceCollection {
+    table?: AtlasProvenanceTableV1;
+    texture(texture: THREE.Texture): AtlasReferenceV1 | undefined;
+    binding(geometry: THREE.BufferGeometry): AtlasBindingV1 | undefined;
+}
+export declare function collectAtlasProvenance(root: THREE.Object3D): AtlasProvenanceCollection;
+export declare function atlasDocumentTable(doc: Document): AtlasProvenanceTableV1 | undefined;
+export declare function atlasMaterialUses(doc: Document): {
+    texture: GltfTexture;
+    info: TextureInfo;
+}[];
+/** Export/optimization only: bind source identity to the final encoded bytes and actual per-use sampler. */
+export declare function refreshAtlasDocumentProvenance(doc: Document): Promise<void>;
+/** Import is validation, never a repair or identity refresh. */
+export declare function validateAtlasDocumentProvenance(doc: Document): Promise<void>;
+/** Host-only owned identity established by the validated GLB loader; no serialized skip flag. */
+export declare function readValidatedAtlasDelivery(texture: THREE.Texture): Readonly<AtlasReferenceV1> | undefined;
+export declare function readAtlasEncodedTexture(texture: THREE.Texture): {
+    mime: 'image/png';
+    bytes: Uint8Array;
+} | undefined;
+/** Called only after validateAtlasDocumentProvenance; each sampler use gets owned Three state. */
+export declare function restoreAtlasTextureProvenance(texture: THREE.Texture, info: TextureInfo, table: AtlasProvenanceTableV1): void;
+/** Compose before mergeDocuments copies image/geometry buffers or deletes the source scene. */
+export declare function mergeAtlasDocumentProvenance(target: Document, source: Document): Promise<void>;