@instruktlabs/kiln 1.2.1 → 1.2.3

package/lib/procedural-texture-v3-contract.js

@@ -0,0 +1,333 @@
+/** Bounded JSON and identity contract; no pixel allocations or Three.js dependency. */
+import { canonicalizeProceduralTextureSpecV2, ProceduralTextureError, sha256Hex, } from "./procedural-material-v2.js";
+import { TEXTURE_USAGES } from "./texture-contract.js";
+export const PROCEDURAL_TEXTURE_V3_COMPILER_ID = 'kiln.procedural-rgba.v3.1';
+export const PROCEDURAL_TEXTURE_SPEC_VERSION_V3 = 3;
+export const MAX_PROCEDURAL_V3_EDGE = 1024;
+export const MAX_PROCEDURAL_V3_TEXELS = 1_048_576;
+export const MAX_PROCEDURAL_V3_OPERATIONS = 64;
+export const MAX_PROCEDURAL_V3_VERTICES = 64;
+export const MAX_PROCEDURAL_V3_STAMPS = 256;
+export const MAX_PROCEDURAL_V3_PALETTE = 32;
+export const MAX_PROCEDURAL_V3_WORK = 64_000_000;
+export const MAX_PROCEDURAL_V3_TRANSIENT_BYTES = 64 * 1024 * 1024;
+function fail(message) {
+    throw new ProceduralTextureError(`proceduralTexture V3: ${message}`, 'PROCEDURAL_TEXTURE_V3_CONTRACT');
+}
+const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
+/** Inspect data descriptors before reading values, including array elements. */
+function assertProceduralJsonV3(input) {
+    let nodes = 0;
+    const visit = (value, path, depth) => {
+        if (++nodes > 16_384 || depth > 10)
+            fail(`${path} exceeds the JSON size/depth budget.`);
+        if (value === null || typeof value === 'boolean')
+            return;
+        if (typeof value === 'string') {
+            if (value.length > 4096)
+                fail(`${path} string is too long.`);
+            return;
+        }
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                fail(`${path} must be finite.`);
+            return;
+        }
+        if (typeof value !== 'object')
+            fail(`${path} must contain only JSON data.`);
+        const array = Array.isArray(value);
+        const proto = Object.getPrototypeOf(value);
+        if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+            fail(`${path} must be a plain JSON ${array ? 'array' : 'object'}.`);
+        // Reject oversized arrays before enumerating or copying element descriptors.
+        const length = array
+            ? Object.getOwnPropertyDescriptor(value, 'length')?.value
+            : undefined;
+        if (array && (typeof length !== 'number' || length > 1024))
+            fail(`${path} array is too long.`);
+        const keys = Reflect.ownKeys(value);
+        if (keys.length > 1024)
+            fail(`${path} has too many fields.`);
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        for (const key of keys) {
+            if (typeof key !== 'string' || forbidden.has(key))
+                fail(`${path} has a forbidden key.`);
+            if (array && key === 'length')
+                continue;
+            const descriptor = descriptors[key];
+            if (!descriptor.enumerable || !('value' in descriptor))
+                fail(`${path}.${key} must be an enumerable JSON data field, never an accessor.`);
+            if (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= length))
+                fail(`${path} has an invalid array key.`);
+        }
+        if (array && keys.length !== length + 1)
+            fail(`${path} must be a dense JSON array.`);
+        for (const key of keys)
+            if (key !== 'length' || !array)
+                visit(descriptors[key].value, `${path}.${String(key)}`, depth + 1);
+    };
+    visit(input, 'recipe', 0);
+}
+function record(value, allowed, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(`${path} must be a JSON object.`);
+    const result = value;
+    for (const key of Object.keys(result))
+        if (!allowed.includes(key))
+            fail(`${path} has unknown field ${key}.`);
+    return result;
+}
+function integer(value, min, max, path, fallback) {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max)
+        fail(`${path} must be an integer ${min}..${max}.`);
+    return value === 0 ? 0 : value;
+}
+function boolean(value, path) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        fail(`${path} must be boolean.`);
+    return value;
+}
+function tuple(value, length, path, min, max) {
+    if (!Array.isArray(value) || value.length !== length)
+        fail(`${path} must be a ${length}-element array.`);
+    return value.map((v, i) => integer(v, min, max, `${path}[${i}]`));
+}
+function rgba(value, path) {
+    const c = tuple(value, 4, path, 0, 255);
+    return c[3] === 0 ? [0, 0, 0, 0] : c;
+}
+function rectangle(value, path, kind) {
+    const r = record(value, ['x', 'y', 'width', 'height', ...(kind ? ['kind'] : [])], path);
+    return {
+        x: integer(r['x'], -4096, 4096, `${path}.x`),
+        y: integer(r['y'], -4096, 4096, `${path}.y`),
+        width: integer(r['width'], 1, 2048, `${path}.width`),
+        height: integer(r['height'], 1, 2048, `${path}.height`),
+    };
+}
+function shape(value, path) {
+    const r = record(value, ['kind', 'x', 'y', 'width', 'height', 'from', 'to', 'points'], path);
+    if (r['kind'] === 'rectangle' || r['kind'] === 'ellipse')
+        return { kind: r['kind'], ...rectangle(r, path, r['kind']) };
+    if (r['kind'] === 'polygon') {
+        record(r, ['kind', 'points'], path);
+        const points = r['points'];
+        if (!Array.isArray(points) || points.length < 3 || points.length > MAX_PROCEDURAL_V3_VERTICES)
+            fail(`${path}.points requires 3..${MAX_PROCEDURAL_V3_VERTICES} vertices.`);
+        return {
+            kind: 'polygon',
+            points: points.map((p, i) => tuple(p, 2, `${path}.points[${i}]`, -4096, 4096)),
+        };
+    }
+    if (r['kind'] === 'line') {
+        record(r, ['kind', 'from', 'to', 'width'], path);
+        return {
+            kind: 'line',
+            from: tuple(r['from'], 2, `${path}.from`, -4096, 4096),
+            to: tuple(r['to'], 2, `${path}.to`, -4096, 4096),
+            width: integer(r['width'], 1, 2048, `${path}.width`),
+        };
+    }
+    return fail(`${path}.kind must be rectangle, ellipse, polygon or line.`);
+}
+export function proceduralShapeBoundsV3(s) {
+    if (s.kind === 'rectangle' || s.kind === 'ellipse')
+        return [s.x, s.y, s.x + s.width, s.y + s.height];
+    const points = s.kind === 'polygon' ? s.points : [s.from, s.to];
+    const radius = s.kind === 'line' ? s.width / 2 : 0;
+    return [
+        Math.min(...points.map((p) => p[0])) - radius,
+        Math.min(...points.map((p) => p[1])) - radius,
+        Math.max(...points.map((p) => p[0])) + radius,
+        Math.max(...points.map((p) => p[1])) + radius,
+    ];
+}
+export function proceduralShapeCostV3(s) {
+    return s.kind === 'polygon'
+        ? s.points.length + 1
+        : s.kind === 'line'
+            ? 4
+            : s.kind === 'ellipse'
+                ? 3
+                : 1;
+}
+export function proceduralClippedBoundsV3(s, width, height, dx = 0, dy = 0) {
+    const [x0, y0, x1, y1] = proceduralShapeBoundsV3(s);
+    return [
+        Math.max(0, Math.ceil(x0 + dx - 0.5)),
+        Math.max(0, Math.ceil(y0 + dy - 0.5)),
+        Math.min(width, Math.floor(x1 + dx - 0.5) + 1),
+        Math.min(height, Math.floor(y1 + dy - 0.5) + 1),
+    ];
+}
+/** Owns the single validation/accounting pass shared by standalone and atlas compilation. */
+export function admitProceduralTextureSpecV3(input) {
+    assertProceduralJsonV3(input);
+    const r = record(input, ['schemaVersion', 'width', 'height', 'usage', 'name', 'background', 'operations', 'palette'], 'recipe');
+    if (r['schemaVersion'] !== 3)
+        fail('schemaVersion must be 3.');
+    const width = integer(r['width'], 4, MAX_PROCEDURAL_V3_EDGE, 'width');
+    const height = integer(r['height'], 4, MAX_PROCEDURAL_V3_EDGE, 'height');
+    const texels = width * height;
+    if (texels > MAX_PROCEDURAL_V3_TEXELS)
+        fail('output texel budget exceeded.');
+    const usage = r['usage'] === undefined ? 'albedo' : r['usage'];
+    if (!TEXTURE_USAGES.includes(usage))
+        fail('usage must be a known texture usage.');
+    const colorUsage = usage === 'albedo' || usage === 'emissive';
+    const name = r['name'];
+    if (name !== undefined &&
+        (typeof name !== 'string' ||
+            !name.length ||
+            name.length > 80 ||
+            [...name].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127)))
+        fail('name must be 1..80 visible characters.');
+    const rawOps = r['operations'];
+    if (!Array.isArray(rawOps) || rawOps.length > MAX_PROCEDURAL_V3_OPERATIONS)
+        fail(`operations must be an array with at most ${MAX_PROCEDURAL_V3_OPERATIONS} entries.`);
+    let work = texels;
+    let expanded = 0;
+    let legacyTransientBytes = 0;
+    const operations = rawOps.map((value, i) => {
+        const path = `operations[${i}]`;
+        const op = record(value, [
+            'op',
+            'shape',
+            'rgba',
+            'opacity',
+            'alpha',
+            'invert',
+            'spec',
+            'count',
+            'seed',
+            'area',
+            'periodic',
+        ], path);
+        if (op['op'] === 'legacy-v2') {
+            record(op, ['op', 'spec', 'alpha', 'opacity'], path);
+            const legacyRecord = record(op['spec'], ['schemaVersion', 'size', 'usage', 'name', 'layers'], `${path}.spec`);
+            if (legacyRecord['schemaVersion'] !== 2)
+                fail(`${path}.spec requires explicit schemaVersion 2.`);
+            const spec = canonicalizeProceduralTextureSpecV2(legacyRecord);
+            if (spec.size !== width || spec.size !== height || spec.usage !== usage)
+                fail(`${path} legacy-v2 dimensions and usage must match the V3 surface.`);
+            work +=
+                texels *
+                    (1 +
+                        spec.layers.reduce((cost, layer) => cost + (layer.op === 'noise' ? layer.octaves * 16 : 4), 0));
+            // Count every legacy result conservatively, even if GC retains prior buffers.
+            legacyTransientBytes += texels * 4;
+            return {
+                op: 'legacy-v2',
+                spec,
+                alpha: integer(op['alpha'], 0, 255, `${path}.alpha`, 255),
+                opacity: integer(op['opacity'], 0, 255, `${path}.opacity`, 255),
+            };
+        }
+        const s = shape(op['shape'], `${path}.shape`);
+        const cost = proceduralShapeCostV3(s);
+        const [x0, y0, x1, y1] = proceduralClippedBoundsV3(s, width, height);
+        const area = Math.max(0, x1 - x0) * Math.max(0, y1 - y0);
+        if (op['op'] === 'mask') {
+            record(op, ['op', 'shape', 'alpha', 'invert'], path);
+            work += texels + area * cost;
+            return {
+                op: 'mask',
+                shape: s,
+                alpha: integer(op['alpha'], 0, 255, `${path}.alpha`, 255),
+                invert: boolean(op['invert'], `${path}.invert`),
+            };
+        }
+        if (op['op'] !== 'paint' && op['op'] !== 'stamps')
+            return fail(`${path}.op must be paint, mask, stamps or legacy-v2.`);
+        const paint = {
+            shape: s,
+            rgba: rgba(op['rgba'], `${path}.rgba`),
+            opacity: integer(op['opacity'], 0, 255, `${path}.opacity`, 255),
+        };
+        if (op['op'] === 'paint') {
+            record(op, ['op', 'shape', 'rgba', 'opacity'], path);
+            work += area * (cost + 1);
+            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 = integer(op['count'], 1, MAX_PROCEDURAL_V3_STAMPS, `${path}.count`);
+        const periodic = boolean(op['periodic'], `${path}.periodic`);
+        const [bx0, by0, bx1, by1] = proceduralShapeBoundsV3(s);
+        if (periodic && (bx1 - bx0 > width || by1 - by0 > height))
+            fail(`${path} periodic shape bounds must fit one surface period.`);
+        expanded += count * (periodic ? 9 : 1);
+        if (expanded > MAX_PROCEDURAL_V3_STAMPS)
+            fail(`expanded stamps budget exceeds ${MAX_PROCEDURAL_V3_STAMPS}.`);
+        // Conservative per-copy bounds, independent of generated positions.
+        work +=
+            count *
+                (periodic ? 9 : 1) *
+                Math.min(width, Math.ceil(bx1 - bx0) + 1) *
+                Math.min(height, Math.ceil(by1 - by0) + 1) *
+                (cost + 1);
+        return {
+            op: 'stamps',
+            ...paint,
+            count,
+            seed: integer(op['seed'], 0, 0xffffffff, `${path}.seed`),
+            area: rectangle(op['area'], `${path}.area`),
+            periodic,
+        };
+    });
+    let palette;
+    if (r['palette'] !== undefined) {
+        if (!colorUsage)
+            fail('palette and dither are supported only for color usages albedo and emissive.');
+        const p = record(r['palette'], ['colors', 'dither'], 'palette');
+        const colors = p['colors'];
+        if (!Array.isArray(colors) || colors.length < 1 || colors.length > MAX_PROCEDURAL_V3_PALETTE)
+            fail(`palette.colors requires 1..${MAX_PROCEDURAL_V3_PALETTE} entries.`);
+        const dither = p['dither'] === undefined ? 'none' : p['dither'];
+        if (dither !== 'none' && dither !== 'bayer4')
+            fail('palette.dither must be none or bayer4.');
+        palette = {
+            colors: colors.map((c, i) => integer(c, 0, 0xffffff, `palette.colors[${i}]`)),
+            dither,
+        };
+        work += texels * (colors.length + 1);
+    }
+    if (work > MAX_PROCEDURAL_V3_WORK)
+        fail(`estimated work budget ${work} exceeds ${MAX_PROCEDURAL_V3_WORK}.`);
+    if (texels * 4 + legacyTransientBytes > MAX_PROCEDURAL_V3_TRANSIENT_BYTES)
+        fail('transient allocation budget exceeded.');
+    const result = {
+        schemaVersion: 3,
+        width,
+        height,
+        usage: usage,
+        ...(name !== undefined ? { name: name } : {}),
+        background: r['background'] === undefined ? [0, 0, 0, 0] : rgba(r['background'], 'background'),
+        operations,
+        ...(palette ? { palette } : {}),
+    };
+    const canonicalJson = JSON.stringify(result);
+    if (canonicalJson.length > 262_144)
+        fail('canonical JSON byte budget exceeded.');
+    return {
+        spec: result,
+        canonicalJson,
+        estimatedWorkUnits: work,
+        conservativePixelAllocationBytes: texels * 4 + legacyTransientBytes,
+    };
+}
+export function canonicalizeProceduralTextureSpecV3(input) {
+    return admitProceduralTextureSpecV3(input).spec;
+}
+export function canonicalProceduralTextureJsonV3(input) {
+    return admitProceduralTextureSpecV3(input).canonicalJson;
+}
+export function hashProceduralTextureSpecV3(input) {
+    return `sha256:${sha256Hex(`${PROCEDURAL_TEXTURE_V3_COMPILER_ID}\n${canonicalProceduralTextureJsonV3(input)}`)}`;
+}

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

