Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

24.9 KB
Raw Blame
import { afterEach, expect, test } from 'bun:test';
import { createHash } from 'node:crypto';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { z } from 'zod';
import {
  canonicalMaterialJson,
  materialLibraryPortableSpec,
  materialManifestV2Schema,
  proceduralMaterialDraftV2Schema,
  materialLibraryResourceId,
  validateMaterialManifestAny,
  type MaterialSourceV1,
  type MaterialRecord,
} from './material-library';
import type { PortableSamplerV1 } from './portable-sampler';
import { DataTexture } from 'three';
import { normalMapFromHeight } from './procedural-texture';
import { compileProceduralTextureSpecV3 } from './procedural-texture-v3';
import {
  createMaterialRecordV1,
  createMaterialRecordV2,
  createMaterialLibraryPayload,
  decodeMaterialLibraryPayload,
  createMaterialLibraryTextureResolver,
  FileMaterialLibrary,
  verifyMaterialRecord,
  resolveMaterialRecordClosure,
} from './material-library-node';
import { compilePortableMaterialSpecV3 } from './portable-material-runtime';
import { describeInputError } from './tools/actions';
import { TEXTURE_ATLAS_COMPILER_ID_V1_2 } from './texture-atlas-contract';
const temporaryRoots: string[] = [];
afterEach(async () => {
  for (const root of temporaryRoots.splice(0)) await rm(root, { recursive: true, force: true });
});
const hash = (bytes: Uint8Array | string) =>
  `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
const sampler = {
  minFilter: 'nearest',
  magFilter: 'nearest',
  wrapS: 'repeat',
  wrapT: 'repeat',
} as const;
const source: MaterialSourceV1 = {
  id: 'authored',
  kind: 'procedural',
  provider: 'Kiln',
  creator: 'Fixture author',
  license: {
    spdx: 'CC0-1.0',
    url: 'https://creativecommons.org/publicdomain/zero/1.0/',
    attribution: '',
  },
  originalFiles: [],
};
const recipe = {
  schemaVersion: 3,
  width: 8,
  height: 4,
  usage: 'albedo',
  background: [20, 50, 80, 255],
  operations: [
    {
      op: 'paint',
      shape: { kind: 'rectangle', x: 2, y: 0, width: 2, height: 4 },
      rgba: [150, 80, 30, 255],
    },
  ],
} as const;
const draft = (s: PortableSamplerV1 = sampler) => ({
  schemaVersion: 2,
  materialId: 'rectangular',
  name: 'Rectangular',
  tileable: true,
  sources: [structuredClone(source)],
  maps: [
    {
      slot: 'baseColor',
      sourceId: 'authored',
      transforms: [],
      sampler: s,
      procedural: structuredClone(recipe),
    },
  ],
});
test('new records retain exact rectangular V3 recipe/pixels/sampling under immutable identity', async () => {
  const a = await createMaterialRecordV2(draft()),
    b = await createMaterialRecordV2(draft());
  expect(a).toEqual(b);
  expect(a.manifest.schemaVersion).toBe(2);
  expect(a.manifest.maps[0]!.width).toBe(8);
  expect(a.manifest.maps[0]!.height).toBe(4);
  expect(a.manifest.maps[0]!.sampler).toEqual(sampler);
  expect(a.manifest.maps[0]!.recipe!.kind).toBe('procedural');
  await verifyMaterialRecord(a);
  const changed = await createMaterialRecordV2(draft({ ...sampler, wrapS: 'clamp-to-edge' }));
  expect(changed.manifest.revisionId).not.toBe(a.manifest.revisionId);
  expect(changed.files).toEqual(a.files);
  expect(changed.manifest.maps[0]!.pixelHash).toBe(a.manifest.maps[0]!.pixelHash);
});
test('mixed payload keeps old records exact and emits old-only envelope version1', async () => {
  const old = await createMaterialRecordV1({
    materialId: 'legacy',
    name: 'Legacy',
    tileable: true,
    sources: [structuredClone(source)],
    maps: [
      {
        slot: 'baseColor',
        sourceId: 'authored',
        transforms: [],
        procedural: {
          schemaVersion: 2,
          size: 4,
          usage: 'albedo',
          layers: [{ op: 'solid', color: 0x302010 }],
        },
      },
    ],
  });
  const oldJson = canonicalMaterialJson(old.manifest);
  const oldImage = old.files['baseColor.png']!.slice();
  const legacyPayload = await createMaterialLibraryPayload([old]);
  expect(legacyPayload.schemaVersion).toBe(1);
  const modern = await createMaterialRecordV2(draft());
  const mixed = await createMaterialLibraryPayload([old, modern]);
  expect(mixed.schemaVersion).toBe(2);
  const read = await decodeMaterialLibraryPayload(mixed);
  expect(canonicalMaterialJson(read[0]!.manifest)).toBe(oldJson);
  expect(read[0]!.files['baseColor.png']).toEqual(oldImage);
  expect(read[1]).toEqual(modern);
  expect(old.manifest.schemaVersion).toBe(1);
  expect('sampler' in old.manifest.maps[0]!).toBe(false);
});
test('tampered compiler, sampler, image, dimensions and even rehashed recipe/pixel inconsistencies fail', async () => {
  const original = await createMaterialRecordV2(draft());
  for (const mutate of [
    (r: typeof original) => {
      r.manifest.maps[0]!.sampler.wrapS = 'clamp-to-edge';
    },
    (r: typeof original) => {
      r.files['baseColor.png']![40] = r.files['baseColor.png']![40]! ^ 1;
    },
    (r: typeof original) => {
      r.manifest.maps[0]!.width++;
    },
  ]) {
    const r = structuredClone(original);
    mutate(r);
    await expect(verifyMaterialRecord(r)).rejects.toThrow();
  }
  const r = structuredClone(original);
  r.manifest.maps[0]!.pixelHash = `sha256:${'0'.repeat(64)}`;
  const { revisionId: _, ...content } = r.manifest;
  r.manifest.revisionId = hash(canonicalMaterialJson(content)) as typeof r.manifest.revisionId;
  await expect(verifyMaterialRecord(r)).rejects.toThrow(/pixel|recipe/);
  const future = structuredClone(original);
  (future.manifest.maps[0]!.recipe as unknown as Record<string, unknown>).compilerId = 'future';
  expect(() => validateMaterialManifestAny(future.manifest)).toThrow();
});
test('saved V2 resolver prepares owned bytes and compiled V3 texture without mesh/project', async () => {
  const record = await createMaterialRecordV2({
    ...draft(),
    physicalSizeMeters: { width: 2, height: 1 },
  });
  const resolver = await createMaterialLibraryTextureResolver([record]);
  const portable = materialLibraryPortableSpec(record.manifest);
  expect(portable.schemaVersion).toBe(3);
  const material = await compilePortableMaterialSpecV3(portable, { resolver });
  expect((material.map as DataTexture).image.width).toBe(8);
  expect(material.map!.minFilter).toBe(1003);
  const id = materialLibraryResourceId(record.manifest, 'baseColor');
  const a = await resolver.preparePortableTexture!(id);
  expect(a.userData['kilnMaterialResource']).toHaveProperty('physicalSizeMeters', {
    width: 2,
    height: 1,
  });
  a.bytes.fill(0);
  expect((await resolver.preparePortableTexture!(id)).bytes[0]).toBe(137);
});
test('filesystem readManifest is shape/identity-only and exact V1/V2 records read/import idempotently', async () => {
  const root = await mkdtemp(join(tmpdir(), 'kiln-material-v2-'));
  temporaryRoots.push(root);
  const library = new FileMaterialLibrary(root),
    record = await createMaterialRecordV2(draft());
  await library.import([record]);
  await library.import([record]);
  expect(
    await library.readManifest(record.manifest.materialId, record.manifest.revisionId),
  ).toEqual(record.manifest);
  expect(await library.read(record.manifest.materialId, record.manifest.revisionId)).toEqual(
    record,
  );
  expect(await library.list()).toEqual([record.manifest]);
});
test('manifest-first closure rejects aggregate before any full reads and preserves root order', async () => {
  const a = await createMaterialRecordV2(draft()),
    b = await createMaterialRecordV2({ ...draft(), materialId: 'second' });
  let reads = 0;
  const byId = new Map([
    [a.manifest.materialId, a],
    [b.manifest.materialId, b],
  ]);
  const reader = {
    readManifest: async (id: string) => byId.get(id)!.manifest,
    read: async (id: string) => {
      reads++;
      return byId.get(id)!;
    },
  };
  await expect(
    resolveMaterialRecordClosure([a.manifest, b.manifest], reader, {
      maxRecords: 1,
      maxBytes: 100000,
      maxPixels: 100000,
    }),
  ).rejects.toThrow(/count|record|limit/i);
  expect(reads).toBe(0);
  expect(
    (await resolveMaterialRecordClosure([b.manifest, a.manifest], reader)).map(
      (r) => r.manifest.materialId,
    ),
  ).toEqual(['second', 'rectangular']);
});
const atlasDraft = (child: MaterialRecord) => ({
  ...draft(),
  materialId: 'atlas',
  name: 'Atlas',
  maps: [
    {
      slot: 'baseColor',
      sourceId: 'authored',
      transforms: [],
      sampler,
      atlas: {
        schemaVersion: 1,
        width: 8,
        height: 4,
        usage: 'albedo',
        sampler,
        regions: [
          {
            name: 'source',
            content: { x: 0, y: 0, width: 8, height: 4 },
            gutter: 0,
            edgeMode: 'copy-edge',
            source: {
              kind: 'resource',
              resourceId: materialLibraryResourceId(child.manifest, 'baseColor'),
              pin: {
                resourceId: child.manifest.materialId,
                revisionId: child.manifest.revisionId,
                sha256: child.manifest.revisionId,
              },
            },
          },
        ],
      },
    },
  ],
});
test('dependent atlas pins exact revisions and roundtrips transitive mixed payload offline', async () => {
  const child = await createMaterialRecordV2(draft()),
    atlas = await createMaterialRecordV2(atlasDraft(child), { materials: [child] });
  expect(atlas.manifest.dependencies).toEqual([
    {
      resourceId: child.manifest.materialId,
      revisionId: child.manifest.revisionId,
      sha256: child.manifest.revisionId,
    },
  ]);
  expect(atlas.files['baseColor.png']).toEqual(child.files['baseColor.png']);
  await verifyMaterialRecord(atlas, { materials: [atlas, child] });
  await expect(verifyMaterialRecord(atlas)).rejects.toThrow(/pin|library|material/i);
  await expect(createMaterialLibraryPayload([atlas])).rejects.toThrow(/missing/i);
  const payload = await createMaterialLibraryPayload([atlas, child]);
  expect(await decodeMaterialLibraryPayload(payload)).toEqual([atlas, child]);
  const library = new FileMaterialLibrary(await mkdtemp(join(tmpdir(), 'kiln-atlas-library-')));
  temporaryRoots.push(library.root);
  await library.import([atlas], { materials: [atlas, child] });
  await expect(library.read(atlas.manifest.materialId, atlas.manifest.revisionId)).rejects.toThrow(
    /ENOENT|missing/i,
  );
  await library.import([child]);
  expect(await library.read(atlas.manifest.materialId, atlas.manifest.revisionId)).toEqual(atlas);
  const resolver = await createMaterialLibraryTextureResolver([atlas, child]),
    port = resolver.pinnedMaterialMaps!;
  const atlasTexture = await resolver.loadApprovedTexture(
    materialLibraryResourceId(atlas.manifest, 'baseColor'),
  );
  const atlasRecipe = atlas.manifest.maps[0]!.recipe!;
  expect(atlasTexture.userData['kilnAtlas'].manifest).toEqual(
    atlasRecipe.kind === 'atlas' ? atlasRecipe.manifest : undefined,
  );
  expect(
    (await resolver.preparePortableTexture!(materialLibraryResourceId(atlas.manifest, 'baseColor')))
      .userData['kilnAtlas'],
  ).toEqual(atlasTexture.userData['kilnAtlas']);
  const id = materialLibraryResourceId(child.manifest, 'baseColor'),
    pin = atlas.manifest.dependencies[0]!;
  const first = await port.resolvePinnedMaterialMapPixels(id, pin);
  first.pixels.fill(0);
  first.descriptor.width = 99;
  expect((await port.resolvePinnedMaterialMapPixels(id, pin)).descriptor.width).toBe(8);
  expect((await port.resolvePinnedMaterialMapPixels(id, pin)).pixels.some((x) => x !== 0)).toBe(
    true,
  );
  expect(port.describePinnedMaterialMap('kiln.texture.bark-albedo.v1', pin)).toBeUndefined();
});
test('closure metadata admits dependencies before full reads and rejects changed manifests', async () => {
  const child = await createMaterialRecordV2(draft()),
    atlas = await createMaterialRecordV2(atlasDraft(child), { materials: [child] });
  let reads = 0;
  const reader = {
    readManifest: async () => child.manifest,
    read: async (id: string) => {
      reads++;
      return id === 'atlas' ? atlas : child;
    },
  };
  await expect(
    resolveMaterialRecordClosure([atlas.manifest], reader, {
      maxRecords: 1,
      maxBytes: 100000,
      maxPixels: 100000,
    }),
  ).rejects.toThrow(/limit/);
  expect(reads).toBe(0);
  const missing = {
    ...reader,
    readManifest: async () => {
      throw new Error('missing child');
    },
  };
  await expect(resolveMaterialRecordClosure([atlas.manifest], missing)).rejects.toThrow(/missing/);
  expect(reads).toBe(0);
  const changed = { ...reader, read: async () => child };
  await expect(resolveMaterialRecordClosure([atlas.manifest], changed)).rejects.toThrow(/changed/);
});
test('V2 source closure rejects aggregate metadata before any caller byte snapshot', async () => {
  const base = await createMaterialRecordV2(draft());
  const records = Array.from({ length: 3 }, (_entry, i) => {
    const record = structuredClone(base),
      bytes = new Uint8Array(7 * 1024 * 1024);
    bytes.set(record.files['baseColor.png']!);
    record.files['baseColor.png'] = bytes;
    record.manifest.materialId = `padded${i}`;
    record.manifest.maps[0]!.bytes = bytes.length;
    record.manifest.maps[0]!.sha256 = hash(bytes);
    const { revisionId: _, ...content } = record.manifest;
    record.manifest.revisionId = hash(canonicalMaterialJson(content));
    return record;
  });
  await verifyMaterialRecord(records[0]!);
  let copies = 0;
  for (const record of records) {
    const bytes = record.files['baseColor.png']!,
      slice = bytes.slice.bind(bytes);
    bytes.slice = ((start?: number, end?: number) => {
      copies++;
      return slice(start, end);
    }) as typeof bytes.slice;
  }
  await expect(createMaterialRecordV2(draft(), { materials: records })).rejects.toThrow(
    /budget|limit/,
  );
  expect(copies).toBe(0);
});
test('persisted V3 recipe combinations share the exact64M work budget', async () => {
  const paint = {
    op: 'paint',
    shape: { kind: 'rectangle', x: 0, y: 0, width: 1024, height: 1024 },
    rgba: [30, 40, 50, 255],
  };
  const input = {
    ...draft(),
    maps: [
      {
        ...draft().maps[0],
        procedural: {
          schemaVersion: 3,
          width: 1024,
          height: 1024,
          usage: 'albedo',
          operations: Array.from({ length: 30 }, () => paint),
        },
      },
      {
        slot: 'emissive',
        sourceId: 'authored',
        transforms: [],
        sampler,
        procedural: {
          schemaVersion: 3,
          width: 256,
          height: 256,
          usage: 'emissive',
          background: [30, 40, 50, 255],
          operations: [],
        },
      },
    ],
  };
  await expect(createMaterialRecordV2(input)).rejects.toThrow(/work|aggregate|budget/i);
});
test('import deduplicates exact compound context identities and rejects conflicting selected bytes', async () => {
  const record = await createMaterialRecordV2(draft()),
    library = new FileMaterialLibrary(await mkdtemp(join(tmpdir(), 'kiln-context-library-')));
  temporaryRoots.push(library.root);
  const context = Array.from({ length: 1024 }, (_entry, i) => {
    if (i === 0) return record;
    const copy = structuredClone(record);
    copy.manifest.materialId = `context${i}`;
    const { revisionId: _, ...content } = copy.manifest;
    copy.manifest.revisionId = hash(canonicalMaterialJson(content));
    return copy;
  });
  await library.import([record], { materials: context });
  expect(await library.read(record.manifest.materialId, record.manifest.revisionId)).toEqual(
    record,
  );
  const bad = structuredClone(record);
  bad.files['baseColor.png']![40] = bad.files['baseColor.png']![40]! ^ 1;
  await expect(library.import([bad], { materials: [record] })).rejects.toThrow(
    /integrity|conflict|hash/i,
  );
  await expect(library.import([record], { materials: [bad] })).rejects.toThrow(
    /integrity|conflict|hash/i,
  );
});

// #198: a recipe only its canonicalizer rejects reached the agent as a bare
// "maps.0.procedural: Invalid input". Each refine now reports the canonicalizer's
// reason once, at the field it checked, in the text kiln_material returns.
const toolError = (schema: z.ZodType, value: unknown): string => {
  const parsed = schema.safeParse(value);
  expect(parsed.success).toBe(false);
  return describeInputError('kiln_material', parsed.error)!;
};
// V3 stamps accept every usage since #205; a palette is still limited to colour usages.
const palette = { colors: [0x102030], dither: 'none' };
const withMap = (map: Record<string, unknown>) => {
  const value = draft() as Record<string, unknown> & { maps: Record<string, unknown>[] };
  value.maps = [{ ...value.maps[0]!, ...map }];
  return value;
};
test('draft V3 recipe errors name the canonicalizer rule instead of Invalid input', () => {
  const message = toolError(
    proceduralMaterialDraftV2Schema,
    withMap({ procedural: { ...recipe, usage: 'normal', palette } }),
  );
  expect(message).toContain(
    'maps.0.procedural: proceduralTexture V3: palette and dither are supported only for color usages albedo and emissive',
  );
  expect(message).not.toContain('Invalid input');
});
test('a draft field the schema already bounds is reported once, without a parent line', () => {
  const message = toolError(
    proceduralMaterialDraftV2Schema,
    withMap({ procedural: { ...recipe, name: 'x'.repeat(100) } }),
  );
  expect(message).toContain(
    'maps.0.procedural.name: Too big: expected string to have <=80 characters',
  );
  expect(message).not.toContain('maps.0.procedural:');
  expect(message).not.toContain('Invalid input');
});
test('draft atlas errors name the canonicalizer rule instead of Invalid input', () => {
  const message = toolError(
    proceduralMaterialDraftV2Schema,
    withMap({
      procedural: undefined,
      atlas: {
        schemaVersion: 1,
        width: 8,
        height: 8,
        usage: 'albedo',
        regions: [
          {
            name: 'a',
            content: { x: 2, y: 2, width: 4, height: 4 },
            source: { kind: 'procedural', spec: { ...recipe, width: 4, usage: 'roughness' } },
          },
        ],
      },
    }),
  );
  expect(message).toContain('maps.0.atlas: textureAtlas: source usage does not match atlas usage');
  expect(message).not.toContain('Invalid input');
});
test('a sampler outside the portable set names the field and its options once', () => {
  const message = toolError(
    proceduralMaterialDraftV2Schema,
    withMap({ sampler: { ...sampler, wrapS: 'clamp' } }),
  );
  expect(message).toContain('maps.0.sampler.wrapS');
  expect(message).toContain('repeat');
  expect(message).not.toContain('Invalid input');
});
test('stored V3 and atlas recipe errors carry the canonicalizer reason', async () => {
  const v3 = (await createMaterialRecordV2(draft())).manifest;
  const spec = structuredClone(v3);
  const procedural = spec.maps[0]!.recipe as { spec: Record<string, unknown> };
  procedural.spec = { ...procedural.spec, usage: 'normal', palette };
  const v3Message = toolError(materialManifestV2Schema, spec);
  expect(v3Message).toContain(
    'maps.0.recipe.spec: proceduralTexture V3: palette and dither are supported only for color usages albedo and emissive',
  );
  expect(v3Message).not.toContain('Invalid input');

  const child = await createMaterialRecordV2(draft());
  const atlas = (await createMaterialRecordV2(atlasDraft(child), { materials: [child] })).manifest;
  const dilated = structuredClone(atlas);
  const dilatedSpec = (dilated.maps[0]!.recipe as { spec: Record<string, unknown> }).spec as {
    usage: string;
    regions: Record<string, unknown>[];
  };
  dilatedSpec.usage = 'normal';
  dilatedSpec.regions[0]!.edgeMode = 'mask-rgb-dilate';
  const specMessage = toolError(materialManifestV2Schema, dilated);
  expect(specMessage).toContain(
    'maps.0.recipe.spec: textureAtlas: mask RGB dilation requires color usage',
  );
  expect(specMessage).not.toContain('Invalid input');
  expect(specMessage).not.toContain('Invalid stored atlas manifest');

  const compiler = structuredClone(atlas);
  (compiler.maps[0]!.recipe as { compilerId: string }).compilerId = TEXTURE_ATLAS_COMPILER_ID_V1_2;
  const compilerMessage = toolError(materialManifestV2Schema, compiler);
  expect(compilerMessage).toContain(
    `maps.0.recipe: stored atlas manifest: recipe compilerId ${TEXTURE_ATLAS_COMPILER_ID_V1_2} does not match the manifest's`,
  );

  const layout = structuredClone(atlas);
  (layout.maps[0]!.recipe as { manifest: { layoutHash: string } }).manifest.layoutHash =
    `sha256:${'0'.repeat(64)}`;
  const layoutMessage = toolError(materialManifestV2Schema, layout);
  expect(layoutMessage).toContain('maps.0.recipe: stored atlas manifest: ');
  expect(layoutMessage).not.toMatch(/stored atlas manifest\.?(;|$| Check)/);
});

