@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/skin-binding.js

@@ -0,0 +1,144 @@
+import * as THREE from 'three';
+import { AuthoringDiagnosticError } from "./evaluator/authoring-diagnostic.js";
+import { stampSemanticMetadataV1, } from "./contracts/index.js";
+import { GEOMETRY_ALLOCATION_LIMITS as limits, assertFiniteTriple } from "./geometry-budget.js";
+function topRoot(node) {
+    while (node.parent)
+        node = node.parent;
+    return node;
+}
+function assertMatrix(matrix, label) {
+    if (!matrix.elements.every((value) => Number.isFinite(value) && Number.isFinite(Math.fround(value))) ||
+        !Number.isFinite(matrix.determinant()) ||
+        matrix.determinant() === 0 ||
+        !matrix
+            .clone()
+            .invert()
+            .elements.every((value) => Number.isFinite(value) && Number.isFinite(Math.fround(value))))
+        throw new RangeError(`createSkinnedPart ${label} must have finite invertible bind transforms.`);
+}
+/** Clone unchanged topology, attach explicit four-lane influences and bind at the current rest pose. */
+export function createSkinnedPart(name, geometry, material, options) {
+    try {
+        return buildSkinnedPart(name, geometry, material, options);
+    }
+    catch (error) {
+        if (error instanceof TypeError || error instanceof RangeError)
+            throw new AuthoringDiagnosticError('SKIN_BINDING_ARGUMENT', error.message);
+        throw error;
+    }
+}
+function buildSkinnedPart(name, geometry, material, options) {
+    if (typeof name !== 'string' ||
+        !name.trim() ||
+        THREE.PropertyBinding.sanitizeNodeName(name) !== name)
+        throw new TypeError('createSkinnedPart name must be nonempty and free of animation binding punctuation.');
+    if (!geometry?.isBufferGeometry)
+        throw new TypeError('createSkinnedPart requires BufferGeometry.');
+    const materials = Array.isArray(material) ? material : [material];
+    if (!materials.length || materials.some((value) => !value?.isMaterial))
+        throw new TypeError('createSkinnedPart requires a material or nonempty material array.');
+    if (!options?.parent?.isObject3D)
+        throw new TypeError('createSkinnedPart requires an existing parent in the bone hierarchy.');
+    const { bones, indices, weights, parent } = options;
+    if (!Array.isArray(bones) || bones.length < 1 || bones.length > limits.skinBones)
+        throw new RangeError(`createSkinnedPart bone limit is 1..${limits.skinBones}.`);
+    if (options.normalizeWeights !== undefined && typeof options.normalizeWeights !== 'boolean')
+        throw new TypeError('createSkinnedPart normalizeWeights must be boolean.');
+    const top = topRoot(parent), names = new Set(), members = new Set();
+    for (const bone of bones) {
+        if (!bone?.isBone || topRoot(bone) !== top || members.has(bone))
+            throw new TypeError('createSkinnedPart bones must be distinct Bones in the parent hierarchy.');
+        if (!bone.name ||
+            THREE.PropertyBinding.sanitizeNodeName(bone.name) !== bone.name ||
+            names.has(bone.name))
+            throw new TypeError('createSkinnedPart bones need unique animation-safe names.');
+        members.add(bone);
+        names.add(bone.name);
+    }
+    // Collision with any other node makes name-based animation ambiguous.
+    top.traverse((node) => {
+        if (names.has(node.name) && !members.has(node))
+            throw new TypeError(`createSkinnedPart ambiguous bone name: ${node.name}.`);
+    });
+    const position = geometry.getAttribute('position'), count = position?.count;
+    if (position?.itemSize !== 3 ||
+        !Number.isSafeInteger(count) ||
+        count < 1 ||
+        count > limits.skinVertices)
+        throw new RangeError(`createSkinnedPart position vertex limit is 1..${limits.skinVertices} xyz vertices.`);
+    if (geometry.hasAttribute('skinIndex') || geometry.hasAttribute('skinWeight'))
+        throw new TypeError('createSkinnedPart geometry already contains binding attributes; provide unbound geometry.');
+    let bytes = count * 4 * (2 + 4);
+    const attributes = [
+        geometry.getIndex(),
+        ...Object.values(geometry.attributes),
+        ...Object.values(geometry.morphAttributes).flat(),
+    ];
+    for (const attribute of attributes) {
+        if (!attribute)
+            continue;
+        bytes += attribute.array.byteLength;
+        if (!Number.isSafeInteger(bytes) || bytes > limits.skinAttributeBytes)
+            throw new RangeError(`createSkinnedPart attribute allocation limit is ${limits.skinAttributeBytes} bytes.`);
+    }
+    if (!indices || !weights || indices.length !== count * 4 || weights.length !== count * 4)
+        throw new RangeError('createSkinnedPart requires exactly four indices and weights per vertex.');
+    // First pass validates all input before cloning or allocating output attributes.
+    for (let vertex = 0; vertex < count; vertex++) {
+        let sum = 0;
+        for (let lane = 0; lane < 4; lane++) {
+            const i = vertex * 4 + lane, index = indices[i], weight = weights[i];
+            if (!Number.isInteger(index) || index < 0 || index >= bones.length)
+                throw new RangeError(`createSkinnedPart vertex ${vertex} lane ${lane} has an invalid bone index.`);
+            if (!Number.isFinite(weight) || weight < 0)
+                throw new RangeError(`createSkinnedPart vertex ${vertex} lane ${lane} needs a finite nonnegative weight.`);
+            if (!options.normalizeWeights && weight > 1)
+                throw new RangeError(`createSkinnedPart vertex ${vertex} weights must be <=1 and sum to one; request normalizeWeights explicitly.`);
+            sum += weight;
+        }
+        if (!Number.isFinite(sum) ||
+            sum <= 0 ||
+            (!options.normalizeWeights && Math.abs(sum - 1) > 1e-5))
+            throw new RangeError(`createSkinnedPart vertex ${vertex} has an invalid weight sum; require one or explicitly normalize a positive finite sum.`);
+    }
+    for (const key of ['position', 'rotation', 'scale'])
+        if (options[key] !== undefined)
+            assertFiniteTriple(`createSkinnedPart ${key}`, options[key]);
+    const local = new THREE.Matrix4().compose(new THREE.Vector3(...(options.position ?? [0, 0, 0])), new THREE.Quaternion().setFromEuler(new THREE.Euler(...(options.rotation ?? [0, 0, 0]).map(THREE.MathUtils.degToRad))), new THREE.Vector3(...(options.scale ?? [1, 1, 1])));
+    top.updateWorldMatrix(true, true);
+    const bind = new THREE.Matrix4().multiplyMatrices(parent.matrixWorld, local);
+    assertMatrix(bind, 'mesh');
+    for (const bone of bones) {
+        assertMatrix(bone.matrixWorld, `bone ${bone.name}`);
+    }
+    const skinIndices = new Uint16Array(indices.length), skinWeights = new Float32Array(weights.length);
+    for (let vertex = 0; vertex < count; vertex++) {
+        const start = vertex * 4;
+        const sum = options.normalizeWeights
+            ? weights[start] + weights[start + 1] + weights[start + 2] + weights[start + 3]
+            : 1;
+        for (let lane = 0; lane < 4; lane++) {
+            skinIndices[start + lane] = indices[start + lane];
+            skinWeights[start + lane] = weights[start + lane] / sum;
+        }
+    }
+    const owned = geometry.clone();
+    owned.setAttribute('skinIndex', new THREE.BufferAttribute(skinIndices, 4));
+    owned.setAttribute('skinWeight', new THREE.BufferAttribute(skinWeights, 4));
+    const mesh = new THREE.SkinnedMesh(owned, Array.isArray(material) ? [...material] : material);
+    mesh.name = `Mesh_${name}`;
+    if (options.position)
+        mesh.position.fromArray(options.position);
+    if (options.rotation)
+        mesh.rotation.set(...options.rotation.map(THREE.MathUtils.degToRad));
+    if (options.scale)
+        mesh.scale.fromArray(options.scale);
+    if (options.semantic)
+        stampSemanticMetadataV1(mesh, options.semantic);
+    const skeleton = new THREE.Skeleton([...bones], bones.map((bone) => bone.matrixWorld.clone().invert()));
+    mesh.bind(skeleton, bind);
+    parent.add(mesh);
+    mesh.updateWorldMatrix(true, false);
+    return mesh;
+}

