@alpha2-sh/editor 0.0.0-stage → 0.1.0

package/dist/browser/jobs.js

@@ -0,0 +1,291 @@
+import { classifyBrowserFailure, failureOf, withSecondaryFailure, } from "alpha2/export-failure";
+import { decideRetry, RETRY_PROFILES, } from "alpha2/export-retry";
+import { validFrameRate } from "alpha2/project";
+import { EditorError } from "../core/document.js";
+/**
+ * Refuses an export `frameRate` the engine cannot read, before an export starts, for every
+ * backend: one rate, the same everywhere.
+ */
+export function requireExportFrameRate(frameRate) {
+    if (frameRate !== undefined && !validFrameRate(frameRate))
+        throw new EditorError("invalid_frame_rate", `Export frameRate must be { num, den }, positive 32-bit integers with a frame at least one tick long; received ${JSON.stringify(frameRate)}`, "export");
+}
+/**
+ * One export of a pinned document, run in bounded attempts.
+ *
+ * Every attempt renders the same document from the start, on a fresh device or host, with the same
+ * output settings; a failed one is retried only as the retry policy allows, with less in flight
+ * when the failure is evidence of memory exhaustion. Progress from an attempt that has ended is
+ * ignored, so a late answer cannot move a newer attempt's progress or change its result. Cancelling
+ * stops the running attempt and any pending retry; no new attempt starts after it.
+ */
+export class ExportJob {
+    revision;
+    id;
+    /**
+     * Resolves to the artifact. Rejects with `EditorError` `cancelled` after {@link cancel}, or
+     * with the last attempt's error, whose `failure` property (and {@link failure}) holds the
+     * classified `ExportFailure`.
+     */
+    result;
+    #controller = new AbortController();
+    #listeners = new Set();
+    #progress = { phase: "preparing", fraction: 0 };
+    #settled = false;
+    #failure;
+    #attempts = [];
+    #current = 0;
+    /**
+     * Starts the job at once, on the next microtask.
+     *
+     * @param revision The editor revision `document` was pinned at.
+     * @param backend Runs each attempt; its `dispose` runs once when the job settles.
+     * @param release Called once when the job settles, whatever the outcome.
+     */
+    constructor(revision, document, backend, release = () => { }, options = {}) {
+        this.revision = revision;
+        this.id = options.id ?? crypto.randomUUID();
+        const signal = this.#controller.signal;
+        const progress = (value) => {
+            this.#progress = Object.freeze(value);
+            for (const listener of this.#listeners)
+                listener(this.#progress);
+        };
+        const cancelledBy = (cause) => signal.aborted &&
+            !(cause instanceof EditorError && cause.code === "cancel_failed");
+        this.result = this.#attempt(document, backend, progress, options)
+            .then(async (value) => {
+            // A cancel wins until the job settles, even over an attempt that already finished: what it
+            // made is released and the job settles as cancelled.
+            if (signal.aborted) {
+                this.#record(this.#current, {
+                    outcome: "cancelled",
+                    endedAt: Date.now(),
+                });
+                await releaseArtifact(value);
+                signal.throwIfAborted();
+            }
+            return value;
+        })
+            .then(async (value) => {
+            await backend.dispose?.({ ok: true, cancelled: false });
+            progress({
+                phase: "completed",
+                fraction: 1,
+                attempt: this.#current,
+            });
+            return value;
+        }, async (cause) => {
+            const cancelled = cancelledBy(cause);
+            let failure = cancelled
+                ? undefined
+                : {
+                    ...(failureOf(cause) ??
+                        classifyBrowserFailure(cause, {
+                            phase: phaseOf(this.#progress),
+                        })),
+                    jobId: this.id,
+                };
+            try {
+                await backend.dispose?.({ ok: false, cancelled });
+            }
+            catch (cleanup) {
+                // A failed job keeps its failure and notes the cleanup beside it.
+                if (cancelled)
+                    throw cleanup;
+                if (failure)
+                    failure = withSecondaryFailure(failure, {
+                        code: "UNKNOWN",
+                        phase: "cleanup",
+                        message: cleanup instanceof Error ? cleanup.message : String(cleanup),
+                    });
+            }
+            if (failure)
+                this.#failure = Object.freeze(failure);
+            throw cause;
+        })
+            .catch((cause) => {
+            const cancelled = cancelledBy(cause);
+            progress({
+                phase: cancelled ? "cancelled" : "failed",
+                fraction: this.#progress.fraction,
+                attempt: this.#current,
+            });
+            throw cancelled
+                ? new EditorError("cancelled", "Export cancelled", "export", undefined, true, { cause })
+                : cause;
+        })
+            .finally(() => {
+            this.#settled = true;
+            release();
+        });
+        // Jobs may be cancelled before the caller starts awaiting result.
+        void this.result.catch(() => { });
+    }
+    async #attempt(document, backend, progress, options) {
+        const signal = this.#controller.signal;
+        const policy = options.retry === false ? undefined : (options.retry ?? {});
+        const sleep = options.sleep ?? abortableSleep;
+        const history = [];
+        let profile = policy?.profiles?.[0] ?? RETRY_PROFILES[0];
+        await Promise.resolve();
+        for (let number = 1;; number += 1) {
+            signal.throwIfAborted();
+            const attempt = Object.freeze({
+                id: `${this.id}/${number}`,
+                number,
+                profile,
+                ...(history.length > 0 ? { previous: history.at(-1).failure } : {}),
+            });
+            this.#current = number;
+            this.#record(number, {
+                id: attempt.id,
+                number,
+                profile,
+                startedAt: Date.now(),
+                outcome: "running",
+            });
+            // Progress from an attempt that has ended belongs to nothing.
+            const report = (value) => {
+                if (this.#current === number && !this.#settled)
+                    progress({ ...value, attempt: number });
+            };
+            try {
+                const value = await backend.run(document, signal, report, attempt);
+                this.#record(number, { outcome: "succeeded", endedAt: Date.now() });
+                return value;
+            }
+            catch (cause) {
+                if (signal.aborted) {
+                    this.#record(number, { outcome: "cancelled", endedAt: Date.now() });
+                    throw cause;
+                }
+                // The next attempt owns progress from here: a late report from this one is dropped.
+                this.#current = number + 1;
+                const failure = {
+                    ...(failureOf(cause) ??
+                        classifyBrowserFailure(cause, {
+                            phase: phaseOf(this.#progress),
+                        })),
+                    jobId: this.id,
+                    attemptId: attempt.id,
+                };
+                history.push({ failure, profile });
+                const decision = policy
+                    ? decideRetry(history, policy)
+                    : { retry: false, reason: "retries are off for this job" };
+                this.#record(number, {
+                    outcome: "failed",
+                    endedAt: Date.now(),
+                    failure,
+                    decision: { retry: decision.retry, reason: decision.reason },
+                });
+                if (!decision.retry) {
+                    this.#current = number;
+                    if (cause instanceof Error)
+                        Object.defineProperty(cause, "failure", {
+                            value: failure,
+                            configurable: true,
+                        });
+                    throw cause;
+                }
+                progress({
+                    phase: "retrying",
+                    fraction: this.#progress.fraction,
+                    attempt: number + 1,
+                    retry: { reason: decision.reason, delayMs: decision.delayMs },
+                });
+                await sleep(decision.delayMs, signal);
+                profile = decision.profile;
+            }
+        }
+    }
+    #record(number, patch) {
+        const index = number - 1;
+        this.#attempts[index] = Object.freeze({
+            ...this.#attempts[index],
+            ...patch,
+        });
+    }
+    /** The latest progress, frozen. Reports from an attempt that has ended are not reflected. */
+    get progress() {
+        return this.#progress;
+    }
+    /** Why the job failed, classified; undefined unless it failed. */
+    get failure() {
+        return this.#failure;
+    }
+    /** Every attempt so far, oldest first. */
+    get attempts() {
+        return [...this.#attempts];
+    }
+    /**
+     * Calls `listener` with the current progress at once and with every later change. Returns
+     * the unsubscribe function.
+     */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#progress);
+        return () => this.#listeners.delete(listener);
+    }
+    /**
+     * Stops the running attempt and any pending retry, and resolves once the job has settled. An
+     * attempt that finished before the job settled has what it made released (a temporary file
+     * deleted). Resolves without effect on a settled job. Rejects only when cleanup failed
+     * (`EditorError` `cancel_failed`).
+     */
+    async cancel() {
+        if (!this.#settled) {
+            this.#progress = {
+                phase: "cancelling",
+                fraction: this.#progress.fraction,
+                attempt: this.#current,
+            };
+            for (const listener of this.#listeners)
+                listener(this.#progress);
+            this.#controller.abort();
+        }
+        await this.result.catch((error) => {
+            if (error instanceof EditorError && error.code === "cancel_failed")
+                throw error;
+        });
+    }
+}
+/** Deletes what a finished attempt made, when its kind can be deleted. */
+async function releaseArtifact(artifact) {
+    if ("release" in artifact && typeof artifact.release === "function")
+        await artifact.release();
+}
+/** Waits `ms`, or rejects as soon as `signal` aborts. */
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const stop = () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error
+                ? signal.reason
+                : new DOMException("Cancelled", "AbortError"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", stop, { once: true });
+        if (signal.aborted)
+            stop();
+    });
+}
+/** The export step a job's progress was in, for an error that did not say. */
+function phaseOf(progress) {
+    switch (progress.phase) {
+        case "rendering":
+            return "render";
+        case "finalizing":
+            return "mux";
+        case "publishing":
+            return "publish";
+        case "downloading":
+            return "download";
+        default:
+            return "prepare";
+    }
+}

