@alpha2-sh/editor 0.0.0 → 0.1.0

package/dist/core/keyframes.d.ts

@@ -0,0 +1,82 @@
+import type { Animated } from "alpha2/project";
+type Keyframes<T> = Extract<Animated<T>, {
+    mode: "keyframes";
+}>;
+type Keyframe<T> = Keyframes<T>["keyframes"][number];
+/** How a keyframe eases to the next one. */
+export type Interpolation = Keyframe<unknown>["interpolation"];
+/** Common easing curves, as CSS names them. */
+export declare const EASINGS: {
+    readonly ease_in: {
+        readonly type: "cubic_bezier";
+        readonly x1: 0.42;
+        readonly y1: 0;
+        readonly x2: 1;
+        readonly y2: 1;
+    };
+    readonly ease_out: {
+        readonly type: "cubic_bezier";
+        readonly x1: 0;
+        readonly y1: 0;
+        readonly x2: 0.58;
+        readonly y2: 1;
+    };
+    readonly ease_in_out: {
+        readonly type: "cubic_bezier";
+        readonly x1: 0.42;
+        readonly y1: 0;
+        readonly x2: 0.58;
+        readonly y2: 1;
+    };
+};
+/**
+ * The keyframe at `from` moved to `to`, kept strictly between its neighbours (a tick from each), so
+ * the order of keyframes never changes. Returns the value and where the keyframe landed.
+ *
+ * Throws when `value` is not keyframed or has no keyframe at `from`. The keyframe-editing
+ * functions below throw in the same cases.
+ */
+export declare function moveKeyframe<T>(value: Animated<T>, from: number, to: number): {
+    readonly value: Animated<T>;
+    readonly time: number;
+};
+/** The keyframe at `time` removed; the last one removed leaves its value, constant. */
+export declare function removeKeyframe<T>(value: Animated<T>, time: number): Animated<T>;
+/** How the keyframe at `time` eases to the next. */
+export declare function setInterpolation<T>(value: Animated<T>, time: number, interpolation: Interpolation): Animated<T>;
+/**
+ * The timing curve from the keyframe at `time` to the next, as its two Bezier handles: `x` in
+ * `0..=1` of the way in time, `y` any fraction of the way in value (beyond `0..=1` overshoots).
+ */
+export declare function setHandles<T>(value: Animated<T>, time: number, handles: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}): Animated<T>;
+/** The keyframe at `time` given `next` as its value. */
+export declare function setKeyframeValue<T>(value: Animated<T>, time: number, next: T): Animated<T>;
+/**
+ * The handles a timing curve has in a curve editor: a Bezier's own, and for a linear segment the
+ * straight line's (a third and two thirds of the way). A held segment has none.
+ */
+export declare function handlesOf(interpolation: Interpolation): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+} | null;
+/**
+ * A CSS `cubic-bezier(x1, y1, x2, y2)` curve's output at linear `progress` (clamped to `0..=1`),
+ * bit for bit as the engine evaluates it (`CubicBezier::apply` in alpha2-model): the handles as the
+ * 32-bit floats a document holds, Newton from `t = progress` while it stays on the curve, then
+ * bisection, which converges where the curve is flat (both `x` handles near one end). A display
+ * that shows a keyframed value takes it from here, so it shows what the render draws.
+ */
+export declare function cubicBezierAt(curve: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}, progress: number): number;
+export {};

package/dist/core/keyframes.js

