@pixerate/editor 0.25.0 → 0.26.1

package/dist/canvas/index.d.ts

@@ -1,9 +1,7 @@
-import { R as Rect, C as CanvasNode, X as XYPosition, b as CanvasEdge, I as IncrementalLayoutOptions, S as Side, c as CanvasLayoutOptions, P as PlaceBesideOptions, T as TrajectoryFunction, F as FanOutTrajectoryOptions, N as NodeTransition, a as CanvasNodeStyle, d as ReflowDisplacementOptions, D as DirectionalDisplacementOptions, e as CanvasClipboardPayload, f as Position, g as Point } from '../types-DX4Mh4SL.js';
-export { h as CanvasDockingCallbacks, i as CollapseNodeOptions, j as DisplacementDirection, k as DockStrategy, E as ExplodeNodeOptions, l as ExplosionSnapshot, G as GraphDifferences, m as TrajectoryPoint } from '../types-DX4Mh4SL.js';
-import { b as CanvasNodeUpdate, N as NodeRectOptions, A as AlignEdge, c as AlignNodesOptions, D as DistributeAxis, a as DistributeMode, d as DistributeNodesOptions, S as SizeDimension, M as MatchSizeOptions, Z as ZOrderOperation, C as CanvasArrangeAction } from '../arrangeShortcuts-sLlD2rSX.js';
-export { e as ArrangeShortcutBinding, f as DEFAULT_ARRANGE_SHORTCUTS, L as LOCKED_DATA_KEY, g as LOCKED_PREVIOUS_FLAGS_KEY, h as alignNodes, i as applyNodeUpdates, j as createNodeLookup, k as distributeNodes, l as getAbsolutePosition, m as getNodeRect, n as getNodeSize, o as invertNodeUpdates, p as isLocked, q as lockNodes, r as matchArrangeShortcut, s as matchSize, t as readStyleSize, u as reorderNodes, v as toggleLockNodes, w as unlockNodes, x as withStyleSize } from '../arrangeShortcuts-sLlD2rSX.js';
-import { C as Command } from '../types-GT5a5YAX.js';
-import { r as TokenType, o as TokenScope, f as TokenLiteral, c as TokenVariable, e as TokenResolution, d as TokenModeContext, T as TokenState } from '../model-C1zApQM8.js';
+import { R as Rect, b as CanvasNode, X as XYPosition, c as CanvasEdge, I as IncrementalLayoutOptions, S as Side, d as CanvasLayoutOptions, P as PlaceBesideOptions, T as TrajectoryFunction, F as FanOutTrajectoryOptions, N as NodeTransition, e as CanvasNodeStyle, f as ReflowDisplacementOptions, g as DirectionalDisplacementOptions, h as CanvasClipboardPayload, i as CanvasNodeUpdate, j as NodeRectOptions, k as Position, l as Point, A as AlignEdge, m as AlignNodesOptions, D as DistributeAxis, a as DistributeMode, n as DistributeNodesOptions, o as SizeDimension, M as MatchSizeOptions, Z as ZOrderOperation, C as CanvasArrangeAction } from '../arrange-BICutYPk.js';
+export { p as ArrangeShortcutBinding, q as CanvasDockingCallbacks, r as CollapseNodeOptions, s as DEFAULT_ARRANGE_SHORTCUTS, t as DisplacementDirection, u as DockStrategy, E as ExplodeNodeOptions, v as ExplosionSnapshot, G as GraphDifferences, L as LOCKED_DATA_KEY, w as LOCKED_PREVIOUS_FLAGS_KEY, x as TrajectoryPoint, y as alignNodes, z as applyNodeUpdates, B as createNodeLookup, H as distributeNodes, J as getAbsolutePosition, K as getNodeRect, O as getNodeSize, Q as invertNodeUpdates, U as isLocked, V as lockNodes, W as matchArrangeShortcut, Y as matchSize, _ as readStyleSize, $ as reorderNodes, a0 as toggleLockNodes, a1 as unlockNodes, a2 as withStyleSize } from '../arrange-BICutYPk.js';
+import { C as Command, M as MergedExecutionOptions } from '../types-GT5a5YAX.js';
+import { r as TokenType, o as TokenScope, f as TokenLiteral, d as TokenModeContext, c as TokenVariable, e as TokenResolution, T as TokenState } from '../model-C1zApQM8.js';
 
 declare const DEFAULT_NODE_WIDTH = 200;
 declare const DEFAULT_NODE_HEIGHT = 60;
@@ -2230,6 +2228,8 @@ interface CanvasTokenProperty {
     /** Returns the node with the value written, or the same node when nothing changes. */
     write(node: CanvasNode, value: TokenLiteral): CanvasNode;
 }
+/** The top-level `name: value` declarations of a style string (names as written, in order). */
+declare function parseNodeStyleDeclarations(style: string): [string, string][];
 /** A style property (camelCase name) from a style string or object. */
 declare function readNodeStyleProperty(style: CanvasNodeStyle | undefined | null, prop: string): string | number | undefined;
 /**
@@ -2300,4 +2300,1229 @@ declare function detachTokenBindings<TNode extends CanvasNode>(nodes: readonly T
  */
 declare function pruneCanvasTokenModes<TNode extends CanvasNode>(nodes: readonly TNode[], state: TokenState): TNode[];
 
