@aelionsdk/sdk 0.1.0-beta.1

package/dist/persistence.d.ts

@@ -0,0 +1,73 @@
+import { type AelionProject } from '@aelionsdk/project-schema';
+import type { AelionSessionApi } from './types.js';
+export declare const PROJECT_REVISION_RECORD_VERSION: "aelion.project-revision/1";
+export interface ProjectRevisionRecord {
+    readonly version: typeof PROJECT_REVISION_RECORD_VERSION;
+    readonly projectId: string;
+    /** Monotonic store generation; unlike Session revision, this survives reloads. */
+    readonly generation: number;
+    /** Transaction revision that triggered this snapshot inside its source Session. */
+    readonly sourceRevision: string;
+    readonly savedAtEpochMs: number;
+    readonly canonicalProject: string;
+    readonly contentHash: string;
+}
+export interface ProjectRevisionStore {
+    loadLatest(projectId: string): Promise<ProjectRevisionRecord | null>;
+    /**
+     * Atomically keeps the record with the greatest generation.
+     * Implementations must not replace a newer record with a stale write.
+     */
+    saveLatest(record: ProjectRevisionRecord): Promise<void>;
+    remove(projectId: string): Promise<void>;
+}
+export declare class MemoryProjectRevisionStore implements ProjectRevisionStore {
+    #private;
+    loadLatest(projectId: string): Promise<ProjectRevisionRecord | null>;
+    saveLatest(record: ProjectRevisionRecord): Promise<void>;
+    remove(projectId: string): Promise<void>;
+}
+export interface IndexedDbProjectRevisionStoreOptions {
+    readonly databaseName?: string;
+}
+/** Browser persistence with an atomic stale-generation guard. */
+export declare class IndexedDbProjectRevisionStore implements ProjectRevisionStore {
+    #private;
+    constructor(options?: IndexedDbProjectRevisionStoreOptions);
+    loadLatest(projectId: string): Promise<ProjectRevisionRecord | null>;
+    saveLatest(record: ProjectRevisionRecord): Promise<void>;
+    remove(projectId: string): Promise<void>;
+}
+export interface ProjectPersistenceOptions {
+    readonly debounceMs?: number;
+    readonly saveInitial?: boolean;
+    readonly onError?: (error: unknown) => void;
+    readonly now?: () => number;
+}
+export interface ProjectPersistenceSnapshot {
+    readonly projectId: string;
+    readonly pendingRevision: bigint | null;
+    readonly lastSavedRevision: bigint | null;
+    readonly generation: number;
+    readonly disposed: boolean;
+    readonly error: unknown;
+}
+/**
+ * Serializes immutable Project snapshots in revision order. Call `flush` before
+ * navigation when durability matters; `dispose` also flushes the trailing edit.
+ */
+export declare class ProjectPersistenceController {
+    #private;
+    private constructor();
+    static attach(session: AelionSessionApi, store: ProjectRevisionStore, options?: ProjectPersistenceOptions): Promise<ProjectPersistenceController>;
+    getSnapshot(): ProjectPersistenceSnapshot;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface RestoredProjectRevision {
+    readonly record: ProjectRevisionRecord;
+    readonly project: Readonly<AelionProject>;
+}
+/** Verifies the canonical content hash before loading a stored Project. */
+export declare function restoreLatestProject(session: AelionSessionApi, store: ProjectRevisionStore, projectId: string): Promise<RestoredProjectRevision | null>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

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

package/dist/persistence.js

@@ -0,0 +1,245 @@
+import { canonicalHash, canonicalStringify } from '@aelionsdk/project-schema';
+export const PROJECT_REVISION_RECORD_VERSION = 'aelion.project-revision/1';
+function cloneRecord(record) {
+    return structuredClone(record);
+}
+function assertRecord(value, projectId) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError('Invalid Aelion Project revision record');
+    }
+    const record = value;
+    if (record.version !== PROJECT_REVISION_RECORD_VERSION ||
+        typeof record.projectId !== 'string' ||
+        (projectId !== undefined && record.projectId !== projectId) ||
+        typeof record.generation !== 'number' ||
+        !Number.isSafeInteger(record.generation) ||
+        record.generation < 0 ||
+        typeof record.sourceRevision !== 'string' ||
+        !/^(0|[1-9]\d*)$/u.test(record.sourceRevision) ||
+        typeof record.savedAtEpochMs !== 'number' ||
+        !Number.isFinite(record.savedAtEpochMs) ||
+        typeof record.canonicalProject !== 'string' ||
+        record.canonicalProject.length === 0 ||
+        typeof record.contentHash !== 'string' ||
+        record.contentHash.length === 0) {
+        throw new TypeError('Invalid Aelion Project revision record');
+    }
+}
+function persistenceError(value) {
+    return value instanceof Error ? value : new Error('Project persistence failed', { cause: value });
+}
+export class MemoryProjectRevisionStore {
+    #records = new Map();
+    loadLatest(projectId) {
+        const record = this.#records.get(projectId);
+        return Promise.resolve(record === undefined ? null : cloneRecord(record));
+    }
+    saveLatest(record) {
+        assertRecord(record);
+        const current = this.#records.get(record.projectId);
+        if (current === undefined || record.generation > current.generation) {
+            this.#records.set(record.projectId, cloneRecord(record));
+        }
+        return Promise.resolve();
+    }
+    remove(projectId) {
+        this.#records.delete(projectId);
+        return Promise.resolve();
+    }
+}
+function requestResult(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'));
+    });
+}
+function transactionComplete(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onabort = () => reject(transaction.error ?? new DOMException('IndexedDB transaction aborted', 'AbortError'));
+        transaction.onerror = () => reject(transaction.error ?? new Error('IndexedDB transaction failed'));
+    });
+}
+/** Browser persistence with an atomic stale-generation guard. */
+export class IndexedDbProjectRevisionStore {
+    #database;
+    constructor(options = {}) {
+        if (typeof indexedDB === 'undefined') {
+            throw new Error('IndexedDB is unavailable in this environment');
+        }
+        const request = indexedDB.open(options.databaseName ?? 'aelion-projects', 1);
+        request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains('project-revisions')) {
+                request.result.createObjectStore('project-revisions', { keyPath: 'projectId' });
+            }
+        };
+        this.#database = requestResult(request);
+    }
+    async loadLatest(projectId) {
+        const database = await this.#database;
+        const transaction = database.transaction('project-revisions', 'readonly');
+        const value = await requestResult(transaction.objectStore('project-revisions').get(projectId));
+        await transactionComplete(transaction);
+        if (value === undefined)
+            return null;
+        assertRecord(value, projectId);
+        return cloneRecord(value);
+    }
+    async saveLatest(record) {
+        assertRecord(record);
+        const database = await this.#database;
+        const transaction = database.transaction('project-revisions', 'readwrite');
+        const store = transaction.objectStore('project-revisions');
+        const current = await requestResult(store.get(record.projectId));
+        if (current !== undefined)
+            assertRecord(current, record.projectId);
+        if (current === undefined || record.generation > current.generation) {
+            store.put(cloneRecord(record));
+        }
+        await transactionComplete(transaction);
+    }
+    async remove(projectId) {
+        const database = await this.#database;
+        const transaction = database.transaction('project-revisions', 'readwrite');
+        transaction.objectStore('project-revisions').delete(projectId);
+        await transactionComplete(transaction);
+    }
+}
+/**
+ * Serializes immutable Project snapshots in revision order. Call `flush` before
+ * navigation when durability matters; `dispose` also flushes the trailing edit.
+ */
+export class ProjectPersistenceController {
+    #session;
+    #store;
+    #projectId;
+    #debounceMs;
+    #onError;
+    #now;
+    #unsubscribe;
+    #pending;
+    #timer;
+    #tail = Promise.resolve();
+    #generation;
+    #lastSavedRevision = null;
+    #error;
+    #disposed = false;
+    constructor(session, store, projectId, generation, options) {
+        this.#session = session;
+        this.#store = store;
+        this.#projectId = projectId;
+        this.#generation = generation;
+        this.#debounceMs = options.debounceMs ?? 250;
+        if (!Number.isFinite(this.#debounceMs) || this.#debounceMs < 0) {
+            throw new RangeError('debounceMs must be a non-negative finite number');
+        }
+        this.#onError = options.onError;
+        this.#now = options.now ?? Date.now;
+        this.#unsubscribe = session.subscribe('project-changed', event => {
+            this.#schedule(event.commit.revision);
+        });
+        if (options.saveInitial ?? true) {
+            const revision = session.revision;
+            if (revision !== null)
+                this.#schedule(revision);
+        }
+    }
+    static async attach(session, store, options = {}) {
+        const project = session.getSnapshot().project;
+        if (project === null)
+            throw new Error('Load an Aelion Project before attaching persistence');
+        const latest = await store.loadLatest(project.projectId);
+        return new ProjectPersistenceController(session, store, project.projectId, latest?.generation ?? 0, options);
+    }
+    getSnapshot() {
+        return {
+            projectId: this.#projectId,
+            pendingRevision: this.#pending?.sourceRevision ?? null,
+            lastSavedRevision: this.#lastSavedRevision,
+            generation: this.#generation,
+            disposed: this.#disposed,
+            error: this.#error,
+        };
+    }
+    async flush() {
+        this.#enqueuePending();
+        await this.#tail;
+        if (this.#error !== undefined)
+            throw persistenceError(this.#error);
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#unsubscribe();
+        await this.flush();
+    }
+    #schedule(revision) {
+        if (this.#disposed)
+            return;
+        const project = this.#session.getSnapshot().project;
+        if (project === null || project.projectId !== this.#projectId) {
+            const error = new Error('Persistence controller cannot follow a different Project');
+            this.#error = error;
+            this.#onError?.(error);
+            return;
+        }
+        this.#pending = {
+            project: structuredClone(project),
+            sourceRevision: revision,
+        };
+        if (this.#timer !== undefined)
+            clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => this.#enqueuePending(), this.#debounceMs);
+    }
+    #enqueuePending() {
+        if (this.#timer !== undefined) {
+            clearTimeout(this.#timer);
+            this.#timer = undefined;
+        }
+        const pending = this.#pending;
+        if (pending === undefined)
+            return;
+        this.#pending = undefined;
+        const generation = this.#generation + 1;
+        this.#generation = generation;
+        this.#tail = this.#tail.then(async () => {
+            try {
+                const canonicalProject = canonicalStringify(pending.project);
+                const contentHash = await canonicalHash(pending.project);
+                await this.#store.saveLatest({
+                    version: PROJECT_REVISION_RECORD_VERSION,
+                    projectId: this.#projectId,
+                    generation,
+                    sourceRevision: pending.sourceRevision.toString(),
+                    savedAtEpochMs: this.#now(),
+                    canonicalProject,
+                    contentHash,
+                });
+                this.#lastSavedRevision = pending.sourceRevision;
+                this.#error = undefined;
+            }
+            catch (error) {
+                this.#error = error;
+                this.#onError?.(error);
+            }
+        });
+    }
+}
+/** Verifies the canonical content hash before loading a stored Project. */
+export async function restoreLatestProject(session, store, projectId) {
+    const record = await store.loadLatest(projectId);
+    if (record === null)
+        return null;
+    assertRecord(record, projectId);
+    const parsed = JSON.parse(record.canonicalProject);
+    const contentHash = await canonicalHash(parsed);
+    if (contentHash !== record.contentHash) {
+        throw new Error(`Stored Aelion Project ${projectId} failed its content-hash check`);
+    }
+    await session.loadProject(parsed);
+    const project = session.getSnapshot().project;
+    if (project === null)
+        throw new Error('Restored Project did not enter the Session');
+    return { record, project };
+}