@@ -0,0 +1,12 @@
+import { PROCEDURAL_TEXTURE_V3_COMPILER_ID, type CanonicalProceduralTextureSpecV3 } from "./procedural-texture-v3-contract.js";
+export { canonicalizeProceduralTextureSpecV3, canonicalProceduralTextureJsonV3, hashProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, PROCEDURAL_TEXTURE_SPEC_VERSION_V3, MAX_PROCEDURAL_V3_EDGE, MAX_PROCEDURAL_V3_TEXELS, MAX_PROCEDURAL_V3_OPERATIONS, MAX_PROCEDURAL_V3_VERTICES, MAX_PROCEDURAL_V3_STAMPS, MAX_PROCEDURAL_V3_PALETTE, MAX_PROCEDURAL_V3_WORK, MAX_PROCEDURAL_V3_TRANSIENT_BYTES, } from "./procedural-texture-v3-contract.js";
+export type { RgbaV3, PixelPointV3, PixelRectangleV3, ProceduralShapeV3, ProceduralOperationV3, CanonicalProceduralOperationV3, ProceduralTextureSpecV3, CanonicalProceduralTextureSpecV3, } from "./procedural-texture-v3-contract.js";
+export interface CompiledProceduralTextureV3 {
+    spec: CanonicalProceduralTextureSpecV3;
+    pixels: Uint8Array;
+    canonicalJson: string;
+    recipeHash: `sha256:${string}`;
+    compilerId: typeof PROCEDURAL_TEXTURE_V3_COMPILER_ID;
+}
+/** Preflight validates all nested values and total worst-case work before allocation. */
+export declare function compileProceduralTextureSpecV3(input: unknown): CompiledProceduralTextureV3;

