@sophistry/core 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Lucier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @sophistry/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-free animation and visualization engine: a retained scene graph, tracks, seekable animations, geometry, themes and a Canvas2D renderer. Pair it with a binding ([`@sophistry/solidjs`](../solidjs) or [`@sophistry/react`](../react)).
+
+Part of [sophistry](https://sophistry.dev), controllable Manim for the web. Pre-1.0: minor releases may break.
+
+## Install
+
+```sh
+pnpm add @sophistry/core
+```
+
+## Example
+
+```ts
+import { circle, createScene, draw, track } from "@sophistry/core";
+
+const scene = createScene({ host: document.getElementById("stage") as HTMLElement });
+const drawn = track(0);
+scene.root.add(circle.create({ radius: 2, progress: drawn }));
+void scene.play(draw(drawn, { duration: 1.5 }));
+```
+
+Subpaths: `/geometry`, `/color`, `/themes` (pure helpers) and the unstable `/internal`.
+
+## Links
+
+[Documentation](https://sophistry.dev) · [API](https://sophistry.dev/reference/api/) · [Source](https://github.com/BenjaminLucier/sophistry/tree/main/packages/core) · MIT

package/dist/anim/animation.d.ts

@@ -0,0 +1,208 @@
+/**
+ * The animation model: an `Animation` is data plus a sampler with a known
+ * duration, not a running process. A runner (`timeline.ts`) samples the whole
+ * script at one absolute time per clock step, which keeps composition exact and
+ * makes fast-forward and scrubbing work. No canvas, no clock here.
+ */
+import type { Easing } from "../tween/easing";
+/**
+ * Floating-point slack, in seconds, when comparing absolute times. Child
+ * offsets are sums of floats (`0.1 + 0.2`), so a child that "should" be exactly
+ * finished can land a few ulps short; without slack its last frame would be
+ * left at 0.99999999 of the way.
+ */
+export declare const EPSILON = 1e-9;
+/**
+ * A lazy, seekable animation with a known length. Nothing runs when you build
+ * one; a runner ({@link timeline}, {@link play}) samples it. Implement the
+ * members only for a custom leaf (see {@link animation}).
+ *
+ * `seek(t)` writes the state for local time `t` and must not depend on what
+ * time was seen before. Composites restore children that are now ahead of the
+ * seek time to their start ({@link Animation.restore}), and write later
+ * children over earlier ones. {@link Animation.begin} runs the first time a
+ * child is entered, seeing the world as of its own start time, so relative
+ * animations capture what the previous step left; restoring does not re-arm.
+ * `repeat` and `forever` re-enter each cycle.
+ *
+ * @see {@link https://sophistry.dev/guides/timelines/#what-seeking-does}
+ * @see {@link https://sophistry.dev/guides/extending/#custom-animations}
+ * @category Animation composition & timelines
+ */
+export interface Animation {
+    /**
+     * Length in seconds of timeline time, including any leading `delay`.
+     * `Infinity` is allowed (`forever`); a runner then never finishes on its own.
+     */
+    readonly duration: number;
+    /**
+     * The local time a reduced-motion run jumps to instead of playing: the
+     * state the animation comes to rest in. Defaults to {@link
+     * Animation.duration} when that is finite and to `0` when it is infinite
+     * (an endless loop holds its starting state). {@link compose} derives it
+     * from its children, so `sequence(fadeIn(a), forever(spin(b)))` rests at
+     * the end of the fade with the spin held at its start.
+     */
+    readonly restAt?: number;
+    /**
+     * Called when the animation is armed: the first time it is entered, and
+     * again for each fresh run (a new `repeat` cycle, a `timeline` replay).
+     * Capture start values here, with `peek()`.
+     * It is **not** called again when the animation is merely re-entered after
+     * a {@link Animation.restore}; the earlier capture stays valid.
+     */
+    begin?(): void;
+    /**
+     * Writes the state for local time `t` (clamped to `[0, duration]` by the
+     * composites and by {@link animation}).
+     */
+    seek(t: number): void;
+    /**
+     * Optional: writes the start state (what `seek(0)` would write for a leaf
+     * with no leading hold) **and keeps whatever {@link Animation.begin}
+     * captured**. Composites call it instead of `seek(0)` when a scrub rewinds
+     * to before the animation's start, and then skip `begin()` on re-entry. It
+     * matters for zero-length leaves (whose `seek` can only report the final
+     * value) and for `from`-style leaves (whose start state would otherwise be
+     * mistaken for the rest value). Does nothing if the animation was never
+     * entered. When omitted, composites fall back to `seek(0)` and re-arm the
+     * animation with `begin()` on re-entry (the pre-`restore` behaviour).
+     */
+    restore?(): void;
+    /**
+     * Optional cleanup when the run is aborted while this animation is active
+     * (entered but not finished). The grow presets use it to snap back to rest.
+     * Presets that simply stop where they stand leave it undefined.
+     */
+    abort?(): void;
+}
+/** The time a reduced-motion run of `animation` jumps to; see {@link Animation.restAt}. */
+export declare function restTime(animation: Animation): number;
+/**
+ * Normalises a requested seek time into `[0, duration]`, always finite.
+ *
+ * `NaN` and `-Infinity` mean the start (`0`); a finite or `+Infinity` time is
+ * clamped to `duration`. `+Infinity` on an *endless* animation has no end to
+ * land on, so it lands on `rest` (the reduced-motion rest state, finite by
+ * construction). Every `seek` path goes through this so a non-finite time can
+ * never reach arithmetic like `Infinity - Infinity`.
+ */
+export declare function sampleTime(t: number, duration: number, rest?: number): number;
+/**
+ * Builds a custom leaf {@link Animation}.
+ *
+ * `seek` always receives a time clamped to `[0, duration]`, and `duration` is
+ * sanitised (negative or NaN becomes 0; `Infinity` is allowed). Use it for
+ * anything the track-driving builders ({@link driveTrack}, {@link driveProgress})
+ * do not cover.
+ *
+ * @param spec - The members of {@link Animation}.
+ * @returns The animation.
+ * @category Animation composition & timelines
+ */
+export declare function animation(spec: Animation): Animation;
+/** Timing common to every eased leaf. */
+export interface LeafTiming {
+    /**
+     * Seconds of eased motion; 0 lands immediately.
+     * @default 1
+     */
+    duration?: number;
+    /**
+     * Seconds of leading hold inside the animation's own duration.
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Easing curve name or function.
+     * @default `"smooth"`
+     */
+    easing?: Easing;
+}
+/** What an eased leaf does at each sampled progress. */
+export interface LeafHooks {
+    /** Capture start values (via `peek`). */
+    begin?: () => void;
+    /**
+     * Write state for eased progress `eased` (raw progress `raw`, uneased,
+     * 0..1).
+     */
+    apply: (eased: number, raw: number) => void;
+    /** Cleanup when aborted while active. Only called if the leaf has begun. */
+    abort?: () => void;
+    /**
+     * Write the start state (progress 0) for the whole leading `delay` too,
+     * instead of staying silent until the delay ends. The grow presets use it
+     * so a delayed grow is hidden during its delay. Without it a delaying leaf
+     * does not touch the track until the delay is over (so it cannot clobber a
+     * concurrent animation of the same track), except to restore the start
+     * when it is rewound.
+     */
+    holdStart?: boolean;
+}
+/**
+ * The shared eased leaf: `[delay][duration of eased progress]`.
+ *
+ * Handles delay, zero-length animations (a zero-length `seek` reports only the
+ * final value; {@link Animation.restore} writes the start), easing, and lazy
+ * `begin` so a leaf can be seeked directly in a test without a composite
+ * around it.
+ */
+export declare function easedLeaf(timing: LeafTiming, hooks: LeafHooks): Animation;
+/** A child placed at an offset inside a composite. */
+export interface Placed {
+    animation: Animation;
+    /** Seconds after the composite's start at which the child begins. */
+    start: number;
+}
+/**
+ * Builds a composite from children placed at known offsets. `sequence`,
+ * `parallel` and `lagged` are all this with different offsets.
+ *
+ * Duration is `max(start + child.duration)`. See {@link Animation} for the
+ * seek semantics it implements.
+ *
+ * A steady-state seek costs O(active children + log n), not O(n): children
+ * are indexed by start and by end time, the active ones are kept in a list,
+ * and only a seek that moves *backwards* visits the children it crosses.
+ * The bookkeeping rests on two invariants that hold after every seek to
+ * `last`: a child that has been entered started at or before `last`, and a
+ * finished (DONE) child ended at or before `last`. So a forward seek can only
+ * enter children starting in `(last, now]`, and a backward one can only
+ * rewind children starting in `(now, last]` or reopen ones ending there.
+ */
+export declare function compose(children: Placed[]): Animation;
+/**
+ * Where each cycle of a `repeat`/`forever` takes its start values from.
+ *
+ * - `"continue"`: from wherever the previous cycle left the tracks (the
+ *   default). Relative animations accumulate.
+ * - `"fixed"`: from one capture taken when the repeat is first entered; every
+ *   cycle restarts from it. Scrubbing is exact in both directions.
+ *
+ * @category Animation composition & timelines
+ */
+export type CycleStart = "continue" | "fixed";
+/**
+ * Plays `inner` `times` times; the engine behind `repeat` and `forever`.
+ *
+ * Each cycle re-enters `inner`, so it captures its start values afresh from
+ * wherever the previous cycle left the tracks (a `forever` of
+ * `sequence(valueTo(a, 2), valueTo(a, 0))` loops without a jump, and a
+ * repeated relative move accumulates). A seek that jumps over cycles finishes
+ * each skipped cycle in turn so those captures are right (at most
+ * {@link MAX_REPLAYED_CYCLES} are replayed; older ones are skipped).
+ *
+ * Scrubbing *backwards* across a cycle boundary re-samples the earlier cycle
+ * with the start values captured for the most recent cycle, because the
+ * earlier capture is gone: exact for absolute animations, an offset for
+ * relative ones that accumulate.
+ *
+ * With `start: "fixed"` the animation is entered once and every cycle replays
+ * from that one capture (each new cycle first restores the start state, it
+ * does not recapture). Relative animations then repeat the same move instead
+ * of accumulating, and because no cycle depends on a previous one, a seek
+ * anywhere, in either direction, is exact.
+ */
+export declare function cycles(inner: Animation, times: number, start?: CycleStart): Animation;
+//# sourceMappingURL=animation.d.ts.map

package/dist/anim/animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation.d.ts","sourceRoot":"","sources":["../../src/anim/animation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAG9C;;;;;GAKG;AACH,eAAO,MAAM,OAAO,OAAO,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,IAAI,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CACf;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAKrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,MAAM,CAMxE;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAUpD;AAED,yCAAyC;AACzC,MAAM,WAAW,UAAU;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,SAAS;IACzB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,CA0CzE;AAOD,sDAAsD;AACtD,MAAM,WAAW,MAAM;IACtB,SAAS,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;CACd;AAsCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAwNrD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAK9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CACrB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,UAAuB,GAC5B,SAAS,CA6EX"}

package/dist/anim/draw.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Creation animations — `draw` (Manim `Create`), `erase` (`Uncreate`), `write`, `drawBorderThenFill`.
+ *
+ * All of them drive a shape's `progress` track from 0 to 1; the renderer turns
+ * that into an arc-length reveal. A shape's polylines share one budget, spent in
+ * order, so a multi-part shape draws part by part rather than all at once.
+ */
+import type { Animatable } from "../tween";
+import type { Animation, AnimOptions } from "./types";
+/** @category Animation presets */
+export interface DrawOptions extends AnimOptions {
+    /** Progress (0..1) to reset the track to before drawing; defaults to the track's current value. */
+    from?: number;
+}
+/**
+ * Draws a shape on by tweening its `progress` track to 1, tip-first.
+ *
+ * Bind the track to a shape's `progress` prop; the renderer reveals the
+ * outline by arc length. Easing defaults to `"linear"` so the pen moves at a
+ * constant speed. Start the track at 0 (or pass `from`) for a full draw-on.
+ *
+ * @param progress - The shape's progress track, 0..1.
+ * @param options - Timing options plus `from`.
+ * @returns An {@link Animation}.
+ * @see {@link erase}
+ * @see {@link write}
+ *
+ * @category Animation presets
+ */
+export declare function draw(progress: Animatable<number>, options?: DrawOptions): Animation;
+/**
+ * Erases a shape by tweening its `progress` track to 0.
+ *
+ * @param progress - The shape's progress track, 0..1.
+ * @param options - Timing options; `easing` defaults to `"linear"`.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function erase(progress: Animatable<number>, options?: AnimOptions): Animation;
+/**
+ * Options for {@link write}: {@link DrawOptions} plus the stagger between tracks.
+ *
+ * @category Animation presets
+ */
+export interface WriteOptions extends DrawOptions {
+    /**
+     * Seconds between consecutive starts. Ignored when `lagRatio` is given.
+     * @default 0.12
+     */
+    lag?: number;
+    /** Manim's `lag_ratio`: start each when the previous is this fraction through. Takes precedence over `lag`. */
+    lagRatio?: number;
+}
+/**
+ * `Write`: a staggered {@link draw} across several tracks, the way Manim
+ * draws one glyph after another.
+ *
+ * Pass one progress track per stroke or label, in drawing order. Each starts
+ * `lag` seconds after the previous one and runs for the full `duration`.
+ *
+ * @param progresses - One progress track (0..1) per element.
+ * @param options - Timing options plus the stagger: `lag`, seconds between starts (default 0.12), or `lagRatio` (see {@link lagged}). If both are given, `lagRatio` wins and `lag` is ignored.
+ * @returns An {@link Animation}.
+ * @category Animation presets
+ */
+export declare function write(progresses: Animatable<number>[], options?: WriteOptions): Animation;
+/** @category Animation presets */
+export interface UnwriteOptions extends AnimOptions {
+    /**
+     * Seconds between consecutive starts. Ignored when `lagRatio` is given.
+     * @default 0.12
+     */
+    lag?: number;
+    /** Manim's `lag_ratio`: start each when the previous is this fraction through; takes precedence over `lag`. */
+    lagRatio?: number;
+    /**
+     * Erase from the end backwards, as Manim's `Unwrite` does. Writing runs left
+     * to right, so unwriting the same way looks like the text is being eaten
+     * from the front; going backwards reads as undoing it. Defaults to true.
+     */
+    reverse?: boolean;
+}
+/**
+ * `Unwrite` — `write` in reverse: a staggered `erase` across several tracks.
+ *
+ * The stagger runs from the last track to the first by default, so the stroke
+ * that was drawn last is the first to go.
+ *
+ * @category Animation presets
+ */
+export declare function unwrite(progresses: Animatable<number>[], options?: UnwriteOptions): Animation;
+/**
+ * `DrawBorderThenFill`: traces the outline, then fades the fill in.
+ *
+ * The total `duration` (default 1.5 seconds) is split 65% on the outline and
+ * 35% on the fill. Bind the tracks to a shape's `progress` and `fillOpacity`.
+ *
+ * @param progress - Outline progress track, 0..1.
+ * @param fillOpacity - Fill opacity track, 0..1.
+ * @param options - Timing options plus `fillTo`, the final fill opacity (default 1).
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function drawBorderThenFill(progress: Animatable<number>, fillOpacity: Animatable<number>, options?: AnimOptions & {
+    fillTo?: number;
+}): Animation;
+//# sourceMappingURL=draw.d.ts.map

package/dist/anim/draw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../../src/anim/draw.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQtD,kCAAkC;AAClC,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CACnB,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,GAAE,WAAgB,GACvB,SAAS,CAEX;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACpB,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,GAAE,WAAgB,GACvB,SAAS,CAEX;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAa,SAAQ,WAAW;IAChD;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CACpB,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,EAChC,OAAO,GAAE,YAAiB,GACxB,SAAS,CAMX;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACtB,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,EAChC,OAAO,GAAE,cAAmB,GAC1B,SAAS,CAOX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,EAC/B,OAAO,GAAE,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,SAAS,CAWX"}

package/dist/anim/emphasis.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Emphasis presets — `Indicate`, `Flash`, `Wiggle`, `Circumscribe`.
+ *
+ * These are the ones that are pure easing-curve tricks: each returns the track
+ * to exactly where it started, so they can be fired at any time without
+ * disturbing the scene's resting state.
+ */
+import type { Animatable } from "../tween";
+import type { Animation, AnimOptions } from "./types";
+/** @category Animation presets */
+export interface IndicateOptions extends AnimOptions {
+    /**
+     * Peak scale multiplier relative to the resting scale.
+     * @default 1.2
+     */
+    factor?: number;
+    /** Colour track to flash to `highlight` and back; omit for a scale-only swell. */
+    color?: Animatable<string>;
+    /** CSS colour to flash to. Defaults to the theme's `palette.highlight`. */
+    highlight?: string;
+}
+/**
+ * `Indicate`: a quick swell and return, optionally with a colour flash.
+ *
+ * Scales up to `factor` times the resting scale and back, so the track ends
+ * where it began and the animation can be fired at any time. Duration defaults
+ * to 0.8 seconds.
+ *
+ * @param scale - Scale track to swell.
+ * @param options - Timing options plus {@link IndicateOptions} fields.
+ * @returns An {@link Animation}.
+ * @category Animation presets
+ */
+export declare function indicate(scale: Animatable<number>, options?: IndicateOptions): Animation;
+/**
+ * `Flash`: a ring that expands outward while fading to transparent.
+ *
+ * Drive a circle whose radius and opacity are these two tracks. Opacity goes
+ * from 1 to 0; it is not restored afterwards.
+ *
+ * @param radius - Radius track in scene units.
+ * @param opacity - Opacity track, 0..1.
+ * @param options - Timing options (duration 0.6 s, easing `"out"` by
+ *   default) plus `from` (start radius, default the track's value) and `to`
+ *   (end radius, default 2.2 times the start).
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function flash(radius: Animatable<number>, opacity: Animatable<number>, options?: AnimOptions & {
+    to?: number;
+    from?: number;
+}): Animation;
+/**
+ * `Wiggle`: a damped rotational shake that settles back to rest.
+ *
+ * @param rotation - Rotation track, radians.
+ * @param options - Timing options (duration 0.7 s, linear) plus `amplitude`,
+ *   the peak swing in radians (default 0.12), and `cycles`, the number of
+ *   oscillations (default 3).
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function wiggle(rotation: Animatable<number>, options?: AnimOptions & {
+    amplitude?: number;
+    cycles?: number;
+}): Animation;
+/**
+ * A slow breathing pulse; useful as ambient emphasis under {@link forever}.
+ *
+ * @param scale - Scale track; returns to its starting value.
+ * @param options - Timing options (duration 1.6 s) plus `factor`, the peak
+ *   multiplier (default 1.06).
+ * @returns An {@link Animation}.
+ * @category Animation presets
+ */
+export declare function pulse(scale: Animatable<number>, options?: AnimOptions & {
+    factor?: number;
+}): Animation;
+/**
+ * `Circumscribe`: draws a highlight shape around something, then erases it.
+ *
+ * Point it at the progress track of a rectangle or circle you keep hidden. The
+ * duration (default 1.2 seconds) is split evenly between drawing and erasing.
+ *
+ * @param progress - Progress track (0..1) of the highlight shape.
+ * @param options - Timing options; `easing` defaults to `"inOut"`.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function circumscribe(progress: Animatable<number>, options?: AnimOptions): Animation;
+//# sourceMappingURL=emphasis.d.ts.map

package/dist/anim/emphasis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emphasis.d.ts","sourceRoot":"","sources":["../../src/anim/emphasis.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtD,kCAAkC;AAClC,MAAM,WAAW,eAAgB,SAAQ,WAAW;IACnD;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACvB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,OAAO,GAAE,eAAoB,GAC3B,SAAS,CA+BX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CACpB,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAC1B,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,EAC3B,OAAO,GAAE,WAAW,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,SAAS,CAmBX;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACrB,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,GAAE,WAAW,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,SAAS,CAqBX;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CACpB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,OAAO,GAAE,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,SAAS,CAWX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC3B,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,GAAE,WAAgB,GACvB,SAAS,CAaX"}

package/dist/anim/fade.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Fades. The whole category is one opacity tween, plus optional drift so
+ * `FadeIn(shift=UP)` has an equivalent.
+ */
+import type { Point } from "../geometry";
+import type { Animatable } from "../tween";
+import type { Animation, AnimOptions } from "./types";
+/** @category Animation presets */
+export interface FadeOptions extends AnimOptions {
+    /**
+     * Opacity (0..1) that `fadeIn` ends on.
+     * @default 1
+     */
+    to?: number;
+}
+/**
+ * Tweens an opacity track up to 1 (or `options.to`), easing out.
+ *
+ * It does not set the track to 0 first: the fade starts from the track's
+ * current value, so initialise the track to 0 for a fade from invisible.
+ *
+ * @param opacity - Opacity track, 0..1; pass `opacity()` to a shape's `opacity` prop.
+ * @param options - Timing options; `easing` defaults to `"out"`.
+ * @returns An {@link Animation}.
+ * @see {@link fadeOut}
+ * @see {@link fadeInFrom}
+ *
+ * @category Animation presets
+ */
+export declare function fadeIn(opacity: Animatable<number>, options?: FadeOptions): Animation;
+/**
+ * Tweens an opacity track down to 0, easing in.
+ *
+ * @param opacity - Opacity track, 0..1.
+ * @param options - Timing options; `easing` defaults to `"in"`.
+ * @returns An {@link Animation}.
+ * @see {@link fadeIn}
+ *
+ * @category Animation presets
+ */
+export declare function fadeOut(opacity: Animatable<number>, options?: AnimOptions): Animation;
+/**
+ * Tweens an opacity track to an arbitrary value.
+ *
+ * Identical to {@link valueTo}; it exists so "fade to half" reads naturally
+ * beside `fadeIn`/`fadeOut`. Easing defaults to `"smooth"`.
+ *
+ * @param opacity - Opacity track, 0..1.
+ * @param value - Target opacity.
+ * @param options - Timing options.
+ * @returns An {@link Animation}.
+ * @category Animation presets
+ */
+export declare function fadeTo(opacity: Animatable<number>, value: number, options?: AnimOptions): Animation;
+/**
+ * `FadeIn(shift=...)`: fades in while sliding from an offset back to rest.
+ *
+ * When entered, the position is displaced by `offset` (and held there through
+ * any `delay`) and then tweened back to where it was, so the track ends where
+ * it started and composes with layout.
+ *
+ * @param opacity - Opacity track, 0..1.
+ * @param position - Position track in scene units.
+ * @param offset - Displacement in scene units to start from (e.g. `{ x: 0, y: -1 }`).
+ * @param options - Timing options; `easing` defaults to `"out"`.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function fadeInFrom(opacity: Animatable<number>, position: Animatable<Point>, offset: Point, options?: FadeOptions): Animation;
+/**
+ * `FadeOut(shift=...)`: fades out while drifting away by `offset`.
+ *
+ * @param opacity - Opacity track, 0..1.
+ * @param position - Position track in scene units; ends at its start plus `offset`.
+ * @param offset - Displacement in scene units.
+ * @param options - Timing options; `easing` defaults to `"in"`.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function fadeOutTo(opacity: Animatable<number>, position: Animatable<Point>, offset: Point, options?: AnimOptions): Animation;
+//# sourceMappingURL=fade.d.ts.map

package/dist/anim/fade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fade.d.ts","sourceRoot":"","sources":["../../src/anim/fade.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAI3C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtD,kCAAkC;AAClC,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CACrB,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,EAC3B,OAAO,GAAE,WAAgB,GACvB,SAAS,CAEX;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACtB,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,EAC3B,OAAO,GAAE,WAAgB,GACvB,SAAS,CAEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CACrB,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,CAEX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CACzB,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,EAC3B,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,EAC3B,MAAM,EAAE,KAAK,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,CAUX;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,EAC3B,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,EAC3B,MAAM,EAAE,KAAK,EACb,OAAO,GAAE,WAAgB,GACvB,SAAS,CAaX"}

package/dist/anim/growing.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Growing presets (Manim's `growing`): bring a shape in by scale rather than by
+ * arc length. The rest value is captured on entry (`peek`), the start state is
+ * held through `delay`, and an aborted grow snaps back to rest so a cancelled
+ * script never leaves a shape half-size or invisible.
+ */
+import type { Bounds, Point } from "../geometry";
+import type { Animatable } from "../tween";
+import type { Animation, AnimOptions } from "./types";
+/**
+ * `GrowFromCenter` — the shape swells from nothing about its own centre.
+ *
+ * Drives a scale track from 0 to wherever it was resting. The component's
+ * `origin` decides what "centre" means; left unset that is the shape's own
+ * bounding-box centre, which is exactly Manim's behaviour.
+ *
+ * This is also Manim's `GrowArrow`: set `origin={tail}` on an `arrow()` and the
+ * scale track pivots on the tail. It inflates a small complete arrow, head and
+ * all, where `draw()` draws a full-size one progressively.
+ *
+ * @param scale - Scale track; its value when the animation is entered is the resting scale.
+ * @param options - Timing options; duration 1 s and easing `"out"` by default.
+ * @returns An {@link Animation}.
+ * @category Animation presets
+ */
+export declare function growFromCenter(scale: Animatable<number>, options?: AnimOptions): Animation;
+/**
+ * `ShrinkToCenter`: the inverse of {@link growFromCenter}; the scale collapses
+ * to 0.
+ *
+ * @param scale - Scale track.
+ * @param options - Timing options; duration 1 s and easing `"in"` by default.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function shrinkToCenter(scale: Animatable<number>, options?: AnimOptions): Animation;
+/**
+ * `GrowFromPoint` — the shape grows while travelling from `from` to its resting
+ * position, so it reads as having been thrown from somewhere.
+ *
+ * Built the same way as `fadeInFrom`: displace first, then tween both tracks
+ * back together. Because both resting values are captured on entry, this
+ * composes with layout — the shape lands wherever it would have been anyway.
+ *
+ * @param scale - Scale track.
+ * @param position - Position track in scene units.
+ * @param from - Scene-space point the shape starts at.
+ * @param options - Timing options; duration 1 s and easing `"out"` by default.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function growFromPoint(scale: Animatable<number>, position: Animatable<Point>, from: Point, options?: AnimOptions): Animation;
+/**
+ * Manim's `GrowFromEdge`: the shape unfolds from one edge or corner of its own
+ * box, which stays pinned. Any direction works (`{ x: 0.5, y: 1 }` is a point
+ * along the top edge). Pass the shape's resting box, `handle()?.localBounds()`.
+ *
+ * @param scale - Scale track.
+ * @param position - Position track.
+ * @param bounds - The shape's resting box, in the shape's local coordinates.
+ * @param direction - Anchor on the box, e.g. `{ x: -1, y: 0 }` for the left edge.
+ * @param options - Timing options; duration 1 s and easing `"out"` by default.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function growFromEdge(scale: Animatable<number>, position: Animatable<Point>, bounds: Bounds, direction: Point, options?: AnimOptions): Animation;
+/** @category Animation presets */
+export interface SpinInOptions extends AnimOptions {
+    /**
+     * Turn to arrive through, in radians. Defaults to Manim's quarter turn.
+     * @default Math.PI / 2
+     */
+    turn?: number;
+}
+/**
+ * `SpinInFromNothing` — grows while rotating into place.
+ *
+ * The rotation *ends* at rest, so the shape settles at whatever angle the scene
+ * had it; only the approach spins. Both tracks are driven together, so easing
+ * applies to the pair and the spin can't outrun the growth.
+ *
+ * @param scale - Scale track.
+ * @param rotation - Rotation track, radians.
+ * @param options - Timing options plus `turn`; duration 1 s and easing `"out"` by default.
+ * @returns An {@link Animation}.
+ *
+ * @category Animation presets
+ */
+export declare function spinInFromNothing(scale: Animatable<number>, rotation: Animatable<number>, options?: SpinInOptions): Animation;
+//# sourceMappingURL=growing.d.ts.map

package/dist/anim/growing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"growing.d.ts","sourceRoot":"","sources":["../../src/anim/growing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAqCtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,OAAO,GAAE,WAAgB,GACvB,SAAS,CAUX;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,OAAO,GAAE,WAAgB,GACvB,SAAS,CAQX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,EAC3B,IAAI,EAAE,KAAK,EACX,OAAO,GAAE,WAAgB,GACvB,SAAS,CAEX;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,QAAQ,EAAE,UAAU,CAAC,KAAK,CAAC,EAC3B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,KAAK,EAChB,OAAO,GAAE,WAAgB,GACvB,SAAS,CAeX;AAwCD,kCAAkC;AAClC,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAC5B,OAAO,GAAE,aAAkB,GACzB,SAAS,CAiBX"}