@aelionsdk/sdk 0.1.0-beta.1

package/dist/media-provider.js

@@ -0,0 +1,388 @@
+import { AelionError } from '@aelionsdk/core';
+import { createSampleIndex, createVideoFrameDecodeSessionFromReader, decodeAudioPcmRange, MemoryRangeReader, } from '@aelionsdk/media';
+function positiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+function nonNegativeSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function errorReason(value, fallback) {
+    return value instanceof Error ? value : new Error(fallback, { cause: value });
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error
+        ? signal.reason
+        : new DOMException('Operation aborted', 'AbortError');
+}
+function settleShared(operation, result) {
+    if (operation.settled)
+        return;
+    operation.settled = true;
+    const subscribers = [...operation.subscribers.values()];
+    operation.subscribers.clear();
+    for (const subscriber of subscribers) {
+        subscriber.signal?.removeEventListener('abort', subscriber.onAbort);
+        if (result.ok)
+            subscriber.resolve(result.value);
+        else
+            subscriber.reject(result.error);
+    }
+}
+function observeShared(operation, promise, failureMessage, onSettled) {
+    void promise.then(value => {
+        try {
+            settleShared(operation, { ok: true, value });
+        }
+        finally {
+            onSettled();
+        }
+    }, (error) => {
+        try {
+            settleShared(operation, {
+                ok: false,
+                error: errorReason(error, failureMessage),
+            });
+        }
+        finally {
+            onSettled();
+        }
+    });
+}
+function awaitShared(operation, signal) {
+    if (signal?.aborted === true)
+        return Promise.reject(abortReason(signal));
+    if (operation.settled)
+        return Promise.reject(new Error('Shared operation already settled'));
+    return new Promise((resolve, reject) => {
+        const token = Symbol('media-subscriber');
+        const onAbort = () => {
+            if (!operation.subscribers.delete(token))
+                return;
+            signal?.removeEventListener('abort', onAbort);
+            if (signal !== undefined)
+                reject(abortReason(signal));
+            if (operation.subscribers.size === 0 && !operation.settled) {
+                operation.controller.abort(new DOMException('Shared media operation has no active callers', 'AbortError'));
+            }
+        };
+        operation.subscribers.set(token, {
+            resolve,
+            reject,
+            ...(signal === undefined ? {} : { signal }),
+            onAbort,
+        });
+        signal?.addEventListener('abort', onAbort, { once: true });
+        // Covers unusual AbortSignal implementations that become aborted while a
+        // listener is being installed.
+        if (signal?.aborted === true)
+            onAbort();
+    });
+}
+/**
+ * Convenience provider for small Alpha projects. It keeps a bounded LRU of
+ * immutable asset bytes and reuses SampleIndex across exact seeks. Large/CDN
+ * integrations should provide their own Range-backed AelionMediaProvider.
+ */
+export class ByteMediaProvider {
+    #resolve;
+    #maxCachedBytes;
+    #maxConcurrentOperations;
+    #maxPendingOperations;
+    #maxInFlightRequests;
+    #cache = new Map();
+    #loads = new Map();
+    #assetLoadOperations = new Set();
+    #indexOperations = new Set();
+    #operationWaiters = [];
+    #cachedBytes = 0;
+    #activeOperations = 0;
+    #inFlightRequests = 0;
+    #generation = 0;
+    constructor(options) {
+        this.#resolve = options.resolveAssetBytes;
+        this.#maxCachedBytes = positiveSafeInteger(options.maxCachedBytes ?? 64 * 1_024 * 1_024, 'maxCachedBytes');
+        if (options.maxConcurrentOperations !== undefined &&
+            options.maxConcurrentLoads !== undefined &&
+            options.maxConcurrentOperations !== options.maxConcurrentLoads) {
+            throw new RangeError('maxConcurrentOperations and maxConcurrentLoads must match');
+        }
+        this.#maxConcurrentOperations = positiveSafeInteger(options.maxConcurrentOperations ?? options.maxConcurrentLoads ?? 4, 'maxConcurrentOperations');
+        this.#maxPendingOperations = nonNegativeSafeInteger(options.maxPendingOperations ?? 64, 'maxPendingOperations');
+        this.#maxInFlightRequests = this.#maxConcurrentOperations + this.#maxPendingOperations;
+        if (!Number.isSafeInteger(this.#maxInFlightRequests)) {
+            throw new RangeError('maxConcurrentOperations + maxPendingOperations must be a safe integer');
+        }
+    }
+    async frameAt(assetId, streamIndex, sourceTimeUs, signal) {
+        this.#admitRequest(signal);
+        try {
+            const cached = await this.#asset(assetId, signal);
+            const index = await this.#sampleIndex(cached, signal);
+            cached.videoSessions ??= new Map();
+            let session = cached.videoSessions.get(streamIndex);
+            if (session === undefined) {
+                session = createVideoFrameDecodeSessionFromReader(new MemoryRangeReader(`${assetId}:video:${streamIndex.toString()}`, cached.bytes), index, {
+                    streamIndex,
+                    maxCachedFrames: 8,
+                    maxCachedBytes: 96 * 1_024 * 1_024,
+                });
+                cached.videoSessions.set(streamIndex, session);
+            }
+            const decoded = await this.#runBounded(signal, () => session.frameAt(sourceTimeUs, signal));
+            try {
+                if (signal?.aborted === true)
+                    throw abortReason(signal);
+                return decoded.frame.clone();
+            }
+            finally {
+                decoded.close();
+            }
+        }
+        finally {
+            this.#releaseRequest();
+        }
+    }
+    async pcmRange(assetId, streamIndex, startUs, durationUs, signal) {
+        this.#admitRequest(signal);
+        try {
+            const cached = await this.#asset(assetId, signal);
+            const block = await this.#runBounded(signal, () => decodeAudioPcmRange(cached.bytes, startUs, durationUs, {
+                streamIndex,
+                ...(signal === undefined ? {} : { signal }),
+            }));
+            if (signal?.aborted === true)
+                throw abortReason(signal);
+            return block;
+        }
+        finally {
+            this.#releaseRequest();
+        }
+    }
+    clear() {
+        this.#generation += 1;
+        for (const cached of this.#cache.values())
+            this.#disposeAsset(cached);
+        this.#cache.clear();
+        this.#cachedBytes = 0;
+    }
+    snapshot() {
+        return {
+            assets: this.#cache.size,
+            cachedBytes: this.#cachedBytes,
+            maxCachedBytes: this.#maxCachedBytes,
+            inFlightAssetLoads: this.#assetLoadOperations.size,
+            inFlightSampleIndexes: this.#indexOperations.size,
+            inFlightRequests: this.#inFlightRequests,
+            maxInFlightRequests: this.#maxInFlightRequests,
+            sharedOperationSubscribers: [...this.#assetLoadOperations, ...this.#indexOperations].reduce((total, operation) => total + operation.subscribers.size, 0),
+            activeOperations: this.#activeOperations,
+            pendingOperations: this.#operationWaiters.length,
+            maxConcurrentOperations: this.#maxConcurrentOperations,
+            maxPendingOperations: this.#maxPendingOperations,
+            activeLoads: this.#activeOperations,
+            pendingLoads: this.#operationWaiters.length,
+            maxConcurrentLoads: this.#maxConcurrentOperations,
+        };
+    }
+    async #asset(assetId, signal) {
+        if (signal?.aborted === true)
+            throw abortReason(signal);
+        const existing = this.#cache.get(assetId);
+        if (existing !== undefined) {
+            this.#cache.delete(assetId);
+            this.#cache.set(assetId, existing);
+            return existing;
+        }
+        const generation = this.#generation;
+        const inFlight = this.#loads.get(assetId);
+        if (inFlight?.generation === generation &&
+            !inFlight.settled &&
+            !inFlight.controller.signal.aborted) {
+            return awaitShared(inFlight, signal);
+        }
+        if (this.#activeOperations >= this.#maxConcurrentOperations &&
+            this.#operationWaiters.length >= this.#maxPendingOperations) {
+            throw this.#queueFullError('operation');
+        }
+        const controller = new AbortController();
+        const load = {
+            generation,
+            controller,
+            settled: false,
+            subscribers: new Map(),
+        };
+        this.#loads.set(assetId, load);
+        this.#assetLoadOperations.add(load);
+        observeShared(load, this.#loadAsset(assetId, generation, controller.signal), 'Shared asset load failed', () => {
+            this.#assetLoadOperations.delete(load);
+            if (this.#loads.get(assetId) === load)
+                this.#loads.delete(assetId);
+        });
+        return awaitShared(load, signal);
+    }
+    async #loadAsset(assetId, generation, signal) {
+        return this.#runBounded(signal, async () => {
+            const bytes = await this.#resolve(assetId, signal);
+            if (signal.aborted)
+                throw abortReason(signal);
+            if (!(bytes instanceof Uint8Array)) {
+                throw new TypeError(`Asset resolver returned no bytes for ${assetId}`);
+            }
+            // Only trust the genuine copy's intrinsic length. A Uint8Array subclass
+            // can override `byteLength`; using the resolver object's property would
+            // let it under-report cache ownership after a large copy was allocated.
+            const copy = new Uint8Array(bytes);
+            const byteLength = copy.byteLength;
+            if (byteLength === 0)
+                throw new TypeError(`Asset resolver returned no bytes for ${assetId}`);
+            const cached = { bytes: copy, byteLength };
+            if (generation !== this.#generation || byteLength > this.#maxCachedBytes)
+                return cached;
+            while (this.#cachedBytes + byteLength > this.#maxCachedBytes && this.#cache.size > 0) {
+                const oldest = this.#cache.entries().next().value;
+                if (oldest === undefined)
+                    break;
+                this.#cache.delete(oldest[0]);
+                this.#disposeAsset(oldest[1]);
+                this.#cachedBytes -= oldest[1].byteLength;
+            }
+            this.#cache.set(assetId, cached);
+            this.#cachedBytes += cached.byteLength;
+            return cached;
+        });
+    }
+    async #sampleIndex(cached, signal) {
+        if (signal?.aborted === true)
+            throw abortReason(signal);
+        if (cached.index !== undefined)
+            return cached.index;
+        let operation = cached.indexOperation;
+        if (operation === undefined || operation.settled || operation.controller.signal.aborted) {
+            if (this.#activeOperations >= this.#maxConcurrentOperations &&
+                this.#operationWaiters.length >= this.#maxPendingOperations) {
+                throw this.#queueFullError('operation');
+            }
+            const controller = new AbortController();
+            operation = {
+                controller,
+                settled: false,
+                subscribers: new Map(),
+            };
+            const current = operation;
+            const promise = this.#runBounded(controller.signal, async () => {
+                const index = await createSampleIndex(cached.bytes, { signal: controller.signal });
+                if (controller.signal.aborted)
+                    throw abortReason(controller.signal);
+                cached.index = index;
+                return index;
+            });
+            cached.indexOperation = current;
+            this.#indexOperations.add(current);
+            observeShared(current, promise, 'Shared media index operation failed', () => {
+                this.#indexOperations.delete(current);
+                if (cached.indexOperation === current)
+                    cached.indexOperation = undefined;
+            });
+        }
+        return awaitShared(operation, signal);
+    }
+    #disposeAsset(cached) {
+        for (const session of cached.videoSessions?.values() ?? [])
+            session.dispose();
+        cached.videoSessions?.clear();
+    }
+    async #runBounded(signal, operation) {
+        await this.#acquireOperationSlot(signal);
+        try {
+            if (signal?.aborted === true)
+                throw abortReason(signal);
+            return await operation();
+        }
+        finally {
+            this.#releaseOperationSlot();
+        }
+    }
+    async #acquireOperationSlot(signal) {
+        if (signal?.aborted === true)
+            throw abortReason(signal);
+        if (this.#activeOperations < this.#maxConcurrentOperations) {
+            this.#activeOperations += 1;
+            return;
+        }
+        if (this.#operationWaiters.length >= this.#maxPendingOperations) {
+            throw this.#queueFullError('operation');
+        }
+        await new Promise((resolve, reject) => {
+            let queued = true;
+            const waiter = {
+                ...(signal === undefined ? {} : { signal }),
+                grant: () => {
+                    if (!queued)
+                        return;
+                    queued = false;
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve();
+                },
+                reject: error => {
+                    if (!queued)
+                        return;
+                    queued = false;
+                    signal?.removeEventListener('abort', onAbort);
+                    reject(error);
+                },
+            };
+            const onAbort = () => {
+                const index = this.#operationWaiters.indexOf(waiter);
+                if (index >= 0)
+                    this.#operationWaiters.splice(index, 1);
+                if (signal !== undefined)
+                    waiter.reject(abortReason(signal));
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.#operationWaiters.push(waiter);
+        });
+    }
+    #releaseOperationSlot() {
+        let next = this.#operationWaiters.shift();
+        while (next?.signal?.aborted === true) {
+            next.reject(abortReason(next.signal));
+            next = this.#operationWaiters.shift();
+        }
+        if (next === undefined) {
+            this.#activeOperations -= 1;
+            return;
+        }
+        next.grant();
+    }
+    #admitRequest(signal) {
+        if (signal?.aborted === true)
+            throw abortReason(signal);
+        if (this.#inFlightRequests >= this.#maxInFlightRequests) {
+            throw this.#queueFullError('request');
+        }
+        this.#inFlightRequests += 1;
+    }
+    #releaseRequest() {
+        this.#inFlightRequests -= 1;
+    }
+    #queueFullError(scope) {
+        const limit = scope === 'request' ? this.#maxInFlightRequests : this.#maxPendingOperations;
+        return new AelionError([
+            {
+                code: 'MEDIA_PROVIDER_QUEUE_FULL',
+                severity: 'error',
+                message: scope === 'request'
+                    ? `ByteMediaProvider reached its ${limit.toString()} in-flight request limit`
+                    : `ByteMediaProvider operation queue reached its ${limit.toString()} pending operation limit`,
+                recoverable: true,
+                details: { scope, limit },
+            },
+        ]);
+    }
+}

