@glissade/core 0.50.0 → 0.51.0-pre.1

package/dist/track.d.ts

@@ -168,6 +168,14 @@ interface ValueType<T> {
   /** Accepts easedT outside [0,1] (spring overshoot)? Otherwise clamped. */
   extrapolates: boolean;
   equals(a: T, b: T): boolean;
+  /**
+   * Optional fail-loud structural guard for a keyframe VALUE, called per key by
+   * `validateTrack`. Throws (with the offending field named) on a structurally
+   * invalid value that `lerp` would otherwise turn into a NaN / native-backend
+   * panic much later. ADDITIVE: only throws on genuinely invalid input, so every
+   * valid document is unaffected (goldens byte-identical).
+   */
+  validate?(value: T): void;
   /** Optional linear-space operators (offset decay + reserved additive blending, §B.6). */
   add?(a: T, b: T): T;
   sub?(a: T, b: T): T;

package/dist/track.js

@@ -809,6 +809,22 @@ const paintType = {
 		return paintSnap(t, a, b);
 	},
 	extrapolates: false,
+	validate: (v) => {
+		if (v === null || typeof v !== "object" || !("kind" in v)) throw new TypeError(`paint value must be an object with a 'kind', got ${JSON.stringify(v)}`);
+		switch (v.kind) {
+			case "color":
+				if (typeof v.color !== "string") throw new TypeError("paint kind 'color' requires a string `color`");
+				return;
+			case "linear":
+			case "radial":
+				if (!Array.isArray(v.stops) || v.stops.length === 0) throw new TypeError(`paint kind '${v.kind}' requires a non-empty \`stops\` array`);
+				return;
+			case "mesh":
+				if (!Array.isArray(v.points) || v.points.length === 0) throw new TypeError("paint kind 'mesh' requires a non-empty `points` array");
+				return;
+			default: throw new TypeError(`unknown paint kind '${v.kind}' (expected color | linear | radial | mesh)`);
+		}
+	},
 	equals: (a, b) => {
 		if (a === b) return true;
 		if (a.kind !== b.kind) return false;
@@ -900,6 +916,11 @@ function validateTrack(track) {
 	if (vt.defaultHandoff === "cut") {
 		for (const k of track.keys) if (k.interp !== "hold") k.interp = "hold";
 	}
+	if (vt.validate) for (const k of track.keys) try {
+		vt.validate(k.value);
+	} catch (e) {
+		throw new TrackValidationError(track.target, `invalid ${vt.id} keyframe at t=${k.t}: ${e instanceof Error ? e.message : String(e)}`);
+	}
 	const repr = vt.repr ?? vt.id;
 	if (repr === "number" || repr === "vec2") {
 		for (const k of track.keys) if (!(repr === "number" ? typeof k.value === "number" && Number.isFinite(k.value) : Array.isArray(k.value) && k.value.length === 2 && k.value.every((n) => typeof n === "number" && Number.isFinite(n)))) {

package/package.json

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