@instruktlabs/kiln 1.2.1 → 1.2.3

package/src/portable-sampler.ts

@@ -0,0 +1,54 @@
+/** Shared portable sampler contract; no renderer, loader or native dependencies. */
+import { ProceduralTextureError } from './procedural-material-v2';
+
+export const PORTABLE_MIN_FILTERS_V1 = [
+  'nearest',
+  'linear',
+  'nearest-mipmap-nearest',
+  'linear-mipmap-nearest',
+  'nearest-mipmap-linear',
+  'linear-mipmap-linear',
+] as const;
+export const PORTABLE_MAG_FILTERS_V1 = ['nearest', 'linear'] as const;
+export const PORTABLE_WRAPS_V1 = ['repeat', 'clamp-to-edge', 'mirrored-repeat'] as const;
+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 function canonicalizePortableSamplerV1(input: unknown): CanonicalPortableSamplerV1 {
+  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 as Record<string, unknown>;
+  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 as readonly unknown[]).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'],
+  } as CanonicalPortableSamplerV1;
+}

package/src/primitives.ts

@@ -19,7 +19,7 @@ import {
   GEOMETRY_ALLOCATION_LIMITS,
 } from './geometry-budget';
 import { buildWallPanels } from './wall-panels';
-import { createJointChain } from './character';
+import { createBoneChain, createJointChain, createSkinnedPart } from './character';
 import { describeAssembly, replicateAssembly } from './assembly';
 import { defineLod } from './lod';
 export { defineLod } from './lod';
@@ -57,8 +57,12 @@ import * as profile from './profile';
 import * as solids from './solids';
 import * as proceduralTextures from './procedural-texture';
 import * as textures from './textures';
+import { textureAtlas, remapUVToAtlas } from './texture-atlas';
 import type { TextureResolver } from './texture-resolver';
