@instruktlabs/kiln 1.2.2 → 1.2.3

package/src/material-library.ts

@@ -4,6 +4,21 @@ import {
   canonicalizeProceduralTextureSpecV2,
   type CanonicalPortableMaterialSpecV2,
 } from './procedural-material-v2';
+import {
+  canonicalizeProceduralTextureSpecV3,
+  PROCEDURAL_TEXTURE_V3_COMPILER_ID,
+} from './procedural-texture-v3-contract';
+import { canonicalizePortableSamplerV1 } from './portable-sampler';
+import type { CanonicalPortableMaterialSpecV3 } from './procedural-material-v3';
+import {
+  canonicalizeTextureAtlasSpecV1,
+  validateTextureAtlasManifestV1,
+  TEXTURE_ATLAS_COMPILER_ID,
+  type CanonicalTextureAtlasSpecV1,
+} from './texture-atlas-contract';
+import type { TextureAtlasManifestV1 } from './texture-atlas-pixels';
+import type { MaterialMapPinV1 } from './pinned-material-map';
+import { makeMaterialAuthoringSchemas } from './material-authoring-schema';
 
 export const MATERIAL_LIBRARY_LIMITS = Object.freeze({
   maxMapBytes: 8 * 1024 * 1024,
@@ -301,9 +316,14 @@ export interface MaterialLibraryPayloadV1 {
   records: { manifest: MaterialManifestV1; files: Record<string, string> }[];
 }
 export interface MaterialLibrary {
-  list(): Promise<MaterialManifestV1[]>;
-  read(materialId: string, revisionId: string): Promise<MaterialRecordV1>;
-  import(records: MaterialRecordV1[]): Promise<MaterialManifestV1[]>;
+  list(): Promise<MaterialManifest[]>;
+  read(materialId: string, revisionId: string): Promise<MaterialRecord>;
+  readManifest?(materialId: string, revisionId: string): Promise<MaterialManifest>;
+  readRecordFiles?(materialId: string, revisionId: string): Promise<MaterialRecord>;
+  import(
+    records: MaterialRecord[],
+    options?: { materials?: readonly MaterialRecord[] },
+  ): Promise<MaterialManifest[]>;
 }
 export const materialLibraryPayloadSchema = z
   .object({
@@ -455,7 +475,7 @@ export function validateMaterialRecordShape(record: MaterialRecordV1): MaterialM
   return manifest;
 }
 export function materialLibraryResourceId(
-  manifest: MaterialManifestV1,
+  manifest: MaterialManifest,
   slot: MaterialLibrarySlot,
 ): string {
   materialLibraryHashSchema.parse(manifest.revisionId);
@@ -464,7 +484,35 @@ export function materialLibraryResourceId(
 }
 export function materialLibraryPortableSpec(
   manifest: MaterialManifestV1,
-): CanonicalPortableMaterialSpecV2 {
+): CanonicalPortableMaterialSpecV2;
+export function materialLibraryPortableSpec(
+  manifest: MaterialManifestV2,
+): CanonicalPortableMaterialSpecV3;
+export function materialLibraryPortableSpec(
+  manifest: MaterialManifest,
+): CanonicalPortableMaterialSpecV2 | CanonicalPortableMaterialSpecV3;
+export function materialLibraryPortableSpec(
+  manifest: MaterialManifest,
+): CanonicalPortableMaterialSpecV2 | CanonicalPortableMaterialSpecV3 {
+  if (manifest.schemaVersion === 2) {
+    const modern = validateMaterialManifestAny(manifest) as MaterialManifestV2;
+    return {
+      schemaVersion: 3,
+      model: 'pbrMetallicRoughness',
+      name: modern.name,
+      ...modern.parameters,
+      textures: Object.fromEntries(
+        modern.maps.map((map) => [
+          map.slot,
+          {
+            kind: 'resource' as const,
+            resourceId: materialLibraryResourceId(modern, map.slot),
+            sampler: { ...map.sampler },
+          },
+        ]),
+      ),
+    };
+  }
   manifest = validateMaterialManifest(manifest);
   return {
     schemaVersion: 2,
@@ -479,3 +527,298 @@ export function materialLibraryPortableSpec(
     ),
   };
 }
+
+/** 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: z.ZodType<CanonicalTextureAtlasSpecV1> =
+  authoringSchemas.canonicalTextureAtlasSpecV1Schema.refine((value) => {
+    try {
+      return (
+        canonicalMaterialJson(value) ===
+        canonicalMaterialJson(canonicalizeTextureAtlasSpecV1(value))
+      );
+    } catch {
+      return false;
+    }
+  });
+const atlasManifestSchema: z.ZodType<TextureAtlasManifestV1> =
+  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 type MaterialManifestV2 = z.infer<typeof materialManifestV2Schema>;
+export type MaterialMapV2 = MaterialManifestV2['maps'][number];
+export interface MaterialRecordV2 {
+  manifest: MaterialManifestV2;
+  files: Record<string, Uint8Array>;
+}
+export type MaterialManifest = MaterialManifestV1 | MaterialManifestV2;
+export type MaterialRecord = MaterialRecordV1 | MaterialRecordV2;
+export interface MaterialLibraryPayloadV2 {
+  schemaVersion: 2;
+  records: { manifest: MaterialManifest; files: Record<string, string> }[];
+}
+export type MaterialLibraryPayload = MaterialLibraryPayloadV1 | MaterialLibraryPayloadV2;
+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: MaterialManifest): MaterialMapPinV1[] {
+  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 type ProceduralMaterialDraftV2 = z.infer<typeof proceduralMaterialDraftV2Schema>;
+export const proceduralMaterialDraftAnySchema = z.union([
+  proceduralMaterialDraftSchema,
+  proceduralMaterialDraftV2Schema,
+]);
+export function validateMaterialManifestAny(value: unknown): MaterialManifest {
+  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 as Record<string, unknown>)['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<string, MaterialMapPinV1>();
+  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: MaterialRecord): MaterialManifest {
+  assertMaterialJson(record, true);
+  if (record.manifest.schemaVersion === 1)
+    return validateMaterialRecordShape(record as MaterialRecordV1);
+  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/src/pinned-material-map.ts

@@ -0,0 +1,43 @@
+/** Host-only atlas map capability. Authored code receives neither this port nor bytes. */
+import type { TextureUsage } from './texture-contract';
+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/src/portable-material-runtime.ts

@@ -12,6 +12,16 @@ import {
 } from './procedural-material-v2';
 import { proceduralTexture } from './procedural-texture';
 import { pbrMaterial, type PbrMaterialOptions, type TextureUsage } from './textures';
+import { loadTexture } from './textures';
+import {
+  admitPortableMaterialSpecV3,
+  PORTABLE_MATERIAL_V3_LIMITS,
+  PORTABLE_MATERIAL_SLOT_USAGE,
+  PortableMaterialV3Error,
+  type CanonicalPortableMaterialSpecV3,
+} from './procedural-material-v3';
+import { applyPortableSamplerV1 } from './portable-sampler-runtime';
+import type { PreparedPortableTextureV3 } from './texture-resolver';
 
 const SLOT_USAGE = {
   baseColor: 'albedo',
@@ -107,3 +117,193 @@ export async function compilePortableMaterialSpecV2(
     spec satisfies CanonicalPortableMaterialSpecV2;
   return material;
 }
+
+/** New V3 path owns every mutable texture/source/pixel/encoded-byte binding. */
+export async function compilePortableMaterialSpecV3(
+  input: unknown,
+  options: { resolver?: TextureResolver; signal?: AbortSignal } = {},
+): Promise<THREE.MeshStandardMaterial> {
+  const owned = new Map<PortableSlot, THREE.Texture>();
+  try {
+    const admission = admitPortableMaterialSpecV3(input),
+      spec = admission.spec;
+    const resolver = options.resolver ?? DEFAULT_TEXTURE_RESOLVER;
+    const entries = Object.entries(spec.textures) as Array<
+      [PortableSlot, NonNullable<CanonicalPortableMaterialSpecV3['textures'][PortableSlot]>]
+    >;
+    // 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<PortableSlot, PreparedPortableTextureV3>();
+    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: THREE.DataTexture;
+      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'] as Record<string, unknown>),
+          ...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/src/portable-sampler-runtime.ts

@@ -0,0 +1,40 @@
+/** Apply only after the caller has established independent texture ownership. */
+import {
+  ClampToEdgeWrapping,
+  LinearFilter,
+  LinearMipmapLinearFilter,
+  LinearMipmapNearestFilter,
+  MirroredRepeatWrapping,
+  NearestFilter,
+  NearestMipmapLinearFilter,
+  NearestMipmapNearestFilter,
+  RepeatWrapping,
+  type Texture,
+} from 'three';
+import { canonicalizePortableSamplerV1, type CanonicalPortableSamplerV1 } from './portable-sampler';
+const min = {
+  nearest: NearestFilter,
+  linear: LinearFilter,
+  'nearest-mipmap-nearest': NearestMipmapNearestFilter,
+  'linear-mipmap-nearest': LinearMipmapNearestFilter,
+  'nearest-mipmap-linear': NearestMipmapLinearFilter,
+  'linear-mipmap-linear': LinearMipmapLinearFilter,
+} as const;
+const wrap = {
+  repeat: RepeatWrapping,
+  'clamp-to-edge': ClampToEdgeWrapping,
+  'mirrored-repeat': MirroredRepeatWrapping,
+} as const;
+export function applyPortableSamplerV1<T extends Texture>(
+  ownedTexture: T,
+  sampler: CanonicalPortableSamplerV1,
+): T {
+  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;
+}