@aelionsdk/material-sdk 0.1.0-beta.1

package/dist/graph-builder.d.ts

@@ -0,0 +1,45 @@
+import type { JsonValue } from '@aelionsdk/core';
+import type { GraphBinding, MaterialGraph } from '@aelionsdk/material-compiler';
+export type GraphValueType = 'float' | 'enum' | 'visual-frame';
+export interface GraphValue<T extends GraphValueType> {
+    readonly type: T;
+    readonly binding: GraphBinding;
+}
+export type FloatValue = GraphValue<'float'>;
+export type EnumValue = GraphValue<'enum'>;
+export type VisualFrameValue = GraphValue<'visual-frame'>;
+export declare class MaterialGraphBuilder {
+    #private;
+    literal(number: number): FloatValue;
+    enum(value_: string): EnumValue;
+    parameterFloat(id: string): FloatValue;
+    parameterEnum(id: string): EnumValue;
+    inputFrame(id: string): VisualFrameValue;
+    resource(id: string): GraphValue<'visual-frame'>;
+    systemFloat(id: 'sequenceTimeUs' | 'itemTimeUs' | 'itemDurationUs' | 'normalizedItemTime' | 'transitionProgress' | 'frameIndex' | 'frameDurationUs' | 'qualityScale' | 'randomSeed'): FloatValue;
+    transitionCurve(id: string, progress: FloatValue, curve: EnumValue): FloatValue;
+    mix(id: string, a: VisualFrameValue, b: VisualFrameValue, amount: FloatValue): VisualFrameValue;
+    temperature(id: string, source: VisualFrameValue, amount: FloatValue): VisualFrameValue;
+    liftBlack(id: string, source: VisualFrameValue, amount: FloatValue): VisualFrameValue;
+    extractHighlights(id: string, source: VisualFrameValue, threshold: FloatValue): VisualFrameValue;
+    gaussianBlur(id: string, source: VisualFrameValue, radiusPx: FloatValue): VisualFrameValue;
+    scaleRgb(id: string, source: VisualFrameValue, scale: FloatValue): VisualFrameValue;
+    screen(id: string, base: VisualFrameValue, overlay: VisualFrameValue): VisualFrameValue;
+    multiplyFrames(id: string, base: VisualFrameValue, overlay: VisualFrameValue): VisualFrameValue;
+    addFrames(id: string, base: VisualFrameValue, overlay: VisualFrameValue): VisualFrameValue;
+    exposure(id: string, source: VisualFrameValue, stops: FloatValue): VisualFrameValue;
+    contrast(id: string, source: VisualFrameValue, amount: FloatValue): VisualFrameValue;
+    saturation(id: string, source: VisualFrameValue, amount: FloatValue): VisualFrameValue;
+    invert(id: string, source: VisualFrameValue): VisualFrameValue;
+    add(id: string, a: FloatValue, b: FloatValue): FloatValue;
+    subtract(id: string, a: FloatValue, b: FloatValue): FloatValue;
+    multiply(id: string, a: FloatValue, b: FloatValue): FloatValue;
+    divide(id: string, a: FloatValue, b: FloatValue): FloatValue;
+    clamp(id: string, input: FloatValue, min: FloatValue, max: FloatValue): FloatValue;
+    smoothstep(id: string, edge0: FloatValue, edge1: FloatValue, x: FloatValue): FloatValue;
+    output(id: string, frame: VisualFrameValue): this;
+    build(): MaterialGraph;
+}
+export declare function materialGraph(build: (graph: MaterialGraphBuilder) => void): MaterialGraph;
+export type MaterialGraphLiteral = JsonValue;
+//# sourceMappingURL=graph-builder.d.ts.map

package/dist/graph-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-builder.d.ts","sourceRoot":"","sources":["../src/graph-builder.ts"],"names":[],"mappings":"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"}

package/dist/graph-builder.js