package/lib/texture-atlas-contract.d.ts

@@ -0,0 +1,97 @@
+/** Browser-safe named pixel regions. Admission never loads or allocates image pixels. */
+import { type CanonicalPortableSamplerV1, type PortableSamplerV1 } from "./portable-sampler.js";
+import { type CanonicalProceduralTextureSpecV3, type ProceduralTextureSpecV3 } from "./procedural-texture-v3-contract.js";
+import type { MaterialMapPinV1 } from "./pinned-material-map.js";
+import type { TextureAtlasManifestV1 } from "./texture-atlas-pixels.js";
+import { type TextureUsage } from "./texture-contract.js";
+import { AuthoringDiagnosticError } from "./evaluator/authoring-diagnostic.js";
+export declare const TEXTURE_ATLAS_COMPILER_ID: 'kiln.texture-atlas.v1.1';
+export declare const TEXTURE_ATLAS_LIMITS: Readonly<{
+    edge: 1024;
+    outputTexels: 1048576;
+    regions: 64;
+    sources: 16;
+    sourceTexels: 4194304;
+    encodedSourceBytes: 8388608;
+    encodedBytes: 16777216;
+    jsonBytes: 262144;
+    work: 64000000;
+    allocatedBytes: 67108864;
+    uvVertices: 262144;
+    uvAttributeBytes: 134217728;
+}>;
+export interface AtlasRectangleV1 {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type AtlasEdgeModeV1 = 'copy-edge' | 'mask-rgb-dilate';
+export interface AtlasResourceExpectationV1 {
+    width?: number;
+    height?: number;
+    imageSha256?: `sha256:${string}`;
+    decodedPixelHash?: `sha256:${string}`;
+}
+export type TextureAtlasSourceV1 = {
+    kind: 'procedural';
+    spec: ProceduralTextureSpecV3;
+} | {
+    kind: 'resource';
+    resourceId: string;
+    pin: MaterialMapPinV1;
+    expected?: AtlasResourceExpectationV1;
+};
+export interface TextureAtlasRegionV1 {
+    name: string;
+    content: AtlasRectangleV1;
+    gutter?: number;
+    edgeMode?: AtlasEdgeModeV1;
+    source: TextureAtlasSourceV1;
+    crop?: AtlasRectangleV1;
+}
+export interface TextureAtlasSpecV1 {
+    schemaVersion: 1;
+    width: number;
+    height: number;
+    usage: TextureUsage;
+    sampler?: PortableSamplerV1;
+    regions: TextureAtlasRegionV1[];
+}
+export type CanonicalTextureAtlasSourceV1 = {
+    kind: 'procedural';
+    spec: CanonicalProceduralTextureSpecV3;
+} | Extract<TextureAtlasSourceV1, {
+    kind: 'resource';
+}>;
+export interface CanonicalTextureAtlasRegionV1 {
+    name: string;
+    content: AtlasRectangleV1;
+    gutter: number;
+    edgeMode: AtlasEdgeModeV1;
+    source: CanonicalTextureAtlasSourceV1;
+    crop?: AtlasRectangleV1;
+}
+export interface CanonicalTextureAtlasSpecV1 {
+    schemaVersion: 1;
+    width: number;
+    height: number;
+    usage: TextureUsage;
+    sampler: CanonicalPortableSamplerV1;
+    regions: CanonicalTextureAtlasRegionV1[];
+}
+export declare class TextureAtlasError extends AuthoringDiagnosticError {
+    constructor(message: string);
+}
+export declare function atlasFailure(message: string): never;
+export declare function atlasAllocationV1(region: Pick<CanonicalTextureAtlasRegionV1, 'content' | 'gutter'>): AtlasRectangleV1;
+export declare function assertAtlasCropV1(crop: AtlasRectangleV1, content: AtlasRectangleV1, width: number, height: number): void;
+export declare function atlasSourceIdentityV1(source: CanonicalTextureAtlasSourceV1): string;
+export declare function canonicalizeTextureAtlasSpecV1(input: unknown): CanonicalTextureAtlasSpecV1;
+export declare function canonicalTextureAtlasJsonV1(input: unknown): string;
+export declare function hashTextureAtlasSpecV1(input: unknown): `sha256:${string}`;
+/** Internal identity helper for bounded atlas metadata; stable across object property order. */
+export declare function canonicalAtlasMetadataJsonV1(input: unknown): string;
+export declare function atlasLayoutHashV1(spec: CanonicalTextureAtlasSpecV1): `sha256:${string}`;
+/** Pure persisted-manifest reader. Actual PNG/RGBA and recompilation belong to the host. */
+export declare function validateTextureAtlasManifestV1(input: unknown, providedSpec: CanonicalTextureAtlasSpecV1): TextureAtlasManifestV1;

package/lib/texture-atlas-contract.js

@@ -0,0 +1,414 @@
+/** Browser-safe named pixel regions. Admission never loads or allocates image pixels. */
+import { canonicalizePortableSamplerV1, } from "./portable-sampler.js";
+import { admitProceduralTextureSpecV3, hashProceduralTextureSpecV3, } from "./procedural-texture-v3-contract.js";
+import { sha256Hex } from "./procedural-material-v2.js";
+import { TEXTURE_USAGES } from "./texture-contract.js";
+import { AuthoringDiagnosticError } from "./evaluator/authoring-diagnostic.js";
+export const TEXTURE_ATLAS_COMPILER_ID = 'kiln.texture-atlas.v1.1';
+export const TEXTURE_ATLAS_LIMITS = Object.freeze({
+    edge: 1024,
+    outputTexels: 1_048_576,
+    regions: 64,
+    sources: 16,
+    sourceTexels: 4_194_304,
+    encodedSourceBytes: 8_388_608,
+    encodedBytes: 16_777_216,
+    jsonBytes: 262_144,
+    work: 64_000_000,
+    allocatedBytes: 67_108_864,
+    uvVertices: 262_144,
+    uvAttributeBytes: 134_217_728,
+});
+export class TextureAtlasError extends AuthoringDiagnosticError {
+    constructor(message) {
+        super('TEXTURE_ATLAS_CONTRACT', `textureAtlas: ${message}`);
+        this.name = 'TextureAtlasError';
+    }
+}
+export function atlasFailure(message) {
+    throw new TextureAtlasError(message);
+}
+function preflight(input) {
+    let nodes = 0;
+    let bytes = 0;
+    const encoder = new TextEncoder();
+    const addBytes = (count) => {
+        bytes += count;
+        if (bytes > TEXTURE_ATLAS_LIMITS.jsonBytes)
+            atlasFailure('JSON byte budget exceeded.');
+    };
+    const visit = (value, depth) => {
+        if (++nodes > 65_536 || depth > 16)
+            atlasFailure('JSON node/depth budget exceeded.');
+        if (value === null || typeof value === 'boolean') {
+            addBytes(value === false ? 5 : 4);
+            return;
+        }
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                atlasFailure('JSON numbers must be finite.');
+            addBytes(JSON.stringify(value).length);
+            return;
+        }
+        if (typeof value === 'string') {
+            if (value.length > 4096)
+                atlasFailure('JSON string budget exceeded.');
+            addBytes(encoder.encode(JSON.stringify(value)).length);
+            return;
+        }
+        if (typeof value !== 'object')
+            atlasFailure('plain JSON data is required.');
+        const array = Array.isArray(value), proto = Object.getPrototypeOf(value);
+        if (array ? proto !== Array.prototype : proto !== null && proto !== Object.prototype)
+            atlasFailure('plain JSON prototypes are required.');
+        const length = array ? Object.getOwnPropertyDescriptor(value, 'length')?.value : undefined;
+        if (array && (!Number.isSafeInteger(length) || length > 1024))
+            atlasFailure('JSON array budget exceeded.');
+        const keys = Reflect.ownKeys(value);
+        if (keys.length > 1024 || (array && keys.length !== length + 1))
+            atlasFailure('dense bounded JSON fields are required.');
+        addBytes(2 + Math.max(0, keys.length - (array ? 1 : 0) - 1));
+        for (const key of keys) {
+            if (array && key === 'length')
+                continue;
+            if (typeof key !== 'string' || ['__proto__', 'prototype', 'constructor'].includes(key))
+                atlasFailure('forbidden JSON field.');
+            if (key.length > 4096)
+                atlasFailure('JSON field name budget exceeded.');
+            if (!array)
+                addBytes(encoder.encode(JSON.stringify(key)).length + 1);
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor.enumerable || !('value' in descriptor))
+                atlasFailure('JSON accessors/hidden fields are unsupported.');
+            if (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= length))
+                atlasFailure('invalid JSON array key.');
+            visit(descriptor.value, depth + 1);
+        }
+    };
+    visit(input, 0);
+}
+function record(value, fields, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        atlasFailure(`${label} must be a JSON object.`);
+    const r = value;
+    if (Object.keys(r).some((k) => !fields.includes(k)))
+        atlasFailure(`${label} has an unknown field.`);
+    return r;
+}
+function integer(value, min, max, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min || value > max)
+        atlasFailure(`${label} must be an integer ${min}..${max}.`);
+    return value === 0 ? 0 : value;
+}
+function hash(value, label) {
+    if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(value))
+        atlasFailure(`${label} must be an exact SHA-256 hash.`);
+    return value;
+}
+function rect(value, label) {
+    const r = record(value, ['x', 'y', 'width', 'height'], label);
+    return {
+        x: integer(r['x'], 0, 4096, `${label}.x`),
+        y: integer(r['y'], 0, 4096, `${label}.y`),
+        width: integer(r['width'], 1, 4096, `${label}.width`),
+        height: integer(r['height'], 1, 4096, `${label}.height`),
+    };
+}
+export function atlasAllocationV1(region) {
+    const { content: c, gutter: g } = region;
+    return { x: c.x - g, y: c.y - g, width: c.width + 2 * g, height: c.height + 2 * g };
+}
+export function assertAtlasCropV1(crop, content, width, height) {
+    if (crop.x + crop.width > width || crop.y + crop.height > height)
+        atlasFailure('source crop is out of bounds.');
+    if (crop.width !== content.width || crop.height !== content.height)
+        atlasFailure('source crop/content dimensions must match; resampling is unsupported.');
+}
+export function atlasSourceIdentityV1(source) {
+    return source.kind === 'procedural'
+        ? `procedural:${hashProceduralTextureSpecV3(source.spec)}`
+        : `resource:${source.pin.resourceId}:${source.pin.revisionId}:${source.resourceId}`;
+}
+export function canonicalizeTextureAtlasSpecV1(input) {
+    preflight(input);
+    const r = record(input, ['schemaVersion', 'width', 'height', 'usage', 'sampler', 'regions'], 'atlas');
+    if (r['schemaVersion'] !== 1)
+        atlasFailure('schemaVersion must be 1.');
+    const width = integer(r['width'], 4, TEXTURE_ATLAS_LIMITS.edge, 'width'), height = integer(r['height'], 4, TEXTURE_ATLAS_LIMITS.edge, 'height');
+    if (!TEXTURE_USAGES.includes(r['usage']))
+        atlasFailure('usage must be a texture usage.');
+    const usage = r['usage'];
+    if (!Array.isArray(r['regions']) ||
+        !r['regions'].length ||
+        r['regions'].length > TEXTURE_ATLAS_LIMITS.regions)
+        atlasFailure('regions must contain 1..64 entries.');
+    const regions = r['regions']
+        .map((value, i) => {
+        const q = record(value, ['name', 'content', 'gutter', 'edgeMode', 'source', 'crop'], `regions[${i}]`);
+        if (typeof q['name'] !== 'string' || !/^[a-z][a-z0-9_-]{0,79}$/.test(q['name']))
+            atlasFailure('region name must be a stable lowercase identifier.');
+        const content = rect(q['content'], 'content'), gutter = q['gutter'] === undefined ? 2 : integer(q['gutter'], 0, 32, 'gutter');
+        const edgeMode = q['edgeMode'] === undefined ? 'copy-edge' : q['edgeMode'];
+        if (!['copy-edge', 'mask-rgb-dilate'].includes(edgeMode))
+            atlasFailure('unsupported edgeMode.');
+        if (edgeMode === 'mask-rgb-dilate' && usage !== 'albedo' && usage !== 'emissive')
+            atlasFailure('mask RGB dilation requires color usage.');
+        const s = record(q['source'], ['kind', 'spec', 'resourceId', 'pin', 'expected'], 'source');
+        let source;
+        let crop = q['crop'] === undefined ? undefined : rect(q['crop'], 'crop');
+        if (s['kind'] === 'procedural') {
+            record(s, ['kind', 'spec'], 'procedural source');
+            const admission = admitProceduralTextureSpecV3(s['spec']);
+            if (admission.spec.usage !== usage)
+                atlasFailure('source usage does not match atlas usage.');
+            source = { kind: 'procedural', spec: admission.spec };
+            crop ??= { x: 0, y: 0, width: admission.spec.width, height: admission.spec.height };
+            assertAtlasCropV1(crop, content, admission.spec.width, admission.spec.height);
+        }
+        else if (s['kind'] === 'resource') {
+            record(s, ['kind', 'resourceId', 'pin', 'expected'], 'resource source');
+            if (typeof s['resourceId'] !== 'string' ||
+                !/^[a-zA-Z0-9][a-zA-Z0-9_.:/-]{0,199}$/.test(s['resourceId']))
+                atlasFailure('source resourceId must be an exact returned map ID.');
+            const p = record(s['pin'], ['resourceId', 'revisionId', 'sha256'], 'source pin');
+            if (typeof p['resourceId'] !== 'string' || !/^[a-z][a-z0-9_-]{0,79}$/.test(p['resourceId']))
+                atlasFailure('pin resourceId must be a material ID.');
+            const revisionId = hash(p['revisionId'], 'pin revisionId'), sha256 = hash(p['sha256'], 'pin sha256');
+            if (revisionId !== sha256)
+                atlasFailure('source pin revision/hash mismatch.');
+            let expected;
+            if (s['expected'] !== undefined) {
+                const e = record(s['expected'], ['width', 'height', 'imageSha256', 'decodedPixelHash'], 'source expected');
+                expected = {
+                    ...(e['width'] === undefined
+                        ? {}
+                        : { width: integer(e['width'], 1, 4096, 'expected.width') }),
+                    ...(e['height'] === undefined
+                        ? {}
+                        : { height: integer(e['height'], 1, 4096, 'expected.height') }),
+                    ...(e['imageSha256'] === undefined
+                        ? {}
+                        : { imageSha256: hash(e['imageSha256'], 'expected.imageSha256') }),
+                    ...(e['decodedPixelHash'] === undefined
+                        ? {}
+                        : { decodedPixelHash: hash(e['decodedPixelHash'], 'expected.decodedPixelHash') }),
+                };
+            }
+            source = {
+                kind: 'resource',
+                resourceId: s['resourceId'],
+                pin: { resourceId: p['resourceId'], revisionId, sha256 },
+                ...(expected ? { expected } : {}),
+            };
+            if (crop && (crop.width !== content.width || crop.height !== content.height))
+                atlasFailure('source crop/content dimensions must match; resampling is unsupported.');
+        }
+        else
+            atlasFailure('source kind must be procedural or pinned resource.');
+        const result = {
+            name: q['name'],
+            content,
+            gutter,
+            edgeMode: edgeMode,
+            source,
+            ...(crop ? { crop } : {}),
+        };
+        const allocation = atlasAllocationV1(result);
+        if (allocation.x < 0 ||
+            allocation.y < 0 ||
+            allocation.x + allocation.width > width ||
+            allocation.y + allocation.height > height)
+            atlasFailure('padded allocation is out of bounds.');
+        return result;
+    })
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    if (new Set(regions.map((v) => v.name)).size !== regions.length)
+        atlasFailure('duplicate region name.');
+    for (let i = 0; i < regions.length; i++)
+        for (let j = i + 1; j < regions.length; j++) {
+            const a = atlasAllocationV1(regions[i]), b = atlasAllocationV1(regions[j]);
+            if (a.x < b.x + b.width &&
+                b.x < a.x + a.width &&
+                a.y < b.y + b.height &&
+                b.y < a.y + a.height)
+                atlasFailure(`padded allocations overlap: ${regions[i].name}, ${regions[j].name}.`);
+        }
+    if (new Set(regions.map((v) => atlasSourceIdentityV1(v.source))).size > TEXTURE_ATLAS_LIMITS.sources)
+        atlasFailure('distinct source budget exceeds 16.');
+    let sampler;
+    try {
+        sampler = canonicalizePortableSamplerV1(r['sampler'] === undefined
+            ? {
+                minFilter: 'linear-mipmap-linear',
+                magFilter: 'linear',
+                wrapS: 'clamp-to-edge',
+                wrapT: 'clamp-to-edge',
+            }
+            : r['sampler']);
+    }
+    catch (e) {
+        atlasFailure(`sampler: ${e.message}`);
+    }
+    const spec = {
+        schemaVersion: 1,
+        width,
+        height,
+        usage,
+        sampler,
+        regions,
+    };
+    if (new TextEncoder().encode(JSON.stringify(spec)).length > TEXTURE_ATLAS_LIMITS.jsonBytes)
+        atlasFailure('canonical JSON byte budget exceeded.');
+    return spec;
+}
+export function canonicalTextureAtlasJsonV1(input) {
+    return JSON.stringify(canonicalizeTextureAtlasSpecV1(input));
+}
+export function hashTextureAtlasSpecV1(input) {
+    return `sha256:${sha256Hex(`${TEXTURE_ATLAS_COMPILER_ID}\n${canonicalTextureAtlasJsonV1(input)}`)}`;
+}
+/** Internal identity helper for bounded atlas metadata; stable across object property order. */
+export function canonicalAtlasMetadataJsonV1(input) {
+    preflight(input);
+    const sort = (value) => Array.isArray(value)
+        ? value.map(sort)
+        : value !== null && typeof value === 'object'
+            ? Object.fromEntries(Object.entries(value)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([k, v]) => [k, sort(v)]))
+            : value;
+    return JSON.stringify(sort(input));
+}
+export function atlasLayoutHashV1(spec) {
+    return `sha256:${sha256Hex(`kiln.atlas-layout.v1\n${canonicalAtlasMetadataJsonV1({ width: spec.width, height: spec.height, origin: 'top-left', regions: spec.regions.map((r) => ({ name: r.name, content: r.content, allocation: atlasAllocationV1(r) })) })}`)}`;
+}
+/** Pure persisted-manifest reader. Actual PNG/RGBA and recompilation belong to the host. */
+export function validateTextureAtlasManifestV1(input, providedSpec) {
+    preflight(input);
+    const spec = canonicalizeTextureAtlasSpecV1(providedSpec);
+    const r = record(input, [
+        'version',
+        'compilerId',
+        'width',
+        'height',
+        'usage',
+        'origin',
+        'sampler',
+        'specHash',
+        'layoutHash',
+        'decodedPixelHash',
+        'atlasPixelHash',
+        'sources',
+        'regions',
+        'manifestHash',
+    ], 'manifest');
+    if (r['version'] !== 'kiln.atlas-manifest.v1' ||
+        r['compilerId'] !== TEXTURE_ATLAS_COMPILER_ID ||
+        r['width'] !== spec.width ||
+        r['height'] !== spec.height ||
+        r['usage'] !== spec.usage ||
+        r['origin'] !== 'top-left')
+        atlasFailure('manifest version/compiler/dimensions/usage/origin mismatch.');
+    if (canonicalAtlasMetadataJsonV1(r['sampler']) !== canonicalAtlasMetadataJsonV1(spec.sampler) ||
+        r['specHash'] !== hashTextureAtlasSpecV1(spec) ||
+        r['layoutHash'] !== atlasLayoutHashV1(spec))
+        atlasFailure('manifest sampler/spec/layout identity mismatch.');
+    hash(r['decodedPixelHash'], 'manifest decodedPixelHash');
+    hash(r['atlasPixelHash'], 'manifest atlasPixelHash');
+    const expectedSources = new Map(spec.regions.map((region) => [atlasSourceIdentityV1(region.source), region.source]));
+    if (!Array.isArray(r['sources']) ||
+        r['sources'].length !== expectedSources.size ||
+        !Array.isArray(r['regions']) ||
+        r['regions'].length !== spec.regions.length)
+        atlasFailure('manifest source/region inventory mismatch.');
+    const dimensions = new Map();
+    for (const sourceValue of r['sources']) {
+        const s = record(sourceValue, [
+            'id',
+            'kind',
+            'width',
+            'height',
+            'decodedPixelHash',
+            'recipeHash',
+            'compilerId',
+            'descriptor',
+        ], 'manifest source');
+        if (typeof s['id'] !== 'string' || dimensions.has(s['id']))
+            atlasFailure('duplicate/invalid manifest source identity.');
+        const source = expectedSources.get(s['id']);
+        if (!source || s['kind'] !== source.kind)
+            atlasFailure('manifest source identity mismatch.');
+        const width = integer(s['width'], 1, 4096, 'manifest source width'), height = integer(s['height'], 1, 4096, 'manifest source height');
+        hash(s['decodedPixelHash'], 'manifest source decodedPixelHash');
+        if (source.kind === 'procedural') {
+            record(s, ['id', 'kind', 'width', 'height', 'decodedPixelHash', 'recipeHash', 'compilerId'], 'manifest procedural source');
+            if (width !== source.spec.width ||
+                height !== source.spec.height ||
+                s['recipeHash'] !== hashProceduralTextureSpecV3(source.spec) ||
+                s['compilerId'] !== 'kiln.procedural-rgba.v3.1')
+                atlasFailure('manifest procedural source identity mismatch.');
+        }
+        else {
+            record(s, ['id', 'kind', 'width', 'height', 'decodedPixelHash', 'descriptor'], 'manifest resource source');
+            const d = record(s['descriptor'], [
+                'materialId',
+                'revisionId',
+                'resourceId',
+                'slot',
+                'usage',
+                'colorSpace',
+                'width',
+                'height',
+                'encodedByteLength',
+                'imageSha256',
+                'decodedPixelHash',
+            ], 'manifest source descriptor');
+            const slots = {
+                baseColor: 'albedo',
+                normal: 'normal',
+                metallicRoughness: 'metallicRoughness',
+                emissive: 'emissive',
+                occlusion: 'occlusion',
+            };
+            if (d['materialId'] !== source.pin.resourceId ||
+                d['revisionId'] !== source.pin.revisionId ||
+                d['resourceId'] !== source.resourceId ||
+                d['width'] !== width ||
+                d['height'] !== height ||
+                d['usage'] !== spec.usage ||
+                typeof d['slot'] !== 'string' ||
+                slots[d['slot']] !== spec.usage ||
+                d['colorSpace'] !==
+                    (spec.usage === 'albedo' || spec.usage === 'emissive' ? 'srgb' : 'linear'))
+                atlasFailure('manifest pinned resource descriptor mismatch.');
+            hash(d['imageSha256'], 'manifest source imageSha256');
+            integer(d['encodedByteLength'], 1, TEXTURE_ATLAS_LIMITS.encodedSourceBytes, 'manifest encodedByteLength');
+            if (d['decodedPixelHash'] !== undefined && d['decodedPixelHash'] !== s['decodedPixelHash'])
+                atlasFailure('manifest source decodedPixelHash mismatch.');
+            for (const key of ['width', 'height', 'imageSha256', 'decodedPixelHash']) {
+                const expected = source.expected?.[key];
+                if (expected !== undefined && expected !== (key === 'decodedPixelHash' ? s[key] : d[key]))
+                    atlasFailure('manifest source expectation mismatch.');
+            }
+        }
+        dimensions.set(s['id'], { width, height });
+    }
+    for (let i = 0; i < spec.regions.length; i++) {
+        const region = spec.regions[i], v = record(r['regions'][i], ['name', 'content', 'allocation', 'crop', 'sourceId'], 'manifest region');
+        const sourceId = atlasSourceIdentityV1(region.source), size = dimensions.get(sourceId);
+        const crop = region.crop ?? { x: 0, y: 0, width: size.width, height: size.height };
+        assertAtlasCropV1(crop, region.content, size.width, size.height);
+        if (v['name'] !== region.name ||
+            v['sourceId'] !== sourceId ||
+            canonicalAtlasMetadataJsonV1(v['content']) !== canonicalAtlasMetadataJsonV1(region.content) ||
+            canonicalAtlasMetadataJsonV1(v['allocation']) !==
+                canonicalAtlasMetadataJsonV1(atlasAllocationV1(region)) ||
+            canonicalAtlasMetadataJsonV1(v['crop']) !== canonicalAtlasMetadataJsonV1(crop))
+            atlasFailure('manifest named region/crop/allocation identity mismatch.');
+    }
+    const { manifestHash, ...payload } = r;
+    if (manifestHash !==
+        `sha256:${sha256Hex(`kiln.atlas-manifest.v1\n${canonicalAtlasMetadataJsonV1(payload)}`)}`)
+        atlasFailure('manifest hash mismatch.');
+    return structuredClone(input);
+}