package/lib/procedural-texture-v3.js

@@ -0,0 +1,165 @@
+/** Deterministic binary coverage and straight RGBA source-over compiler. */
+import { compileProceduralTextureSpecV2 } from "./procedural-texture-v2-compiler.js";
+import { canonicalizeProceduralTextureSpecV3, canonicalProceduralTextureJsonV3, hashProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, proceduralClippedBoundsV3, proceduralShapeBoundsV3, } from "./procedural-texture-v3-contract.js";
+export { canonicalizeProceduralTextureSpecV3, canonicalProceduralTextureJsonV3, hashProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, PROCEDURAL_TEXTURE_SPEC_VERSION_V3, MAX_PROCEDURAL_V3_EDGE, MAX_PROCEDURAL_V3_TEXELS, MAX_PROCEDURAL_V3_OPERATIONS, MAX_PROCEDURAL_V3_VERTICES, MAX_PROCEDURAL_V3_STAMPS, MAX_PROCEDURAL_V3_PALETTE, MAX_PROCEDURAL_V3_WORK, MAX_PROCEDURAL_V3_TRANSIENT_BYTES, } from "./procedural-texture-v3-contract.js";
+const roundRatio = (numerator, denominator) => Math.floor(numerator / denominator + 0.5);
+/** Pixel centers; rectangles half-open, curved and polygon boundaries inclusive. */
+function covers(shape, x, y) {
+    const px = x + 0.5;
+    const py = y + 0.5;
+    if (shape.kind === 'rectangle')
+        return (px >= shape.x && px < shape.x + shape.width && py >= shape.y && py < shape.y + shape.height);
+    if (shape.kind === 'ellipse') {
+        const dx = 2 * px - 2 * shape.x - shape.width;
+        const dy = 2 * py - 2 * shape.y - shape.height;
+        const w2 = shape.width * shape.width;
+        const h2 = shape.height * shape.height;
+        return dx * dx * h2 + dy * dy * w2 <= w2 * h2;
+    }
+    if (shape.kind === 'line') {
+        const [ax, ay] = shape.from;
+        const dx = shape.to[0] - ax;
+        const dy = shape.to[1] - ay;
+        const vx = px - ax;
+        const vy = py - ay;
+        const length2 = dx * dx + dy * dy;
+        const dot = vx * dx + vy * dy;
+        const radius2 = (shape.width * shape.width) / 4;
+        if (dot <= 0 || length2 === 0)
+            return vx * vx + vy * vy <= radius2;
+        if (dot >= length2)
+            return (px - shape.to[0]) ** 2 + (py - shape.to[1]) ** 2 <= radius2;
+        const cross = vx * dy - vy * dx;
+        return cross * cross <= radius2 * length2;
+    }
+    let inside = false;
+    for (let i = 0, j = shape.points.length - 1; i < shape.points.length; j = i++) {
+        const [ax, ay] = shape.points[j];
+        const [bx, by] = shape.points[i];
+        const cross = (px - ax) * (by - ay) - (py - ay) * (bx - ax);
+        if (cross === 0 &&
+            px >= Math.min(ax, bx) &&
+            px <= Math.max(ax, bx) &&
+            py >= Math.min(ay, by) &&
+            py <= Math.max(ay, by))
+            return true;
+        if (ay > py !== by > py && (by > ay ? cross < 0 : cross > 0))
+            inside = !inside;
+    }
+    return inside;
+}
+/** All divisions round half-up. Stored channels are straight, not premultiplied. */
+function sourceOver(pixels, offset, rgba, opacity) {
+    const sa = roundRatio(rgba[3] * opacity, 255);
+    if (sa === 0)
+        return;
+    const da = pixels[offset + 3];
+    const alphaNumerator = sa * 255 + da * (255 - sa);
+    for (let channel = 0; channel < 3; channel++) {
+        pixels[offset + channel] = roundRatio(rgba[channel] * sa * 255 + pixels[offset + channel] * da * (255 - sa), alphaNumerator);
+    }
+    pixels[offset + 3] = roundRatio(alphaNumerator, 255);
+}
+function paint(pixels, width, height, shape, rgba, opacity, dx = 0, dy = 0) {
+    const [x0, y0, x1, y1] = proceduralClippedBoundsV3(shape, width, height, dx, dy);
+    for (let y = y0; y < y1; y++)
+        for (let x = x0; x < x1; x++) {
+            if (covers(shape, x - dx, y - dy))
+                sourceOver(pixels, (y * width + x) * 4, rgba, opacity);
+        }
+}
+const BAYER4 = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5];
+function applyPalette(pixels, width, palette) {
+    const colors = palette.colors.map((c) => [(c >>> 16) & 255, (c >>> 8) & 255, c & 255]);
+    for (let i = 0; i < pixels.length; i += 4) {
+        if (pixels[i + 3] === 0)
+            continue;
+        const index = i / 4;
+        const x = index % width;
+        const y = Math.floor(index / width);
+        const offset = palette.dither === 'bayer4' ? (2 * BAYER4[(y % 4) * 4 + (x % 4)] - 15) * 2 : 0;
+        const r = Math.max(0, Math.min(255, pixels[i] + offset));
+        const g = Math.max(0, Math.min(255, pixels[i + 1] + offset));
+        const b = Math.max(0, Math.min(255, pixels[i + 2] + offset));
+        let best = colors[0];
+        let distance = Infinity;
+        for (const color of colors) {
+            const candidate = (r - color[0]) ** 2 + (g - color[1]) ** 2 + (b - color[2]) ** 2;
+            if (candidate < distance) {
+                distance = candidate;
+                best = color;
+            }
+        }
+        pixels[i] = best[0];
+        pixels[i + 1] = best[1];
+        pixels[i + 2] = best[2];
+    }
+}
+/** Xorshift32 stream, initialized by a fixed salt; modulo chooses integer offsets. */
+function stampRandom(seed) {
+    let state = (seed ^ 0xa3c59ac3) >>> 0;
+    if (state === 0)
+        state = 0x6d2b79f5;
+    return () => {
+        state ^= state << 13;
+        state ^= state >>> 17;
+        state ^= state << 5;
+        return state >>> 0;
+    };
+}
+const wrap = (value, period) => ((value % period) + period) % period;
+/** Preflight validates all nested values and total worst-case work before allocation. */
+export function compileProceduralTextureSpecV3(input) {
+    const spec = canonicalizeProceduralTextureSpecV3(input);
+    const { width, height } = spec;
+    const pixels = new Uint8Array(width * height * 4);
+    for (let i = 0; i < pixels.length; i += 4)
+        pixels.set(spec.background, i);
+    for (const op of spec.operations) {
+        if (op.op === 'paint')
+            paint(pixels, width, height, op.shape, op.rgba, op.opacity);
+        else if (op.op === 'mask') {
+            const [x0, y0, x1, y1] = proceduralClippedBoundsV3(op.shape, width, height);
+            for (let y = 0; y < height; y++)
+                for (let x = 0; x < width; x++) {
+                    const covered = x >= x0 && x < x1 && y >= y0 && y < y1 && covers(op.shape, x, y);
+                    const alpha = covered !== op.invert ? op.alpha : 0;
+                    const offset = (y * width + x) * 4;
+                    pixels[offset + 3] = roundRatio(pixels[offset + 3] * alpha, 255);
+                    if (pixels[offset + 3] === 0)
+                        pixels.fill(0, offset, offset + 3);
+                }
+        }
+        else if (op.op === 'legacy-v2') {
+            const legacy = compileProceduralTextureSpecV2(op.spec).pixels;
+            for (let i = 0; i < pixels.length; i += 4)
+                sourceOver(pixels, i, [legacy[i], legacy[i + 1], legacy[i + 2], op.alpha], op.opacity);
+        }
+        else {
+            const random = stampRandom(op.seed);
+            const [bx0, by0] = proceduralShapeBoundsV3(op.shape);
+            for (let stamp = 0; stamp < op.count; stamp++) {
+                let dx = op.area.x + (random() % op.area.width);
+                let dy = op.area.y + (random() % op.area.height);
+                if (!op.periodic)
+                    paint(pixels, width, height, op.shape, op.rgba, op.opacity, dx, dy);
+                else {
+                    dx = wrap(dx + bx0, width) - bx0;
+                    dy = wrap(dy + by0, height) - by0;
+                    for (const oy of [-height, 0, height])
+                        for (const ox of [-width, 0, width])
+                            paint(pixels, width, height, op.shape, op.rgba, op.opacity, dx + ox, dy + oy);
+                }
+            }
+        }
+    }
+    if (spec.palette)
+        applyPalette(pixels, width, spec.palette);
+    return {
+        spec,
+        pixels,
+        canonicalJson: canonicalProceduralTextureJsonV3(spec),
+        recipeHash: hashProceduralTextureSpecV3(spec),
+        compilerId: PROCEDURAL_TEXTURE_V3_COMPILER_ID,
+    };
+}

