@pixerate/editor 0.27.0 → 0.28.0

package/README.md

@@ -399,7 +399,8 @@ Each module is also available as a subpath import:
 | `@pixerate/editor/history` | `HistoryManager`: a command-pattern undo/redo stack with gesture merge keys, undo marks, a byte budget and a History-panel listing; `DirtyTracker` / `bindDirtyToHistory` |
 | `@pixerate/editor/spreadsheet` | `SpreadsheetController`, formula parser/evaluator and dependency graph, formula function registry (`registerFormulaFunction`, `listFormulaFunctions`, `searchFormulaFunctions`, `getFormulaSignature`) and autocomplete helpers (`getFormulaHints`, `applyFormulaSuggestion`) |
 | `@pixerate/editor/image-editor` | `ImageEditorController` and Canvas 2D renderer: crop, adjustments, annotations, depth masks, selections and layer masks, and AI hooks. Needs a DOM/canvas environment (the selection algorithms themselves are pure). |
-| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, clipboard and streaming layout helpers |
+| `@pixerate/editor/animation` | The keyframe model without canvas nodes: `AnimationTrack` / `AnimationKeyframe`, easing (`resolveEasing`, `evaluateEasing`, `cubicBezierAt`, `springAt`, presets, `parseCssEasing`, `easingToCss`), `evaluateTrack`, `interpolateAnimationValue`, `normalizeKeyframes`, OKLab colour mixing, `AnimationPlayer` and the `Clock` / `ManualClock` / `realClock` time sources (no third-party imports) |
+| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, clipboard and streaming layout helpers, and node keyframe animation (re-exports everything in `/animation`) |
 | `@pixerate/editor/agent` | MCP tool schemas, a planner for agent-driven canvas edits, and the dynamic `ToolRegistry` with editor/spreadsheet tool providers |
 | `@pixerate/editor/commands` | `CommandRegistry`, `ShortcutMap`, palette ranking, `createCommandToolProvider` and built-in history / arrange / spreadsheet commands (no third-party imports) |
 | `@pixerate/editor/persistence` | Autosave and crash recovery (`createAutosaveController`, `createRecoveryPolicy`, `createRevisionTracker`), storage adapters (memory, localStorage, IndexedDB, OPFS) and document migration (`migrateDocument`, `loadSections`, `LoadReport`) (no third-party imports) |
@@ -408,7 +409,29 @@ Each module is also available as a subpath import:
 | `@pixerate/editor/export` | Word export: `exportDocx`, `exportDocxBlob`, `createDocxParts`, `DocxExportController`, plus the zip writer and XML escapers it uses (no third-party imports; also re-exported from the root entry) |
 | `@pixerate/editor/tokens` | Design tokens: collections, modes, aliases, `TokenStore`, `resolveToken`, W3C Design Tokens JSON and CSS custom-property export (no third-party imports) |
 