-import { compilePortableMaterialSpecV2 } from './portable-material-runtime';
+import {
+  compilePortableMaterialSpecV2,
+  compilePortableMaterialSpecV3,
+} from './portable-material-runtime';
 import { createVehicleFrame, createWheelAssembly, createWheelGeometrySet } from './vehicle';
 import {
   stampSemanticMetadataV1,
@@ -72,6 +76,36 @@ export { projectUV } from './uv-project';
 export type { ProjectUVOptions } from './uv-project';
 export { remapUV } from './uv-shapes';
 export type { RemapUVOptions } from './uv-shapes';
+export { textureAtlas, remapUVToAtlas } from './texture-atlas';
+export type { AtlasUVOptionsV1 } from './texture-atlas';
+export {
+  TextureAtlasError,
+  TEXTURE_ATLAS_COMPILER_ID,
+  TEXTURE_ATLAS_LIMITS,
+  canonicalizeTextureAtlasSpecV1,
+  canonicalTextureAtlasJsonV1,
+  hashTextureAtlasSpecV1,
+} from './texture-atlas-contract';
+export type {
+  AtlasRectangleV1,
+  AtlasEdgeModeV1,
+  AtlasResourceExpectationV1,
+  TextureAtlasSourceV1,
+  TextureAtlasRegionV1,
+  TextureAtlasSpecV1,
+  CanonicalTextureAtlasSourceV1,
+  CanonicalTextureAtlasRegionV1,
+  CanonicalTextureAtlasSpecV1,
+} from './texture-atlas-contract';
+export { compileTextureAtlasSpecV1 } from './texture-atlas-pixels';
+export type {
+  TextureAtlasCompileOptionsV1,
+  TextureAtlasBudgetV1,
+  TextureAtlasSourceManifestV1,
+  TextureAtlasRegionManifestV1,
+  TextureAtlasManifestV1,
+  CompiledTextureAtlasV1,
+} from './texture-atlas-pixels';
 
 export {
   createGableEndPanel,
@@ -86,8 +120,10 @@ export type {
   RoofFaceFrame,
   RoofSurfaceLayoutOptions,
 } from './architecture';
-export { createJointChain } from './character';
+export { createBoneChain, createJointChain, createSkinnedPart } from './character';
 export type {
+  BoneChainResultV1,
+  CreateSkinnedPartOptions,
   CreateJointChainOptionsV1,
   JointChainResultV1,
   JointChainSegmentV1,
@@ -100,7 +136,50 @@ export {
 export { materialRecipe } from './material-recipe-runtime';
 export type { ApplyMaterialRecipeOptions } from './material-recipe-runtime';
 export type { MaterialRecipeId, MaterialRecipeOverridesV1 } from './material-recipes';
-export { compilePortableMaterialSpecV2 } from './portable-material-runtime';
+export {
+  compilePortableMaterialSpecV2,
+  compilePortableMaterialSpecV3,
+} from './portable-material-runtime';
+export {
+  canonicalizePortableMaterialSpecV3,
+  PortableMaterialV3Error,
+  PORTABLE_MATERIAL_V3_LIMITS,
+} from './procedural-material-v3';
+export type {
+  PortableMaterialSpecV3,
+  CanonicalPortableMaterialSpecV3,
+  PortableTextureRefV3,
+  CanonicalPortableTextureRefV3,
+} from './procedural-material-v3';
+export { canonicalizePortableSamplerV1 } from './portable-sampler';
+export type { PortableSamplerV1, CanonicalPortableSamplerV1 } from './portable-sampler';
+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';
+export type {
+  CompiledProceduralTextureV3,
+  RgbaV3,
+  PixelPointV3,
+  PixelRectangleV3,
+  ProceduralShapeV3,
+  ProceduralOperationV3,
+  CanonicalProceduralOperationV3,
+  ProceduralTextureSpecV3,
+  CanonicalProceduralTextureSpecV3,
+} from './procedural-texture-v3';
 export {
   MAX_PORTABLE_MATERIAL_TEXELS,
   MAX_PORTABLE_MATERIAL_TEXTURES,
@@ -2173,6 +2252,8 @@ export function buildSandboxGlobals(
     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),
@@ -2223,6 +2304,13 @@ export function buildSandboxGlobals(
         );
       return compilePortableMaterialSpecV2(args[0], { resolver: options.textureResolver });
     }),
+    compilePortableMaterialSpecV3: wrap('compilePortableMaterialSpecV3', (...args: unknown[]) => {
+      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),
@@ -2275,6 +2363,7 @@ export function buildSandboxGlobals(
     // 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),
@@ -2283,6 +2372,11 @@ export function buildSandboxGlobals(
     loadApprovedTexture: wrap('loadApprovedTexture', loadApprovedTexture),
     // Procedural textures (sync — no I/O, so no await)
     proceduralTexture: wrap('proceduralTexture', proceduralTextures.proceduralTexture),
+    textureAtlas: wrap('textureAtlas', (...args: unknown[]) => {
+      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/src/procedural-material-v2.ts

@@ -519,7 +519,8 @@ const SHA256_K = new Uint32Array([
 const rotateRight = (value: number, bits: number): number =>
   (value >>> bits) | (value << (32 - bits));
 
-function sha256Hex(text: string): string {
+/** Browser-safe SHA-256 shared by versioned recipe contracts. */
+export function sha256Hex(text: string): string {
   const source = new TextEncoder().encode(text);
   const bitLength = source.length * 8;
   const paddedLength = Math.ceil((source.length + 9) / 64) * 64;

package/src/procedural-material-v3.ts

@@ -0,0 +1,224 @@
+/** Strict opt-in PBR material data. Pixel/byte loading is outside this module. */
+import {
+  canonicalizePortableMaterialSpecV2,
+  ProceduralTextureError,
+} from './procedural-material-v2';
+import {
+  admitProceduralTextureSpecV3,
+  type CanonicalProceduralTextureSpecV3,
+  type ProceduralTextureSpecV3,
+} from './procedural-texture-v3-contract';
+import {
+  canonicalizePortableSamplerV1,
+  type CanonicalPortableSamplerV1,
+  type PortableSamplerV1,
+} from './portable-sampler';
+import type { MaterialMapSlotV1 } from './pinned-material-map';
+
+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',
+} as const;
+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 class PortableMaterialV3Error extends ProceduralTextureError {
+  constructor(message: string) {
+    super(`portableMaterial V3: ${message}`, 'PORTABLE_MATERIAL_V3_CONTRACT');
+    this.name = 'PortableMaterialV3Error';
+  }
+}
+function fail(message: string): never {
+  throw new PortableMaterialV3Error(message);
+}
+/** Bound untrusted data before reading any accessor or making canonical copies. */
+function assertJson(input: unknown): void {
+  let nodes = 0;
+  const visit = (value: unknown, depth: number): void => {
+    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 as number) : 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: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('expected a JSON object.');
+  const result = value as Record<string, unknown>;
+  if (Object.keys(result).some((key) => !keys.includes(key)))
+    fail('unknown field in material or texture reference.');
+  return result;
+}
+export interface PortableMaterialAdmissionV3 {
+  spec: CanonicalPortableMaterialSpecV3;
+  texels: number;
+  estimatedWorkUnits: number;
+  conservativePixelAllocationBytes: number;
+}
+function admitMaterial(input: unknown): PortableMaterialAdmissionV3 {
+  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: CanonicalPortableMaterialSpecV3['textures'] = {};
+  let texels = 0,
+    work = 0,
+    bytes = 0;
+  for (const [key, value] of Object.entries(refs)) {
+    const slot = key as MaterialMapSlotV1;
+    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 as string } : {}),
+      textures,
+    },
+    texels,
+    estimatedWorkUnits: work,
+    conservativePixelAllocationBytes: bytes,
+  };
+}
+export function admitPortableMaterialSpecV3(input: unknown): PortableMaterialAdmissionV3 {
+  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: unknown,
+): CanonicalPortableMaterialSpecV3 {
+  return admitPortableMaterialSpecV3(input).spec;
+}

package/src/procedural-texture-v2-compiler.ts

@@ -0,0 +1,234 @@
+/** Legacy V1/V2 pixel compiler. Extraction preserves arithmetic and recipe identity. */
+import {
+  type CanonicalProceduralLayerV2,
+  type CanonicalProceduralTextureSpecV2,
+  type ProceduralBlend,
+  canonicalProceduralTextureJsonV2,
+  canonicalizeProceduralTextureSpecV2,
+  hashProceduralTextureSpecV2,
+} from './procedural-material-v2';
+
+// -----------------------------------------------------------------------------
+// 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: number, y: number, seed: number): number {
+  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: number): number => 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: number, v: number, period: number, seed: number): number {
+  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: number): number => ((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: number, v: number, period: number, octaves: number, seed: number): number {
+  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: number): [number, number, number] => [
+  (color >> 16) & 0xff,
+  (color >> 8) & 0xff,
+  color & 0xff,
+];
+
+const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
+
+/** Rotate normalized coords about the center so angled patterns stay centered. */
+function project(u: number, v: number, angleDeg: number): number {
+  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: CanonicalProceduralLayerV2,
+  u: number,
+  v: number,
+): [number, number, number] {
+  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: ProceduralBlend, base: number, top: number): number {
+  const b = base / 255;
+  const t = top / 255;
+  let out: number;
+  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;
+}
+
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+
+/**
+ * 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 function compileProceduralTextureSpecV2(input: unknown): CompiledProceduralTextureV2 {
+  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),
+  };
+}