@glissade/core 0.2.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,6 +49,15 @@ 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> {
@@ -76,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);
 }
@@ -521,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, 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 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, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };
+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).
@@ -348,17 +360,71 @@ function discrete(id) {
 }
 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";
@@ -372,6 +438,7 @@ registerValueType(vec2Type);
 registerValueType(colorType);
 registerValueType(stringType);
 registerValueType(booleanType);
+registerValueType(pathType);
 //#endregion
 //#region src/vec2Signal.ts
 /**
@@ -754,18 +821,6 @@ function springEasingDerivative(cfg) {
 	return (p) => p >= 1 ? 0 : rawDerivative(cfg, p * d) * scale;
 }
 //#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/track.ts
 /**
 * Track & keyframe model (DESIGN.md §2.2) and sampling (§2.4): binary search
@@ -1554,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, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };
+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.2.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",