@glissade/core 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,30 @@
+# @glissade/core
+
+The engine-agnostic heart: pull-based signals, the serializable keyframe **Timeline document**, the fluent builder that compiles to it, easing + closed-form springs, OKLab color, `bake()` for stateful simulation under seeking, and the v2 analytic layer (ease derivatives, `velocityAt`, `spring.retarget`). Zero DOM or Node dependencies; ≤ 11 kB gz.
+
+```sh
+npm i @glissade/core
+```
+
+```ts
+import { timeline, spring } from '@glissade/core';
+
+const doc = timeline((tl) => {
+  tl.to('dot/opacity', 1, { duration: 0.5 })
+    .to('dot/position.x', 520, { ease: spring({ stiffness: 170, damping: 14 }) })
+    .label('arrived')
+    .to('dot/fill', '#7c4dff', { duration: 0.6, at: 'arrived' });
+});
+// `doc` is plain JSON: nothing executes at play time, so any t samples in O(log keys)
+```
+
+One contract underneath everything: evaluation is a **pure function of time** — same inputs, same output, in any order.
+
+## Part of glissade
+
+*(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.
+
+- [Repository & full README](https://github.com/tyevco/glissade)
+- [Getting started](https://github.com/tyevco/glissade/blob/main/docs/getting-started.md) · [Concepts](https://github.com/tyevco/glissade/blob/main/docs/concepts.md) · [Interactivity](https://github.com/tyevco/glissade/blob/main/docs/interactivity.md)
+
+Apache-2.0.

package/dist/index.d.ts

@@ -49,12 +49,29 @@ declare function untracked<T>(fn: () => T): T;
  * (spring overshoot); non-extrapolating types clamp.
  */
 type Vec2 = readonly [number, number];
+/** One bezier contour in Lottie's vertex form: anchor points + RELATIVE in/out tangents. */
+interface PathContour {
+  closed: boolean;
+  v: Vec2[];
+  in: Vec2[];
+  out: Vec2[];
+}
+/** The 'path' document value (§2.2): plain JSON, serializes with no new hooks. */
+type PathValue = PathContour[];
+/** Transition handoff policies (v2 addendum §A.4/§B.1); 'crossfade' reserved. */
+type HandoffKind = 'cut' | 'decay' | 'spring' | 'blend-from-frozen';
 interface ValueType<T> {
   id: string;
   lerp(a: T, b: T, t: number): T;
   /** Accepts easedT outside [0,1] (spring overshoot)? Otherwise clamped. */
   extrapolates: boolean;
   equals(a: T, b: T): boolean;
+  /** Optional linear-space operators (offset decay + reserved additive blending, §B.6). */
+  add?(a: T, b: T): T;
+  sub?(a: T, b: T): T;
+  scale?(a: T, k: number): T;
+  /** Type-class handoff default (§B.1): spring for kinetic, cut for hold-only. */
+  defaultHandoff?: HandoffKind;
 }
 type ValueTypeId = 'number' | 'vec2' | 'color' | 'string' | 'boolean' | (string & {});
 declare function registerValueType<T>(vt: ValueType<T>): void;
@@ -68,6 +85,15 @@ declare const vec2Type: ValueType<Vec2>;
 declare const colorType: ValueType<string>;
 declare const stringType: ValueType<string>;
 declare const booleanType: ValueType<boolean>;
+/**
+ * Path morphing (§2.2): pairwise lerp of anchors and tangents — exactly how
+ * lottie-web morphs, so imported animations are pixel-faithful. Mismatched
+ * topology snaps (hold a, then b at t ≥ 1) with a one-time dev warning; the
+ * de Casteljau normalization fallback for arbitrary native morphs is tracked
+ * future work. Lerp-only: offsets are not well-defined under mismatched
+ * topology, so no add/sub/scale — handoffs blend from the frozen value.
+ */
+declare const pathType: ValueType<PathValue>;
 declare class ValueTypeInferenceError extends Error {
   constructor(value: unknown);
 }
@@ -104,6 +130,12 @@ type EaseSpec = string | {
   mass: number;
 };
 declare const easings: Record<string, EasingFn>;
+/**
+ * Analytic derivatives d(u) of every named ease (§B.6) — closed-form, used
+ * for reading velocity off in-flight curves at interruption time. Property-
+ * tested against central differences at interior points.
+ */
+declare const easingDerivatives: Record<string, EasingFn>;
 /** Default property-tween ease (Motion Canvas precedent). */
 declare const DEFAULT_EASE = "easeInOutCubic";
 /**
@@ -111,6 +143,8 @@ declare const DEFAULT_EASE = "easeInOutCubic";
  * with a bisection fallback for the flat-derivative regions.
  */
 declare function cubicBezier(p1x: number, p1y: number, p2x: number, p2y: number): EasingFn;
+/** Analytic dy/dx of a cubic bézier ease: y'(s)/x'(s) at the solved parameter (§B.6). */
+declare function cubicBezierDerivative(p1x: number, p1y: number, p2x: number, p2y: number): EasingFn;
 declare class UnknownEasingError extends Error {
   constructor(name: string);
 }
@@ -144,10 +178,24 @@ declare function duration(cfg: SpringConfig, opts?: {
 declare function value(cfg: SpringConfig, t: number, opts?: {
   settleTolerance?: number;
 }): number;
+/**
+ * Velocity-matched retarget oscillator (v2 addendum §B.3): the same damped
+ * harmonic oscillator on an OFFSET in value units with nonzero initial
+ * velocity — y(0)=x0, y'(0)=v0, decaying to 0. No affine rescale (the target
+ * is exactly 0). Pure closed forms; seek-safe at any τ.
+ */
+interface RetargetSpring {
+  value(tau: number): number;
+  velocity(tau: number): number;
+  /** Earliest τ after which |value| stays within tol (default 0.005·|x0|+1e-6 floor). */
+  settleTime(tol?: number): number;
+}
+declare function retarget(cfg: SpringConfig, x0: number, v0: number): RetargetSpring;
 interface SpringFactory {
   (cfg: SpringConfig): SpringEase;
   duration: typeof duration;
   value: typeof value;
+  retarget: typeof retarget;
 }
 declare const spring: SpringFactory;
 /**
@@ -155,6 +203,12 @@ declare const spring: SpringFactory;
  * spring.duration(cfg) (validated at the document layer, §2.7).
  */
 declare function springEasing(cfg: SpringConfig): EasingFn;
+/**
+ * Analytic d/dp of springEasing (§B.6): oscillator derivative × the affine
+ * rescale factor × duration (chain rule p → t = p·D). Flat past p=1,
+ * matching value()'s clamp (right-derivative convention).
+ */
+declare function springEasingDerivative(cfg: SpringConfig): EasingFn;
 //#endregion
 //#region src/color.d.ts
 /**
@@ -215,9 +269,29 @@ declare function track<T>(target: string, type: ValueTypeId, keys: Key<T>[], opt
   editable?: boolean;
 }): Track<T>;
 declare function resolveEase(spec: EaseSpec | undefined): EasingFn;
+/**
+ * Analytic d(u) for an ease spec (§B.6). Custom-registered eases without a
+ * derivative fall back to a symmetric difference with a one-time dev warning.
+ */
+declare function resolveEaseDerivative(spec: EaseSpec | undefined): EasingFn;
+/**
+ * Analytic track derivative at time t, in value-units per second of local
+ * track time (v2 addendum §B.3/§B.6 conventions, pinned):
+ * (a) at a key boundary, velocity is the RIGHT derivative;
+ * (b) hold segments and the clamped regions outside the keys have v = 0;
+ * (c) types without sub/scale operators return null (no kinetic velocity).
+ */
+declare function velocityAt<T>(tr: Track<T>, t: number): T | null;
 /** Pure sample of a track at time t (§2.4). */
 declare function sampleTrack<T>(tr: Track<T>, t: number): T;
 //#endregion
+//#region src/devWarning.d.ts
+/** The configurable dev-warning channel (no DOM lib in core; console may not exist). */
+type DevWarning = (message: string) => void;
+declare function setDevWarning(fn: DevWarning): void;
+/** Internal: emit through the configurable channel. */
+declare function emitDevWarning(message: string): void;
+//#endregion
 //#region src/timeline.d.ts
 type Json = null | boolean | number | string | Json[] | {
   [k: string]: Json;
@@ -293,10 +367,6 @@ interface CompiledTimeline {
   /** Audio clips rebased to the root time axis (§5.3); sync timeScale scales playbackRate. */
   audio: AudioClip[];
 }
-type DevWarning = (message: string) => void;
-declare function setDevWarning(fn: DevWarning): void;
-/** Internal: emit through the configurable dev-warning channel. */
-
 declare function compileTimeline(doc: Timeline): CompiledTimeline;
 //#endregion
 //#region src/targetRef.d.ts
@@ -365,8 +435,18 @@ interface BindTarget {
   bindSource(fn: () => unknown): void;
   unbindSource(): void;
 }
+/** Analytic value/velocity access to one bound target (v2 addendum §B.6). */
+interface CurveSampler {
+  readonly track: Track;
+  /** Pure sample at local timeline time t. */
+  value(t: number): unknown;
+  /** Analytic derivative per §B.3 conventions; null for types without operators. */
+  velocity(t: number): unknown | null;
+}
 interface BoundTimeline {
   playhead: Playhead;
+  /** Per-target analytic samplers (additive, v2 §B.6); machines read these. */
+  samplers: ReadonlyMap<string, CurveSampler>;
   /** Detach every track binding, freezing signals at their last values. */
   unbind(): void;
 }
@@ -459,4 +539,4 @@ declare function normalizeEditedKeys(keys: Key[]): Key[];
  */
 declare function mergeSidecar(code: Timeline, sidecar: SidecarDoc | null | undefined): Timeline;
 //#endregion
-export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type CompiledTimeline, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type Json, type Key, type KeyOpts, type Marker, type OkLab, type Playhead, type Position, PositionError, type ReadonlySignal, type Rgba, type Rng, type SidecarDoc, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Signal, WriteDuringEvaluationError, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, easings, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, random, registerValueType, resolveEase, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type };
+export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type CompiledTimeline, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type OkLab, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type RetargetSpring, type Rgba, type Rng, type SidecarDoc, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Signal, WriteDuringEvaluationError, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/dist/index.js

@@ -287,6 +287,18 @@ function lerpColor(from, to, t) {
 	}));
 }
 //#endregion
+//#region src/devWarning.ts
+let devWarn = (msg) => {
+	globalThis.console?.warn(`[glissade] ${msg}`);
+};
+function setDevWarning(fn) {
+	devWarn = fn;
+}
+/** Internal: emit through the configurable channel. */
+function emitDevWarning(message) {
+	devWarn(message);
+}
+//#endregion
 //#region src/valueTypes.ts
 /**
 * Value-type registry with pluggable per-type interpolation (DESIGN.md §2.2).
@@ -312,20 +324,29 @@ const numberType = {
 	id: "number",
 	lerp: (a, b, t) => a + (b - a) * t,
 	extrapolates: true,
-	equals: Object.is
+	equals: Object.is,
+	add: (a, b) => a + b,
+	sub: (a, b) => a - b,
+	scale: (a, k) => a * k,
+	defaultHandoff: "spring"
 };
 const vec2Equals = (a, b) => a[0] === b[0] && a[1] === b[1];
 const vec2Type = {
 	id: "vec2",
 	lerp: (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t],
 	extrapolates: true,
-	equals: vec2Equals
+	equals: vec2Equals,
+	add: (a, b) => [a[0] + b[0], a[1] + b[1]],
+	sub: (a, b) => [a[0] - b[0], a[1] - b[1]],
+	scale: (a, k) => [a[0] * k, a[1] * k],
+	defaultHandoff: "spring"
 };
 const colorType = {
 	id: "color",
 	lerp: lerpColor,
 	extrapolates: true,
-	equals: (a, b) => a === b
+	equals: (a, b) => a === b,
+	defaultHandoff: "blend-from-frozen"
 };
 /** Discrete types: hold-only by construction (§2.2); lerp snaps at t=1. */
 function discrete(id) {
@@ -333,22 +354,77 @@ function discrete(id) {
 		id,
 		lerp: (a, b, t) => t >= 1 ? b : a,
 		extrapolates: false,
-		equals: (a, b) => Object.is(a, b)
+		equals: (a, b) => Object.is(a, b),
+		defaultHandoff: "cut"
 	};
 }
 const stringType = discrete("string");
 const booleanType = discrete("boolean");
+const lerpV = (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+/** Topology must match for a morph (contour count, closed flags, vertex counts). */
+function pathTopologyMatches(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		const ca = a[i];
+		const cb = b[i];
+		if (ca.closed !== cb.closed || ca.v.length !== cb.v.length) return false;
+	}
+	return true;
+}
+let warnedPathTopology = false;
+/**
+* Path morphing (§2.2): pairwise lerp of anchors and tangents — exactly how
+* lottie-web morphs, so imported animations are pixel-faithful. Mismatched
+* topology snaps (hold a, then b at t ≥ 1) with a one-time dev warning; the
+* de Casteljau normalization fallback for arbitrary native morphs is tracked
+* future work. Lerp-only: offsets are not well-defined under mismatched
+* topology, so no add/sub/scale — handoffs blend from the frozen value.
+*/
+const pathType = {
+	id: "path",
+	lerp: (a, b, t) => {
+		if (!pathTopologyMatches(a, b)) {
+			if (!warnedPathTopology) {
+				warnedPathTopology = true;
+				emitDevWarning("path lerp with mismatched topology (contour/vertex counts or closed flags differ): snapping instead of morphing — supply matched vertex counts (§2.2)");
+			}
+			return t >= 1 ? b : a;
+		}
+		return a.map((ca, i) => {
+			const cb = b[i];
+			return {
+				closed: ca.closed,
+				v: ca.v.map((p, j) => lerpV(p, cb.v[j], t)),
+				in: ca.in.map((p, j) => lerpV(p, cb.in[j], t)),
+				out: ca.out.map((p, j) => lerpV(p, cb.out[j], t))
+			};
+		});
+	},
+	extrapolates: false,
+	equals: (a, b) => {
+		if (a === b) return true;
+		if (!pathTopologyMatches(a, b)) return false;
+		const eq = (x, y) => x[0] === y[0] && x[1] === y[1];
+		return a.every((ca, i) => {
+			const cb = b[i];
+			return ca.v.every((p, j) => eq(p, cb.v[j])) && ca.in.every((p, j) => eq(p, cb.in[j])) && ca.out.every((p, j) => eq(p, cb.out[j]));
+		});
+	},
+	defaultHandoff: "blend-from-frozen"
+};
 var ValueTypeInferenceError = class extends Error {
 	constructor(value) {
 		super(`cannot infer a value type for ${JSON.stringify(value)}; register a custom type`);
 		this.name = "ValueTypeInferenceError";
 	}
 };
+const isContour = (c) => typeof c === "object" && c !== null && typeof c.closed === "boolean" && Array.isArray(c.v) && Array.isArray(c.in) && Array.isArray(c.out);
 /** Infer a registered type id from a sample value (builder + bake authoring surfaces). */
 function inferValueType(value) {
 	if (typeof value === "number") return "number";
 	if (typeof value === "boolean") return "boolean";
 	if (Array.isArray(value) && value.length === 2 && value.every((v) => typeof v === "number")) return "vec2";
+	if (Array.isArray(value) && value.length > 0 && value.every(isContour)) return "path";
 	if (typeof value === "string") try {
 		parseColor(value);
 		return "color";
@@ -362,6 +438,7 @@ registerValueType(vec2Type);
 registerValueType(colorType);
 registerValueType(stringType);
 registerValueType(booleanType);
+registerValueType(pathType);
 //#endregion
 //#region src/vec2Signal.ts
 /**
@@ -456,13 +533,75 @@ const easings = {
 	easeOutBounce: bounceOut,
 	easeInOutBounce: (t) => t < .5 ? (1 - bounceOut(1 - 2 * t)) / 2 : (1 + bounceOut(2 * t - 1)) / 2
 };
-/** Default property-tween ease (Motion Canvas precedent). */
-const DEFAULT_EASE = "easeInOutCubic";
+function bounceOutD(t) {
+	const n1 = 7.5625;
+	const d1 = 2.75;
+	if (t < 1 / d1) return 2 * n1 * t;
+	if (t < 2 / d1) return 2 * n1 * (t - 1.5 / d1);
+	if (t < 2.5 / d1) return 2 * n1 * (t - 2.25 / d1);
+	return 2 * n1 * (t - 2.625 / d1);
+}
+const LN2 = Math.LN2;
 /**
-* CSS-style cubic bézier where x is time and y is progress. Newton's method
-* with a bisection fallback for the flat-derivative regions.
+* Analytic derivatives d(u) of every named ease (§B.6) — closed-form, used
+* for reading velocity off in-flight curves at interruption time. Property-
+* tested against central differences at interior points.
 */
-function cubicBezier(p1x, p1y, p2x, p2y) {
+const easingDerivatives = {
+	linear: () => 1,
+	easeInQuad: (t) => 2 * t,
+	easeOutQuad: (t) => 2 * (1 - t),
+	easeInOutQuad: (t) => t < .5 ? 4 * t : 4 * (1 - t),
+	easeInCubic: (t) => 3 * t ** 2,
+	easeOutCubic: (t) => 3 * (1 - t) ** 2,
+	easeInOutCubic: (t) => t < .5 ? 12 * t ** 2 : 12 * (1 - t) ** 2,
+	easeInQuart: (t) => 4 * t ** 3,
+	easeOutQuart: (t) => 4 * (1 - t) ** 3,
+	easeInOutQuart: (t) => t < .5 ? 32 * t ** 3 : 32 * (1 - t) ** 3,
+	easeInQuint: (t) => 5 * t ** 4,
+	easeOutQuint: (t) => 5 * (1 - t) ** 4,
+	easeInOutQuint: (t) => t < .5 ? 80 * t ** 4 : 80 * (1 - t) ** 4,
+	easeInSine: (t) => Math.PI / 2 * Math.sin(t * Math.PI / 2),
+	easeOutSine: (t) => Math.PI / 2 * Math.cos(t * Math.PI / 2),
+	easeInOutSine: (t) => Math.PI / 2 * Math.sin(Math.PI * t),
+	easeInExpo: (t) => t === 0 ? 0 : 10 * LN2 * 2 ** (10 * t - 10),
+	easeOutExpo: (t) => t === 1 ? 0 : 10 * LN2 * 2 ** (-10 * t),
+	easeInOutExpo: (t) => t === 0 || t === 1 ? 0 : t < .5 ? 10 * LN2 * 2 ** (20 * t - 10) : 10 * LN2 * 2 ** (-20 * t + 10),
+	easeInCirc: (t) => t / Math.sqrt(1 - t * t),
+	easeOutCirc: (t) => (1 - t) / Math.sqrt(1 - (t - 1) * (t - 1)),
+	easeInOutCirc: (t) => t < .5 ? 2 * t / Math.sqrt(1 - 4 * t * t) : (2 - 2 * t) / Math.sqrt(1 - (-2 * t + 2) ** 2),
+	easeInBack: (t) => 3 * c3 * t ** 2 - 2 * c1 * t,
+	easeOutBack: (t) => 3 * c3 * (t - 1) ** 2 + 2 * c1 * (t - 1),
+	easeInOutBack: (t) => t < .5 ? 12 * 3.5949095 * t ** 2 - 4 * c2 * t : 3 * 3.5949095 * (2 * t - 2) ** 2 + 2 * c2 * (2 * t - 2),
+	easeInElastic: (t) => {
+		if (t === 0 || t === 1) return 0;
+		const theta = (t * 10 - 10.75) * c4;
+		const amp = 2 ** (10 * t - 10);
+		return -(10 * LN2 * amp * Math.sin(theta) + amp * 10 * c4 * Math.cos(theta));
+	},
+	easeOutElastic: (t) => {
+		if (t === 0 || t === 1) return 0;
+		const phi = (t * 10 - .75) * c4;
+		const amp = 2 ** (-10 * t);
+		return -10 * LN2 * amp * Math.sin(phi) + amp * 10 * c4 * Math.cos(phi);
+	},
+	easeInOutElastic: (t) => {
+		if (t === 0 || t === 1) return 0;
+		const psi = (20 * t - 11.125) * c5;
+		if (t < .5) {
+			const amp = 2 ** (20 * t - 10);
+			return -(20 * LN2 * amp * Math.sin(psi) + amp * 20 * c5 * Math.cos(psi)) / 2;
+		}
+		const amp = 2 ** (-20 * t + 10);
+		return (-20 * LN2 * amp * Math.sin(psi) + amp * 20 * c5 * Math.cos(psi)) / 2;
+	},
+	easeInBounce: (t) => bounceOutD(1 - t),
+	easeOutBounce: bounceOutD,
+	easeInOutBounce: (t) => t < .5 ? bounceOutD(1 - 2 * t) : bounceOutD(2 * t - 1)
+};
+/** Default property-tween ease (Motion Canvas precedent). */
+const DEFAULT_EASE = "easeInOutCubic";
+function bezierKernel(p1x, p1y, p2x, p2y) {
 	const ax = 3 * p1x - 3 * p2x + 1;
 	const bx = 3 * p2x - 6 * p1x;
 	const cx = 3 * p1x;
@@ -472,6 +611,7 @@ function cubicBezier(p1x, p1y, p2x, p2y) {
 	const sampleX = (u) => ((ax * u + bx) * u + cx) * u;
 	const sampleY = (u) => ((ay * u + by) * u + cy) * u;
 	const sampleDX = (u) => (3 * ax * u + 2 * bx) * u + cx;
+	const sampleDY = (u) => (3 * ay * u + 2 * by) * u + cy;
 	const solveU = (x) => {
 		let u = x;
 		for (let i = 0; i < 8; i++) {
@@ -491,10 +631,33 @@ function cubicBezier(p1x, p1y, p2x, p2y) {
 		}
 		return u;
 	};
+	return {
+		sampleY,
+		sampleDX,
+		sampleDY,
+		solveU
+	};
+}
+/**
+* CSS-style cubic bézier where x is time and y is progress. Newton's method
+* with a bisection fallback for the flat-derivative regions.
+*/
+function cubicBezier(p1x, p1y, p2x, p2y) {
+	const k = bezierKernel(p1x, p1y, p2x, p2y);
 	return (t) => {
 		if (t <= 0) return 0;
 		if (t >= 1) return 1;
-		return sampleY(solveU(t));
+		return k.sampleY(k.solveU(t));
+	};
+}
+/** Analytic dy/dx of a cubic bézier ease: y'(s)/x'(s) at the solved parameter (§B.6). */
+function cubicBezierDerivative(p1x, p1y, p2x, p2y) {
+	const k = bezierKernel(p1x, p1y, p2x, p2y);
+	return (t) => {
+		const u = k.solveU(Math.min(1, Math.max(0, t)));
+		const dx = k.sampleDX(u);
+		if (Math.abs(dx) < 1e-9) return 0;
+		return k.sampleDY(u) / dx;
 	};
 }
 var UnknownEasingError = class extends Error {
@@ -519,6 +682,20 @@ function params(cfg) {
 		zeta: cfg.damping / (2 * Math.sqrt(cfg.stiffness * mass))
 	};
 }
+/** Raw closed-form spring velocity at time t — d/dt of rawValue's three branches. */
+function rawDerivative(cfg, t) {
+	if (t <= 0) return 0;
+	const { w0, zeta } = params(cfg);
+	if (Math.abs(zeta - 1) < 1e-9) return w0 * w0 * t * Math.exp(-w0 * t);
+	if (zeta < 1) {
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		return Math.exp(-zeta * w0 * t) * (w0 * w0 / wd) * Math.sin(wd * t);
+	}
+	const s = Math.sqrt(zeta * zeta - 1);
+	const r1 = -w0 * (zeta - s);
+	const r2 = -w0 * (zeta + s);
+	return r1 * r2 * (Math.exp(r1 * t) - Math.exp(r2 * t)) / (r1 - r2);
+}
 /** Raw closed-form spring position at time t (seconds). Approaches 1, may overshoot. */
 function rawValue(cfg, t) {
 	if (t <= 0) return 0;
@@ -565,6 +742,53 @@ function value(cfg, t, opts) {
 	const d = duration(cfg, opts);
 	return rawValue(cfg, Math.min(t, d)) / rawValue(cfg, d);
 }
+function retarget(cfg, x0, v0) {
+	const { w0, zeta } = params(cfg);
+	let value0;
+	let velocity0;
+	let envelope;
+	if (Math.abs(zeta - 1) < 1e-9) {
+		const b = v0 + w0 * x0;
+		value0 = (tau) => tau <= 0 ? x0 : Math.exp(-w0 * tau) * (x0 + b * tau);
+		velocity0 = (tau) => tau <= 0 ? v0 : Math.exp(-w0 * tau) * (v0 - w0 * b * tau);
+		envelope = (tau) => Math.exp(-w0 * tau) * (Math.abs(x0) + Math.abs(b) * tau);
+	} else if (zeta < 1) {
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		const c2v = (v0 + zeta * w0 * x0) / wd;
+		const amp = Math.hypot(x0, c2v);
+		value0 = (tau) => tau <= 0 ? x0 : Math.exp(-zeta * w0 * tau) * (x0 * Math.cos(wd * tau) + c2v * Math.sin(wd * tau));
+		velocity0 = (tau) => tau <= 0 ? v0 : Math.exp(-zeta * w0 * tau) * (v0 * Math.cos(wd * tau) - (w0 * w0 * x0 + zeta * w0 * v0) / wd * Math.sin(wd * tau));
+		envelope = (tau) => Math.exp(-zeta * w0 * tau) * amp;
+	} else {
+		const s = Math.sqrt(zeta * zeta - 1);
+		const rp = w0 * (-zeta + s);
+		const rm = w0 * (-zeta - s);
+		const cp = (v0 - rm * x0) / (rp - rm);
+		const cm = (rp * x0 - v0) / (rp - rm);
+		value0 = (tau) => tau <= 0 ? x0 : cp * Math.exp(rp * tau) + cm * Math.exp(rm * tau);
+		velocity0 = (tau) => tau <= 0 ? v0 : cp * rp * Math.exp(rp * tau) + cm * rm * Math.exp(rm * tau);
+		envelope = (tau) => Math.abs(cp) * Math.exp(rp * tau) + Math.abs(cm) * Math.exp(rm * tau);
+	}
+	const settleTime = (tol) => {
+		const eps = tol ?? Math.abs(x0) * .005 + 1e-6;
+		if (envelope(0) <= eps && Math.abs(v0) < 1e-12) return 0;
+		let hi = 1 / w0;
+		let guard = 0;
+		while (envelope(hi) > eps && guard++ < 64) hi *= 2;
+		let lo = 0;
+		for (let i = 0; i < 64 && hi - lo > 1e-9; i++) {
+			const mid = (lo + hi) / 2;
+			if (Math.max(envelope(mid), envelope(mid * 1.05 + 1e-6)) > eps) lo = mid;
+			else hi = mid;
+		}
+		return hi;
+	};
+	return {
+		value: value0,
+		velocity: velocity0,
+		settleTime
+	};
+}
 const spring = Object.assign((cfg) => {
 	params(cfg);
 	return {
@@ -575,7 +799,8 @@ const spring = Object.assign((cfg) => {
 	};
 }, {
 	duration,
-	value
+	value,
+	retarget
 });
 /**
 * The spring as a normalized easing over a segment whose length must equal
@@ -585,6 +810,16 @@ function springEasing(cfg) {
 	const d = duration(cfg);
 	return (p) => value(cfg, p * d);
 }
+/**
+* Analytic d/dp of springEasing (§B.6): oscillator derivative × the affine
+* rescale factor × duration (chain rule p → t = p·D). Flat past p=1,
+* matching value()'s clamp (right-derivative convention).
+*/
+function springEasingDerivative(cfg) {
+	const d = duration(cfg);
+	const scale = d / rawValue(cfg, d);
+	return (p) => p >= 1 ? 0 : rawDerivative(cfg, p * d) * scale;
+}
 //#endregion
 //#region src/track.ts
 /**
@@ -645,6 +880,27 @@ function resolveEase(spec) {
 	if (spec.kind === "cubicBezier") return cubicBezier(...spec.pts);
 	return springEasing(spec);
 }
+const warnedNumericDerivative = /* @__PURE__ */ new Set();
+/**
+* Analytic d(u) for an ease spec (§B.6). Custom-registered eases without a
+* derivative fall back to a symmetric difference with a one-time dev warning.
+*/
+function resolveEaseDerivative(spec) {
+	if (spec === void 0) return easingDerivatives["linear"];
+	if (typeof spec === "string") {
+		const d = easingDerivatives[spec];
+		if (d) return d;
+		const fn = namedEasing(spec);
+		if (!warnedNumericDerivative.has(spec)) {
+			warnedNumericDerivative.add(spec);
+			emitDevWarning(`easing '${spec}' has no registered derivative; velocity uses a numeric fallback — register one in easingDerivatives for exact interruption handoff`);
+		}
+		const h = 1e-5;
+		return (u) => (fn(Math.min(1, u + h)) - fn(Math.max(0, u - h))) / (Math.min(1, u + h) - Math.max(0, u - h));
+	}
+	if (spec.kind === "cubicBezier") return cubicBezierDerivative(...spec.pts);
+	return springEasingDerivative(spec);
+}
 const samplerStates = /* @__PURE__ */ new WeakMap();
 function state(tr) {
 	let s = samplerStates.get(tr);
@@ -684,6 +940,34 @@ function findSegment(keys, t, hint) {
 	}
 	return lo;
 }
+/**
+* Analytic track derivative at time t, in value-units per second of local
+* track time (v2 addendum §B.3/§B.6 conventions, pinned):
+* (a) at a key boundary, velocity is the RIGHT derivative;
+* (b) hold segments and the clamped regions outside the keys have v = 0;
+* (c) types without sub/scale operators return null (no kinetic velocity).
+*/
+function velocityAt(tr, t) {
+	const vt = getValueType(tr.type);
+	if (!vt.sub || !vt.scale) return null;
+	const keys = tr.keys;
+	const n = keys.length;
+	const s = state(tr);
+	const i = findSegment(keys, t, s.cursor);
+	const zero = vt.scale(vt.sub(keys[0].value, keys[0].value), 0);
+	if (i === 0 || i >= n) return zero;
+	const arrival = keys[i];
+	if (arrival.interp === "hold") return zero;
+	const prev = keys[i - 1];
+	const segDur = arrival.t - prev.t;
+	const p = (t - prev.t) / segDur;
+	if (!vt.extrapolates) {
+		const eased = easeFor(tr, s, i)(p);
+		if (eased < 0 || eased > 1) return zero;
+	}
+	const d = resolveEaseDerivative(arrival.ease)(p);
+	return vt.scale(vt.sub(arrival.value, prev.value), d / segDur);
+}
 /** Pure sample of a track at time t (§2.4). */
 function sampleTrack(tr, t) {
 	const keys = tr.keys;
@@ -740,16 +1024,6 @@ function validateSpringKeys(tr) {
 		}
 	}
 }
-let devWarn = (msg) => {
-	globalThis.console?.warn(`[glissade] ${msg}`);
-};
-function setDevWarning(fn) {
-	devWarn = fn;
-}
-/** Internal: emit through the configurable dev-warning channel. */
-function emitDevWarning(message) {
-	devWarn(message);
-}
 function rebaseKeys(keys, at, timeScale) {
 	return keys.map((k) => ({
 		...k,
@@ -797,7 +1071,7 @@ function coalesce(entries) {
 		const existingStart = existing.keys[0].t;
 		const existingEnd = existing.keys[existing.keys.length - 1].t;
 		const kept = existing.keys.filter((k) => k.t < start || k.t > end);
-		if (existingStart <= end && start <= existingEnd) devWarn(`overlapping tracks for '${tr.target}' in [${start}, ${end}]: later insertion wins (${existing.keys.length - kept.length} earlier key(s) dropped)`);
+		if (existingStart <= end && start <= existingEnd) emitDevWarning(`overlapping tracks for '${tr.target}' in [${start}, ${end}]: later insertion wins (${existing.keys.length - kept.length} earlier key(s) dropped)`);
 		existing.keys = [...kept, ...tr.keys].sort((a, b) => a.t - b.t);
 	}
 	return byTarget;
@@ -1103,14 +1377,21 @@ var UnboundTargetError = class extends Error {
 */
 function bindTimeline(compiled, resolve, playhead = createPlayhead()) {
 	const bound = [];
+	const samplers = /* @__PURE__ */ new Map();
 	for (const [target, tr] of compiled.tracks) {
 		const sig = resolve(target);
 		if (!sig) throw new UnboundTargetError(target);
 		sig.bindSource(() => sampleTrack(tr, playhead()));
 		bound.push(sig);
+		samplers.set(target, {
+			track: tr,
+			value: (t) => sampleTrack(tr, t),
+			velocity: (t) => velocityAt(tr, t)
+		});
 	}
 	return {
 		playhead,
+		samplers,
 		unbind: () => {
 			for (const sig of bound) sig.unbindSource();
 		}
@@ -1328,4 +1609,4 @@ function mergeSidecar(code, sidecar) {
 	return merged;
 }
 //#endregion
-export { BakeError, CircularDependencyError, ColorParseError, DEFAULT_EASE, PositionError, SidecarVersionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, easings, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, random, registerValueType, resolveEase, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type };
+export { BakeError, CircularDependencyError, ColorParseError, DEFAULT_EASE, PositionError, SidecarVersionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "glissade core: signals, tracks, timeline document, evaluation, easing, springs, seeded RNG. Zero DOM/Node dependencies.",
   "license": "Apache-2.0",
   "type": "module",