package/dist/browser/resources.d.ts

@@ -0,0 +1,40 @@
+/** A counted reference to a registry entry. */
+export interface Lease<T> {
+    readonly value: T;
+    /**
+     * Drops this reference. Idempotent. The entry's `dispose` runs when its last lease is
+     * released.
+     */
+    release(): void;
+}
+/**
+ * Holds runtime values (decoders, bitmaps, files) that must never enter the project JSON or
+ * its history, keyed by id and revision and kept alive by explicit leases from owners and
+ * export jobs.
+ */
+export declare class ResourceRegistry<T> {
+    #private;
+    readonly limit: number;
+    /** @param limit Most entries held at once (default 128). */
+    constructor(limit?: number);
+    /**
+     * Stores `value` under `id` at `revision` and returns its first lease. `dispose` runs once,
+     * when the last lease is released or the registry is disposed.
+     *
+     * Throws `EditorError` `disposed` after {@link dispose}, `duplicate_resource` if that
+     * revision is already stored, and `resource_budget` when `limit` entries are held.
+     */
+    put(id: string, revision: number, value: T, dispose: () => void): Lease<T>;
+    /**
+     * Takes another lease on a stored entry. Throws `EditorError` `missing_asset` if no entry
+     * exists for `id` at `revision`.
+     */
+    acquire(id: string, revision: number): Lease<T>;
+    /** Entries currently held. */
+    get size(): number;
+    /**
+     * Disposes every entry regardless of outstanding leases and refuses later `put` calls.
+     * Idempotent.
+     */
+    dispose(): void;
+}

