@alpha2-sh/editor 0.0.0-stage → 0.1.0

package/dist/core/compositions.d.ts

@@ -0,0 +1,234 @@
+import type { Clip, ClipEffect, Composition, CompositionNode, Project } from "alpha2/project";
+/** One effect of a clip's effect stack: an effect node of its composition. */
+export interface StackEntry {
+    /** The effect node's id, stable across edits. */
+    readonly id: string;
+    readonly effect: ClipEffect;
+    readonly bypass: boolean;
+}
+/**
+ * The composition `id` names in `project`. Looked up in an index of the project's compositions
+ * array, made once per array, so walks that find many compositions stay linear. An index a changed
+ * array no longer matches is made again, and an id it lacks is looked for in the array itself.
+ */
+export declare function findComposition(project: Project, id: string): Composition | undefined;
+/**
+ * A clip's effects as a stack: its composition when that is the clip's picture through a chain of
+ * effect nodes and nothing else, bottom first. A clip without a composition has an empty stack.
+ * `undefined` means the composition is a graph a stack cannot show: it branches, merges, reads
+ * other sources, or has loose nodes.
+ */
+export declare function effectStack(project: Project, clip: Clip): readonly StackEntry[] | undefined;
+/** An id based on `base` that no composition in `project` has. */
+export declare function freeCompositionId(project: Project, base: string): string;
+/**
+ * `project` with clip `clipId` showing its picture through `stack`, bottom first: its composition
+ * rewritten as that chain, or removed with the reference when the stack is empty. The composition
+ * keeps its id and the clip its time mapping; a clip without one gets `<clip id>-fx`.
+ * Throws when `clipId` names no clip.
+ */
+export declare function withEffectStack(project: Project, clipId: string, stack: readonly StackEntry[]): Project;
+/**
+ * The compositions `id` draws: itself and, through group nodes, the group definitions it uses, each
+ * once.
+ */
+export declare function compositionTree(project: Project, id: string): Composition[];
+/**
+ * Ids of the compositions `project` draws: those clips show and composition sources show (Library
+ * items), and those these use through group nodes and composition sources, as far as they go.
+ */
+export declare function drawnCompositions(project: Project): Set<string>;
+/**
+ * `after` without the compositions `before` drew and `after` no longer does: a clip owns the
+ * composition it shows, so the edit that stops the last drawing of one (deleting its clip or track,
+ * removing its Library source or the group node that drew it, emptying an effect stack) removes it,
+ * and the group definitions only it drew with it. A composition `before` did not draw stays, so one
+ * added for a later edit (a macro's definition) waits for it. Returns the ids it removed.
+ */
+export declare function withoutUndrawn(before: Project, after: Project): {
+    readonly project: Project;
+    readonly removed: ReadonlySet<string>;
+};
+/**
+ * `project` with `clip` given compositions no other clip draws, for a clip a command puts down (a
+ * paste, a duplicate). With `compositions`, those the clip drew when it was copied, it shows a copy
+ * of them whatever the project has now. Otherwise it shows a copy of its composition when anything
+ * else draws that composition or a group definition in it, and the composition itself when nothing
+ * does. A copy takes free ids based on `<root>~<clip id>` ({@link copyComposition}), so the clip is
+ * edited independently of its original. Returns the copies' ids by their originals'.
+ */
+export declare function ownComposition(project: Project, clip: Clip, compositions?: readonly Composition[]): {
+    readonly project: Project;
+    readonly clip: Clip;
+    readonly copies: ReadonlyMap<string, string>;
+};
+/**
+ * The compositions `copy` draws for those `original` draws, by id: the two themselves, and the
+ * definitions of their group nodes of the same id, as far as they go. A composition copied for a
+ * split or a paste corresponds to its original this way.
+ */
+export declare function correspondingCompositions(project: Project, original: string, copy: string): Map<string, string>;
+/**
+ * Composition time at timeline time `tick` for `clip`: `offset + (tick - start) * scale`, rounded
+ * down, as the engine maps it. Without a composition, timeline time. Time is whole ticks; a
+ * fraction (a curve sampled between ticks) reads as the tick it falls in.
+ */
+export declare function compositionTime(clip: Clip, tick: number): number;
+/**
+ * The first timeline time at which `clip` shows composition time `time`: the inverse of
+ * {@link compositionTime}, rounded up to a tick. A fractional `time` is first rounded up to the
+ * next whole tick.
+ */
+export declare function timelineTime(clip: Clip, time: number): number;
+/**
+ * Ids of the sources `tracks`' clips draw: each clip's own, and those the media nodes its
+ * compositions' outputs need read (the inputs {@link CompositionReads.neededInputs} names: of a
+ * group node only the ports its composition reads), through group nodes and composition sources
+ * too. A clip's composition source counts only where the clip's own composition draws the clip. The
+ * engine's `Project::used_sources` is the same set; `tests/cases/used-sources-corpus.json` holds both to
+ * it.
+ */
+export declare function shownSources(project: Project, tracks?: Project["timeline"]["tracks"]): Set<string>;
+/**
+ * Ids of the effect resources (`effect_resources`) what `tracks` draw reads: those the effect and
+ * transition nodes drawing {@link shownSources} evaluates name (not a bypassed node's), and those
+ * the tracks' transitions name. Only these must be registered for a render: the engine asks for a
+ * resource when a node it evaluates needs one.
+ */
+export declare function drawnEffectResources(project: Project, tracks?: Project["timeline"]["tracks"]): Set<string>;
+/**
+ * A node input as graph commands name it: `input`, `from`, `to`, `matte`, or a merge layer's index.
+ */
+export type InputKey = "input" | "from" | "to" | "matte" | number;
+/** The input keys of a node's operation, in order. */
+export declare function inputKeys(op: CompositionNode["op"]): InputKey[];
+/**
+ * The inputs drawing `node` reads: only its pass-through input (the first) when it is bypassed, and
+ * every input otherwise.
+ */
+export declare function neededInputs(node: CompositionNode): InputKey[];
+/** What each composition's output reads, as alpha2-model's `CompositionReads`. */
+export interface CompositionReads {
+    /**
+     * Whether composition `id`'s output reads its group input `port`; true for a composition it does
+     * not know.
+     */
+    readsPort(id: string, port: number): boolean;
+    /**
+     * Whether composition `id`, shown by a clip, draws the clip's picture: its output reaches a clip
+     * node, directly or in a group. True for a composition it does not know.
+     */
+    drawsClip(id: string): boolean;
+    /**
+     * The inputs drawing `node` reads: its {@link neededInputs}, of a group node only the ports its
+     * composition reads.
+     */
+    neededInputs(node: CompositionNode): InputKey[];
+}
+/**
+ * What each of `compositions` reads: the group inputs and clip nodes a walk from its output
+ * reaches, along the inputs drawing each node reads, into the compositions its group nodes draw. A
+ * group draws what its nodes would inline, so a group node needs only the ports its composition
+ * reads: a port it never reads may be left unconnected, and what a connected one reads is not
+ * drawn. A composition that uses itself (which validation refuses) reads every port and draws the
+ * clip.
+ */
+export declare function compositionReads(compositions: readonly Composition[]): CompositionReads;
+/** The node an input reads, or `undefined` when it is unconnected or absent. */
+export declare function inputOf(op: CompositionNode["op"], key: InputKey): string | undefined;
+/**
+ * `op` with input `key` reading `node` (`null` disconnects it). Throws when `op` has no input
+ * `key`.
+ */
+export declare function withInput(op: CompositionNode["op"], key: InputKey, node: string | null): CompositionNode["op"];
+/**
+ * How a composition is drawn, which decides what its clip nodes and group inputs read, as the
+ * engine plans it.
+ *
+ * - `clip`: a clip's own composition. Its clip nodes draw the clip; no group node feeds its group
+ *   inputs.
+ * - `source`: a composition source, drawn by a clip or a media node. Nothing feeds its clip nodes
+ *   or its group inputs.
+ * - `group`: a group's definition, opened on its own. Its group inputs read the group node's
+ *   inputs, and whether its clip nodes draw anything depends on where the group is drawn, so
+ *   neither is an issue here.
+ */
+export type GraphUse = "clip" | "source" | "group";
+/**
+ * Why a composition's output cannot be drawn: the engine's four reasons for refusing it as an
+ * incomplete composition (`INCOMPLETE_COMPOSITION`). An issue inside a composition that a group or
+ * media node draws names its node as the engine does, prefixed by the drawing node's id and `/`
+ * (`group/blur`); a `no_output` there names the drawing node.
+ */
+export type GraphIssue = {
+    readonly kind: "no_output";
+    readonly node?: string;
+} | {
+    readonly kind: "missing_input";
+    readonly node: string;
+    readonly input: InputKey;
+}
+/** A group input no group node feeds: in a clip's composition or a composition source. */
+ | {
+    readonly kind: "unbound_group_input";
+    readonly node: string;
+}
+/** A clip node in a composition source, which shows no clip. */
+ | {
+    readonly kind: "clip_without_clip";
+    readonly node: string;
+};
+/**
+ * What {@link graphIssues} reads to follow group and media nodes into the compositions they draw.
+ */
+export interface GraphProject {
+    readonly compositions?: readonly Composition[] | null;
+    readonly sources: readonly {
+        readonly id: string;
+        readonly composition?: string | null;
+    }[];
+}
+/**
+ * What stops `composition`'s output from rendering when it is drawn as `use`: no output, an
+ * unconnected input a node the output reaches uses (only the pass-through input of a bypassed node,
+ * and of a group node only the ports its composition reads), a group input nothing feeds, or a clip
+ * node where there is no clip. The engine refuses the same frames with `INCOMPLETE_COMPOSITION`;
+ * this lets an editor mark the nodes before it asks.
+ *
+ * With `project`, the issues of the compositions the output's group and media nodes draw are
+ * included, as the engine plans them inline; without it those nodes are taken as drawn.
+ */
+export declare function graphIssues(composition: Composition, use: GraphUse, project?: GraphProject): GraphIssue[];
+/** An id based on `base` that no node of `composition` has. */
+export declare function freeNodeId(composition: Composition, base: string): string;
+/**
+ * `composition` without the nodes `ids`, every input that read one of them disconnected, no output
+ * if it was one of them, and no control that exposed one of them.
+ */
+export declare function withoutNodes(composition: Composition, ids: readonly string[]): Composition;
+/**
+ * `composition` with nodes `ids` folded into a group node `groupId` that draws a new composition
+ * `definitionId` of them: each node outside the selection that a selected node reads becomes one of
+ * its inputs, in the order first read, and the one selected node read from outside (or the output)
+ * becomes its output. A selected group input stays in `composition`: it reads `composition`'s own
+ * input, which a node inside the group reads through a port like any node outside. The picture does
+ * not change.
+ *
+ * @throws When the selection is empty or only group inputs, names an absent node, `groupId` names
+ * an unselected node, or other than one selected node's picture leaves the selection.
+ */
+export declare function groupNodes(composition: Composition, ids: readonly string[], groupId: string, definitionId: string): {
+    readonly parent: Composition;
+    readonly definition: Composition;
+};
+/**
+ * `composition` with group node `groupId` replaced by the nodes of the composition it draws, under
+ * ids based on `<group>-<node>`: its group inputs read what the group node's inputs read, its
+ * controls keep the values the group node set, and what read the group reads its output. Returns
+ * the new ids by inner id. The picture does not change.
+ * Throws when `groupId` is not a group node of `composition`.
+ */
+export declare function ungroupNode(composition: Composition, groupId: string, definition: Composition): {
+    readonly parent: Composition;
+    readonly ids: ReadonlyMap<string, string>;
+};