@aelionsdk/sdk 0.1.0-beta.1

package/dist/session.js

@@ -0,0 +1,1114 @@
+import { renderIrAudio } from '@aelionsdk/audio';
+import { probeCapabilities } from '@aelionsdk/capability';
+import { AelionError } from '@aelionsdk/core';
+import { createRemoteExportContentId, exportFrozenRenderIrAv1Mp4, exportFrozenRenderIrHevcMp4, exportFrozenRenderIrMp4, exportFrozenRenderIrWebM, exportGif, exportStillImage, exportWav, preflightProfileExport, preflightWebMExport, runRemoteExport, selectExportProfile, } from '@aelionsdk/export';
+import { canonicalStringify, ProjectValidator, } from '@aelionsdk/project-schema';
+import { evaluateAnimatedValue, evaluateVisualState, IncrementalRenderCompiler, } from '@aelionsdk/render-ir';
+import { RenderIrFrameRenderer, } from '@aelionsdk/renderer-worker';
+import { EditingCommands, TransactionEngine, TransactionHistory, } from '@aelionsdk/transaction';
+import { SessionAudioController, projectAudioMastering } from './audio-controller.js';
+import { createMasteredAudioRenderer } from './audio-mastering.js';
+import { AelionPlayer } from './player.js';
+import { normalizePreviewQuality } from './preview-quality.js';
+import { defaultSchemas } from './default-schemas.js';
+import { ExportJob } from './export-job.js';
+function unloaded() {
+    return new Error('Load an Aelion Project before using this session');
+}
+function channelCountForLayout(layout) {
+    if (layout === 'mono')
+        return 1;
+    if (layout === 'stereo')
+        return 2;
+    if (layout === '5.1')
+        return 6;
+    throw new RangeError(`Unsupported channel layout ${layout}`);
+}
+function objectValue(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function finiteValue(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function directOpaqueVisualSource(ir, timeUs) {
+    const state = evaluateVisualState(ir, timeUs);
+    const active = state.clips[0];
+    if (state.transition !== undefined ||
+        state.clips.length !== 1 ||
+        active?.clip.kind !== 'visual-clip' ||
+        active.sourceTimeUs === null ||
+        active.materials.length !== 0) {
+        return undefined;
+    }
+    const clip = active.clip;
+    const visual = clip.visual;
+    if (visual.fit !== 'fill' ||
+        visual.blendMode !== 'normal' ||
+        visual.mask !== undefined ||
+        clip.materialInstanceIds.length !== 0) {
+        return undefined;
+    }
+    const evaluate = (value) => evaluateAnimatedValue(value, timeUs, clip.range.startUs);
+    const transform = visual.transform;
+    const position = objectValue(evaluate(transform.positionPx));
+    const anchor = objectValue(evaluate(transform.anchor));
+    const scale = objectValue(evaluate(transform.scale));
+    const skew = objectValue(evaluate(transform.skewDeg));
+    const crop = objectValue(evaluate(visual.crop));
+    if (finiteValue(position.x, ir.width / 2) !== ir.width / 2 ||
+        finiteValue(position.y, ir.height / 2) !== ir.height / 2 ||
+        finiteValue(anchor.x, 0.5) !== 0.5 ||
+        finiteValue(anchor.y, 0.5) !== 0.5 ||
+        finiteValue(scale.x, 1) !== 1 ||
+        finiteValue(scale.y, 1) !== 1 ||
+        finiteValue(skew.x, 0) !== 0 ||
+        finiteValue(skew.y, 0) !== 0 ||
+        finiteValue(evaluate(transform.rotationDeg), 0) !== 0 ||
+        finiteValue(evaluate(visual.opacity), 1) !== 1 ||
+        finiteValue(crop.left, 0) !== 0 ||
+        finiteValue(crop.top, 0) !== 0 ||
+        finiteValue(crop.right, 0) !== 0 ||
+        finiteValue(crop.bottom, 0) !== 0) {
+        return undefined;
+    }
+    return {
+        assetId: clip.source.assetId,
+        streamIndex: clip.source.streamIndex,
+        sourceTimeUs: active.sourceTimeUs,
+    };
+}
+function frameHasAlpha(frame) {
+    return frame.format === 'I420A' || frame.format === 'RGBA' || frame.format === 'BGRA';
+}
+const DEFAULT_MAX_DIAGNOSTICS = 256;
+function diagnosticHistoryLimit(value) {
+    const limit = value ?? DEFAULT_MAX_DIAGNOSTICS;
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        throw new RangeError('maxDiagnostics must be a positive safe integer');
+    }
+    return limit;
+}
+export class AelionSession {
+    #options;
+    #validator;
+    #compiler = new IncrementalRenderCompiler();
+    #renderer;
+    #lastDisposedRenderer;
+    #listeners = new Set();
+    #state = 'empty';
+    #capability;
+    #diagnostics = [];
+    #maxDiagnostics;
+    #droppedDiagnostics = 0;
+    #engine;
+    #history;
+    #commands;
+    #unsubscribeHistory;
+    #ir;
+    #compileStats;
+    #sequenceId;
+    #previewRequestedFrames = 0;
+    #previewRenderedFrames = 0;
+    #previewFailedFrames = 0;
+    #lastPreviewBackend;
+    #lastPreviewWidth;
+    #lastPreviewHeight;
+    #lastPreviewRenderScale;
+    #exportJobsStarted = 0;
+    #exportJobsCompleted = 0;
+    #exportJobsFailed = 0;
+    #exportJobsCancelled = 0;
+    #activeExportJob;
+    #nextExportJobId = 1;
+    #loadGeneration = 0;
+    #loadInProgress = 0;
+    #loadTail = Promise.resolve();
+    #disposeTask;
+    #activeInteractiveEdit;
+    #nextInteractiveEditId = 1;
+    player;
+    audio;
+    transaction;
+    preview;
+    export;
+    constructor(options = {}) {
+        this.#options = options;
+        this.#maxDiagnostics = diagnosticHistoryLimit(options.maxDiagnostics);
+        if (options.maxPendingFrames !== undefined &&
+            (!Number.isSafeInteger(options.maxPendingFrames) || options.maxPendingFrames <= 0)) {
+            throw new RangeError('maxPendingFrames must be a positive safe integer');
+        }
+        this.#validator = new ProjectValidator({
+            projectSchema: (options.schemas ?? defaultSchemas).project,
+            materialInstanceSchema: (options.schemas ?? defaultSchemas).materialInstance,
+        });
+        this.player = new AelionPlayer(this, (error) => this.#acceptPlayerError(error), options.runtimeAssets);
+        this.audio = new SessionAudioController({
+            ir: () => this.requireIr(),
+            project: () => {
+                const value = this.#engine?.getSnapshot();
+                if (value === undefined)
+                    throw unloaded();
+                return value;
+            },
+            media: () => this.requireMedia(),
+            revision: () => {
+                const value = this.revision;
+                if (value === null)
+                    throw unloaded();
+                return value;
+            },
+            edit: (label, callback) => this.#edit(callback, { label }),
+        });
+        this.preview = {
+            renderFrame: options => this.#renderPreviewFrame(options),
+        };
+        const commands = () => this.#requireCommands();
+        const canUndo = () => this.#history?.state.canUndo ?? false;
+        const canRedo = () => this.#history?.state.canRedo ?? false;
+        this.transaction = {
+            edit: (callback, editOptions = {}) => this.#edit(callback, editOptions),
+            beginInteractive: editOptions => this.#beginInteractiveEdit(editOptions),
+            undo: () => this.#undoChange(),
+            redo: () => this.#redoChange(),
+            get commands() {
+                return commands();
+            },
+            get canUndo() {
+                return canUndo();
+            },
+            get canRedo() {
+                return canRedo();
+            },
+        };
+        const activeExportJob = () => this.#activeExportJob ?? null;
+        this.export = {
+            preflight: options => this.#preflight(options),
+            preflightProfile: options => this.#preflightProfile(options),
+            negotiate: options => this.#negotiateExport(options),
+            start: options => this.#startExport(options),
+            startProfile: options => this.#startProfileExport(options),
+            startRemote: options => this.#startRemoteExport(options),
+            cancel: reason => this.#cancelExport(reason),
+            get activeJob() {
+                return activeExportJob();
+            },
+        };
+    }
+    get state() {
+        return this.#state;
+    }
+    get revision() {
+        return this.#engine?.revision ?? null;
+    }
+    async loadProject(value) {
+        this.#assertActive();
+        const validation = this.#validator.validate(value);
+        if (!validation.ok) {
+            for (const diagnostic of validation.diagnostics)
+                this.#recordDiagnostic(diagnostic);
+            throw new AelionError(validation.diagnostics);
+        }
+        const generation = this.#loadGeneration + 1;
+        this.#loadGeneration = generation;
+        this.#loadInProgress += 1;
+        const task = this.#loadTail.then(() => this.#installProject(validation.value.project, generation));
+        // Serialize reset/install work so a superseded load cannot finish resetting
+        // Player resources after a newer Project has already become visible. Keep the
+        // tail fulfilled so one failed/superseded load cannot block the next request.
+        this.#loadTail = task.then(() => undefined, () => undefined);
+        return task.finally(() => {
+            this.#loadInProgress -= 1;
+        });
+    }
+    async #installProject(project, generation) {
+        this.#assertLoadCurrent(generation);
+        this.#invalidateInteractiveEdit();
+        await this.player.reset();
+        this.#assertLoadCurrent(generation);
+        const engineRef = {};
+        const engine = new TransactionEngine(project, candidate => {
+            const result = this.#validator.validate(candidate);
+            return { ok: result.ok, diagnostics: result.diagnostics };
+        }, {
+            prepareCommit: commit => {
+                const current = engineRef.current;
+                if (current === undefined)
+                    throw new Error('Transaction engine is not installed');
+                return this.#prepareCommit(current, commit);
+            },
+        });
+        engineRef.current = engine;
+        const history = new TransactionHistory(engine);
+        const commands = new EditingCommands({
+            get revision() {
+                return history.revision;
+            },
+            getSnapshot: () => history.getSnapshot(),
+            subscribe: listener => history.subscribe(listener),
+            edit: (editOptions, callback) => {
+                this.#assertTransactionAvailable();
+                if (this.#history !== history)
+                    throw new Error('Editing command belongs to a stale Project');
+                if (this.#activeInteractiveEdit?.active === true) {
+                    throw new Error('Finish or cancel the active interactive edit before starting another edit');
+                }
+                return history.edit(editOptions, callback);
+            },
+        });
+        const sequenceId = this.#options.sequenceId ?? project.settings.defaultSequenceId;
+        const compiler = new IncrementalRenderCompiler();
+        const compilation = compiler.compile(engine.getSnapshot(), sequenceId, engine.revision, {
+            resolveMaterialProgram: (definition, parameters) => this.#options.materials?.resolveProgram(definition, parameters),
+        });
+        // A synchronous host Material resolver may re-enter the Session and dispose
+        // it (or request a newer load) while compilation is running.
+        this.#assertLoadCurrent(generation);
+        const unsubscribeHistory = history.subscribe(commit => this.#publishCommit(engine, commit));
+        this.#unsubscribeHistory?.();
+        this.#engine = engine;
+        this.#unsubscribeHistory = unsubscribeHistory;
+        this.#history = history;
+        this.#commands = commands;
+        this.#sequenceId = sequenceId;
+        this.#compiler = compiler;
+        this.#compileStats = compilation.stats;
+        this.#ir = compilation.ir;
+        this.#setState('ready');
+        // `state-changed` listeners are user callbacks and may synchronously dispose
+        // the Session or request another Project. Roll back this just-installed
+        // candidate before surfacing the stale load so no engine survives disposal.
+        try {
+            this.#assertLoadCurrent(generation);
+        }
+        catch (error) {
+            unsubscribeHistory();
+            if (this.#engine === engine) {
+                this.#engine = undefined;
+                this.#unsubscribeHistory = undefined;
+                this.#history = undefined;
+                this.#commands = undefined;
+                this.#sequenceId = undefined;
+                this.#ir = undefined;
+                this.#compileStats = undefined;
+            }
+            throw error;
+        }
+        this.#emit({
+            type: 'project-loaded',
+            projectId: project.projectId,
+            revision: engine.revision,
+        });
+    }
+    async renderFrame(options) {
+        return this.#renderPreviewFrame(options);
+    }
+    async #renderPreviewFrame(options) {
+        this.#previewRequestedFrames += 1;
+        this.#emitStats();
+        try {
+            const ir = this.requireIr();
+            const media = this.#options.media;
+            if (media === undefined)
+                throw new Error('AelionSession requires a media provider to render');
+            const previewQuality = normalizePreviewQuality(options);
+            const result = await this.#requireRenderer().render({
+                ir,
+                timeUs: options.timeUs,
+                source: media,
+                mode: 'preview',
+                preferredBackend: this.#options.preferredBackend ?? 'auto',
+                allowFallback: this.#options.allowBackendFallback ?? true,
+                renderScale: previewQuality.renderScale,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
+            this.#previewRenderedFrames += 1;
+            this.#lastPreviewBackend = result.backend;
+            this.#lastPreviewWidth = result.width;
+            this.#lastPreviewHeight = result.height;
+            this.#lastPreviewRenderScale = result.renderScale;
+            this.#emitStats();
+            return result;
+        }
+        catch (error) {
+            this.#previewFailedFrames += 1;
+            this.#recordErrorDiagnostics(error);
+            this.#emitStats();
+            throw error;
+        }
+    }
+    async probeCapabilities(signal) {
+        this.#assertActive();
+        const capability = await probeCapabilities(signal === undefined ? {} : { signal });
+        this.#capability = capability;
+        for (const diagnostic of capability.diagnostics)
+            this.#recordDiagnostic(diagnostic);
+        this.#emit({ type: 'capability-changed', capability });
+        return capability;
+    }
+    getSnapshot() {
+        return Object.freeze({
+            state: this.#state,
+            revision: this.revision,
+            project: this.#engine?.getSnapshot() ?? null,
+            renderIr: this.#ir ?? null,
+            capability: this.#capability ?? null,
+            diagnostics: this.getDiagnostics(),
+            stats: this.getStats(),
+        });
+    }
+    getCapabilitySnapshot() {
+        return this.#capability ?? null;
+    }
+    getDiagnostics() {
+        return Object.freeze([...this.#diagnostics]);
+    }
+    getStats() {
+        const active = this.#activeExportJob?.getSnapshot();
+        const renderer = this.#renderer?.snapshot();
+        return Object.freeze({
+            schemaVersion: '1.0.0',
+            revision: this.revision,
+            diagnostics: Object.freeze({
+                retained: this.#diagnostics.length,
+                dropped: this.#droppedDiagnostics,
+                limit: this.#maxDiagnostics,
+            }),
+            compile: this.#compileStats ?? null,
+            preview: Object.freeze({
+                requestedFrames: this.#previewRequestedFrames,
+                renderedFrames: this.#previewRenderedFrames,
+                failedFrames: this.#previewFailedFrames,
+                lastBackend: this.#lastPreviewBackend ?? null,
+                lastWidth: this.#lastPreviewWidth ?? null,
+                lastHeight: this.#lastPreviewHeight ?? null,
+                lastRenderScale: this.#lastPreviewRenderScale ?? null,
+                pendingFrames: renderer?.pendingFrames ?? 0,
+                maxPendingFrames: renderer?.maxPendingFrames ?? this.#options.maxPendingFrames ?? 2,
+                rendererPresent: renderer !== undefined,
+                rendererDisposed: renderer?.disposed ?? true,
+                workerPendingRequests: renderer?.worker.pendingRequests ?? 0,
+                workerActiveRequests: renderer?.worker.activeRequests ?? 0,
+                workerCancelledRequests: renderer?.worker.cancelledRequests ?? 0,
+                lastDisposedRenderer: this.#lastDisposedRenderer === undefined
+                    ? null
+                    : Object.freeze({
+                        disposed: this.#lastDisposedRenderer.disposed,
+                        pendingFrames: this.#lastDisposedRenderer.pendingFrames,
+                        workerDisposed: this.#lastDisposedRenderer.worker.disposed,
+                        workerPendingRequests: this.#lastDisposedRenderer.worker.pendingRequests,
+                        workerActiveRequests: this.#lastDisposedRenderer.worker.activeRequests,
+                        workerCancelledRequests: this.#lastDisposedRenderer.worker.cancelledRequests,
+                    }),
+            }),
+            player: this.player.getStats(),
+            export: Object.freeze({
+                jobsStarted: this.#exportJobsStarted,
+                jobsCompleted: this.#exportJobsCompleted,
+                jobsFailed: this.#exportJobsFailed,
+                jobsCancelled: this.#exportJobsCancelled,
+                activeJobId: active?.id ?? null,
+                progress: active?.progress ?? 0,
+            }),
+        });
+    }
+    subscribe(typeOrListener, typedListener) {
+        this.#assertActive();
+        const listener = typeof typeOrListener === 'function'
+            ? typeOrListener
+            : event => {
+                if (event.type === typeOrListener)
+                    typedListener?.(event);
+            };
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    dispose() {
+        const existing = this.#disposeTask;
+        if (existing !== undefined)
+            return existing;
+        let resolveTask;
+        let rejectTask;
+        const task = new Promise((resolve, reject) => {
+            resolveTask = resolve;
+            rejectTask = reject;
+        });
+        // Publish the task before cleanup emits `state-changed`; a listener may call
+        // dispose() re-entrantly and must receive this exact Promise.
+        this.#disposeTask = task;
+        void this.#dispose().then(resolveTask, rejectTask);
+        return task;
+    }
+    async #dispose() {
+        this.#loadGeneration += 1;
+        this.#invalidateInteractiveEdit();
+        const drainLoads = this.#loadTail.then(() => undefined, () => undefined);
+        const renderer = this.#renderer;
+        const cancelExport = this.#cancelExport(new DOMException('AelionSession disposed', 'AbortError'));
+        this.#setState('disposed');
+        this.#listeners.clear();
+        this.#unsubscribeHistory?.();
+        this.#unsubscribeHistory = undefined;
+        this.#engine = undefined;
+        this.#history = undefined;
+        this.#commands = undefined;
+        this.#ir = undefined;
+        this.#compileStats = undefined;
+        this.#sequenceId = undefined;
+        this.#compiler.clear();
+        const results = await Promise.allSettled([
+            cancelExport,
+            this.player.dispose(),
+            drainLoads,
+            ...(renderer === undefined ? [] : [renderer.dispose()]),
+        ]);
+        if (renderer !== undefined)
+            this.#lastDisposedRenderer = renderer.snapshot();
+        this.#renderer = undefined;
+        const errors = [];
+        for (const result of results) {
+            if (result.status === 'rejected')
+                errors.push(result.reason);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'One or more AelionSession resources failed to dispose');
+        }
+    }
+    requireIr() {
+        this.#assertActive();
+        if (this.#ir === undefined)
+            throw unloaded();
+        return this.#ir;
+    }
+    requireMedia() {
+        const media = this.#options.media;
+        if (media === undefined)
+            throw new Error('AelionSession requires a media provider');
+        return media;
+    }
+    notifyStatsChanged() {
+        if (this.#state !== 'disposed')
+            this.#emitStats();
+    }
+    #edit(callback, options) {
+        this.#assertTransactionAvailable();
+        if (this.#activeInteractiveEdit?.active === true) {
+            throw new Error('Finish or cancel the active interactive edit before starting another edit');
+        }
+        const history = this.#history;
+        if (history === undefined)
+            throw unloaded();
+        return history.edit({
+            ...(options.label === undefined ? {} : { label: options.label }),
+            ...(options.baseRevision === undefined ? {} : { baseRevision: options.baseRevision }),
+        }, callback);
+    }
+    #beginInteractiveEdit(options = {}) {
+        this.#assertTransactionAvailable();
+        if (this.#activeInteractiveEdit?.active === true) {
+            throw new Error('An interactive edit is already active');
+        }
+        const state = {
+            id: `interactive_${this.#nextInteractiveEditId.toString()}`,
+            ...(options.label === undefined ? {} : { label: options.label }),
+            ...(options.baseRevision === undefined ? {} : { baseRevision: options.baseRevision }),
+            active: true,
+            updateCount: 0,
+        };
+        this.#nextInteractiveEditId += 1;
+        this.#activeInteractiveEdit = state;
+        const isActive = () => state.active && this.#activeInteractiveEdit === state;
+        return Object.freeze({
+            get active() {
+                return isActive();
+            },
+            get updateCount() {
+                return state.updateCount;
+            },
+            update: (callback) => this.#updateInteractiveEdit(state, callback),
+            commit: () => this.#finishInteractiveEdit(state),
+            cancel: () => this.#cancelInteractiveEdit(state),
+        });
+    }
+    #updateInteractiveEdit(state, callback) {
+        this.#assertInteractiveEditActive(state);
+        const history = this.#history;
+        if (history === undefined)
+            throw unloaded();
+        const commit = history.edit({
+            ...(state.label === undefined ? {} : { label: state.label }),
+            ...(state.updateCount === 0 && state.baseRevision !== undefined
+                ? { baseRevision: state.baseRevision }
+                : {}),
+            historyGroup: state.id,
+        }, callback);
+        state.updateCount += 1;
+        return commit;
+    }
+    #finishInteractiveEdit(state) {
+        this.#assertInteractiveEditActive(state);
+        this.#history?.finishGroup(state.id);
+        state.active = false;
+        this.#activeInteractiveEdit = undefined;
+    }
+    #cancelInteractiveEdit(state) {
+        this.#assertInteractiveEditActive(state);
+        const history = this.#history;
+        if (history === undefined)
+            throw unloaded();
+        const commit = state.updateCount === 0 ? null : history.cancelGroup(state.id);
+        state.active = false;
+        this.#activeInteractiveEdit = undefined;
+        return commit;
+    }
+    #assertInteractiveEditActive(state) {
+        this.#assertTransactionAvailable();
+        if (!state.active || this.#activeInteractiveEdit !== state) {
+            throw new Error('Interactive edit is no longer active');
+        }
+    }
+    #invalidateInteractiveEdit() {
+        if (this.#activeInteractiveEdit !== undefined)
+            this.#activeInteractiveEdit.active = false;
+        this.#activeInteractiveEdit = undefined;
+    }
+    #undoChange() {
+        this.#assertTransactionAvailable();
+        if (this.#activeInteractiveEdit?.active === true) {
+            throw new Error('Finish or cancel the active interactive edit before undo');
+        }
+        const history = this.#history;
+        if (history === undefined)
+            throw unloaded();
+        return history.undo();
+    }
+    #redoChange() {
+        this.#assertTransactionAvailable();
+        if (this.#activeInteractiveEdit?.active === true) {
+            throw new Error('Finish or cancel the active interactive edit before redo');
+        }
+        const history = this.#history;
+        if (history === undefined)
+            throw unloaded();
+        return history.redo();
+    }
+    #prepareCommit(engine, commit) {
+        this.#assertPreparedCommitCurrent(engine, commit.changeSet.baseRevision);
+        const sequenceId = this.#sequenceId;
+        if (sequenceId === undefined)
+            throw unloaded();
+        const baseCompiler = this.#compiler;
+        const compiler = baseCompiler.fork();
+        const compilation = compiler.compile(commit.snapshot, sequenceId, commit.revision, {
+            affectedEntityIds: commit.changeSet.affectedEntityIds,
+            affectedRanges: commit.changeSet.affectedRanges,
+            resolveMaterialProgram: (definition, parameters) => this.#options.materials?.resolveProgram(definition, parameters),
+        });
+        this.#assertPreparedCommitCurrent(engine, commit.changeSet.baseRevision);
+        let published = false;
+        return {
+            publish: () => {
+                if (published)
+                    throw new Error('Prepared Render IR commit was already published');
+                this.#assertPreparedCommitCurrent(engine, commit.changeSet.baseRevision);
+                if (this.#compiler !== baseCompiler) {
+                    throw new Error('Prepared Render IR compiler baseline is stale');
+                }
+                published = true;
+                this.#compiler = compiler;
+                this.#compileStats = compilation.stats;
+                this.#ir = compilation.ir;
+            },
+        };
+    }
+    #publishCommit(engine, commit) {
+        if (!this.#isCurrentEngine(engine, commit.revision))
+            return;
+        this.#emit({ type: 'project-changed', commit });
+        if (!this.#isCurrentEngine(engine, commit.revision))
+            return;
+        this.player.invalidate(commit.changeSet);
+    }
+    #assertTransactionAvailable() {
+        this.#assertActive();
+        if (this.#loadInProgress > 0) {
+            throw new Error('AelionSession Project transactions are unavailable while a load is pending');
+        }
+    }
+    #assertPreparedCommitCurrent(engine, baseRevision) {
+        this.#assertActive();
+        if (this.#engine !== engine || engine.revision !== baseRevision || this.#loadInProgress > 0) {
+            throw new DOMException('AelionSession transaction was superseded', 'AbortError');
+        }
+    }
+    #isCurrentEngine(engine, revision) {
+        return (this.#state !== 'disposed' &&
+            this.#engine === engine &&
+            this.#loadInProgress === 0 &&
+            engine.revision === revision &&
+            this.#ir?.revision === revision);
+    }
+    #frozenExportOptions(options, signal = options.signal, onProgress = options.onProgress, masteredRenderAudio, frozen) {
+        const ir = frozen?.ir ?? this.requireIr();
+        const media = frozen?.media ?? this.requireMedia();
+        return {
+            ir,
+            projectRevision: ir.revision,
+            videoBitrate: options.videoBitrate ?? 8_000_000,
+            audioBitrate: options.audioBitrate ?? 192_000,
+            ...(this.#options.runtimeAssets?.exportWorker === undefined
+                ? {}
+                : { workerUrl: this.#options.runtimeAssets.exportWorker }),
+            ...(options.execution === undefined ? {} : { execution: options.execution }),
+            sink: options.sink,
+            renderFrame: request => this.#renderExportFrame(ir, media, request, signal),
+            renderAudio: masteredRenderAudio ??
+                (request => renderIrAudio({
+                    ir,
+                    startFrame: request.startFrame,
+                    frameCount: request.frameCount,
+                    channelCount: request.channelCount,
+                    source: media,
+                    ...(signal === undefined ? {} : { signal }),
+                })),
+            ...(signal === undefined ? {} : { signal }),
+            ...(options.cleanupSink === undefined ? {} : { cleanupSink: options.cleanupSink }),
+            ...(onProgress === undefined ? {} : { onProgress }),
+        };
+    }
+    async #preflight(options) {
+        const report = await preflightWebMExport(this.#frozenExportOptions(options));
+        for (const diagnostic of report.issues)
+            this.#recordDiagnostic(diagnostic);
+        return report;
+    }
+    async #createExportAudioRenderer(ir, source, processing, signal) {
+        return createMasteredAudioRenderer({
+            ir,
+            source,
+            ...(processing === undefined ? {} : { processing }),
+            signal,
+        });
+    }
+    async #renderExportFrame(ir, media, request, signal) {
+        const direct = directOpaqueVisualSource(ir, request.timestampUs);
+        if (direct !== undefined) {
+            const source = await media.frameAt(direct.assetId, direct.streamIndex, direct.sourceTimeUs, signal, { purpose: 'export', maxDimension: Math.max(ir.width, ir.height) });
+            try {
+                if (!frameHasAlpha(source)) {
+                    return new VideoFrame(source, {
+                        timestamp: request.timestampUs,
+                        duration: request.durationUs,
+                    });
+                }
+            }
+            finally {
+                source.close();
+            }
+        }
+        const rendered = await this.#requireRenderer().render({
+            ir,
+            timeUs: request.timestampUs,
+            source: media,
+            mode: 'export',
+            preferredBackend: this.#options.preferredBackend ?? 'auto',
+            allowFallback: this.#options.allowBackendFallback ?? true,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        try {
+            return new VideoFrame(rendered.bitmap, {
+                timestamp: request.timestampUs,
+                duration: request.durationUs,
+            });
+        }
+        finally {
+            rendered.bitmap.close();
+        }
+    }
+    async #preflightProfile(options) {
+        const ir = this.requireIr();
+        const report = await preflightProfileExport({
+            ir,
+            projectRevision: ir.revision,
+            profile: options.profile,
+            sink: options.sink,
+            ...('videoBitrate' in options ? { videoBitrate: options.videoBitrate } : {}),
+            ...('audioBitrate' in options ? { audioBitrate: options.audioBitrate } : {}),
+        });
+        for (const diagnostic of report.issues)
+            this.#recordDiagnostic(diagnostic);
+        return report;
+    }
+    async #negotiateExport(options) {
+        const ir = this.requireIr();
+        return selectExportProfile({
+            ...options,
+            width: ir.width,
+            height: ir.height,
+            framerate: ir.frameRate.numerator / ir.frameRate.denominator,
+            sampleRate: ir.sampleRate,
+            numberOfChannels: channelCountForLayout(ir.channelLayout),
+        });
+    }
+    #startExport(options) {
+        this.#assertActive();
+        if (this.#activeExportJob?.state === 'running') {
+            const diagnostics = [
+                {
+                    code: 'EXPORT_JOB_ACTIVE',
+                    severity: 'error',
+                    message: 'AelionSession supports one active export; cancel it before starting another',
+                    recoverable: true,
+                },
+            ];
+            for (const diagnostic of diagnostics)
+                this.#recordDiagnostic(diagnostic);
+            throw new AelionError(diagnostics);
+        }
+        const ir = this.requireIr();
+        const media = this.requireMedia();
+        const project = this.#engine?.getSnapshot();
+        if (project === undefined)
+            throw unloaded();
+        const configuredProcessing = options.audioProcessing ?? projectAudioMastering(project, ir.sequenceId);
+        const processing = configuredProcessing === undefined ? undefined : structuredClone(configuredProcessing);
+        const id = `export-${this.#nextExportJobId.toString()}`;
+        this.#nextExportJobId += 1;
+        this.#exportJobsStarted += 1;
+        const job = new ExportJob({
+            id,
+            ...(options.signal === undefined ? {} : { externalSignal: options.signal }),
+            run: async (signal, updateProgress) => {
+                try {
+                    const mastering = await this.#createExportAudioRenderer(ir, media, processing, signal);
+                    return await exportFrozenRenderIrWebM(this.#frozenExportOptions(options, signal, progress => {
+                        updateProgress(progress);
+                        options.onProgress?.(progress);
+                    }, mastering.render, { ir, media }));
+                }
+                catch (error) {
+                    // Publish structured export diagnostics before the await-compatible
+                    // job rejects so callers observe one deterministic Session state.
+                    this.#recordErrorDiagnostics(error);
+                    throw error;
+                }
+            },
+            onSnapshot: snapshot => this.#acceptExportSnapshot(snapshot),
+            onSettled: settled => {
+                if (this.#activeExportJob === settled)
+                    this.#activeExportJob = undefined;
+                this.#emitStats();
+            },
+        });
+        this.#activeExportJob = job;
+        this.#emitStats();
+        return job;
+    }
+    #startProfileExport(options) {
+        this.#assertActive();
+        if (this.#activeExportJob?.state === 'running') {
+            const diagnostic = {
+                code: 'EXPORT_JOB_ACTIVE',
+                severity: 'error',
+                message: 'AelionSession supports one active export; cancel it before starting another',
+                recoverable: true,
+            };
+            this.#recordDiagnostic(diagnostic);
+            throw new AelionError([diagnostic]);
+        }
+        const ir = this.requireIr();
+        const media = this.requireMedia();
+        const project = this.#engine?.getSnapshot();
+        if (project === undefined)
+            throw unloaded();
+        const configuredProcessing = options.audioProcessing ?? projectAudioMastering(project, ir.sequenceId);
+        const processing = configuredProcessing === undefined ? undefined : structuredClone(configuredProcessing);
+        const id = `export-${this.#nextExportJobId.toString()}`;
+        this.#nextExportJobId += 1;
+        this.#exportJobsStarted += 1;
+        const job = new ExportJob({
+            id,
+            ...(options.signal === undefined ? {} : { externalSignal: options.signal }),
+            run: async (signal, updateProgress) => {
+                const onProgress = (progress) => {
+                    updateProgress(progress);
+                    options.onProgress?.(progress);
+                };
+                const cleanup = options.cleanupSink;
+                const renderFrame = (request) => this.#renderExportFrame(ir, media, request, signal);
+                let mastering;
+                const requireMastering = async () => {
+                    mastering ??= await this.#createExportAudioRenderer(ir, media, processing, signal);
+                    return mastering;
+                };
+                const renderAudio = async (request) => (await requireMastering()).render(request, signal);
+                try {
+                    if (options.profile === 'webm-vp9-opus' ||
+                        options.profile === 'mp4-h264-aac' ||
+                        options.profile === 'mp4-av1-aac' ||
+                        options.profile === 'mp4-hevc-aac') {
+                        const frozen = this.#frozenExportOptions({
+                            sink: options.sink,
+                            ...(options.videoBitrate === undefined
+                                ? {}
+                                : { videoBitrate: options.videoBitrate }),
+                            ...(options.audioBitrate === undefined
+                                ? {}
+                                : { audioBitrate: options.audioBitrate }),
+                            ...(cleanup === undefined ? {} : { cleanupSink: cleanup }),
+                            ...(options.audioProcessing === undefined
+                                ? {}
+                                : { audioProcessing: options.audioProcessing }),
+                            ...(options.execution === undefined ? {} : { execution: options.execution }),
+                        }, signal, onProgress, (await requireMastering()).render, { ir, media });
+                        if (options.profile === 'mp4-h264-aac') {
+                            return await exportFrozenRenderIrMp4(frozen);
+                        }
+                        if (options.profile === 'mp4-av1-aac') {
+                            return await exportFrozenRenderIrAv1Mp4(frozen);
+                        }
+                        if (options.profile === 'mp4-hevc-aac') {
+                            return await exportFrozenRenderIrHevcMp4(frozen);
+                        }
+                        return await exportFrozenRenderIrWebM(frozen);
+                    }
+                    if (options.profile === 'audio-wav') {
+                        return await exportWav({
+                            durationUs: ir.durationUs,
+                            sampleRate: ir.sampleRate,
+                            channelCount: channelCountForLayout(ir.channelLayout),
+                            sink: options.sink,
+                            renderAudio,
+                            signal,
+                            onProgress,
+                            ...(options.sampleFormat === undefined ? {} : { sampleFormat: options.sampleFormat }),
+                            ...(cleanup === undefined ? {} : { cleanupSink: cleanup }),
+                        });
+                    }
+                    if (options.profile === 'animated-gif') {
+                        return await exportGif({
+                            durationUs: ir.durationUs,
+                            width: ir.width,
+                            height: ir.height,
+                            frameRate: ir.frameRate,
+                            sink: options.sink,
+                            renderFrame,
+                            signal,
+                            onProgress,
+                            ...(options.loopCount === undefined ? {} : { loopCount: options.loopCount }),
+                            ...(cleanup === undefined ? {} : { cleanupSink: cleanup }),
+                        });
+                    }
+                    const format = options.profile === 'still-png'
+                        ? 'png'
+                        : options.profile === 'still-jpeg'
+                            ? 'jpeg'
+                            : 'webp';
+                    if (!('timeUs' in options))
+                        throw new TypeError('Unsupported export profile');
+                    return await exportStillImage({
+                        timeUs: options.timeUs,
+                        width: ir.width,
+                        height: ir.height,
+                        format,
+                        sink: options.sink,
+                        renderFrame,
+                        signal,
+                        ...(options.quality === undefined ? {} : { quality: options.quality }),
+                        ...(cleanup === undefined ? {} : { cleanupSink: cleanup }),
+                    });
+                }
+                catch (error) {
+                    this.#recordErrorDiagnostics(error);
+                    throw error;
+                }
+            },
+            onSnapshot: snapshot => this.#acceptExportSnapshot(snapshot),
+            onSettled: settled => {
+                if (this.#activeExportJob === settled)
+                    this.#activeExportJob = undefined;
+                this.#emitStats();
+            },
+        });
+        this.#activeExportJob = job;
+        this.#emitStats();
+        return job;
+    }
+    #startRemoteExport(options) {
+        this.#assertActive();
+        if (this.#activeExportJob?.state === 'running') {
+            const diagnostic = {
+                code: 'EXPORT_JOB_ACTIVE',
+                severity: 'error',
+                message: 'AelionSession supports one active export; cancel it before starting another',
+                recoverable: true,
+            };
+            this.#recordDiagnostic(diagnostic);
+            throw new AelionError([diagnostic]);
+        }
+        const engine = this.#engine;
+        const ir = this.requireIr();
+        const sequenceId = this.#sequenceId;
+        if (engine === undefined || sequenceId === undefined)
+            throw unloaded();
+        const project = engine.getSnapshot();
+        const revision = ir.revision.toString();
+        const manifest = options.manifest ??
+            {
+                protocol: 'aelion.remote-export/1',
+                profileId: options.profile,
+                sequenceId,
+                revision,
+                project,
+            };
+        const canonicalManifestBytes = new TextEncoder().encode(canonicalStringify(manifest));
+        const id = `export-${this.#nextExportJobId.toString()}`;
+        this.#nextExportJobId += 1;
+        this.#exportJobsStarted += 1;
+        const job = new ExportJob({
+            id,
+            ...(options.signal === undefined ? {} : { externalSignal: options.signal }),
+            run: async (signal, updateProgress) => {
+                try {
+                    const contentId = await createRemoteExportContentId(canonicalManifestBytes, options.profile, revision);
+                    return await runRemoteExport({
+                        provider: options.provider,
+                        authorizer: options.authorizer,
+                        request: {
+                            contentId,
+                            idempotencyKey: options.idempotencyKey ?? contentId,
+                            profileId: options.profile,
+                            projectId: project.projectId,
+                            sequenceId,
+                            revision,
+                            manifest,
+                        },
+                        signal,
+                        onProgress: (progress, stage) => {
+                            updateProgress(progress);
+                            options.onProgress?.(progress, stage);
+                        },
+                    });
+                }
+                catch (error) {
+                    this.#recordErrorDiagnostics(error);
+                    throw error;
+                }
+            },
+            onSnapshot: snapshot => this.#acceptExportSnapshot(snapshot),
+            onSettled: settled => {
+                if (this.#activeExportJob === settled)
+                    this.#activeExportJob = undefined;
+                this.#emitStats();
+            },
+        });
+        this.#activeExportJob = job;
+        this.#emitStats();
+        return job;
+    }
+    async #cancelExport(reason) {
+        await this.#activeExportJob?.cancel(reason);
+    }
+    #acceptExportSnapshot(snapshot) {
+        if (snapshot.state === 'completed')
+            this.#exportJobsCompleted += 1;
+        else if (snapshot.state === 'cancelled')
+            this.#exportJobsCancelled += 1;
+        else if (snapshot.state === 'failed')
+            this.#exportJobsFailed += 1;
+        this.#emitStats();
+    }
+    #recordErrorDiagnostics(error) {
+        if (error === null || typeof error !== 'object')
+            return 0;
+        const diagnostics = Reflect.get(error, 'diagnostics');
+        if (!Array.isArray(diagnostics))
+            return 0;
+        let recorded = 0;
+        for (const diagnostic of diagnostics) {
+            if (this.#isDiagnostic(diagnostic)) {
+                this.#recordDiagnostic(diagnostic);
+                recorded += 1;
+            }
+        }
+        return recorded;
+    }
+    #acceptPlayerError(error) {
+        if (this.#recordErrorDiagnostics(error) === 0) {
+            this.#recordDiagnostic({
+                code: 'PLAYER_RUNTIME_FAILED',
+                severity: 'error',
+                message: error instanceof Error ? error.message : 'Player runtime failed',
+                recoverable: true,
+                cause: error,
+            });
+        }
+        this.#emitStats();
+    }
+    #isDiagnostic(value) {
+        return (value !== null &&
+            typeof value === 'object' &&
+            typeof Reflect.get(value, 'code') === 'string' &&
+            typeof Reflect.get(value, 'message') === 'string' &&
+            typeof Reflect.get(value, 'recoverable') === 'boolean');
+    }
+    #recordDiagnostic(diagnostic) {
+        if (this.#diagnostics.length === this.#maxDiagnostics) {
+            this.#diagnostics.shift();
+            this.#droppedDiagnostics += 1;
+        }
+        this.#diagnostics.push(diagnostic);
+        this.#emit({ type: 'diagnostic', diagnostic });
+    }
+    #setState(state) {
+        if (this.#state === state)
+            return;
+        const previousState = this.#state;
+        this.#state = state;
+        this.#emit({ type: 'state-changed', previousState, state });
+    }
+    #emitStats() {
+        this.#emit({ type: 'stats-changed', stats: this.getStats() });
+    }
+    #assertActive() {
+        if (this.#state === 'disposed')
+            throw new ReferenceError('AelionSession is disposed');
+    }
+    #assertLoadCurrent(generation) {
+        if (this.#state === 'disposed')
+            throw new ReferenceError('AelionSession is disposed');
+        if (generation !== this.#loadGeneration) {
+            throw new DOMException('AelionSession Project load was superseded', 'AbortError');
+        }
+    }
+    #requireRenderer() {
+        this.#assertActive();
+        this.#renderer ??= new RenderIrFrameRenderer({
+            ...(this.#options.maxPendingFrames === undefined
+                ? {}
+                : { maxPendingFrames: this.#options.maxPendingFrames }),
+            ...(this.#options.runtimeAssets?.rendererWorker === undefined
+                ? {}
+                : { workerUrl: this.#options.runtimeAssets.rendererWorker }),
+        });
+        return this.#renderer;
+    }
+    #requireCommands() {
+        this.#assertTransactionAvailable();
+        if (this.#commands === undefined)
+            throw unloaded();
+        return this.#commands;
+    }
+    #emit(event) {
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Consumer callbacks must not corrupt SDK state or stop other subscribers.
+            }
+        }
+    }
+}