package/dist/migration-materials.d.ts

@@ -0,0 +1,10 @@
+import type { JsonValue } from '@aelionsdk/core';
+import type { WebGl2MaterialProgram } from '@aelionsdk/material-compiler';
+import type { IrMaterialDefinition } from '@aelionsdk/render-ir';
+export interface MigrationMaterialRegistry {
+    register(definition: IrMaterialDefinition, program: WebGl2MaterialProgram | ((parameters: Readonly<Record<string, JsonValue>>) => WebGl2MaterialProgram)): () => void;
+}
+/** Install renderable programs for every Material emitted by the Diffusion adapter. */
+export declare function installMigrationMaterials(registry: MigrationMaterialRegistry): () => void;
+export declare function migrationMaterialProgram(materialId: string): WebGl2MaterialProgram | undefined;
+//# sourceMappingURL=migration-materials.d.ts.map

package/dist/migration-materials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-materials.d.ts","sourceRoot":"","sources":["../src/migration-materials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAA0B,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAIjE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CACN,UAAU,EAAE,oBAAoB,EAChC,OAAO,EACH,qBAAqB,GACrB,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,KAAK,qBAAqB,CAAC,GAC/E,MAAM,IAAI,CAAC;CACf;AAoMD,uFAAuF;AACvF,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,IAAI,CAOzF;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAE9F"}