@@ -0,0 +1,153 @@
+/** Common easing curves, as CSS names them. */
+export const EASINGS = {
+    ease_in: { type: "cubic_bezier", x1: 0.42, y1: 0, x2: 1, y2: 1 },
+    ease_out: { type: "cubic_bezier", x1: 0, y1: 0, x2: 0.58, y2: 1 },
+    ease_in_out: { type: "cubic_bezier", x1: 0.42, y1: 0, x2: 0.58, y2: 1 },
+};
+function keyframesOf(value) {
+    if (value.mode !== "keyframes")
+        throw new Error("the value has no keyframes");
+    return [...value.keyframes];
+}
+function indexAt(keys, time) {
+    const index = keys.findIndex((key) => key.time === time);
+    if (index < 0)
+        throw new Error(`no keyframe at ${time}`);
+    return index;
+}
+/**
+ * The keyframe at `from` moved to `to`, kept strictly between its neighbours (a tick from each), so
+ * the order of keyframes never changes. Returns the value and where the keyframe landed.
+ *
+ * Throws when `value` is not keyframed or has no keyframe at `from`. The keyframe-editing
+ * functions below throw in the same cases.
+ */
+export function moveKeyframe(value, from, to) {
+    const keys = keyframesOf(value);
+    const index = indexAt(keys, from);
+    const low = index > 0 ? keys[index - 1].time + 1 : -Infinity;
+    const high = index + 1 < keys.length ? keys[index + 1].time - 1 : Infinity;
+    const time = Math.round(Math.min(high, Math.max(low, to)));
+    keys[index] = { ...keys[index], time };
+    return { value: { mode: "keyframes", keyframes: keys }, time };
+}
+/** The keyframe at `time` removed; the last one removed leaves its value, constant. */
+export function removeKeyframe(value, time) {
+    const keys = keyframesOf(value);
+    const [removed] = keys.splice(indexAt(keys, time), 1);
+    return keys.length
+        ? { mode: "keyframes", keyframes: keys }
+        : { mode: "constant", value: removed.value };
+}
+/** How the keyframe at `time` eases to the next. */
+export function setInterpolation(value, time, interpolation) {
+    const keys = keyframesOf(value);
+    const index = indexAt(keys, time);
+    keys[index] = { ...keys[index], interpolation };
+    return { mode: "keyframes", keyframes: keys };
+}
+/**
+ * The timing curve from the keyframe at `time` to the next, as its two Bezier handles: `x` in
+ * `0..=1` of the way in time, `y` any fraction of the way in value (beyond `0..=1` overshoots).
+ */
+export function setHandles(value, time, handles) {
+    const clampX = (x) => Math.min(1, Math.max(0, x));
+    return setInterpolation(value, time, {
+        type: "cubic_bezier",
+        x1: clampX(handles.x1),
+        y1: handles.y1,
+        x2: clampX(handles.x2),
+        y2: handles.y2,
+    });
+}
+/** The keyframe at `time` given `next` as its value. */
+export function setKeyframeValue(value, time, next) {
+    const keys = keyframesOf(value);
+    const index = indexAt(keys, time);
+    keys[index] = { ...keys[index], value: next };
+    return { mode: "keyframes", keyframes: keys };
+}
+/**
+ * The handles a timing curve has in a curve editor: a Bezier's own, and for a linear segment the
+ * straight line's (a third and two thirds of the way). A held segment has none.
+ */
+export function handlesOf(interpolation) {
+    if (interpolation.type === "cubic_bezier")
+        return {
+            x1: interpolation.x1,
+            y1: interpolation.y1,
+            x2: interpolation.x2,
+            y2: interpolation.y2,
+        };
+    if (interpolation.type === "linear")
+        return { x1: 1 / 3, y1: 1 / 3, x2: 2 / 3, y2: 2 / 3 };
+    return null;
+}
+/** Newton steps tried before bisection takes over. */
+const NEWTON_STEPS = 8;
+/** Bisection halvings; 2^-64 is far below the tolerance. */
+const BISECTION_STEPS = 64;
+/** Accepted distance between the curve's `x` and the requested progress. */
+const TOLERANCE = 1e-12;
+/** A slope this flat would send a Newton step far outside the curve. */
+const MIN_SLOPE = 1e-9;
+/**
+ * A CSS `cubic-bezier(x1, y1, x2, y2)` curve's output at linear `progress` (clamped to `0..=1`),
+ * bit for bit as the engine evaluates it (`CubicBezier::apply` in alpha2-model): the handles as the
+ * 32-bit floats a document holds, Newton from `t = progress` while it stays on the curve, then
+ * bisection, which converges where the curve is flat (both `x` handles near one end). A display
+ * that shows a keyframed value takes it from here, so it shows what the render draws.
+ */
+export function cubicBezierAt(curve, progress) {
+    const x = Math.min(1, Math.max(0, progress));
+    if (x <= 0)
+        return 0;
+    if (x >= 1)
+        return 1;
+    const x1 = Math.fround(curve.x1);
+    const x2 = Math.fround(curve.x2);
+    const parameter = newton(x, x1, x2) ?? bisection(x, x1, x2);
+    return component(parameter, Math.fround(curve.y1), Math.fround(curve.y2));
+}
+function newton(x, x1, x2) {
+    let parameter = x;
+    for (let step = 0; step < NEWTON_STEPS; step += 1) {
+        const error = component(parameter, x1, x2) - x;
+        if (Math.abs(error) < TOLERANCE)
+            return parameter >= 0 && parameter <= 1 ? parameter : undefined;
+        const slope = slopeAt(parameter, x1, x2);
+        if (Math.abs(slope) < MIN_SLOPE)
+            return undefined;
+        parameter -= error / slope;
+    }
+    return undefined;
+}
+function bisection(x, x1, x2) {
+    let low = 0;
+    let high = 1;
+    let parameter = x;
+    for (let step = 0; step < BISECTION_STEPS; step += 1) {
+        const value = component(parameter, x1, x2);
+        if (Math.abs(value - x) < TOLERANCE)
+            break;
+        if (value < x)
+            low = parameter;
+        else
+            high = parameter;
+        parameter = low + (high - low) * 0.5;
+    }
+    return parameter;
+}
+/** One coordinate of the curve at parameter `t`, in the engine's Horner form. */
+function component(t, p1, p2) {
+    const c = 3 * p1;
+    const b = 3 * (p2 - p1) - c;
+    const a = 1 - c - b;
+    return ((a * t + b) * t + c) * t;
+}
+function slopeAt(t, p1, p2) {
+    const c = 3 * p1;
+    const b = 3 * (p2 - p1) - c;
+    const a = 1 - c - b;
+    return (3 * a * t + 2 * b) * t + c;
+}

