@alpha2-sh/editor 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,87 @@
+/** Which storage APIs this page has, as an export's result reports them. */
+export function storageSupport(): {
+    opfs: boolean;
+    savePicker: boolean;
+    estimate: boolean;
+};
+/**
+ * Opens where an export writes, refusing before anything renders only an in-memory output past its
+ * limit.
+ *
+ * Storage is never refused ahead: `navigator.storage.estimate()` is a guess, and WebKit's usage
+ * counts every write since its last disk scan, so `quota - usage` can be near zero on an empty
+ * disk. A full disk fails at the write (`STORAGE_QUOTA_EXCEEDED`); the estimate is only reported.
+ *
+ * Returns `{ mode, destination, storageEstimate, abort, finish }`: `destination` is the sink's,
+ * `abort` discards the file, and `finish(sinkOutput)` turns the finished output into the artifact's
+ * fields.
+ */
+export function openExportOutput({ jobId, name, target, durationSeconds, videoBitrate, audioBitrate, }: {
+    jobId: any;
+    name: any;
+    target: any;
+    durationSeconds: any;
+    videoBitrate: any;
+    audioBitrate: any;
+}): Promise<{
+    mode: string;
+    estimatedBytes: any;
+    storageEstimate: null;
+    destination: {
+        kind: string;
+        writable: WritableStream<import("alpha2/export-destination").PositionedWrite>;
+    };
+    stats: () => import("alpha2/export-destination").FileDestinationStats;
+    abort: (reason: any) => Promise<void>;
+    finish: (output: any) => Promise<{
+        kind: string;
+        name: any;
+        bytes: any;
+    }>;
+} | {
+    mode: string;
+    estimatedBytes: any;
+    storageEstimate: {
+        quotaBytes: number;
+        usageBytes: number;
+        neededBytes: number;
+        belowEstimate: boolean;
+    } | null;
+    destination: {
+        kind: string;
+        writable: WritableStream<import("alpha2/export-destination").PositionedWrite>;
+    };
+    stats: () => import("alpha2/export-destination").FileDestinationStats;
+    abort: (reason: any) => Promise<void>;
+    finish: (output: any) => Promise<{
+        kind: string;
+        file: File;
+        name: any;
+        bytes: any;
+        release: () => Promise<void>;
+    }>;
+} | {
+    mode: string;
+    estimatedBytes: any;
+    storageEstimate: null;
+    destination: {
+        kind: string;
+        maxBytes: number;
+    };
+    stats: () => null;
+    abort: () => Promise<void>;
+    finish: (output: any) => Promise<{
+        kind: string;
+        blob: Blob;
+        name: any;
+        bytes: any;
+    }>;
+}>;
+/**
+ * Deletes temporary export files left by pages that are gone: started over a day ago and held by
+ * no page. Resolves to the names removed.
+ * @returns {Promise<string[]>}
+ */
+export function sweepStaleExports(now?: number): Promise<string[]>;
+/** The most an in-memory output may hold at its peak unless asked otherwise. */
+export const DEFAULT_MEMORY_OUTPUT_LIMIT: number;

package/dist/browser/runtime/output.js