package/lib/procedural-texture.d.ts

@@ -37,38 +37,16 @@
  * still catches.
  */
 import * as THREE from 'three';
-import { type CanonicalProceduralTextureSpecV2, type ProceduralTextureSpec } from "./procedural-material-v2.js";
+import type { ProceduralTextureSpecV3 } from "./procedural-texture-v3.js";
+import { type ProceduralTextureSpec as LegacyProceduralTextureSpec } from "./procedural-material-v2.js";
 export { MAX_NOISE_OCTAVES, MAX_PORTABLE_MATERIAL_TEXELS, MAX_PORTABLE_MATERIAL_TEXTURES, MAX_PROCEDURAL_LAYERS, MAX_PROCEDURAL_NAME_LENGTH, MAX_PROCEDURAL_PATTERN_COUNT, MAX_PROCEDURAL_SIZE, MIN_PROCEDURAL_SIZE, PORTABLE_MATERIAL_SPEC_VERSION, PROCEDURAL_TEXTURE_SPEC_VERSION, ProceduralTextureError, canonicalProceduralTextureJsonV2, canonicalizePortableMaterialSpecV2, canonicalizeProceduralTextureSpecV2, hashProceduralTextureSpecV2, migrateProceduralTextureSpecV1, } from "./procedural-material-v2.js";
