@aelionsdk/sdk 0.1.0-beta.1

package/dist/extension-host.js

@@ -0,0 +1,367 @@
+export const AELION_EXTENSION_PROTOCOL = 'aelion.extension/1';
+function positiveInteger(value, fallback, name) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    return resolved;
+}
+function payloadBytes(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new TypeError('Extension payload must be acyclic JSON');
+    }
+    if (typeof serialized !== 'string')
+        throw new TypeError('Extension payload must be JSON');
+    return new TextEncoder().encode(serialized).byteLength;
+}
+function clonePayload(value, maximum) {
+    if (payloadBytes(value) > maximum) {
+        throw new RangeError(`Extension payload exceeds ${maximum.toString()} bytes`);
+    }
+    return structuredClone(value);
+}
+function validManifest(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const manifest = value;
+    return (typeof manifest.id === 'string' &&
+        /^[A-Za-z][A-Za-z0-9._:-]*$/u.test(manifest.id) &&
+        typeof manifest.version === 'string' &&
+        manifest.version.length > 0 &&
+        Array.isArray(manifest.methods) &&
+        manifest.methods.length > 0 &&
+        manifest.methods.every(method => typeof method === 'string' && /^[A-Za-z][A-Za-z0-9._:-]*$/u.test(method)) &&
+        new Set(manifest.methods).size === manifest.methods.length);
+}
+function asWorkerMessage(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const message = value;
+    if (message.protocol !== AELION_EXTENSION_PROTOCOL)
+        return undefined;
+    if (message.type === 'ready' && validManifest(message.manifest)) {
+        return message;
+    }
+    if (message.type === 'result' &&
+        Number.isSafeInteger(message.id) &&
+        (message.id ?? 0) > 0 &&
+        'payload' in message) {
+        return message;
+    }
+    if (message.type === 'error' &&
+        Number.isSafeInteger(message.id) &&
+        (message.id ?? 0) > 0 &&
+        typeof message.name === 'string' &&
+        typeof message.message === 'string') {
+        return message;
+    }
+    return undefined;
+}
+function asHostMessage(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const message = value;
+    if (message.protocol !== AELION_EXTENSION_PROTOCOL)
+        return undefined;
+    if (message.type === 'initialize' &&
+        Number.isSafeInteger(message.maxPayloadBytes) &&
+        message.maxPayloadBytes > 0) {
+        return message;
+    }
+    if (message.type === 'invoke' &&
+        Number.isSafeInteger(message.id) &&
+        message.id > 0 &&
+        typeof message.method === 'string' &&
+        /^[A-Za-z][A-Za-z0-9._:-]*$/u.test(message.method) &&
+        'payload' in message) {
+        return message;
+    }
+    if (message.type === 'cancel' && Number.isSafeInteger(message.id) && message.id > 0) {
+        return message;
+    }
+    return undefined;
+}
+function abortRejection(reason) {
+    return reason instanceof Error
+        ? reason
+        : new DOMException('Extension call aborted', 'AbortError');
+}
+/**
+ * Fault-isolated RPC host for extension module Workers. The Worker receives
+ * cloned JSON only—never Session, media providers, DOM nodes or credentials.
+ */
+export class AelionExtensionHost {
+    #transport;
+    #maxPendingCalls;
+    #maxPayloadBytes;
+    #invocationTimeoutMs;
+    #pending = new Map();
+    #readyPromise;
+    #resolveReady;
+    #rejectReady;
+    #handshakeTimer;
+    #manifest;
+    #nextRequestId = 1;
+    #disposed = false;
+    constructor(transport, options = {}) {
+        this.#transport = transport;
+        this.#maxPendingCalls = positiveInteger(options.maxPendingCalls, 8, 'maxPendingCalls');
+        this.#maxPayloadBytes = positiveInteger(options.maxPayloadBytes, 1_048_576, 'maxPayloadBytes');
+        this.#invocationTimeoutMs = positiveInteger(options.invocationTimeoutMs, 5_000, 'invocationTimeoutMs');
+        const handshakeTimeoutMs = positiveInteger(options.handshakeTimeoutMs, 5_000, 'handshakeTimeoutMs');
+        this.#readyPromise = new Promise((resolve, reject) => {
+            this.#resolveReady = resolve;
+            this.#rejectReady = reject;
+        });
+        this.#transport.addEventListener('message', this.#handleMessage);
+        this.#transport.addEventListener('error', this.#handleError);
+        this.#handshakeTimer = setTimeout(() => {
+            this.#fault(new DOMException('Extension handshake timed out', 'TimeoutError'));
+        }, handshakeTimeoutMs);
+        this.#transport.postMessage({
+            protocol: AELION_EXTENSION_PROTOCOL,
+            type: 'initialize',
+            maxPayloadBytes: this.#maxPayloadBytes,
+        });
+    }
+    get ready() {
+        return this.#readyPromise;
+    }
+    snapshot() {
+        return {
+            ready: this.#manifest !== undefined,
+            disposed: this.#disposed,
+            pendingCalls: this.#pending.size,
+            nextRequestId: this.#nextRequestId,
+            manifest: this.#manifest === undefined ? null : structuredClone(this.#manifest),
+        };
+    }
+    async invoke(method, payload, options = {}) {
+        const manifest = await this.#readyPromise;
+        if (this.#disposed)
+            throw new ReferenceError('AelionExtensionHost is disposed');
+        if (!manifest.methods.includes(method)) {
+            throw new ReferenceError(`Extension ${manifest.id} does not expose ${method}`);
+        }
+        if (this.#pending.size >= this.#maxPendingCalls) {
+            throw new RangeError(`Extension call queue reached its ${this.#maxPendingCalls.toString()} call limit`);
+        }
+        if (options.signal?.aborted === true) {
+            throw options.signal.reason ?? new DOMException('Extension call aborted', 'AbortError');
+        }
+        const clonedPayload = clonePayload(payload, this.#maxPayloadBytes);
+        const id = this.#nextRequestId;
+        this.#nextRequestId += 1;
+        const timeoutMs = positiveInteger(options.timeoutMs, this.#invocationTimeoutMs, 'timeoutMs');
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#fault(new DOMException(`Extension call ${method} timed out`, 'TimeoutError'));
+            }, timeoutMs);
+            const abort = options.signal === undefined
+                ? undefined
+                : () => {
+                    const pending = this.#pending.get(id);
+                    if (pending === undefined)
+                        return;
+                    this.#settle(id, () => {
+                        this.#transport.postMessage({
+                            protocol: AELION_EXTENSION_PROTOCOL,
+                            type: 'cancel',
+                            id,
+                        });
+                        reject(abortRejection(options.signal?.reason));
+                    });
+                };
+            this.#pending.set(id, {
+                resolve,
+                reject,
+                timer,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                ...(abort === undefined ? {} : { abort }),
+            });
+            options.signal?.addEventListener('abort', abort, { once: true });
+            try {
+                this.#transport.postMessage({
+                    protocol: AELION_EXTENSION_PROTOCOL,
+                    type: 'invoke',
+                    id,
+                    method,
+                    payload: clonedPayload,
+                });
+            }
+            catch (error) {
+                this.#fault(error);
+            }
+        });
+    }
+    dispose(reason = new DOMException('Extension host disposed', 'AbortError')) {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        clearTimeout(this.#handshakeTimer);
+        this.#transport.removeEventListener('message', this.#handleMessage);
+        this.#transport.removeEventListener('error', this.#handleError);
+        this.#transport.terminate();
+        this.#rejectReady(reason);
+        for (const [id, pending] of this.#pending) {
+            this.#settle(id, () => pending.reject(reason));
+        }
+    }
+    #handleMessage = (event) => {
+        if (this.#disposed)
+            return;
+        const message = asWorkerMessage(event.data);
+        if (message === undefined) {
+            this.#fault(new TypeError('Extension emitted an invalid protocol message'));
+            return;
+        }
+        if (message.type === 'ready') {
+            if (this.#manifest !== undefined) {
+                this.#fault(new TypeError('Extension emitted duplicate ready messages'));
+                return;
+            }
+            try {
+                if (payloadBytes(message.manifest) > this.#maxPayloadBytes) {
+                    throw new RangeError('Extension manifest exceeds the payload budget');
+                }
+            }
+            catch (error) {
+                this.#fault(error);
+                return;
+            }
+            clearTimeout(this.#handshakeTimer);
+            this.#manifest = structuredClone(message.manifest);
+            this.#resolveReady(structuredClone(message.manifest));
+            return;
+        }
+        const pending = this.#pending.get(message.id);
+        if (pending === undefined)
+            return;
+        if (message.type === 'result') {
+            try {
+                const payload = clonePayload(message.payload, this.#maxPayloadBytes);
+                this.#settle(message.id, () => pending.resolve(payload));
+            }
+            catch (error) {
+                this.#fault(error);
+            }
+            return;
+        }
+        this.#settle(message.id, () => {
+            const error = new Error(message.message);
+            error.name = message.name;
+            pending.reject(error);
+        });
+    };
+    #handleError = (event) => {
+        this.#fault(event.error ?? new Error(event.message || 'Extension Worker failed'));
+    };
+    #settle(id, callback) {
+        const pending = this.#pending.get(id);
+        if (pending === undefined)
+            return;
+        this.#pending.delete(id);
+        clearTimeout(pending.timer);
+        if (pending.signal !== undefined && pending.abort !== undefined) {
+            pending.signal.removeEventListener('abort', pending.abort);
+        }
+        callback();
+    }
+    #fault(error) {
+        if (this.#disposed)
+            return;
+        const ready = this.#manifest !== undefined;
+        this.dispose(error);
+        if (ready) {
+            // `dispose` rejects all invocations. The ready Promise is already settled.
+            return;
+        }
+    }
+}
+/**
+ * Worker-side counterpart. It exposes an explicit method table and supports
+ * cooperative cancellation without importing or receiving the editor Session.
+ */
+export function exposeAelionExtension(endpoint, manifest, handlers) {
+    if (!validManifest(manifest))
+        throw new TypeError('Invalid Aelion extension manifest');
+    for (const method of manifest.methods) {
+        if (handlers[method] === undefined) {
+            throw new ReferenceError(`Missing extension handler ${method}`);
+        }
+    }
+    const active = new Map();
+    let maximumPayloadBytes;
+    const listener = (event) => {
+        const message = asHostMessage(event.data);
+        if (message === undefined)
+            return;
+        if (message.type === 'initialize') {
+            if (maximumPayloadBytes !== undefined)
+                return;
+            maximumPayloadBytes = message.maxPayloadBytes;
+            endpoint.postMessage({
+                protocol: AELION_EXTENSION_PROTOCOL,
+                type: 'ready',
+                manifest: structuredClone(manifest),
+            });
+            return;
+        }
+        if (message.type === 'cancel') {
+            active.get(message.id)?.abort(new DOMException('Extension call aborted', 'AbortError'));
+            return;
+        }
+        if (maximumPayloadBytes === undefined || active.has(message.id))
+            return;
+        const maximum = maximumPayloadBytes;
+        const handler = handlers[message.method];
+        if (handler === undefined) {
+            endpoint.postMessage({
+                protocol: AELION_EXTENSION_PROTOCOL,
+                type: 'error',
+                id: message.id,
+                name: 'ReferenceError',
+                message: `Unknown extension method ${message.method}`,
+            });
+            return;
+        }
+        const controller = new AbortController();
+        active.set(message.id, controller);
+        void Promise.resolve()
+            .then(() => handler(clonePayload(message.payload, maximum), { signal: controller.signal }))
+            .then(payload => {
+            if (controller.signal.aborted)
+                return;
+            endpoint.postMessage({
+                protocol: AELION_EXTENSION_PROTOCOL,
+                type: 'result',
+                id: message.id,
+                payload: clonePayload(payload, maximum),
+            });
+        })
+            .catch((error) => {
+            if (controller.signal.aborted)
+                return;
+            endpoint.postMessage({
+                protocol: AELION_EXTENSION_PROTOCOL,
+                type: 'error',
+                id: message.id,
+                name: error instanceof Error ? error.name : 'Error',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => active.delete(message.id));
+    };
+    endpoint.addEventListener('message', listener);
+    return () => {
+        endpoint.removeEventListener('message', listener);
+        for (const controller of active.values()) {
+            controller.abort(new DOMException('Extension runtime disposed', 'AbortError'));
+        }
+        active.clear();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { AelionApi } from './types.js';
+export * from './runtime-material-registry.js';
+export * from './media-provider.js';
+export * from './production-media-provider.js';
+export * from './project-builder.js';
+export * from './composition.js';
+export * from './migration.js';
+export * from './migration-materials.js';
+export * from './audio-controller.js';
+export * from './audio-mastering.js';
+export * from './persistence.js';
+export * from './extension-host.js';
+export * from './preview-controller.js';
+export * from './default-schemas.js';
+export * from './session.js';
+export * from './types.js';
+export declare const Aelion: AelionApi;
+//# 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":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qBAAqB,CAAC;AACpC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAE3B,eAAO,MAAM,MAAM,EAAE,SAEpB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+import { AelionSession } from './session.js';
+export * from './runtime-material-registry.js';
+export * from './media-provider.js';
+export * from './production-media-provider.js';
+export * from './project-builder.js';
+export * from './composition.js';
+export * from './migration.js';
+export * from './migration-materials.js';
+export * from './audio-controller.js';
+export * from './audio-mastering.js';
+export * from './persistence.js';
+export * from './extension-host.js';
+export * from './preview-controller.js';
+export * from './default-schemas.js';
+export * from './session.js';
+export * from './types.js';
+export const Aelion = {
+    createSession: options => Promise.resolve(new AelionSession(options)),
+};

package/dist/media-provider.d.ts

@@ -0,0 +1,49 @@
+import type { PcmSourceBlock } from '@aelionsdk/audio';
+import type { AelionMediaProvider } from './types.js';
+export type AelionAssetBytesResolver = (assetId: string, signal?: AbortSignal) => Promise<Uint8Array>;
+export interface ByteMediaProviderOptions {
+    readonly resolveAssetBytes: AelionAssetBytesResolver;
+    readonly maxCachedBytes?: number;
+    /** Maximum byte-load, SampleIndex and decode operations allowed at once. Defaults to 4. */
+    readonly maxConcurrentOperations?: number;
+    /** Maximum bounded operations waiting for a slot. Defaults to 64. */
+    readonly maxPendingOperations?: number;
+    /** Compatibility alias for maxConcurrentOperations; covers load, index and decode work. */
+    readonly maxConcurrentLoads?: number;
+}
+/**
+ * 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 declare class ByteMediaProvider implements AelionMediaProvider {
+    #private;
+    constructor(options: ByteMediaProviderOptions);
+    frameAt(assetId: string, streamIndex: number, sourceTimeUs: number, signal?: AbortSignal): Promise<VideoFrame>;
+    pcmRange(assetId: string, streamIndex: number, startUs: number, durationUs: number, signal?: AbortSignal): Promise<PcmSourceBlock>;
+    clear(): void;
+    snapshot(): {
+        readonly assets: number;
+        readonly cachedBytes: number;
+        readonly maxCachedBytes: number;
+        readonly inFlightAssetLoads: number;
+        readonly inFlightSampleIndexes: number;
+        /** Public frameAt/pcmRange calls currently admitted across their full lifecycle. */
+        readonly inFlightRequests: number;
+        /** Hard request cap, derived as maxConcurrentOperations + maxPendingOperations. */
+        readonly maxInFlightRequests: number;
+        /** Subscribers retained by active single-flight load and index operations. */
+        readonly sharedOperationSubscribers: number;
+        readonly activeOperations: number;
+        readonly pendingOperations: number;
+        readonly maxConcurrentOperations: number;
+        readonly maxPendingOperations: number;
+        /** Compatibility alias for activeOperations. */
+        readonly activeLoads: number;
+        /** Compatibility alias for pendingOperations. */
+        readonly pendingLoads: number;
+        /** Compatibility alias for maxConcurrentOperations. */
+        readonly maxConcurrentLoads: number;
+    };
+}
+//# sourceMappingURL=media-provider.d.ts.map

package/dist/media-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-provider.d.ts","sourceRoot":"","sources":["../src/media-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAWvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,iBAAiB,EAAE,wBAAwB,CAAC;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAgID;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,mBAAmB;;gBAgBxC,OAAO,EAAE,wBAAwB;IA2BvC,OAAO,CAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC;IA+BT,QAAQ,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC;IAiBnB,KAAK,IAAI,IAAI;IAOb,QAAQ,IAAI;QACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;QACvC,oFAAoF;QACpF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,mFAAmF;QACnF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,8EAA8E;QAC9E,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;QAC5C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;QACnC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;QACzC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;QACtC,gDAAgD;QAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,iDAAiD;QACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,uDAAuD;QACvD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;KACrC;CA4NF"}