@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/primitives.js

@@ -12,7 +12,7 @@ import * as THREE from 'three';
 import { AuthoringDiagnosticError } from "./evaluator/authoring-diagnostic.js";
 import { assertDimension, assertPrimitiveSegments, assertPrimitiveGrid, assertFiniteTriple, GEOMETRY_ALLOCATION_LIMITS, } from "./geometry-budget.js";
 import { buildWallPanels } from "./wall-panels.js";
-import { createJointChain } from "./character.js";
+import { createBoneChain, createJointChain, createSkinnedPart } from "./character.js";
 import { describeAssembly, replicateAssembly } from "./assembly.js";
 import { defineLod } from "./lod.js";
 export { defineLod } from "./lod.js";
@@ -37,7 +37,8 @@ import * as profile from "./profile.js";
 import * as solids from "./solids.js";
 import * as proceduralTextures from "./procedural-texture.js";
 import * as textures from "./textures.js";
-import { compilePortableMaterialSpecV2 } from "./portable-material-runtime.js";
+import { textureAtlas, remapUVToAtlas } from "./texture-atlas.js";
+import { compilePortableMaterialSpecV2, compilePortableMaterialSpecV3, } from "./portable-material-runtime.js";
 import { createVehicleFrame, createWheelAssembly, createWheelGeometrySet } from "./vehicle.js";
 import { stampSemanticMetadataV1, } from "./contracts/index.js";
 import * as uv from "./uv.js";
@@ -45,11 +46,17 @@ import * as uvShapes from "./uv-shapes.js";
 import { projectUV } from "./uv-project.js";
 export { projectUV } from "./uv-project.js";
 export { remapUV } from "./uv-shapes.js";
+export { textureAtlas, remapUVToAtlas } from "./texture-atlas.js";
+export { TextureAtlasError, TEXTURE_ATLAS_COMPILER_ID, TEXTURE_ATLAS_LIMITS, canonicalizeTextureAtlasSpecV1, canonicalTextureAtlasJsonV1, hashTextureAtlasSpecV1, } from "./texture-atlas-contract.js";
+export { compileTextureAtlasSpecV1 } from "./texture-atlas-pixels.js";
 export { createGableEndPanel, createGableRoof, createGableShell, createRoofSurfaceLayout, } from "./architecture.js";