package/dist/player.d.ts

@@ -0,0 +1,22 @@
+import type { ChangeSet } from '@aelionsdk/transaction';
+import type { AelionSession } from './session.js';
+import type { AelionPlayerApi, AelionPlayerFrame, AelionPlayerStats, AelionPlayerState, AelionRuntimeAssets } from './types.js';
+type RuntimeErrorListener = (error: unknown) => void;
+export declare class AelionPlayer implements AelionPlayerApi {
+    #private;
+    constructor(session: AelionSession, onRuntimeError?: RuntimeErrorListener, runtimeAssets?: AelionRuntimeAssets);
+    get state(): AelionPlayerState;
+    get currentTimeUs(): number;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seek(timeUs: number): Promise<void>;
+    scrub(timeUs: number): Promise<import("@aelionsdk/renderer-worker").RenderIrFrameResult>;
+    setPreviewQuality(options: Parameters<AelionPlayerApi['setPreviewQuality']>[0]): void;
+    getStats(): AelionPlayerStats;
+    subscribe(listener: (frame: AelionPlayerFrame) => void): () => void;
+    invalidate(changeSet: ChangeSet): void;
+    reset(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=player.d.ts.map

package/dist/player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.d.ts","sourceRoot":"","sources":["../src/player.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAEjB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAIpB,KAAK,oBAAoB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAiBrD,qBAAa,YAAa,YAAW,eAAe;;gBA2BhD,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,oBAAoB,EACrC,aAAa,CAAC,EAAE,mBAAmB;IAOrC,IAAW,KAAK,IAAI,iBAAiB,CAEpC;IAED,IAAW,aAAa,IAAI,MAAM,CAKjC;IAEY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAWtB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCzC,KAAK,CAAC,MAAM,EAAE,MAAM;IAIpB,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAOrF,QAAQ,IAAI,iBAAiB;IAwD7B,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI;IASnE,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAahC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAsShC"}