@@ -0,0 +1,125 @@
+import { MATERIAL_GRAPH_SCHEMA, MATERIAL_NODE_SET } from './types.js';
+function value(type, binding) {
+    return { type, binding };
+}
+export class MaterialGraphBuilder {
+    #nodes = [];
+    #ids = new Set();
+    #outputs = {};
+    literal(number) {
+        if (!Number.isFinite(number))
+            throw new TypeError('Graph literals must be finite');
+        return value('float', { value: number });
+    }
+    enum(value_) {
+        return value('enum', { value: value_ });
+    }
+    parameterFloat(id) {
+        return value('float', { parameter: id });
+    }
+    parameterEnum(id) {
+        return value('enum', { parameter: id });
+    }
+    inputFrame(id) {
+        return value('visual-frame', { inputPort: id });
+    }
+    resource(id) {
+        return value('visual-frame', { resource: id });
+    }
+    systemFloat(id) {
+        return value('float', { system: id });
+    }
+    #node(id, type, inputs, output, outputType) {
+        if (this.#ids.has(id))
+            throw new TypeError(`Duplicate Material Graph node ${id}`);
+        this.#ids.add(id);
+        this.#nodes.push({
+            id,
+            type,
+            typeVersion: '1.0.0',
+            inputs: Object.fromEntries(Object.entries(inputs).map(([name, input]) => [name, input.binding])),
+        });
+        return value(outputType, { node: id, output });
+    }
+    transitionCurve(id, progress, curve) {
+        return this.#node(id, 'time.transition-curve', { progress, curve }, 'value', 'float');
+    }
+    mix(id, a, b, amount) {
+        return this.#node(id, 'composite.mix', { a, b, amount }, 'frame', 'visual-frame');
+    }
+    temperature(id, source, amount) {
+        return this.#node(id, 'color.temperature', { source, amount }, 'frame', 'visual-frame');
+    }
+    liftBlack(id, source, amount) {
+        return this.#node(id, 'color.lift-black', { source, amount }, 'frame', 'visual-frame');
+    }
+    extractHighlights(id, source, threshold) {
+        return this.#node(id, 'color.extract-highlights', { source, threshold }, 'frame', 'visual-frame');
+    }
+    gaussianBlur(id, source, radiusPx) {
+        return this.#node(id, 'blur.gaussian', { source, radiusPx }, 'frame', 'visual-frame');
+    }
+    scaleRgb(id, source, scale) {
+        return this.#node(id, 'color.scale-rgb', { source, scale }, 'frame', 'visual-frame');
+    }
+    screen(id, base, overlay) {
+        return this.#node(id, 'composite.screen', { base, overlay }, 'frame', 'visual-frame');
+    }
+    multiplyFrames(id, base, overlay) {
+        return this.#node(id, 'composite.multiply', { base, overlay }, 'frame', 'visual-frame');
+    }
+    addFrames(id, base, overlay) {
+        return this.#node(id, 'composite.add', { base, overlay }, 'frame', 'visual-frame');
+    }
+    exposure(id, source, stops) {
+        return this.#node(id, 'color.exposure', { source, stops }, 'frame', 'visual-frame');
+    }
+    contrast(id, source, amount) {
+        return this.#node(id, 'color.contrast', { source, amount }, 'frame', 'visual-frame');
+    }
+    saturation(id, source, amount) {
+        return this.#node(id, 'color.saturation', { source, amount }, 'frame', 'visual-frame');
+    }
+    invert(id, source) {
+        return this.#node(id, 'color.invert', { source }, 'frame', 'visual-frame');
+    }
+    add(id, a, b) {
+        return this.#node(id, 'math.add', { a, b }, 'value', 'float');
+    }
+    subtract(id, a, b) {
+        return this.#node(id, 'math.subtract', { a, b }, 'value', 'float');
+    }
+    multiply(id, a, b) {
+        return this.#node(id, 'math.multiply', { a, b }, 'value', 'float');
+    }
+    divide(id, a, b) {
+        return this.#node(id, 'math.divide', { a, b }, 'value', 'float');
+    }
+    clamp(id, input, min, max) {
+        return this.#node(id, 'math.clamp', { value: input, min, max }, 'value', 'float');
+    }
+    smoothstep(id, edge0, edge1, x) {
+        return this.#node(id, 'math.smoothstep', { edge0, edge1, x }, 'value', 'float');
+    }
+    output(id, frame) {
+        if (!('node' in frame.binding)) {
+            throw new TypeError('A Material Graph output must reference a node output');
+        }
+        this.#outputs[id] = { node: frame.binding.node, output: frame.binding.output };
+        return this;
+    }
+    build() {
+        return {
+            $schema: MATERIAL_GRAPH_SCHEMA,
+            graphVersion: '1.0.0',
+            nodeSet: MATERIAL_NODE_SET,
+            nodes: this.#nodes.map(node => ({ ...node, inputs: { ...node.inputs } })),
+            outputs: { ...this.#outputs },
+        };
+    }
+}
+export function materialGraph(build) {
+    const builder = new MaterialGraphBuilder();
+    build(builder);
+    return builder.build();
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './canonical.js';
+export * from './catalog.js';
+export * from './composition.js';
+export * from './definition-builder.js';
+export * from './graph-builder.js';
+export * from './lab.js';
+export * from './migration.js';
+export { decodeMaterialJson, packMaterialPackage, verifyMaterialPackage } from './package.js';
+export * from './package-limits.js';
+export * from './registry.js';
+export * from './security.js';
+export * from './types.js';
+export * from './validation.js';
+export * from './zip.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9F,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export * from './canonical.js';
+export * from './catalog.js';
+export * from './composition.js';
+export * from './definition-builder.js';
+export * from './graph-builder.js';
+export * from './lab.js';
+export * from './migration.js';
+export { decodeMaterialJson, packMaterialPackage, verifyMaterialPackage } from './package.js';
+export * from './package-limits.js';
+export * from './registry.js';
+export * from './security.js';
+export * from './types.js';
+export * from './validation.js';
+export * from './zip.js';

package/dist/lab.d.ts

@@ -0,0 +1,48 @@
+import type { Diagnostic, JsonValue } from '@aelionsdk/core';
+import { type CompileMaterialOptions, type MaterialExecutionPlan } from '@aelionsdk/material-compiler';
+import type { AuthoredMaterial, MaterialPackageFile, MaterialPackageMetadata, PackedMaterialPackage } from './types.js';
+export interface MaterialLabBudgetReport {
+    readonly nodes: number;
+    readonly depth: number;
+    readonly passes: number;
+    readonly textureSamples: number;
+    readonly intermediateTextures: number;
+}
+export interface MaterialLabBackendReport {
+    readonly available: boolean;
+    readonly graphHash?: string;
+    readonly executionPlan?: MaterialExecutionPlan;
+    readonly error?: string;
+}
+export interface MaterialLabReport {
+    readonly timeUs: number;
+    readonly parameters: Readonly<Record<string, JsonValue>>;
+    readonly inputs: Readonly<Record<string, JsonValue>>;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly budget: MaterialLabBudgetReport;
+    readonly webgl2: MaterialLabBackendReport;
+    readonly webgpu: MaterialLabBackendReport;
+    readonly gpuTimingsUs: readonly number[];
+}
+export interface MaterialGoldenDiff {
+    readonly passed: boolean;
+    readonly comparedValues: number;
+    readonly differingValues: number;
+    readonly maximumError: number;
+    readonly meanError: number;
+}
+/** Headless Material Lab model shared by UI, CI and package authoring tools. */
+export declare class MaterialLabSession {
+    #private;
+    constructor(authored: AuthoredMaterial);
+    setTime(timeUs: number): void;
+    setParameter(id: string, value: JsonValue): void;
+    setInput(id: string, descriptor: JsonValue): void;
+    recordGpuTiming(totalUs: number): void;
+    analyze(options?: {
+        readonly budget?: CompileMaterialOptions['budget'];
+    }): MaterialLabReport;
+    exportPackage(metadata: MaterialPackageMetadata, files?: readonly MaterialPackageFile[]): Promise<PackedMaterialPackage>;
+}
+export declare function compareMaterialGolden(actual: Uint8Array | Uint8ClampedArray, expected: Uint8Array | Uint8ClampedArray, tolerance?: number): MaterialGoldenDiff;
+//# sourceMappingURL=lab.d.ts.map

package/dist/lab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lab.d.ts","sourceRoot":"","sources":["../src/lab.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAiED,gFAAgF;AAChF,qBAAa,kBAAkB;;gBAOV,QAAQ,EAAE,gBAAgB;IAUtC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM7B,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAgBhD,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,GAAG,IAAI;IAQjD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMtC,OAAO,CACZ,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAA;KAAO,GACnE,iBAAiB;IAyCb,aAAa,CAClB,QAAQ,EAAE,uBAAuB,EACjC,KAAK,GAAE,SAAS,mBAAmB,EAAO,GACzC,OAAO,CAAC,qBAAqB,CAAC;CAGlC;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,UAAU,GAAG,iBAAiB,EACtC,QAAQ,EAAE,UAAU,GAAG,iBAAiB,EACxC,SAAS,SAAI,GACZ,kBAAkB,CAqBpB"}

package/dist/lab.js

@@ -0,0 +1,169 @@
+import { compileMaterialGraph, compileMaterialGraphToWebGl2, compileMaterialGraphToWebGpu, } from '@aelionsdk/material-compiler';
+import { packMaterialPackage } from './package.js';
+import { validateAuthoredMaterial } from './validation.js';
+function compilerType(type) {
+    return ['float', 'integer', 'angle', 'duration'].includes(type)
+        ? 'float'
+        : type === 'enum'
+            ? 'enum'
+            : undefined;
+}
+function compileOptions(authored) {
+    return {
+        parameters: Object.fromEntries(authored.definition.parameters.flatMap(parameter => {
+            const type = compilerType(parameter.type);
+            return type === undefined ? [] : [[parameter.id, type]];
+        })),
+        inputPorts: Object.fromEntries(authored.definition.ports
+            .filter(port => port.direction === 'input' && port.type === 'visual-frame')
+            .map(port => [port.id, 'visual-frame'])),
+        systems: {
+            sequenceTimeUs: 'float',
+            itemTimeUs: 'float',
+            itemDurationUs: 'float',
+            normalizedItemTime: 'float',
+            transitionProgress: 'float',
+            frameIndex: 'float',
+            frameDurationUs: 'float',
+            qualityScale: 'float',
+            randomSeed: 'float',
+        },
+        specializationValues: Object.fromEntries(authored.definition.parameters
+            .filter(parameter => parameter.affects === 'specialization')
+            .map(parameter => [parameter.id, parameter.default])),
+    };
+}
+function backendReport(operation) {
+    try {
+        const value = operation();
+        return { available: true, graphHash: value.graphHash, executionPlan: value.executionPlan };
+    }
+    catch (error) {
+        return { available: false, error: error instanceof Error ? error.message : 'Backend failed' };
+    }
+}
+function validParameterValue(type, value) {
+    if (type === 'boolean')
+        return typeof value === 'boolean';
+    if (['integer', 'duration'].includes(type))
+        return typeof value === 'number' && Number.isSafeInteger(value);
+    if (['float', 'angle'].includes(type))
+        return typeof value === 'number' && Number.isFinite(value);
+    if (type === 'enum' || type === 'string')
+        return typeof value === 'string';
+    return value !== null;
+}
+/** Headless Material Lab model shared by UI, CI and package authoring tools. */
+export class MaterialLabSession {
+    #authored;
+    #parameters;
+    #inputs = {};
+    #gpuTimingsUs = [];
+    #timeUs = 0;
+    constructor(authored) {
+        this.#authored = structuredClone(authored);
+        this.#parameters = Object.fromEntries(authored.definition.parameters.map(parameter => [
+            parameter.id,
+            structuredClone(parameter.default),
+        ]));
+    }
+    setTime(timeUs) {
+        if (!Number.isSafeInteger(timeUs) || timeUs < 0)
+            throw new RangeError('MATERIAL_LAB_TIME_INVALID');
+        this.#timeUs = timeUs;
+    }
+    setParameter(id, value) {
+        const definition = this.#authored.definition.parameters.find(parameter => parameter.id === id);
+        if (definition === undefined)
+            throw new ReferenceError(`MATERIAL_LAB_PARAMETER_MISSING: ${id}`);
+        if (!validParameterValue(definition.type, value)) {
+            throw new TypeError(`MATERIAL_LAB_PARAMETER_TYPE_INVALID: ${id}`);
+        }
+        if (typeof value === 'number' &&
+            ((definition.range?.min !== undefined && value < definition.range.min) ||
+                (definition.range?.max !== undefined && value > definition.range.max))) {
+            throw new RangeError(`MATERIAL_LAB_PARAMETER_RANGE_INVALID: ${id}`);
+        }
+        this.#parameters[id] = structuredClone(value);
+    }
+    setInput(id, descriptor) {
+        const port = this.#authored.definition.ports.find(value => value.id === id && value.direction === 'input');
+        if (port === undefined)
+            throw new ReferenceError(`MATERIAL_LAB_INPUT_MISSING: ${id}`);
+        this.#inputs[id] = structuredClone(descriptor);
+    }
+    recordGpuTiming(totalUs) {
+        if (!Number.isSafeInteger(totalUs) || totalUs < 0)
+            throw new RangeError('GPU_TIMING_INVALID');
+        this.#gpuTimingsUs.push(totalUs);
+        if (this.#gpuTimingsUs.length > 256)
+            this.#gpuTimingsUs.shift();
+    }
+    analyze(options = {}) {
+        const validation = validateAuthoredMaterial(this.#authored, options);
+        const graph = this.#authored.graph;
+        if (graph === undefined) {
+            return {
+                timeUs: this.#timeUs,
+                parameters: structuredClone(this.#parameters),
+                inputs: structuredClone(this.#inputs),
+                diagnostics: validation.diagnostics,
+                budget: { nodes: 0, depth: 0, passes: 0, textureSamples: 0, intermediateTextures: 0 },
+                webgl2: { available: false, error: 'Material has no graph implementation' },
+                webgpu: { available: false, error: 'Material has no graph implementation' },
+                gpuTimingsUs: [...this.#gpuTimingsUs],
+            };
+        }
+        const compile = {
+            ...compileOptions(this.#authored),
+            ...(options.budget === undefined ? {} : { budget: options.budget }),
+        };
+        const analysis = compileMaterialGraph(graph, compile);
+        const webgl2 = backendReport(() => compileMaterialGraphToWebGl2(graph, compile));
+        const webgpu = backendReport(() => compileMaterialGraphToWebGpu(graph, compile));
+        const plan = webgl2.executionPlan ?? webgpu.executionPlan;
+        return {
+            timeUs: this.#timeUs,
+            parameters: structuredClone(this.#parameters),
+            inputs: structuredClone(this.#inputs),
+            diagnostics: [...validation.diagnostics, ...analysis.diagnostics],
+            budget: {
+                nodes: analysis.order.length,
+                depth: analysis.depth,
+                passes: plan?.passes.length ?? analysis.estimatedPasses,
+                textureSamples: analysis.estimatedTextureSamples,
+                intermediateTextures: plan?.intermediateTextureCount ?? 0,
+            },
+            webgl2,
+            webgpu,
+            gpuTimingsUs: [...this.#gpuTimingsUs],
+        };
+    }
+    exportPackage(metadata, files = []) {
+        return packMaterialPackage({ metadata, materials: [this.#authored], files });
+    }
+}
+export function compareMaterialGolden(actual, expected, tolerance = 2) {
+    if (actual.length !== expected.length)
+        throw new RangeError('MATERIAL_GOLDEN_SIZE_MISMATCH');
+    if (!Number.isSafeInteger(tolerance) || tolerance < 0 || tolerance > 255) {
+        throw new RangeError('MATERIAL_GOLDEN_TOLERANCE_INVALID');
+    }
+    let differingValues = 0;
+    let maximumError = 0;
+    let totalError = 0;
+    for (let index = 0; index < actual.length; index++) {
+        const error = Math.abs((actual[index] ?? 0) - (expected[index] ?? 0));
+        if (error > tolerance)
+            differingValues++;
+        maximumError = Math.max(maximumError, error);
+        totalError += error;
+    }
+    return {
+        passed: differingValues === 0,
+        comparedValues: actual.length,
+        differingValues,
+        maximumError,
+        meanError: actual.length === 0 ? 0 : totalError / actual.length,
+    };
+}

package/dist/migration.d.ts

@@ -0,0 +1,22 @@
+import type { JsonValue } from '@aelionsdk/core';
+export type MaterialMigrationDomain = 'protocol' | 'package' | 'definition' | 'node-set';
+export interface MaterialMigration {
+    readonly id: string;
+    readonly domain: MaterialMigrationDomain;
+    readonly from: string;
+    readonly to: string;
+    migrate(value: JsonValue): JsonValue;
+}
+export interface MaterialMigrationReport {
+    readonly domain: MaterialMigrationDomain;
+    readonly from: string;
+    readonly to: string;
+    readonly migrationIds: readonly string[];
+    readonly value: JsonValue;
+}
+export declare class MaterialMigrationRegistry {
+    #private;
+    register(migration: MaterialMigration): void;
+    migrate(domain: MaterialMigrationDomain, from: string, to: string, input: JsonValue): MaterialMigrationReport;
+}
+//# sourceMappingURL=migration.d.ts.map

package/dist/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,uBAAuB,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,CAAC;AAEzF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAQD,qBAAa,yBAAyB;;IAG7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAQ5C,OAAO,CACZ,MAAM,EAAE,uBAAuB,EAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,SAAS,GACf,uBAAuB;CAiD3B"}

package/dist/migration.js

@@ -0,0 +1,59 @@
+import { canonicalMaterialBytes } from './canonical.js';
+function equalBytes(left, right) {
+    return (left.byteLength === right.byteLength && left.every((value, index) => value === right[index]));
+}
+export class MaterialMigrationRegistry {
+    #migrations = new Map();
+    register(migration) {
+        const key = this.#key(migration.domain, migration.from, migration.to);
+        if (migration.id.length === 0 || migration.from === migration.to || this.#migrations.has(key)) {
+            throw new TypeError('MATERIAL_MIGRATION_INVALID');
+        }
+        this.#migrations.set(key, migration);
+    }
+    migrate(domain, from, to, input) {
+        if (from === to) {
+            return { domain, from, to, migrationIds: [], value: structuredClone(input) };
+        }
+        const path = this.#path(domain, from, to);
+        if (path === undefined)
+            throw new ReferenceError(`MATERIAL_MIGRATION_MISSING: ${from} -> ${to}`);
+        let value = structuredClone(input);
+        for (const migration of path) {
+            const first = migration.migrate(structuredClone(value));
+            const second = migration.migrate(structuredClone(value));
+            if (!equalBytes(canonicalMaterialBytes(first), canonicalMaterialBytes(second))) {
+                throw new TypeError(`MATERIAL_MIGRATION_NON_DETERMINISTIC: ${migration.id}`);
+            }
+            value = structuredClone(first);
+        }
+        return { domain, from, to, migrationIds: path.map(value => value.id), value };
+    }
+    #path(domain, from, to) {
+        const queue = [
+            { version: from, path: [] },
+        ];
+        const visited = new Set([from]);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current === undefined)
+                break;
+            const next = [...this.#migrations.values()]
+                .filter(value => value.domain === domain && value.from === current.version)
+                .sort((left, right) => left.id.localeCompare(right.id));
+            for (const migration of next) {
+                const path = [...current.path, migration];
+                if (migration.to === to)
+                    return path;
+                if (!visited.has(migration.to)) {
+                    visited.add(migration.to);
+                    queue.push({ version: migration.to, path });
+                }
+            }
+        }
+        return undefined;
+    }
+    #key(domain, from, to) {
+        return `${domain}\0${from}\0${to}`;
+    }
+}

package/dist/package-limits.d.ts

@@ -0,0 +1,30 @@
+import type { MaterialPackageByteLimitOptions, MaterialPackageByteLimits, PackedMaterialPackage } from './types.js';
+export declare const MATERIAL_PACKAGE_MAX_FILES = 256;
+export declare const MATERIAL_PACKAGE_MAX_FILE_BYTES: number;
+export declare const MATERIAL_PACKAGE_MAX_MANIFEST_BYTES: number;
+export declare const MATERIAL_PACKAGE_MAX_BYTES: number;
+export declare const MATERIAL_PACKAGE_MAX_ARCHIVE_BYTES: number;
+export declare const DEFAULT_MATERIAL_PACKAGE_BYTE_LIMITS: MaterialPackageByteLimits;
+export interface InspectedMaterialPackageFile {
+    readonly path: string;
+    readonly data: Uint8Array;
+    readonly byteLength: number;
+}
+export interface MaterialPackageTransportInspection {
+    readonly limits: MaterialPackageByteLimits;
+    readonly integrity: PackedMaterialPackage['integrity'];
+    readonly manifestBytes: Uint8Array;
+    readonly manifestByteLength: number;
+    readonly archiveBytes: Uint8Array;
+    readonly archiveByteLength: number;
+    readonly files: readonly InspectedMaterialPackageFile[];
+    readonly packageBytes: number;
+}
+export declare function materialPackageBudgetExceeded(scope: string, actual: number, limit: number): never;
+export declare function resolveMaterialPackageByteLimits(options?: MaterialPackageByteLimitOptions): MaterialPackageByteLimits;
+export declare function addMaterialPackageBytes(total: number, value: number, scope: string): number;
+export declare function materialUint8ArrayByteLength(value: unknown, scope: string): number;
+export declare function copyMaterialBytes(value: Uint8Array, expectedByteLength: number, scope: string): Uint8Array;
+export declare function validMaterialPackagePath(path: unknown): path is string;
+export declare function inspectPackedMaterialPackage(packed: PackedMaterialPackage, options?: MaterialPackageByteLimitOptions): MaterialPackageTransportInspection;
+//# sourceMappingURL=package-limits.d.ts.map

package/dist/package-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-limits.d.ts","sourceRoot":"","sources":["../src/package-limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,+BAA+B,QAAmB,CAAC;AAChE,eAAO,MAAM,mCAAmC,QAAa,CAAC;AAC9D,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAC3D,eAAO,MAAM,kCAAkC,QAAmB,CAAC;AA+BnE,eAAO,MAAM,oCAAoC,EAAE,yBAMjD,CAAC;AAEH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAoBD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAIjG;AAWD,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,+BAAoC,GAC5C,yBAAyB,CA4B3B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAalF;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,kBAAkB,EAAE,MAAM,EAC1B,KAAK,EAAE,MAAM,GACZ,UAAU,CAUZ;AAmCD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAWtE;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,qBAAqB,EAC7B,OAAO,GAAE,+BAAoC,GAC5C,kCAAkC,CAoDpC"}