package/dist/migration-materials.js

@@ -0,0 +1,148 @@
+import { migrationMaterialPackage } from './migration.js';
+const vertexPrelude = `#version 300 es
+precision highp float;
+`;
+function plan(id, textureSamples) {
+    return {
+        passes: [
+            {
+                id,
+                kind: 'draw',
+                nodes: [id],
+                estimatedTextureSamples: textureSamples,
+            },
+        ],
+        intermediateTextureCount: 0,
+    };
+}
+function parameter(id) {
+    return {
+        name: `u_parameter_${id}`,
+        type: 'float',
+        source: { kind: 'parameter', id },
+    };
+}
+const progressUniform = {
+    name: 'u_system_transitionProgress',
+    type: 'float',
+    source: { kind: 'system', id: 'transitionProgress' },
+};
+function transitionProgram(id, body, textureSamples = 2) {
+    return {
+        backend: 'webgl2',
+        nodeSet: 'aelion.migration/1.0.0',
+        graphHash: `aelion-migration-${id}-v1`,
+        inputPorts: ['from', 'to'],
+        uniforms: [progressUniform],
+        executionPlan: plan(id, textureSamples),
+        fragmentShader: `${vertexPrelude}
+uniform sampler2D u_input_from;
+uniform sampler2D u_input_to;
+uniform float u_system_transitionProgress;
+in vec2 v_uv;
+out vec4 out_color;
+void main() {
+  float progress = clamp(u_system_transitionProgress, 0.0, 1.0);
+  ${body}
+}`,
+    };
+}
+const transitionPrograms = {
+    'diffusion-dissolve': transitionProgram('diffusion-dissolve', 'out_color = mix(texture(u_input_from, v_uv), texture(u_input_to, v_uv), progress);'),
+    'diffusion-slide-from-right': transitionProgram('diffusion-slide-from-right', `float offset = (1.0 - progress) * (1.0 - progress);
+  vec4 from_color = texture(u_input_from, v_uv);
+  vec2 to_uv = vec2(v_uv.x - offset, v_uv.y);
+  vec4 to_color = texture(u_input_to, clamp(to_uv, 0.0, 1.0));
+  out_color = v_uv.x >= offset ? to_color : from_color;`),
+    'diffusion-slide-from-left': transitionProgram('diffusion-slide-from-left', `float offset = (1.0 - progress) * (1.0 - progress);
+  vec4 from_color = texture(u_input_from, v_uv);
+  vec2 to_uv = vec2(v_uv.x + offset, v_uv.y);
+  vec4 to_color = texture(u_input_to, clamp(to_uv, 0.0, 1.0));
+  out_color = v_uv.x <= 1.0 - offset ? to_color : from_color;`),
+    'diffusion-fade-to-black': transitionProgram('diffusion-fade-to-black', `vec4 base = progress < 0.5 ? texture(u_input_from, v_uv) : texture(u_input_to, v_uv);
+  float amount = progress < 0.5 ? progress * 2.0 : (1.0 - progress) * 2.0;
+  out_color = mix(base, vec4(0.0, 0.0, 0.0, 1.0), amount);`),
+    'diffusion-fade-to-white': transitionProgram('diffusion-fade-to-white', `vec4 base = progress < 0.5 ? texture(u_input_from, v_uv) : texture(u_input_to, v_uv);
+  float amount = progress < 0.5 ? progress * 2.0 : (1.0 - progress) * 2.0;
+  out_color = mix(base, vec4(1.0), amount);`),
+};
+function effectProgram(id, body, parameters = ['value'], textureSamples = 1) {
+    const declarations = parameters.map(value => `uniform float u_parameter_${value};`).join('\n');
+    return {
+        backend: 'webgl2',
+        nodeSet: 'aelion.migration/1.0.0',
+        graphHash: `aelion-migration-${id}-v1`,
+        inputPorts: ['source'],
+        uniforms: parameters.map(parameter),
+        executionPlan: plan(id, textureSamples),
+        fragmentShader: `${vertexPrelude}
+uniform sampler2D u_input_source;
+${declarations}
+in vec2 v_uv;
+out vec4 out_color;
+void main() {
+  vec4 source_color = texture(u_input_source, v_uv);
+  float amount = u_parameter_value / 100.0;
+  ${body}
+}`,
+    };
+}
+const effectPrograms = {
+    'diffusion-brightness': effectProgram('diffusion-brightness', 'out_color = vec4(source_color.rgb * amount, source_color.a);'),
+    'diffusion-contrast': effectProgram('diffusion-contrast', 'out_color = vec4((source_color.rgb - 0.5) * amount + 0.5, source_color.a);'),
+    'diffusion-grayscale': effectProgram('diffusion-grayscale', `float luma = dot(source_color.rgb, vec3(0.2126, 0.7152, 0.0722));
+  out_color = vec4(mix(source_color.rgb, vec3(luma), clamp(amount, 0.0, 1.0)), source_color.a);`),
+    'diffusion-hue-rotate': effectProgram('diffusion-hue-rotate', `float angle = radians(u_parameter_value);
+  float c = cos(angle);
+  float s = sin(angle);
+  mat3 hue = mat3(
+    0.213 + c * 0.787 - s * 0.213,
+    0.715 - c * 0.715 - s * 0.715,
+    0.072 - c * 0.072 + s * 0.928,
+    0.213 - c * 0.213 + s * 0.143,
+    0.715 + c * 0.285 + s * 0.140,
+    0.072 - c * 0.072 - s * 0.283,
+    0.213 - c * 0.213 - s * 0.787,
+    0.715 - c * 0.715 + s * 0.715,
+    0.072 + c * 0.928 + s * 0.072
+  );
+  out_color = vec4(clamp(hue * source_color.rgb, 0.0, 1.0), source_color.a);`),
+    'diffusion-invert': effectProgram('diffusion-invert', 'out_color = vec4(mix(source_color.rgb, 1.0 - source_color.rgb, clamp(amount, 0.0, 1.0)), source_color.a);'),
+    'diffusion-opacity': effectProgram('diffusion-opacity', 'out_color = source_color * clamp(amount, 0.0, 1.0);'),
+    'diffusion-saturate': effectProgram('diffusion-saturate', `float luma = dot(source_color.rgb, vec3(0.2126, 0.7152, 0.0722));
+  out_color = vec4(mix(vec3(luma), source_color.rgb, max(0.0, amount)), source_color.a);`),
+    'diffusion-sepia': effectProgram('diffusion-sepia', `vec3 sepia = vec3(
+    dot(source_color.rgb, vec3(0.393, 0.769, 0.189)),
+    dot(source_color.rgb, vec3(0.349, 0.686, 0.168)),
+    dot(source_color.rgb, vec3(0.272, 0.534, 0.131))
+  );
+  out_color = vec4(mix(source_color.rgb, min(sepia, 1.0), clamp(amount, 0.0, 1.0)), source_color.a);`),
+    'diffusion-blur': effectProgram('diffusion-blur', `vec2 radius = vec2(
+    max(0.0, u_parameter_value) / max(1.0, u_parameter_width),
+    max(0.0, u_parameter_value) / max(1.0, u_parameter_height)
+  );
+  vec4 sum = source_color * 0.227027;
+  sum += texture(u_input_source, v_uv + vec2(radius.x, 0.0) * 1.384615) * 0.158108;
+  sum += texture(u_input_source, v_uv - vec2(radius.x, 0.0) * 1.384615) * 0.158108;
+  sum += texture(u_input_source, v_uv + vec2(0.0, radius.y) * 1.384615) * 0.158108;
+  sum += texture(u_input_source, v_uv - vec2(0.0, radius.y) * 1.384615) * 0.158108;
+  sum += texture(u_input_source, v_uv + radius * 3.230769) * 0.035885;
+  sum += texture(u_input_source, v_uv - radius * 3.230769) * 0.035885;
+  sum += texture(u_input_source, v_uv + vec2(radius.x, -radius.y) * 3.230769) * 0.035885;
+  sum += texture(u_input_source, v_uv + vec2(-radius.x, radius.y) * 3.230769) * 0.035885;
+  out_color = sum;`, ['value', 'width', 'height'], 9),
+};
+function definition(materialId) {
+    return { ...migrationMaterialPackage, materialId };
+}
+/** Install renderable programs for every Material emitted by the Diffusion adapter. */
+export function installMigrationMaterials(registry) {
+    const disposers = [...Object.entries(transitionPrograms), ...Object.entries(effectPrograms)].map(([materialId, program]) => registry.register(definition(materialId), program));
+    return () => {
+        for (const dispose of disposers.reverse())
+            dispose();
+    };
+}
+export function migrationMaterialProgram(materialId) {
+    return transitionPrograms[materialId] ?? effectPrograms[materialId];
+}

