@alpha2-sh/editor 0.0.0 → 0.1.0

package/dist/core/document.d.ts

@@ -0,0 +1,245 @@
+import type { ExportFailureCode } from "alpha2/export-failure";
+import type { ClipTransition, MediaFingerprint, Project, Track, Clip, ProjectSettings, TimeRange } from "alpha2/project";
+/** A JSON value: what editor metadata and asset authoring data may hold. */
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+/** A bin asset: what the editor knows about a project source or effect resource. */
+export interface AssetDescriptor {
+    /** The id of the project source or effect resource it describes. */
+    readonly id: string;
+    /**
+     * The source kind (`video`, `image`, `generated`, ...), or an editor-only kind such as
+     * `captions`.
+     */
+    readonly kind: string;
+    /** The display name, usually the imported file's name. */
+    readonly name: string;
+    /**
+     * A non-negative safe integer that changes whenever the asset's content is replaced (a relink).
+     */
+    readonly contentRevision: number;
+    /** Whether the asset's media is offline. */
+    readonly missing?: boolean;
+    /** Where the media is read from, when it is not kept in the document. */
+    readonly locator?: string;
+    /** Data the asset is built from: a text asset's `text` style, a captions asset's cue rows. */
+    readonly authoring?: Json;
+    /** Evidence of the file imported, as the project source records it too. */
+    readonly fingerprint?: MediaFingerprint;
+}
+/**
+ * A track's editor metadata. A `locked` track refuses every edit that changes what it renders; a
+ * track with `enabled: false` draws and plays nothing (see {@link compileEditorDocument}).
+ */
+export interface TrackMetadata {
+    readonly locked?: boolean;
+    readonly enabled?: boolean;
+    /** A `#rrggbb` color. */
+    readonly color?: string;
+    /**
+     * Whether a ripple edit on another track moves this track's content after the edit point too,
+     * keeping it in sync.
+     */
+    readonly syncLock?: boolean;
+}
+/** A clip's editor metadata. A clip without a `name` shows its source's name. */
+export interface ClipMetadata {
+    readonly name?: string;
+}
+/** A timeline marker: an instant, or a range when it has an `end`. */
+export interface Marker {
+    readonly id: string;
+    /** Where it is, in timeline ticks. */
+    readonly time: number;
+    /** Where a range marker ends; after `time`. */
+    readonly end?: number;
+    readonly name: string;
+    readonly note?: string;
+    /** A `#rrggbb` color. */
+    readonly color?: string;
+    /** Whether what it notes is done. */
+    readonly done?: boolean;
+}
+/** A node's place in the node editor, in canvas pixels. */
+export interface GraphPosition {
+    readonly x: number;
+    readonly y: number;
+}
+/** Node positions by composition, then node: editor metadata, not render input. */
+export type GraphLayout = Readonly<Record<string, Readonly<Record<string, GraphPosition>>>>;
+/** What the editor keeps beside the engine project: none of it is render input. */
+export interface EditorMetadata {
+    /** By track id. */
+    readonly tracks: Readonly<Record<string, TrackMetadata>>;
+    /** By clip id. */
+    readonly clips: Readonly<Record<string, ClipMetadata>>;
+    /**
+     * Stable ids for list items the project keeps without one, by list (`<trackId>/cues`,
+     * `<trackId>/transitions`, `<clipId>/masks`). Maintained by {@link withInstanceIds}.
+     */
+    readonly instanceIds: Readonly<Record<string, readonly string[]>>;
+    readonly markers: readonly Marker[];
+    /** The range an export renders by default, in timeline ticks; `null` for the whole timeline. */
+    readonly exportRange: TimeRange | null;
+    /** Node positions of the effect graph view. */
+    readonly graphLayout?: GraphLayout;
+    /**
+     * Names of compositions drawn as groups, by composition id: editor metadata, not render input.
+     */
+    readonly graphNames?: Readonly<Record<string, string>>;
+}
+/** An editor project file: the engine project plus editor metadata and bin assets. */
+export interface EditorDocument {
+    readonly format: "alpha2-editor-project";
+    readonly version: 1;
+    readonly project: Project;
+    readonly metadata: EditorMetadata;
+    readonly assets: Readonly<Record<string, AssetDescriptor>>;
+}
+/** An editor refusal or failure, with a machine-readable `code` (a snake_case identifier). */
+export declare class EditorError extends Error {
+    readonly code: string;
+    readonly operation: string;
+    readonly entityId?: string | undefined;
+    readonly recoverable: boolean;
+    /**
+     * @param code What went wrong, such as `invalid_command` or `locked`.
+     * @param message A human-readable description.
+     * @param operation The operation that failed, such as `validate`, `open` or a command name.
+     * @param entityId The track, clip, asset or other entity the error concerns, when there is one.
+     * @param recoverable Whether the editor stays usable after the error. Defaults to `true`.
+     */
+    constructor(code: string, message: string, operation: string, entityId?: string | undefined, recoverable?: boolean, options?: ErrorOptions);
+    /**
+     * The export failure class this error is evidence of, which `classifyBrowserFailure` reads: the
+     * editor knows what its own refusals mean. `UNKNOWN` for a code without a class.
+     */
+    get failureCode(): ExportFailureCode;
+}
+/** The outcome of an operation that reports its refusal instead of throwing it. */
+export type Result<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: EditorError;
+};
+/** Deep-freezes `value` in place and returns it. Already frozen objects are not descended into. */
+export declare function freeze<T>(value: T): T;
+/**
+ * The deepest nesting of arrays and objects an editor document may have: the engine's for its
+ * project ({@link MAX_JSON_DEPTH}), and one more for the document that holds it.
+ */
+export declare const MAX_DOCUMENT_JSON_DEPTH: number;
+/**
+ * Throws an `EditorError` (`invalid_document`) unless `value` is plain JSON: finite numbers, and
+ * arrays and plain objects of JSON values only, nested at most `maxDepth` arrays and objects deep
+ * ({@link MAX_DOCUMENT_JSON_DEPTH} by default).
+ */
+export declare function assertJson(value: unknown, maxDepth?: number): void;
+/**
+ * Throws an `EditorError` unless `document` is a valid editor document: finite JSON within the
+ * engine and editor file size limits, a supported format and version, a project the engine
+ * accepts, and well-formed editor metadata and assets.
+ */
+export declare function validateDocument(document: EditorDocument): void;
+/**
+ * Throws the first `invalid_projection` error of `document`'s projection (the project without what
+ * disabled tracks draw and play), so a document that opens is one the engine renders.
+ */
+export declare function assertProjection(document: EditorDocument): void;
+/**
+ * The checks a gesture's candidate needs on every pointer move: the format and the project's
+ * rules. What `validateDocument` adds (every value is finite JSON, the engine JSON and the editor
+ * file fit their size limits) walks or serializes the whole document, so a gesture runs it once,
+ * when it commits. The project's rules cost a candidate the parts its command changed:
+ * `validateProject` reuses what it found of the frozen parts the candidate shares with the
+ * gesture's start. Throws an `EditorError` (`unsupported_version` or `invalid_project`).
+ */
+export declare function validateDocumentShape(document: EditorDocument): void;
+/**
+ * The largest editor file {@link parseDocument} opens. Every document that validates fits it, as
+ * {@link serializeDocument} writes it.
+ */
+export declare const MAX_EDITOR_FILE_BYTES: number;
+/**
+ * A new frozen document holding a copy of `project`, with an asset for each source and effect
+ * resource (offline unless generated or a composition) overridden by `assets`. Throws an
+ * `EditorError` when the result does not validate.
+ */
+export declare function createDocument(project: Project, assets?: EditorDocument["assets"]): EditorDocument;
+/** A new document with no media: 1920x1080 at 30 fps and 48 kHz unless `settings` say otherwise. */
+export declare function createEmptyDocument(settings?: Partial<ProjectSettings>): EditorDocument;
+/**
+ * The editor file of `document`: compact JSON, so a document that validates is a file
+ * {@link parseDocument} opens. Throws an `EditorError` when the document does not validate.
+ */
+export declare function serializeDocument(document: EditorDocument): string;
+/**
+ * Opens an editor file, or a bare engine project (JSON with `schema_version`) as a new document.
+ * Returns a frozen document. Every refusal is an `EditorError`: `too_large` for a file over
+ * {@link MAX_EDITOR_FILE_BYTES}, `invalid_document` for text that is not an editor document's JSON,
+ * and the code of the check a document (or project) fails otherwise.
+ */
+export declare function parseDocument(text: string): EditorDocument;
+/**
+ * The id of `transition` on track `trackId`: the edge it joins, which a track has one transition
+ * on. It stays the transition's own while other transitions come and go, and changes when its clips
+ * do (a split hands an outgoing transition to the right part).
+ */
+export declare function transitionInstanceId(trackId: string, transition: Pick<ClipTransition, "from_clip" | "to_clip">): string;
+/**
+ * `document` with an instance id for every caption cue, transition and clip mask: each track's
+ * transitions named by {@link transitionInstanceId}; cues and masks keep the ids they have, and
+ * those without one get a new one no other in the list has. Returns `document` itself when nothing
+ * changes, and leaves a document of the wrong shape for validation to refuse.
+ */
+export declare function withInstanceIds(document: EditorDocument): EditorDocument;
+/** A document's tracks and clips by id. */
+export interface EntityIndex {
+    readonly tracks: ReadonlyMap<string, Track>;
+    readonly clips: ReadonlyMap<string, {
+        readonly clip: Clip;
+        readonly trackId: string;
+    }>;
+}
+/** The {@link EntityIndex} of `document`, built once per document object and cached. */
+export declare function indexDocument(document: EditorDocument): EntityIndex;
+/** What the engine renders of a document. */
+export interface CompiledEditorDocument {
+    /**
+     * The project as the engine renders it: what disabled tracks draw and play left out, the mattes
+     * enabled clips name kept (see `compileEditorDocument`).
+     */
+    readonly project: Project;
+    /** The engine's validation errors for `project`, as `invalid_projection` errors. */
+    readonly diagnostics: readonly EditorError[];
+    /** The projection's JSON: equal keys render the same. Serialized on first read. */
+    readonly revisionKey: string;
+}
+/**
+ * The project the engine renders for `document`. A disabled track draws and plays nothing: it is
+ * left out, but for the clips enabled clips name as mattes (never drawn themselves), kept on it
+ * muted; a track that ducks under a disabled track does not duck; a clip only disabled clips name
+ * as their matte draws nothing but still plays. Never throws for an invalid projection; the errors
+ * are in `diagnostics`. Cached for frozen documents.
+ */
+export declare function compileEditorDocument(document: EditorDocument): CompiledEditorDocument;
+/**
+ * Where `project`'s timeline ends, in ticks: the end of its last clip or caption cue, 0 when it has
+ * neither.
+ */
+export declare function sequenceEnd(project: Project): number;
+/**
+ * Where `document`'s program ends, in ticks: the {@link sequenceEnd} of what the engine renders of
+ * it ({@link compileEditorDocument}), so a disabled track adds no length. Playback without an
+ * export range stops there, an export without one ends there, and an export range with only its
+ * start set runs to it.
+ */
+export declare function programEnd(document: EditorDocument): number;
+/**
+ * Seeds the {@link indexDocument} cache of `next` from that of `previous`, rebuilding entries only
+ * for tracks that changed. Does nothing when `previous` has no index.
+ */
+export declare function inheritDocumentIndex(previous: EditorDocument, next: EditorDocument): void;