@@ -0,0 +1,230 @@
+// Where a browser export's file goes: streamed into a temporary OPFS file (or a user-picked file)
+// so encoded video never accumulates in memory. In-memory output is for small outputs sized up
+// front, never a silent fallback for a large one.
+import { estimatedOutputBytes, memoryOutputPeakBytes, MEMORY_OUTPUT_COPIES, MEMORY_OUTPUT_MARGIN, WritableFileDestination, } from "alpha2/export-destination";
+import { ExportFailureError } from "alpha2/export-failure";
+import { holdShared, whenUnheld } from "./locks.js";
+/** The most an in-memory output may hold at its peak unless asked otherwise. */
+export const DEFAULT_MEMORY_OUTPUT_LIMIT = 512 * 1024 * 1024;
+/** The origin-private directory temporary export files live in. */
+const EXPORT_DIRECTORY = "alpha2-exports";
+/**
+ * A temporary export older than this, that no page holds, belongs to a page that is gone. Where the
+ * browser has no Web Locks, age alone decides.
+ */
+const STALE_EXPORT_MS = 24 * 60 * 60 * 1000;
+/** The Web Lock a page holds on a temporary export file while it writes or keeps it. */
+const exportLock = (fileName) => `alpha2-export:${fileName}`;
+/** Free storage an export is reported to want beyond its estimate. */
+const STORAGE_MARGIN = MEMORY_OUTPUT_MARGIN;
+/** Which storage APIs this page has, as an export's result reports them. */
+export function storageSupport() {
+    const storage = globalThis.navigator?.storage;
+    return {
+        // Handles gained `createWritable` later than the directory, so that is checked at open.
+        opfs: typeof storage?.getDirectory === "function",
+        savePicker: typeof globalThis.showSaveFilePicker === "function",
+        estimate: typeof storage?.estimate === "function",
+    };
+}
+/**
+ * Opens where an export writes, refusing before anything renders only an in-memory output past its
+ * limit.
+ *
+ * Storage is never refused ahead: `navigator.storage.estimate()` is a guess, and WebKit's usage
+ * counts every write since its last disk scan, so `quota - usage` can be near zero on an empty
+ * disk. A full disk fails at the write (`STORAGE_QUOTA_EXCEEDED`); the estimate is only reported.
+ *
+ * Returns `{ mode, destination, storageEstimate, abort, finish }`: `destination` is the sink's,
+ * `abort` discards the file, and `finish(sinkOutput)` turns the finished output into the artifact's
+ * fields.
+ */
+export async function openExportOutput({ jobId, name, target, durationSeconds, videoBitrate, audioBitrate, }) {
+    const estimate = estimatedOutputBytes({
+        durationSeconds,
+        videoBitrate,
+        audioBitrate,
+    });
+    const kind = target?.kind ?? "opfs";
+    if (kind === "file")
+        return openPickedFile(target.handle, estimate);
+    if (kind === "opfs") {
+        const opened = await openOriginPrivateFile(jobId, name, estimate);
+        if (opened)
+            return opened;
+    }
+    return openMemory(target?.maxBytes ?? DEFAULT_MEMORY_OUTPUT_LIMIT, estimate, {
+        name,
+        fellBack: kind !== "memory",
+    });
+}
+async function openPickedFile(handle, estimate) {
+    const writable = await handle
+        .createWritable({ keepExistingData: false })
+        .catch((cause) => {
+        throw refused("OUTPUT_IO_FAILED", `The chosen file cannot be written: ${cause?.message ?? cause}`, { cause });
+    });
+    const destination = new WritableFileDestination(writable);
+    return {
+        mode: "file",
+        estimatedBytes: estimate,
+        storageEstimate: null,
+        destination: { kind: "stream", writable: destination.writable },
+        stats: () => destination.stats,
+        abort: (reason) => destination.abort(reason),
+        finish: async (output) => ({
+            kind: "saved",
+            name: handle.name,
+            bytes: output.bytes,
+        }),
+    };
+}
+async function openOriginPrivateFile(jobId, name, estimate) {
+    const storage = globalThis.navigator?.storage;
+    if (typeof storage?.getDirectory !== "function")
+        return null;
+    let directory;
+    let handle;
+    let writable;
+    const fileName = `${Date.now()}-${jobId}.mp4`;
+    // Held from before the file exists until it is removed, so another page's sweep leaves it alone.
+    const lease = await holdShared(exportLock(fileName));
+    try {
+        directory = await (await storage.getDirectory()).getDirectoryHandle(EXPORT_DIRECTORY, { create: true });
+        handle = await directory.getFileHandle(fileName, { create: true });
+        if (typeof handle.createWritable !== "function") {
+            await directory.removeEntry(fileName).catch(() => { });
+            void lease.release();
+            return null;
+        }
+    }
+    catch {
+        void lease.release();
+        return null;
+    }
+    const storageEstimate = await reportedStorage(storage, estimate);
+    try {
+        writable = await handle.createWritable();
+    }
+    catch {
+        await directory.removeEntry(fileName).catch(() => { });
+        void lease.release();
+        return null;
+    }
+    const destination = new WritableFileDestination(writable);
+    let released = false;
+    const remove = async () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            await directory.removeEntry(fileName);
+        }
+        finally {
+            void lease.release();
+        }
+    };
+    return {
+        mode: "opfs",
+        estimatedBytes: estimate,
+        storageEstimate,
+        destination: { kind: "stream", writable: destination.writable },
+        stats: () => destination.stats,
+        abort: async (reason) => {
+            await destination.abort(reason);
+            await remove().catch(() => { });
+        },
+        finish: async (output) => {
+            const file = await handle.getFile();
+            return {
+                kind: "file",
+                file: new File([file], name, { type: "video/mp4" }),
+                name,
+                bytes: output.bytes,
+                release: remove,
+            };
+        },
+    };
+}
+/**
+ * What the browser says about the origin's storage, beside what this export is expected to need:
+ * `belowEstimate` when its `quota - usage` is less. A report, never a refusal (see
+ * `openExportOutput`); `null` where the browser says nothing.
+ */
+async function reportedStorage(storage, estimate) {
+    if (typeof storage.estimate !== "function")
+        return null;
+    const { quota, usage } = await storage.estimate().catch(() => ({}));
+    if (typeof quota !== "number" || typeof usage !== "number")
+        return null;
+    const needed = Math.ceil(estimate * STORAGE_MARGIN);
+    return {
+        quotaBytes: quota,
+        usageBytes: usage,
+        neededBytes: needed,
+        belowEstimate: quota - usage < needed,
+    };
+}
+function openMemory(limit, estimate, { name, fellBack }) {
+    const peak = memoryOutputPeakBytes(estimate);
+    if (peak > limit)
+        throw refused("RESOURCE_LIMIT", `${fellBack ? "This browser cannot write the export to disk, and an" : "An"} output of about ${megabytes(estimate)} needs up to ${megabytes(peak)} of memory while it is kept in memory, over the ${megabytes(limit)} limit. Export a shorter range or use the native exporter.`, { requestedBytes: peak, resource: "js" });
+    return {
+        mode: "memory",
+        estimatedBytes: estimate,
+        storageEstimate: null,
+        destination: {
+            kind: "memory",
+            maxBytes: Math.floor(limit / MEMORY_OUTPUT_COPIES),
+        },
+        stats: () => null,
+        abort: async () => { },
+        finish: async (output) => ({
+            kind: "blob",
+            blob: new Blob([output.buffer], { type: "video/mp4" }),
+            name,
+            bytes: output.buffer.byteLength,
+        }),
+    };
+}
+/**
+ * Deletes temporary export files left by pages that are gone: started over a day ago and held by
+ * no page. Resolves to the names removed.
+ * @returns {Promise<string[]>}
+ */
+export async function sweepStaleExports(now = Date.now()) {
+    const removed = [];
+    try {
+        const directory = await (await globalThis.navigator.storage.getDirectory()).getDirectoryHandle(EXPORT_DIRECTORY, { create: false });
+        const stale = [];
+        for await (const [entry] of directory.entries()) {
+            const started = Number(entry.split("-", 1)[0]);
+            if (Number.isFinite(started) && now - started > STALE_EXPORT_MS)
+                stale.push(entry);
+        }
+        for (const entry of stale)
+            if (await whenUnheld(exportLock(entry), () => directory.removeEntry(entry)).catch(() => false))
+                removed.push(entry);
+    }
+    catch {
+        // No directory yet, or no OPFS: nothing to sweep.
+    }
+    return removed;
+}
+function refused(code, message, extra = {}) {
+    return new ExportFailureError({
+        code,
+        message,
+        origin: "browser",
+        operation: "export",
+        backend: "unknown",
+        phase: "prepare",
+        resource: extra.resource ?? "unknown",
+        ...(extra.requestedBytes === undefined
+            ? {}
+            : { requestedBytes: extra.requestedBytes }),
+    }, extra.cause === undefined ? undefined : { cause: extra.cause });
+}
+function megabytes(bytes) {
+    return `${(bytes / 1e6).toFixed(bytes < 1e7 ? 1 : 0)} MB`;
+}