const heightSource = {
  schemaVersion: 3,
  width: 8,
  height: 8,
  usage: 'normal',
  background: [200, 200, 200, 255],
  operations: [
    {
      op: 'paint',
      shape: { kind: 'ellipse', x: 2, y: 2, width: 4, height: 4 },
      rgba: [40, 40, 40, 255],
    },
  ],
} as const;
const derivedDraft = (map: Record<string, unknown>) => ({
  schemaVersion: 2,
  materialId: 'pitted',
  name: 'Pitted',
  tileable: true,
  sources: [structuredClone(source)],
  maps: [{ slot: 'normal', sourceId: 'authored', transforms: [], sampler, ...map }],
});
test('V3 height derives a normal map that verifies and round-trips through a payload', async () => {
  const derive = { kind: 'normal-from-height', strength: 4 } as const;
  const record = await createMaterialRecordV2(
    derivedDraft({ procedural: structuredClone(heightSource), derive }),
  );
  const compiled = compileProceduralTextureSpecV3(heightSource);
  const height = new DataTexture(compiled.pixels, 8, 8);
  const normal = normalMapFromHeight(height, { strength: 4 });
  const map = record.manifest.maps[0]!;
  expect(map.pixelHash).toBe(hash(normal.image.data as Uint8Array));
  expect(map.pixelHash).not.toBe(hash(compiled.pixels));
  expect(map.recipe).toMatchObject({ kind: 'procedural', recipeHash: compiled.recipeHash, derive });
  await verifyMaterialRecord(record);
  const read = await decodeMaterialLibraryPayload(await createMaterialLibraryPayload([record]));
  expect(read[0]).toEqual(record);
  const tampered = structuredClone(record);
  (tampered.manifest.maps[0]!.recipe as { derive: { strength: number } }).derive.strength = 2;
  const { revisionId: _, ...content } = tampered.manifest;
  tampered.manifest.revisionId = hash(
    canonicalMaterialJson(content),
  ) as typeof tampered.manifest.revisionId;
  await expect(verifyMaterialRecord(tampered)).rejects.toThrow(/pixel|recipe/);
});
test('normal derivation still requires a normal slot and refuses atlas sources', async () => {
  await expect(
    createMaterialRecordV2({
      ...draft(),
      maps: [
        {
          ...draft().maps[0]!,
          derive: { kind: 'normal-from-height', strength: 2 },
        },
      ],
    }),
  ).rejects.toThrow(/normal map slot|usage/);
  await expect(
    createMaterialRecordV2(
      derivedDraft({
        procedural: { ...structuredClone(heightSource), usage: 'albedo' },
        derive: { kind: 'normal-from-height', strength: 2 },
      }),
    ),
  ).rejects.toThrow(/usage/);
  const child = await createMaterialRecordV2(draft());
  const atlas = atlasDraft(child);
  await expect(
    createMaterialRecordV2(
      {
        ...atlas,
        maps: [{ ...atlas.maps[0]!, derive: { kind: 'normal-from-height', strength: 2 } }],
      },
      { materials: [child] },
    ),
  ).rejects.toThrow(/Atlas derivation unsupported/);
});
test('V2 normal derivation keeps its recorded identities', async () => {
  const record = await createMaterialRecordV2(
    derivedDraft({
      procedural: {
        schemaVersion: 2,
        size: 8,
        usage: 'normal',
        layers: [{ op: 'noise', colorA: 0x202020, colorB: 0xe0e0e0, scale: 4, seed: 7 }],
      },
      derive: { kind: 'normal-from-height', strength: 3 },
    }),
  );
  expect(record.manifest.maps[0]!.pixelHash).toBe(
    'sha256:82ccc4035b46c5c224fe3ec50b4db8bdccda4f34cd7bb57ab9dac1c0dd2d2a74',
  );
  // The revision also covers the PNG encoder version, so only compiler identities are pinned.
  expect(record.manifest.maps[0]!.recipe).toMatchObject({
    recipeHash: 'sha256:30d6d7a740a6cc860148171b4ebce1288c09e0b9e95284936493df921e205578',
  });
});
test('a V3 height source may stamp pits on a data usage before derivation', async () => {
  const pits = {
    op: 'stamps',
    shape: { kind: 'ellipse', x: 0, y: 0, width: 3, height: 2 },
    rgba: [40, 40, 40, 255],
    count: 12,
    seed: 11,
    area: { x: 0, y: 0, width: 16, height: 16 },
    periodic: true,
  } as const;
  const height = { ...structuredClone(heightSource), width: 16, height: 16, operations: [pits] };
  const record = await createMaterialRecordV2(
    derivedDraft({ procedural: height, derive: { kind: 'normal-from-height', strength: 4 } }),
  );
  const compiled = compileProceduralTextureSpecV3(height);
  expect(new Set(compiled.pixels.filter((_, i) => i % 4 === 0))).toEqual(new Set([200, 40]));
  await verifyMaterialRecord(record);
  expect(() =>
    compileProceduralTextureSpecV3({ ...height, palette: { colors: [0x808080] } }),
  ).toThrow(/palette and dither are supported only for color usages/);
});