-export { AUTO_LAYOUT_DATA_KEY, type AffineMatrix, AlignEdge, AlignNodesOptions, type ArrangeHistoryTarget, type AutoLayout, type AutoLayoutAlignContent, type AutoLayoutAlignCross, type AutoLayoutAlignMain, type AutoLayoutCellAlign, type AutoLayoutChild, type AutoLayoutConstraints, type AutoLayoutGrid, type AutoLayoutGridArea, type AutoLayoutGridCell, type AutoLayoutGridGeometry, type AutoLayoutGridTrack, type AutoLayoutHorizontalConstraint, type AutoLayoutInsertTarget, type AutoLayoutMeasure, type AutoLayoutMode, type AutoLayoutOptions, type AutoLayoutPadding, type AutoLayoutSize, type AutoLayoutSizing, type AutoLayoutSizingPair, type AutoLayoutVerticalConstraint, type BezierCommand, type BezierContour, type BezierPath, type BezierPathInput, type BezierPathToSvgOptions, type BezierSegment, CANVAS_TOKEN_PROPERTIES, CHILD_LAYOUT_DATA_KEY, CONNECTION_LINE_TYPES, CanvasArrangeAction, type CanvasArrangeController, type CanvasArrangeControllerOptions, type CanvasAutoLayoutController, type CanvasAutoLayoutControllerOptions, CanvasClipboardPayload, type CanvasConnectionLineType, CanvasEdge, type CanvasHeightOptions, CanvasLayoutOptions, CanvasNode, CanvasNodeStyle, CanvasNodeUpdate, type CanvasScene, type CanvasScenesOptions, type CanvasScenesState, CanvasScenesStore, type CanvasTokenBindingInfo, type CanvasTokenOptions, type CanvasTokenProperty, type CanvasViewport, type Clock, type CombineShapeNodesOptions, type CombineShapeNodesRefusal, type CombineShapeNodesResult, type ConnectorSnap, type ConnectorSnapOptions, type ConnectorSnapTarget, type CubicSegment, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, type DashedPath, DirectionalDisplacementOptions, DistributeAxis, DistributeMode, DistributeNodesOptions, type DividePathsResult, type EllipseShape, FanOutTrajectoryOptions, type FitCubicsOptions, type FitPathDataOptions, type FitViewportOptions, type FlattenOptions, type GuideIndex, type GuideLine, IncrementalLayoutOptions, ManualClock, MatchSizeOptions, type MeasureGuide, type MeasureSelectionOptions, type MeasureSelectionResult, type MultiNodeTransitionOptions, type MultiPolygon, NodeRectOptions, NodeTransition, type OffsetPathOptions, type OffsetShapeNodesOptions, type OutlineShapeStrokesOptions, type OutlineStrokeOptions, type PathBooleanOperation, type PathBooleanResult, type PathCommand, type PathOperand, type PathOperandInput, PathOpsError, type PathOpsOptions, type PathOpsReport, type PathPiece, type PathPointAtLength, type PathShape, PlaceBesideOptions, Point, type PolygonBooleanOperation, type PolygonBooleanOptions, type PolygonFillRule, type PolygonInput, type PolygonOperand, type PolygonPiece, type PolygonRing, type PolygonToPathOptions, type PolygonWithHoles, Position, type PositionChangeLike, RESIZE_HANDLES, Rect, type RectShape, ReflowDisplacementOptions, type RegularPolygonShape, type ResizeHandle, SHAPE_DATA_KEY, SHAPE_KINDS, SHAPE_NODE_TYPE, SHAPE_OPERATIONS, type SerializedCanvasScenes, type ShapeDescription, type ShapeKind, type ShapeNodePolygonOptions, type ShapeOperation, type ShapePaint, type ShapePathEditOperation, type ShapePathEditRefusal, type ShapePathEditResult, type ShapeRenderData, type ShapeSize, Side, SizeDimension, type SnapGuidesOptions, type SnapNodeDragOptions, type SnapNodeDragResult, type SnapNodeResizeOptions, type SnapNodeResizeResult, type SnapResizeOptions, type SnapResizeResult, type SnapResult, type StarShape, StreamingLayoutManager, type StreamingLayoutManagerOptions, type StrokeCap, type StrokeJoin, TOKEN_BINDINGS_DATA_KEY, TOKEN_MODES_DATA_KEY, TrajectoryFunction, XYPosition, ZOrderOperation, applyConstraints, applyShapeCombination, applyShapeReplacement, arcToCubics, bezierPathArea, bezierPathBounds, bezierPathLength, bezierPathPointAtLength, bezierPathSignedArea, bezierPathToSvg, bindCanvasToken, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canCombineShapeNodes, canOffsetShapeNodes, canOutlineShapeNodeStrokes, canvasHeight, centerNodes, centre, clampLayoutSize, closeContour, collectDescendantIds, combineShapeNodes, computeNodesBoundingBox, computeSnapGuides, connectedOnly, contourSignedArea, contoursToPath, countPathSegments, createBezierTrajectory, createCanvasArrangeController, createCanvasAutoLayoutController, createCanvasScenesStore, createFanOutTrajectory, createGuideIndex, createNodeGuideIndex, cubicPointAt, cubicsToPathData, dashContours, defaultEasing, detachTokenBindings, distanceToBezierPath, dividePaths, dividePolygons, ensureLayout, estimateCanvasHeight, estimateNodeSize, excludePaths, findConnectorSnap, fitCubicRun, fitCubics, fitFreehandPath, fitPathData, fitViewportToNodes, fitViewportToRect, flattenSvgPath, flowSide, formatNumber, getAutoLayout, getAutoLayoutGrid, getAutoLayoutInsertTarget, getBindableTokenProperties, getCanvasTokenProperty, getCenteredNodePosition, getChildLayout, getEffectiveTokenModes, getFlowChildren, getLayoutParent, getLayoutSizing, getLayoutedNodes, getNodeShape, getNodeTokenBindings, getNodeTokenModes, getResizingNodeRect, getShapeRenderData, getShapeSvg, getTokenPropertyScope, getTokensForProperty, handlePoint, hasVisibleStroke, inferResizeHandle, inspectNodeTokens, intersectPaths, intersectPolygons, isAutoLayoutFrame, isEventFromTextInput, isMeasureModifierHeld, isShapeDescription, isShapeNode, isStraightCubic, isValidCanvasEdge, isValidCanvasNode, isValidCanvasScene, isValidUrl, layoutAll, layoutBounds, layoutFrame, layoutUp, layoutUpMany, linearPositionTrajectory, linearTrajectory, makeSizingCoherent, measureBetween, measureLabel, measureSelection, measureToLine, mergeNodeUpdates, moveLayoutChild, multiPolygonArea, multiPolygonBounds, nearestHandlePositions, normalizeBezierPath, offsetPath, offsetShapeNodes, oppositePosition, outlineShapeNodeStrokes, outlineStroke, overlaps, pageHidden, parseCanvasClipboardData, parseCanvasScenes, parseSvgPath, pathBoolean, pathToContours, placeBeside, pointInBezierPath, pointInMultiPolygon, pointInRings, polygonArea, polygonBoolean, polygonToSvgPath, positionToSide, pruneCanvasTokenModes, readNodeStyleProperty, realClock, relayoutUpdates, remapPastedNodes, repositionNodesTo, resizeHandleAxes, resolveCanvasTokens, resolvePadding, revertShapeCombination, ringSignedArea, runMultiNodeTransition, segmentBounds, segmentCurvature, segmentDerivative, segmentExtrema, segmentLength, segmentNearest, segmentParamAtLength, segmentPoint, segmentTangent, serializeCanvasNodes, setCanvasTokenMode, shapeNodeToBezierPath, shapeNodeToPolygon, shapeToBezierPath, shapeToPolygon, sideToPosition, simplifyRing, snapNodeDrag, snapNodeResize, snapResize, snapToGrid, splitSegment, strokeOutlineRings, subSegment, subtractPaths, subtractPolygons, toBezierPath, transformBezierPath, trimSegments, unionPolygons, unitePaths, windingNumber, withStyleOpacity, writeNodeStyleProperty, xorPolygons };
+/**
+ * Keyframe easing: the curve a segment follows from one keyframe to the next.
+ *
+ * - `hold` keeps the first keyframe's value until the next one (a step).
+ * - `linear` and the CSS presets (`ease`, `ease-in`, `ease-out`, `ease-in-out`) are
+ *   CSS-compatible `cubic-bezier()` curves; `{ type: 'cubic-bezier', x1, y1, x2, y2 }` is any
+ *   such curve (x1 / y1 is the leaving keyframe's out handle, x2 / y2 the next one's in handle).
+ * - `spring` is a damped spring settling on the next value (it may overshoot).
+ */
+/** Named easing presets. */
+type AnimationEasingPreset = 'linear' | 'hold' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ease-in-back' | 'ease-out-back' | 'spring';
+interface CubicBezierEasing {
+    type: 'cubic-bezier';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+interface SpringEasing {
+    type: 'spring';
+    /** Spring stiffness (default 170). */
+    stiffness?: number;
+    /** Damping (default 26). */
+    damping?: number;
+    /** Mass (default 1). */
+    mass?: number;
+    /** Initial velocity in units of the segment's value change per second (default 0). */
+    velocity?: number;
+}
+type AnimationEasing = AnimationEasingPreset | CubicBezierEasing | SpringEasing;
+/** Preset names, in picker order. */
+declare const ANIMATION_EASING_PRESETS: readonly AnimationEasingPreset[];
+/** Picker labels for the presets. */
+declare const ANIMATION_EASING_LABELS: Readonly<Record<AnimationEasingPreset, string>>;
+/** The CSS control points of the bezier presets (CSS Easing Functions Level 1 values for the CSS keywords). */
+declare const CUBIC_BEZIER_PRESETS: Readonly<Record<string, readonly [number, number, number, number]>>;
+/**
+ * Solves a CSS `cubic-bezier(x1, y1, x2, y2)` for y at progress x (Newton steps with a
+ * bisection fallback). x1 / x2 are clamped to 0–1 as CSS requires.
+ */
+declare function cubicBezierAt(x1: number, y1: number, x2: number, y2: number, x: number): number;
+/**
+ * Normalised position of a damped spring released from 0 towards 1, `seconds` after release.
+ * Closed form for under-, critically and over-damped springs.
+ */
+declare function springAt(spring: Omit<SpringEasing, 'type'>, seconds: number): number;
+/** Resolves an easing to a cubic-bezier, spring or hold descriptor (unknown input → linear). */
+declare function resolveEasing(easing: AnimationEasing | string | undefined | null): CubicBezierEasing | Required<SpringEasing> | 'hold';
+/**
+ * Eased progress for linear progress `u` (0–1) through a segment lasting `durationMs`
+ * (springs depend on real time; other curves ignore it). `hold` returns 0 until `u` reaches 1.
+ */
+declare function evaluateEasing(easing: AnimationEasing | string | undefined | null, u: number, durationMs?: number): number;
+/**
+ * The easing filmcraft (and Premiere) derive from temporal "influence" handles: flat handles of
+ * the given influences (0.01–1, default 1/3) on the leaving and arriving keyframe.
+ */
+declare function easingFromInfluence(outInfluence?: number, inInfluence?: number): CubicBezierEasing;
+/**
+ * Parses a CSS easing (`linear`, `ease…`, `cubic-bezier(…)`, `steps(1, end)` / `step-end` →
+ * hold) or a preset name. Returns `null` for anything else.
+ */
+declare function parseCssEasing(text: string): AnimationEasing | null;
+/** Whether a value is a usable easing (preset name, CSS easing string or descriptor). */
+declare function isAnimationEasing(value: unknown): value is AnimationEasing;
+/**
+ * The CSS `animation-timing-function` for an easing: a keyword or `cubic-bezier()`,
+ * `steps(1, end)` for hold, and a sampled `linear(…)` for springs over `durationMs`.
+ */
+declare function easingToCss(easing: AnimationEasing | string | undefined | null, durationMs?: number, samples?: number): string;
+/** Short label for an easing (a preset's label, or `Custom` / `Spring`). */
+declare function easingLabel(easing: AnimationEasing | undefined | null): string;
+
+/**
+ * Colour interpolation in OKLab (Björn Ottosson's perceptual space, as CSS Color 4 uses for
+ * `color-mix(in oklab, …)`), with premultiplied alpha so a fade to `transparent` does not
+ * darken through black.
+ */
+interface OklabColor {
+    /** Lightness, 0–1. */
+    l: number;
+    a: number;
+    b: number;
+    /** Alpha, 0–1. */
+    alpha: number;
+}
+/** sRGB channels (0–1) to OKLab. */
+declare function rgbToOklab(r: number, g: number, b: number, alpha?: number): OklabColor;
+/** OKLab to sRGB channels (0–1, clamped into gamut). */
+declare function oklabToRgb(color: OklabColor): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/** Parses a CSS colour (hex, `rgb()` / `rgba()`, `transparent`, `black`, `white`) to OKLab, or `null`. */
+declare function parseOklab(input: unknown): OklabColor | null;
+/** Formats OKLab as `#rrggbb` (or `#rrggbbaa` when translucent). */
+declare function formatOklab(color: OklabColor): string;
+/**
+ * Mixes two colours at `t` (0 = `from`, 1 = `to`) in OKLab with premultiplied alpha.
+ * Returns `null` when either is not a readable colour.
+ */
+declare function mixColorsOklab(from: unknown, to: unknown, t: number): string | null;
+
+/**
+ * Keyframe animation for canvas nodes.
+ *
+ * A node's animation lives in `node.data.animation`, so it is copied, pasted, duplicated and
+ * serialised with the node (component instances copy it too). Each animatable property has a
+ * track of keyframes `{ time (ms), value, easing }`; the easing governs the segment *leaving*
+ * the keyframe (filmcraft / After Effects convention).
+ */
+/** Data key holding a node's animation. */
+declare const ANIMATION_DATA_KEY = "animation";
+/** Keyframe times closer than this (ms) are the same time. */
+declare const ANIMATION_TIME_EPSILON = 0.000001;
+/** A keyframe value: a number, or a CSS colour for colour properties. */
+type AnimationValue = number | string;
+interface AnimationKeyframe {
+    /** Time in milliseconds from the start of the timeline. */
+    time: number;
+    value: AnimationValue;
+    /** Easing of the segment from this keyframe to the next (default `linear`). */
+    easing?: AnimationEasing;
+}
+interface AnimationTrack {
+    keyframes: AnimationKeyframe[];
+    /** Disabled tracks keep their keyframes but do not animate (default `true`). */
+    enabled?: boolean;
+}
+/** A path a node's centre follows, driven by the `motionPath` track (progress 0–1). */
+interface AnimationMotionPath {
+    /** SVG path data in flow coordinates (the parent's when the node has a `parentId`). */
+    d: string;
+    /** Rotate the node along the path's tangent (default `false`). */
+    autoRotate?: boolean;
+}
+interface NodeAnimation {
+    /** Property key → track. */
+    tracks: Record<string, AnimationTrack>;
+    motionPath?: AnimationMotionPath;
+}
+type AnimationValueType = 'number' | 'color';
+/** A node property keyframes can drive. */
+interface AnimatableProperty {
+    key: string;
+    label: string;
+    type: AnimationValueType;
+    /** Values are clamped into `[min, max]` when written. */
+    min?: number;
+    max?: number;
+    /** Unit for display (`px`, `°`, …). */
+    unit?: string;
+    /** The node's current (static) value, or `undefined` when it has none. */
+    read(node: CanvasNode): AnimationValue | undefined;
+    /** Returns the node with `value` written (a new object; the input is never mutated). */
+    write(node: CanvasNode, value: AnimationValue): CanvasNode;
+}
+/**
+ * The built-in animatable properties, in the order they are applied (`motionPath` comes after
+ * `x` / `y` / `rotation` so it wins over them).
+ *
+ * Rotation and scale use the CSS individual transform properties (`style.rotate`,
+ * `style.scale`), which compose with the `transform` xyflow positions nodes with.
+ */
+declare const ANIMATABLE_PROPERTIES: readonly AnimatableProperty[];
+interface AnimationPropertyOptions {
+    /** Animatable properties (default {@link ANIMATABLE_PROPERTIES}); add your own to extend. */
+    properties?: readonly AnimatableProperty[];
+}
+declare function getAnimatableProperty(key: string, options?: AnimationPropertyOptions): AnimatableProperty | undefined;
+/** Clamps a value into a property's range (numbers) or returns it unchanged. */
+declare function clampAnimationValue(property: AnimatableProperty | undefined, value: AnimationValue): AnimationValue;
+/** Whether `value` is a well-formed keyframe. */
+declare function isAnimationKeyframe(value: unknown): value is AnimationKeyframe;
+/**
+ * Keyframes sorted by time, invalid entries dropped and duplicate times merged (the *later*
+ * entry in the array wins, so appending a keyframe replaces one at the same time). Cached per
+ * array (revalidated by element identity), so evaluating every frame does not re-sort; treat
+ * keyframe objects as immutable.
+ */
+declare function normalizeKeyframes(keyframes: readonly AnimationKeyframe[] | undefined | null): AnimationKeyframe[];
+/** The node's animation (tracks with at least one valid keyframe), or `null`. */
+declare function getNodeAnimation(node: CanvasNode | undefined | null): NodeAnimation | null;
+/** The track for `property` on a node, if it has keyframes. */
+declare function getAnimationTrack(node: CanvasNode | undefined | null, property: string): AnimationTrack | undefined;
+/** Whether the node has any (enabled or disabled) keyframes. */
+declare function isNodeAnimated(node: CanvasNode | undefined | null): boolean;
+/** Property keys of the node's tracks (in registry order, unknown keys last). */
+declare function getAnimatedProperties(node: CanvasNode | undefined | null, options?: AnimationPropertyOptions): string[];
+/**
+ * Returns the node with its animation replaced (`null` or no tracks removes the key). Empty
+ * tracks are dropped.
+ */
+declare function withNodeAnimation<TNode extends CanvasNode>(node: TNode, animation: NodeAnimation | null): TNode;
+
+/** How time past the end of the timeline maps back into it. */
+type AnimationLoopMode = 'none' | 'loop' | 'ping-pong';
+/** Nodes, or a document holding them. */
+type AnimationDocument = readonly CanvasNode[] | {
+    readonly nodes: readonly CanvasNode[];
+};
+/** Evaluated values: node id → property key → value. */
+type AnimationOverrides = Record<string, Record<string, AnimationValue>>;
+/**
+ * Interpolates between two keyframe values: numbers linearly, colours in OKLab (premultiplied
+ * alpha). Mismatched or unreadable values hold `from` until `t` reaches 1.
+ */
+declare function interpolateAnimationValue(from: AnimationValue, to: AnimationValue, t: number, type?: AnimationValueType): AnimationValue;
+/**
+ * A track's value at `time`. Before the first keyframe it holds the first value, after the
+ * last the last value. Keyframes may be unsorted or share times (see `normalizeKeyframes`).
+ * Returns `undefined` for a track without valid keyframes.
+ */
+declare function evaluateTrack(track: AnimationTrack | readonly AnimationKeyframe[] | undefined | null, time: number, type?: AnimationValueType): AnimationValue | undefined;
+/** The last keyframe time over the enabled tracks of the nodes (0 when nothing is animated). */
+declare function getAnimationDuration(doc: AnimationDocument): number;
+/**
+ * Maps a running time onto the timeline `[0, duration]`: clamped (`none`), wrapped (`loop`)
+ * or bounced (`ping-pong`).
+ */
+declare function wrapAnimationTime(time: number, duration: number, loop?: AnimationLoopMode): number;
+interface EvaluateAnimationOptions extends AnimationPropertyOptions {
+    /** Only evaluate these nodes. */
+    ids?: Iterable<string>;
+}
+/**
+ * Evaluates every enabled track at `time`: node id → property → value. The nodes are not
+ * touched; apply the result with `applyAnimationOverrides` (or use `applyAnimation`).
+ */
+declare function evaluateAnimation(doc: AnimationDocument, time: number, options?: EvaluateAnimationOptions): AnimationOverrides;
+/**
+ * Writes evaluated values into copies of the nodes (in the registry's order). Nodes without
+ * overrides keep their identity, and the input array is returned when nothing changes.
+ */
+declare function applyAnimationOverrides<TNode extends CanvasNode>(nodes: readonly TNode[], overrides: AnimationOverrides, options?: AnimationPropertyOptions): TNode[];
+/**
+ * The nodes as they look at `time`: `applyAnimationOverrides(nodes, evaluateAnimation(nodes, time))`.
+ * Run it after `resolveCanvasTokens` so animated values win over token values while playing.
+ */
+declare function applyAnimation<TNode extends CanvasNode>(nodes: readonly TNode[], time: number, options?: EvaluateAnimationOptions): TNode[];
+
+/** Identifies one keyframe: node, property and time. */
+interface KeyframeRef {
+    nodeId: string;
+    property: string;
+    time: number;
+}
+type AnimationEditErrorCode = 'unknown_node' | 'unknown_property' | 'unknown_keyframe' | 'duplicate_keyframe' | 'invalid_time' | 'invalid_value' | 'invalid_easing' | 'invalid_factor' | 'too_many_keyframes' | 'no_movement_range';
+/** Thrown by the editing functions for invalid requests; nothing is changed when it is thrown. */
+declare class AnimationEditError extends Error {
+    readonly code: AnimationEditErrorCode;
+    constructor(code: AnimationEditErrorCode, message: string);
+}
+/** Most keyframes one move / scale / delete may name (as filmcraft's `effects.moveKeyframes`). */
+declare const MAX_KEYFRAME_REFS = 4096;
+/** Snaps a time to the nearest frame at `fps`. */
+declare function snapTimeToFrame(time: number, fps: number): number;
+/** Static value of a property, for keying (sizes fall back to the measured size). */
+declare function readAnimatableValue(node: CanvasNode, property: AnimatableProperty): AnimationValue | undefined;
+/** The value a property shows at `time`: its track's value when animated, else its static value. */
+declare function getAnimatedValue(node: CanvasNode, propertyKey: string, time: number, options?: AnimationPropertyOptions): AnimationValue | undefined;
+interface SetKeyframeOptions extends AnimationPropertyOptions {
+    /** Easing of the segment leaving the keyframe (default: kept, or the previous keyframe's). */
+    easing?: AnimationEasing | string;
+}
+/** Adds a keyframe, or replaces the value (and easing, when given) of the one at `time`. */
+declare function setKeyframe<TNode extends CanvasNode>(nodes: readonly TNode[], nodeId: string, property: string, time: number, value: AnimationValue, options?: SetKeyframeOptions): TNode[];
+/**
+ * Keys the given properties of the nodes at `time` with the values they show there (the
+ * "add keyframe at playhead" action). Without `properties`, keys every animated property, or
+ * `x` and `y` for nodes that have none. Returns the new nodes and the keyed refs.
+ */
+declare function addKeyframesAtTime<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, time: number, options?: AnimationPropertyOptions & {
+    properties?: readonly AnimatableProperty[];
+    keys?: readonly string[];
+}): {
+    nodes: TNode[];
+    refs: KeyframeRef[];
+};
+interface KeyframePatch {
+    time?: number;
+    value?: AnimationValue;
+    easing?: AnimationEasing | string | null;
+}
+/** Changes one keyframe's time, value or easing (`easing: null` resets it to linear). */
+declare function updateKeyframe<TNode extends CanvasNode>(nodes: readonly TNode[], ref: KeyframeRef, patch: KeyframePatch, options?: AnimationPropertyOptions): TNode[];
+/** Sets the easing of the segments leaving the keyframes. */
+declare function setKeyframeEasing<TNode extends CanvasNode>(nodes: readonly TNode[], refs: readonly KeyframeRef[], easing: AnimationEasing | string | null, options?: AnimationPropertyOptions): TNode[];
+/**
+ * Deletes keyframes. When a track loses its last keyframe the node keeps that keyframe's
+ * value as its static value, so it does not jump (filmcraft `remove_keyframe_at`).
+ */
+declare function deleteKeyframes<TNode extends CanvasNode>(nodes: readonly TNode[], refs: readonly KeyframeRef[], options?: AnimationPropertyOptions): TNode[];
+/** Turns a track on or off (disabled tracks keep their keyframes but do not animate). */
+declare function setTrackEnabled<TNode extends CanvasNode>(nodes: readonly TNode[], nodeId: string, property: string, enabled: boolean): TNode[];
+/**
+ * Removes a track. With `keepValueAt`, the node keeps the value the track had at that time
+ * (filmcraft's stopwatch toggle).
+ */
+declare function removeTrack<TNode extends CanvasNode>(nodes: readonly TNode[], nodeId: string, property: string, options?: AnimationPropertyOptions & {
+    keepValueAt?: number;
+}): TNode[];
+/** Sets (or with `null` removes) the path the `motionPath` track moves the node along. */
+declare function setMotionPath<TNode extends CanvasNode>(nodes: readonly TNode[], nodeId: string, motionPath: {
+    d: string;
+    autoRotate?: boolean;
+} | null): TNode[];
+interface KeyframeRangeOptions {
+    /** Earliest allowed time (default 0). */
+    min?: number;
+    /** Latest allowed time (default unbounded). */
+    max?: number;
+}
+interface MoveKeyframesResult<TNode extends CanvasNode = CanvasNode> {
+    nodes: TNode[];
+    /** The delta applied (the request clamped so the whole group stays in range). */
+    delta: number;
+    /** The moved keyframes at their new times, in request order. */
+    refs: KeyframeRef[];
+}
+/**
+ * Moves keyframes (across nodes and properties) by one common `delta`, so their relative timing
+ * is kept. The delta is clamped so every key stays inside `[min, max]`; a clamped-to-zero move
+ * returns the input nodes. Moved keys replace unselected keys at their destination, but never
+ * each other: all originals are removed before any is re-inserted. Invalid or duplicate
+ * references throw without changing anything.
+ */
+declare function moveKeyframes<TNode extends CanvasNode>(nodes: readonly TNode[], refs: readonly KeyframeRef[], delta: number, options?: KeyframeRangeOptions): MoveKeyframesResult<TNode>;
+interface ScaleKeyframesOptions extends KeyframeRangeOptions {
+    /** Time that stays fixed (default: the earliest selected keyframe). */
+    pivot?: number;
+}
+/**
+ * Scales the spacing of keyframes in time around `pivot` (factor 2 = twice as slow). The factor
+ * is reduced so every key stays inside `[min, max]`. Returns the factor applied.
+ */
+declare function scaleKeyframes<TNode extends CanvasNode>(nodes: readonly TNode[], refs: readonly KeyframeRef[], factor: number, options?: ScaleKeyframesOptions): {
+    nodes: TNode[];
+    factor: number;
+    refs: KeyframeRef[];
+};
+/** Keyframe times on the nodes (all when `ids` is omitted), sorted and unique, minus `exclude`. */
+declare function getKeyframeTimes(nodes: readonly CanvasNode[], options?: {
+    ids?: Iterable<string>;
+    exclude?: readonly KeyframeRef[];
+}): number[];
+interface KeyframeSnap {
+    /** The delta after snapping. */
+    delta: number;
+    /** The time snapped to, or `null` when nothing was within the threshold. */
+    target: number | null;
+}
+/**
+ * Snaps a group move: the selected key (at `times + delta`) nearest to any target pulls the
+ * whole group onto it when within `threshold` ms (convert the timeline's screen threshold,
+ * e.g. 8px, with its scale). The group's spacing is kept.
+ */
+declare function snapKeyframeDelta(times: readonly number[], delta: number, targets: readonly number[], threshold: number): KeyframeSnap;
+/** Clipboard payload for keyframes; times are offsets from the earliest copied keyframe. */
+interface AnimationKeyframeClipboard {
+    type: 'pixerate/keyframes';
+    version: 1;
+    keyframes: {
+        nodeId: string;
+        property: string;
+        offset: number;
+        value: AnimationValue;
+        easing?: AnimationEasing;
+    }[];
+}
+/** Copies keyframes into a clipboard payload. */
+declare function copyKeyframes(nodes: readonly CanvasNode[], refs: readonly KeyframeRef[]): AnimationKeyframeClipboard;
+/** Reads a keyframe clipboard payload (object or JSON text), or `null`. */
+declare function parseKeyframeClipboard(input: unknown): AnimationKeyframeClipboard | null;
+/**
+ * Pastes keyframes with their first key at `time`, replacing keys at the same times. Targets:
+ * `nodeIds` (every target gets a single-node clip; several source nodes map onto the targets
+ * in order), or the original nodes when omitted. Keys for missing nodes or unknown properties
+ * are skipped. Returns the pasted refs.
+ */
+declare function pasteKeyframes<TNode extends CanvasNode>(nodes: readonly TNode[], clipboard: AnimationKeyframeClipboard, time: number, options?: AnimationPropertyOptions & {
+    nodeIds?: readonly string[];
+}): {
+    nodes: TNode[];
+    refs: KeyframeRef[];
+};
+interface RecordAnimationOptions extends AnimationPropertyOptions {
+    /**
+     * Record mode: changing a property that is not animated yet keys it too (otherwise only
+     * properties that already have keyframes are keyed and other changes are static edits).
+     */
+    recording?: boolean;
+}
+/**
+ * Turns edits made on the *displayed* (evaluated) nodes into edits of the stored nodes.
+ *
+ * - `base`: the stored nodes; `before`: what was displayed (`applyAnimation(base, time)`);
+ *   `after`: the displayed nodes after the edit (e.g. React Flow changes applied to `before`).
+ * - A changed property with an enabled track is keyed at `time` and keeps its stored value.
+ * - In record mode a changed property without a track gets one: a key at 0 with the previous
+ *   value (when `time` > 0) and a key at `time`, so it animates from where it was. The stored
+ *   value stays the previous one.
+ * - Everything else (other fields, unanimated properties outside record mode) passes through.
+ *
+ * Unchanged nodes keep their stored identity; returns the new stored nodes and the keyed refs.
+ */
+declare function recordAnimationChanges<TNode extends CanvasNode>(base: readonly TNode[], before: readonly TNode[], after: readonly TNode[], time: number, options?: RecordAnimationOptions): {
+    nodes: TNode[];
+    keyed: KeyframeRef[];
+};
+interface AnimateNodeOptions extends AnimationPropertyOptions {
+    /** Values at the end (property → value). */
+    to: Record<string, AnimationValue>;
+    /** Values at the start (default: what the node shows at `delay`). */
+    from?: Record<string, AnimationValue>;
+    /** Duration in ms (default 1000). */
+    duration?: number;
+    /** Start time in ms (default 0). */
+    delay?: number;
+    easing?: AnimationEasing | string;
+}
+/**
+ * Animates a node from `from` (or its current values) to `to` over `duration` ms starting at
+ * `delay`: two keyframes per property, replacing keys at those times.
+ */
+declare function animateNode<TNode extends CanvasNode>(nodes: readonly TNode[], nodeId: string, options: AnimateNodeOptions): {
+    nodes: TNode[];
+    refs: KeyframeRef[];
+};
+
+interface AnimationPlayerState {
+    /** Playhead time in ms, inside `[0, duration]`. */
+    time: number;
+    playing: boolean;
+    /** True between `scrub` and `endScrub`. */
+    scrubbing: boolean;
+    loop: AnimationLoopMode;
+    /** Speed multiplier (negative plays backwards). */
+    playbackRate: number;
+    duration: number;
+}
+interface AnimationPlayerOptions {
+    /** Time source (default `realClock`: requestAnimationFrame). Pass a `ManualClock` in tests or for rendering. */
+    clock?: Clock;
+    /** Timeline length in ms, or a getter (e.g. the last keyframe time). Default 1000. */
+    duration?: number | (() => number);
+    loop?: AnimationLoopMode;
+    playbackRate?: number;
+    /** Initial playhead time (default 0). */
+    time?: number;
+    /** Called whenever the playhead moves (playback, seek, scrub). */
+    onTime?: (time: number) => void;
+    /** Called when non-looping playback reaches the end (or the start, playing backwards). */
+    onEnd?: () => void;
+}
+/**
+ * Plays a timeline on an injectable `Clock`: play / pause / seek / scrub with looping,
+ * ping-pong and playback rate. It only asks the clock for frames while playing, so a
+ * `ManualClock` steps it deterministically and the real clock's requestAnimationFrame is the
+ * only place wall time enters.
+ *
+ * `getState()` returns a cached snapshot replaced on change (usable with `useSyncExternalStore`).
+ */
+declare class AnimationPlayer {
+    private readonly clock;
+    private durationSource;
+    private onTime?;
+    private onEnd?;
+    private time;
+    private playing;
+    private scrubbing;
+    private resumeAfterScrub;
+    private loop;
+    private rate;
+    /** Unwrapped time at `anchorAt` (keeps the ping-pong direction across frames). */
+    private anchorRaw;
+    private anchorAt;
+    private generation;
+    private cached;
+    private listeners;
+    constructor(options?: AnimationPlayerOptions);
+    /** Current timeline length (ms). */
+    get duration(): number;
+    get currentTime(): number;
+    get isPlaying(): boolean;
+    getState(): AnimationPlayerState;
+    subscribe(listener: (state: AnimationPlayerState) => void): () => void;
+    /** Replaces the callbacks (hooks keep them current without recreating the player). */
+    setCallbacks(callbacks: {
+        onTime?: (time: number) => void;
+        onEnd?: () => void;
+    }): void;
+    setDuration(duration: number | (() => number)): void;
+    setLoop(loop: AnimationLoopMode): void;
+    setPlaybackRate(rate: number): void;
+    /** Starts playing from the playhead (from the start again when a one-shot play had ended). */
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Pauses and returns to the start. */
+    stop(): void;
+    /** Moves the playhead (clamped to the timeline); playback continues from there. */
+    seek(time: number): void;
+    /** Seeks while dragging the playhead: playback pauses until `endScrub`. */
+    scrub(time: number): void;
+    /** Ends a scrub, resuming playback if it was playing when the scrub began. */
+    endScrub(): void;
+    /** Stops scheduling frames and drops listeners. */
+    destroy(): void;
+    private clamp;
+    private reanchor;
+    private rawNow;
+    private schedule;
+    /** Advances the playhead to the clock's time; `notify` emits the change. */
+    private tick;
+    private snapshot;
+    private emit;
+}
+declare function createAnimationPlayer(options?: AnimationPlayerOptions): AnimationPlayer;
+
+interface SampleAnimationOptions extends EvaluateAnimationOptions {
+    /** Frames per second (default 30). */
+    fps?: number;
+    /** Length in ms (default: the last keyframe time). */
+    duration?: number;
+    /** First time sampled (default 0). */
+    start?: number;
+    /** Refuses to produce more frames than this (default 100 000). */
+    maxFrames?: number;
+}
+interface AnimationFrame {
+    index: number;
+    /** Time in ms. */
+    time: number;
+    overrides: AnimationOverrides;
+}
+/**
+ * Samples the animation at a fixed frame rate from `start` through `start + duration`
+ * (both included), e.g. to render video frames. Apply a frame with `applyAnimationOverrides`.
+ */
+declare function sampleAnimationFrames(doc: AnimationDocument, options?: SampleAnimationOptions): AnimationFrame[];
+/** CSS property each animatable property maps to (camelCase for the Web Animations API). */
+declare const CSS_ANIMATION_PROPERTIES: Readonly<Record<string, {
+    css: string;
+    camel: string;
+}>>;
+interface AnimationStop {
+    /** 0–1 */
+    offset: number;
+    value: string;
+    /** Timing function of the segment starting here. */
+    easing?: string;
+}
+interface CssPropertyAnimation {
+    /** CSS property, e.g. `translate`. */
+    property: string;
+    /** camelCase name for `element.animate`. */
+    camel: string;
+    /** Animatable properties driving it, e.g. `['x', 'y']`. */
+    sources: string[];
+    stops: AnimationStop[];
+    /** False when the stops are sampled (colours mixed in OKLab, x / y with different timing, motion paths). */
+    exact: boolean;
+}
+interface CssExportOptions {
+    /** Timeline length in ms (default: the document's last keyframe time). */
+    duration?: number;
+    loop?: AnimationLoopMode;
+    playbackRate?: number;
+    /** Sampling rate for tracks CSS cannot express exactly (default 30 per second). */
+    sampleFps?: number;
+    /** Map properties to other CSS properties (e.g. `{ fill: { css: 'fill', camel: 'fill' } }` for SVG). */
+    cssProperties?: Record<string, {
+        css: string;
+        camel: string;
+    }>;
+}
+/**
+ * The node's enabled tracks as per-CSS-property keyframe stops: rotation / scale use the
+ * individual transform properties, x / y become `translate` relative to the node's position.
+ * Tracks CSS cannot reproduce exactly are sampled (`exact: false`).
+ */
+declare function getCssPropertyAnimations(nodes: readonly CanvasNode[], nodeId: string, options?: CssExportOptions): CssPropertyAnimation[];
+type PlaybackDirectionLike = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+interface CssAnimationExport {
+    /** `@keyframes` blocks plus a rule applying them to `selector`. */
+    css: string;
+    /** Value for the `animation` property (comma-separated, one per CSS property). */
+    animation: string;
+    animations: {
+        name: string;
+        property: string;
+        exact: boolean;
+    }[];
+    /** Whether every property is reproduced exactly. */
+    exact: boolean;
+}
+/**
+ * Exports a node's animation as CSS `@keyframes` (one per CSS property, so different tracks
+ * keep their own easing) and an `animation` declaration for `selector`.
+ */
+declare function exportCssAnimation(nodes: readonly CanvasNode[], nodeId: string, options?: CssExportOptions & {
+    name?: string;
+    selector?: string;
+}): CssAnimationExport;
+/** One `element.animate(keyframes, options)` call. */
+interface WebAnimationSpec {
+    property: string;
+    keyframes: {
+        offset: number;
+        easing?: string;
+        [property: string]: string | number | undefined;
+    }[];
+    options: {
+        duration: number;
+        iterations: number;
+        direction: PlaybackDirectionLike;
+        fill: 'both';
+        easing: 'linear';
+    };
+    exact: boolean;
+}
+/** The node's animation as Web Animations API keyframes (one animation per CSS property). */
+declare function toWebAnimations(nodes: readonly CanvasNode[], nodeId: string, options?: CssExportOptions): WebAnimationSpec[];
+/** Plays Web Animations specs on an element (anything with `animate`), returning the animations. */
+declare function playWebAnimations<TAnimation>(element: {
+    animate(keyframes: any, options: any): TAnimation;
+}, specs: readonly WebAnimationSpec[]): TAnimation[];
+/** Whether every enabled track of the node can be exported without sampling. */
+declare function isCssExportExact(nodes: readonly CanvasNode[], nodeId: string): boolean;
+
+/**
+ * View-model helpers for timeline UIs (React and Svelte render the same rows).
+ */
+interface TimelineKeyframe {
+    ref: KeyframeRef;
+    /** Time shown (includes the preview offset of a keyframe drag). */
+    time: number;
+    value: AnimationValue;
+    easing?: AnimationEasing;
+    selected: boolean;
+}
+interface TimelineRow {
+    /** `nodeId:property`. */
+    id: string;
+    nodeId: string;
+    nodeLabel: string;
+    property: string;
+    label: string;
+    enabled: boolean;
+    keyframes: TimelineKeyframe[];
+}
+interface TimelineRowsOptions extends AnimationPropertyOptions {
+    /** Selected keyframes. */
+    selection?: readonly KeyframeRef[];
+    /** Preview offset for the selected keyframes while they are dragged. */
+    dragDelta?: number;
+    /** Row label for a node (default: `data.label`, then the id). */
+    labelOf?: (node: CanvasNode) => string;
+}
+/** Whether `ref` is in `selection` (same node, property and time). */
+declare function isKeyframeSelected(selection: readonly KeyframeRef[], ref: KeyframeRef): boolean;
+/** One row per animated property of each node in `ids` (in `ids` order). */
+declare function getTimelineRows(nodes: readonly CanvasNode[], ids: Iterable<string>, options?: TimelineRowsOptions): TimelineRow[];
+/** x position (px) of `time` on a lane `width` px wide showing `[0, duration]`. */
+declare function timeToX(time: number, duration: number, width: number): number;
+/** Time at x (px) on a lane `width` px wide, clamped to `[0, duration]`. */
+declare function xToTime(x: number, duration: number, width: number): number;
+/** `1.25s` style label. */
+declare function formatAnimationTime(ms: number): string;
+/** Ruler ticks at a round step leaving at least `minSpacing` px between labels. */
+declare function getTimelineTicks(duration: number, width: number, minSpacing?: number): {
+    time: number;
+    x: number;
+    label: string;
+}[];
+
+/** History surface (`HistoryManager` satisfies it). */
+interface AnimationHistoryTarget {
+    execute(command: Command): void;
+    executeMerged?(command: Command, options?: MergedExecutionOptions): void;
+}
+interface KeyframeDragState {
+    refs: KeyframeRef[];
+    /** Offset previewed (after clamping and snapping). */
+    delta: number;
+    /** Time snapped to, for a snap guide. */
+    target: number | null;
+}
+interface CanvasAnimationState extends AnimationPlayerState {
+    /** Record mode: changing an unanimated property at the playhead keys it. */
+    recording: boolean;
+    /** Frame rate used for frame snapping and export (default 30). */
+    fps: number;
+    selection: readonly KeyframeRef[];
+    drag: KeyframeDragState | null;
+    /** Whether the duration follows the last keyframe (`setDuration(null)`). */
+    autoDuration: boolean;
+}
+interface CanvasAnimationControllerOptions<TNode extends CanvasNode = CanvasNode> {
+    getNodes: () => TNode[];
+    setNodes: (nodes: TNode[]) => void;
+    /** When set, keyframe edits are undoable steps (recording merges a drag into one step). */
+    history?: AnimationHistoryTarget;
+    /** Ids acted on without explicit ids (default: nodes with `selected: true`). */
+    getSelectedIds?: () => string[];
+    /** Time source for playback (default `realClock`). */
+    clock?: Clock;
+    /** Fixed timeline length in ms; omitted = the last keyframe time, at least `minDuration`. */
+    duration?: number;
+    /** Shortest automatic duration (default 1000 ms). */
+    minDuration?: number;
+    loop?: AnimationLoopMode;
+    playbackRate?: number;
+    fps?: number;
+    recording?: boolean;
+    properties?: readonly AnimatableProperty[];
+    /** Called when the playhead moves. */
+    onTime?: (time: number) => void;
+    onChange?: (state: CanvasAnimationState) => void;
+}
+/**
+ * Framework-agnostic animation controller shared by the React hook and the Svelte rune:
+ * playback (on an injected clock), record mode, keyframe editing with undo, multi-keyframe
+ * drag with snapping, copy / paste and export.
+ *
+ * Render `display()` (the nodes evaluated at the playhead) and route edits made on the
+ * displayed nodes through `applyDisplayChanges`, so animated properties are keyed instead of
+ * being overwritten by the next frame.
+ */
+declare function createCanvasAnimationController<TNode extends CanvasNode = CanvasNode>(options: CanvasAnimationControllerOptions<TNode>): {
+    player: AnimationPlayer;
+    getState: () => CanvasAnimationState;
+    subscribe(listener: (state: CanvasAnimationState) => void): () => void;
+    /** Re-reads node-derived state (the automatic duration) and notifies when it changed. */
+    refresh(): void;
+    readonly time: number;
+    readonly playing: boolean;
+    readonly duration: number;
+    play: () => void;
+    pause: () => void;
+    toggle: () => void;
+    stop: () => void;
+    seek: (time: number) => void;
+    scrub: (time: number) => void;
+    endScrub: () => void;
+    setLoop: (loop: AnimationLoopMode) => void;
+    setPlaybackRate: (rate: number) => void;
+    /** Fixed duration in ms, or `null` to follow the last keyframe. */
+    setDuration(ms: number | null): void;
+    setFps(value: number): void;
+    setRecording(on: boolean): void;
+    toggleRecording(): void;
+    /** Seeks to the next keyframe (of the selected nodes, or all) after the playhead. */
+    nextKeyframe(ids?: Iterable<string>): number | null;
+    previousKeyframe(ids?: Iterable<string>): number | null;
+    /** The nodes evaluated at the playhead (same array when nothing is animated). */
+    display: (nodes?: readonly TNode[]) => TNode[];
+    /**
+     * Applies edits made on the displayed nodes: animated properties (and, in record mode,
+     * any property) are keyed at the playhead; other changes go to the stored nodes.
+     * Keying is one undo step per node set, merged while a drag continues.
+     */
+    applyDisplayChanges(next: TNode[]): KeyframeRef[];
+    /** Keys the nodes (default: selected) at the playhead; see `addKeyframesAtTime`. */
+    addKeyframe(ids?: Iterable<string>, keys?: readonly string[], time?: number): KeyframeRef[];
+    setKeyframe(nodeId: string, property: string, value: AnimationValue, time?: number, easing?: AnimationEasing | string): void;
+    updateKeyframe(ref: KeyframeRef, patch: KeyframePatch): void;
+    deleteKeyframes(refs?: readonly KeyframeRef[]): boolean;
+    setEasing(easing: AnimationEasing | string | null, refs?: readonly KeyframeRef[]): boolean;
+    setTrackEnabled(nodeId: string, property: string, enabled: boolean): void;
+    removeTrack(nodeId: string, property: string): void;
+    setMotionPath(nodeId: string, motionPath: {
+        d: string;
+        autoRotate?: boolean;
+    } | null): void;
+    /** Animates a node to `to` (from its current values) over `duration`; see `animateNode`. */
+    animateNode(nodeId: string, opts: Omit<AnimateNodeOptions, "properties">): KeyframeRef[];
+    /** Moves keyframes (default: selected) by `delta` ms as one step; returns the delta applied. */
+    moveKeyframes(delta: number, refs?: readonly KeyframeRef[]): number;
+    /** Scales keyframe spacing (default: selected) around `pivot`; returns the factor applied. */
+    scaleKeyframes(factor: number, refs?: readonly KeyframeRef[], pivot?: number): number;
+    copyKeyframes(refs?: readonly KeyframeRef[]): AnimationKeyframeClipboard | null;
+    /** Pastes at the playhead onto the selected nodes (or the copied ones). */
+    pasteKeyframes(data?: AnimationKeyframeClipboard | null, nodeIds?: readonly string[], time?: number): KeyframeRef[];
+    readonly clipboard: AnimationKeyframeClipboard | null;
+    readonly selection: readonly KeyframeRef[];
+    selectKeyframes(refs: readonly KeyframeRef[], mode?: "replace" | "add" | "toggle"): void;
+    clearSelection(): void;
+    /** Starts dragging keyframes (default: the selection; refs not selected become the selection). */
+    beginKeyframeDrag(refs?: readonly KeyframeRef[]): void;
+    /**
+     * Previews the drag at `delta` ms. With `snap` (default on) the group snaps to other
+     * keyframes, the playhead, 0 and the end within `thresholdMs`, else to whole frames.
+     */
+    updateKeyframeDrag(delta: number, opts?: {
+        snap?: boolean;
+        thresholdMs?: number;
+    }): KeyframeDragState | null;
+    /** Commits the drag as one undo step. */
+    endKeyframeDrag(): number;
+    /** Cancels the drag preview (Escape); nothing is edited. */
+    cancelKeyframeDrag(): void;
+    /** Timeline rows for `ids` (default: selected nodes), including the drag preview. */
+    timelineRows(ids?: Iterable<string>, opts?: Omit<TimelineRowsOptions, "selection" | "dragDelta">): TimelineRow[];
+    sampleFrames(opts?: SampleAnimationOptions): AnimationFrame[];
+    exportCss(nodeId: string, opts?: CssExportOptions & {
+        name?: string;
+        selector?: string;
+    }): CssAnimationExport;
+    toWebAnimations(nodeId: string, opts?: CssExportOptions): WebAnimationSpec[];
+    destroy(): void;
+};
+type CanvasAnimationController<TNode extends CanvasNode = CanvasNode> = ReturnType<typeof createCanvasAnimationController<TNode>>;
+
+/**
+ * Figma-style components and instances on the canvas.
+ *
+ * - A **main component** is a node with `data.component` (a frame whose children, via
+ *   `parentId`, are its layers). A **component set** (`data.componentSet`) holds variants:
+ *   components with `data.component.variant` (`{ Size: 'Small', Style: 'Primary' }`).
+ * - An **instance** is a node with `data.instance = { componentId, properties }`. Its layers are
+ *   real nodes copied from the main; every copy records the main layer it mirrors in
+ *   `data.componentSource` and the property groups changed locally in
+ *   `data.componentOverrides` (`data.label`, `style.backgroundColor`, `shape.fill`,
+ *   `layout.gap`, `token.fill`, `hidden`, …).
+ * - When a main changes, its instances are rebuilt from it, keeping layer ids and re-applying
+ *   overrides (matched by source, then by layer name path, so switching variants keeps
+ *   compatible overrides). Component properties (boolean → visibility, text → a `data` field,
+ *   instance swap → a nested instance's main) are applied through `data.componentPropertyRefs`
+ *   on the main's layers.
+ * - Instances never gain or lose layers: deleting a layer inside an instance hides it, and
+ *   nodes added inside one move out next to it. Geometry of layers inside an instance follows
+ *   the main (and constraints / auto layout); only the instance itself resizes.
+ * - An instance whose main was deleted keeps its layers ("missing main") and can restore it.
+ *
+ * Everything lives in `data`, so components and instances survive JSON, copy / paste and
+ * duplication; `syncCanvasComponents(before, after)` relinks what a paste brought in.
+ */
+/** Data key of a main component's definition. */
+declare const COMPONENT_DATA_KEY = "component";
+/** Data key of a component set's definition (its variants are its child components). */
+declare const COMPONENT_SET_DATA_KEY = "componentSet";
+/** Data key of an instance's link to its main (`componentId`) and its property values. */
+declare const INSTANCE_DATA_KEY = "instance";
+/** Data key of the main-component layer an instance layer mirrors. */
+declare const COMPONENT_SOURCE_DATA_KEY = "componentSource";
+/** Data key of the override groups of an instance layer. */
+declare const COMPONENT_OVERRIDES_DATA_KEY = "componentOverrides";
+/** Data key of a main layer's component property bindings (field → property name). */
+declare const COMPONENT_PROPERTY_REFS_DATA_KEY = "componentPropertyRefs";
+type CanvasComponentPropertyType = 'boolean' | 'text' | 'instanceSwap';
+type CanvasComponentPropertyDef = {
+    type: 'boolean';
+    default: boolean;
+    description?: string;
+} | {
+    type: 'text';
+    default: string;
+    description?: string;
+} | {
+    type: 'instanceSwap';
+    default: string;
+    preferred?: string[];
+    description?: string;
+};
+type CanvasComponentPropertyValue = boolean | string;
+interface CanvasComponentData {
+    description?: string;
+    /** Component properties (on a lone component; variants share their set's). */
+    properties?: Record<string, CanvasComponentPropertyDef>;
+    /** Variant property values of a component inside a set. */
+    variant?: Record<string, string>;
+}
+interface CanvasComponentSetData {
+    description?: string;
+    /** Component properties shared by every variant. */
+    properties?: Record<string, CanvasComponentPropertyDef>;
+}
+interface CanvasInstanceData {
+    componentId: string;
+    properties?: Record<string, CanvasComponentPropertyValue>;
+}
+/**
+ * A field a component property drives on a main layer: `visible` (boolean), `component` (instance
+ * swap, on a nested instance) or a `data.<key>` field (text, e.g. `data.label`).
+ */
+type CanvasComponentPropertyField = 'visible' | 'component' | `data.${string}`;
+type CanvasComponentErrorCode = 'not-found' | 'invalid' | 'cycle' | 'inside-instance' | 'nested-instance' | 'missing-main' | 'no-overrides' | 'unknown-property' | 'type-mismatch';
+type CanvasComponentResult<TNode extends CanvasNode = CanvasNode> = {
+    ok: true;
+    nodes: TNode[];
+    ids: string[];
+} | {
+    ok: false;
+    nodes: TNode[];
+    code: CanvasComponentErrorCode;
+    reason: string;
+};
+interface CanvasComponentSyncOptions {
+    /** Ids for new layer copies (default `<instanceId>:<sourceId>`, made unique). */
+    idGenerator?: (instanceId: string, sourceId: string) => string;
+    /** Node types whose overrides all survive variant switches (default `['text']`). */
+    textTypes?: readonly string[];
+    /** Re-run auto layout inside rebuilt instances (default `true`). */
+    layout?: boolean | AutoLayoutOptions;
+    /**
+     * Resolves token bindings after a sync when `state` is given (bindings inside instances
+     * resolve in the instance's own modes). Bindings are always compared, never values.
+     */
+    tokens?: CanvasTokenOptions & {
+        state?: TokenState;
+    };
+}
+interface CreateCanvasComponentOptions extends CanvasComponentSyncOptions {
+    /** Id of the wrapping frame (when the selection is wrapped). */
+    id?: string;
+    /** Node type of the wrapping frame (default `group`). */
+    frameType?: string;
+    /** Node types that become a component themselves instead of being wrapped (default `['group', 'frame']`). */
+    frameTypes?: readonly string[];
+    /** Name (`data.label`) of a wrapping frame. */
+    name?: string;
+}
+interface CreateCanvasInstanceOptions extends CanvasComponentSyncOptions {
+    id?: string;
+    /** Frame to place the instance in (must not be inside its own main or an instance). */
+    parentId?: string;
+    /** Position in the parent's space (default: right of the main, or 0,0 in a parent). */
+    position?: XYPosition;
+    /** Property values (variant properties pick the variant). */
+    properties?: Record<string, CanvasComponentPropertyValue>;
+}
+type Value = CanvasComponentPropertyValue;
+/** Whether `node` is a main component. */
+declare function isCanvasComponent(node: CanvasNode | undefined | null): boolean;
+/** Whether `node` is a component set. */
+declare function isCanvasComponentSet(node: CanvasNode | undefined | null): boolean;
+/** Whether `node` is an instance (top-level or nested). */
+declare function isCanvasInstance(node: CanvasNode | undefined | null): boolean;
+/** The instance data of `node`, if it is an instance. */
+declare function getInstanceData(node: CanvasNode | undefined | null): CanvasInstanceData | undefined;
+/** The component definition of `node`, if it is a main component. */
+declare function getComponentData(node: CanvasNode | undefined | null): CanvasComponentData | undefined;
+/** The main-component layer an instance layer mirrors. */
+declare function getComponentSourceId(node: CanvasNode | undefined | null): string | undefined;
+/** The override groups of an instance layer. */
+declare function getNodeOverrides(node: CanvasNode | undefined | null): readonly string[];
+/** Component property bindings of a main layer (field → property name). */
+declare function getComponentPropertyRefs(node: CanvasNode | undefined | null): Readonly<Record<string, string>>;
+/** A layer's display name: `data.name`, then `data.label`, then `data.text`, then its type. */
+declare function getLayerName(node: CanvasNode | undefined | null): string;
+/** Reads one override group (`hidden`, `size`, `position`, `style.<prop>`, `data.<key>`, …) of a node. */
+declare function readOverrideGroup(node: CanvasNode, group: string): unknown;
+/** Returns `node` with one override group set to `value` (the same node when nothing changes). */
+declare function writeOverrideGroup<T extends CanvasNode>(node: T, group: string, value: unknown): T;
+/** Override groups whose values differ between two nodes. */
+declare function diffOverrideGroups(a: CanvasNode, b: CanvasNode): string[];
+/** The variant property values of a component: `data.component.variant`, else parsed from its name. */
+declare function getVariantValues(node: CanvasNode | undefined | null): Record<string, string>;
+/** Parses a variant name `Size=Large, State=Hover` into its pairs. */
+declare function parseVariantName(name: string): Record<string, string>;
+/** Formats variant pairs as a name, in `order` (other properties after, sorted). */
+declare function formatVariantName(pairs: Readonly<Record<string, string>>, order?: readonly string[]): string;
+/** Whether an instance of `componentId` placed in `parentId` would contain itself. */
+declare function wouldCreateComponentCycle(nodes: readonly CanvasNode[], componentId: string, parentId: string | undefined): boolean;
+/** The component a node belongs to (itself, or its nearest component ancestor). */
+declare function getOwningComponent(nodes: readonly CanvasNode[], id: string): string | undefined;
+/** The innermost instance containing `id` (`id` itself when it is an instance). */
+declare function getOwningInstance(nodes: readonly CanvasNode[], id: string): string | undefined;
+/** The outermost instance containing `id`. */
+declare function getRootInstance(nodes: readonly CanvasNode[], id: string): string | undefined;
+/** Whether `id` is a layer inside an instance (not a top-level instance itself). */
+declare function isInsideInstance(nodes: readonly CanvasNode[], id: string): boolean;
+/** Top-level and nested instances of `componentId`. */
+declare function getComponentInstances(nodes: readonly CanvasNode[], componentId: string): string[];
+/** `linked`, or `missing-main` when the instance's main component is gone. */
+declare function getInstanceStatus(nodes: readonly CanvasNode[], id: string): 'linked' | 'missing-main' | undefined;
+/** The variant set of a component (its parent set), if any. */
+declare function getVariantSet(nodes: readonly CanvasNode[], componentId: string): string | undefined;
+/** Variant properties of a set with their values, in first-seen order. */
+declare function getVariantOptions(nodes: readonly CanvasNode[], setId: string): {
+    name: string;
+    values: string[];
+}[];
+/** The variant of `setId` matching `wanted` (all values, or else the most). */
+declare function findVariant(nodes: readonly CanvasNode[], setId: string, wanted: Readonly<Record<string, string>>): string | undefined;
+/** A set's default variant: the one in its top-left corner. */
+declare function getDefaultVariant(nodes: readonly CanvasNode[], setId: string): string | undefined;
+/** Variant combinations shared by two or more variants of a set (conflicts to resolve). */
+declare function getVariantConflicts(nodes: readonly CanvasNode[], setId: string): string[][];
+/** Component property definitions of a component (its set's for variants). */
+declare function getComponentPropertyDefs(nodes: readonly CanvasNode[], componentId: string): Record<string, CanvasComponentPropertyDef>;
+/** An instance's property values, with defaults for those it doesn't set. */
+declare function getInstanceProperties(nodes: readonly CanvasNode[], id: string): Record<string, Value>;
+interface CanvasComponentInfo {
+    id: string;
+    name: string;
+    setId?: string;
+    variant?: Record<string, string>;
+    /** Instances linked to it (top-level and nested). */
+    instanceCount: number;
+}
+interface CanvasComponentSetInfo {
+    id: string;
+    name: string;
+    variants: CanvasComponentInfo[];
+    options: {
+        name: string;
+        values: string[];
+    }[];
+    defaultVariantId?: string;
+}
+/** Components (lone ones and variants) and component sets, in document order. */
+declare function listCanvasComponents(nodes: readonly CanvasNode[]): {
+    components: CanvasComponentInfo[];
+    sets: CanvasComponentSetInfo[];
+};
+interface CanvasInstancePropertyInfo {
+    name: string;
+    type: CanvasComponentPropertyType;
+    value: Value;
+    default: Value;
+    /** Instance swap: preferred components (all components when empty). */
+    preferred?: string[];
+}
+interface CanvasInstanceInfo {
+    /** The instance (the node itself, or the instance owning the inspected layer). */
+    id: string;
+    /** The outermost instance (where reset / push / detach act). */
+    rootId: string;
+    nested: boolean;
+    componentId: string;
+    componentName?: string;
+    status: 'linked' | 'missing-main';
+    setId?: string;
+    variant: Record<string, string>;
+    variantOptions: {
+        name: string;
+        values: string[];
+    }[];
+    properties: CanvasInstancePropertyInfo[];
+    /** Layers of the instance with overrides (the instance itself included). */
+    overrides: {
+        id: string;
+        name: string;
+        groups: string[];
+    }[];
+}
+/** Everything an instance inspector shows, for an instance or a layer inside one. */
+declare function inspectCanvasInstance(nodes: readonly CanvasNode[], id: string): CanvasInstanceInfo | undefined;
+/**
+ * Rebuilds one instance from its main (keeping ids, overrides and property values).
+ */
+declare function syncCanvasInstance<TNode extends CanvasNode>(nodes: readonly TNode[], instanceId: string, options?: CanvasComponentSyncOptions): TNode[];
+/**
+ * Rebuilds every instance from its main, inner components first (e.g. after loading a
+ * document whose instances were saved without their layers).
+ */
+declare function syncAllCanvasInstances<TNode extends CanvasNode>(nodes: readonly TNode[], options?: CanvasComponentSyncOptions): TNode[];
+/**
+ * Keeps components and instances consistent after an edit from `before` to `after`:
+ *
+ * 1. Layers deleted from inside an instance come back hidden; nodes added inside an instance
+ *    move out next to it; pasted / duplicated copies of instance layers stop mirroring the main,
+ *    and a copied nested instance becomes an instance of its own main.
+ * 2. Edits to instance layers are recorded as overrides (a value equal to the main's clears
+ *    the override; values from the same variable or from a component property are not
+ *    overrides; layer geometry inside an instance is not overridable, the instance's size is).
+ * 3. Instances of components whose layers changed are rebuilt (nested components first),
+ *    as are instances whose main, properties or overrides were switched or reset.
+ *
+ * Returns `after` unchanged when there is nothing to do, so it can run on every change.
+ */
+declare function syncCanvasComponents<TNode extends CanvasNode>(before: readonly TNode[], after: readonly TNode[], options?: CanvasComponentSyncOptions): TNode[];
+/**
+ * Create Component: a single frame-like node (one with children, a frame / group type or auto
+ * layout) becomes a component; anything else is wrapped in a new component frame. Refuses
+ * layers inside an instance and layers that don't share a parent.
+ */
+declare function createCanvasComponent<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, options?: CreateCanvasComponentOptions): CanvasComponentResult<TNode>;
+/**
+ * Combine as Variants: wraps sibling components in a component set. Each variant takes its
+ * `data.component.variant`, else the `Prop=Value` pairs of its name, else `Property 1=…`.
+ */
+declare function combineCanvasComponentsAsVariants<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, options?: CanvasComponentSyncOptions & {
+    id?: string;
+    name?: string;
+    frameType?: string;
+    padding?: number;
+}): CanvasComponentResult<TNode>;
+/**
+ * Create Instance of a component (or of a set's default variant). Refuses placing it inside
+ * its own main (directly or through nested instances) or inside another instance.
+ */
+declare function createCanvasInstance<TNode extends CanvasNode>(nodes: readonly TNode[], componentId: string, options?: CreateCanvasInstanceOptions): CanvasComponentResult<TNode>;
+/**
+ * Detach Instance: the instance becomes a plain frame with the same look; its layers stop
+ * mirroring the main, and instances nested in it become instances of their own mains. Nested
+ * instances can't be detached on their own.
+ */
+declare function detachCanvasInstance<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, options?: CanvasComponentSyncOptions): CanvasComponentResult<TNode>;
+/**
+ * Reset overrides: `group` resets one override group of layer `id`; without it, an instance
+ * resets every override in it (its own size stays) and its property values, a layer resets all of
+ * its own.
+ */
+declare function resetCanvasInstanceOverrides<TNode extends CanvasNode>(nodes: readonly TNode[], id: string, group?: string, options?: CanvasComponentSyncOptions): CanvasComponentResult<TNode>;
+/**
+ * Push overrides to main: copies every overridden value of the (outermost) instance to the
+ * main layers it mirrors (geometry, swaps and property values stay with the instance), clears
+ * those overrides and updates every other instance.
+ */
+declare function pushCanvasInstanceOverrides<TNode extends CanvasNode>(nodes: readonly TNode[], id: string, options?: CanvasComponentSyncOptions): CanvasComponentResult<TNode>;
+/** Swaps instances to another component (or a set's default variant), keeping same-named property values. */
+declare function swapCanvasInstance<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, componentId: string, options?: CanvasComponentSyncOptions & {
+    keepTextOverridesOnly?: boolean;
+}): CanvasComponentResult<TNode>;
+/**
+ * Sets instance property values: variant properties switch to the matching variant of the set
+ * (keeping compatible overrides), others must be defined on the component with the right type
+ * (boolean, text, or a component id for instance swap).
+ */
+declare function setCanvasInstanceProperties<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, properties: Readonly<Record<string, unknown>>, options?: CanvasComponentSyncOptions): CanvasComponentResult<TNode>;
+/**
+ * Adds, edits (`def`) or deletes (`null`) a component property on a component (variants share
+ * their set's). `newName` renames it, carrying layer bindings and instance values along.
+ */
+declare function setCanvasComponentProperty<TNode extends CanvasNode>(nodes: readonly TNode[], componentId: string, name: string, def: CanvasComponentPropertyDef | null, options?: CanvasComponentSyncOptions & {
+    newName?: string;
+}): CanvasComponentResult<TNode>;
+/**
+ * Binds a field of a main-component layer to a component property (`null` unbinds): `visible`
+ * takes a boolean property, `data.<key>` a text property, `component` (on a nested instance) an
+ * instance swap property.
+ */
+declare function bindCanvasComponentProperty<TNode extends CanvasNode>(nodes: readonly TNode[], layerId: string, field: CanvasComponentPropertyField, name: string | null, options?: CanvasComponentSyncOptions): CanvasComponentResult<TNode>;
+/**
+ * Restore Main Component of an instance whose main was deleted: the instance becomes the main
+ * again, with its old id, and its layers take the ids their copies mirror, so every other
+ * instance re-links. Its property values become the property defaults.
+ */
+declare function restoreCanvasMainComponent<TNode extends CanvasNode>(nodes: readonly TNode[], id: string, options?: CanvasComponentSyncOptions): CanvasComponentResult<TNode>;
+
+interface CanvasComponentsControllerOptions<TNode extends CanvasNode = CanvasNode> extends CanvasComponentSyncOptions {
+    getNodes: () => TNode[];
+    setNodes: (nodes: TNode[]) => void;
+    /** When set, every component action is one undoable step. */
+    history?: ArrangeHistoryTarget;
+    /** The selection (default: nodes with `selected`). */
+    getSelectedIds?: () => string[];
+    /** Called by `goToMainComponent` with the main (e.g. to pan the viewport to it). */
+    onReveal?: (node: TNode) => void;
+}
+/**
+ * Framework-agnostic components controller shared by the React hook and the Svelte rune. Its
+ * actions (create component / instance, combine as variants, detach, reset, push, swap, set
+ * properties, restore main) are one undoable step each with a `history`; `sync()` keeps
+ * instances following their mains after any other edit (call it after the nodes change).
+ * Each `can…` check returns `true` or the reason the action can't run.
+ */
+declare function createCanvasComponentsController<TNode extends CanvasNode = CanvasNode>(options: CanvasComponentsControllerOptions<TNode>): {
+    sync: () => TNode[];
+    /** Rebuilds every instance from its main (e.g. after loading), not recorded in history. */
+    syncAll(): TNode[];
+    /** Create Component from `ids` (default: the selection). */
+    createComponent(ids?: Iterable<string>, createOptions?: Omit<CreateCanvasComponentOptions, keyof CanvasComponentSyncOptions>): CanvasComponentResult<TNode>;
+    canCreateComponent: (ids?: Iterable<string>) => string | true;
+    /** Combine as Variants: wraps the selected components in a component set. */
+    combineAsVariants(ids?: Iterable<string>, combineOptions?: {
+        id?: string;
+        name?: string;
+        padding?: number;
+    }): CanvasComponentResult<TNode>;
+    canCombineAsVariants: (ids?: Iterable<string>) => string | true;
+    /** Create Instance of a component or component set. */
+    createInstance(componentId: string, createOptions?: Omit<CreateCanvasInstanceOptions, keyof CanvasComponentSyncOptions>): CanvasComponentResult<TNode>;
+    canCreateInstance(componentId?: string, parentId?: string): true | string;
+    /** Detach Instance (default: the selected instances). */
+    detachInstance(ids?: Iterable<string>): CanvasComponentResult<TNode>;
+    canDetachInstance(ids?: Iterable<string>): true | string;
+    /** Reset overrides of an instance or layer (default: the first selected); `group` resets one. */
+    resetOverrides(id?: string, group?: string): CanvasComponentResult<TNode>;
+    canResetOverrides(id?: string): true | string;
+    /** Push the (outermost) instance's overrides to its main component. */
+    pushOverrides(id?: string): CanvasComponentResult<TNode>;
+    canPushOverrides(id?: string): true | string;
+    /** Swap the selected instances to another component (or a set's default variant). */
+    swapInstance(componentId: string, ids?: Iterable<string>, swapOptions?: {
+        keepTextOverridesOnly?: boolean;
+    }): CanvasComponentResult<TNode>;
+    canSwapInstance(componentId?: string, ids?: Iterable<string>): true | string;
+    /** Set variant / component property values on the selected instances (one step). */
+    setInstanceProperties(properties: Record<string, unknown>, ids?: Iterable<string>): CanvasComponentResult<TNode>;
+    canSetInstanceProperties(ids?: Iterable<string>): true | string;
+    /** Restore Main Component from an instance whose main was deleted. */
+    restoreMainComponent(id?: string): CanvasComponentResult<TNode>;
+    canRestoreMainComponent(id?: string): true | string;
+    /** Adds, edits or (with `null`) deletes a component property. */
+    setComponentProperty(componentId: string, name: string, def: CanvasComponentPropertyDef | null, propertyOptions?: {
+        newName?: string;
+    }): CanvasComponentResult<TNode>;
+    /** Binds (or with `null` unbinds) a main layer's field to a component property. */
+    bindComponentProperty(layerId: string, field: CanvasComponentPropertyField, name: string | null): CanvasComponentResult<TNode>;
+    /** Selects the main component of an instance (or of the instance a layer is in). */
+    goToMainComponent(id?: string): string | undefined;
+    canGoToMainComponent(id?: string): true | string;
+    /** Components and component sets, for a components panel. */
+    list: () => {
+        components: CanvasComponentInfo[];
+        sets: CanvasComponentSetInfo[];
+    };
+    /** The instance inspector's view of an instance or a layer inside one (default: the selection). */
+    inspect: (id?: string) => CanvasInstanceInfo | undefined;
+    /** The outermost instance containing `id`. */
+    rootInstanceOf: (id: string) => string | undefined;
+};
+type CanvasComponentsController<TNode extends CanvasNode = CanvasNode> = ReturnType<typeof createCanvasComponentsController<TNode>>;
+/** Drag data type for dragging a component from a components panel onto a canvas. */
+declare const CANVAS_COMPONENT_DRAG_TYPE = "application/x-pixerate-component";
+/** Reads the component id a components panel put on a drag (or `undefined`). */
+declare function getCanvasComponentDragId(dataTransfer: Pick<DataTransfer, 'getData'> | null | undefined): string | undefined;
+
+export { ANIMATABLE_PROPERTIES, ANIMATION_DATA_KEY, ANIMATION_EASING_LABELS, ANIMATION_EASING_PRESETS, ANIMATION_TIME_EPSILON, AUTO_LAYOUT_DATA_KEY, type AffineMatrix, AlignEdge, AlignNodesOptions, type AnimatableProperty, type AnimateNodeOptions, type AnimationDocument, type AnimationEasing, type AnimationEasingPreset, AnimationEditError, type AnimationEditErrorCode, type AnimationFrame, type AnimationHistoryTarget, type AnimationKeyframe, type AnimationKeyframeClipboard, type AnimationLoopMode, type AnimationMotionPath, type AnimationOverrides, AnimationPlayer, type AnimationPlayerOptions, type AnimationPlayerState, type AnimationPropertyOptions, type AnimationStop, type AnimationTrack, type AnimationValue, type AnimationValueType, type ArrangeHistoryTarget, type AutoLayout, type AutoLayoutAlignContent, type AutoLayoutAlignCross, type AutoLayoutAlignMain, type AutoLayoutCellAlign, type AutoLayoutChild, type AutoLayoutConstraints, type AutoLayoutGrid, type AutoLayoutGridArea, type AutoLayoutGridCell, type AutoLayoutGridGeometry, type AutoLayoutGridTrack, type AutoLayoutHorizontalConstraint, type AutoLayoutInsertTarget, type AutoLayoutMeasure, type AutoLayoutMode, type AutoLayoutOptions, type AutoLayoutPadding, type AutoLayoutSize, type AutoLayoutSizing, type AutoLayoutSizingPair, type AutoLayoutVerticalConstraint, type BezierCommand, type BezierContour, type BezierPath, type BezierPathInput, type BezierPathToSvgOptions, type BezierSegment, CANVAS_COMPONENT_DRAG_TYPE, CANVAS_TOKEN_PROPERTIES, CHILD_LAYOUT_DATA_KEY, COMPONENT_DATA_KEY, COMPONENT_OVERRIDES_DATA_KEY, COMPONENT_PROPERTY_REFS_DATA_KEY, COMPONENT_SET_DATA_KEY, COMPONENT_SOURCE_DATA_KEY, CONNECTION_LINE_TYPES, CSS_ANIMATION_PROPERTIES, CUBIC_BEZIER_PRESETS, type CanvasAnimationController, type CanvasAnimationControllerOptions, type CanvasAnimationState, CanvasArrangeAction, type CanvasArrangeController, type CanvasArrangeControllerOptions, type CanvasAutoLayoutController, type CanvasAutoLayoutControllerOptions, CanvasClipboardPayload, type CanvasComponentData, type CanvasComponentErrorCode, type CanvasComponentInfo, type CanvasComponentPropertyDef, type CanvasComponentPropertyField, type CanvasComponentPropertyType, type CanvasComponentPropertyValue, type CanvasComponentResult, type CanvasComponentSetData, type CanvasComponentSetInfo, type CanvasComponentSyncOptions, type CanvasComponentsController, type CanvasComponentsControllerOptions, type CanvasConnectionLineType, CanvasEdge, type CanvasHeightOptions, type CanvasInstanceData, type CanvasInstanceInfo, type CanvasInstancePropertyInfo, CanvasLayoutOptions, CanvasNode, CanvasNodeStyle, CanvasNodeUpdate, type CanvasScene, type CanvasScenesOptions, type CanvasScenesState, CanvasScenesStore, type CanvasTokenBindingInfo, type CanvasTokenOptions, type CanvasTokenProperty, type CanvasViewport, type Clock, type CombineShapeNodesOptions, type CombineShapeNodesRefusal, type CombineShapeNodesResult, type ConnectorSnap, type ConnectorSnapOptions, type ConnectorSnapTarget, type CreateCanvasComponentOptions, type CreateCanvasInstanceOptions, type CssAnimationExport, type CssExportOptions, type CssPropertyAnimation, type CubicBezierEasing, type CubicSegment, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, type DashedPath, DirectionalDisplacementOptions, DistributeAxis, DistributeMode, DistributeNodesOptions, type DividePathsResult, type EllipseShape, type EvaluateAnimationOptions, FanOutTrajectoryOptions, type FitCubicsOptions, type FitPathDataOptions, type FitViewportOptions, type FlattenOptions, type GuideIndex, type GuideLine, INSTANCE_DATA_KEY, IncrementalLayoutOptions, type KeyframeDragState, type KeyframePatch, type KeyframeRangeOptions, type KeyframeRef, type KeyframeSnap, MAX_KEYFRAME_REFS, ManualClock, MatchSizeOptions, type MeasureGuide, type MeasureSelectionOptions, type MeasureSelectionResult, type MoveKeyframesResult, type MultiNodeTransitionOptions, type MultiPolygon, type NodeAnimation, NodeRectOptions, NodeTransition, type OffsetPathOptions, type OffsetShapeNodesOptions, type OklabColor, type OutlineShapeStrokesOptions, type OutlineStrokeOptions, type PathBooleanOperation, type PathBooleanResult, type PathCommand, type PathOperand, type PathOperandInput, PathOpsError, type PathOpsOptions, type PathOpsReport, type PathPiece, type PathPointAtLength, type PathShape, PlaceBesideOptions, Point, type PolygonBooleanOperation, type PolygonBooleanOptions, type PolygonFillRule, type PolygonInput, type PolygonOperand, type PolygonPiece, type PolygonRing, type PolygonToPathOptions, type PolygonWithHoles, Position, type PositionChangeLike, RESIZE_HANDLES, type RecordAnimationOptions, Rect, type RectShape, ReflowDisplacementOptions, type RegularPolygonShape, type ResizeHandle, SHAPE_DATA_KEY, SHAPE_KINDS, SHAPE_NODE_TYPE, SHAPE_OPERATIONS, type SampleAnimationOptions, type ScaleKeyframesOptions, type SerializedCanvasScenes, type SetKeyframeOptions, type ShapeDescription, type ShapeKind, type ShapeNodePolygonOptions, type ShapeOperation, type ShapePaint, type ShapePathEditOperation, type ShapePathEditRefusal, type ShapePathEditResult, type ShapeRenderData, type ShapeSize, Side, SizeDimension, type SnapGuidesOptions, type SnapNodeDragOptions, type SnapNodeDragResult, type SnapNodeResizeOptions, type SnapNodeResizeResult, type SnapResizeOptions, type SnapResizeResult, type SnapResult, type SpringEasing, type StarShape, StreamingLayoutManager, type StreamingLayoutManagerOptions, type StrokeCap, type StrokeJoin, TOKEN_BINDINGS_DATA_KEY, TOKEN_MODES_DATA_KEY, type TimelineKeyframe, type TimelineRow, type TimelineRowsOptions, TrajectoryFunction, type WebAnimationSpec, XYPosition, ZOrderOperation, addKeyframesAtTime, animateNode, applyAnimation, applyAnimationOverrides, applyConstraints, applyShapeCombination, applyShapeReplacement, arcToCubics, bezierPathArea, bezierPathBounds, bezierPathLength, bezierPathPointAtLength, bezierPathSignedArea, bezierPathToSvg, bindCanvasComponentProperty, bindCanvasToken, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canCombineShapeNodes, canOffsetShapeNodes, canOutlineShapeNodeStrokes, canvasHeight, centerNodes, centre, clampAnimationValue, clampLayoutSize, closeContour, collectDescendantIds, combineCanvasComponentsAsVariants, combineShapeNodes, computeNodesBoundingBox, computeSnapGuides, connectedOnly, contourSignedArea, contoursToPath, copyKeyframes, countPathSegments, createAnimationPlayer, createBezierTrajectory, createCanvasAnimationController, createCanvasArrangeController, createCanvasAutoLayoutController, createCanvasComponent, createCanvasComponentsController, createCanvasInstance, createCanvasScenesStore, createFanOutTrajectory, createGuideIndex, createNodeGuideIndex, cubicBezierAt, cubicPointAt, cubicsToPathData, dashContours, defaultEasing, deleteKeyframes, detachCanvasInstance, detachTokenBindings, diffOverrideGroups, distanceToBezierPath, dividePaths, dividePolygons, easingFromInfluence, easingLabel, easingToCss, ensureLayout, estimateCanvasHeight, estimateNodeSize, evaluateAnimation, evaluateEasing, evaluateTrack, excludePaths, exportCssAnimation, findConnectorSnap, findVariant, fitCubicRun, fitCubics, fitFreehandPath, fitPathData, fitViewportToNodes, fitViewportToRect, flattenSvgPath, flowSide, formatAnimationTime, formatNumber, formatOklab, formatVariantName, getAnimatableProperty, getAnimatedProperties, getAnimatedValue, getAnimationDuration, getAnimationTrack, getAutoLayout, getAutoLayoutGrid, getAutoLayoutInsertTarget, getBindableTokenProperties, getCanvasComponentDragId, getCanvasTokenProperty, getCenteredNodePosition, getChildLayout, getComponentData, getComponentInstances, getComponentPropertyDefs, getComponentPropertyRefs, getComponentSourceId, getCssPropertyAnimations, getDefaultVariant, getEffectiveTokenModes, getFlowChildren, getInstanceData, getInstanceProperties, getInstanceStatus, getKeyframeTimes, getLayerName, getLayoutParent, getLayoutSizing, getLayoutedNodes, getNodeAnimation, getNodeOverrides, getNodeShape, getNodeTokenBindings, getNodeTokenModes, getOwningComponent, getOwningInstance, getResizingNodeRect, getRootInstance, getShapeRenderData, getShapeSvg, getTimelineRows, getTimelineTicks, getTokenPropertyScope, getTokensForProperty, getVariantConflicts, getVariantOptions, getVariantSet, getVariantValues, handlePoint, hasVisibleStroke, inferResizeHandle, inspectCanvasInstance, inspectNodeTokens, interpolateAnimationValue, intersectPaths, intersectPolygons, isAnimationEasing, isAnimationKeyframe, isAutoLayoutFrame, isCanvasComponent, isCanvasComponentSet, isCanvasInstance, isCssExportExact, isEventFromTextInput, isInsideInstance, isKeyframeSelected, isMeasureModifierHeld, isNodeAnimated, isShapeDescription, isShapeNode, isStraightCubic, isValidCanvasEdge, isValidCanvasNode, isValidCanvasScene, isValidUrl, layoutAll, layoutBounds, layoutFrame, layoutUp, layoutUpMany, linearPositionTrajectory, linearTrajectory, listCanvasComponents, makeSizingCoherent, measureBetween, measureLabel, measureSelection, measureToLine, mergeNodeUpdates, mixColorsOklab, moveKeyframes, moveLayoutChild, multiPolygonArea, multiPolygonBounds, nearestHandlePositions, normalizeBezierPath, normalizeKeyframes, offsetPath, offsetShapeNodes, oklabToRgb, oppositePosition, outlineShapeNodeStrokes, outlineStroke, overlaps, pageHidden, parseCanvasClipboardData, parseCanvasScenes, parseCssEasing, parseKeyframeClipboard, parseNodeStyleDeclarations, parseOklab, parseSvgPath, parseVariantName, pasteKeyframes, pathBoolean, pathToContours, placeBeside, playWebAnimations, pointInBezierPath, pointInMultiPolygon, pointInRings, polygonArea, polygonBoolean, polygonToSvgPath, positionToSide, pruneCanvasTokenModes, pushCanvasInstanceOverrides, readAnimatableValue, readNodeStyleProperty, readOverrideGroup, realClock, recordAnimationChanges, relayoutUpdates, remapPastedNodes, removeTrack, repositionNodesTo, resetCanvasInstanceOverrides, resizeHandleAxes, resolveCanvasTokens, resolveEasing, resolvePadding, restoreCanvasMainComponent, revertShapeCombination, rgbToOklab, ringSignedArea, runMultiNodeTransition, sampleAnimationFrames, scaleKeyframes, segmentBounds, segmentCurvature, segmentDerivative, segmentExtrema, segmentLength, segmentNearest, segmentParamAtLength, segmentPoint, segmentTangent, serializeCanvasNodes, setCanvasComponentProperty, setCanvasInstanceProperties, setCanvasTokenMode, setKeyframe, setKeyframeEasing, setMotionPath, setTrackEnabled, shapeNodeToBezierPath, shapeNodeToPolygon, shapeToBezierPath, shapeToPolygon, sideToPosition, simplifyRing, snapKeyframeDelta, snapNodeDrag, snapNodeResize, snapResize, snapTimeToFrame, snapToGrid, splitSegment, springAt, strokeOutlineRings, subSegment, subtractPaths, subtractPolygons, swapCanvasInstance, syncAllCanvasInstances, syncCanvasComponents, syncCanvasInstance, timeToX, toBezierPath, toWebAnimations, transformBezierPath, trimSegments, unionPolygons, unitePaths, updateKeyframe, windingNumber, withNodeAnimation, withStyleOpacity, wouldCreateComponentCycle, wrapAnimationTime, writeNodeStyleProperty, writeOverrideGroup, xToTime, xorPolygons };