-export type { CanonicalPortableMaterialSpecV2, CanonicalPortableTextureRefV2, CanonicalProceduralLayerV2, CanonicalProceduralTextureSpecV2, PortableMaterialSpecV2, PortableTextureRefV2, ProceduralBlend, ProceduralLayer, ProceduralTextureSpec, ProceduralTextureSpecV1, ProceduralTextureSpecV2, } from "./procedural-material-v2.js";
-/**
- * Build a tiling texture from a bounded, deterministic layer stack.
- *
- * The result is a plain RGBA `DataTexture`; `renderSceneToGLB` bakes it to PNG
- * and embeds it, so nothing else has to be done to ship it.
- *
- * @example
- * const bark = proceduralTexture({
- *   schemaVersion: 2,
- *   size: 256,
- *   usage: 'albedo',
- *   name: 'Bark',
- *   layers: [
- *     { op: 'solid', color: 0x5a4632 },
- *     { op: 'noise', colorA: 0x3d2f21, colorB: 0x7a6248, scale: 6, octaves: 4, blend: 'overlay' },
- *     { op: 'stripes', colorA: 0x000000, colorB: 0xffffff, count: 24, angleDeg: 90,
- *       blend: 'multiply', opacity: 0.15 },
- *   ],
- * });
- * const trunk = createPart('Trunk', cylinderGeo(0.3, 0.3, 3), pbrMaterial({ albedo: bark }), { parent: root });
- */
-export interface CompiledProceduralTextureV2 {
-    spec: CanonicalProceduralTextureSpecV2;
-    pixels: Uint8Array;
-    canonicalJson: string;
-    recipeHash: `sha256:${string}`;
-}
-/** Validate, canonicalize, and compile one texture without constructing Three.js state. */
-export declare function compileProceduralTextureSpecV2(input: unknown): CompiledProceduralTextureV2;
+export type { CanonicalPortableMaterialSpecV2, CanonicalPortableTextureRefV2, CanonicalProceduralLayerV2, CanonicalProceduralTextureSpecV2, PortableMaterialSpecV2, PortableTextureRefV2, ProceduralBlend, ProceduralLayer, ProceduralTextureSpecV1, ProceduralTextureSpecV2, } from "./procedural-material-v2.js";
+export * from "./procedural-texture-v3.js";
+export type ProceduralTextureSpec = LegacyProceduralTextureSpec | ProceduralTextureSpecV3;
+/** Dispatch never invokes an input accessor; absent/undefined retains V1 compatibility. */
+export declare function proceduralTextureSchemaVersion(input: unknown): 1 | 2 | 3;
+export { compileProceduralTextureSpecV2 } from "./procedural-texture-v2-compiler.js";
+export type { CompiledProceduralTextureV2 } from "./procedural-texture-v2-compiler.js";
 export declare function proceduralTexture(spec: ProceduralTextureSpec): THREE.DataTexture;
 /**
  * Derive a tangent-space normal map from the luminance of another texture.