package/dist/browser/resources.js

@@ -0,0 +1,83 @@
+import { EditorError } from "../core/document.js";
+/**
+ * Holds runtime values (decoders, bitmaps, files) that must never enter the project JSON or
+ * its history, keyed by id and revision and kept alive by explicit leases from owners and
+ * export jobs.
+ */
+export class ResourceRegistry {
+    limit;
+    #entries = new Map();
+    #closed = false;
+    /** @param limit Most entries held at once (default 128). */
+    constructor(limit = 128) {
+        this.limit = limit;
+    }
+    /**
+     * Stores `value` under `id` at `revision` and returns its first lease. `dispose` runs once,
+     * when the last lease is released or the registry is disposed.
+     *
+     * Throws `EditorError` `disposed` after {@link dispose}, `duplicate_resource` if that
+     * revision is already stored, and `resource_budget` when `limit` entries are held.
+     */
+    put(id, revision, value, dispose) {
+        if (this.#closed)
+            throw new EditorError("disposed", "Resources are closed", "resource");
+        const key = JSON.stringify([id, revision]);
+        if (this.#entries.has(key))
+            throw new EditorError("duplicate_resource", "Resource revision already exists", "resource", id);
+        if (this.#entries.size >= this.limit)
+            throw new EditorError("resource_budget", "Resource budget reached", "resource", id);
+        let closed = false;
+        this.#entries.set(key, {
+            value,
+            refs: 0,
+            dispose: () => {
+                if (!closed) {
+                    closed = true;
+                    dispose();
+                }
+            },
+        });
+        return this.acquire(id, revision);
+    }
+    /**
+     * Takes another lease on a stored entry. Throws `EditorError` `missing_asset` if no entry
+     * exists for `id` at `revision`.
+     */
+    acquire(id, revision) {
+        const key = JSON.stringify([id, revision]);
+        const entry = this.#entries.get(key);
+        if (!entry)
+            throw new EditorError("missing_asset", "Runtime resource is missing", "resource", id);
+        entry.refs++;
+        let released = false;
+        return {
+            value: entry.value,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                if (--entry.refs === 0) {
+                    this.#entries.delete(key);
+                    entry.dispose();
+                }
+            },
+        };
+    }
+    /** Entries currently held. */
+    get size() {
+        return this.#entries.size;
+    }
+    /**
+     * Disposes every entry regardless of outstanding leases and refuses later `put` calls.
+     * Idempotent.
+     */
+    dispose() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const entry of this.#entries.values())
+            entry.dispose();
+        this.#entries.clear();
+    }
+}