-The root entry (`@pixerate/editor`) re-exports everything except canvas, agent, commands, persistence, generation, tokens and image editor, including TipTap. Import from the narrowest subpath you need: `grammar`, `history`, `spreadsheet`, `commands`, `persistence` and `image-editor` have no third-party imports, so a spreadsheet-only app bundles no TipTap, markdown or dagre code. The package is marked `sideEffects: false`, so unused root exports are also tree-shaken.
+The root entry (`@pixerate/editor`) re-exports everything except animation, canvas, agent, commands, persistence, generation, tokens and image editor, including TipTap. Import from the narrowest subpath you need: `grammar`, `history`, `animation`, `spreadsheet`, `commands`, `persistence` and `image-editor` have no third-party imports, so a spreadsheet-only app bundles no TipTap, markdown or dagre code. The package is marked `sideEffects: false`, so unused root exports are also tree-shaken.
+
+## Keyframe animation without the canvas
+
+`@pixerate/editor/animation` is the keyframe model on its own: no dagre, TipTap or canvas nodes. Use it to animate anything you can describe as a track of numbers or CSS colours.
+
+```ts
+import { evaluateTrack, createAnimationPlayer, ManualClock, type AnimationTrack } from "@pixerate/editor/animation";
+
+const opacity: AnimationTrack = {
+  keyframes: [
+    { time: 0, value: 0, easing: "ease-out" },
+    { time: 600, value: 1, easing: { type: "spring", stiffness: 170, damping: 26 } },
+    { time: 1200, value: 0.5 },
+  ],
+};
+evaluateTrack(opacity, 300); // eased value at 300 ms
+evaluateTrack({ keyframes: [{ time: 0, value: "#ff0000" }, { time: 1000, value: "transparent" }] }, 500, "color"); // OKLab mix
+
+const player = createAnimationPlayer({ clock: new ManualClock(), duration: 1200, loop: "ping-pong", onTime: (t) => console.log(evaluateTrack(opacity, t)) });
+```
+
+`@pixerate/editor/canvas` re-exports all of it, and adds node tracks (`evaluateAnimation`, `applyAnimation`), editing, timeline and export helpers on top.
 
 ## Autosave, crash recovery and document migration
 

package/dist/animation/index.cjs

@@ -0,0 +1,62 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+var _chunkTTYCN6ZHcjs = require('../chunk-TTYCN6ZH.cjs');
+require('../chunk-A6PHCAGX.cjs');
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.ANIMATION_EASING_LABELS = _chunkTTYCN6ZHcjs.ANIMATION_EASING_LABELS; exports.ANIMATION_EASING_PRESETS = _chunkTTYCN6ZHcjs.ANIMATION_EASING_PRESETS; exports.ANIMATION_TIME_EPSILON = _chunkTTYCN6ZHcjs.ANIMATION_TIME_EPSILON; exports.AnimationPlayer = _chunkTTYCN6ZHcjs.AnimationPlayer; exports.CUBIC_BEZIER_PRESETS = _chunkTTYCN6ZHcjs.CUBIC_BEZIER_PRESETS; exports.ManualClock = _chunkTTYCN6ZHcjs.ManualClock; exports.createAnimationPlayer = _chunkTTYCN6ZHcjs.createAnimationPlayer; exports.cubicBezierAt = _chunkTTYCN6ZHcjs.cubicBezierAt; exports.easingFromInfluence = _chunkTTYCN6ZHcjs.easingFromInfluence; exports.easingLabel = _chunkTTYCN6ZHcjs.easingLabel; exports.easingToCss = _chunkTTYCN6ZHcjs.easingToCss; exports.evaluateEasing = _chunkTTYCN6ZHcjs.evaluateEasing; exports.evaluateTrack = _chunkTTYCN6ZHcjs.evaluateTrack; exports.formatOklab = _chunkTTYCN6ZHcjs.formatOklab; exports.interpolateAnimationValue = _chunkTTYCN6ZHcjs.interpolateAnimationValue; exports.isAnimationEasing = _chunkTTYCN6ZHcjs.isAnimationEasing; exports.isAnimationKeyframe = _chunkTTYCN6ZHcjs.isAnimationKeyframe; exports.mixColorsOklab = _chunkTTYCN6ZHcjs.mixColorsOklab; exports.normalizeKeyframes = _chunkTTYCN6ZHcjs.normalizeKeyframes; exports.oklabToRgb = _chunkTTYCN6ZHcjs.oklabToRgb; exports.pageHidden = _chunkTTYCN6ZHcjs.pageHidden; exports.parseCssEasing = _chunkTTYCN6ZHcjs.parseCssEasing; exports.parseOklab = _chunkTTYCN6ZHcjs.parseOklab; exports.realClock = _chunkTTYCN6ZHcjs.realClock; exports.resolveEasing = _chunkTTYCN6ZHcjs.resolveEasing; exports.rgbToOklab = _chunkTTYCN6ZHcjs.rgbToOklab; exports.springAt = _chunkTTYCN6ZHcjs.springAt; exports.wrapAnimationTime = _chunkTTYCN6ZHcjs.wrapAnimationTime;
+//# sourceMappingURL=index.cjs.map

