@instruktlabs/kiln 1.2.2 → 1.2.3

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

@@ -0,0 +1,73 @@
+import { type ProceduralTextureAdmissionV3 } from "./procedural-texture-v3-contract.js";
+import type { PinnedMaterialMapPortV1, VerifiedPinnedMaterialMapDescriptorV1 } from "./pinned-material-map.js";
+import { TEXTURE_ATLAS_COMPILER_ID, type AtlasRectangleV1, type CanonicalTextureAtlasSourceV1, type CanonicalTextureAtlasSpecV1 } from "./texture-atlas-contract.js";
+type Hash = `sha256:${string}`;
+export interface TextureAtlasCompileOptionsV1 {
+    resources?: PinnedMaterialMapPortV1;
+    signal?: AbortSignal;
+}
+export interface TextureAtlasBudgetV1 {
+    sourceTexels: number;
+    encodedBytes: number;
+    workUnits: number;
+    conservativePixelAllocationBytes: number;
+    dilationScratchBytes: number;
+}
+interface PreparedSource {
+    id: string;
+    source: CanonicalTextureAtlasSourceV1;
+    width: number;
+    height: number;
+    descriptor?: VerifiedPinnedMaterialMapDescriptorV1;
+    admission?: ProceduralTextureAdmissionV3;
+}
+export interface TextureAtlasAdmissionV1 {
+    spec: CanonicalTextureAtlasSpecV1;
+    sources: PreparedSource[];
+    crops: Map<string, AtlasRectangleV1>;
+    budget: TextureAtlasBudgetV1;
+}
+export interface TextureAtlasSourceManifestV1 {
+    id: string;
+    kind: 'procedural' | 'resource';
+    width: number;
+    height: number;
+    decodedPixelHash: Hash;
+    recipeHash?: Hash;
+    compilerId?: string;
+    descriptor?: VerifiedPinnedMaterialMapDescriptorV1;
+}
+export interface TextureAtlasRegionManifestV1 {
+    name: string;
+    content: AtlasRectangleV1;
+    allocation: AtlasRectangleV1;
+    crop: AtlasRectangleV1;
+    sourceId: string;
+}
+export interface TextureAtlasManifestV1 {
+    version: 'kiln.atlas-manifest.v1';
+    compilerId: typeof TEXTURE_ATLAS_COMPILER_ID;
+    width: number;
+    height: number;
+    usage: CanonicalTextureAtlasSpecV1['usage'];
+    origin: 'top-left';
+    sampler: CanonicalTextureAtlasSpecV1['sampler'];
+    specHash: Hash;
+    layoutHash: Hash;
+    decodedPixelHash: Hash;
+    atlasPixelHash: Hash;
+    sources: TextureAtlasSourceManifestV1[];
+    regions: TextureAtlasRegionManifestV1[];
+    manifestHash: Hash;
+}
+export interface CompiledTextureAtlasV1 {
+    spec: CanonicalTextureAtlasSpecV1;
+    canonicalJson: string;
+    pixels: Uint8Array;
+    manifest: TextureAtlasManifestV1;
+    budget: TextureAtlasBudgetV1;
+}
+/** Admit all sources and aggregate work/buffer allocations before any source pixel load. */
+export declare function admitTextureAtlasSpecV1(input: unknown, options?: TextureAtlasCompileOptionsV1): TextureAtlasAdmissionV1;
+export declare function compileTextureAtlasSpecV1(input: unknown, options?: TextureAtlasCompileOptionsV1): Promise<CompiledTextureAtlasV1>;
+export {};

package/lib/texture-atlas-pixels.js