-export { createJointChain } from "./character.js";
+export { createBoneChain, createJointChain, createSkinnedPart } from "./character.js";
 export { createVehicleFrame, createWheelAssembly, createWheelGeometrySet, } from "./vehicle.js";
 export { materialRecipe } from "./material-recipe-runtime.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 { canonicalizePortableSamplerV1 } 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 { 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";
 function vectorToTuple(v) {
     return [v.x, v.y, v.z];
@@ -1429,6 +1436,8 @@ export function buildSandboxGlobals(usage, options = {}) {
         replicateAssembly: wrap('replicateAssembly', replicateAssembly),
         createPivot: wrap('createPivot', createPivot),
         createJointChain: wrap('createJointChain', createJointChain),
+        createBoneChain: wrap('createBoneChain', createBoneChain),
+        createSkinnedPart: wrap('createSkinnedPart', createSkinnedPart),
         createVehicleFrame: wrap('createVehicleFrame', createVehicleFrame),
         createWheelGeometrySet: wrap('createWheelGeometrySet', createWheelGeometrySet),
         createWheelAssembly: wrap('createWheelAssembly', createWheelAssembly),
@@ -1477,6 +1486,11 @@ export function buildSandboxGlobals(usage, options = {}) {
                 return Promise.reject(new TypeError('compilePortableMaterialSpecV2 accepts exactly one material spec'));
             return compilePortableMaterialSpecV2(args[0], { resolver: options.textureResolver });
         }),
+        compilePortableMaterialSpecV3: wrap('compilePortableMaterialSpecV3', (...args) => {
+            if (args.length !== 1)
+                return Promise.reject(new TypeError('compilePortableMaterialSpecV3 accepts exactly one material spec'));
+            return compilePortableMaterialSpecV3(args[0], { resolver: options.textureResolver });
+        }),
         basicMaterial: wrap('basicMaterial', basicMaterial),
         glassMaterial: wrap('glassMaterial', glassMaterial),
         lambertMaterial: wrap('lambertMaterial', lambertMaterial),
@@ -1529,6 +1543,7 @@ export function buildSandboxGlobals(usage, options = {}) {
         // Shape-aware unwraps (sync — preserve built-in directional UVs)
         projectUV: wrap('projectUV', projectUV),
         remapUV: wrap('remapUV', uvShapes.remapUV),
+        remapUVToAtlas: wrap('remapUVToAtlas', remapUVToAtlas),
         // Parametric primitives
         gearGeo: wrapGeo('gearGeo', gears.gearGeo),
         bladeGeo: wrapGeo('bladeGeo', gears.bladeGeo),
@@ -1537,6 +1552,11 @@ export function buildSandboxGlobals(usage, options = {}) {
         loadApprovedTexture: wrap('loadApprovedTexture', loadApprovedTexture),
         // Procedural textures (sync — no I/O, so no await)
         proceduralTexture: wrap('proceduralTexture', proceduralTextures.proceduralTexture),
+        textureAtlas: wrap('textureAtlas', (...args) => {
+            if (args.length !== 1)
+                return Promise.reject(new TypeError('textureAtlas accepts exactly one atlas spec'));
+            return textureAtlas(args[0], { resources: options.textureResolver?.pinnedMaterialMaps });
+        }),
         normalMapFromHeight: wrap('normalMapFromHeight', proceduralTextures.normalMapFromHeight),
         pbrMaterial: wrap('pbrMaterial', textures.pbrMaterial),
         foliageMaterial: wrap('foliageMaterial', textures.foliageMaterial),

package/lib/procedural-material-v2.d.ts

@@ -184,6 +184,8 @@ export declare class ProceduralTextureError extends AuthoringDiagnosticError {
 export declare function migrateProceduralTextureSpecV1(input: unknown): ProceduralTextureSpecV2;
 export declare function canonicalizeProceduralTextureSpecV2(input: unknown): CanonicalProceduralTextureSpecV2;
 export declare function canonicalProceduralTextureJsonV2(input: unknown): string;
+/** Browser-safe SHA-256 shared by versioned recipe contracts. */
+export declare function sha256Hex(text: string): string;
 export declare function hashProceduralTextureSpecV2(input: unknown): `sha256:${string}`;
 export declare function canonicalizePortableMaterialSpecV2(input: unknown): CanonicalPortableMaterialSpecV2;
 export {};

package/lib/procedural-material-v2.js

@@ -294,7 +294,8 @@ const SHA256_K = new Uint32Array([
     0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
 ]);
 const rotateRight = (value, bits) => (value >>> bits) | (value << (32 - bits));
-function sha256Hex(text) {
+/** Browser-safe SHA-256 shared by versioned recipe contracts. */
+export function sha256Hex(text) {
     const source = new TextEncoder().encode(text);
     const bitLength = source.length * 8;
     const paddedLength = Math.ceil((source.length + 9) / 64) * 64;

package/lib/procedural-material-v3.d.ts

@@ -0,0 +1,72 @@
+/** Strict opt-in PBR material data. Pixel/byte loading is outside this module. */
+import { ProceduralTextureError } from "./procedural-material-v2.js";
+import { type CanonicalProceduralTextureSpecV3, type ProceduralTextureSpecV3 } from "./procedural-texture-v3-contract.js";
+import { type CanonicalPortableSamplerV1, type PortableSamplerV1 } from "./portable-sampler.js";
+import type { MaterialMapSlotV1 } from "./pinned-material-map.js";
+export declare const PORTABLE_MATERIAL_V3_LIMITS: Readonly<{
+    maxBindings: 5;
+    maxTexels: number;
+    maxEncodedBytes: number;
+    maxWork: 64000000;
+    maxTransientBytes: number;
+    maxJsonBytes: number;
+}>;
+export declare const PORTABLE_MATERIAL_SLOT_USAGE: {
+    readonly baseColor: 'albedo';
+    readonly normal: 'normal';
+    readonly metallicRoughness: 'metallicRoughness';
+    readonly emissive: 'emissive';
+    readonly occlusion: 'occlusion';
+};
+export type PortableTextureRefV3 = {
+    kind: 'procedural';
+    spec: ProceduralTextureSpecV3;
+    sampler: PortableSamplerV1;
+} | {
+    kind: 'resource';
+    resourceId: string;
+    sampler: PortableSamplerV1;
+};
+export type CanonicalPortableTextureRefV3 = {
+    kind: 'procedural';
+    spec: CanonicalProceduralTextureSpecV3;
+    sampler: CanonicalPortableSamplerV1;
+} | {
+    kind: 'resource';
+    resourceId: string;
+    sampler: CanonicalPortableSamplerV1;
+};
+export interface PortableMaterialSpecV3 {
+    schemaVersion: 3;
+    model: 'pbrMetallicRoughness';
+    name?: string;
+    baseColor?: number;
+    roughness?: number;
+    metalness?: number;
+    emissive?: number;
+    emissiveIntensity?: number;
+    alphaMode?: 'opaque' | 'mask' | 'blend';
+    alphaCutoff?: number;
+    doubleSided?: boolean;
+    textures?: Partial<Record<MaterialMapSlotV1, PortableTextureRefV3>>;
+}
+export interface CanonicalPortableMaterialSpecV3 extends Omit<PortableMaterialSpecV3, 'textures' | 'roughness' | 'metalness' | 'emissiveIntensity' | 'alphaMode' | 'alphaCutoff' | 'doubleSided'> {
+    roughness: number;
+    metalness: number;
+    emissiveIntensity: number;
+    alphaMode: 'opaque' | 'mask' | 'blend';
+    alphaCutoff: number;
+    doubleSided: boolean;
+    textures: Partial<Record<MaterialMapSlotV1, CanonicalPortableTextureRefV3>>;
+}
+export declare class PortableMaterialV3Error extends ProceduralTextureError {
+    constructor(message: string);
+}
+export interface PortableMaterialAdmissionV3 {
+    spec: CanonicalPortableMaterialSpecV3;
+    texels: number;
+    estimatedWorkUnits: number;
+    conservativePixelAllocationBytes: number;
+}
+export declare function admitPortableMaterialSpecV3(input: unknown): PortableMaterialAdmissionV3;
+export declare function canonicalizePortableMaterialSpecV3(input: unknown): CanonicalPortableMaterialSpecV3;

package/lib/procedural-material-v3.js

@@ -0,0 +1,162 @@
+/** Strict opt-in PBR material data. Pixel/byte loading is outside this module. */
+import { canonicalizePortableMaterialSpecV2, ProceduralTextureError, } from "./procedural-material-v2.js";
+import { admitProceduralTextureSpecV3, } from "./procedural-texture-v3-contract.js";
+import { canonicalizePortableSamplerV1, } from "./portable-sampler.js";
+export const PORTABLE_MATERIAL_V3_LIMITS = Object.freeze({
+    maxBindings: 5,
+    maxTexels: 4 * 1024 * 1024,
+    maxEncodedBytes: 16 * 1024 * 1024,
+    maxWork: 64_000_000,
+    maxTransientBytes: 64 * 1024 * 1024,
+    maxJsonBytes: 1024 * 1024,
+});
+export const PORTABLE_MATERIAL_SLOT_USAGE = {
+    baseColor: 'albedo',
+    normal: 'normal',
+    metallicRoughness: 'metallicRoughness',
+    emissive: 'emissive',
+    occlusion: 'occlusion',
+};
+export class PortableMaterialV3Error extends ProceduralTextureError {
+    constructor(message) {
+        super(`portableMaterial V3: ${message}`, 'PORTABLE_MATERIAL_V3_CONTRACT');
+        this.name = 'PortableMaterialV3Error';
+    }
+}
+function fail(message) {
+    throw new PortableMaterialV3Error(message);
+}
+/** Bound untrusted data before reading any accessor or making canonical copies. */
+function assertJson(input) {
+    let nodes = 0;
+    const visit = (value, depth) => {
+        if (++nodes > 65536 || depth > 16)
+            fail('JSON size/depth budget exceeded.');
+        if (value === null || typeof value === 'boolean')
+            return;
+        if (typeof value === 'string') {
+            if (value.length > PORTABLE_MATERIAL_V3_LIMITS.maxJsonBytes)
+                fail('string budget exceeded.');
+            return;
+        }
+        if (typeof value === 'number' && Number.isFinite(value))
+            return;
+        if (!value || typeof value !== 'object')
+            fail('only plain JSON data is supported.');
+        const array = Array.isArray(value), proto = Object.getPrototypeOf(value);
+        if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+            fail('only plain JSON prototypes are supported.');
+        const descriptors = Object.getOwnPropertyDescriptors(value), keys = Reflect.ownKeys(value);
+        if (keys.length > 1025)
+            fail('field/array budget exceeded.');
+        const length = array ? descriptors['length']?.value : undefined;
+        if (array && (length > 1024 || keys.length !== length + 1))
+            fail('arrays must be bounded dense JSON data.');
+        for (const key of keys) {
+            if (array && key === 'length')
+                continue;
+            if (typeof key !== 'string' || ['__proto__', 'prototype', 'constructor'].includes(key))
+                fail('forbidden JSON field.');
+            const d = descriptors[key];
+            if (!d.enumerable || !('value' in d))
+                fail('JSON accessors/hidden fields are unsupported.');
+            if (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= length))
+                fail('invalid array key.');
+            visit(d.value, depth + 1);
+        }
+    };
+    visit(input, 0);
+    if (new TextEncoder().encode(JSON.stringify(input)).length >
+        PORTABLE_MATERIAL_V3_LIMITS.maxJsonBytes)
+        fail('JSON byte budget exceeded.');
+}
+function record(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('expected a JSON object.');
+    const result = value;
+    if (Object.keys(result).some((key) => !keys.includes(key)))
+        fail('unknown field in material or texture reference.');
+    return result;
+}
+function admitMaterial(input) {
+    assertJson(input);
+    const scalarKeys = [
+        'baseColor',
+        'roughness',
+        'metalness',
+        'emissive',
+        'emissiveIntensity',
+        'alphaMode',
+        'alphaCutoff',
+        'doubleSided',
+    ];
+    const r = record(input, ['schemaVersion', 'model', 'name', 'textures', ...scalarKeys]);
+    if (r['schemaVersion'] !== 3 || r['model'] !== 'pbrMetallicRoughness')
+        fail('requires schemaVersion 3 and model pbrMetallicRoughness.');
+    const name = r['name'];
+    if (name !== undefined && (typeof name !== 'string' || name.length < 1 || name.length > 200))
+        fail('name requires 1..200 characters.');
+    const common = canonicalizePortableMaterialSpecV2({
+        schemaVersion: 2,
+        model: 'pbrMetallicRoughness',
+        ...Object.fromEntries(scalarKeys.filter((k) => r[k] !== undefined).map((k) => [k, r[k]])),
+    });
+    const refs = record(r['textures'] ?? {}, Object.keys(PORTABLE_MATERIAL_SLOT_USAGE));
+    const textures = {};
+    let texels = 0, work = 0, bytes = 0;
+    for (const [key, value] of Object.entries(refs)) {
+        const slot = key;
+        const ref = record(value, ['kind', 'spec', 'resourceId', 'sampler']);
+        const sampler = canonicalizePortableSamplerV1(ref['sampler']);
+        if (ref['kind'] === 'procedural') {
+            if (ref['resourceId'] !== undefined)
+                fail('procedural references cannot carry a resource ID.');
+            const admitted = admitProceduralTextureSpecV3(ref['spec']);
+            if (admitted.spec.usage !== PORTABLE_MATERIAL_SLOT_USAGE[slot])
+                fail(`${slot} requires ${PORTABLE_MATERIAL_SLOT_USAGE[slot]} data.`);
+            texels += admitted.spec.width * admitted.spec.height;
+            work += admitted.estimatedWorkUnits;
+            bytes += admitted.conservativePixelAllocationBytes;
+            textures[slot] = { kind: 'procedural', spec: admitted.spec, sampler };
+        }
+        else if (ref['kind'] === 'resource') {
+            if (ref['spec'] !== undefined ||
+                typeof ref['resourceId'] !== 'string' ||
+                ref['resourceId'].length > 128 ||
+                !/^kiln\.[a-z0-9][a-z0-9._-]+$/.test(ref['resourceId']))
+                fail('resource requires only a bounded closed kiln.* ID and sampler.');
+            textures[slot] = { kind: 'resource', resourceId: ref['resourceId'], sampler };
+        }
+        else
+            fail('texture kind must be procedural or resource.');
+    }
+    if (texels > PORTABLE_MATERIAL_V3_LIMITS.maxTexels ||
+        work > PORTABLE_MATERIAL_V3_LIMITS.maxWork ||
+        bytes > PORTABLE_MATERIAL_V3_LIMITS.maxTransientBytes)
+        fail('aggregate texel/work/allocation budget exceeded.');
+    const { schemaVersion: _, textures: __, ...parameters } = common;
+    return {
+        spec: {
+            schemaVersion: 3,
+            ...parameters,
+            ...(name !== undefined ? { name: name } : {}),
+            textures,
+        },
+        texels,
+        estimatedWorkUnits: work,
+        conservativePixelAllocationBytes: bytes,
+    };
+}
+export function admitPortableMaterialSpecV3(input) {
+    try {
+        return admitMaterial(input);
+    }
+    catch (error) {
+        if (error instanceof PortableMaterialV3Error)
+            throw error;
+        throw new PortableMaterialV3Error(error instanceof ProceduralTextureError ? error.message : 'Invalid bounded material data.');
+    }
+}
+export function canonicalizePortableMaterialSpecV3(input) {
+    return admitPortableMaterialSpecV3(input).spec;
+}

package/lib/procedural-texture-v2-compiler.d.ts

@@ -0,0 +1,31 @@
+/** Legacy V1/V2 pixel compiler. Extraction preserves arithmetic and recipe identity. */
+import { type CanonicalProceduralTextureSpecV2 } from "./procedural-material-v2.js";
+/**
+ * Build a tiling texture from a bounded, deterministic layer stack.
+ *
+ * The result is a plain RGBA `DataTexture`; `renderSceneToGLB` bakes it to PNG
+ * and embeds it, so nothing else has to be done to ship it.
+ *
+ * @example
+ * const bark = proceduralTexture({
+ *   schemaVersion: 2,
+ *   size: 256,
+ *   usage: 'albedo',
+ *   name: 'Bark',
+ *   layers: [
+ *     { op: 'solid', color: 0x5a4632 },
+ *     { op: 'noise', colorA: 0x3d2f21, colorB: 0x7a6248, scale: 6, octaves: 4, blend: 'overlay' },
+ *     { op: 'stripes', colorA: 0x000000, colorB: 0xffffff, count: 24, angleDeg: 90,
+ *       blend: 'multiply', opacity: 0.15 },
+ *   ],
+ * });
+ * const trunk = createPart('Trunk', cylinderGeo(0.3, 0.3, 3), pbrMaterial({ albedo: bark }), { parent: root });
+ */
+export interface CompiledProceduralTextureV2 {
+    spec: CanonicalProceduralTextureSpecV2;
+    pixels: Uint8Array;
+    canonicalJson: string;
+    recipeHash: `sha256:${string}`;
+}
+/** Validate, canonicalize, and compile one texture without constructing Three.js state. */
+export declare function compileProceduralTextureSpecV2(input: unknown): CompiledProceduralTextureV2;

package/lib/procedural-texture-v2-compiler.js

@@ -0,0 +1,172 @@
+/** Legacy V1/V2 pixel compiler. Extraction preserves arithmetic and recipe identity. */
+import { canonicalProceduralTextureJsonV2, canonicalizeProceduralTextureSpecV2, hashProceduralTextureSpecV2, } from "./procedural-material-v2.js";
+// -----------------------------------------------------------------------------
+// Deterministic value noise
+// -----------------------------------------------------------------------------
+/**
+ * Integer hash of a lattice coordinate. Not a cryptographic hash — it only has
+ * to decorrelate neighbouring integers and return the same value forever.
+ */
+function hash2(x, y, seed) {
+    let h = (Math.imul(x, 374761393) + Math.imul(y, 668265263) + Math.imul(seed, 1274126177)) | 0;
+    h = h ^ (h >>> 13);
+    h = Math.imul(h, 1274126177) | 0;
+    h = h ^ (h >>> 16);
+    return (h >>> 0) / 4294967296;
+}
+const smoothstep = (t) => t * t * (3 - 2 * t);
+/**
+ * Value noise on a lattice that wraps at `period`, so the result tiles.
+ * `period` is in lattice cells, and both axes use the same one.
+ */
+function valueNoise(u, v, period, seed) {
+    const x = u * period;
+    const y = v * period;
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    const xf = x - xi;
+    const yf = y - yi;
+    // Wrapping the lattice index (not the sample point) is what makes it tile:
+    // the cell to the right of the last one is the first one again.
+    const wrap = (n) => ((n % period) + period) % period;
+    const x0 = wrap(xi);
+    const y0 = wrap(yi);
+    const x1 = wrap(xi + 1);
+    const y1 = wrap(yi + 1);
+    const sx = smoothstep(xf);
+    const sy = smoothstep(yf);
+    const n00 = hash2(x0, y0, seed);
+    const n10 = hash2(x1, y0, seed);
+    const n01 = hash2(x0, y1, seed);
+    const n11 = hash2(x1, y1, seed);
+    const top = n00 + sx * (n10 - n00);
+    const bottom = n01 + sx * (n11 - n01);
+    return top + sy * (bottom - top);
+}
+function fbm(u, v, period, octaves, seed) {
+    let sum = 0;
+    let amplitude = 1;
+    let total = 0;
+    let p = period;
+    for (let o = 0; o < octaves; o++) {
+        sum += valueNoise(u, v, p, seed + o * 101) * amplitude;
+        total += amplitude;
+        amplitude *= 0.5;
+        // Doubling the period keeps every octave tileable at the base period.
+        p *= 2;
+    }
+    return total > 0 ? sum / total : 0;
+}
+// -----------------------------------------------------------------------------
+// Layer evaluation
+// -----------------------------------------------------------------------------
+const rgbOf = (color) => [
+    (color >> 16) & 0xff,
+    (color >> 8) & 0xff,
+    color & 0xff,
+];
+const lerp = (a, b, t) => a + (b - a) * t;
+/** Rotate normalized coords about the center so angled patterns stay centered. */
+function project(u, v, angleDeg) {
+    const a = (angleDeg * Math.PI) / 180;
+    return (u - 0.5) * Math.cos(a) + (v - 0.5) * Math.sin(a) + 0.5;
+}
+/** Evaluate one layer at a normalized coordinate, returning 0-255 RGB. */
+function evalLayer(layer, u, v) {
+    switch (layer.op) {
+        case 'solid':
+            return rgbOf(layer.color);
+        case 'checker': {
+            const cx = Math.floor(u * layer.squares);
+            const cy = Math.floor(v * layer.squares);
+            return rgbOf((cx + cy) % 2 === 0 ? layer.colorA : layer.colorB);
+        }
+        case 'stripes': {
+            const t = project(u, v, layer.angleDeg);
+            return rgbOf(Math.floor(t * layer.count) % 2 === 0 ? layer.colorA : layer.colorB);
+        }
+        case 'gradient': {
+            const t = Math.min(1, Math.max(0, project(u, v, layer.angleDeg)));
+            const from = rgbOf(layer.from);
+            const to = rgbOf(layer.to);
+            return [lerp(from[0], to[0], t), lerp(from[1], to[1], t), lerp(from[2], to[2], t)];
+        }
+        case 'bricks': {
+            const row = Math.floor(v * layer.rows);
+            // Offset alternate rows, wrapping into [0,1) so the pattern still tiles.
+            const shifted = (u + (row % 2 === 0 ? 0 : layer.stagger / layer.cols) + 1) % 1;
+            const inCol = (shifted * layer.cols) % 1;
+            const inRow = (v * layer.rows) % 1;
+            const isMortar = inCol < layer.mortarWidth ||
+                inCol > 1 - layer.mortarWidth ||
+                inRow < layer.mortarWidth ||
+                inRow > 1 - layer.mortarWidth;
+            return rgbOf(isMortar ? layer.mortar : layer.brick);
+        }
+        case 'noise': {
+            const n = fbm(u, v, layer.scale, layer.octaves, layer.seed);
+            const a = rgbOf(layer.colorA);
+            const b = rgbOf(layer.colorB);
+            return [lerp(a[0], b[0], n), lerp(a[1], b[1], n), lerp(a[2], b[2], n)];
+        }
+    }
+}
+function blendChannel(mode, base, top) {
+    const b = base / 255;
+    const t = top / 255;
+    let out;
+    switch (mode) {
+        case 'multiply':
+            out = b * t;
+            break;
+        case 'screen':
+            out = 1 - (1 - b) * (1 - t);
+            break;
+        case 'overlay':
+            out = b < 0.5 ? 2 * b * t : 1 - 2 * (1 - b) * (1 - t);
+            break;
+        default:
+            out = t;
+    }
+    return out * 255;
+}
+/** Validate, canonicalize, and compile one texture without constructing Three.js state. */
+export function compileProceduralTextureSpecV2(input) {
+    const spec = canonicalizeProceduralTextureSpecV2(input);
+    const { size, layers } = spec;
+    const data = new Uint8Array(size * size * 4);
+    for (let y = 0; y < size; y++) {
+        // Sample at texel centers so a pattern with N divisions lands on exact
+        // boundaries instead of drifting half a texel.
+        const v = (y + 0.5) / size;
+        for (let x = 0; x < size; x++) {
+            const u = (x + 0.5) / size;
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            for (const [i, layer] of layers.entries()) {
+                const [lr, lg, lb] = evalLayer(layer, u, v);
+                if (i === 0) {
+                    r = lr;
+                    g = lg;
+                    b = lb;
+                    continue;
+                }
+                r = lerp(r, blendChannel(layer.blend, r, lr), layer.opacity);
+                g = lerp(g, blendChannel(layer.blend, g, lg), layer.opacity);
+                b = lerp(b, blendChannel(layer.blend, b, lb), layer.opacity);
+            }
+            const o = (y * size + x) * 4;
+            data[o] = Math.max(0, Math.min(255, Math.round(r)));
+            data[o + 1] = Math.max(0, Math.min(255, Math.round(g)));
+            data[o + 2] = Math.max(0, Math.min(255, Math.round(b)));
+            data[o + 3] = 255;
+        }
+    }
+    return {
+        spec,
+        pixels: data,
+        canonicalJson: canonicalProceduralTextureJsonV2(spec),
+        recipeHash: hashProceduralTextureSpecV2(spec),
+    };
+}

package/lib/procedural-texture-v3-contract.d.ts

@@ -0,0 +1,125 @@
+/** Bounded JSON and identity contract; no pixel allocations or Three.js dependency. */
+import { type CanonicalProceduralTextureSpecV2, type ProceduralTextureSpecV2 } from "./procedural-material-v2.js";
+import { type TextureUsage } from "./texture-contract.js";
+export declare const PROCEDURAL_TEXTURE_V3_COMPILER_ID: 'kiln.procedural-rgba.v3.1';
+export declare const PROCEDURAL_TEXTURE_SPEC_VERSION_V3: 3;
+export declare const MAX_PROCEDURAL_V3_EDGE = 1024;
+export declare const MAX_PROCEDURAL_V3_TEXELS = 1048576;
+export declare const MAX_PROCEDURAL_V3_OPERATIONS = 64;
+export declare const MAX_PROCEDURAL_V3_VERTICES = 64;
+export declare const MAX_PROCEDURAL_V3_STAMPS = 256;
+export declare const MAX_PROCEDURAL_V3_PALETTE = 32;
+export declare const MAX_PROCEDURAL_V3_WORK = 64000000;
+export declare const MAX_PROCEDURAL_V3_TRANSIENT_BYTES: number;
+export type RgbaV3 = [number, number, number, number];
+export type PixelPointV3 = [number, number];
+export interface PixelRectangleV3 {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type ProceduralShapeV3 = (PixelRectangleV3 & {
+    kind: 'rectangle';
+}) | (PixelRectangleV3 & {
+    kind: 'ellipse';
+}) | {
+    kind: 'polygon';
+    points: PixelPointV3[];
+} | {
+    kind: 'line';
+    from: PixelPointV3;
+    to: PixelPointV3;
+    width: number;
+};
+export type ProceduralOperationV3 = {
+    op: 'paint';
+    shape: ProceduralShapeV3;
+    rgba: RgbaV3;
+    opacity?: number;
+} | {
+    op: 'mask';
+    shape: ProceduralShapeV3;
+    alpha?: number;
+    invert?: boolean;
+} | {
+    op: 'stamps';
+    shape: ProceduralShapeV3;
+    rgba: RgbaV3;
+    opacity?: number;
+    count: number;
+    seed: number;
+    area: PixelRectangleV3;
+    periodic?: boolean;
+} | {
+    op: 'legacy-v2';
+    spec: ProceduralTextureSpecV2;
+    alpha?: number;
+    opacity?: number;
+};
+export interface ProceduralTextureSpecV3 {
+    schemaVersion: 3;
+    width: number;
+    height: number;
+    usage?: TextureUsage;
+    name?: string;
+    background?: RgbaV3;
+    operations: ProceduralOperationV3[];
+    palette?: {
+        colors: number[];
+        dither?: 'none' | 'bayer4';
+    };
+}
+export type CanonicalProceduralOperationV3 = {
+    op: 'paint';
+    shape: ProceduralShapeV3;
+    rgba: RgbaV3;
+    opacity: number;
+} | {
+    op: 'mask';
+    shape: ProceduralShapeV3;
+    alpha: number;
+    invert: boolean;
+} | {
+    op: 'stamps';
+    shape: ProceduralShapeV3;
+    rgba: RgbaV3;
+    opacity: number;
+    count: number;
+    seed: number;
+    area: PixelRectangleV3;
+    periodic: boolean;
+} | {
+    op: 'legacy-v2';
+    spec: CanonicalProceduralTextureSpecV2;
+    alpha: number;
+    opacity: number;
+};
+export interface CanonicalProceduralTextureSpecV3 {
+    schemaVersion: 3;
+    width: number;
+    height: number;
+    usage: TextureUsage;
+    name?: string;
+    background: RgbaV3;
+    operations: CanonicalProceduralOperationV3[];
+    palette?: {
+        colors: number[];
+        dither: 'none' | 'bayer4';
+    };
+}
+export declare function proceduralShapeBoundsV3(s: ProceduralShapeV3): [number, number, number, number];
+export declare function proceduralShapeCostV3(s: ProceduralShapeV3): number;
+export declare function proceduralClippedBoundsV3(s: ProceduralShapeV3, width: number, height: number, dx?: number, dy?: number): [number, number, number, number];
+/** Internal composition admission; byte accounting is total RGBA allocations, not live peak/RSS. */
+export interface ProceduralTextureAdmissionV3 {
+    spec: CanonicalProceduralTextureSpecV3;
+    canonicalJson: string;
+    estimatedWorkUnits: number;
+    conservativePixelAllocationBytes: number;
+}
+/** Owns the single validation/accounting pass shared by standalone and atlas compilation. */
+export declare function admitProceduralTextureSpecV3(input: unknown): ProceduralTextureAdmissionV3;
+export declare function canonicalizeProceduralTextureSpecV3(input: unknown): CanonicalProceduralTextureSpecV3;
+export declare function canonicalProceduralTextureJsonV3(input: unknown): string;
+export declare function hashProceduralTextureSpecV3(input: unknown): `sha256:${string}`;