package/dist/animation/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/editor/editor/packages/core/dist/animation/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,+qDAAC","file":"/home/runner/work/editor/editor/packages/core/dist/animation/index.cjs"}

package/dist/animation/index.d.cts

@@ -0,0 +1,296 @@
+/**
+ * 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 tracks, independent of what they animate: each track is a list of keyframes
+ * `{ time (ms), value, easing }`, where the easing governs the segment *leaving* the keyframe
+ * (filmcraft / After Effects convention).
+ */
+/** 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;
+}
+/** How a track's values interpolate: numbers linearly, colours in OKLab. */
+type AnimationValueType = 'number' | 'color';
+/** 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[];
+
+/** How time past the end of the timeline maps back into it. */
+type AnimationLoopMode = 'none' | 'loop' | 'ping-pong';
+/**
+ * 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;
+/**
+ * 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;
+
+/**
+ * The time source that animations (and canvas agent performances) play on.
+ *
+ * Defaults to `realClock` (requestAnimationFrame and setTimeout).
+ * A `ManualClock` moves only when told to via `advance(ms)` or `tick(fps)`,
+ * enabling deterministic frame-by-frame stepping for testing, video generation,
+ * or headless server environments.
+ */
+interface Clock {
+    /** Current time in milliseconds. */
+    now(): number;
+    /** Resolves on the next animation frame. */
+    frame(): Promise<void>;
+    /** Resolves after `ms` milliseconds of this clock's time. */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Whether the clock follows wall time. Live clocks stop or degrade when the
+     * tab is in the background (browsers pause animation frames), so transitions
+     * can commit immediately rather than leaving operations hanging.
+     */
+    readonly live: boolean;
+}
+/** Whether the browser tab is hidden (where RAF pauses). */
+declare const pageHidden: () => boolean;
+/** Real-time clock using requestAnimationFrame and setTimeout. */
+declare const realClock: Clock;
+/**
+ * A deterministic clock that only moves forward when `advance` or `tick` is called.
+ * Allows step-by-step frame testing and video rendering without waiting for real time.
+ */
+declare class ManualClock implements Clock {
+    readonly live = false;
+    private time;
+    private frames;
+    private sleepers;
+    private seq;
+    constructor(start?: number);
+    now(): number;
+    frame(): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    /** Whether any frames or sleep timers are currently pending. */
+    get pending(): boolean;
+    /** Advances time by `ms`, resolving due sleep timers in order, followed by queued frames. */
+    advance(ms: number): Promise<void>;
+    /** Convenience method to advance by 1 frame at a given fps (default: 60fps = 16.67ms). */
+    tick(fps?: number): Promise<void>;
+}
+
+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;
+
+export { ANIMATION_EASING_LABELS, ANIMATION_EASING_PRESETS, ANIMATION_TIME_EPSILON, type AnimationEasing, type AnimationEasingPreset, type AnimationKeyframe, type AnimationLoopMode, AnimationPlayer, type AnimationPlayerOptions, type AnimationPlayerState, type AnimationTrack, type AnimationValue, type AnimationValueType, CUBIC_BEZIER_PRESETS, type Clock, type CubicBezierEasing, ManualClock, type OklabColor, type SpringEasing, createAnimationPlayer, cubicBezierAt, easingFromInfluence, easingLabel, easingToCss, evaluateEasing, evaluateTrack, formatOklab, interpolateAnimationValue, isAnimationEasing, isAnimationKeyframe, mixColorsOklab, normalizeKeyframes, oklabToRgb, pageHidden, parseCssEasing, parseOklab, realClock, resolveEasing, rgbToOklab, springAt, wrapAnimationTime };