package/dist/browser/runtime/preview-utils.d.ts

@@ -0,0 +1,3 @@
+export function containRect(sourceWidth: any, sourceHeight: any, width: any, height: any): number[];
+export function previewFrameIndex(seconds: any, fps: any): number;
+export function seekVideoFrame(video: any, seconds: any, tolerance?: number): Promise<void>;

package/dist/browser/runtime/preview-utils.js

@@ -0,0 +1,49 @@
+// Keep the source's display aspect ratio; transparent padding belongs to the clip and participates
+// in its transform and transition.
+export function containRect(sourceWidth, sourceHeight, width, height) {
+    const scale = Math.min(width / sourceWidth, height / sourceHeight);
+    const drawWidth = sourceWidth * scale;
+    const drawHeight = sourceHeight * scale;
+    return [
+        (width - drawWidth) / 2,
+        (height - drawHeight) / 2,
+        drawWidth,
+        drawHeight,
+    ];
+}
+// Select project frames from the clock instead of accumulating RAF delays.
+export function previewFrameIndex(seconds, fps) {
+    return Math.floor(seconds * fps + 1e-7);
+}
+export async function seekVideoFrame(video, seconds, tolerance = 0.001) {
+    if (!video.seeking &&
+        Math.abs(video.currentTime - seconds) <= tolerance &&
+        video.readyState >= 2)
+        return;
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timeout);
+            video.removeEventListener("seeked", done);
+            video.removeEventListener("error", failed);
+        };
+        const done = () => {
+            if (video.seeking)
+                return;
+            cleanup();
+            resolve();
+        };
+        const failed = () => {
+            cleanup();
+            reject(video.error ?? new Error("video seek failed"));
+        };
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error("video seek timed out"));
+        }, 10_000);
+        video.addEventListener("seeked", done);
+        video.addEventListener("error", failed);
+        // currentTime changes before the new frame is available; wait on a pending seek to this target.
+        if (!video.seeking || Math.abs(video.currentTime - seconds) > tolerance)
+            video.currentTime = seconds;
+    });
+}

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