package/dist/browser/runtime/assets.d.ts

@@ -0,0 +1,233 @@
+/**
+ * What a video container holds, read by the demuxer: its picture (`video`: size, frame rate, an HDR
+ * declaration), or null when it has no video track, and whether it has an audio stream. Null when
+ * the demuxer cannot read the container.
+ */
+export function probeVideo(file: any): Promise<{
+    video: {
+        colorMetadata: import("alpha2").ColorMetadata | null;
+        width: number;
+        height: number;
+        frameRate: number;
+    } | null;
+    hasAudio: boolean;
+    audioDecodable: boolean;
+} | null>;
+/**
+ * Streams a file's primary audio track into per-bucket peak magnitudes (`bucketsPerSecond`, capped
+ * at `maxBuckets`) with bounded memory. A bucket's peak is its loudest sample in any channel,
+ * since decoders order channels differently. `null` without audio.
+ */
+export function streamPeaks(file: any, { signal, bucketsPerSecond, maxBuckets }?: {
+    bucketsPerSecond?: number | undefined;
+    maxBuckets?: number | undefined;
+}): Promise<Float32Array<ArrayBuffer> | null>;
+/** Per-bucket peak magnitudes used to draw clip waveforms. */
+export function computePeaks(buffer: any, buckets?: number): Float32Array<ArrayBuffer>;
+export const IMAGE_TYPES: string[];
+export const VIDEO_TYPES: string[];
+export const AUDIO_TYPES: string[];
+export const ACCEPTED_TYPES: string;
+/** A title's style where its authoring leaves a field out (`TEXT_DEFAULTS`, exported from core). */
+export const DEFAULT_TEXT: Readonly<{
+    readonly content: "alpha2";
+    readonly fontSize: 120;
+    readonly fontFamily: "Inter, Segoe UI, system-ui, sans-serif";
+    readonly color: "#ffffff";
+    readonly align: "center";
+    readonly maxWidth: 0;
+    readonly lineHeight: 1.15;
+}>;
+export class AssetLibrary {
+    get map(): Map<any, any>;
+    get all(): any[];
+    get(id: any): any;
+    /** Metadata persisted in an editor project. Media bytes stay in local files. */
+    projectManifest(): {
+        id: any;
+        kind: any;
+        name: any;
+        locator: any;
+        type: any;
+        size: any;
+        lastModified: any;
+        width: any;
+        height: any;
+        frameRate: any;
+        duration: any;
+        hasAudio: boolean;
+        fit: any;
+        colorMetadata: any;
+        text: any;
+        generator: any;
+    }[];
+    /** Replaces the library with embedded text assets and missing local-file references. */
+    restoreProjectManifest(manifest: any): any[];
+    get missing(): any[];
+    /** Imports a non-media resource consumed by an engine effect. */
+    importEffectResource(file: any, kind: any): Promise<{
+        id: any;
+        kind: any;
+        name: any;
+        locator: any;
+        file: any;
+        text: any;
+    }>;
+    usedBy(doc: any): Set<any>;
+    remove(id: any): void;
+    /**
+     * Imports browser files; each one that does not import is reported back with its name and why
+     * (see {@link importFile}).
+     */
+    importFiles(files: any, onProgress: any): Promise<{
+        imported: ({
+            id: any;
+            kind: string;
+            name: any;
+            locator: any;
+            file: any;
+            width: number;
+            height: number;
+            duration: number;
+            fit: string;
+            thumbnail: HTMLCanvasElement;
+        } | {
+            id: any;
+            kind: string;
+            name: any;
+            locator: any;
+            file: any;
+            url: string;
+            video: HTMLVideoElement;
+            width: any;
+            height: any;
+            frameRate: any;
+            duration: number;
+            hasAudio: any;
+            audioDecodable: any;
+            colorMetadata: any;
+            fit: string;
+            thumbnail: null;
+            peaks: null;
+        } | {
+            id: any;
+            kind: string;
+            name: any;
+            locator: any;
+            file: any;
+            duration: number;
+            hasAudio: boolean;
+            audioDecodable: boolean;
+            peaks: null;
+            thumbnail: null;
+        })[];
+        rejected: {
+            name: any;
+            error: unknown;
+        }[];
+        relinked: any[];
+    }>;
+    /**
+     * Imports one browser file as an image, video or audio asset. Rejects with an `EditorError`:
+     * `unsupported_media` for a file that is none of those, `unreadable_media` for one that is but
+     * that this browser could not read (a codec it does not decode, a damaged file), with the
+     * decoder's or demuxer's reason in the message and as the `cause`.
+     */
+    importFile(file: any): Promise<{
+        id: any;
+        kind: string;
+        name: any;
+        locator: any;
+        file: any;
+        width: number;
+        height: number;
+        duration: number;
+        fit: string;
+        thumbnail: HTMLCanvasElement;
+    } | {
+        id: any;
+        kind: string;
+        name: any;
+        locator: any;
+        file: any;
+        url: string;
+        video: HTMLVideoElement;
+        width: any;
+        height: any;
+        frameRate: any;
+        duration: number;
+        hasAudio: any;
+        audioDecodable: any;
+        colorMetadata: any;
+        fit: string;
+        thumbnail: null;
+        peaks: null;
+    } | {
+        id: any;
+        kind: string;
+        name: any;
+        locator: any;
+        file: any;
+        duration: number;
+        hasAudio: boolean;
+        audioDecodable: boolean;
+        peaks: null;
+        thumbnail: null;
+    }>;
+    /** Registers a project-rate audio buffer synthesized in the page rather than read from a file. */
+    addGeneratedAudio(name: any, audioBuffer: any): {
+        id: string;
+        kind: string;
+        name: any;
+        generated: boolean;
+        duration: any;
+        hasAudio: boolean;
+        audioBuffer: any;
+        peaks: Float32Array<ArrayBuffer>;
+        thumbnail: null;
+    };
+    /**
+     * Creates a text source rasterized by the packaged `OffscreenTextRasterizer`, the browser host
+     * for the engine's host-rasterized text contract.
+     */
+    createText(style?: {}, { id }?: {
+        id?: string | undefined;
+    }): {
+        id: string;
+        kind: string;
+        name: string;
+        text: {
+            content: "alpha2";
+            fontSize: 120;
+            fontFamily: "Inter, Segoe UI, system-ui, sans-serif";
+            color: "#ffffff";
+            align: "center";
+            maxWidth: 0;
+            lineHeight: 1.15;
+        };
+        duration: number;
+        fit: string;
+        raster: null;
+        thumbnail: null;
+    };
+    /**
+     * Creates a source the engine draws itself from `generator` (see `generators.js`); it needs no
+     * file and has no duration.
+     */
+    createGenerated(generator: any, { id, name }?: {
+        id?: string | undefined;
+        name?: null | undefined;
+    }): {
+        id: string;
+        kind: string;
+        name: string;
+        generator: any;
+        duration: number;
+        thumbnail: null;
+    };
+    updateGenerated(asset: any, generator: any): void;
+    rasterizeText(asset: any, text: any): any;
+    dispose(): void;
+    clear(): void;
+    #private;
+}