@alpha2-sh/editor 0.0.0-stage → 0.1.0

package/dist/browser/extensions-worker-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/extensions-worker-entry.js

@@ -0,0 +1,3 @@
+// The `@alpha2-sh/editor/extensions-worker` entry (see `runtimeAssets.extensionsWorkerFactory`).
+import { installExtensionsWorker } from "./extensions-worker.js";
+installExtensionsWorker(self);

package/dist/browser/extensions-worker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Answers the call posted to `scope` (a dedicated worker's global): `{ type: "call", call, file,
+ * wasmUrl, ... }` is answered with `{ type: "answered", result }`, or `{ type: "failed", name,
+ * message }` when the file cannot be read or the provider refuses it. `{ type: "started" }` is
+ * posted first, once the worker runs.
+ * @param {{ onmessage: ((event: MessageEvent) => void) | null, postMessage(message: unknown): void }} scope
+ */
+export function installExtensionsWorker(scope: {
+    onmessage: ((event: MessageEvent) => void) | null;
+    postMessage(message: unknown): void;
+}): void;
+/**
+ * Runs an extensions call: `request` names the call (`read`, `svg-diagnostics` or
+ * `exr-first-frame`), the `file` it reads and what else the call takes. With `factory`, the call
+ * runs in a worker it makes (one running {@link installExtensionsWorker}), which is terminated once
+ * it answers, when `signal` aborts (rejecting with its reason), or after `timeoutMs` (rejecting as
+ * `provider_stalled`). A worker that cannot start (its script does not load) leaves the call to
+ * this thread, as it does without a factory; here the module call cannot be stopped, and `signal`
+ * is checked between steps.
+ *
+ * @param {{ factory?: () => Worker, wasmUrl?: string | URL }} module
+ * @param {{ call: string, file: Blob & { name?: string }, [key: string]: unknown }} request
+ * @param {{ signal?: AbortSignal, timeoutMs?: number, operation?: string }} [options]
+ */
+export function callExtensions({ factory, wasmUrl }: {
+    factory?: () => Worker;
+    wasmUrl?: string | URL;
+}, request: {
+    call: string;
+    file: Blob & {
+        name?: string;
+    };
+    [key: string]: unknown;
+}, { signal, timeoutMs, operation }?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    operation?: string;
+}): Promise<any>;
+/**
+ * How long one call in an extensions worker may run before the worker is terminated and the call
+ * fails as `provider_stalled`: the 40 s a native host's decode shard may spend inside one provider
+ * or decoder call (10 s plus the default `ALPHA2_GPU_TIMEOUT_MS`) before the export fails as
+ * stalled. The provider's budgets refuse a file whose drawing they can count long before this; the
+ * limit is for work they cannot.
+ */
+export const EXTENSIONS_CALL_TIMEOUT_MS: 40000;

package/dist/browser/extensions-worker.js

@@ -0,0 +1,149 @@
+// Runs extension provider calls (probe, open, thumbnail) off the page's thread: each is one
+// synchronous call that can decode every frame or parse a file whole. A host bundling the
+// `@alpha2-sh/editor/extensions-worker` entry passes `runtimeAssets.extensionsWorkerFactory`; each
+// call gets its own worker, terminated on cancel or past `EXTENSIONS_CALL_TIMEOUT_MS`.
+import { EditorError } from "../core/document.js";
+import { exrFirstFrame, readProviderFile, svgDiagnostics, } from "./runtime/extension-import.js";
+/**
+ * How long one call in an extensions worker may run before the worker is terminated and the call
+ * fails as `provider_stalled`: the 40 s a native host's decode shard may spend inside one provider
+ * or decoder call (10 s plus the default `ALPHA2_GPU_TIMEOUT_MS`) before the export fails as
+ * stalled. The provider's budgets refuse a file whose drawing they can count long before this; the
+ * limit is for work they cannot.
+ */
+export const EXTENSIONS_CALL_TIMEOUT_MS = 40_000;
+/** Loads the provider module (`alpha2/extensions`) from `wasmUrl`, once per realm. */
+async function loadModule(wasmUrl) {
+    const { loadExtensions } = await import("alpha2/extensions");
+    return loadExtensions(wasmUrl);
+}
+/** What each call reads of its file's bytes with the provider module. */
+const CALLS = {
+    /** What import reads of a file: `null`, or its provider, report and thumbnail. */
+    read: (extensions, bytes) => readProviderFile(extensions, bytes),
+    /** An SVG's diagnostics with the font stack `fonts` (bytes, in fallback order). */
+    "svg-diagnostics": (extensions, bytes, { provider, fonts }) => svgDiagnostics(extensions, provider, bytes, fonts),
+    /** An OpenEXR sequence's first frame: its thumbnail and report. */
+    "exr-first-frame": (extensions, bytes) => exrFirstFrame(extensions, bytes),
+};
+/** Runs `request` in this realm, checking `signal` between the steps it waits for. */
+async function run(request, wasmUrl, load, signal) {
+    const call = CALLS[request.call];
+    if (!call)
+        throw new Error(`unknown extensions call ${request.call}`);
+    const extensions = await load(wasmUrl);
+    signal?.throwIfAborted();
+    const bytes = new Uint8Array(await request.file.arrayBuffer());
+    signal?.throwIfAborted();
+    return call(extensions, bytes, request);
+}
+/**
+ * Answers the call posted to `scope` (a dedicated worker's global): `{ type: "call", call, file,
+ * wasmUrl, ... }` is answered with `{ type: "answered", result }`, or `{ type: "failed", name,
+ * message }` when the file cannot be read or the provider refuses it. `{ type: "started" }` is
+ * posted first, once the worker runs.
+ * @param {{ onmessage: ((event: MessageEvent) => void) | null, postMessage(message: unknown): void }} scope
+ */
+export function installExtensionsWorker(scope) {
+    scope.onmessage = async ({ data }) => {
+        if (data?.type !== "call")
+            return;
+        try {
+            const result = await run(data, data.wasmUrl, loadModule);
+            scope.postMessage({ type: "answered", result });
+        }
+        catch (error) {
+            scope.postMessage({
+                type: "failed",
+                name: error?.name ?? "Error",
+                // A provider's refusal is thrown as its message alone.
+                message: String(error?.message ?? error),
+            });
+        }
+    };
+    scope.postMessage({ type: "started" });
+}
+/** `url` as an absolute URL, which a worker resolves the same as the page. */
+function absolute(url) {
+    if (url === undefined)
+        return undefined;
+    const base = globalThis.location?.href;
+    return base ? new URL(String(url), base).href : String(url);
+}
+/**
+ * Runs an extensions call: `request` names the call (`read`, `svg-diagnostics` or
+ * `exr-first-frame`), the `file` it reads and what else the call takes. With `factory`, the call
+ * runs in a worker it makes (one running {@link installExtensionsWorker}), which is terminated once
+ * it answers, when `signal` aborts (rejecting with its reason), or after `timeoutMs` (rejecting as
+ * `provider_stalled`). A worker that cannot start (its script does not load) leaves the call to
+ * this thread, as it does without a factory; here the module call cannot be stopped, and `signal`
+ * is checked between steps.
+ *
+ * @param {{ factory?: () => Worker, wasmUrl?: string | URL }} module
+ * @param {{ call: string, file: Blob & { name?: string }, [key: string]: unknown }} request
+ * @param {{ signal?: AbortSignal, timeoutMs?: number, operation?: string }} [options]
+ */
+export function callExtensions({ factory, wasmUrl }, request, { signal, timeoutMs = EXTENSIONS_CALL_TIMEOUT_MS, operation = "import" } = {}) {
+    signal?.throwIfAborted();
+    const here = () => run(request, wasmUrl, loadModule, signal);
+    if (!factory)
+        return here();
+    let worker;
+    try {
+        worker = factory();
+    }
+    catch {
+        return here();
+    }
+    return new Promise((resolve, reject) => {
+        let started = false;
+        let ended = false;
+        const end = () => {
+            ended = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            worker.terminate();
+        };
+        const abort = () => {
+            end();
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        const timer = setTimeout(() => {
+            end();
+            reject(new EditorError("provider_stalled", `${request.file.name ?? "The file"} took the extension provider more than ${timeoutMs / 1000} s to read; it was stopped`, operation));
+        }, timeoutMs);
+        signal?.addEventListener("abort", abort, { once: true });
+        worker.onmessage = ({ data }) => {
+            if (ended)
+                return;
+            if (data?.type === "started")
+                started = true;
+            else if (data?.type === "answered") {
+                end();
+                resolve(data.result);
+            }
+            else if (data?.type === "failed") {
+                end();
+                reject(Object.assign(new Error(data.message), {
+                    name: data.name ?? "Error",
+                }));
+            }
+        };
+        worker.onerror = (event) => {
+            if (ended)
+                return;
+            event?.preventDefault?.();
+            end();
+            if (started)
+                reject(new Error(`the extensions worker stopped: ${event?.message ?? "an uncaught error"}`));
+            // The worker never ran: the call is made here instead.
+            else
+                here().then(resolve, reject);
+        };
+        worker.postMessage({
+            type: "call",
+            ...request,
+            wasmUrl: absolute(wasmUrl),
+        });
+    });
+}

package/dist/browser/hash-worker-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/hash-worker-entry.js

@@ -0,0 +1,3 @@
+// The `@alpha2-sh/editor/hash-worker` entry (see `runtimeAssets.hashWorkerFactory`).
+import { installHashWorker } from "./hash-worker.js";
+installHashWorker(self);

package/dist/browser/hash-worker.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Answers hash requests posted to `scope` (a dedicated worker's global): `{ type: "hash", file }`
+ * is answered with `{ type: "progress", bytes }` as it is read and `{ type: "hashed", sha256 }`, or
+ * `{ type: "failed", message, name }` when the file cannot be read.
+ * @param {{ onmessage: ((event: MessageEvent) => void) | null, postMessage(message: unknown): void }} scope
+ */
+export function installHashWorker(scope: {
+    onmessage: ((event: MessageEvent) => void) | null;
+    postMessage(message: unknown): void;
+}): void;
+/**
+ * The SHA-256 of `file`, as `sha256Blob` gives it, hashed in a worker `factory` makes (one running
+ * {@link installHashWorker}), which is terminated once it answers or `signal` aborts. A worker that
+ * cannot start (its script does not load) leaves the hash to this thread's `sha256Blob`, which lets
+ * other tasks run every few milliseconds.
+ * @param {() => Worker} factory
+ * @param {Blob} file
+ * @param {{ signal?: AbortSignal, onProgress?: (bytes: number) => void }} [options]
+ * @returns {Promise<string>}
+ */
+export function hashInWorker(factory: () => Worker, file: Blob, { signal, onProgress }?: {
+    signal?: AbortSignal;
+    onProgress?: (bytes: number) => void;
+}): Promise<string>;

package/dist/browser/hash-worker.js

@@ -0,0 +1,87 @@
+// Hashes an imported file off the page's thread (about 5 ms of CPU per megabyte in JavaScript).
+// A host bundling the `@alpha2-sh/editor/hash-worker` entry passes
+// `runtimeAssets.hashWorkerFactory`; each file gets its own worker, terminated on cancel.
+import { sha256Blob } from "alpha2/assets";
+/**
+ * Answers hash requests posted to `scope` (a dedicated worker's global): `{ type: "hash", file }`
+ * is answered with `{ type: "progress", bytes }` as it is read and `{ type: "hashed", sha256 }`, or
+ * `{ type: "failed", message, name }` when the file cannot be read.
+ * @param {{ onmessage: ((event: MessageEvent) => void) | null, postMessage(message: unknown): void }} scope
+ */
+export function installHashWorker(scope) {
+    scope.onmessage = async ({ data }) => {
+        if (data?.type !== "hash")
+            return;
+        try {
+            const sha256 = await sha256Blob(data.file, {
+                onProgress: (bytes) => scope.postMessage({ type: "progress", bytes }),
+            });
+            scope.postMessage({ type: "hashed", sha256 });
+        }
+        catch (error) {
+            scope.postMessage({
+                type: "failed",
+                name: error?.name ?? "Error",
+                message: String(error?.message ?? error),
+            });
+        }
+    };
+}
+/**
+ * The SHA-256 of `file`, as `sha256Blob` gives it, hashed in a worker `factory` makes (one running
+ * {@link installHashWorker}), which is terminated once it answers or `signal` aborts. A worker that
+ * cannot start (its script does not load) leaves the hash to this thread's `sha256Blob`, which lets
+ * other tasks run every few milliseconds.
+ * @param {() => Worker} factory
+ * @param {Blob} file
+ * @param {{ signal?: AbortSignal, onProgress?: (bytes: number) => void }} [options]
+ * @returns {Promise<string>}
+ */
+export function hashInWorker(factory, file, { signal, onProgress } = {}) {
+    signal?.throwIfAborted();
+    let worker;
+    try {
+        worker = factory();
+    }
+    catch {
+        return sha256Blob(file, { signal, onProgress });
+    }
+    return new Promise((resolve, reject) => {
+        let answered = false;
+        const end = () => {
+            answered = true;
+            signal?.removeEventListener("abort", abort);
+            worker.terminate();
+        };
+        const abort = () => {
+            end();
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        worker.onmessage = ({ data }) => {
+            if (answered)
+                return;
+            if (data?.type === "progress")
+                onProgress?.(data.bytes);
+            else if (data?.type === "hashed") {
+                end();
+                resolve(data.sha256);
+            }
+            else if (data?.type === "failed") {
+                end();
+                reject(Object.assign(new Error(data.message), {
+                    name: data.name ?? "Error",
+                }));
+            }
+        };
+        worker.onerror = (event) => {
+            if (answered)
+                return;
+            event?.preventDefault?.();
+            end();
+            // The worker never ran: the hash is made here instead.
+            sha256Blob(file, { signal, onProgress }).then(resolve, reject);
+        };
+        worker.postMessage({ type: "hash", file });
+    });
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,11 @@
+export { ConformError, createBrowserBridge, createMediaAdapter, } from "./bridge.js";
+export { ResourceRegistry } from "./resources.js";
+export { ExportJob } from "./jobs.js";
+export type { ExportAttemptRecord, ExportJobOptions } from "./jobs.js";
+export { keptProxies, removeKeptProxies } from "./runtime/proxy-storage.js";
+export { estimatedStagingBytes, minimumExportWorkingSet, } from "./runtime/staging.js";
+export { sequenceNumbering } from "./runtime/extension-import.js";
+export { createWorkerPreview, installEditorWorker } from "./worker.js";
+export { hashInWorker, installHashWorker } from "./hash-worker.js";
+export { EXTENSIONS_CALL_TIMEOUT_MS, installExtensionsWorker, } from "./extensions-worker.js";
+export type * from "./types.js";

package/dist/browser/index.js

@@ -0,0 +1,9 @@
+export { ConformError, createBrowserBridge, createMediaAdapter, } from "./bridge.js";
+export { ResourceRegistry } from "./resources.js";
+export { ExportJob } from "./jobs.js";
+export { keptProxies, removeKeptProxies } from "./runtime/proxy-storage.js";
+export { estimatedStagingBytes, minimumExportWorkingSet, } from "./runtime/staging.js";
+export { sequenceNumbering } from "./runtime/extension-import.js";
+export { createWorkerPreview, installEditorWorker } from "./worker.js";
+export { hashInWorker, installHashWorker } from "./hash-worker.js";
+export { EXTENSIONS_CALL_TIMEOUT_MS, installExtensionsWorker, } from "./extensions-worker.js";

package/dist/browser/jobs.d.ts

@@ -0,0 +1,82 @@
+import { type ExportFailure } from "alpha2/export-failure";
+import { type RetryPolicyOptions, type RetryProfile } from "alpha2/export-retry";
+import type { EditorDocument } from "../core/document.js";
+import type { ExportBackend, ExportProgress, ExportArtifact } from "../ports/index.js";
+/**
+ * Refuses an export `frameRate` the engine cannot read, before an export starts, for every
+ * backend: one rate, the same everywhere.
+ */
+export declare function requireExportFrameRate(frameRate: unknown): void;
+/** What happened to one attempt of a job. */
+export interface ExportAttemptRecord {
+    readonly id: string;
+    readonly number: number;
+    readonly profile: RetryProfile;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly outcome: "running" | "succeeded" | "failed" | "cancelled";
+    readonly failure?: ExportFailure;
+    /** What the retry policy decided after this attempt failed, and why. */
+    readonly decision?: {
+        readonly retry: boolean;
+        readonly reason: string;
+    };
+}
+/** Options of an {@link ExportJob}. */
+export interface ExportJobOptions {
+    /** The job's id, when its backend already named it (a service's job); a fresh UUID otherwise. */
+    readonly id?: string;
+    /**
+     * The retry policy (see `alpha2/export-retry`), or `false` for one attempt. Default: three
+     * attempts, the reference backoff.
+     */
+    readonly retry?: RetryPolicyOptions | false;
+    /** Waits `ms` or rejects when `signal` aborts; replaceable for tests. */
+    readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * 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 declare class ExportJob {
+    #private;
+    readonly revision: number;
+    readonly id: string;
+    /**
+     * 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`.
+     */
+    readonly result: Promise<ExportArtifact>;
+    /**
+     * 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: number, document: EditorDocument, backend: ExportBackend, release?: () => void, options?: ExportJobOptions);
+    /** The latest progress, frozen. Reports from an attempt that has ended are not reflected. */
+    get progress(): ExportProgress;
+    /** Why the job failed, classified; undefined unless it failed. */
+    get failure(): ExportFailure | undefined;
+    /** Every attempt so far, oldest first. */
+    get attempts(): readonly ExportAttemptRecord[];
+    /**
+     * Calls `listener` with the current progress at once and with every later change. Returns
+     * the unsubscribe function.
+     */
+    subscribe(listener: (value: ExportProgress) => void): () => void;
+    /**
+     * 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`).
+     */
+    cancel(): Promise<void>;
+}