@@ -0,0 +1,72 @@
+/** A proxy's longer displayed edge, in pixels. */
+export const PROXY_LONG_EDGE: 960;
+/**
+ * @typedef {{
+ *   made_from: import("alpha2/project").MediaFingerprint,
+ *   width: number,
+ *   height: number,
+ *   frame_rate?: { num: number, den: number },
+ *   duration_ticks?: number,
+ *   audio_sample_rate?: number,
+ * }} ProxyRecord
+ */
+/**
+ * Keeps proxies by their original's SHA-256: in OPFS where the browser can write files there, and
+ * otherwise in this page's memory, within {@link DEFAULT_MEMORY_OUTPUT_LIMIT} unless asked
+ * otherwise.
+ */
+export class ProxyStore {
+    constructor({ memoryLimit }?: {
+        memoryLimit?: number | undefined;
+    });
+    /**
+     * Holds the proxy of `hash` in use until `release()`, so no page removes it meanwhile (see
+     * `holdProxy`).
+     */
+    hold(hash: any): Promise<{
+        release(): Promise<void>;
+    }>;
+    /** The proxy made from the media with `hash`, if one is kept. */
+    find(hash: any): Promise<{
+        record: any;
+        file: File;
+    } | null>;
+    /**
+     * The proxies kept: each original's hash and the bytes its proxy takes, on disk or in this page's
+     * memory.
+     */
+    list(): Promise<{
+        hash: string;
+        bytes: number;
+    }[]>;
+    /**
+     * Removes the proxies of `hashes`, except those a page holds in use. Resolves to the hashes
+     * removed and those left in use.
+     */
+    remove(hashes: any): Promise<import("../types.js").ProxyRemoval>;
+    /**
+     * Makes a proxy of `file`, whose fingerprint is `fingerprint`, and keeps it. The video is scaled
+     * to fit {@link PROXY_LONG_EDGE} with a key frame every second; timestamps and the audio sample
+     * rate are the original's. A proxy already kept for the same bytes is returned instead. Pages of
+     * the origin make one hash's proxy in turn (`whileMakingProxy`).
+     *
+     * Refuses before encoding when the conversion would drop a track the fingerprint records. Rejects
+     * with `signal.reason` if `signal` aborts before the proxy is kept.
+     */
+    generate(file: any, fingerprint: any, { signal, onProgress }?: {}): Promise<{
+        record: any;
+        file: File;
+    }>;
+    #private;
+}
+export type ProxyRecord = {
+    made_from: import("alpha2/project").MediaFingerprint;
+    width: number;
+    height: number;
+    frame_rate?: {
+        num: number;
+        den: number;
+    };
+    duration_ticks?: number;
+    audio_sample_rate?: number;
+};