package/dist/migration.d.ts

@@ -0,0 +1,109 @@
+import { type Rational } from '@aelionsdk/core';
+import type { AelionProject } from '@aelionsdk/project-schema';
+import { type AddAssetOptions } from './project-builder.js';
+export declare const migrationMaterialPackage: Readonly<{
+    packageId: "aelion.migration.builtin";
+    packageVersion: "1.0.0";
+    packageIntegrity: `sha256:${string}`;
+}>;
+export type MigrationSeverity = 'info' | 'warning' | 'error';
+export interface MigrationDiagnostic {
+    readonly code: string;
+    readonly severity: MigrationSeverity;
+    readonly path: string;
+    readonly message: string;
+}
+export interface MigrationResult {
+    readonly project: Readonly<AelionProject>;
+    readonly diagnostics: readonly MigrationDiagnostic[];
+    /** Maps source object identifiers to generated Aelion entity identifiers. */
+    readonly entityMap: Readonly<Record<string, string>>;
+}
+export declare class ProjectMigrationError extends Error {
+    readonly diagnostics: readonly MigrationDiagnostic[];
+    readonly name = "ProjectMigrationError";
+    constructor(diagnostics: readonly MigrationDiagnostic[]);
+}
+export interface MigrationOptions {
+    /** Reject every rendering feature that cannot be represented exactly. Defaults to true. */
+    readonly strict?: boolean;
+    readonly projectId?: string;
+    readonly sequenceId?: string;
+    readonly title?: string;
+    readonly frameRate?: Rational;
+}
+export interface WebAvAssetBinding extends Omit<AddAssetOptions, 'kind'> {
+    readonly kind: 'video' | 'audio' | 'image';
+    /** Natural decoded size, required for visual rect conversion. */
+    readonly width?: number;
+    readonly height?: number;
+}
+export interface WebAvAnimationFrame {
+    /** Item-local time in WebAV microseconds. */
+    readonly timeUs: number;
+    readonly x?: number;
+    readonly y?: number;
+    readonly width?: number;
+    readonly height?: number;
+    /** WebAV stores rotation in radians. */
+    readonly angle?: number;
+    readonly opacity?: number;
+}
+/**
+ * Serializable projection of WebAV BaseSprite public state.
+ *
+ * WebAV deliberately keeps the IClip and its bytes private on OffscreenSprite,
+ * so callers must bind the source Asset explicitly instead of the adapter
+ * pretending it can recover source bytes from a Sprite.
+ */
+export interface WebAvSpriteSnapshot {
+    readonly id: string;
+    readonly kind: 'video' | 'audio' | 'image';
+    readonly assetId: string;
+    readonly time: {
+        readonly offset: number;
+        readonly duration: number;
+        readonly playbackRate?: number;
+    };
+    readonly rect?: {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly h: number;
+        readonly angle?: number;
+    };
+    readonly zIndex?: number;
+    readonly opacity?: number;
+    readonly flip?: 'horizontal' | 'vertical' | null;
+    readonly visible?: boolean;
+    readonly sourceStartUs?: number;
+    /** Set when the WebAV IClip produces audio as well as video. */
+    readonly includeAudio?: boolean;
+    /** WebAV's private animation state must be projected explicitly by the caller. */
+    readonly animation?: readonly WebAvAnimationFrame[];
+}
+export interface WebAvProjectSnapshot {
+    readonly width: number;
+    readonly height: number;
+    readonly backgroundColor?: string;
+    readonly assets: readonly WebAvAssetBinding[];
+    readonly sprites: readonly WebAvSpriteSnapshot[];
+}
+export interface DiffusionAssetBinding extends Omit<AddAssetOptions, 'id' | 'kind'> {
+    /** Diffusion BaseSource.id used by checkpoint Clip.source. */
+    readonly sourceId: string;
+    readonly assetId: string;
+    readonly kind: AddAssetOptions['kind'];
+    readonly width?: number;
+    readonly height?: number;
+    /** Whether a VIDEO source also exposes an audio track. */
+    readonly hasAudio?: boolean;
+    /** Required to turn a Diffusion CaptionSource into an inline Aelion Caption. */
+    readonly captionText?: string;
+}
+export interface DiffusionMigrationOptions extends MigrationOptions {
+    readonly assets: readonly DiffusionAssetBinding[];
+}
+export declare function migrateWebAvProject(snapshot: WebAvProjectSnapshot, options?: MigrationOptions): MigrationResult;
+export declare function migrateDiffusionCheckpoint(value: unknown, options: DiffusionMigrationOptions): MigrationResult;
+//# 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":"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"}