@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/evaluator/protocol.d.ts

@@ -3,7 +3,7 @@ import { type RequirementsContext } from "../requirements-context.js";
 import type { AssetQaReport } from "../qa/types.js";
 import type { RenderGlbOptions, RenderResult } from "../render.js";
 import type { KhronosGltfValidationReport } from "../qa/gltf.js";
-import type { MaterialLibraryPayloadV1 } from "../material-library.js";
+import { type MaterialLibraryPayload } from "../material-library.js";
 export declare const EVALUATOR_REQUEST_VERSION: 'kiln.evaluator.request.v2';
 export declare const EVALUATOR_RESULT_VERSION: 'kiln.evaluator.result.v2';
 export declare const MAX_EVALUATOR_CODE_BYTES: number;
@@ -96,7 +96,7 @@ export declare function encodeRenderResultV2(requestId: string, render: RenderRe
 export declare function decodeEvaluatorResultV2(json: string, maxGlbBytes: number, expectedRequestId?: string): EvaluatorResultV2;
 export declare function createEvaluatorPortV2(transport: EvaluatorTransportV2, defaults?: EvaluatorPortCallControlsV2): EvaluatorPortV2;
 /** All transports bind decoded acceptance evidence to the same current-host snapshot. */
-export declare function assertEvaluatorResultMaterialResources(result: EvaluatorResultV2, expected?: MaterialLibraryPayloadV1): void;
+export declare function assertEvaluatorResultMaterialResources(result: EvaluatorResultV2, expected?: MaterialLibraryPayload): void;
 /** All transports bind decoded acceptance evidence to the same current-host snapshot. */
 export declare function assertEvaluatorResultRequirements(result: EvaluatorResultV2, expected: RequirementsContext): void;
 /** Explicit trusted/test compatibility port. Production hosts must inject a

package/lib/evaluator/protocol.js

@@ -2,7 +2,8 @@ import { authoringDiagnosticAdvice, EXECUTION_REJECTED_ADVICE, } from "./authori
 import { createHash } from 'node:crypto';
 import { assertNoLegacyRuntimePolicy, validateRequirementsBinding, validateRequirementsContext, resolveRequirementsContext, requirementsContextsEqual, } from "../requirements-context.js";
 import { validateRequirementsQaReport } from "../qa/requirements-report.js";
-import { validateMaterialLibraryPayload, validateMaterialManifestIdentity, } from "../material-library-node.js";
+import { validateMaterialLibraryPayloadAny, validateMaterialManifestIdentityAny, } from "../material-library-node.js";
+import { canonicalMaterialJson } from "../material-library.js";
 import { rebuildOptionsSchema } from "../rebuild-options.js";
 export const EVALUATOR_REQUEST_VERSION = 'kiln.evaluator.request.v2';
 export const EVALUATOR_RESULT_VERSION = 'kiln.evaluator.result.v2';
@@ -134,7 +135,7 @@ function parseOptions(value) {
     }
     const options = {};
     if (value.materialResources !== undefined)
-        options.materialResources = validateMaterialLibraryPayload(value.materialResources);
+        options.materialResources = validateMaterialLibraryPayloadAny(value.materialResources);
     if (value.gltfExporter !== undefined) {
         if (value.gltfExporter !== 'legacy' && value.gltfExporter !== 'three')
             fail('request');
@@ -272,6 +273,9 @@ export function decodeEvaluatorResultV2(json, maxGlbBytes, expectedRequestId) {
                     value.error.diagnostic !== 'ROUNDED_BOX_RADIUS' &&
                     value.error.diagnostic !== 'PROCEDURAL_TEXTURE_UNKNOWN_KEY' &&
                     value.error.diagnostic !== 'PROCEDURAL_TEXTURE_BLEND' &&
+                    value.error.diagnostic !== 'PROCEDURAL_TEXTURE_V3_CONTRACT' &&
+                    value.error.diagnostic !== 'PORTABLE_MATERIAL_V3_CONTRACT' &&
+                    value.error.diagnostic !== 'TEXTURE_ATLAS_CONTRACT' &&
                     value.error.diagnostic !== 'MATERIAL_FRACTION_RANGE' &&
                     value.error.diagnostic !== 'MATERIAL_RECIPE_TEXTURE_BINDING' &&
                     value.error.diagnostic !== 'PORTABLE_TEXTURE_REFERENCE' &&
@@ -297,7 +301,10 @@ export function decodeEvaluatorResultV2(json, maxGlbBytes, expectedRequestId) {
                     value.error.diagnostic !== 'PROGRAM_TYPE_ERROR' &&
                     value.error.diagnostic !== 'PROGRAM_RANGE_ERROR' &&
                     value.error.diagnostic !== 'LOD_SET' &&
-                    value.error.diagnostic !== 'OPEN_SHELL')))
+                    value.error.diagnostic !== 'OPEN_SHELL' &&
+                    value.error.diagnostic !== 'EXPORT_MATERIAL_SIDE_UNSUPPORTED' &&
+                    value.error.diagnostic !== 'BONE_CHAIN_ARGUMENT' &&
+                    value.error.diagnostic !== 'SKIN_BINDING_ARGUMENT')))
             return fail('result');
         if (value.error.qa !== undefined) {
             if (value.error.code !== 'QA_BLOCKED' ||
@@ -352,7 +359,7 @@ export function decodeEvaluatorResultV2(json, maxGlbBytes, expectedRequestId) {
             fail('result');
         try {
             for (const manifest of value.render.materialLibraryDependencies)
-                validateMaterialManifestIdentity(manifest);
+                validateMaterialManifestIdentityAny(manifest);
         }
         catch {
             return fail('result');
@@ -478,8 +485,11 @@ export function assertEvaluatorResultMaterialResources(result, expected) {
     if (!result.ok)
         return;
     const actual = result.render.materialLibraryDependencies ?? [];
-    const wanted = expected?.records.map((record) => record.manifest.revisionId).sort() ?? [];
-    if (JSON.stringify(actual.map((manifest) => manifest.revisionId).sort()) !== JSON.stringify(wanted))
+    const wanted = expected?.records.map((record) => record.manifest) ?? [];
+    const identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;
+    if (new Set(actual.map(identity)).size !== actual.length ||
+        JSON.stringify(actual.map(canonicalMaterialJson).sort()) !==
+            JSON.stringify(wanted.map(canonicalMaterialJson).sort()))
         throw new EvaluatorPortError('PROTOCOL_ERROR');
 }
 /** All transports bind decoded acceptance evidence to the same current-host snapshot. */

package/lib/evaluator/subprocess.js

@@ -3,7 +3,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { AssetQaBlockedError } from "../qa/run.js";
 import { assertNoLegacyRuntimePolicy, resolveRequirementsContext } from "../requirements-context.js";
-import { validateMaterialLibraryPayload } from "../material-library-node.js";
+import { validateMaterialLibraryPayloadAny } from "../material-library-node.js";
 import { decodeEvaluatorResultV2, assertEvaluatorResultRequirements, assertEvaluatorResultMaterialResources, evaluatorOutcomeMessage, EVALUATOR_REQUEST_VERSION, MAX_EVALUATOR_REQUEST_BYTES, } from "./protocol.js";
 const DEFAULT_DEADLINE_MS = 60_000;
 const DEFAULT_MAX_GLB_BYTES = 16 * 1024 * 1024;
@@ -67,7 +67,7 @@ export async function renderGLBViaProcessLaunch(code, options = {}, controls = {
     const maxGlbBytes = boundedInteger(controls.maxGlbBytes, DEFAULT_MAX_GLB_BYTES, 64 * 1024 * 1024);
     const maxResponseBytes = boundedInteger(controls.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, 96 * 1024 * 1024);
     if (options.materialResources !== undefined)
-        validateMaterialLibraryPayload(options.materialResources);
+        validateMaterialLibraryPayloadAny(options.materialResources);
     const request = {
         version: EVALUATOR_REQUEST_VERSION,
         requestId: 'render-1',

package/lib/exporter-node.js

@@ -16,8 +16,16 @@ export async function prepareNodeExport(hasTextures) {
         host['FileReader'] = ExportFileReader;
     if (!hasTextures || host['OffscreenCanvas'] || host['document'])
         return;
-    const { Canvas, ImageData } = await import('@napi-rs/canvas');
+    const { Canvas, ImageData } = await import('@napi-rs/canvas').catch((cause) => {
+        throw new Error('Headless textured export requires @napi-rs/canvas. Reinstall Kiln with optional dependencies enabled, then verify the native binding in the same Node runtime and platform used by the Kiln host.', { cause });
+    });
     class ExportCanvas extends Canvas {
+        constructor(width, height) {
+            super(width, height);
+            // Native Canvas.data() is a method, not a DataTexture image byte array.
+            // Shadow it on the instance: the native constructor supplies its own prototype.
+            Object.defineProperty(this, 'data', { value: undefined });
+        }
         async convertToBlob(options = {}) {
             const type = options.type ?? options.mime ?? 'image/png';
             if (type !== 'image/png' && type !== 'image/jpeg' && type !== 'image/webp')

package/lib/geometry-budget.d.ts

@@ -7,6 +7,13 @@ export declare const GEOMETRY_ALLOCATION_LIMITS: Readonly<{
     repeatedMeshes: 10000;
     primitiveSegments: 4096;
     primitiveGridVertices: 262144;
+    unwrapVertices: 65536;
+    unwrapTriangles: 1000000;
+    unwrapAttributeBytes: number;
+    unwrapResolution: 4096;
+    skinBones: 1024;
+    skinVertices: 262144;
+    skinAttributeBytes: number;
 }>;
 export declare function assertDimension(name: string, value: number, allowZero?: boolean): void;
 export declare function assertPrimitiveSegments(name: string, value: number, minimum: number): void;

package/lib/geometry-budget.js

@@ -7,6 +7,14 @@ export const GEOMETRY_ALLOCATION_LIMITS = Object.freeze({
     repeatedMeshes: 10_000,
     primitiveSegments: 4096,
     primitiveGridVertices: 262_144,
+    // xatlasjs 0.2 returns Uint16 indices and source-vertex correspondence.
+    unwrapVertices: 65_536,
+    unwrapTriangles: 1_000_000,
+    unwrapAttributeBytes: 128 * 1024 * 1024,
+    unwrapResolution: 4096,
+    skinBones: 1024,
+    skinVertices: 262_144,
+    skinAttributeBytes: 128 * 1024 * 1024,
 });
 export function assertDimension(name, value, allowZero = false) {
     if (!Number.isFinite(value) ||

package/lib/gltf-texture-binding.d.ts

@@ -0,0 +1,6 @@
+import * as THREE from 'three';
+import type { TextureInfo } from '@gltf-transform/core';
+/** glTF image orientation and sampling belong to every texture use, not just atlases. */
+export declare function restoreGltfTextureBinding(texture: THREE.Texture, info: TextureInfo): void;
+/** Two uses of one image may differ in sampler, UV channel, transform or atlas provenance. */
+export declare function gltfTextureBindingKey(info: TextureInfo | null | undefined): string;

package/lib/gltf-texture-binding.js

@@ -0,0 +1,54 @@
+import * as THREE from 'three';
+const MIN = {
+    9728: THREE.NearestFilter,
+    9729: THREE.LinearFilter,
+    9984: THREE.NearestMipmapNearestFilter,
+    9985: THREE.LinearMipmapNearestFilter,
+    9986: THREE.NearestMipmapLinearFilter,
+    9987: THREE.LinearMipmapLinearFilter,
+};
+const WRAP = {
+    33071: THREE.ClampToEdgeWrapping,
+    33648: THREE.MirroredRepeatWrapping,
+    10497: THREE.RepeatWrapping,
+};
+/** glTF image orientation and sampling belong to every texture use, not just atlases. */
+export function restoreGltfTextureBinding(texture, info) {
+    texture.minFilter = MIN[info.getMinFilter() ?? 9729];
+    texture.magFilter = info.getMagFilter() === 9728 ? THREE.NearestFilter : THREE.LinearFilter;
+    texture.wrapS = WRAP[info.getWrapS()];
+    texture.wrapT = WRAP[info.getWrapT()];
+    texture.generateMipmaps = [9984, 9985, 9986, 9987].includes(info.getMinFilter() ?? 9729);
+    texture.flipY = false;
+    const transform = info.getExtension('KHR_texture_transform');
+    texture.channel = transform?.getTexCoord() ?? info.getTexCoord();
+    if (transform) {
+        texture.offset.fromArray(transform.getOffset());
+        texture.repeat.fromArray(transform.getScale());
+        texture.rotation = transform.getRotation();
+        // glTF composes T*R*S. Three's automatic UV matrix composes nonuniform
+        // repeat and rotation in a different order; retain the actual glTF basis.
+        const c = Math.cos(texture.rotation), s = Math.sin(texture.rotation);
+        const [sx, sy] = transform.getScale(), [x, y] = transform.getOffset();
+        texture.matrix.set(sx * c, sy * s, x, -sx * s, sy * c, y, 0, 0, 1);
+        texture.matrixAutoUpdate = false;
+    }
+}
+/** Two uses of one image may differ in sampler, UV channel, transform or atlas provenance. */
+export function gltfTextureBindingKey(info) {
+    if (!info)
+        return '';
+    const transform = info.getExtension('KHR_texture_transform');
+    return JSON.stringify([
+        info.getMinFilter(),
+        info.getMagFilter(),
+        info.getWrapS(),
+        info.getWrapT(),
+        info.getTexCoord(),
+        transform?.getTexCoord(),
+        transform?.getOffset(),
+        transform?.getScale(),
+        transform?.getRotation(),
+        info.getExtras()['kilnAtlasReference'],
+    ]);
+}

package/lib/material-authoring-node.d.ts

@@ -0,0 +1,6 @@
+/** Shared CLI/MCP JSON authoring boundary. Library pins never imply project membership. */
+import { type MaterialLibrary, type MaterialRecord } from "./material-library.js";
+export declare function createProceduralMaterialRecord(value: unknown, library: MaterialLibrary): Promise<{
+    record: MaterialRecord;
+    dependencies: MaterialRecord[];
+}>;

package/lib/material-authoring-node.js

@@ -0,0 +1,49 @@
+/** Shared CLI/MCP JSON authoring boundary. Library pins never imply project membership. */
+import { MATERIAL_LIBRARY_LIMITS, assertMaterialJson, proceduralMaterialDraftSchema, proceduralMaterialDraftV2Schema, } from "./material-library.js";
+import { createMaterialRecordV1, createMaterialRecordV2, resolveMaterialRecordClosure, } from "./material-library-node.js";
+import { canonicalizeTextureAtlasSpecV1 } from "./texture-atlas-contract.js";
+export async function createProceduralMaterialRecord(value, library) {
+    assertMaterialJson(value);
+    if (new TextEncoder().encode(JSON.stringify(value)).length >
+        MATERIAL_LIBRARY_LIMITS.maxManifestBytes)
+        throw new Error('Material draft exceeds size limit');
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Material draft must be a JSON object');
+    if (!Object.hasOwn(value, 'schemaVersion'))
+        return {
+            record: await createMaterialRecordV1(proceduralMaterialDraftSchema.parse(value)),
+            dependencies: [],
+        };
+    const draft = proceduralMaterialDraftV2Schema.parse(value);
+    const pins = new Map();
+    for (const map of draft.maps) {
+        if (!map.atlas)
+            continue;
+        for (const region of canonicalizeTextureAtlasSpecV1(map.atlas).regions) {
+            if (region.source.kind !== 'resource')
+                continue;
+            const pin = region.source.pin;
+            pins.set(`${pin.resourceId}@${pin.revisionId}`, pin);
+        }
+    }
+    if (pins.size > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
+        throw new Error('Material source closure count limit exceeded');
+    const roots = [];
+    if (pins.size && !library.readManifest)
+        throw new Error('Pinned atlas creation requires a material library with readManifest support.');
+    for (const pin of pins.values()) {
+        const manifest = await library.readManifest(pin.resourceId, pin.revisionId);
+        if (manifest.materialId !== pin.resourceId || manifest.revisionId !== pin.revisionId)
+            throw new Error('Material source pin identity mismatch');
+        roots.push(manifest);
+    }
+    const dependencies = roots.length
+        ? await resolveMaterialRecordClosure(roots, {
+            readManifest: (id, revision) => library.readManifest(id, revision),
+            read: (id, revision) => library.readRecordFiles
+                ? library.readRecordFiles(id, revision)
+                : library.read(id, revision),
+        })
+        : [];
+    return { record: await createMaterialRecordV2(draft, { materials: dependencies }), dependencies };
+}