@instruktlabs/kiln 1.2.1 → 1.2.3

package/lib/material-library.js

@@ -1,6 +1,10 @@
 /** Portable material-library records. Source URLs are provenance, never loading instructions. */
 import { z } from 'zod';
 import { canonicalizeProceduralTextureSpecV2, } from "./procedural-material-v2.js";
+import { canonicalizeProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, } from "./procedural-texture-v3-contract.js";
+import { canonicalizePortableSamplerV1 } from "./portable-sampler.js";
+import { canonicalizeTextureAtlasSpecV1, validateTextureAtlasManifestV1, TEXTURE_ATLAS_COMPILER_ID, } from "./texture-atlas-contract.js";
+import { makeMaterialAuthoringSchemas } from "./material-authoring-schema.js";
 export const MATERIAL_LIBRARY_LIMITS = Object.freeze({
     maxMapBytes: 8 * 1024 * 1024,
     maxRecordBytes: 32 * 1024 * 1024,
@@ -411,6 +415,23 @@ export function materialLibraryResourceId(manifest, slot) {
     return `kiln.library.${manifest.revisionId.slice(7)}.${slotNames[slot]}`;
 }
 export function materialLibraryPortableSpec(manifest) {
+    if (manifest.schemaVersion === 2) {
+        const modern = validateMaterialManifestAny(manifest);
+        return {
+            schemaVersion: 3,
+            model: 'pbrMetallicRoughness',
+            name: modern.name,
+            ...modern.parameters,
+            textures: Object.fromEntries(modern.maps.map((map) => [
+                map.slot,
+                {
+                    kind: 'resource',
+                    resourceId: materialLibraryResourceId(modern, map.slot),
+                    sampler: { ...map.sampler },
+                },
+            ])),
+        };
+    }
     manifest = validateMaterialManifest(manifest);
     return {
         schemaVersion: 2,
@@ -423,3 +444,254 @@ export function materialLibraryPortableSpec(manifest) {
         ])),
     };
 }
