@glissade/lottie 0.50.0 → 0.51.0-pre.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _glissade_scene0 from "@glissade/scene";
 import { Node, SceneModule } from "@glissade/scene";
-import { PathContour, PathValue, Timeline, Vec2 } from "@glissade/core";
+import { Paint, PathContour, PathValue, Timeline, Vec2 } from "@glissade/core";
 
 //#region src/spec.d.ts
 
@@ -19,7 +19,8 @@ interface GroupSpec extends BaseSpec {
 interface PathSpec extends BaseSpec {
   kind: 'path';
   data: PathValue;
-  fill?: string;
+  /** A CSS color string, or a linear/radial gradient `Paint` (imported from `gf`). */
+  fill?: string | Paint;
   stroke?: string;
   strokeWidth?: number;
 }
@@ -102,6 +103,16 @@ interface LottieShapePathData {
   o: number[][];
   c?: boolean;
 }
+/**
+ * A gradient color ramp (`gf`/`gs` `.g`): `p` = the number of COLOR stops, `k`
+ * the animatable flattened array. Static `k` is `[offset,r,g,b, …]` (p color
+ * stops, 0–1 floats) optionally followed by `[offset,a, …]` alpha stops when any
+ * stop is translucent; the split point is `p*4`.
+ */
+interface LottieGradient {
+  p: number;
+  k: LottieProp;
+}
 interface LottieShapeItem {
   /** shape direction: 3 = reversed winding (el/rc). */
   d?: number | {
@@ -115,11 +126,11 @@ interface LottieShapeItem {
   /** sh */
   ks?: LottieProp;
   closed?: boolean;
-  /** el / rc / tr */
+  /** el / rc / tr — also gf/gs gradient START point (s) + highlight angle (a). */
   p?: LottieProp;
   s?: LottieProp;
   a?: LottieProp;
-  /** rc corner radius / fl-st opacity-adjacent fields */
+  /** rc corner radius / fl-st opacity-adjacent fields / gf-gs fill rule. */
   r?: LottieProp | number;
   /** fl / st */
   c?: LottieProp;
@@ -127,6 +138,11 @@ interface LottieShapeItem {
   w?: LottieProp;
   /** mm */
   mm?: number;
+  /** gf / gs gradient: type (1 linear, 2 radial), END point, highlight length, color ramp. */
+  t?: number;
+  e?: LottieProp;
+  h?: LottieProp;
+  g?: LottieGradient;
 }
 interface LottieTransform {
   a?: LottieProp;

package/dist/index.js

@@ -289,7 +289,6 @@ const UNSUPPORTED_SHAPE_ITEMS = {
 	rp: "repeater",
 	rd: "round corners",
 	sr: "polystar",
-	gf: "gradient fill",
 	gs: "gradient stroke",
 	zz: "zig-zag",
 	op: "offset path",
@@ -337,6 +336,20 @@ function auditShapeItems(ctx, items, where) {
 				checkExpression(ctx, item.o, `${here}.o`);
 				checkExpression(ctx, item.w, `${here}.w`);
 				break;
+			case "gf": {
+				if (sawGroup) reject(ctx, "unsupported-shape-structure", `style inheriting into a preceding group at ${here}`);
+				if (typeof item.r === "number" && item.r === 2) reject(ctx, "unsupported-fill-rule", `even-odd gradient fill at ${here}`);
+				if (item.t !== 1 && item.t !== 2) reject(ctx, "unsupported-gradient", `gradient type ${String(item.t)} (only linear=1 / radial=2) at ${here}`);
+				if (!isProp(item.s) || !isProp(item.e)) reject(ctx, "invalid-gradient", `${here}: gradient fill missing start/end point (s/e)`);
+				const g = item.g;
+				if (!g || typeof g.p !== "number" || g.p < 1 || !isProp(g.k)) reject(ctx, "invalid-gradient", `${here}: gradient fill missing color stops (g.p/g.k)`);
+				for (const [name, prop] of [["h", item.h], ["a", item.a]]) if (isProp(prop) && !isKeyframed(prop) && typeof prop.k === "number" && Math.abs(prop.k) > 1e-9) reject(ctx, "unsupported-gradient", `radial highlight (${name}) at ${here}`);
+				checkExpression(ctx, item.s, `${here}.s`);
+				checkExpression(ctx, item.e, `${here}.e`);
+				checkExpression(ctx, item.o, `${here}.o`);
+				checkExpression(ctx, g?.k, `${here}.g`);
+				break;
+			}
 			case "mm": {
 				const mode = item.mm ?? 1;
 				if (mode !== 1) degrade(ctx, "unsupported-shape-modifier", `merge paths mode ${mode} at ${here}`);
@@ -884,6 +897,112 @@ function mergeGeomSources(ctx, sources, tm, where) {
 		keys: enforceMonotonic(keys)
 	};
 }
+/** Lottie gf color ramp (`g.k`) → glissade ColorStop[]. The first `p` groups of
+* `[offset,r,g,b]` are colors (0–1 floats); trailing `[offset,a]` groups are alpha
+* stops, merged onto each color offset (interpolated across the alpha ramp). */
+function gradientStops(k, p) {
+	const alphas = [];
+	for (let i = p * 4; i + 1 < k.length; i += 2) alphas.push({
+		offset: k[i],
+		a: k[i + 1]
+	});
+	const alphaAt = (offset) => {
+		if (alphas.length === 0) return 1;
+		let lo = alphas[0];
+		if (offset <= lo.offset) return lo.a;
+		for (let j = 1; j < alphas.length; j++) {
+			const hi = alphas[j];
+			if (offset <= hi.offset) {
+				const span = hi.offset - lo.offset;
+				return span > 0 ? lo.a + (hi.a - lo.a) * (offset - lo.offset) / span : hi.a;
+			}
+			lo = hi;
+		}
+		return lo.a;
+	};
+	const stops = [];
+	for (let i = 0; i < p; i++) {
+		const o = i * 4;
+		const offset = k[o] ?? 0;
+		stops.push({
+			offset,
+			color: formatColor({
+				r: (k[o + 1] ?? 0) * 255,
+				g: (k[o + 2] ?? 0) * 255,
+				b: (k[o + 3] ?? 0) * 255,
+				a: alphaAt(offset)
+			})
+		});
+	}
+	return stops;
+}
+/** Reconstruct a static Paint from a gf's start/end points + ramp — the inverse of
+* export.ts's gradientStart/gradientEnd (radial: centre = s, radius = |s→e|). */
+function buildStaticPaint(t, s, e, k, p) {
+	const stops = gradientStops(k, p);
+	if (t === 2) return {
+		kind: "radial",
+		stops,
+		center: [s[0], s[1]],
+		radius: Math.hypot(e[0] - s[0], e[1] - s[1])
+	};
+	return {
+		kind: "linear",
+		stops,
+		from: [s[0], s[1]],
+		to: [e[0], e[1]]
+	};
+}
+/** Set `spec.fill` to a linear/radial Paint (static) or push a `paint` track (animated). */
+function applyGradientFill(ctx, spec, style, tm) {
+	const t = style.t;
+	const p = style.g?.p ?? 0;
+	const sNorm = norms(style.s);
+	const eNorm = norms(style.e);
+	const gNorm = norms(style.g?.k);
+	const staticS = () => vec2Of(style.s?.k ?? [0, 0]);
+	const staticE = () => vec2Of(style.e?.k ?? [0, 0]);
+	const staticG = () => Array.isArray(style.g?.k.k) ? style.g.k.k : [];
+	if (!sNorm && !eNorm && !gNorm) {
+		spec.fill = buildStaticPaint(t, staticS(), staticE(), staticG(), p);
+		return;
+	}
+	const channels = [
+		sNorm,
+		eNorm,
+		gNorm
+	].filter((n) => n !== void 0);
+	const first = channels[0];
+	const aligned = channels.every((n) => n.length === first.length && n.every((kk, j) => kk.t === first[j].t));
+	let keys;
+	if (aligned) {
+		keys = convertKeys(gNorm ?? sNorm ?? eNorm, tm, () => ({
+			kind: "linear",
+			stops: []
+		}));
+		for (let j = 0; j < keys.length; j++) {
+			const s = sNorm ? vec2Of(sNorm[j].value) : staticS();
+			const e = eNorm ? vec2Of(eNorm[j].value) : staticE();
+			const g = gNorm ? gNorm[j].value : staticG();
+			keys[j].value = buildStaticPaint(t, s, e, g, p);
+		}
+	} else {
+		const times = [...new Set(channels.flatMap((n) => n.map((kk) => kk.t)))].sort((a, b) => a - b);
+		const at = (norm, ft, fallback, read) => {
+			if (!norm) return fallback();
+			let v = norm[0].value;
+			for (const kk of norm) if (kk.t <= ft) v = kk.value;
+			else break;
+			return read(v);
+		};
+		keys = enforceMonotonic(times.map((ft) => ({
+			t: toSeconds(tm, ft),
+			value: buildStaticPaint(t, at(sNorm, ft, staticS, vec2Of), at(eNorm, ft, staticE, vec2Of), at(gNorm, ft, staticG, (v) => v), p)
+		})));
+	}
+	spec.fill = keys[0].value;
+	pushTrack(ctx, `${spec.id}/fill`, "paint", keys);
+}
 function pathSpecFor(ctx, style, geom, idBase, tm) {
 	const spec = {
 		kind: "path",
@@ -891,6 +1010,11 @@ function pathSpecFor(ctx, style, geom, idBase, tm) {
 		data: geom.kind === "static" ? geom.value : geom.keys[0].value
 	};
 	if (geom.kind === "animated") pushTrack(ctx, `${spec.id}/d`, "path", geom.keys.map((k) => ({ ...k })));
+	if (style.ty === "gf") {
+		applyGradientFill(ctx, spec, style, tm);
+		applyOpacity(ctx, spec, style.o, tm);
+		return spec;
+	}
 	const colorTarget = style.ty === "fl" ? "fill" : "stroke";
 	const cNorm = norms(style.c);
 	if (cNorm) {
@@ -948,7 +1072,7 @@ function denormItems(ctx, items, idBase, tm, where) {
 				source,
 				name: item.nm ?? `geo${geomCounter++}`
 			});
-		} else if (item.ty === "fl" || item.ty === "st") {
+		} else if (item.ty === "fl" || item.ty === "st" || item.ty === "gf") {
 			const preceding = geoms.filter((g) => g.index < i);
 			if (preceding.length === 0) continue;
 			const styleNodes = (hasMerge ? [{
@@ -1543,9 +1667,11 @@ function decimateLinearKeys(keys, relEps = .002) {
 * same discipline the importer uses for misaligned parametric geometry.
 *
 * SCOPE (MVP — mirror the importer's audit discipline: warn + drop, never
-* silent). IN: Group hierarchy, Rect/Circle/Path with a SOLID fill (+ optional
-* stroke), transform channels (position / position.x/.y split, opacity, scale,
-* rotation → identity degrees), animated `fill` color, animated `d` path
+* silent). IN: Group hierarchy, Rect/Circle/Path with a SOLID fill or a
+* LINEAR/RADIAL gradient `fill: paint` (→ Lottie `gf`; +optional stroke),
+* transform channels (position / position.x/.y split, opacity, scale,
+* rotation → identity degrees), animated `fill` color OR animated `fill: paint`
+* gradient (keyed g/s/e when directly invertible, else sampled), animated `d` path
 * (constant topology), and TEXT (ty:5): a Text node → a text layer with a font
 * reference (fonts.list) + a text-document keyframe stream (static = one doc;
 * animated text/fill/fontSize → doc keyframes sampled on the frame grid, held).
@@ -1564,8 +1690,9 @@ function decimateLinearKeys(keys, relEps = .002) {
 * 0.75, not the correct single 0.5). Same limitation the importer documents at
 * convert.ts:470-475. A correct-for-overlap precomp (ty:0 + assets) is a later phase.
 *
-* OUT (warned + dropped): Image/Video, gradient/mesh paint (solid only),
-* non-center anchors, text typewriter `reveal`/`revealFraction`, variable-font axes
+* OUT (warned + dropped): Image/Video, MESH paint (`gf` covers linear/radial only —
+* mesh has no Lottie ramp), gradient STROKE (`gs` — Path.stroke is a color string,
+* not a Paint), non-center anchors, text typewriter `reveal`/`revealFraction`, variable-font axes
 * (`fontAxes`/`fontVariationSettings` — no Lottie doc field), `box` valign
 * (baseline-approximated) and wrap `width` (the player self-reflows), TokenHighlight.
 * Animated primitive geometry (width/radius tracks) is SAMPLED, not channel-mapped.
@@ -2101,11 +2228,7 @@ function colorKeys(ctx, tr) {
 function buildFill(ctx, node, tracks) {
 	const tr = tracks.get("fill");
 	if (tr) {
-		if (tr.type !== "color") {
-			ctx.warn(`${describe(node)}: animated '${tr.type}' fill (gradient/mesh) is not exported — dropped`);
-			return;
-		}
-		return {
+		if (tr.type === "color") return {
 			ty: "fl",
 			c: {
 				a: 1,
@@ -2116,19 +2239,267 @@ function buildFill(ctx, node, tracks) {
 				k: 100
 			}
 		};
+		if (tr.type === "paint") return buildAnimatedGradientFill(ctx, node, tr);
+		ctx.warn(`${describe(node)}: animated '${tr.type}' fill is not exported — dropped`);
+		return;
 	}
 	const fill = node.fill();
-	if (typeof fill !== "string") {
-		ctx.warn(`${describe(node)}: a gradient/mesh fill is not exported (MVP: solid color) — dropped`);
-		return;
+	if (typeof fill === "string") {
+		if (fill === "") return void 0;
+		return {
+			ty: "fl",
+			c: {
+				a: 0,
+				k: colorToLottie(fill)
+			},
+			o: {
+				a: 0,
+				k: 100
+			}
+		};
 	}
-	if (fill === "") return void 0;
-	return {
+	if (fill.kind === "color") return {
 		ty: "fl",
 		c: {
 			a: 0,
-			k: colorToLottie(fill)
+			k: colorToLottie(fill.color)
+		},
+		o: {
+			a: 0,
+			k: 100
+		}
+	};
+	if (fill.kind === "mesh") {
+		ctx.warn(`${describe(node)}: a mesh fill has no Lottie gradient ramp (MVP: solid / linear / radial) — dropped`);
+		return;
+	}
+	warnGradientInterpolation(ctx, node, fill);
+	return gradientFillItem(fill, localBounds(node));
+}
+/** Local-space bounds of a shape's fill path — the gradient-geometry default source
+* (matches raster2d.resolveFill: linear ⇒ vertical bounds sweep, radial ⇒ centre +
+* half-diagonal). Rect/Circle draw centred at the origin; a Path bounds its anchors. */
+function localBounds(node) {
+	if (node instanceof Rect) {
+		const w = node.width() / 2;
+		const h = node.height() / 2;
+		return {
+			minX: -w,
+			minY: -h,
+			maxX: w,
+			maxY: h
+		};
+	}
+	if (node instanceof Circle) {
+		const r = node.radius();
+		return {
+			minX: -r,
+			minY: -r,
+			maxX: r,
+			maxY: r
+		};
+	}
+	let minX = Infinity;
+	let minY = Infinity;
+	let maxX = -Infinity;
+	let maxY = -Infinity;
+	for (const contour of node.data()) for (const [x, y] of contour.v) {
+		if (x < minX) minX = x;
+		if (y < minY) minY = y;
+		if (x > maxX) maxX = x;
+		if (y > maxY) maxY = y;
+	}
+	if (!Number.isFinite(minX)) return {
+		minX: 0,
+		minY: 0,
+		maxX: 0,
+		maxY: 0
+	};
+	return {
+		minX,
+		minY,
+		maxX,
+		maxY
+	};
+}
+/** gf start point (Lottie `s`) from a gradient's geometry, defaulting to bounds
+* exactly as raster2d.resolveFill does (linear: [centre-x, minY]; radial: centre). */
+function gradientStart(g, b) {
+	const cx = (b.minX + b.maxX) / 2;
+	if (g.kind === "linear") return g.from ? [g.from[0], g.from[1]] : [cx, b.minY];
+	const cy = (b.minY + b.maxY) / 2;
+	return g.center ? [g.center[0], g.center[1]] : [cx, cy];
+}
+/** gf end point (Lottie `e`): linear ⇒ `to`; radial ⇒ centre + [radius, 0], so the
+* Lottie radial extent (|s→e|) equals the glissade radius (half-diagonal default). */
+function gradientEnd(g, b) {
+	if (g.kind === "linear") {
+		const cx = (b.minX + b.maxX) / 2;
+		return g.to ? [g.to[0], g.to[1]] : [cx, b.maxY];
+	}
+	const [cx, cy] = gradientStart(g, b);
+	return [cx + (g.radius !== void 0 ? g.radius : Math.hypot(b.maxX - b.minX, b.maxY - b.minY) / 2), cy];
+}
+/** Flatten stops into the Lottie `g.k` array: `[offset,r,g,b, …]` (0–1 floats),
+* then `[offset,a, …]` alpha stops appended iff any stop is translucent. */
+function gradientStopArray(stops) {
+	const colors = [];
+	const alphas = [];
+	let anyAlpha = false;
+	for (const s of stops) {
+		const { r, g, b, a } = parseColor(s.color);
+		colors.push(s.offset, r / 255, g / 255, b / 255);
+		alphas.push(s.offset, a);
+		if (a < 1) anyAlpha = true;
+	}
+	return anyAlpha ? [...colors, ...alphas] : colors;
+}
+function warnGradientInterpolation(ctx, node, g) {
+	if (g.interpolation !== void 0 && g.interpolation !== "linear") ctx.warn(`${describe(node)}: '${g.interpolation}' gradient interpolation is emitted as a linear Lottie ramp (gf has no smooth/gaussian mode) — mid-stop banding may differ`);
+}
+/** A static linear/radial gradient → a `gf` shape item (geometry from `bounds`). */
+function gradientFillItem(g, bounds) {
+	const gk = {
+		p: g.stops.length,
+		k: {
+			a: 0,
+			k: gradientStopArray(g.stops)
+		}
+	};
+	const s = gradientStart(g, bounds);
+	const e = gradientEnd(g, bounds);
+	if (g.kind === "radial") return {
+		ty: "gf",
+		t: 2,
+		s: {
+			a: 0,
+			k: s
+		},
+		e: {
+			a: 0,
+			k: e
+		},
+		g: gk,
+		h: {
+			a: 0,
+			k: 0
+		},
+		a: {
+			a: 0,
+			k: 0
+		},
+		o: {
+			a: 0,
+			k: 100
+		}
+	};
+	return {
+		ty: "gf",
+		t: 1,
+		s: {
+			a: 0,
+			k: s
+		},
+		e: {
+			a: 0,
+			k: e
+		},
+		g: gk,
+		o: {
+			a: 0,
+			k: 100
+		}
+	};
+}
+/**
+* An animated `fill: paint` track → a `gf` with keyframed s/e/g channels. The
+* gradient KIND (linear/radial) is fixed to the first key's kind (Lottie can't
+* animate `t`); mesh/color first keys warn-drop. Directly-invertible tracks keep
+* their eases via emitKeys; anything else (named ease / spring / expr) samples on
+* the frame grid. A key whose kind/stop-count differs from the first would snap
+* under paintType anyway, so its geometry/ramp is read as best-effort.
+*/
+function buildAnimatedGradientFill(ctx, node, tr) {
+	const first = tr.keys[0].value;
+	if (first.kind === "mesh") {
+		ctx.warn(`${describe(node)}: an animated mesh fill has no Lottie gradient ramp — dropped`);
+		return;
+	}
+	if (first.kind === "color") {
+		ctx.warn(`${describe(node)}: an animated color-only paint fill is not exported (use a 'color' track) — dropped`);
+		return;
+	}
+	const kind = first.kind;
+	const bounds = localBounds(node);
+	const asGradient = (p) => p.kind === "linear" || p.kind === "radial" ? p : {
+		kind,
+		stops: [{
+			offset: 0,
+			color: "#000000"
+		}]
+	};
+	warnGradientInterpolation(ctx, node, first);
+	const p = first.stops.length;
+	const sMap = (v) => gradientStart(asGradient(v), bounds);
+	const eMap = (v) => gradientEnd(asGradient(v), bounds);
+	const gMap = (v) => gradientStopArray(asGradient(v).stops);
+	let sK;
+	let eK;
+	let gK;
+	if (isDirectlyInvertible(tr.keys, tr.expr)) {
+		sK = emitKeys(tr.keys, ctx.fr, sMap);
+		eK = emitKeys(tr.keys, ctx.fr, eMap);
+		gK = emitKeys(tr.keys, ctx.fr, gMap);
+	} else {
+		ctx.warn(`${describe(node)}: animated gradient fill is sampled at ${ctx.fr} fps (non-invertible ease)`);
+		sK = sampleToLottieKeys(tr, ctx.fr, ctx.ip, ctx.op, sMap);
+		eK = sampleToLottieKeys(tr, ctx.fr, ctx.ip, ctx.op, eMap);
+		gK = sampleToLottieKeys(tr, ctx.fr, ctx.ip, ctx.op, gMap);
+	}
+	const g = {
+		p,
+		k: {
+			a: 1,
+			k: gK
+		}
+	};
+	if (kind === "radial") return {
+		ty: "gf",
+		t: 2,
+		s: {
+			a: 1,
+			k: sK
+		},
+		e: {
+			a: 1,
+			k: eK
+		},
+		g,
+		h: {
+			a: 0,
+			k: 0
+		},
+		a: {
+			a: 0,
+			k: 0
+		},
+		o: {
+			a: 0,
+			k: 100
+		}
+	};
+	return {
+		ty: "gf",
+		t: 1,
+		s: {
+			a: 1,
+			k: sK
+		},
+		e: {
+			a: 1,
+			k: eK
 		},
+		g,
 		o: {
 			a: 0,
 			k: 100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/lottie",
-  "version": "0.50.0",
+  "version": "0.51.0-pre.1",
   "description": "glissade Lottie import (S1 MVP): pure .json (Lottie/bodymovin) → node specs + a v1 Timeline. Fail-fast feature audit; no DOM/Node dependencies.",
   "license": "Apache-2.0",
   "engines": {
@@ -18,11 +18,11 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.50.0",
-    "@glissade/scene": "0.50.0"
+    "@glissade/core": "0.51.0-pre.1",
+    "@glissade/scene": "0.51.0-pre.1"
   },
   "devDependencies": {
-    "@glissade/backend-skia": "0.50.0"
+    "@glissade/backend-skia": "0.51.0-pre.1"
   },
   "repository": {
     "type": "git",