@@ -0,0 +1,290 @@
+/** Deterministic fixed-scale composition. Resource loading is a trusted host capability. */
+import { compileProceduralTextureSpecV3 } from "./procedural-texture-v3.js";
+import { admitProceduralTextureSpecV3, hashProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, } from "./procedural-texture-v3-contract.js";
+import { sha256Hex } from "./procedural-material-v2.js";
+import { atlasAllocationV1, atlasFailure, atlasLayoutHashV1, atlasSourceIdentityV1, assertAtlasCropV1, canonicalizeTextureAtlasSpecV1, canonicalAtlasMetadataJsonV1, hashTextureAtlasSpecV1, TEXTURE_ATLAS_COMPILER_ID, TEXTURE_ATLAS_LIMITS, } from "./texture-atlas-contract.js";
+const isHash = (value) => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+const boundedInteger = (value, max) => Number.isSafeInteger(value) && value >= 1 && value <= max;
+function checkDescriptor(d, source, usage) {
+    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 ||
+        !isHash(d.revisionId) ||
+        !isHash(d.imageSha256))
+        atlasFailure('pinned source descriptor identity/hash mismatch.');
+    if (d.usage !== usage ||
+        slots[d.slot] !== usage ||
+        d.colorSpace !== (usage === 'albedo' || usage === 'emissive' ? 'srgb' : 'linear'))
+        atlasFailure('pinned source usage/slot/colorSpace mismatch.');
+    if (!boundedInteger(d.width, 4096) ||
+        !boundedInteger(d.height, 4096) ||
+        !boundedInteger(d.encodedByteLength, TEXTURE_ATLAS_LIMITS.encodedSourceBytes) ||
+        (d.decodedPixelHash !== undefined && !isHash(d.decodedPixelHash)))
+        atlasFailure('pinned source dimensions/byte/hash budget is invalid.');
+    for (const key of ['width', 'height', 'imageSha256', 'decodedPixelHash']) {
+        const expected = source.expected?.[key];
+        if (expected !== undefined && d[key] !== undefined && expected !== d[key])
+            atlasFailure(`source expected ${key} does not match verified descriptor.`);
+    }
+}
+/** Admit all sources and aggregate work/buffer allocations before any source pixel load. */
+export function admitTextureAtlasSpecV1(input, options = {}) {
+    const spec = canonicalizeTextureAtlasSpecV1(input), unique = new Map(), crops = new Map();
+    const outputTexels = spec.width * spec.height;
+    // Include output and two output-sized hash snapshots/domain concatenation buffers.
+    const budget = {
+        sourceTexels: 0,
+        encodedBytes: 0,
+        workUnits: outputTexels * 13,
+        conservativePixelAllocationBytes: outputTexels * 12,
+        dilationScratchBytes: 0,
+    };
+    for (const region of spec.regions) {
+        const id = atlasSourceIdentityV1(region.source);
+        let prepared = unique.get(id);
+        if (!prepared) {
+            if (region.source.kind === 'procedural') {
+                const admission = admitProceduralTextureSpecV3(region.source.spec);
+                prepared = {
+                    id,
+                    source: region.source,
+                    width: admission.spec.width,
+                    height: admission.spec.height,
+                    admission,
+                };
+                budget.workUnits += admission.estimatedWorkUnits;
+                budget.conservativePixelAllocationBytes += admission.conservativePixelAllocationBytes;
+            }
+            else {
+                const described = options.resources?.describePinnedMaterialMap(region.source.resourceId, region.source.pin);
+                if (!described)
+                    atlasFailure(`source ${region.name} requires a verified pinned library map. Get its exact map ID with kiln_material get and supply materialDependencies or project pins; approved resources are unsupported for atlas sources.`);
+                checkDescriptor(described, region.source, spec.usage);
+                // Snapshot verified metadata before an async loader can mutate its own object.
+                const descriptor = structuredClone(described);
+                prepared = {
+                    id,
+                    source: region.source,
+                    width: descriptor.width,
+                    height: descriptor.height,
+                    descriptor,
+                };
+                budget.encodedBytes += descriptor.encodedByteLength;
+                // Returned owned pixels + our immutable snapshot + decoder/copy allowance + encoded input.
+                budget.conservativePixelAllocationBytes +=
+                    descriptor.width * descriptor.height * 12 + descriptor.encodedByteLength;
+            }
+            const texels = prepared.width * prepared.height;
+            budget.sourceTexels += texels;
+            budget.workUnits += texels * 8;
+            budget.conservativePixelAllocationBytes += texels * 4; // Raw-pixel hash snapshot allowance.
+            unique.set(id, prepared);
+        }
+        if (region.source.kind === 'resource')
+            checkDescriptor(prepared.descriptor, region.source, spec.usage);
+        const crop = region.crop ?? { x: 0, y: 0, width: prepared.width, height: prepared.height };
+        assertAtlasCropV1(crop, region.content, prepared.width, prepared.height);
+        crops.set(region.name, crop);
+        const allocation = atlasAllocationV1(region), texels = allocation.width * allocation.height;
+        budget.workUnits += texels * (region.edgeMode === 'mask-rgb-dilate' ? 16 : 2);
+        if (region.edgeMode === 'mask-rgb-dilate')
+            budget.dilationScratchBytes = Math.max(budget.dilationScratchBytes, texels * 8);
+    }
+    budget.workUnits += (spec.regions.length * (spec.regions.length - 1)) / 2;
+    budget.conservativePixelAllocationBytes += budget.dilationScratchBytes;
+    if (budget.sourceTexels > TEXTURE_ATLAS_LIMITS.sourceTexels)
+        atlasFailure('full decoded source texel budget exceeded; a small crop does not reduce source decode cost.');
+    if (budget.encodedBytes > TEXTURE_ATLAS_LIMITS.encodedBytes)
+        atlasFailure('aggregate encoded source byte budget exceeded.');
+    if (budget.workUnits > TEXTURE_ATLAS_LIMITS.work)
+        atlasFailure(`aggregate work budget ${budget.workUnits} exceeds ${TEXTURE_ATLAS_LIMITS.work}.`);
+    if (budget.conservativePixelAllocationBytes > TEXTURE_ATLAS_LIMITS.allocatedBytes)
+        atlasFailure(`aggregate pixel allocation budget ${budget.conservativePixelAllocationBytes} exceeds ${TEXTURE_ATLAS_LIMITS.allocatedBytes}.`);
+    return {
+        spec,
+        sources: [...unique.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        crops,
+        budget,
+    };
+}
+async function pixelDigest(bytes) {
+    // Compiler/host snapshots are ArrayBuffer-backed, never shared mutable cache state.
+    const result = await crypto.subtle.digest('SHA-256', bytes);
+    return `sha256:${[...new Uint8Array(result)].map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+}
+function cancelled(signal) {
+    if (signal?.aborted)
+        atlasFailure('compilation cancelled.');
+}
+/** Copy exact crop and fill only this region's disjoint allocation. Scratch is reused. */
+function composeRegion(output, atlasWidth, region, crop, source, sourceWidth, distances, donors) {
+    const allocation = atlasAllocationV1(region), w = allocation.width, h = allocation.height, g = region.gutter;
+    const sourcePixel = (cx, cy) => ((crop.y + cy) * sourceWidth + crop.x + cx) * 4;
+    const destination = (x, y) => ((allocation.y + y) * atlasWidth + allocation.x + x) * 4;
+    if (region.edgeMode === 'copy-edge') {
+        for (let y = 0; y < h; y++)
+            for (let x = 0; x < w; x++) {
+                const s = sourcePixel(Math.max(0, Math.min(crop.width - 1, x - g)), Math.max(0, Math.min(crop.height - 1, y - g))), d = destination(x, y);
+                for (let c = 0; c < 4; c++)
+                    output[d + c] = source[s + c];
+            }
+        return;
+    }
+    const length = w * h, infinity = 0x3fffffff;
+    distances.fill(infinity, 0, length);
+    donors.fill(infinity, 0, length);
+    for (let cy = 0; cy < crop.height; cy++)
+        for (let cx = 0; cx < crop.width; cx++) {
+            const s = sourcePixel(cx, cy), d = destination(cx + g, cy + g), index = (cy + g) * w + cx + g;
+            for (let c = 0; c < 4; c++)
+                output[d + c] = source[s + c];
+            if (source[s + 3] > 0) {
+                distances[index] = 0;
+                donors[index] = cy * crop.width + cx;
+            }
+        }
+    const consider = (i, neighbor) => {
+        const distance = distances[neighbor] + 1;
+        if (distance < distances[i] ||
+            (distance === distances[i] && donors[neighbor] < donors[i])) {
+            distances[i] = distance;
+            donors[i] = donors[neighbor];
+        }
+    };
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            const i = y * w + x;
+            if (x)
+                consider(i, i - 1);
+            if (y)
+                consider(i, i - w);
+        }
+    for (let y = h - 1; y >= 0; y--)
+        for (let x = w - 1; x >= 0; x--) {
+            const i = y * w + x;
+            if (x + 1 < w)
+                consider(i, i + 1);
+            if (y + 1 < h)
+                consider(i, i + w);
+        }
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            const d = destination(x, y);
+            if (output[d + 3] > 0)
+                continue;
+            const donor = donors[y * w + x];
+            if (donor === infinity) {
+                output[d] = 0;
+                output[d + 1] = 0;
+                output[d + 2] = 0;
+            }
+            else {
+                const s = sourcePixel(donor % crop.width, Math.floor(donor / crop.width));
+                for (let c = 0; c < 3; c++)
+                    output[d + c] = source[s + c];
+            }
+        }
+}
+export async function compileTextureAtlasSpecV1(input, options = {}) {
+    const admission = admitTextureAtlasSpecV1(input, options), { spec, sources, crops, budget } = admission;
+    cancelled(options.signal);
+    const sourcePixels = new Map(), sourceManifests = [];
+    // Sequential loads avoid multiplying decoder/snapshot peaks; each exact source compiles once.
+    for (const prepared of sources) {
+        cancelled(options.signal);
+        let pixels, manifest;
+        if (prepared.source.kind === 'procedural') {
+            pixels = compileProceduralTextureSpecV3(prepared.source.spec).pixels;
+            manifest = {
+                id: prepared.id,
+                kind: 'procedural',
+                width: prepared.width,
+                height: prepared.height,
+                decodedPixelHash: await pixelDigest(pixels),
+                recipeHash: hashProceduralTextureSpecV3(prepared.source.spec),
+                compilerId: PROCEDURAL_TEXTURE_V3_COMPILER_ID,
+            };
+        }
+        else {
+            const resolved = await options.resources.resolvePinnedMaterialMapPixels(prepared.source.resourceId, prepared.source.pin, { signal: options.signal });
+            checkDescriptor(resolved.descriptor, prepared.source, spec.usage);
+            if (canonicalAtlasMetadataJsonV1(resolved.descriptor) !==
+                canonicalAtlasMetadataJsonV1(prepared.descriptor))
+                atlasFailure('resolved source descriptor changed after admission.');
+            if (!(resolved.pixels instanceof Uint8Array) ||
+                resolved.pixels.length !== prepared.width * prepared.height * 4)
+                atlasFailure('decoded source RGBA dimensions/length mismatch.');
+            pixels = Uint8Array.from(resolved.pixels);
+            const decodedPixelHash = await pixelDigest(pixels);
+            if (decodedPixelHash !== resolved.decodedPixelHash ||
+                (prepared.descriptor.decodedPixelHash !== undefined &&
+                    decodedPixelHash !== prepared.descriptor.decodedPixelHash))
+                atlasFailure('decoded source pixel hash mismatch.');
+            manifest = {
+                id: prepared.id,
+                kind: 'resource',
+                width: prepared.width,
+                height: prepared.height,
+                decodedPixelHash,
+                descriptor: prepared.descriptor,
+            };
+        }
+        sourcePixels.set(prepared.id, pixels);
+        sourceManifests.push(manifest);
+    }
+    // Compare every reuse's expectations, including an old external source without a descriptor hash.
+    for (const region of spec.regions)
+        if (region.source.kind === 'resource' &&
+            region.source.expected?.decodedPixelHash !== undefined) {
+            const actual = sourceManifests.find((v) => v.id === atlasSourceIdentityV1(region.source)).decodedPixelHash;
+            if (actual !== region.source.expected.decodedPixelHash)
+                atlasFailure('source expected decodedPixelHash mismatch.');
+        }
+    cancelled(options.signal);
+    const pixels = new Uint8Array(spec.width * spec.height * 4), scratchLength = budget.dilationScratchBytes / 8;
+    const distances = new Int32Array(scratchLength), donors = new Int32Array(scratchLength);
+    for (const region of spec.regions)
+        composeRegion(pixels, spec.width, region, crops.get(region.name), sourcePixels.get(atlasSourceIdentityV1(region.source)), sources.find((v) => v.id === atlasSourceIdentityV1(region.source)).width, distances, donors);
+    const decodedPixelHash = await pixelDigest(pixels), header = new TextEncoder().encode(`kiln.atlas-pixels.v1\n${spec.width},${spec.height},${spec.usage}\n`);
+    const tagged = new Uint8Array(header.length + pixels.length);
+    tagged.set(header);
+    tagged.set(pixels, header.length);
+    const atlasPixelHash = await pixelDigest(tagged);
+    const payload = {
+        version: 'kiln.atlas-manifest.v1',
+        compilerId: TEXTURE_ATLAS_COMPILER_ID,
+        width: spec.width,
+        height: spec.height,
+        usage: spec.usage,
+        origin: 'top-left',
+        sampler: spec.sampler,
+        specHash: hashTextureAtlasSpecV1(spec),
+        layoutHash: atlasLayoutHashV1(spec),
+        decodedPixelHash,
+        atlasPixelHash,
+        sources: sourceManifests,
+        regions: spec.regions.map((r) => ({
+            name: r.name,
+            content: r.content,
+            allocation: atlasAllocationV1(r),
+            crop: crops.get(r.name),
+            sourceId: atlasSourceIdentityV1(r.source),
+        })),
+    };
+    const manifestHash = `sha256:${sha256Hex(`kiln.atlas-manifest.v1\n${canonicalAtlasMetadataJsonV1(payload)}`)}`;
+    cancelled(options.signal);
+    return {
+        spec,
+        canonicalJson: JSON.stringify(spec),
+        pixels,
+        manifest: { ...payload, manifestHash },
+        budget,
+    };
+}

package/lib/texture-atlas.d.ts

@@ -0,0 +1,10 @@
+/** Three state and affine UV wrapper; host resources never enter authored arguments. */
+import * as THREE from 'three';
+import { type TextureAtlasCompileOptionsV1, type TextureAtlasManifestV1 } from "./texture-atlas-pixels.js";
+/** SDK/host API. Sandbox integration closes over options and exposes exactly one argument. */
+export declare function textureAtlas(input: unknown, options?: TextureAtlasCompileOptionsV1): Promise<THREE.DataTexture>;
+export interface AtlasUVOptionsV1 {
+    inputOrigin: 'top-left' | 'bottom-left';
+    mode: 'content-boundary' | 'texel-center';
+}
+export declare function remapUVToAtlas(geometry: THREE.BufferGeometry, atlas: THREE.Texture | TextureAtlasManifestV1, name: string, options: AtlasUVOptionsV1): THREE.BufferGeometry;

package/lib/texture-atlas.js

@@ -0,0 +1,143 @@
+/** Three state and affine UV wrapper; host resources never enter authored arguments. */
+import * as THREE from 'three';
+import { applyPortableSamplerV1 } from "./portable-sampler-runtime.js";
+import { compileTextureAtlasSpecV1, } from "./texture-atlas-pixels.js";
+import { atlasFailure, canonicalAtlasMetadataJsonV1, TEXTURE_ATLAS_COMPILER_ID, TEXTURE_ATLAS_LIMITS, } from "./texture-atlas-contract.js";
+import { sha256Hex } from "./procedural-material-v2.js";
+import { remapUV } from "./uv-shapes.js";
+/** SDK/host API. Sandbox integration closes over options and exposes exactly one argument. */
+export async function textureAtlas(input, options = {}) {
+    const compiled = await compileTextureAtlasSpecV1(input, options);
+    const texture = new THREE.DataTexture(compiled.pixels, compiled.spec.width, compiled.spec.height, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.name = 'Atlas';
+    texture.flipY = false;
+    texture.colorSpace =
+        compiled.spec.usage === 'albedo' || compiled.spec.usage === 'emissive'
+            ? THREE.SRGBColorSpace
+            : THREE.NoColorSpace;
+    applyPortableSamplerV1(texture, compiled.spec.sampler);
+    texture.userData.kilnAtlas = { spec: compiled.spec, manifest: compiled.manifest };
+    texture.userData.kilnTexture = {
+        usage: compiled.spec.usage,
+        colorSpace: compiled.spec.usage === 'albedo' || compiled.spec.usage === 'emissive' ? 'srgb' : 'linear',
+        width: compiled.spec.width,
+        height: compiled.spec.height,
+        hasAlpha: compiled.pixels.some((v, i) => i % 4 === 3 && v < 255),
+    };
+    return texture;
+}
+function manifestOf(atlas) {
+    const value = atlas?.isTexture
+        ? atlas.userData.kilnAtlas?.manifest
+        : atlas;
+    if (!value || typeof value !== 'object')
+        atlasFailure('an atlas texture or compiled manifest is required.');
+    canonicalAtlasMetadataJsonV1(value);
+    const manifest = value;
+    if (manifest.version !== 'kiln.atlas-manifest.v1' ||
+        manifest.compilerId !== TEXTURE_ATLAS_COMPILER_ID ||
+        manifest.origin !== 'top-left' ||
+        !Array.isArray(manifest.regions) ||
+        !manifest.regions.length ||
+        manifest.regions.length > 64 ||
+        !Number.isSafeInteger(manifest.width) ||
+        manifest.width < 4 ||
+        manifest.width > 1024 ||
+        !Number.isSafeInteger(manifest.height) ||
+        manifest.height < 4 ||
+        manifest.height > 1024)
+        atlasFailure('invalid atlas manifest dimensions/version.');
+    const { manifestHash, ...payload } = manifest;
+    if (`sha256:${sha256Hex(`kiln.atlas-manifest.v1\n${canonicalAtlasMetadataJsonV1(payload)}`)}` !==
+        manifestHash)
+        atlasFailure('atlas manifest identity mismatch.');
+    return manifest;
+}
+export function remapUVToAtlas(geometry, atlas, name, options) {
+    const manifest = manifestOf(atlas);
+    canonicalAtlasMetadataJsonV1(options);
+    if (!options ||
+        typeof options !== 'object' ||
+        Array.isArray(options) ||
+        Object.keys(options).some((k) => !['inputOrigin', 'mode'].includes(k)) ||
+        !['top-left', 'bottom-left'].includes(options.inputOrigin) ||
+        !['content-boundary', 'texel-center'].includes(options.mode))
+        atlasFailure('explicit inputOrigin and content-boundary/texel-center mode are required.');
+    const region = manifest.regions.find((r) => r.name === name);
+    if (!region)
+        atlasFailure(`unknown named region ${String(name)}.`);
+    const { x, y, width: w, height: h } = region.content;
+    if (![x, y, w, h].every(Number.isSafeInteger) ||
+        x < 0 ||
+        y < 0 ||
+        w < 1 ||
+        h < 1 ||
+        x + w > manifest.width ||
+        y + h > manifest.height)
+        atlasFailure('invalid region content rectangle.');
+    const uv = geometry?.getAttribute?.('uv'), position = geometry?.getAttribute?.('position');
+    if (!position ||
+        !uv ||
+        uv.itemSize !== 2 ||
+        uv.count !== position.count ||
+        uv.count < 1 ||
+        uv.count > TEXTURE_ATLAS_LIMITS.uvVertices ||
+        uv.isInstancedBufferAttribute ||
+        uv.data?.isInstancedInterleavedBuffer)
+        atlasFailure('matching per-vertex UV0 and positions are required; per-instance UVs are unsupported.');
+    let bytes = uv.count * 8;
+    const interleavedBuffers = new Set();
+    const count = (attribute) => {
+        if (attribute.isInterleavedBufferAttribute) {
+            // Three's geometry-copy data cache deduplicates interleaved backing buffers.
+            const buffer = attribute.array.buffer;
+            if (!interleavedBuffers.has(buffer)) {
+                interleavedBuffers.add(buffer);
+                bytes += buffer.byteLength;
+            }
+        }
+        else {
+            // Ordinary attributes/morphs/index clone independently even with shared input arrays.
+            // Typed convenience subclasses may allocate in both constructor and copy.
+            bytes +=
+                attribute.array.byteLength *
+                    (attribute.constructor === THREE.BufferAttribute ||
+                        attribute.constructor === THREE.InstancedBufferAttribute
+                        ? 1
+                        : 2);
+        }
+    };
+    for (const attr of Object.values(geometry.attributes))
+        count(attr);
+    for (const attrs of Object.values(geometry.morphAttributes))
+        for (const attr of attrs)
+            count(attr);
+    if (geometry.index)
+        count(geometry.index);
+    if (bytes > TEXTURE_ATLAS_LIMITS.uvAttributeBytes)
+        atlasFailure('owned UV clone attribute allocation budget exceeded.');
+    for (let i = 0; i < uv.count; i++)
+        if (![uv.getX(i), uv.getY(i)].every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
+            atlasFailure('UV0 must be finite in the unit domain [0,1]; region tiling is unsupported.');
+    const center = options.mode === 'texel-center', su = (w - (center ? 1 : 0)) / manifest.width, sv = (h - (center ? 1 : 0)) / manifest.height;
+    const bottom = options.inputOrigin === 'bottom-left';
+    const offset = [
+        (x + (center ? 0.5 : 0)) / manifest.width,
+        (y + (bottom ? h - (center ? 0.5 : 0) : center ? 0.5 : 0)) / manifest.height,
+    ];
+    const scale = [su, bottom ? -sv : sv];
+    const output = remapUV(geometry, { scale, offset });
+    output.userData.kilnAtlasBinding = {
+        manifestHash: manifest.manifestHash,
+        specHash: manifest.specHash,
+        layoutHash: manifest.layoutHash,
+        region: name,
+        content: structuredClone(region.content),
+        allocation: structuredClone(region.allocation),
+        inputOrigin: options.inputOrigin,
+        mode: options.mode,
+        scale,
+        offset,
+    };
+    return output;
+}

package/lib/texture-bake.d.ts

@@ -39,6 +39,7 @@
  * blocks, with a message that now names the procedural fix.
  */
 import * as THREE from 'three';
+import { type AtlasReferenceV1 } from "./atlas-provenance.js";
 import type { TextureUsage } from "./textures.js";
 export interface BakedTextureBindingV1 {
     node: string;
@@ -90,6 +91,8 @@ export interface BakedTextureProvenanceV1 {
      * regenerate the exact bytes. Absent for textures loaded from a file.
      */
     procedural?: ProceduralRecipeRecord;
+    /** Compact atlas source identity; the export scene table owns its recipe/manifest. */
+    atlas?: AtlasReferenceV1;
 }
 /** The `userData.kilnProcedural` stamp `proceduralTexture()` leaves behind. */
 interface ProceduralRecipeRecord {

package/lib/texture-bake.js

@@ -40,6 +40,7 @@
  */
 import { createHash } from 'node:crypto';
 import * as THREE from 'three';
+import { collectAtlasProvenance, readAtlasEncodedTexture, readValidatedAtlasDelivery, } from "./atlas-provenance.js";
 /**
  * Material slots the GLB bridge can serialize, with the glTF usage each one
  * implies. Kept in the same order the bridge reads them so a warning list and a
@@ -142,6 +143,7 @@ function isTexture(value) {
  * @returns Provenance for each baked texture, sorted by name/slot.
  */
 export async function bakeSceneTextures(root, warnings) {
+    const atlas = collectAtlasProvenance(root);
     // Collect first, encode second: traversal is sync, encoding is not, and doing
     // them together would interleave awaits with a mutating walk.
     const pending = new Map();
@@ -154,7 +156,7 @@ export async function bakeSceneTextures(root, warnings) {
                 const texture = bag[slot];
                 if (!isTexture(texture))
                     continue;
-                if (texture.userData['encoded'])
+                if (texture.userData['encoded'] && !atlas.texture(texture))
                     continue;
                 const existing = pending.get(texture) ?? { texture, bindings: [] };
                 existing.bindings.push({
@@ -170,16 +172,66 @@ export async function bakeSceneTextures(root, warnings) {
     const baked = [];
     for (const entry of pending.values()) {
         const name = entry.texture.name || '(unnamed texture)';
-        const raw = readPixels(entry.texture);
+        const atlasRef = atlas.texture(entry.texture);
+        const atlasRecord = atlasRef && atlas.table.atlases.find((a) => a.id === atlasRef.id);
+        const encoded = atlasRef ? readAtlasEncodedTexture(entry.texture) : undefined;
+        if (encoded &&
+            (encoded.mime !== 'image/png' ||
+                !(encoded.bytes instanceof Uint8Array) ||
+                encoded.bytes.length > 16_777_216))
+            throw new TypeError('Atlas baked encoding must be bounded PNG bytes.');
+        const raw = encoded && atlasRecord
+            ? {
+                width: atlasRecord.spec.width,
+                height: atlasRecord.spec.height,
+                channels: 4,
+                data: new Uint8Array(0),
+            }
+            : readPixels(entry.texture);
         const firstBinding = entry.bindings[0];
         const bindingSummary = `material ${JSON.stringify(firstBinding.material)} (${firstBinding.slot})${entry.bindings.length > 1 ? ` and ${entry.bindings.length - 1} other binding(s)` : ''}`;
         if (typeof raw === 'string') {
+            if (atlasRef)
+                throw new TypeError(`Atlas has stale compiled provenance: ${raw}; rebuild with textureAtlas() or remove atlas metadata for a manual texture.`);
             warnings.push(`Texture ${JSON.stringify(name)} on ${bindingSummary} was dropped from the GLB: ${raw}.`);
             continue;
         }
+        if (atlasRecord) {
+            const stale = () => new TypeError('Atlas has stale compiled provenance: rebuild with textureAtlas() after editing pixels, or remove atlas metadata for a manual texture.');
+            if (encoded) {
+                const delivery = readValidatedAtlasDelivery(entry.texture);
+                if (delivery) {
+                    if (delivery.id !== atlasRef.id ||
+                        delivery.finalMime !== encoded.mime ||
+                        delivery.finalImageSha256 !==
+                            `sha256:${createHash('sha256').update(encoded.bytes).digest('hex')}`)
+                        throw stale();
+                }
+                else {
+                    const sharp = (await import('sharp')).default;
+                    const image = sharp(encoded.bytes, {
+                        limitInputPixels: atlasRecord.spec.width * atlasRecord.spec.height,
+                    });
+                    const metadata = await image.metadata();
+                    if (metadata.width !== atlasRecord.spec.width ||
+                        metadata.height !== atlasRecord.spec.height)
+                        throw stale();
+                    const decoded = await image.ensureAlpha().raw().toBuffer();
+                    if (`sha256:${createHash('sha256').update(decoded).digest('hex')}` !==
+                        atlasRecord.manifest.decodedPixelHash)
+                        throw stale();
+                }
+            }
+            else if (raw.width !== atlasRecord.spec.width ||
+                raw.height !== atlasRecord.spec.height ||
+                raw.channels !== 4 ||
+                `sha256:${createHash('sha256').update(raw.data).digest('hex')}` !==
+                    atlasRecord.manifest.decodedPixelHash)
+                throw stale();
+        }
         let bytes;
         try {
-            bytes = await encodePngFromRaw(raw);
+            bytes = encoded?.bytes ?? (await encodePngFromRaw(raw));
         }
         catch (err) {
             warnings.push(`Texture ${JSON.stringify(name)} on ${bindingSummary} was dropped from the GLB: PNG encoding failed (${err instanceof Error ? err.message : String(err)}).`);
@@ -197,18 +249,20 @@ export async function bakeSceneTextures(root, warnings) {
         // Prefer the authored portable usage over incidental slot order. A packed
         // metallic-roughness map occupies both Three.js slots, where choosing the
         // first (`roughnessMap`) loses the authored combined-channel meaning.
-        const primaryUsage = recipe?.usage ??
+        const primaryUsage = atlasRecord?.spec.usage ??
+            recipe?.usage ??
             (entry.bindings.some(({ slot }) => slot === 'roughnessMap') &&
                 entry.bindings.some(({ slot }) => slot === 'metalnessMap')
                 ? 'metallicRoughness'
                 : (entry.bindings[0]?.usage ?? 'albedo'));
-        entry.texture.userData['kilnTexture'] = {
-            usage: primaryUsage,
-            colorSpace,
-            width: raw.width,
-            height: raw.height,
-            hasAlpha: hasTranslucentPixel(raw),
-        };
+        if (!encoded)
+            entry.texture.userData['kilnTexture'] = {
+                usage: primaryUsage,
+                colorSpace,
+                width: raw.width,
+                height: raw.height,
+                hasAlpha: hasTranslucentPixel(raw),
+            };
         const sha1 = createHash('sha1').update(bytes).digest('hex');
         const imageSha256 = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
         baked.push({
@@ -228,6 +282,7 @@ export async function bakeSceneTextures(root, warnings) {
             imageSha256,
             sha1,
             ...(recipe ? { procedural: recipe } : {}),
+            ...(atlasRef ? { atlas: atlasRef } : {}),
         });
     }
     return baked.sort((a, b) => `${a.node}:${a.material}:${a.texture}:${a.slot}`.localeCompare(`${b.node}:${b.material}:${b.texture}:${b.slot}`));