package/dist/core/presets.d.ts

@@ -0,0 +1,64 @@
+import type { Composition, EffectResource, MediaSource, Project } from "alpha2/project";
+import type { Command } from "./commands.js";
+import type { EditorDocument } from "./document.js";
+/**
+ * A reusable group: the composition a group node draws, the compositions it uses in turn, and what
+ * it needs from the project it is applied to. Saved outside any project, as JSON.
+ */
+export interface GraphPreset {
+    readonly format: "alpha2-graph-preset";
+    readonly version: 1;
+    readonly name: string;
+    /** The group's composition first, then those its group nodes and composition sources use. */
+    readonly compositions: readonly Composition[];
+    /** Media, effect resources, and effects its nodes read. */
+    readonly requires: {
+        readonly sources: readonly MediaSource[];
+        readonly resources: readonly EffectResource[];
+        readonly effects: readonly {
+            readonly id: string;
+            readonly version: number;
+        }[];
+    };
+}
+/** What a preset needs that a project lacks. */
+export interface PresetShortfall {
+    /** Sources its media nodes read that the project has not got, by id. */
+    readonly sources: readonly string[];
+    /** Effect resources (LUTs) its effects use that the project has not got, by id. */
+    readonly resources: readonly string[];
+    /** Effects the engine does not run, as `id@version`. */
+    readonly effects: readonly string[];
+}
+/**
+ * The preset of composition `id`, as a group node would draw it: it, every composition it uses, and
+ * the sources, resources, and effects they read.
+ */
+export declare function graphPreset(project: Project, id: string, name: string): GraphPreset;
+/**
+ * What `preset` needs that `document`'s project lacks: file-backed sources and effect resources by
+ * id (a composition source it brings along is not missing), and effects `runs` says the engine does
+ * not have.
+ */
+export declare function presetShortfall(document: EditorDocument, preset: GraphPreset, runs: (id: string, version: number) => boolean): PresetShortfall;
+/**
+ * The command that places `preset` in composition `compositionId` as one undoable edit: its
+ * compositions added under free ids, and an unconnected group node `groupId` drawing the first, at
+ * `position` in the node editor.
+ * Returns `null` when the preset has no composition or `compositionId` does not exist. The command
+ * may still be refused when executed.
+ */
+export declare function placeGraphPreset(document: EditorDocument, preset: GraphPreset, compositionId: string, groupId: string, position?: {
+    readonly x: number;
+    readonly y: number;
+}): Command | null;
+/**
+ * The command that applies `preset` to clip `clipId` as one undoable edit: its compositions added
+ * under free ids, and a group node drawing the first placed after the clip composition's output
+ * (reading it, when the group has an input) and made the output. A clip without a composition gets
+ * one. Returns `null` for a preset with more than one input, which has no single place to go, and
+ * for an unknown clip.
+ */
+export declare function applyGraphPreset(document: EditorDocument, preset: GraphPreset, clipId: string, ids: {
+    readonly groupId: string;
+}): Command | null;

