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.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(materials): derive normal maps from V3 height recipes (#205) (#225)
Matthew Kissingerb3c5bdf1eb04
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 671290c7..fb75150c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,12 @@ does not publish a package.bounded at 262,144 vertices. Discovery now answers foliage wording ("palm frondleaflets", "fern", "grass clump") with the repetition and card helpers, and the authoringskill describes the foliage workflow and when per-element naming applies.+- Accept `derive: normal-from-height` on V3 normal-slot maps in `schemaVersion:2` material+ drafts. Derivation reads compiled RGB luma as height, counts toward the V3 budgets, is+ recorded in the saved recipe and reapplied by verification. V3 `stamps` now accept data+ usages such as `normal`, so a height recipe can emboss the albedo's stamped pits; palettes+ stay colour-only. V2 derivation identities and existing V3 recipe hashes are unchanged+ (#205).## 1.3.1 (2026-10-17)diff --git a/dist/agent-run.mjs b/dist/agent-run.mjsindex 0d901d67..3ef49841 100644--- a/dist/agent-run.mjs+++ b/dist/agent-run.mjs@@ -3251,7 +3251,7 @@ function authoringDiagnosticAdvice(diagnostic) {if (diagnostic === "TEXTURE_ATLAS_CONTRACT")return 'textureAtlas requires bounded named integer content rectangles with nonoverlapping gutter allocations, matching source crops and usage, and explicit portable sampling. Sources are V3 recipes or exact host-injected library map pins. Split atlases exceeding aggregate work or allocation budgets. remapUVToAtlas requires finite unit UV0, a named content region, inputOrigin and mapping mode; it preserves topology and does not unwrap or tile a region. Read kiln_discover ids ["textureAtlas", "remapUVToAtlas"] for the exact contracts.';if (diagnostic === "PROCEDURAL_TEXTURE_V3_CONTRACT")- return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither and seeded stamps support only albedo/emissive. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';+ return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither supports only albedo/emissive; seeded stamps accept every usage. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';if (diagnostic === "BONE_CHAIN_ARGUMENT")return 'createBoneChain requires 1..1024 valid local joint descriptors with unique roles and animation-safe names across the parent hierarchy. Use normalized perpendicular forward/bend axes and finite rest transforms; an explicit parentRole must match the declared parent. Read the retained source and kiln_discover ids ["createBoneChain"] for the exact contract.';if (diagnostic === "SKIN_BINDING_ARGUMENT")@@ -4043,8 +4043,6 @@ function admitProceduralTextureSpecV3(input) {return { op: "paint", ...paint };}record2(op, ["op", "shape", "rgba", "opacity", "count", "seed", "area", "periodic"], path);- if (!colorUsage)- fail("stamps are supported only for color usages albedo and emissive.");const count = integer2(op["count"], 1, MAX_PROCEDURAL_V3_STAMPS, `${path}.count`);const periodic = boolean(op["periodic"], `${path}.periodic`);const [bx0, by0, bx1, by1] = proceduralShapeBoundsV3(s);@@ -5072,8 +5070,8 @@ function validateMaterialManifestAny(value) {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");+ if (recipe.compilerId !== PROCEDURAL_TEXTURE_V3_COMPILER_ID || spec.width !== map.width || spec.height !== map.height)+ throw Error("V3 compiler/dimensions 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")@@ -11730,14 +11728,13 @@ function exactKeys(value, keys) {if (Object.keys(value).some((key) => !keys.includes(key)))throw new Error("Unknown material draft field");}-function materialPixels(spec, derive) {- const compiled = compileProceduralTextureSpecV2(spec);+function derivedNormalPixels(compiled, size, derive) {if (!derive)return compiled;materialNormalDerivationSchema.parse(derive);- if (compiled.spec.usage !== "normal")+ if (size.usage !== "normal")throw new Error("Height derivation requires a normal map slot");- const height = new DataTexture3(compiled.pixels, compiled.spec.size, compiled.spec.size);+ const height = new DataTexture3(compiled.pixels, size.width, size.height);const normal = normalMapFromHeight(height, { strength: derive.strength });if (!(normal.image.data instanceof Uint8Array))throw new Error("Normal derivation must produce RGBA8 pixels");@@ -11746,6 +11743,15 @@ function materialPixels(spec, derive) {normal.dispose();return { ...compiled, pixels };}+function materialPixels(spec, derive) {+ const compiled = compileProceduralTextureSpecV2(spec);+ const { size, usage } = compiled.spec;+ return derivedNormalPixels(compiled, { width: size, height: size, usage }, derive);+}+function materialPixelsV3(spec, derive) {+ const compiled = compileProceduralTextureSpecV3(spec);+ return derivedNormalPixels(compiled, compiled.spec, derive);+}async function createMaterialRecordV1(draft) {assertMaterialJson(draft, true);exactKeys(draft, [@@ -12198,7 +12204,7 @@ async function verifyMaterialRecordContents(record, options) {if (canonicalMaterialJson(compiled.manifest) !== canonicalMaterialJson(recipe.manifest) || digest2(compiled.pixels) !== map.pixelHash)throw new Error("Atlas recipe/manifest/pixel hash mismatch");} else {- const compiled = recipe.spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(recipe.spec) : materialPixels(recipe.spec, recipe.derive);+ const compiled = recipe.spec.schemaVersion === 3 ? materialPixelsV3(recipe.spec, recipe.derive) : materialPixels(recipe.spec, recipe.derive);if (compiled.recipeHash !== recipe.recipeHash || digest2(compiled.pixels) !== recipe.pixelHash)throw new Error("Procedural recipe/pixel hash mismatch");}@@ -12217,9 +12223,10 @@ function admitMaterialManifestRecipes(manifest, resources) {if (recipe?.kind === "procedural") {if (recipe.spec.schemaVersion === 3) {const a = admitProceduralTextureSpecV3(recipe.spec);+ const derived = normalDerivationBudget(recipe.derive ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;} else {texels += recipe.spec.size ** 2;work += recipe.spec.size ** 2 * recipe.spec.layers.length * 16;@@ -12381,14 +12388,15 @@ async function createMaterialRecordV2(draft, options) {if (raw["procedural"] !== undefined) {const spec = raw["procedural"];if (spec.schemaVersion === 3) {- if (raw["derive"] !== undefined)- throw new Error("V3 normal derivation is unsupported");const a = admitProceduralTextureSpecV3(spec);if (a.spec.usage !== MATERIAL_LIBRARY_USAGE[slot])throw new Error("Procedural usage mismatch");+ if (raw["derive"] !== undefined && slot !== "normal")+ throw new Error("Height derivation requires a normal map slot");+ const derived = normalDerivationBudget(raw["derive"] !== undefined ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;prepared.push({ raw, slot, sampler, procedural: a.spec });} else {const canonical = canonicalizeProceduralTextureSpecV2(spec);@@ -12434,7 +12442,8 @@ async function createMaterialRecordV2(draft, options) {let bytes, pixelHash, recipe;if (item.procedural !== undefined) {const spec = item.procedural;- const compiled = spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(spec) : materialPixels(spec, raw["derive"]);+ const derive = raw["derive"];+ const compiled = spec.schemaVersion === 3 ? materialPixelsV3(spec, derive) : materialPixels(spec, derive);const d = compiled.spec.schemaVersion === 3 ? { width: compiled.spec.width, height: compiled.spec.height } : { width: compiled.spec.size, height: compiled.spec.size };pixelHash = digest2(compiled.pixels);bytes = new Uint8Array(await sharp(compiled.pixels, { raw: { ...d, channels: 4 } }).png({ compressionLevel: 9, adaptiveFiltering: false }).toBuffer());@@ -12513,7 +12522,7 @@ async function createMaterialRecordV2(draft, options) {await verifyMaterialRecord(record, { materials: [...records, record] });return record;}-var digest2 = (bytes) => `sha256:${createHash6("sha256").update(bytes).digest("hex")}`, encoder, identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;+var digest2 = (bytes) => `sha256:${createHash6("sha256").update(bytes).digest("hex")}`, encoder, normalDerivationBudget = (texels) => ({ work: texels * 16, allocation: texels * 8 }), identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;var init_material_library_node = __esm(() => {init_atomic_directory();init_material_library();@@ -41818,7 +41827,7 @@ define2("compilePortableMaterialSpecV3", {aliases: ["portable RGBA material", "explicit texture sampling"],intents: ["compile cutout or pixel-textured portable materials"],limitations: [- "Height-map derivation is not part of the V3 binding contract. V2 remains available for existing derive recipes."+ "Height-map derivation is not part of the V3 binding contract. Save a schemaVersion:2 material whose normal map has a V2 or V3 recipe with derive, then bind the saved record."]});var animationFacts = {@@ -42483,7 +42492,7 @@ define2("proceduralTexture", {parameters: ["V1/V2 preserve opaque patterns: size power-of-two 4..1024 and at most 8 layers. Explicit schemaVersion 3 uses width/height integers 4..1024, byte RGBA, at most 64 ordered operations and 64 polygon vertices.","V3 paint/mask use integer pixel-edge shapes with binary center coverage and fixed integer source-over rounding. A mask clears outside its shape; invert keeps outside. Zero-alpha pixels are transparent black.",- "V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Color-only stamps use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.",+ "V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Stamps (any usage) use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.","Pattern counts 1..256 and noise octaves 1..6; seeded patterns are deterministic.","For stripes and gradient, angleDeg rotates the direction of color variation in UV space about the image center. At 0 degrees colors vary across U: stripe bands run along V. At 90 degrees colors vary across V: bands run along U. This does not rotate the mesh UVs.","Stripes count is the number of alternating bands across one unit of the projected coordinate, not the number of colorA/colorB pairs. Gradient runs from its from color to its to color along that coordinate and clamps outside 0..1.",diff --git a/dist/build.json b/dist/build.jsonindex e39ef5f4..7dfd2385 100644--- a/dist/build.json+++ b/dist/build.json@@ -2,10 +2,10 @@"schemaVersion": 1,"entries": {"worker": {- "identity": "sha256:d71f5b28bc9572e3e74b37e93e6ad9917638d7f1421531506ed48a8e998ea1e9",+ "identity": "sha256:65bbde8a0f4fb6bbe5d2fb453a7bf06ee53816e24a065327378cc435eab7cacd","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "9e6070306969a354eb0817fba2931ec0504db414ecea16f3d06c7c5e85f670a6",+ "sourceHash": "9fd570a2fb356da9c98850bfdbec20794e41a56842a44a6118ea5c7f605dd23b","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -37,13 +37,13 @@},"target": "node","file": "evaluator-worker.mjs",- "bundleHash": "sha256:4cbcdd1fd68e59e1fa4c1117db544fb3feae766778af50a12a2fd9a10d1b24fb"+ "bundleHash": "sha256:bbf2cb6546fb3b154fb1fa1c4fd84f5829494e8729286746dff1c17eac076343"},"agent-run": {- "identity": "sha256:d71f5b28bc9572e3e74b37e93e6ad9917638d7f1421531506ed48a8e998ea1e9",+ "identity": "sha256:65bbde8a0f4fb6bbe5d2fb453a7bf06ee53816e24a065327378cc435eab7cacd","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "9e6070306969a354eb0817fba2931ec0504db414ecea16f3d06c7c5e85f670a6",+ "sourceHash": "9fd570a2fb356da9c98850bfdbec20794e41a56842a44a6118ea5c7f605dd23b","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -75,13 +75,13 @@},"target": "node","file": "agent-run.mjs",- "bundleHash": "sha256:91bc1d3195738d8a2f73be78a4244a31e5683959a31b412826f492721c8353c5"+ "bundleHash": "sha256:88a47ef5bf4cced9a46e776e2bdf7b5f47f446a3fd26e47164e49402c7721d8b"},"agent-providers": {- "identity": "sha256:d71f5b28bc9572e3e74b37e93e6ad9917638d7f1421531506ed48a8e998ea1e9",+ "identity": "sha256:65bbde8a0f4fb6bbe5d2fb453a7bf06ee53816e24a065327378cc435eab7cacd","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "9e6070306969a354eb0817fba2931ec0504db414ecea16f3d06c7c5e85f670a6",+ "sourceHash": "9fd570a2fb356da9c98850bfdbec20794e41a56842a44a6118ea5c7f605dd23b","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -116,10 +116,10 @@"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"},"mcp": {- "identity": "sha256:d71f5b28bc9572e3e74b37e93e6ad9917638d7f1421531506ed48a8e998ea1e9",+ "identity": "sha256:65bbde8a0f4fb6bbe5d2fb453a7bf06ee53816e24a065327378cc435eab7cacd","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "9e6070306969a354eb0817fba2931ec0504db414ecea16f3d06c7c5e85f670a6",+ "sourceHash": "9fd570a2fb356da9c98850bfdbec20794e41a56842a44a6118ea5c7f605dd23b","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -154,10 +154,10 @@"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"},"cli": {- "identity": "sha256:d71f5b28bc9572e3e74b37e93e6ad9917638d7f1421531506ed48a8e998ea1e9",+ "identity": "sha256:65bbde8a0f4fb6bbe5d2fb453a7bf06ee53816e24a065327378cc435eab7cacd","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "9e6070306969a354eb0817fba2931ec0504db414ecea16f3d06c7c5e85f670a6",+ "sourceHash": "9fd570a2fb356da9c98850bfdbec20794e41a56842a44a6118ea5c7f605dd23b","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -189,13 +189,13 @@},"target": "node","file": "cli.mjs",- "bundleHash": "sha256:6cacc84f73dbb600481d7549bc77c348013da1ffea0492dae1d00f26e25ec322"+ "bundleHash": "sha256:63f82be14be5a505b9d06fda197e4e5d6fe8b478c196f653981fcdce960a60c3"},"engine": {- "identity": "sha256:d71f5b28bc9572e3e74b37e93e6ad9917638d7f1421531506ed48a8e998ea1e9",+ "identity": "sha256:65bbde8a0f4fb6bbe5d2fb453a7bf06ee53816e24a065327378cc435eab7cacd","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "9e6070306969a354eb0817fba2931ec0504db414ecea16f3d06c7c5e85f670a6",+ "sourceHash": "9fd570a2fb356da9c98850bfdbec20794e41a56842a44a6118ea5c7f605dd23b","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -227,7 +227,7 @@},"target": "node","file": "mcp-engine.mjs",- "bundleHash": "sha256:ea01dc20d07ae19bb315d1c8954f403b191156afffa0218e82ea02e15af24724"+ "bundleHash": "sha256:c41e776bf0a57d83a82221f2a90465bd82d4743768fa09ecd6d1f2b7055dc25e"}}}diff --git a/dist/cli.mjs b/dist/cli.mjsindex ae7f3474..c9da3cc0 100644--- a/dist/cli.mjs+++ b/dist/cli.mjs@@ -129,7 +129,7 @@ function authoringDiagnosticAdvice(diagnostic) {if (diagnostic === "TEXTURE_ATLAS_CONTRACT")return 'textureAtlas requires bounded named integer content rectangles with nonoverlapping gutter allocations, matching source crops and usage, and explicit portable sampling. Sources are V3 recipes or exact host-injected library map pins. Split atlases exceeding aggregate work or allocation budgets. remapUVToAtlas requires finite unit UV0, a named content region, inputOrigin and mapping mode; it preserves topology and does not unwrap or tile a region. Read kiln_discover ids ["textureAtlas", "remapUVToAtlas"] for the exact contracts.';if (diagnostic === "PROCEDURAL_TEXTURE_V3_CONTRACT")- return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither and seeded stamps support only albedo/emissive. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';+ return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither supports only albedo/emissive; seeded stamps accept every usage. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';if (diagnostic === "BONE_CHAIN_ARGUMENT")return 'createBoneChain requires 1..1024 valid local joint descriptors with unique roles and animation-safe names across the parent hierarchy. Use normalized perpendicular forward/bend axes and finite rest transforms; an explicit parentRole must match the declared parent. Read the retained source and kiln_discover ids ["createBoneChain"] for the exact contract.';if (diagnostic === "SKIN_BINDING_ARGUMENT")@@ -1424,8 +1424,6 @@ function admitProceduralTextureSpecV3(input) {return { op: "paint", ...paint };}record2(op, ["op", "shape", "rgba", "opacity", "count", "seed", "area", "periodic"], path);- if (!colorUsage)- fail("stamps are supported only for color usages albedo and emissive.");const count = integer2(op["count"], 1, MAX_PROCEDURAL_V3_STAMPS, `${path}.count`);const periodic = boolean(op["periodic"], `${path}.periodic`);const [bx0, by0, bx1, by1] = proceduralShapeBoundsV3(s);@@ -15101,8 +15099,8 @@ function validateMaterialManifestAny(value) {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");+ if (recipe.compilerId !== PROCEDURAL_TEXTURE_V3_COMPILER_ID || spec.width !== map.width || spec.height !== map.height)+ throw Error("V3 compiler/dimensions 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")@@ -18772,14 +18770,13 @@ function exactKeys(value, keys) {if (Object.keys(value).some((key) => !keys.includes(key)))throw new Error("Unknown material draft field");}-function materialPixels(spec, derive) {- const compiled = compileProceduralTextureSpecV2(spec);+function derivedNormalPixels(compiled, size, derive) {if (!derive)return compiled;materialNormalDerivationSchema.parse(derive);- if (compiled.spec.usage !== "normal")+ if (size.usage !== "normal")throw new Error("Height derivation requires a normal map slot");- const height = new DataTexture3(compiled.pixels, compiled.spec.size, compiled.spec.size);+ const height = new DataTexture3(compiled.pixels, size.width, size.height);const normal = normalMapFromHeight(height, { strength: derive.strength });if (!(normal.image.data instanceof Uint8Array))throw new Error("Normal derivation must produce RGBA8 pixels");@@ -18788,6 +18785,15 @@ function materialPixels(spec, derive) {normal.dispose();return { ...compiled, pixels };}+function materialPixels(spec, derive) {+ const compiled = compileProceduralTextureSpecV2(spec);+ const { size, usage } = compiled.spec;+ return derivedNormalPixels(compiled, { width: size, height: size, usage }, derive);+}+function materialPixelsV3(spec, derive) {+ const compiled = compileProceduralTextureSpecV3(spec);+ return derivedNormalPixels(compiled, compiled.spec, derive);+}async function createMaterialRecordV1(draft) {assertMaterialJson(draft, true);exactKeys(draft, [@@ -19376,7 +19382,7 @@ async function verifyMaterialRecordContents(record, options) {if (canonicalMaterialJson(compiled.manifest) !== canonicalMaterialJson(recipe.manifest) || digest(compiled.pixels) !== map.pixelHash)throw new Error("Atlas recipe/manifest/pixel hash mismatch");} else {- const compiled = recipe.spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(recipe.spec) : materialPixels(recipe.spec, recipe.derive);+ const compiled = recipe.spec.schemaVersion === 3 ? materialPixelsV3(recipe.spec, recipe.derive) : materialPixels(recipe.spec, recipe.derive);if (compiled.recipeHash !== recipe.recipeHash || digest(compiled.pixels) !== recipe.pixelHash)throw new Error("Procedural recipe/pixel hash mismatch");}@@ -19395,9 +19401,10 @@ function admitMaterialManifestRecipes(manifest, resources) {if (recipe?.kind === "procedural") {if (recipe.spec.schemaVersion === 3) {const a = admitProceduralTextureSpecV3(recipe.spec);+ const derived = normalDerivationBudget(recipe.derive ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;} else {texels += recipe.spec.size ** 2;work += recipe.spec.size ** 2 * recipe.spec.layers.length * 16;@@ -19559,14 +19566,15 @@ async function createMaterialRecordV2(draft, options) {if (raw["procedural"] !== undefined) {const spec = raw["procedural"];if (spec.schemaVersion === 3) {- if (raw["derive"] !== undefined)- throw new Error("V3 normal derivation is unsupported");const a = admitProceduralTextureSpecV3(spec);if (a.spec.usage !== MATERIAL_LIBRARY_USAGE[slot])throw new Error("Procedural usage mismatch");+ if (raw["derive"] !== undefined && slot !== "normal")+ throw new Error("Height derivation requires a normal map slot");+ const derived = normalDerivationBudget(raw["derive"] !== undefined ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;prepared.push({ raw, slot, sampler, procedural: a.spec });} else {const canonical = canonicalizeProceduralTextureSpecV2(spec);@@ -19612,7 +19620,8 @@ async function createMaterialRecordV2(draft, options) {let bytes, pixelHash, recipe;if (item.procedural !== undefined) {const spec = item.procedural;- const compiled = spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(spec) : materialPixels(spec, raw["derive"]);+ const derive = raw["derive"];+ const compiled = spec.schemaVersion === 3 ? materialPixelsV3(spec, derive) : materialPixels(spec, derive);const d = compiled.spec.schemaVersion === 3 ? { width: compiled.spec.width, height: compiled.spec.height } : { width: compiled.spec.size, height: compiled.spec.size };pixelHash = digest(compiled.pixels);bytes = new Uint8Array(await sharp(compiled.pixels, { raw: { ...d, channels: 4 } }).png({ compressionLevel: 9, adaptiveFiltering: false }).toBuffer());@@ -19691,7 +19700,7 @@ async function createMaterialRecordV2(draft, options) {await verifyMaterialRecord(record, { materials: [...records, record] });return record;}-var digest = (bytes) => `sha256:${createHash5("sha256").update(bytes).digest("hex")}`, encoder, identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;+var digest = (bytes) => `sha256:${createHash5("sha256").update(bytes).digest("hex")}`, encoder, normalDerivationBudget = (texels) => ({ work: texels * 16, allocation: texels * 8 }), identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;var init_material_library_node = __esm(() => {init_atomic_directory();init_material_library();@@ -45147,7 +45156,7 @@ var init_helper_contracts = __esm(() => {aliases: ["portable RGBA material", "explicit texture sampling"],intents: ["compile cutout or pixel-textured portable materials"],limitations: [- "Height-map derivation is not part of the V3 binding contract. V2 remains available for existing derive recipes."+ "Height-map derivation is not part of the V3 binding contract. Save a schemaVersion:2 material whose normal map has a V2 or V3 recipe with derive, then bind the saved record."]});animationFacts = {@@ -45812,7 +45821,7 @@ var init_helper_contracts = __esm(() => {parameters: ["V1/V2 preserve opaque patterns: size power-of-two 4..1024 and at most 8 layers. Explicit schemaVersion 3 uses width/height integers 4..1024, byte RGBA, at most 64 ordered operations and 64 polygon vertices.","V3 paint/mask use integer pixel-edge shapes with binary center coverage and fixed integer source-over rounding. A mask clears outside its shape; invert keeps outside. Zero-alpha pixels are transparent black.",- "V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Color-only stamps use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.",+ "V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Stamps (any usage) use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.","Pattern counts 1..256 and noise octaves 1..6; seeded patterns are deterministic.","For stripes and gradient, angleDeg rotates the direction of color variation in UV space about the image center. At 0 degrees colors vary across U: stripe bands run along V. At 90 degrees colors vary across V: bands run along U. This does not rotate the mesh UVs.","Stripes count is the number of alternating bands across one unit of the projected coordinate, not the number of colorA/colorB pairs. Gradient runs from its from color to its to color along that coordinate and clamps outside 0..1.",diff --git a/dist/evaluator-worker.mjs b/dist/evaluator-worker.mjsindex 95c8fa86..afa07572 100644--- a/dist/evaluator-worker.mjs+++ b/dist/evaluator-worker.mjs@@ -31,7 +31,7 @@ function authoringDiagnosticAdvice(diagnostic) {if (diagnostic === "TEXTURE_ATLAS_CONTRACT")return 'textureAtlas requires bounded named integer content rectangles with nonoverlapping gutter allocations, matching source crops and usage, and explicit portable sampling. Sources are V3 recipes or exact host-injected library map pins. Split atlases exceeding aggregate work or allocation budgets. remapUVToAtlas requires finite unit UV0, a named content region, inputOrigin and mapping mode; it preserves topology and does not unwrap or tile a region. Read kiln_discover ids ["textureAtlas", "remapUVToAtlas"] for the exact contracts.';if (diagnostic === "PROCEDURAL_TEXTURE_V3_CONTRACT")- return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither and seeded stamps support only albedo/emissive. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';+ return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither supports only albedo/emissive; seeded stamps accept every usage. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';if (diagnostic === "BONE_CHAIN_ARGUMENT")return 'createBoneChain requires 1..1024 valid local joint descriptors with unique roles and animation-safe names across the parent hierarchy. Use normalized perpendicular forward/bend axes and finite rest transforms; an explicit parentRole must match the declared parent. Read the retained source and kiln_discover ids ["createBoneChain"] for the exact contract.';if (diagnostic === "SKIN_BINDING_ARGUMENT")@@ -4270,8 +4270,6 @@ function admitProceduralTextureSpecV3(input) {return { op: "paint", ...paint };}record5(op, ["op", "shape", "rgba", "opacity", "count", "seed", "area", "periodic"], path);- if (!colorUsage)- fail("stamps are supported only for color usages albedo and emissive.");const count = integer2(op["count"], 1, MAX_PROCEDURAL_V3_STAMPS, `${path}.count`);const periodic = boolean(op["periodic"], `${path}.periodic`);const [bx0, by0, bx1, by1] = proceduralShapeBoundsV3(s);@@ -30901,8 +30899,8 @@ function validateMaterialManifestAny(value) {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");+ if (recipe.compilerId !== PROCEDURAL_TEXTURE_V3_COMPILER_ID || spec.width !== map.width || spec.height !== map.height)+ throw Error("V3 compiler/dimensions 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")@@ -31259,14 +31257,13 @@ function snapshot(record) {files: Object.fromEntries(Object.entries(record.files).map(([name, bytes]) => [name, Uint8Array.from(bytes)]))};}-function materialPixels(spec, derive) {- const compiled = compileProceduralTextureSpecV2(spec);+function derivedNormalPixels(compiled, size, derive) {if (!derive)return compiled;materialNormalDerivationSchema.parse(derive);- if (compiled.spec.usage !== "normal")+ if (size.usage !== "normal")throw new Error("Height derivation requires a normal map slot");- const height = new DataTexture4(compiled.pixels, compiled.spec.size, compiled.spec.size);+ const height = new DataTexture4(compiled.pixels, size.width, size.height);const normal = normalMapFromHeight(height, { strength: derive.strength });if (!(normal.image.data instanceof Uint8Array))throw new Error("Normal derivation must produce RGBA8 pixels");@@ -31275,6 +31272,15 @@ function materialPixels(spec, derive) {normal.dispose();return { ...compiled, pixels };}+function materialPixels(spec, derive) {+ const compiled = compileProceduralTextureSpecV2(spec);+ const { size, usage } = compiled.spec;+ return derivedNormalPixels(compiled, { width: size, height: size, usage }, derive);+}+function materialPixelsV3(spec, derive) {+ const compiled = compileProceduralTextureSpecV3(spec);+ return derivedNormalPixels(compiled, compiled.spec, derive);+}async function verifyMaterialRecordV1(record) {const manifest = validateMaterialRecordShape(record);if (revisionHash(manifest) !== manifest.revisionId)@@ -31625,7 +31631,7 @@ async function verifyMaterialRecordContents(record, options) {if (canonicalMaterialJson(compiled.manifest) !== canonicalMaterialJson(recipe.manifest) || digest(compiled.pixels) !== map.pixelHash)throw new Error("Atlas recipe/manifest/pixel hash mismatch");} else {- const compiled = recipe.spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(recipe.spec) : materialPixels(recipe.spec, recipe.derive);+ const compiled = recipe.spec.schemaVersion === 3 ? materialPixelsV3(recipe.spec, recipe.derive) : materialPixels(recipe.spec, recipe.derive);if (compiled.recipeHash !== recipe.recipeHash || digest(compiled.pixels) !== recipe.pixelHash)throw new Error("Procedural recipe/pixel hash mismatch");}@@ -31639,9 +31645,10 @@ function admitMaterialManifestRecipes(manifest, resources) {if (recipe?.kind === "procedural") {if (recipe.spec.schemaVersion === 3) {const a = admitProceduralTextureSpecV3(recipe.spec);+ const derived = normalDerivationBudget(recipe.derive ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;} else {texels += recipe.spec.size ** 2;work += recipe.spec.size ** 2 * recipe.spec.layers.length * 16;@@ -31754,7 +31761,7 @@ async function decodeMaterialLibraryPayload(value) {const result = new Map(admitted.map((r) => [identity(r.manifest), r]));return wires.map((w) => result.get(identity(w.manifest)));}-var digest = (bytes) => `sha256:${createHash6("sha256").update(bytes).digest("hex")}`, encoder, identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;+var digest = (bytes) => `sha256:${createHash6("sha256").update(bytes).digest("hex")}`, encoder, normalDerivationBudget = (texels) => ({ work: texels * 16, allocation: texels * 8 }), identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;var init_material_library_node = __esm(() => {init_atomic_directory();init_material_library();diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjsindex 76989f2c..93577341 100644--- a/dist/mcp-engine.mjs+++ b/dist/mcp-engine.mjs@@ -72,7 +72,7 @@ function authoringDiagnosticAdvice(diagnostic) {if (diagnostic === "TEXTURE_ATLAS_CONTRACT")return 'textureAtlas requires bounded named integer content rectangles with nonoverlapping gutter allocations, matching source crops and usage, and explicit portable sampling. Sources are V3 recipes or exact host-injected library map pins. Split atlases exceeding aggregate work or allocation budgets. remapUVToAtlas requires finite unit UV0, a named content region, inputOrigin and mapping mode; it preserves topology and does not unwrap or tile a region. Read kiln_discover ids ["textureAtlas", "remapUVToAtlas"] for the exact contracts.';if (diagnostic === "PROCEDURAL_TEXTURE_V3_CONTRACT")- return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither and seeded stamps support only albedo/emissive. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';+ return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither supports only albedo/emissive; seeded stamps accept every usage. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';if (diagnostic === "BONE_CHAIN_ARGUMENT")return 'createBoneChain requires 1..1024 valid local joint descriptors with unique roles and animation-safe names across the parent hierarchy. Use normalized perpendicular forward/bend axes and finite rest transforms; an explicit parentRole must match the declared parent. Read the retained source and kiln_discover ids ["createBoneChain"] for the exact contract.';if (diagnostic === "SKIN_BINDING_ARGUMENT")@@ -864,8 +864,6 @@ function admitProceduralTextureSpecV3(input) {return { op: "paint", ...paint };}record(op, ["op", "shape", "rgba", "opacity", "count", "seed", "area", "periodic"], path);- if (!colorUsage)- fail("stamps are supported only for color usages albedo and emissive.");const count = integer2(op["count"], 1, MAX_PROCEDURAL_V3_STAMPS, `${path}.count`);const periodic = boolean(op["periodic"], `${path}.periodic`);const [bx0, by0, bx1, by1] = proceduralShapeBoundsV3(s);@@ -1893,8 +1891,8 @@ function validateMaterialManifestAny(value) {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");+ if (recipe.compilerId !== PROCEDURAL_TEXTURE_V3_COMPILER_ID || spec.width !== map.width || spec.height !== map.height)+ throw Error("V3 compiler/dimensions 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")@@ -5818,14 +5816,13 @@ function exactKeys(value, keys) {if (Object.keys(value).some((key) => !keys.includes(key)))throw new Error("Unknown material draft field");}-function materialPixels(spec, derive) {- const compiled = compileProceduralTextureSpecV2(spec);+function derivedNormalPixels(compiled, size, derive) {if (!derive)return compiled;materialNormalDerivationSchema.parse(derive);- if (compiled.spec.usage !== "normal")+ if (size.usage !== "normal")throw new Error("Height derivation requires a normal map slot");- const height = new DataTexture3(compiled.pixels, compiled.spec.size, compiled.spec.size);+ const height = new DataTexture3(compiled.pixels, size.width, size.height);const normal = normalMapFromHeight(height, { strength: derive.strength });if (!(normal.image.data instanceof Uint8Array))throw new Error("Normal derivation must produce RGBA8 pixels");@@ -5834,6 +5831,15 @@ function materialPixels(spec, derive) {normal.dispose();return { ...compiled, pixels };}+function materialPixels(spec, derive) {+ const compiled = compileProceduralTextureSpecV2(spec);+ const { size, usage } = compiled.spec;+ return derivedNormalPixels(compiled, { width: size, height: size, usage }, derive);+}+function materialPixelsV3(spec, derive) {+ const compiled = compileProceduralTextureSpecV3(spec);+ return derivedNormalPixels(compiled, compiled.spec, derive);+}async function createMaterialRecordV1(draft) {assertMaterialJson(draft, true);exactKeys(draft, [@@ -6422,7 +6428,7 @@ async function verifyMaterialRecordContents(record, options) {if (canonicalMaterialJson(compiled.manifest) !== canonicalMaterialJson(recipe.manifest) || digest(compiled.pixels) !== map.pixelHash)throw new Error("Atlas recipe/manifest/pixel hash mismatch");} else {- const compiled = recipe.spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(recipe.spec) : materialPixels(recipe.spec, recipe.derive);+ const compiled = recipe.spec.schemaVersion === 3 ? materialPixelsV3(recipe.spec, recipe.derive) : materialPixels(recipe.spec, recipe.derive);if (compiled.recipeHash !== recipe.recipeHash || digest(compiled.pixels) !== recipe.pixelHash)throw new Error("Procedural recipe/pixel hash mismatch");}@@ -6441,9 +6447,10 @@ function admitMaterialManifestRecipes(manifest, resources) {if (recipe?.kind === "procedural") {if (recipe.spec.schemaVersion === 3) {const a = admitProceduralTextureSpecV3(recipe.spec);+ const derived = normalDerivationBudget(recipe.derive ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;} else {texels += recipe.spec.size ** 2;work += recipe.spec.size ** 2 * recipe.spec.layers.length * 16;@@ -6605,14 +6612,15 @@ async function createMaterialRecordV2(draft, options) {if (raw["procedural"] !== undefined) {const spec = raw["procedural"];if (spec.schemaVersion === 3) {- if (raw["derive"] !== undefined)- throw new Error("V3 normal derivation is unsupported");const a = admitProceduralTextureSpecV3(spec);if (a.spec.usage !== MATERIAL_LIBRARY_USAGE[slot])throw new Error("Procedural usage mismatch");+ if (raw["derive"] !== undefined && slot !== "normal")+ throw new Error("Height derivation requires a normal map slot");+ const derived = normalDerivationBudget(raw["derive"] !== undefined ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;prepared.push({ raw, slot, sampler, procedural: a.spec });} else {const canonical = canonicalizeProceduralTextureSpecV2(spec);@@ -6658,7 +6666,8 @@ async function createMaterialRecordV2(draft, options) {let bytes, pixelHash, recipe;if (item.procedural !== undefined) {const spec = item.procedural;- const compiled = spec.schemaVersion === 3 ? compileProceduralTextureSpecV3(spec) : materialPixels(spec, raw["derive"]);+ const derive = raw["derive"];+ const compiled = spec.schemaVersion === 3 ? materialPixelsV3(spec, derive) : materialPixels(spec, derive);const d = compiled.spec.schemaVersion === 3 ? { width: compiled.spec.width, height: compiled.spec.height } : { width: compiled.spec.size, height: compiled.spec.size };pixelHash = digest(compiled.pixels);bytes = new Uint8Array(await sharp(compiled.pixels, { raw: { ...d, channels: 4 } }).png({ compressionLevel: 9, adaptiveFiltering: false }).toBuffer());@@ -6737,7 +6746,7 @@ async function createMaterialRecordV2(draft, options) {await verifyMaterialRecord(record, { materials: [...records, record] });return record;}-var digest = (bytes) => `sha256:${createHash2("sha256").update(bytes).digest("hex")}`, encoder, identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;+var digest = (bytes) => `sha256:${createHash2("sha256").update(bytes).digest("hex")}`, encoder, normalDerivationBudget = (texels) => ({ work: texels * 16, allocation: texels * 8 }), identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;var init_material_library_node = __esm(() => {init_atomic_directory();init_material_library();@@ -45933,7 +45942,7 @@ define2("compilePortableMaterialSpecV3", {aliases: ["portable RGBA material", "explicit texture sampling"],intents: ["compile cutout or pixel-textured portable materials"],limitations: [- "Height-map derivation is not part of the V3 binding contract. V2 remains available for existing derive recipes."+ "Height-map derivation is not part of the V3 binding contract. Save a schemaVersion:2 material whose normal map has a V2 or V3 recipe with derive, then bind the saved record."]});var animationFacts = {@@ -46598,7 +46607,7 @@ define2("proceduralTexture", {parameters: ["V1/V2 preserve opaque patterns: size power-of-two 4..1024 and at most 8 layers. Explicit schemaVersion 3 uses width/height integers 4..1024, byte RGBA, at most 64 ordered operations and 64 polygon vertices.","V3 paint/mask use integer pixel-edge shapes with binary center coverage and fixed integer source-over rounding. A mask clears outside its shape; invert keeps outside. Zero-alpha pixels are transparent black.",- "V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Color-only stamps use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.",+ "V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Stamps (any usage) use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.","Pattern counts 1..256 and noise octaves 1..6; seeded patterns are deterministic.","For stripes and gradient, angleDeg rotates the direction of color variation in UV space about the image center. At 0 degrees colors vary across U: stripe bands run along V. At 90 degrees colors vary across V: bands run along U. This does not rotate the mesh UVs.","Stripes count is the number of alternating bands across one unit of the projected coordinate, not the number of colorA/colorB pairs. Gradient runs from its from color to its to color along that coordinate and clamps outside 0..1.",diff --git a/docs/material-library.md b/docs/material-library.mdindex f8e0665e..3b5436d1 100644--- a/docs/material-library.md+++ b/docs/material-library.md@@ -50,8 +50,11 @@ drafts with `schemaVersion:2` also support RGBA recipes, named atlases and expliper-map samplers; see the [standalone texture workflow](procedural-surfaces-v3.md#standalone-saved-materials-and-atlases).An optional`derive: {"kind":"normal-from-height","strength":2}` on a normal map converts the recipe's-height pixels through the existing wrapped normal derivation. `import` accepts a complete-normalized payload. None of these operations acquires source images from a provider.+height pixels through the existing wrapped normal derivation: Rec. 601 luma of the compiled RGB+is read as height and alpha is ignored. It applies to V2 layer recipes and, in `schemaVersion:2`+drafts, to V3 RGBA recipes with `usage: 'normal'`; atlases and supplied bytes do not accept it.+The saved recipe records `derive`, and verification recompiles through it. `import` accepts a+complete normalized payload. None of these operations acquires source images from a provider.Curated resource packs are complete normalized payloads: maps, recipes and source/licenseprovenance, ready for explicit import. They are not npm package contents or public downloads;diff --git a/docs/procedural-surfaces-v3.md b/docs/procedural-surfaces-v3.mdindex f3fcabf9..f423a83f 100644--- a/docs/procedural-surfaces-v3.md+++ b/docs/procedural-surfaces-v3.md@@ -31,7 +31,8 @@ and V2 saved material records are opt-in contracts described below.RGBA channels are straight bytes. RGB is authored encoded color for albedo andemissive; other usages retain linear data. Transparent RGBA input canonicalizesto `[0,0,0,0]`, and every output pixel with zero alpha has zero RGB. Palette-mapping and stamps support only albedo/emissive; they reject all data usages.+mapping supports only albedo/emissive and rejects all data usages. Stamps write+bytes like `paint`, so every usage accepts them.Shapes and masks operate on declared bytes without interpreting data channels.Operations have these exact fields:@@ -213,6 +214,18 @@ complete runtime-validated fields. Sources keep explicit creator and licenserecords. The JSON authoring surface accepts no file paths, URLs to fetch, orraw image bytes. Existing external image records enter through verified import.+A normal-slot map with a V3 recipe of `usage: 'normal'` may add+`derive: {"kind":"normal-from-height","strength":4}`. The compiled pixels are+read as height (Rec. 601 luma of RGB; alpha ignored) and converted by the same+wrapped derivation as V2 recipes, so paint pits dark and ridges light. The+recipe hash still identifies the V3 spec; the pixel hash identifies the derived+normal pixels, and the saved recipe records `derive`. Derivation counts toward+the V3 work and allocation budgets. A height recipe can reuse the albedo's+`stamps` operation with the same seed and area, so embossed pits line up with+painted ones; palettes stay colour-only. Authored-source+`compilePortableMaterialSpecV3` references do not accept `derive`; save the+material and bind the record instead.+`textureAtlas(spec)` compiles named, fixed pixel rectangles. The atlas has`schemaVersion:1`, width, height, usage, an optional sampler, and regions.Coordinates are integer pixels from the top-left. Each region has a stablediff --git a/src/discovery/helper-contracts.ts b/src/discovery/helper-contracts.tsindex 687c7a4c..89090820 100644--- a/src/discovery/helper-contracts.ts+++ b/src/discovery/helper-contracts.ts@@ -1882,7 +1882,7 @@ define(aliases: ['portable RGBA material', 'explicit texture sampling'],intents: ['compile cutout or pixel-textured portable materials'],limitations: [- 'Height-map derivation is not part of the V3 binding contract. V2 remains available for existing derive recipes.',+ 'Height-map derivation is not part of the V3 binding contract. Save a schemaVersion:2 material whose normal map has a V2 or V3 recipe with derive, then bind the saved record.',],},);@@ -2699,7 +2699,7 @@ define(parameters: ['V1/V2 preserve opaque patterns: size power-of-two 4..1024 and at most 8 layers. Explicit schemaVersion 3 uses width/height integers 4..1024, byte RGBA, at most 64 ordered operations and 64 polygon vertices.','V3 paint/mask use integer pixel-edge shapes with binary center coverage and fixed integer source-over rounding. A mask clears outside its shape; invert keeps outside. Zero-alpha pixels are transparent black.',- 'V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Color-only stamps use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.',+ 'V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Stamps (any usage) use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.','Pattern counts 1..256 and noise octaves 1..6; seeded patterns are deterministic.','For stripes and gradient, angleDeg rotates the direction of color variation in UV space about the image center. At 0 degrees colors vary across U: stripe bands run along V. At 90 degrees colors vary across V: bands run along U. This does not rotate the mesh UVs.','Stripes count is the number of alternating bands across one unit of the projected coordinate, not the number of colorA/colorB pairs. Gradient runs from its from color to its to color along that coordinate and clamps outside 0..1.',diff --git a/src/evaluator/authoring-diagnostic.ts b/src/evaluator/authoring-diagnostic.tsindex f3c32521..5d6684c1 100644--- a/src/evaluator/authoring-diagnostic.ts+++ b/src/evaluator/authoring-diagnostic.ts@@ -93,7 +93,7 @@ export function authoringDiagnosticAdvice(diagnostic: AuthoringDiagnostic | undeif (diagnostic === 'TEXTURE_ATLAS_CONTRACT')return 'textureAtlas requires bounded named integer content rectangles with nonoverlapping gutter allocations, matching source crops and usage, and explicit portable sampling. Sources are V3 recipes or exact host-injected library map pins. Split atlases exceeding aggregate work or allocation budgets. remapUVToAtlas requires finite unit UV0, a named content region, inputOrigin and mapping mode; it preserves topology and does not unwrap or tile a region. Read kiln_discover ids ["textureAtlas", "remapUVToAtlas"] for the exact contracts.';if (diagnostic === 'PROCEDURAL_TEXTURE_V3_CONTRACT')- return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither and seeded stamps support only albedo/emissive. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';+ return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither supports only albedo/emissive; seeded stamps accept every usage. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';if (diagnostic === 'BONE_CHAIN_ARGUMENT')return 'createBoneChain requires 1..1024 valid local joint descriptors with unique roles and animation-safe names across the parent hierarchy. Use normalized perpendicular forward/bend axes and finite rest transforms; an explicit parentRole must match the declared parent. Read the retained source and kiln_discover ids ["createBoneChain"] for the exact contract.';if (diagnostic === 'SKIN_BINDING_ARGUMENT')diff --git a/src/material-library-node.ts b/src/material-library-node.tsindex ebeae550..1760d514 100644--- a/src/material-library-node.ts+++ b/src/material-library-node.ts@@ -112,16 +112,18 @@ function exactKeys(value: object, keys: string[]): void {if (Object.keys(value).some((key) => !keys.includes(key)))throw new Error('Unknown material draft field');}-function materialPixels(- spec: ProceduralTextureSpecV2,- derive?: { kind: 'normal-from-height'; strength: number },-) {- const compiled = compileProceduralTextureSpecV2(spec);+type MaterialNormalDerivation = { kind: 'normal-from-height'; strength: number };+/** Normal derivation reads four neighbours per texel and allocates the output plus its copy. */+const normalDerivationBudget = (texels: number) => ({ work: texels * 16, allocation: texels * 8 });+function derivedNormalPixels<T extends { pixels: Uint8Array }>(+ compiled: T,+ size: { width: number; height: number; usage: string },+ derive: MaterialNormalDerivation | undefined,+): T {if (!derive) return compiled;materialNormalDerivationSchema.parse(derive);- if (compiled.spec.usage !== 'normal')- throw new Error('Height derivation requires a normal map slot');- const height = new DataTexture(compiled.pixels, compiled.spec.size, compiled.spec.size);+ if (size.usage !== 'normal') throw new Error('Height derivation requires a normal map slot');+ const height = new DataTexture(compiled.pixels, size.width, size.height);const normal = normalMapFromHeight(height, { strength: derive.strength });if (!(normal.image.data instanceof Uint8Array))throw new Error('Normal derivation must produce RGBA8 pixels');@@ -130,6 +132,15 @@ function materialPixels(normal.dispose();return { ...compiled, pixels };}+function materialPixels(spec: ProceduralTextureSpecV2, derive?: MaterialNormalDerivation) {+ const compiled = compileProceduralTextureSpecV2(spec);+ const { size, usage } = compiled.spec;+ return derivedNormalPixels(compiled, { width: size, height: size, usage }, derive);+}+function materialPixelsV3(spec: unknown, derive?: MaterialNormalDerivation) {+ const compiled = compileProceduralTextureSpecV3(spec);+ return derivedNormalPixels(compiled, compiled.spec, derive);+}/** Bake existing bounded procedural recipes or accept normalized PNG bytes supplied by the host. */export async function createMaterialRecordV1(draft: MaterialDraftV1): Promise<MaterialRecordV1> {assertMaterialJson(draft, true);@@ -863,7 +874,7 @@ async function verifyMaterialRecordContents(} else {const compiled =recipe.spec.schemaVersion === 3- ? compileProceduralTextureSpecV3(recipe.spec)+ ? materialPixelsV3(recipe.spec, recipe.derive): materialPixels(recipe.spec, recipe.derive);if (compiled.recipeHash !== recipe.recipeHash || digest(compiled.pixels) !== recipe.pixelHash)throw new Error('Procedural recipe/pixel hash mismatch');@@ -897,9 +908,10 @@ function admitMaterialManifestRecipes(if (recipe?.kind === 'procedural') {if (recipe.spec.schemaVersion === 3) {const a = admitProceduralTextureSpecV3(recipe.spec);+ const derived = normalDerivationBudget(recipe.derive ? a.spec.width * a.spec.height : 0);texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;} else {texels += recipe.spec.size ** 2;work += recipe.spec.size ** 2 * recipe.spec.layers.length * 16;@@ -1134,13 +1146,17 @@ export async function createMaterialRecordV2(if (raw['procedural'] !== undefined) {const spec = raw['procedural'] as { schemaVersion?: number };if (spec.schemaVersion === 3) {- if (raw['derive'] !== undefined) throw new Error('V3 normal derivation is unsupported');const a = admitProceduralTextureSpecV3(spec);if (a.spec.usage !== MATERIAL_LIBRARY_USAGE[slot])throw new Error('Procedural usage mismatch');+ if (raw['derive'] !== undefined && slot !== 'normal')+ throw new Error('Height derivation requires a normal map slot');+ const derived = normalDerivationBudget(+ raw['derive'] !== undefined ? a.spec.width * a.spec.height : 0,+ );texels += a.spec.width * a.spec.height;- work += a.estimatedWorkUnits;- allocation += a.conservativePixelAllocationBytes;+ work += a.estimatedWorkUnits + derived.work;+ allocation += a.conservativePixelAllocationBytes + derived.allocation;prepared.push({ raw, slot, sampler, procedural: a.spec });} else {const canonical = canonicalizeProceduralTextureSpecV2(spec);@@ -1195,13 +1211,9 @@ export async function createMaterialRecordV2(let bytes: Uint8Array, pixelHash: `sha256:${string}`, recipe: MaterialMapV2['recipe'];if (item.procedural !== undefined) {const spec = item.procedural as ProceduralTextureSpecV2 | { schemaVersion: 3 };+ const derive = raw['derive'] as MaterialNormalDerivation | undefined;const compiled =- spec.schemaVersion === 3- ? compileProceduralTextureSpecV3(spec)- : materialPixels(- spec,- raw['derive'] as { kind: 'normal-from-height'; strength: number } | undefined,- );+ spec.schemaVersion === 3 ? materialPixelsV3(spec, derive) : materialPixels(spec, derive);const d =compiled.spec.schemaVersion === 3? { width: compiled.spec.width, height: compiled.spec.height }diff --git a/src/material-library-v2.test.ts b/src/material-library-v2.test.tsindex cce721ed..8634c42c 100644--- a/src/material-library-v2.test.ts+++ b/src/material-library-v2.test.ts@@ -15,7 +15,9 @@ import {type MaterialRecord,} from './material-library';import type { PortableSamplerV1 } from './portable-sampler';-import type { DataTexture } from 'three';+import { DataTexture } from 'three';+import { normalMapFromHeight } from './procedural-texture';+import { compileProceduralTextureSpecV3 } from './procedural-texture-v3';import {createMaterialRecordV1,createMaterialRecordV2,@@ -437,16 +439,8 @@ const toolError = (schema: z.ZodType, value: unknown): string => {expect(parsed.success).toBe(false);return describeInputError('kiln_material', parsed.error)!;};-const stamps = {- op: 'stamps',- shape: { kind: 'rectangle', x: 0, y: 0, width: 1, height: 1 },- rgba: [1, 2, 3, 255],- opacity: 1,- count: 2,- seed: 1,- area: { x: 0, y: 0, width: 8, height: 4 },- periodic: false,-};+// 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 }];@@ -455,10 +449,10 @@ const withMap = (map: Record<string, unknown>) => {test('draft V3 recipe errors name the canonicalizer rule instead of Invalid input', () => {const message = toolError(proceduralMaterialDraftV2Schema,- withMap({ procedural: { ...recipe, usage: 'normal', operations: [stamps] } }),+ withMap({ procedural: { ...recipe, usage: 'normal', palette } }),);expect(message).toContain(- 'maps.0.procedural: proceduralTexture V3: stamps are supported only for color usages albedo and emissive',+ 'maps.0.procedural: proceduralTexture V3: palette and dither are supported only for color usages albedo and emissive',);expect(message).not.toContain('Invalid input');});@@ -509,10 +503,10 @@ 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', operations: [stamps] };+ procedural.spec = { ...procedural.spec, usage: 'normal', palette };const v3Message = toolError(materialManifestV2Schema, spec);expect(v3Message).toContain(- 'maps.0.recipe.spec: proceduralTexture V3: stamps are supported only for color usages albedo and emissive',+ 'maps.0.recipe.spec: proceduralTexture V3: palette and dither are supported only for color usages albedo and emissive',);expect(v3Message).not.toContain('Invalid input');@@ -546,3 +540,122 @@ test('stored V3 and atlas recipe errors carry the canonicalizer reason', async (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/);+});diff --git a/src/material-library.ts b/src/material-library.tsindex 9a27724e..7ea74314 100644--- a/src/material-library.ts+++ b/src/material-library.ts@@ -745,11 +745,10 @@ export function validateMaterialManifestAny(value: unknown): MaterialManifest {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');+ throw Error('V3 compiler/dimensions mismatch');} else if (recipe.compilerId !== 'kiln.procedural-texture.v2' ||spec.size !== map.width ||diff --git a/src/procedural-texture-v3-contract.ts b/src/procedural-texture-v3-contract.tsindex a45bdc33..21d9f855 100644--- a/src/procedural-texture-v3-contract.ts+++ b/src/procedural-texture-v3-contract.ts@@ -356,7 +356,6 @@ export function admitProceduralTextureSpecV3(input: unknown): ProceduralTextureAreturn { op: 'paint', ...paint };}record(op, ['op', 'shape', 'rgba', 'opacity', 'count', 'seed', 'area', 'periodic'], path);- if (!colorUsage) fail('stamps are supported only for color usages albedo and emissive.');const count = integer(op['count'], 1, MAX_PROCEDURAL_V3_STAMPS, `${path}.count`);const periodic = boolean(op['periodic'], `${path}.periodic`);const [bx0, by0, bx1, by1] = proceduralShapeBoundsV3(s);