@instruktlabs/kiln 1.2.1 → 1.2.3

package/docs/sdk.md

@@ -22,7 +22,7 @@ const result = await renderGLB(code);
 ```
 
 The complete authoring and host APIs remain available through documented subpaths.
-The original 55 export paths are retained; version 1.1 adds four
+The original 55 export paths are retained; version 1.1 added four
 host entrypoints below. The root exposes rendering, validation,
 Discovery and engine identity; it does not re-export every name from every module.
 CommonJS is not part of this release's contract.
@@ -53,7 +53,7 @@ entrypoint list. Files inside `lib/`, including declaration dependencies under
 
 ## Stability in 1.x
 
-The table classifies all 59 public entrypoints in version 1.1. The root and every listed subpath
+The table classifies all 59 public entrypoints. The root and every listed subpath
 except `implicit` are stable entrypoints for v1: their declared public signatures,
 record shapes and documented behavior receive normal semantic-versioning
 compatibility. Optional dependencies do not make the two agent APIs experimental.
@@ -80,6 +80,59 @@ and source/revision receipts for reproducible replay. Compatibility of the SDK
 does not imply identical generated GLB bytes or renderer output across releases.
 Persisted data and rebuild restrictions follow the [migration contract](migration.md).
 
+## Procedural RGBA surfaces
+
+The `primitives` entrypoint and authored `proceduralTexture` helper accept an
+explicit V3 recipe for bounded rectangular RGBA images, shape coverage, alpha
+masks, palettes, dithering and seeded stamps. Pure V3 compilation returns pixels,
+canonical JSON and a compiler-qualified recipe hash without creating a mesh.
+Read the [V3 contract](procedural-surfaces-v3.md) for the exact limits and rounding
+rules. V1/V2 remain supported with their existing pixels, hashes and sampler
+defaults. The same entrypoint exposes `textureAtlas` and `remapUVToAtlas` for
+named regions. Portable V3 materials add explicit per-map sampling; opt-in V2
+material records persist recipes, compiled maps and exact dependency pins.
+See the [standalone material and atlas workflow](procedural-surfaces-v3.md#standalone-saved-materials-and-atlases).
+
+## Explicit character skinning
+
+The `character` and `primitives` entrypoints expose opt-in `createBoneChain` and
+`createSkinnedPart`; both are also sandbox helpers. `createJointChain` continues
+to return ordinary rigid `Object3D` pivots. Bone chains use the same versioned
+joint descriptors, infer an attached declared parent role and reject ambiguous
+roles/names before attaching nodes. They do not choose anatomy or a body plan.
+
+`createSkinnedPart(name, geometry, material, { parent, bones, indices, weights })`
+clones unchanged geometry and binds it to the assembled hierarchy's current rest
+pose. Supply exactly four indices and weights per vertex, in the explicit bone
+array order. Indices must be valid even in zero-weight lanes. By default weights
+must be in 0..1 and sum to one within 1e-5; `normalizeWeights: true` explicitly
+normalizes positive finite sums. Zero sums are rejected. Optional local position,
+Euler rotation (degrees), scale and semantic metadata match `createPart`'s units.
+
+The helper owns geometry, influence arrays and inverse bind matrices; bones and
+materials remain shared. Limits are 1024 bones, 262144 vertices and 128 MiB of
+cloned attributes plus new influence storage. These are helper limits, not new
+restrictions on direct Three.js authoring. Existing skin attributes and singular
+bind transforms are rejected. Set up rest transforms before binding; later rest
+edits/reparenting need deliberate rebinding. Animated bounds remain a consumer
+responsibility. The selected Three exporter is required to preserve skins;
+calling these helpers does not change the legacy default or select a converter.
+
+`inspectSkinIntegrity(root)` from `@instruktlabs/kiln/qa` reads source bindings
+without updating matrices, normalizing weights or repairing the scene. It returns
+bounded findings, checked counts and current posed world bounds (including position
+morphs). It is not an animation envelope, deformation-quality score or proof of
+collision clearance. Rigid meshes do not acquire skin or body-plan requirements.
+
+Export runs this check before bounds, texture baking or conversion. Invalid source
+bindings produce an `AssetQaBlockedError` at the scene stage with mesh/joint or
+vertex-range context and repair advice. This is mandatory input integrity, like
+invalid geometry buffers; QA warning mode and derivative serialization do not
+bypass it. The partial failure report does not claim the remaining QA rules ran.
+The independent final glTF validation remains in place. Source Three skeletons
+need their inverse-bind arrays populated; this does not change glTF's valid
+identity-matrix default when the file omits `inverseBindMatrices`.
+
 ## Execution and dependencies
 
 The root SDK is Node-oriented. `/node` adapters use filesystem or server services;

package/docs/tools-operations.md

@@ -1123,7 +1123,7 @@ Create and retain one immutable material from a preset or procedural definition.
           "type": "object",
           "properties": {
             "draft": {
-              "description": "create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
+              "description": "create-procedural: legacy layered draft, or schemaVersion 2 with explicit samplers and RGBA/atlas recipes. Exact atlas sources must exist in this library. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
               "type": "object",
               "propertyNames": {
                 "type": "string"
@@ -1166,7 +1166,7 @@ Import complete normalized material records and embedded PNGs. Does not fetch UR
   "type": "object",
   "properties": {
     "payload": {
-      "description": "import: schemaVersion 1 and complete normalized records with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
+      "description": "import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
       "type": "object",
       "propertyNames": {
         "type": "string"

package/docs/tools.md

@@ -1328,7 +1328,7 @@ Manage optional shared workspace projects: list discovers IDs; get reads the cur
 
 ## kiln_material
 
-Manage optional immutable material resources in this workspace. presets discovers shipped architecture, wood, metal, fabric and ground recipes; create-preset bakes one with an explicit seed, creator and license; list returns compact material/revision summaries; get returns full provenance, hashes, map conventions, physical repeat scale and a code-ready portable material spec; create-procedural bakes bounded editable layer recipes including optional height-derived normals; import accepts complete normalized records with embedded PNG bytes. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before authored evaluation resolves the resources; no project is required.
+Manage optional immutable material resources in this workspace. presets lists shipped recipes; create-preset uses explicit seed, creator and license; list returns revision summaries; get returns provenance, hashes, sampling and a portable material spec. create-procedural accepts legacy layer drafts or schemaVersion 2 drafts with explicit samplers and bounded RGBA or named atlas recipes. Atlas resource sources require exact saved revisions; import requires complete normalized records and dependencies with embedded PNG bytes. Read shape:material-draft or shape:material-import through kiln_discover for full fields. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before evaluation; no project or mesh is required.
 
 <details>
 <summary>Input JSON Schema</summary>
@@ -1431,7 +1431,7 @@ Manage optional immutable material resources in this workspace. presets discover
       "pattern": "^sha256:[a-f0-9]{64}$"
     },
     "draft": {
-      "description": "create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
+      "description": "create-procedural: legacy layered draft, or schemaVersion 2 with explicit samplers and RGBA/atlas recipes. Exact atlas sources must exist in this library. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -1439,7 +1439,7 @@ Manage optional immutable material resources in this workspace. presets discover
       "additionalProperties": {}
     },
     "payload": {
-      "description": "import: schemaVersion 1 and complete normalized records with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
+      "description": "import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
       "type": "object",
       "propertyNames": {
         "type": "string"

package/lib/asset-materials-node.d.ts

@@ -1,5 +1,5 @@
 /** Exact saved material closure, shared by standalone asset and project delivery. */
 import type { AssetRecord } from "./assets.js";
-import { type MaterialLibrary, type MaterialManifestV1, type MaterialRecordV1 } from "./material-library.js";
-export declare function dependencyManifests(asset: AssetRecord): MaterialManifestV1[];
-export declare function resolveSavedAssetMaterials(asset: AssetRecord, library?: MaterialLibrary): Promise<MaterialRecordV1[]>;
+import { type MaterialLibrary, type MaterialManifest, type MaterialRecord } from "./material-library.js";
+export declare function dependencyManifests(asset: AssetRecord): MaterialManifest[];
+export declare function resolveSavedAssetMaterials(asset: AssetRecord, library?: MaterialLibrary): Promise<MaterialRecord[]>;

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>;