package/dist/core/presets.js

@@ -0,0 +1,241 @@
+import { findComposition, freeCompositionId } from "./compositions.js";
+/**
+ * The preset of composition `id`, as a group node would draw it: it, every composition it uses, and
+ * the sources, resources, and effects they read.
+ */
+export function graphPreset(project, id, name) {
+    const compositions = [];
+    const sources = new Map();
+    const resources = new Map();
+    const effects = new Map();
+    const pending = [id];
+    while (pending.length) {
+        const current = findComposition(project, pending.shift());
+        if (!current || compositions.some((c) => c.id === current.id))
+            continue;
+        compositions.push(current);
+        for (const node of current.nodes ?? []) {
+            const op = node.op;
+            if (op.type === "group")
+                pending.push(op.composition);
+            if (op.type === "media") {
+                const source = project.sources.find((s) => s.id === op.source_id);
+                if (source?.composition)
+                    pending.push(source.composition);
+                else if (source)
+                    sources.set(source.id, source);
+            }
+            if (op.type === "effect" || op.type === "transition") {
+                effects.set(`${op.effect.id}@${op.effect.version}`, {
+                    id: op.effect.id,
+                    version: op.effect.version,
+                });
+                for (const resource of Object.values(op.effect.resources ?? {})) {
+                    const found = (project.effect_resources ?? []).find((r) => r.id === resource);
+                    if (found)
+                        resources.set(found.id, found);
+                }
+            }
+        }
+    }
+    // Composition sources the preset's compositions read travel with it.
+    for (const composition of compositions)
+        for (const node of composition.nodes ?? [])
+            if (node.op.type === "media") {
+                const source = project.sources.find((s) => s.id === node.op.source_id);
+                if (source?.composition)
+                    sources.set(source.id, source);
+            }
+    return {
+        format: "alpha2-graph-preset",
+        version: 1,
+        name,
+        compositions,
+        requires: {
+            sources: [...sources.values()],
+            resources: [...resources.values()],
+            effects: [...effects.values()],
+        },
+    };
+}
+/**
+ * What `preset` needs that `document`'s project lacks: file-backed sources and effect resources by
+ * id (a composition source it brings along is not missing), and effects `runs` says the engine does
+ * not have.
+ */
+export function presetShortfall(document, preset, runs) {
+    const project = document.project;
+    return {
+        sources: preset.requires.sources
+            .filter((source) => source.kind !== "composition" &&
+            !project.sources.some((s) => s.id === source.id))
+            .map((source) => source.id),
+        resources: preset.requires.resources
+            .filter((resource) => !(project.effect_resources ?? []).some((r) => r.id === resource.id))
+            .map((resource) => resource.id),
+        effects: preset.requires.effects
+            .filter((effect) => !runs(effect.id, effect.version))
+            .map((effect) => `${effect.id}@${effect.version}`),
+    };
+}
+/**
+ * Commands that add `preset`'s compositions (and the composition sources they read) to `document`
+ * under free ids, and the id its group composition got.
+ */
+function presetAdditions(document, preset) {
+    const project = document.project;
+    let taken = project;
+    const renamed = new Map();
+    for (const composition of preset.compositions) {
+        const id = freeCompositionId(taken, composition.id);
+        renamed.set(composition.id, id);
+        taken = {
+            ...taken,
+            compositions: [...(taken.compositions ?? []), { id, nodes: [] }],
+        };
+    }
+    // An id no existing source, bin asset or earlier-added source has: two of the preset's may share
+    // a base id (`card`, and `card~2` from an earlier rename).
+    const sourceIds = new Map();
+    const takenSources = new Set([
+        ...project.sources.map((s) => s.id),
+        ...Object.keys(document.assets),
+    ]);
+    for (const source of preset.requires.sources) {
+        if (source.kind !== "composition" || !source.composition)
+            continue;
+        let id = source.id;
+        for (let n = 2; takenSources.has(id); n += 1)
+            id = `${source.id}~${n}`;
+        takenSources.add(id);
+        sourceIds.set(source.id, id);
+    }
+    const rename = (node) => {
+        const op = node.op;
+        if (op.type === "group")
+            return {
+                ...node,
+                op: {
+                    ...op,
+                    composition: renamed.get(op.composition) ?? op.composition,
+                },
+            };
+        if (op.type === "media" && sourceIds.has(op.source_id))
+            return {
+                ...node,
+                op: { ...op, source_id: sourceIds.get(op.source_id) },
+            };
+        return node;
+    };
+    const commands = preset.compositions.map((composition) => ({
+        type: "composition.add",
+        composition: {
+            ...structuredClone(composition),
+            id: renamed.get(composition.id),
+            nodes: (composition.nodes ?? []).map(rename),
+        },
+    }));
+    for (const source of preset.requires.sources) {
+        const id = sourceIds.get(source.id);
+        if (!id)
+            continue;
+        commands.push({
+            type: "asset.put",
+            asset: { id, kind: "composition", name: preset.name, contentRevision: 0 },
+            source: {
+                ...source,
+                id,
+                composition: renamed.get(source.composition) ?? source.composition,
+            },
+        });
+    }
+    const root = renamed.get(preset.compositions[0].id);
+    commands.push({
+        type: "metadata.update",
+        patch: {
+            graphNames: {
+                ...document.metadata.graphNames,
+                [root]: preset.name,
+            },
+        },
+    });
+    return { commands, root, taken };
+}
+/**
+ * The command that places `preset` in composition `compositionId` as one undoable edit: its
+ * compositions added under free ids, and an unconnected group node `groupId` drawing the first, at
+ * `position` in the node editor.
+ * Returns `null` when the preset has no composition or `compositionId` does not exist. The command
+ * may still be refused when executed.
+ */
+export function placeGraphPreset(document, preset, compositionId, groupId, position) {
+    const root = preset.compositions[0];
+    if (!root || !findComposition(document.project, compositionId))
+        return null;
+    const added = presetAdditions(document, preset);
+    return {
+        type: "transaction",
+        commands: [
+            ...added.commands,
+            {
+                type: "graph.node.add",
+                compositionId,
+                node: {
+                    id: groupId,
+                    op: {
+                        type: "group",
+                        composition: added.root,
+                        inputs: (root.inputs ?? []).map(() => null),
+                    },
+                },
+                ...(position ? { position } : {}),
+            },
+        ],
+    };
+}
+/**
+ * The command that applies `preset` to clip `clipId` as one undoable edit: its compositions added
+ * under free ids, and a group node drawing the first placed after the clip composition's output
+ * (reading it, when the group has an input) and made the output. A clip without a composition gets
+ * one. Returns `null` for a preset with more than one input, which has no single place to go, and
+ * for an unknown clip.
+ */
+export function applyGraphPreset(document, preset, clipId, ids) {
+    const root = preset.compositions[0];
+    if (!root || (root.inputs ?? []).length > 1)
+        return null;
+    const project = document.project;
+    const clip = project.timeline.tracks
+        .flatMap((track) => track.clips ?? [])
+        .find((c) => c.id === clipId);
+    if (!clip)
+        return null;
+    const added = presetAdditions(document, preset);
+    const commands = [...added.commands];
+    const target = clip.composition?.id ?? freeCompositionId(added.taken, `${clipId}-fx`);
+    if (!clip.composition)
+        commands.push({ type: "graph.create", clipId, compositionId: target });
+    const existing = clip.composition
+        ? findComposition(project, clip.composition.id)
+        : undefined;
+    // A new composition's output is its clip node.
+    const output = existing ? (existing.output ?? null) : "clip";
+    commands.push({
+        type: "graph.node.add",
+        compositionId: target,
+        node: {
+            id: ids.groupId,
+            op: {
+                type: "group",
+                composition: added.root,
+                inputs: (root.inputs ?? []).length === 1 ? [output] : [],
+            },
+        },
+    });
+    commands.push({
+        type: "graph.output",
+        compositionId: target,
+        nodeId: ids.groupId,
+    });
+    return { type: "transaction", commands };
+}