+/** New versions are explicit; every exported V1 schema/type above stays V1. */
+const authoringSchemas = makeMaterialAuthoringSchemas(materialProceduralSpecSchema);
+const samplerSchema = authoringSchemas.portableSamplerSchema.refine((value) => {
+    try {
+        return (canonicalMaterialJson(value) === canonicalMaterialJson(canonicalizePortableSamplerV1(value)));
+    }
+    catch {
+        return false;
+    }
+});
+const v3SpecSchema = authoringSchemas.canonicalProceduralTextureSpecV3Schema.refine((value) => {
+    try {
+        return (canonicalMaterialJson(value) ===
+            canonicalMaterialJson(canonicalizeProceduralTextureSpecV3(value)));
+    }
+    catch {
+        return false;
+    }
+});
+const atlasSpecSchema = authoringSchemas.canonicalTextureAtlasSpecV1Schema.refine((value) => {
+    try {
+        return (canonicalMaterialJson(value) ===
+            canonicalMaterialJson(canonicalizeTextureAtlasSpecV1(value)));
+    }
+    catch {
+        return false;
+    }
+});
+const atlasManifestSchema = authoringSchemas.textureAtlasManifestV1Schema;
+export const materialMapPinSchema = z
+    .object({
+    resourceId: materialLibraryIdSchema,
+    revisionId: materialLibraryHashSchema,
+    sha256: materialLibraryHashSchema,
+})
+    .strict()
+    .refine((pin) => pin.sha256 === pin.revisionId, 'Material pin hash must match revision');
+const materialRecipeV2Schema = z.discriminatedUnion('kind', [
+    z
+        .object({
+        kind: z.literal('procedural'),
+        compilerId: z.enum(['kiln.procedural-texture.v2', PROCEDURAL_TEXTURE_V3_COMPILER_ID]),
+        spec: z.union([materialProceduralSpecSchema, v3SpecSchema]),
+        recipeHash: materialLibraryHashSchema,
+        pixelHash: materialLibraryHashSchema,
+        encoder: z.object({ name: z.literal('sharp'), version: text }).strict(),
+        derive: materialNormalDerivationSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal('atlas'),
+        compilerId: z.literal(TEXTURE_ATLAS_COMPILER_ID),
+        spec: atlasSpecSchema,
+        manifest: atlasManifestSchema,
+        encoder: z.object({ name: z.literal('sharp'), version: text }).strict(),
+    })
+        .strict()
+        .superRefine((recipe, context) => {
+        try {
+            validateTextureAtlasManifestV1(recipe.manifest, recipe.spec);
+        }
+        catch {
+            context.addIssue({ code: 'custom', message: 'Invalid stored atlas manifest' });
+        }
+    }),
+]);
+export const materialManifestV2Schema = materialManifestSchema
+    .omit({ schemaVersion: true, maps: true })
+    .extend({
+    schemaVersion: z.literal(2),
+    dependencies: z.array(materialMapPinSchema).max(16),
+    maps: z
+        .array(materialManifestSchema.shape.maps.element
+        .omit({ procedural: true })
+        .extend({
+        sampler: samplerSchema,
+        pixelHash: materialLibraryHashSchema,
+        recipe: materialRecipeV2Schema.optional(),
+    })
+        .strict())
+        .min(1)
+        .max(5),
+})
+    .strict();
+export const materialManifestAnySchema = z.discriminatedUnion('schemaVersion', [
+    materialManifestSchema,
+    materialManifestV2Schema,
+]);
+export const materialLibraryPayloadV2Schema = materialLibraryPayloadSchema
+    .extend({
+    schemaVersion: z.literal(2),
+    records: z
+        .array(materialLibraryPayloadSchema.shape.records.element
+        .extend({ manifest: materialManifestAnySchema })
+        .strict())
+        .max(MATERIAL_LIBRARY_LIMITS.maxPayloadRecords),
+})
+    .strict();
+export const materialLibraryPayloadAnySchema = z.discriminatedUnion('schemaVersion', [
+    materialLibraryPayloadSchema,
+    materialLibraryPayloadV2Schema,
+]);
+export function materialRecordDependencyPins(manifest) {
+    return manifest.schemaVersion === 1 ? [] : manifest.dependencies.map((pin) => ({ ...pin }));
+}
+/** Opt-in JSON-only standalone creation; external bytes remain host-only. */
+export const proceduralMaterialDraftV2Schema = proceduralMaterialDraftSchema
+    .extend({
+    schemaVersion: z.literal(2),
+    maps: z
+        .array(proceduralMaterialDraftSchema.shape.maps.element
+        .omit({ procedural: true })
+        .extend({
+        sampler: samplerSchema,
+        procedural: z
+            .union([
+            materialProceduralSpecSchema,
+            authoringSchemas.proceduralTextureSpecV3Schema.refine((value) => {
+                try {
+                    canonicalizeProceduralTextureSpecV3(value);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }),
+        ])
+            .optional(),
+        atlas: authoringSchemas.textureAtlasSpecV1Schema
+            .refine((value) => {
+            try {
+                canonicalizeTextureAtlasSpecV1(value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        })
+            .optional(),
+    })
+        .strict()
+        .refine((map) => (map.procedural !== undefined) !== (map.atlas !== undefined), 'Supply exactly one procedural or atlas recipe'))
+        .min(1)
+        .max(5),
+})
+    .strict();
+export const proceduralMaterialDraftAnySchema = z.union([
+    proceduralMaterialDraftSchema,
+    proceduralMaterialDraftV2Schema,
+]);
+export function validateMaterialManifestAny(value) {
+    assertMaterialJson(value);
+    if (new TextEncoder().encode(JSON.stringify(value)).length >
+        MATERIAL_LIBRARY_LIMITS.maxManifestBytes)
+        throw Error('Material manifest exceeds size limit');
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw Error('Invalid material manifest');
+    if (value['schemaVersion'] === 1)
+        return validateMaterialManifest(value);
+    const manifest = materialManifestV2Schema.parse(value);
+    if (new Set(manifest.sources.map((s) => s.id)).size !== manifest.sources.length ||
+        new Set(manifest.maps.map((m) => m.slot)).size !== manifest.maps.length)
+        throw Error('Duplicate material source or slot');
+    let bytes = 0, pixels = 0;
+    const pins = new Map();
+    for (const map of manifest.maps) {
+        const source = manifest.sources.find((s) => s.id === map.sourceId);
+        if (!source ||
+            map.file !== `${map.slot}.png` ||
+            map.usage !== MATERIAL_LIBRARY_USAGE[map.slot] ||
+            map.colorSpace !==
+                (map.slot === 'baseColor' || map.slot === 'emissive' ? 'srgb' : 'linear') ||
+            (map.slot === 'normal') !== (map.normalConvention === 'opengl') ||
+            (map.slot === 'metallicRoughness') !==
+                (map.channelPacking === 'r-occlusion-g-roughness-b-metallic'))
+            throw Error('Material map source/usage/convention mismatch');
+        const recipe = map.recipe;
+        if (recipe) {
+            if (source.kind !== 'procedural' || map.originalFile)
+                throw Error('Procedural/atlas map source convention mismatch');
+            if (recipe.kind === 'procedural') {
+                const spec = recipe.spec;
+                if (spec.schemaVersion === 3) {
+                    if (recipe.compilerId !== PROCEDURAL_TEXTURE_V3_COMPILER_ID ||
+                        recipe.derive ||
+                        spec.width !== map.width ||
+                        spec.height !== map.height)
+                        throw Error('V3 compiler/dimensions/derivation mismatch');
+                }
+                else if (recipe.compilerId !== 'kiln.procedural-texture.v2' ||
+                    spec.size !== map.width ||
+                    map.width !== map.height ||
+                    canonicalMaterialJson(spec) !==
+                        canonicalMaterialJson(canonicalizeProceduralTextureSpecV2(spec)))
+                    throw Error('V2 compiler/canonical recipe dimensions mismatch');
+                if (spec.usage !== map.usage ||
+                    recipe.pixelHash !== map.pixelHash ||
+                    (recipe.derive && map.slot !== 'normal'))
+                    throw Error('Procedural recipe pixel/usage mismatch');
+            }
+            else {
+                validateTextureAtlasManifestV1(recipe.manifest, recipe.spec);
+                if (recipe.spec.width !== map.width ||
+                    recipe.spec.height !== map.height ||
+                    recipe.spec.usage !== map.usage ||
+                    canonicalMaterialJson(recipe.spec.sampler) !== canonicalMaterialJson(map.sampler) ||
+                    recipe.manifest.decodedPixelHash !== map.pixelHash)
+                    throw Error('Atlas recipe map mismatch');
+                for (const region of recipe.spec.regions)
+                    if (region.source.kind === 'resource') {
+                        const pin = region.source.pin;
+                        pins.set(`${pin.resourceId}/${pin.revisionId}`, pin);
+                    }
+            }
+        }
+        else if (source.kind !== 'external' ||
+            !source.originalFiles.some((f) => f.name === map.originalFile))
+            throw Error('External material source original file missing');
+        bytes += map.bytes;
+        pixels += map.width * map.height;
+    }
+    const actual = manifest.dependencies.map((p) => `${p.resourceId}/${p.revisionId}`);
+    if (new Set(actual).size !== actual.length ||
+        actual.length !== pins.size ||
+        actual.some((k) => !pins.has(k)))
+        throw Error('Material dependency pin inventory mismatch');
+    if (bytes > MATERIAL_LIBRARY_LIMITS.maxRecordBytes ||
+        pixels > MATERIAL_LIBRARY_LIMITS.maxRecordPixels)
+        throw Error('Material record exceeds byte/pixel budget');
+    return structuredClone(manifest);
+}
+export function validateMaterialRecordShapeAny(record) {
+    assertMaterialJson(record, true);
+    if (record.manifest.schemaVersion === 1)
+        return validateMaterialRecordShape(record);
+    if (Object.keys(record).some((k) => k !== 'manifest' && k !== 'files'))
+        throw Error('Invalid material record');
+    const manifest = validateMaterialManifestAny(record.manifest);
+    if (!record.files || Object.keys(record.files).length !== manifest.maps.length)
+        throw Error('Material file inventory mismatch');
+    for (const map of manifest.maps) {
+        const bytes = record.files[map.file];
+        if (!(bytes instanceof Uint8Array) || bytes.length !== map.bytes)
+            throw Error('Material file inventory mismatch');
+        const size = materialPngDimensions(bytes);
+        if (size.width !== map.width || size.height !== map.height)
+            throw Error('Material PNG dimensions mismatch');
+    }
+    return manifest;
+}

package/lib/mcp-core.d.ts

@@ -23,7 +23,7 @@ import { type ServeStdioOptions, type StdioServerHandle } from '@modelcontextpro
 import type { AssetLink } from "./assets-resources.js";
 /** Server identity reported in the handshake and stamped into every 2026-07-28 result. */
 export declare const MCP_SERVER_NAME = "kiln";
-export declare const MCP_SERVER_VERSION = "1.2.1";
+export declare const MCP_SERVER_VERSION = "1.2.3";
 /**
  * The spec's optional `instructions` field, returned by `initialize` and
  * `server/discover`.

package/lib/pinned-material-map.d.ts

@@ -0,0 +1,33 @@
+/** Host-only atlas map capability. Authored code receives neither this port nor bytes. */
+import type { TextureUsage } from "./texture-contract.js";
+export type MaterialMapSlotV1 = 'baseColor' | 'normal' | 'metallicRoughness' | 'emissive' | 'occlusion';
+export type MaterialHashV1 = `sha256:${string}`;
+export interface MaterialMapPinV1 {
+    resourceId: string;
+    revisionId: string;
+    sha256: string;
+}
+export interface VerifiedPinnedMaterialMapDescriptorV1 {
+    materialId: string;
+    revisionId: MaterialHashV1;
+    resourceId: string;
+    slot: MaterialMapSlotV1;
+    usage: TextureUsage;
+    colorSpace: 'srgb' | 'linear';
+    width: number;
+    height: number;
+    encodedByteLength: number;
+    imageSha256: MaterialHashV1;
+    decodedPixelHash?: MaterialHashV1;
+}
+export interface OwnedMaterialMapPixelsV1 {
+    descriptor: VerifiedPinnedMaterialMapDescriptorV1;
+    pixels: Uint8Array;
+    decodedPixelHash: MaterialHashV1;
+}
+export interface PinnedMaterialMapPortV1 {
+    describePinnedMaterialMap(mapResourceId: unknown, pin: MaterialMapPinV1): VerifiedPinnedMaterialMapDescriptorV1 | undefined;
+    resolvePinnedMaterialMapPixels(mapResourceId: unknown, pin: MaterialMapPinV1, context?: {
+        signal?: AbortSignal;
+    }): Promise<OwnedMaterialMapPixelsV1>;
+}

package/lib/pinned-material-map.js

@@ -0,0 +1 @@
+export {};

package/lib/portable-material-runtime.d.ts

@@ -12,3 +12,8 @@ import { type TextureResolver } from "./texture-resolver.js";
 export declare function compilePortableMaterialSpecV2(input: unknown, options?: {
     resolver?: TextureResolver;
 }): Promise<THREE.MeshStandardMaterial>;
+/** New V3 path owns every mutable texture/source/pixel/encoded-byte binding. */
+export declare function compilePortableMaterialSpecV3(input: unknown, options?: {
+    resolver?: TextureResolver;
+    signal?: AbortSignal;
+}): Promise<THREE.MeshStandardMaterial>;

package/lib/portable-material-runtime.js

@@ -3,6 +3,9 @@ import { DEFAULT_TEXTURE_RESOLVER } from "./texture-resolver.js";
 import { ProceduralTextureError, canonicalizePortableMaterialSpecV2, } from "./procedural-material-v2.js";
 import { proceduralTexture } from "./procedural-texture.js";
 import { pbrMaterial } from "./textures.js";
+import { loadTexture } from "./textures.js";
+import { admitPortableMaterialSpecV3, PORTABLE_MATERIAL_V3_LIMITS, PORTABLE_MATERIAL_SLOT_USAGE, PortableMaterialV3Error, } from "./procedural-material-v3.js";
+import { applyPortableSamplerV1 } from "./portable-sampler-runtime.js";
 const SLOT_USAGE = {
     baseColor: 'albedo',
     normal: 'normal',
@@ -79,3 +82,160 @@ export async function compilePortableMaterialSpecV2(input, options = {}) {
         spec;
     return material;
 }
+/** New V3 path owns every mutable texture/source/pixel/encoded-byte binding. */
+export async function compilePortableMaterialSpecV3(input, options = {}) {
+    const owned = new Map();
+    try {
+        const admission = admitPortableMaterialSpecV3(input), spec = admission.spec;
+        const resolver = options.resolver ?? DEFAULT_TEXTURE_RESOLVER;
+        const entries = Object.entries(spec.textures);
+        // All slots are checked before even bounded encoded-byte preparation.
+        for (const [slot, ref] of entries)
+            if (ref.kind === 'resource') {
+                const descriptor = resolver.describeApprovedTexture?.(ref.resourceId);
+                if (!descriptor?.allowedSlots.includes(slot) ||
+                    descriptor.usage !== PORTABLE_MATERIAL_SLOT_USAGE[slot])
+                    throw new ProceduralTextureError(`${slot} requires an injected resource approved for its exact slot and usage.`);
+                if (!resolver.preparePortableTexture)
+                    throw new ProceduralTextureError('V3 needs a verified-byte preparation resolver; keep V2 for a legacy resolver.');
+            }
+        const prepared = new Map();
+        let encoded = 0, texels = admission.texels, resourcePixels = 0;
+        for (const [slot, ref] of entries)
+            if (ref.kind === 'resource') {
+                options.signal?.throwIfAborted();
+                const raw = await resolver.preparePortableTexture(ref.resourceId, {
+                    signal: options.signal,
+                });
+                const d = structuredClone(raw.descriptor);
+                if (!(raw.bytes instanceof Uint8Array) ||
+                    raw.bytes.length < 24 ||
+                    raw.bytes.length > 8 * 1024 * 1024 ||
+                    d.encodedByteLength !== raw.bytes.length ||
+                    d.resourceId !== ref.resourceId ||
+                    d.usage !== PORTABLE_MATERIAL_SLOT_USAGE[slot] ||
+                    !d.allowedSlots.includes(slot) ||
+                    d.colorSpace !== (slot === 'baseColor' || slot === 'emissive' ? 'srgb' : 'linear') ||
+                    !Number.isInteger(d.width) ||
+                    !Number.isInteger(d.height) ||
+                    d.width < 1 ||
+                    d.height < 1 ||
+                    d.width > 4096 ||
+                    d.height > 4096 ||
+                    !/^sha256:[a-f0-9]{64}$/.test(d.imageSha256))
+                    throw new ProceduralTextureError('Prepared texture descriptor/bytes are invalid.');
+                const pixels = d.width * d.height;
+                texels += pixels;
+                resourcePixels += pixels;
+                encoded += raw.bytes.length;
+                // Decoded RGBA write/copy plus encoded snapshot/hash/decode passes are
+                // charged beside the sole procedural admission owner's work estimate.
+                const resourceWork = resourcePixels * 12 + encoded * 8;
+                if (admission.estimatedWorkUnits + resourceWork > PORTABLE_MATERIAL_V3_LIMITS.maxWork)
+                    throw new ProceduralTextureError('Aggregate material work budget exceeded before compilation or decoding.');
+                if (texels > PORTABLE_MATERIAL_V3_LIMITS.maxTexels ||
+                    encoded > PORTABLE_MATERIAL_V3_LIMITS.maxEncodedBytes)
+                    throw new ProceduralTextureError('Aggregate resource texel/encoded-byte budget exceeded before decoding.');
+                const snapshot = {
+                    descriptor: structuredClone(d),
+                    bytes: raw.bytes.slice(),
+                    userData: structuredClone(raw.userData),
+                };
+                const header = new DataView(snapshot.bytes.buffer, snapshot.bytes.byteOffset, snapshot.bytes.byteLength);
+                if (![137, 80, 78, 71, 13, 10, 26, 10].every((n, i) => snapshot.bytes[i] === n) ||
+                    String.fromCharCode(...snapshot.bytes.subarray(12, 16)) !== 'IHDR' ||
+                    header.getUint32(16) !== d.width ||
+                    header.getUint32(20) !== d.height)
+                    throw new ProceduralTextureError('Prepared texture PNG/header dimensions mismatch.');
+                const hash = new Uint8Array(await crypto.subtle.digest('SHA-256', snapshot.bytes));
+                if (`sha256:${Array.from(hash, (x) => x.toString(16).padStart(2, '0')).join('')}` !==
+                    d.imageSha256)
+                    throw new ProceduralTextureError('Prepared texture encoded hash mismatch.');
+                prepared.set(slot, snapshot);
+            }
+        // Includes held outputs, decoder/copy allowances, encoded snapshots and generated mips.
+        const transient = admission.conservativePixelAllocationBytes +
+            resourcePixels * 12 +
+            encoded * 3 +
+            Math.ceil((texels * 4) / 3);
+        if (transient > PORTABLE_MATERIAL_V3_LIMITS.maxTransientBytes)
+            throw new ProceduralTextureError('Aggregate material allocation budget exceeded before decoding.');
+        for (const [slot, ref] of entries) {
+            options.signal?.throwIfAborted();
+            let texture;
+            if (ref.kind === 'procedural')
+                texture = proceduralTexture(ref.spec);
+            else {
+                const source = prepared.get(slot);
+                texture = await loadTexture(source.bytes.slice(), {
+                    usage: source.descriptor.usage,
+                    name: ref.resourceId,
+                });
+                owned.set(slot, texture);
+                if (texture.image.width !== source.descriptor.width ||
+                    texture.image.height !== source.descriptor.height ||
+                    !texture.image.data ||
+                    texture.image.data.length !== source.descriptor.width * source.descriptor.height * 4)
+                    throw new ProceduralTextureError('Prepared texture decoded dimensions mismatch.');
+                const actual = texture.userData['kilnTexture'];
+                texture.userData = { ...structuredClone(source.userData), ...texture.userData };
+                texture.userData['kilnTexture'] = {
+                    ...source.userData['kilnTexture'],
+                    ...actual,
+                };
+            }
+            owned.set(slot, texture);
+            texture.flipY = false;
+            texture.premultiplyAlpha = false;
+            applyPortableSamplerV1(texture, ref.sampler);
+            texture.userData['kilnPortableBinding'] = {
+                schemaVersion: 3,
+                slot,
+                sampler: { ...ref.sampler },
+            };
+        }
+        options.signal?.throwIfAborted();
+        const material = pbrMaterial({
+            roughness: spec.roughness,
+            metalness: spec.metalness,
+            emissiveIntensity: spec.emissiveIntensity,
+            alphaMode: spec.alphaMode,
+            ...(spec.alphaMode === 'mask' ? { alphaCutoff: spec.alphaCutoff } : {}),
+            doubleSided: spec.doubleSided,
+            ...(owned.has('baseColor')
+                ? { albedo: owned.get('baseColor') }
+                : spec.baseColor !== undefined
+                    ? { albedo: spec.baseColor }
+                    : {}),
+            ...(owned.has('normal') ? { normal: owned.get('normal') } : {}),
+            ...(owned.has('metallicRoughness')
+                ? { metallicRoughness: owned.get('metallicRoughness') }
+                : {}),
+            ...(owned.has('emissive')
+                ? { emissive: owned.get('emissive') }
+                : spec.emissive !== undefined
+                    ? { emissive: spec.emissive }
+                    : {}),
+            ...(owned.has('occlusion') ? { aoMap: owned.get('occlusion') } : {}),
+        });
+        if (spec.name)
+            material.name = spec.name;
+        if (owned.has('baseColor') && spec.baseColor !== undefined)
+            material.color.setHex(spec.baseColor);
+        if (owned.has('emissive') && spec.emissive !== undefined)
+            material.emissive.setHex(spec.emissive);
+        material.userData['kilnPortableMaterial'] = spec;
+        return material;
+    }
+    catch (error) {
+        for (const texture of owned.values())
+            texture.dispose();
+        if (error instanceof PortableMaterialV3Error)
+            throw error;
+        const wrapped = new PortableMaterialV3Error(error instanceof ProceduralTextureError
+            ? error.message
+            : 'Texture preparation or compilation failed; verify injected bytes, metadata and cancellation state.');
+        wrapped.cause = error;
+        throw wrapped;
+    }
+}

package/lib/portable-sampler-runtime.d.ts

@@ -0,0 +1,4 @@
+/** Apply only after the caller has established independent texture ownership. */
+import { type Texture } from 'three';
+import { type CanonicalPortableSamplerV1 } from "./portable-sampler.js";
+export declare function applyPortableSamplerV1<T extends Texture>(ownedTexture: T, sampler: CanonicalPortableSamplerV1): T;

package/lib/portable-sampler-runtime.js

@@ -0,0 +1,26 @@
+/** Apply only after the caller has established independent texture ownership. */
+import { ClampToEdgeWrapping, LinearFilter, LinearMipmapLinearFilter, LinearMipmapNearestFilter, MirroredRepeatWrapping, NearestFilter, NearestMipmapLinearFilter, NearestMipmapNearestFilter, RepeatWrapping, } from 'three';
+import { canonicalizePortableSamplerV1 } from "./portable-sampler.js";
+const min = {
+    nearest: NearestFilter,
+    linear: LinearFilter,
+    'nearest-mipmap-nearest': NearestMipmapNearestFilter,
+    'linear-mipmap-nearest': LinearMipmapNearestFilter,
+    'nearest-mipmap-linear': NearestMipmapLinearFilter,
+    'linear-mipmap-linear': LinearMipmapLinearFilter,
+};
+const wrap = {
+    repeat: RepeatWrapping,
+    'clamp-to-edge': ClampToEdgeWrapping,
+    'mirrored-repeat': MirroredRepeatWrapping,
+};
+export function applyPortableSamplerV1(ownedTexture, sampler) {
+    const value = canonicalizePortableSamplerV1(sampler);
+    ownedTexture.minFilter = min[value.minFilter];
+    ownedTexture.magFilter = value.magFilter === 'nearest' ? NearestFilter : LinearFilter;
+    ownedTexture.wrapS = wrap[value.wrapS];
+    ownedTexture.wrapT = wrap[value.wrapT];
+    ownedTexture.generateMipmaps = value.minFilter.includes('mipmap');
+    ownedTexture.needsUpdate = true;
+    return ownedTexture;
+}

package/lib/portable-sampler.d.ts

@@ -0,0 +1,11 @@
+export declare const PORTABLE_MIN_FILTERS_V1: readonly ['nearest', 'linear', 'nearest-mipmap-nearest', 'linear-mipmap-nearest', 'nearest-mipmap-linear', 'linear-mipmap-linear'];
+export declare const PORTABLE_MAG_FILTERS_V1: readonly ['nearest', 'linear'];
+export declare const PORTABLE_WRAPS_V1: readonly ['repeat', 'clamp-to-edge', 'mirrored-repeat'];
+export interface PortableSamplerV1 {
+    minFilter: (typeof PORTABLE_MIN_FILTERS_V1)[number];
+    magFilter: (typeof PORTABLE_MAG_FILTERS_V1)[number];
+    wrapS: (typeof PORTABLE_WRAPS_V1)[number];
+    wrapT: (typeof PORTABLE_WRAPS_V1)[number];
+}
+export type CanonicalPortableSamplerV1 = PortableSamplerV1;
+export declare function canonicalizePortableSamplerV1(input: unknown): CanonicalPortableSamplerV1;

package/lib/portable-sampler.js

@@ -0,0 +1,42 @@
+/** Shared portable sampler contract; no renderer, loader or native dependencies. */
+import { ProceduralTextureError } from "./procedural-material-v2.js";
+export const PORTABLE_MIN_FILTERS_V1 = [
+    'nearest',
+    'linear',
+    'nearest-mipmap-nearest',
+    'linear-mipmap-nearest',
+    'nearest-mipmap-linear',
+    'linear-mipmap-linear',
+];
+export const PORTABLE_MAG_FILTERS_V1 = ['nearest', 'linear'];
+export const PORTABLE_WRAPS_V1 = ['repeat', 'clamp-to-edge', 'mirrored-repeat'];
+export function canonicalizePortableSamplerV1(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new ProceduralTextureError('portableSampler requires a complete JSON object.');
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new ProceduralTextureError('portableSampler must be plain JSON data.');
+    for (const key of Reflect.ownKeys(input)) {
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor))
+            throw new ProceduralTextureError('portableSampler requires enumerable JSON data fields, never accessors.');
+    }
+    const value = input;
+    const allowed = {
+        minFilter: PORTABLE_MIN_FILTERS_V1,
+        magFilter: PORTABLE_MAG_FILTERS_V1,
+        wrapS: PORTABLE_WRAPS_V1,
+        wrapT: PORTABLE_WRAPS_V1,
+    };
+    if (Object.keys(value).some((key) => !Object.hasOwn(allowed, key)))
+        throw new ProceduralTextureError('portableSampler contains an unsupported field.');
+    for (const [key, options] of Object.entries(allowed))
+        if (!options.includes(value[key]))
+            throw new ProceduralTextureError(`portableSampler.${key} requires one of ${options.join(', ')}.`);
+    return {
+        minFilter: value['minFilter'],
+        magFilter: value['magFilter'],
+        wrapS: value['wrapS'],
+        wrapT: value['wrapT'],
+    };
+}

package/lib/primitives.d.ts

@@ -25,15 +25,27 @@ export { projectUV } from "./uv-project.js";
 export type { ProjectUVOptions } from "./uv-project.js";
 export { remapUV } from "./uv-shapes.js";
 export type { RemapUVOptions } from "./uv-shapes.js";
+export { textureAtlas, remapUVToAtlas } from "./texture-atlas.js";
+export type { AtlasUVOptionsV1 } from "./texture-atlas.js";
+export { TextureAtlasError, TEXTURE_ATLAS_COMPILER_ID, TEXTURE_ATLAS_LIMITS, canonicalizeTextureAtlasSpecV1, canonicalTextureAtlasJsonV1, hashTextureAtlasSpecV1, } from "./texture-atlas-contract.js";
+export type { AtlasRectangleV1, AtlasEdgeModeV1, AtlasResourceExpectationV1, TextureAtlasSourceV1, TextureAtlasRegionV1, TextureAtlasSpecV1, CanonicalTextureAtlasSourceV1, CanonicalTextureAtlasRegionV1, CanonicalTextureAtlasSpecV1, } from "./texture-atlas-contract.js";
+export { compileTextureAtlasSpecV1 } from "./texture-atlas-pixels.js";
+export type { TextureAtlasCompileOptionsV1, TextureAtlasBudgetV1, TextureAtlasSourceManifestV1, TextureAtlasRegionManifestV1, TextureAtlasManifestV1, CompiledTextureAtlasV1, } from "./texture-atlas-pixels.js";
 export { createGableEndPanel, createGableRoof, createGableShell, createRoofSurfaceLayout, } from "./architecture.js";
 export type { GableEndPanelOptions, GableRoofOptions, GableShellOptions, RoofFaceFrame, RoofSurfaceLayoutOptions, } from "./architecture.js";
-export { createJointChain } from "./character.js";
-export type { CreateJointChainOptionsV1, JointChainResultV1, JointChainSegmentV1, } from "./character.js";
+export { createBoneChain, createJointChain, createSkinnedPart } from "./character.js";
+export type { BoneChainResultV1, CreateSkinnedPartOptions, CreateJointChainOptionsV1, JointChainResultV1, JointChainSegmentV1, } from "./character.js";
 export { createVehicleFrame, createWheelAssembly, createWheelGeometrySet, } from "./vehicle.js";
 export { materialRecipe } from "./material-recipe-runtime.js";
 export type { ApplyMaterialRecipeOptions } from "./material-recipe-runtime.js";
 export type { MaterialRecipeId, MaterialRecipeOverridesV1 } from "./material-recipes.js";
-export { compilePortableMaterialSpecV2 } from "./portable-material-runtime.js";
+export { compilePortableMaterialSpecV2, compilePortableMaterialSpecV3, } from "./portable-material-runtime.js";
+export { canonicalizePortableMaterialSpecV3, PortableMaterialV3Error, PORTABLE_MATERIAL_V3_LIMITS, } from "./procedural-material-v3.js";
+export type { PortableMaterialSpecV3, CanonicalPortableMaterialSpecV3, PortableTextureRefV3, CanonicalPortableTextureRefV3, } from "./procedural-material-v3.js";
+export { canonicalizePortableSamplerV1 } from "./portable-sampler.js";
+export type { PortableSamplerV1, CanonicalPortableSamplerV1 } from "./portable-sampler.js";
+export { compileProceduralTextureSpecV3, canonicalizeProceduralTextureSpecV3, canonicalProceduralTextureJsonV3, hashProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, PROCEDURAL_TEXTURE_SPEC_VERSION_V3, MAX_PROCEDURAL_V3_EDGE, MAX_PROCEDURAL_V3_TEXELS, MAX_PROCEDURAL_V3_OPERATIONS, MAX_PROCEDURAL_V3_VERTICES, MAX_PROCEDURAL_V3_STAMPS, MAX_PROCEDURAL_V3_PALETTE, MAX_PROCEDURAL_V3_WORK, MAX_PROCEDURAL_V3_TRANSIENT_BYTES, } from "./procedural-texture-v3.js";
+export type { CompiledProceduralTextureV3, RgbaV3, PixelPointV3, PixelRectangleV3, ProceduralShapeV3, ProceduralOperationV3, CanonicalProceduralOperationV3, ProceduralTextureSpecV3, CanonicalProceduralTextureSpecV3, } from "./procedural-texture-v3.js";
 export { MAX_PORTABLE_MATERIAL_TEXELS, MAX_PORTABLE_MATERIAL_TEXTURES, MAX_PROCEDURAL_LAYERS, MAX_PROCEDURAL_SIZE, PORTABLE_MATERIAL_SPEC_VERSION, PROCEDURAL_TEXTURE_SPEC_VERSION, ProceduralTextureError, canonicalProceduralTextureJsonV2, canonicalizePortableMaterialSpecV2, canonicalizeProceduralTextureSpecV2, compileProceduralTextureSpecV2, hashProceduralTextureSpecV2, migrateProceduralTextureSpecV1, } from "./procedural-texture.js";
 export type { CanonicalPortableMaterialSpecV2, CanonicalProceduralTextureSpecV2, PortableMaterialSpecV2, ProceduralLayer, ProceduralTextureSpec, ProceduralTextureSpecV1, ProceduralTextureSpecV2, } from "./procedural-texture.js";
 export type { VehicleFrameOptions, VehicleFrameResult, WheelAssemblyOptions, WheelAssemblyResult, WheelGeometrySet, WheelMaterialSet, } from "./vehicle.js";