@alpha2-sh/editor 0.0.0 → 0.1.0

package/dist/core/timeline-index.js

@@ -0,0 +1,59 @@
+const indexes = new WeakMap();
+/**
+ * Every clip, transition, caption cue, and marker of a document, in timeline order (then by kind,
+ * then id). Derived from the document alone and kept per document, so a playing viewer never
+ * rebuilds it: only an edit does.
+ */
+export function timelineIndex(document) {
+    const cached = indexes.get(document);
+    if (cached)
+        return cached;
+    const names = new Map(Object.values(document.assets).map((asset) => [asset.id, asset.name]));
+    const entries = [];
+    for (const track of document.project.timeline.tracks) {
+        for (const clip of track.clips ?? [])
+            entries.push({
+                kind: "clip",
+                id: clip.id,
+                name: document.metadata.clips[clip.id]?.name ??
+                    names.get(clip.source_id) ??
+                    clip.source_id,
+                trackId: track.id,
+                start: clip.timeline_range.start,
+                end: clip.timeline_range.end,
+            });
+        for (const transition of track.transitions ?? [])
+            entries.push({
+                kind: "transition",
+                id: `${transition.from_clip}->${transition.to_clip}`,
+                name: transition.effect.id,
+                trackId: track.id,
+                start: transition.timeline_range.start,
+                end: transition.timeline_range.end,
+            });
+        (track.captions?.cues ?? []).forEach((cue, index) => entries.push({
+            kind: "caption",
+            id: `${track.id}#${index}`,
+            name: cue.text,
+            trackId: track.id,
+            start: cue.timeline_range.start,
+            end: cue.timeline_range.end,
+        }));
+    }
+    for (const marker of document.metadata.markers)
+        entries.push({
+            kind: "marker",
+            id: marker.id,
+            name: marker.name,
+            trackId: null,
+            start: marker.time,
+            end: marker.end ?? marker.time,
+            marker,
+        });
+    const order = { marker: 0, clip: 1, transition: 2, caption: 3 };
+    entries.sort((a, b) => a.start - b.start ||
+        order[a.kind] - order[b.kind] ||
+        (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    indexes.set(document, entries);
+    return entries;
+}

package/dist/core/transitions.d.ts

@@ -0,0 +1,20 @@
+import type { ClipEffect, Track } from "alpha2/project";
+/**
+ * `track` with a transition of `duration` ticks from clip `fromId` into `toId`, ending where
+ * `fromId` ends. `toId` and the clips chained after it move earlier so it overlaps `fromId` by
+ * `duration`.
+ *
+ * Throws an `EditorError` (`invalid_transition`) when the clips are missing or the same, either
+ * edge already has a transition, or `duration` is not positive and shorter than both clips.
+ */
+export declare function addTransition(track: Track, fromId: string, toId: string, duration: number, effect: ClipEffect): Track;
+/**
+ * `track` with transition `index` given `duration` ticks, keeping its end at the outgoing clip's
+ * end and moving the incoming clip's chain to match. Throws like {@link addTransition}.
+ */
+export declare function resizeTransition(track: Track, index: number, duration: number): Track;
+/**
+ * `track` without transition `index`. The incoming clip and its chain move later so it starts
+ * where the outgoing clip ends. Throws an `EditorError` for an unknown index.
+ */
+export declare function removeTransition(track: Track, index: number): Track;

package/dist/core/transitions.js

@@ -0,0 +1,118 @@
+import { EditorError } from "./document.js";
+const fail = (message) => {
+    throw new EditorError("invalid_transition", message, "transition");
+};
+/**
+ * `value` with every keyframe time moved `delta` ticks. Every `Animated<T>` in a clip, masks
+ * included, uses timeline ticks; its composition keeps its own time.
+ */
+function shifted(value, delta) {
+    if (!value || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => shifted(v, delta));
+    const object = value;
+    if (object.mode === "keyframes" && Array.isArray(object.keyframes))
+        return {
+            ...object,
+            keyframes: object.keyframes.map((key) => ({
+                ...key,
+                time: key.time + delta,
+            })),
+        };
+    return Object.fromEntries(Object.entries(object).map(([key, v]) => [key, shifted(v, delta)]));
+}
+/**
+ * `track` with clip `id` starting at `start`, and the clips that follow it through transitions (its
+ * outgoing transition's clip, that clip's, and so on) moved as far with their transitions, so each
+ * overlap the chain holds stays exact. Collisions with other clips are for validation to refuse.
+ */
+function moveChain(track, id, start) {
+    const clip = track.clips.find((c) => c.id === id);
+    const delta = start - clip.timeline_range.start;
+    if (delta === 0)
+        return track;
+    const chain = new Set();
+    for (let at = id; at !== undefined && !chain.has(at);) {
+        chain.add(at);
+        const from = at;
+        at = track.transitions?.find((t) => t.from_clip === from)?.to_clip;
+    }
+    const range = (r) => ({
+        start: r.start + delta,
+        end: r.end + delta,
+    });
+    return {
+        ...track,
+        clips: track.clips.map((c) => chain.has(c.id)
+            ? { ...shifted(c, delta), timeline_range: range(c.timeline_range) }
+            : c),
+        transitions: track.transitions?.map((t) => chain.has(t.from_clip)
+            ? { ...shifted(t, delta), timeline_range: range(t.timeline_range) }
+            : t),
+    };
+}
+/**
+ * `track` with a transition of `duration` ticks from clip `fromId` into `toId`, ending where
+ * `fromId` ends. `toId` and the clips chained after it move earlier so it overlaps `fromId` by
+ * `duration`.
+ *
+ * Throws an `EditorError` (`invalid_transition`) when the clips are missing or the same, either
+ * edge already has a transition, or `duration` is not positive and shorter than both clips.
+ */
+export function addTransition(track, fromId, toId, duration, effect) {
+    const from = track.clips?.find((c) => c.id === fromId), to = track.clips?.find((c) => c.id === toId);
+    if (!from || !to || fromId === toId)
+        fail("Select two different clips on the same track");
+    if ((track.transitions ?? []).some((t) => t.from_clip === fromId || t.to_clip === toId))
+        fail("This clip edge already has a transition");
+    const transition = {
+        from_clip: fromId,
+        to_clip: toId,
+        timeline_range: {
+            start: from.timeline_range.end - duration,
+            end: from.timeline_range.end,
+        },
+        effect,
+        easing: { type: "linear" },
+    };
+    return resizeTransition({ ...track, transitions: [...(track.transitions ?? []), transition] }, (track.transitions ?? []).length, duration);
+}
+/**
+ * `track` with transition `index` given `duration` ticks, keeping its end at the outgoing clip's
+ * end and moving the incoming clip's chain to match. Throws like {@link addTransition}.
+ */
+export function resizeTransition(track, index, duration) {
+    const transition = track.transitions?.[index];
+    if (!transition)
+        fail("Unknown transition");
+    const from = track.clips.find((c) => c.id === transition.from_clip), to = track.clips.find((c) => c.id === transition.to_clip);
+    if (!Number.isSafeInteger(duration) ||
+        duration <= 0 ||
+        duration >=
+            Math.min(from.timeline_range.end - from.timeline_range.start, to.timeline_range.end - to.timeline_range.start))
+        fail("Transition duration must be positive and shorter than both clips");
+    const start = from.timeline_range.end - duration;
+    const moved = moveChain(track, to.id, start);
+    return {
+        ...moved,
+        transitions: moved.transitions.map((t, i) => i === index
+            ? { ...t, timeline_range: { start, end: from.timeline_range.end } }
+            : t),
+    };
+}
+/**
+ * `track` without transition `index`. The incoming clip and its chain move later so it starts
+ * where the outgoing clip ends. Throws an `EditorError` for an unknown index.
+ */
+export function removeTransition(track, index) {
+    const transition = track.transitions?.[index];
+    if (!transition)
+        fail("Unknown transition");
+    const from = track.clips.find((c) => c.id === transition.from_clip);
+    const moved = moveChain(track, transition.to_clip, from.timeline_range.end);
+    return {
+        ...moved,
+        transitions: moved.transitions.filter((_, i) => i !== index),
+    };
+}

package/dist/core/validated.d.ts

@@ -0,0 +1,23 @@
+import type { Project } from "alpha2/project";
+/**
+ * Records that `project` passed `validateProject`. A deep-frozen project is remembered for good;
+ * another only until the `withValidated` call running now returns, since its owner may change it
+ * later.
+ */
+export declare function rememberValid(project: Project): void;
+/** Whether `project` is known to pass `validateProject` (see `rememberValid`). */
+export declare function knownValid(project: Project): boolean;
+/** Runs `run`, forgetting when it returns the unfrozen projects it called valid. */
+export declare function withValidated<T>(run: () => T): T;
+/**
+ * Deep-freezes `document`, which validated, and remembers its project as valid, so compiling it or
+ * checking it again does not walk the project again.
+ */
+export declare function frozenValid<T extends {
+    readonly project: Project;
+}>(document: T): T;
+/**
+ * `document` itself when {@link frozenValid} froze it, which nothing can change, or else a copy
+ * for a session to own. Keeping the frozen document keeps what validating its parts found.
+ */
+export declare function owned<T extends object>(document: T): T;

package/dist/core/validated.js

@@ -0,0 +1,52 @@
+import { freeze } from "./document.js";
+/** Deep-frozen projects that validated: they cannot change, so they stay valid. */
+const frozen = new WeakSet();
+/** Projects an edit validated during the `executeCommand` running now (see `withValidated`). */
+let current = null;
+/**
+ * Records that `project` passed `validateProject`. A deep-frozen project is remembered for good;
+ * another only until the `withValidated` call running now returns, since its owner may change it
+ * later.
+ */
+export function rememberValid(project) {
+    if (Object.isFrozen(project))
+        frozen.add(project);
+    else
+        current?.add(project);
+}
+/** Whether `project` is known to pass `validateProject` (see `rememberValid`). */
+export function knownValid(project) {
+    return frozen.has(project) || (current?.has(project) ?? false);
+}
+/** Runs `run`, forgetting when it returns the unfrozen projects it called valid. */
+export function withValidated(run) {
+    const previous = current;
+    current = new WeakSet();
+    try {
+        return run();
+    }
+    finally {
+        current = previous;
+    }
+}
+/**
+ * Documents {@link frozenValid} froze: plain data the editor made or copied, frozen all through.
+ */
+const sealedDocuments = new WeakSet();
+/**
+ * Deep-freezes `document`, which validated, and remembers its project as valid, so compiling it or
+ * checking it again does not walk the project again.
+ */
+export function frozenValid(document) {
+    freeze(document);
+    rememberValid(document.project);
+    sealedDocuments.add(document);
+    return document;
+}
+/**
+ * `document` itself when {@link frozenValid} froze it, which nothing can change, or else a copy
+ * for a session to own. Keeping the frozen document keeps what validating its parts found.
+ */
+export function owned(document) {
+    return sealedDocuments.has(document) ? document : structuredClone(document);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./core/document.js";
+export * from "./core/time.js";
+export * from "./core/commands.js";
+export * from "./core/compositions.js";
+export * from "./core/clip-time.js";
+export * from "./core/session.js";
+export * from "./core/timeline-index.js";
+export * from "./core/keyframes.js";
+export * from "./core/presets.js";
+export * from "./core/captions.js";
+export * from "./core/text.js";
+export type * from "./ports/index.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from "./core/document.js";
+export * from "./core/time.js";
+export * from "./core/commands.js";
+export * from "./core/compositions.js";
+export * from "./core/clip-time.js";
+export * from "./core/session.js";
+export * from "./core/timeline-index.js";
+export * from "./core/keyframes.js";
+export * from "./core/presets.js";
+export * from "./core/captions.js";
+export * from "./core/text.js";

package/dist/native-client/index.d.ts

@@ -0,0 +1,131 @@
+import type { MediaFingerprint } from "alpha2/project";
+import type { EditorDocument } from "../core/document.js";
+import type { EditorSnapshot } from "../core/session.js";
+import { type ExportFailure } from "alpha2/export-failure";
+import { ExportJob } from "../browser/jobs.js";
+import type { BrowserExportOptions } from "../browser/types.js";
+/**
+ * A file uploaded for a native export, usually produced by the browser bridge's `nativeAssets`.
+ * The host reads media only from these uploads, never from a filesystem path the document names.
+ */
+export interface NativeAsset {
+    /** The source, resource or font id the file belongs to (for `frames`, the upload's own id). */
+    readonly id: string;
+    /**
+     * `proxies`: a proxy standing in for source `id`, made from `madeFrom`. `frames`: one frame of an
+     * image sequence, the file at `locator`.
+     */
+    readonly kind: "assets" | "effect-assets" | "caption-fonts" | "proxies" | "frames";
+    readonly blob: Blob;
+    /** The original file name, sent to the host percent-encoded. */
+    readonly name: string;
+    readonly madeFrom?: MediaFingerprint;
+    readonly locator?: string;
+}
+/**
+ * Export settings for a native job: the browser export's options, plus the MPEG-4 Part 2 codec the
+ * host can encode.
+ */
+export interface NativeExportOptions extends Omit<BrowserExportOptions, "videoCodec"> {
+    readonly videoCodec?: BrowserExportOptions["videoCodec"] | "mpeg4-part2";
+}
+/** A finished native export's file, as the service keeps it. */
+export interface NativeArtifactDescriptor {
+    readonly name: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly createdAt: number;
+    /** When the service deletes it, in milliseconds since the epoch. */
+    readonly expiresAt: number;
+}
+/** Whether a kept file can still be downloaded, and if not, why. */
+export type NativeArtifactStatus = {
+    readonly status: "available";
+    readonly expiresAt: number | null;
+} | {
+    readonly status: "gone";
+    /** `expired`, `deleted`, or `evicted`, as the service says. */
+    readonly reason: string;
+} | {
+    readonly status: "missing" | "unreachable";
+};
+/**
+ * Asks the service whether the file at `url` (an artifact's) can still be downloaded, without
+ * downloading it. Never rejects: a network error is `unreachable`, a 404 is `missing`, and a 410
+ * is `gone` with the reason the service gives (`expired` when it gives none).
+ */
+export declare function nativeArtifactStatus(url: string, request?: typeof fetch): Promise<NativeArtifactStatus>;
+/** A native job's state as the service reports it. */
+export interface NativeJobState {
+    readonly phase: "preparing" | "rendering" | "finalizing" | "publishing" | "completed" | "failed" | "cancelled";
+    /** The finished file, once `completed`. */
+    readonly artifact?: NativeArtifactDescriptor;
+    /** The share done, from 0 to 1. */
+    readonly fraction: number;
+    readonly frames?: {
+        readonly completed: number;
+        readonly total: number;
+    };
+    /** The failure message, when `failed` or `cancelled`. */
+    readonly error?: string;
+    /** The host's classified failure, when `failed`. */
+    readonly failure?: ExportFailure;
+    /**
+     * The host's report on the render cache of the last attempt to finish rendering: `used` with its
+     * counts, or `unavailable` with why (the GPU-resident path bakes nothing); `null` for an attempt
+     * rendered without one (a first attempt, a short export). Absent until an attempt reports.
+     */
+    readonly resume?: {
+        readonly status: "used";
+        readonly [count: string]: unknown;
+    } | {
+        readonly status: "unavailable";
+        readonly reason: string;
+    } | null;
+}
+export interface NativeClientOptions {
+    /** The export service's root URL; a trailing slash is ignored. */
+    readonly baseUrl: string;
+    /** The `fetch` used for every request; the global one by default. */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * A client for the native export service (`@alpha2-sh/node`'s HTTP host). Exports run on the service
+ * with the editor's retry policy; each job uploads its assets once and reuses them across attempts.
+ */
+export declare function createNativeClient(options: NativeClientOptions): {
+    /** The service's `/health` report. Rejects when the service answers with an error status. */
+    capabilities(): Promise<Record<string, unknown>>;
+    /**
+     * Starts an export of `editor.document` on the service and returns its job. The document,
+     * `assets` and `settings` are captured now; later edits do not reach the job. `assets` may be
+     * a function, called once per upload with the document and the attempt's signal. The range is
+     * the document's export range, else the whole timeline. Throws when the client is disposed,
+     * and an `EditorError` `invalid_frame_rate` for a `frameRate` the engine does not read.
+     */
+    startExport(editor: Pick<EditorSnapshot, "document" | "revision">, assets: readonly NativeAsset[] | ((document: EditorDocument, signal: AbortSignal) => Promise<readonly NativeAsset[]>), settings?: NativeExportOptions): ExportJob;
+    /**
+     * What the service knows of job `id`, for a page that lost the job it started (it was
+     * reloaded): its state, and where its file can be downloaded once it is complete. Null when the
+     * service no longer has the job. Rejects on any other error status.
+     */
+    jobState(id: string): Promise<(NativeJobState & {
+        readonly url?: string;
+    }) | null>;
+    /**
+     * Removes job `id` from the service: a render it runs stops, and its kept file is deleted. For
+     * a job this client did not start, such as one a page that is gone left (see
+     * {@link jobState}). Rejects when the service answers with an error status.
+     */
+    releaseJob(id: string): Promise<void>;
+    /** Cancels every running job and refuses new ones. Resolves once the cancellations settle. */
+    dispose(): Promise<void>;
+    /**
+     * Lets go of every running job and refuses new ones, for a page that is leaving, without
+     * cancelling what the service already renders: a job whose render was asked for goes on there
+     * and keeps its file, for a later page to find with {@link jobState}. A job still uploading is
+     * removed, since only this client could send the rest. The jobs here settle as cancelled.
+     * Resolves once they settle; a removal that fails is left to the service's lease.
+     */
+    detach(): Promise<void>;
+};