package/dist/core/session.d.ts

@@ -0,0 +1,150 @@
+import type { EditorDocument, Result } from "./document.js";
+import type { Command } from "./commands.js";
+/** An immutable view of an {@link EditorSession}; a new object after every change. */
+export interface EditorSnapshot {
+    /** The committed document. */
+    readonly document: EditorDocument;
+    /**
+     * Views and preview use the active gesture's valid candidate, or `document`. History, export and
+     * `canExecute` use only the committed `document`.
+     */
+    readonly draft: EditorDocument;
+    /** Selected clip ids; ids of clips the document no longer has are dropped. */
+    readonly selection: readonly string[];
+    /** Increases with every change of the committed document (commit, undo, redo, open). */
+    readonly revision: number;
+    /** Increases when the document is replaced wholesale ({@link EditorSession.open}) or disposed. */
+    readonly generation: number;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+}
+/**
+ * Holds an editor document with undo history, selection, clipboard and pointer gestures. Every
+ * document it holds is frozen; edits produce new documents through {@link Command}s.
+ *
+ * Methods other than `cancelGesture` and `dispose` throw an `EditorError` (`disposed`) after
+ * {@link EditorSession.dispose}.
+ */
+export declare class EditorSession {
+    #private;
+    readonly historyLimit: number;
+    readonly historyByteLimit: number;
+    /**
+     * @param document The initial document, copied; an empty document by default. Throws an
+     *   `EditorError` when it does not validate.
+     * @param historyLimit The most undo steps kept. Defaults to 120.
+     * @param historyByteLimit The most bytes the undo history keeps beyond the document: each step
+     *   counts the serialized size of what it does not share with the document after it, by
+     *   object identity, and the oldest steps are dropped first. Defaults to 64 MiB.
+     * @throws RangeError when a limit is not a non-negative safe integer.
+     */
+    constructor(document?: EditorDocument, historyLimit?: number, historyByteLimit?: number);
+    get document(): EditorDocument;
+    get draft(): EditorDocument;
+    get revision(): number;
+    get generation(): number;
+    get disposed(): boolean;
+    /**
+     * Every document the session can still show or return to: the undo history, the document, the
+     * active gesture's draft and the redo history. A host keeps what these refer to and may release
+     * the rest.
+     */
+    reachableDocuments(): readonly EditorDocument[];
+    /**
+     * The current snapshot; the same object until the next change, as `useSyncExternalStore` needs.
+     */
+    getSnapshot: () => EditorSnapshot;
+    /** Calls `listener` after every change. Returns the unsubscribe function. */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Calls `listener` with `selector`'s result whenever it changes by `equal` (`Object.is` by
+     * default). Returns the unsubscribe function.
+     */
+    subscribeSelector<T>(selector: (snapshot: EditorSnapshot) => T, listener: (value: T) => void, equal?: (a: T, b: T) => boolean): () => void;
+    /**
+     * The document `command` would produce from the committed one, or why it is refused. Changes
+     * nothing.
+     */
+    canExecute(command: Command): Result<EditorDocument>;
+    /**
+     * Runs `command` on the committed document and commits the result as one undo step, cancelling an
+     * active gesture first. A refusal is returned, not thrown, and leaves the session unchanged; so
+     * does a command that changes nothing (its result is the committed document itself), which keeps
+     * the redo history.
+     */
+    dispatch(command: Command): Result<EditorDocument>;
+    /**
+     * Replaces the document, clearing history, selection and clipboard and increasing `generation`.
+     * Throws an `EditorError` when `document` does not validate, leaving the session unchanged.
+     */
+    open(document: EditorDocument): void;
+    /** Steps back one committed change. Returns `false` when there is none. */
+    undo(): boolean;
+    /** Reapplies the last undone change. Returns `false` when there is none. */
+    redo(): boolean;
+    /**
+     * Forgets the undo and redo history and keeps everything else: the document (so `revision` and
+     * `generation` stay), the selection, the clipboard and an active gesture. For a host that made
+     * changes the user should not step back through, such as relinking media it restored, without
+     * {@link open}'s new generation, which tells views and the bridge the document was replaced.
+     */
+    clearHistory(): void;
+    /**
+     * Selects the clips `ids` names; unknown ids and duplicates are dropped. The selection it would
+     * set already holds (the same ids in the same order), it changes nothing and tells no one: a
+     * marquee calls it on every pointer move.
+     */
+    select(ids: readonly string[]): void;
+    /** The committed document's tracks and clips by id. */
+    query(): import("./document.js").EntityIndex;
+    /**
+     * Copies the clips `ids` names (the selection by default) to the session's clipboard, with their
+     * names and the compositions they draw. Unknown ids are skipped.
+     */
+    copy(ids?: readonly string[]): void;
+    /**
+     * Inserts the clipboard's clips on their original tracks, under their names, as one undo step,
+     * the earliest starting at tick `at` and the others keeping their offsets from it. New clip ids
+     * come from `idFactory`. With nothing copied it changes nothing and returns the document.
+     */
+    paste(at: number, idFactory?: () => string): Result<EditorDocument>;
+    /**
+     * Cancels the active gesture, if any, discarding its draft: nothing it previewed is committed.
+     * Returns whether a gesture was active. A host calls it before it tears down the view a gesture
+     * belongs to.
+     */
+    cancelGesture(): boolean;
+    /**
+     * Starts a pointer gesture, cancelling an active one. Each `update` runs a command on the
+     * document the gesture started from and, when valid, shows the result as the snapshot's `draft`
+     * without touching history. `commit` validates the last candidate fully and commits it as one
+     * undo step, returning whether anything was committed; `cancel` discards it. A gesture ends on
+     * commit, cancel, a dispatch, undo, redo, open or dispose, or the next `beginGesture`; `update`
+     * then returns a `stale_gesture` error.
+     */
+    beginGesture(): {
+        readonly candidate: EditorDocument;
+        update: (command: Command) => Result<EditorDocument>;
+        cancel: () => void;
+        commit: () => boolean;
+    };
+    /**
+     * Disposes `resource` when the session is disposed. Returns a function that releases it from the
+     * session without disposing it.
+     */
+    own(resource: {
+        dispose(): void | Promise<void>;
+    }): () => void;
+    /**
+     * Ends the session: cancels a gesture, drops listeners, history and clipboard, and disposes every
+     * owned resource. Idempotent; every call returns the same promise, which rejects with an
+     * `AggregateError` when any resource's disposal failed.
+     */
+    dispose(): Promise<void>;
+}
+/** Creates an {@link EditorSession}; see its constructor for the options and their defaults. */
+export declare function createEditor(options?: {
+    document?: EditorDocument;
+    historyLimit?: number;
+    historyByteLimit?: number;
+}): EditorSession;