@glissade/lottie 0.45.0 → 0.46.0

package/dist/index.d.ts

@@ -35,7 +35,19 @@ interface ImageSpec extends BaseSpec {
   width: number;
   height: number;
 }
-type NodeSpec = GroupSpec | PathSpec | RectSpec | ImageSpec;
+interface TextSpec extends BaseSpec {
+  kind: 'text';
+  text: string;
+  fill: string;
+  fontSize: number;
+  fontFamily: string;
+  fontWeight?: number;
+  fontStyle?: 'normal' | 'italic';
+  align?: 'left' | 'center' | 'right';
+  letterSpacing?: number;
+  lineHeight?: number;
+}
+type NodeSpec = GroupSpec | PathSpec | RectSpec | ImageSpec | TextSpec;
 interface LottieImportResult {
   size: {
     w: number;
@@ -125,6 +137,59 @@ interface LottieTransform {
   sk?: LottieProp;
   sa?: LottieProp;
 }
+/**
+ * A text document (`t.d.k[n].s`) — the paint + font state of a ty:5 text layer
+ * at one keyframe. Modern bodymovin: `fc` is a 0–1 rgb(a) array, `j` is the
+ * justification (0 left, 1 right, 2 center — the Lottie/bodymovin convention).
+ * Optional fields (`tr`/`lh`) are OMITTED when at their glissade default so the
+ * emitted JSON stays minimal + deterministic (mirrors fontSpec()'s omissions).
+ */
+interface LottieTextDocument {
+  /** the text string */
+  t: string;
+  /** font name — references a `fonts.list[n].fName` */
+  f: string;
+  /** font size (px) */
+  s: number;
+  /** fill color, 0–1 `[r,g,b]` or `[r,g,b,a]` */
+  fc: number[];
+  /** justification: 0 = left, 1 = right, 2 = center */
+  j: number;
+  /** tracking / letter-spacing (px) — omitted when unset */
+  tr?: number;
+  /** line height (px) — omitted when the glissade lineHeight is the 1.25 default */
+  lh?: number;
+  /** baseline shift — read-through only (never emitted) */
+  ls?: number;
+  /** wrap box size `[w,h]` — read-through only (never emitted) */
+  sz?: number[];
+  /** wrap box position `[x,y]` — read-through only */
+  ps?: number[];
+}
+/** One text-document keyframe: the document `s` applied from frame `t` (hold). */
+interface LottieTextDocKeyframe {
+  t: number;
+  s: LottieTextDocument;
+}
+/** ty:5 text data: keyframed documents (`d.k`) + animators (`a`, always empty here). */
+interface LottieTextData {
+  d: {
+    k: LottieTextDocKeyframe[];
+  };
+  a?: unknown[];
+  m?: unknown;
+  p?: unknown;
+}
+/** A `fonts.list[n]` entry — a font REFERENCE (never embedded; the player supplies it). */
+interface LottieFont {
+  fName: string;
+  fFamily: string;
+  fStyle: string;
+  fWeight?: string;
+  fPath?: string;
+  origin?: number;
+  ascent?: number;
+}
 interface LottieLayer {
   ty: number;
   nm?: string;
@@ -141,6 +206,8 @@ interface LottieLayer {
   ao?: number;
   /** shape layer */
   shapes?: LottieShapeItem[];
+  /** text layer (ty:5) */
+  t?: LottieTextData;
   /** solid */
   sw?: number;
   sh?: number;
@@ -181,6 +248,10 @@ interface LottieDocument {
   ddd?: number;
   layers: LottieLayer[];
   assets?: LottieAsset[];
+  /** Font references (ty:5 layers name into `fonts.list[n].fName`). */
+  fonts?: {
+    list: LottieFont[];
+  };
 }
 //#endregion
 //#region src/pathvalue.d.ts
@@ -234,4 +305,4 @@ interface ImportOptions {
 }
 declare function importLottie(json: unknown, opts?: ImportOptions): LottieImportResult;
 //#endregion
-export { type CodegenOptions, type ExportOptions, type GroupSpec, type ImageSpec, ImportOptions, KAPPA, type LottieDocument, LottieImportError, type LottieImportResult, type NodeSpec, type PathSpec, type RectSpec, buildNode, buildNodes, colorPropIsBytes, ellipseContour, exportLottie, generateSceneModule, importLottie, lottieColor, mergeContours, rectContour, reverseContour, shToContour };
+export { type CodegenOptions, type ExportOptions, type GroupSpec, type ImageSpec, ImportOptions, KAPPA, type LottieDocument, LottieImportError, type LottieImportResult, type NodeSpec, type PathSpec, type RectSpec, type TextSpec, buildNode, buildNodes, colorPropIsBytes, ellipseContour, exportLottie, generateSceneModule, importLottie, lottieColor, mergeContours, rectContour, reverseContour, shToContour };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Circle, Group, ImageNode, Path, Rect, createScene } from "@glissade/scene";
+import { Circle, Group, ImageNode, Path, Rect, Text, createScene } from "@glissade/scene";
 import { cubicBezier, formatColor, parseColor, sampleTrack, track } from "@glissade/core";
 import "@glissade/core/expr";
 //#region src/spec.ts
@@ -250,7 +250,8 @@ const SUPPORTED_LAYER_TYPES = new Set([
 	1,
 	2,
 	3,
-	4
+	4,
+	5
 ]);
 function reject(ctx, errorClass, detail) {
 	ctx.problems.push(`[${errorClass}] ${detail}`);
@@ -369,8 +370,23 @@ function auditLayer(ctx, layer, index, doc) {
 		const asset = (doc.assets ?? []).find((a) => a.id === layer.refId);
 		if (!asset || typeof asset.p !== "string") reject(ctx, "invalid-asset", `image ${where} references missing asset '${layer.refId ?? ""}'`);
 	}
+	if (layer.ty === 5) auditTextLayer(ctx, layer, where);
 	if (layer.shapes) auditShapeItems(ctx, layer.shapes, where);
 }
+/**
+* Text layers (ty:5) import a static-or-doc-keyframed document; the range-selector
+* ANIMATOR list (`t.a`) has no glissade analogue, so a non-empty one is rejected —
+* loud, not silent (§1). A malformed / missing document is an invalid document.
+*/
+function auditTextLayer(ctx, layer, where) {
+	const t = layer.t;
+	const keys = t?.d?.k;
+	if (!Array.isArray(keys) || keys.length === 0 || typeof keys[0]?.s?.t !== "string") {
+		reject(ctx, "invalid-text", `${where}: text layer has no readable document (t.d.k[0].s.t)`);
+		return;
+	}
+	if (Array.isArray(t?.a) && t.a.length > 0) reject(ctx, "unsupported-text-animator", `${where}: text range-selector animators (t.a) are not supported`);
+}
 /** Throws LottieImportError listing EVERY rejection; returns collected warnings. */
 function auditDocument(doc, allowDegraded) {
 	const ctx = {
@@ -422,6 +438,18 @@ function buildNode(spec) {
 			width: spec.width,
 			height: spec.height
 		});
+		case "text": return new Text({
+			...base,
+			text: spec.text,
+			fill: spec.fill,
+			fontSize: spec.fontSize,
+			fontFamily: spec.fontFamily,
+			...spec.fontWeight !== void 0 ? { fontWeight: spec.fontWeight } : {},
+			...spec.fontStyle !== void 0 ? { fontStyle: spec.fontStyle } : {},
+			...spec.align !== void 0 ? { align: spec.align } : {},
+			...spec.letterSpacing !== void 0 ? { letterSpacing: spec.letterSpacing } : {},
+			...spec.lineHeight !== void 0 ? { lineHeight: spec.lineHeight } : {}
+		});
 	}
 }
 function buildNodes(specs) {
@@ -941,6 +969,80 @@ function denormItems(ctx, items, idBase, tm, where) {
 	}
 	return out;
 }
+/** OTF/bodymovin weight-class names → numeric weight, the inverse of the exporter's map. */
+const WEIGHT_BY_NAME = {
+	Thin: 100,
+	ExtraLight: 200,
+	Light: 300,
+	Regular: 400,
+	Medium: 500,
+	SemiBold: 600,
+	Bold: 700,
+	ExtraBold: 800,
+	Black: 900
+};
+/** Numeric weight from a font ref: prefer `fWeight`, else read a class name out of `fStyle`. */
+function fontWeightFrom(font) {
+	if (font === void 0) return void 0;
+	if (font.fWeight !== void 0) {
+		const n = Number(font.fWeight);
+		if (Number.isFinite(n)) return n;
+	}
+	for (const word of font.fStyle.split(" ")) if (WEIGHT_BY_NAME[word] !== void 0) return WEIGHT_BY_NAME[word];
+}
+/** Justification (0 left / 1 right / 2 center) → glissade align. */
+const justificationToAlign = (j) => j === 1 ? "right" : j === 2 ? "center" : "left";
+/**
+* A varying text-document field → a HOLD track (the document switches discretely
+* between keyframes). Consecutive-equal values collapse; a field constant across
+* the whole stream produces no track (the static base value on the spec suffices).
+*/
+function pushDocTrack(ctx, target, type, dks, tm, extract) {
+	const keys = [];
+	let prev;
+	for (const dk of dks) {
+		const value = extract(dk.s);
+		const sig = JSON.stringify(value);
+		if (sig === prev) continue;
+		const k = {
+			t: toSeconds(tm, dk.t),
+			value
+		};
+		if (keys.length > 0) k.interp = "hold";
+		keys.push(k);
+		prev = sig;
+	}
+	if (keys.length <= 1) return;
+	ctx.tracks.push(track(target, type, enforceMonotonic(keys)));
+}
+/** ty:5 layer → a Text spec (+ hold tracks for any animated text/fill/fontSize). */
+function convertTextLayer(ctx, layer, base, tm) {
+	const dks = layer.t.d.k;
+	const first = dks[0].s;
+	const font = (ctx.doc.fonts?.list ?? []).find((f) => f.fName === first.f);
+	const spec = {
+		kind: "text",
+		id: uid(ctx, `${base}__text`),
+		text: first.t,
+		fill: lottieColor(first.fc, colorPropIsBytes([first.fc])),
+		fontSize: first.s,
+		fontFamily: font?.fFamily ?? first.f
+	};
+	const weight = fontWeightFrom(font);
+	if (weight !== void 0) spec.fontWeight = weight;
+	if (font !== void 0 && /italic/i.test(font.fStyle)) spec.fontStyle = "italic";
+	const align = justificationToAlign(first.j);
+	if (align !== "left") spec.align = align;
+	if (first.tr !== void 0) spec.letterSpacing = first.tr;
+	if (first.lh !== void 0 && first.s > 0) spec.lineHeight = first.lh / first.s;
+	if (dks.length > 1) {
+		pushDocTrack(ctx, `${spec.id}/text`, "string", dks, tm, (s) => s.t);
+		pushDocTrack(ctx, `${spec.id}/fontSize`, "number", dks, tm, (s) => s.s);
+		const bytes = colorPropIsBytes(dks.map((k) => k.s.fc));
+		pushDocTrack(ctx, `${spec.id}/fill`, "color", dks, tm, (s) => lottieColor(s.fc, bytes));
+	}
+	return spec;
+}
 function visibilityWrapper(ctx, base, layer, content, ind) {
 	const { doc } = ctx;
 	const docDur = (doc.op - doc.ip) / doc.fr;
@@ -1026,7 +1128,7 @@ function convertLayer(ctx, layer, index) {
 			position: [w / 2, h / 2]
 		};
 		contentChildren.push(image);
-	}
+	} else if (layer.ty === 5 && layer.t) contentChildren.push(convertTextLayer(ctx, layer, base, tm));
 	if (layer.ty !== 3 && layer.hd !== true) {
 		const content = {
 			kind: "group",
@@ -1084,7 +1186,8 @@ const CTOR = {
 	group: "Group",
 	path: "Path",
 	rect: "Rect",
-	image: "ImageNode"
+	image: "ImageNode",
+	text: "Text"
 };
 function lit(value, indent) {
 	return JSON.stringify(value, null, 2).split("\n").join(`\n${indent}`);
@@ -1117,6 +1220,14 @@ function emitNode(spec, indent) {
 		case "image":
 			props.push(`assetId: ${JSON.stringify(spec.assetId)}`, `width: ${spec.width}`, `height: ${spec.height}`);
 			break;
+		case "text":
+			props.push(`text: ${JSON.stringify(spec.text)}`, `fill: ${JSON.stringify(spec.fill)}`, `fontSize: ${spec.fontSize}`, `fontFamily: ${JSON.stringify(spec.fontFamily)}`);
+			if (spec.fontWeight !== void 0) props.push(`fontWeight: ${spec.fontWeight}`);
+			if (spec.fontStyle !== void 0) props.push(`fontStyle: ${JSON.stringify(spec.fontStyle)}`);
+			if (spec.align !== void 0) props.push(`align: ${JSON.stringify(spec.align)}`);
+			if (spec.letterSpacing !== void 0) props.push(`letterSpacing: ${spec.letterSpacing}`);
+			if (spec.lineHeight !== void 0) props.push(`lineHeight: ${spec.lineHeight}`);
+			break;
 	}
 	return `new ${CTOR[spec.kind]}({\n${props.map((p) => `${inner}${p},`).join("\n")}\n${indent}})`;
 }
@@ -1386,10 +1497,15 @@ function decimateLinearKeys(keys, relEps = .002) {
 * 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
-* (constant topology). OUT (warned + dropped): Text, Image/Video, gradient/mesh
-* paint (solid only), non-center anchors, group opacity compositing (Lottie
-* parenting never inherits opacity). Animated primitive geometry (width/radius
-* tracks) is SAMPLED, not channel-mapped.
+* (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).
+* OUT (warned + dropped): Image/Video, gradient/mesh paint (solid only),
+* non-center anchors, group opacity compositing (Lottie parenting never inherits
+* opacity), 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.
 */
 const EMPTY_TRACKS = /* @__PURE__ */ new Map();
 /** Convert a SceneModule to a Lottie document. Pure over (scene, timeline). */
@@ -1419,9 +1535,11 @@ function exportLottie(mod, opts) {
 		op,
 		warn,
 		layers: [],
-		ind: 0
+		ind: 0,
+		fonts: /* @__PURE__ */ new Map()
 	};
 	walkChildren(ctx, scene.root.children, void 0, byNode);
+	const fonts = [...ctx.fonts.values()];
 	return {
 		v: BODYMOVIN_VERSION,
 		fr,
@@ -1430,7 +1548,8 @@ function exportLottie(mod, opts) {
 		w: opts.width,
 		h: opts.height,
 		nm: "glissade export",
-		layers: ctx.layers
+		layers: ctx.layers,
+		...fonts.length > 0 ? { fonts: { list: fonts } } : {}
 	};
 }
 /**
@@ -1466,12 +1585,12 @@ function walkChildren(ctx, children, parentInd, byNode) {
 		const node = children[i];
 		const kind = classify(node);
 		if (kind === "drop") {
-			ctx.warn(`${describe(node)} is not exportable (MVP: Group / Rect / Circle / Path) — dropped`);
+			ctx.warn(`${describe(node)} is not exportable (MVP: Group / Rect / Circle / Path / Text) — dropped`);
 			continue;
 		}
 		const myInd = ++ctx.ind;
 		const tracks = (node.id !== void 0 ? byNode.get(node.id) : void 0) ?? EMPTY_TRACKS;
-		ctx.layers.push(kind === "group" ? buildNullLayer(ctx, node, myInd, parentInd, tracks) : buildShapeLayer(ctx, node, kind, myInd, parentInd, tracks));
+		ctx.layers.push(kind === "group" ? buildNullLayer(ctx, node, myInd, parentInd, tracks) : kind === "text" ? buildTextLayer(ctx, node, myInd, parentInd, tracks) : buildShapeLayer(ctx, node, kind, myInd, parentInd, tracks));
 		if (node instanceof Group) walkChildren(ctx, node.children, myInd, byNode);
 	}
 }
@@ -1479,6 +1598,7 @@ function classify(node) {
 	if (node instanceof Rect) return "rect";
 	if (node instanceof Circle) return "circle";
 	if (node instanceof Path) return "path";
+	if (node instanceof Text) return "text";
 	if (node instanceof Group) return "group";
 	return "drop";
 }
@@ -1625,6 +1745,133 @@ function buildShapeLayer(ctx, node, kind, ind, parentInd, tracks) {
 		...parentInd !== void 0 ? { parent: parentInd } : {}
 	};
 }
+/** Human weight-class names (400 = Regular), the OTF/bodymovin `fStyle` convention. */
+const WEIGHT_NAMES = {
+	100: "Thin",
+	200: "ExtraLight",
+	300: "Light",
+	400: "Regular",
+	500: "Medium",
+	600: "SemiBold",
+	700: "Bold",
+	800: "ExtraBold",
+	900: "Black"
+};
+/** `fStyle` from weight + italic — e.g. 700 + italic → 'Bold Italic', 400 → 'Regular'. */
+function fontStyleName(weight, italic) {
+	const name = WEIGHT_NAMES[weight] ?? String(weight);
+	if (name === "Regular") return italic ? "Italic" : "Regular";
+	return italic ? `${name} Italic` : name;
+}
+/**
+* Register (family, weight, style) once, returning the stable `fName` the text
+* document references. De-dupe is keyed on the derived fName, so two Text nodes
+* sharing a face share one `fonts.list` entry (pure + insertion-ordered). Fonts
+* are referenced by name only — never embedded; the player supplies the face
+* (the §3.6 registry papercut).
+*/
+function registerFont(ctx, node) {
+	const italic = node.fontStyle === "italic";
+	const fStyle = fontStyleName(node.fontWeight, italic);
+	const fName = `${node.fontFamily}-${fStyle.replace(/ /g, "")}`;
+	if (!ctx.fonts.has(fName)) ctx.fonts.set(fName, {
+		fName,
+		fFamily: node.fontFamily,
+		fStyle,
+		fWeight: String(node.fontWeight)
+	});
+	return fName;
+}
+/** Justification: glissade align → the Lottie/bodymovin `j` (0 left, 1 right, 2 center). */
+function alignToJustification(align) {
+	return align === "left" ? 0 : align === "right" ? 1 : 2;
+}
+/** The text document at time `t`, sampling the animatable text/fill/fontSize props. */
+function textDocAt(node, fName, tracks, t) {
+	const text = sampleStr(tracks, "text", node.text(), t);
+	const fill = sampleColor(tracks, "fill", node.fill(), t);
+	const size = sampleNum(tracks, "fontSize", node.fontSize(), t);
+	return {
+		t: text,
+		f: fName,
+		s: size,
+		fc: colorToLottie(fill),
+		j: alignToJustification(node.align),
+		...node.letterSpacing !== void 0 ? { tr: node.letterSpacing } : {},
+		...node.lineHeight !== 1.25 ? { lh: size * node.lineHeight } : {}
+	};
+}
+const sampleStr = (tracks, prop, staticVal, t) => {
+	const tr = tracks.get(prop);
+	return tr ? sampleTrack(tr, t) : staticVal;
+};
+const sampleNum = (tracks, prop, staticVal, t) => {
+	const tr = tracks.get(prop);
+	return tr ? sampleTrack(tr, t) : staticVal;
+};
+const sampleColor = (tracks, prop, staticVal, t) => {
+	const tr = tracks.get(prop);
+	return tr && tr.type === "color" ? sampleTrack(tr, t) : staticVal;
+};
+/**
+* The text-document keyframe stream. STATIC (no text/fill/fontSize track) = one
+* document at t=0. ANIMATED = one document per frame across the animated span,
+* SAMPLED and held (a Lottie text document switches discretely — smooth fill/size
+* animation degrades to a per-frame step, the honest MVP limit). Consecutive
+* identical documents collapse to their first frame so a constant prop stays lean.
+*/
+function buildTextDocKeyframes(ctx, node, fName, tracks) {
+	const docProps = [
+		"text",
+		"fill",
+		"fontSize"
+	];
+	if (!docProps.some((p) => tracks.has(p))) return [{
+		t: ctx.ip,
+		s: textDocAt(node, fName, tracks, ctx.ip / ctx.fr)
+	}];
+	ctx.warn(`${describe(node)}: animated text/fill/fontSize is sampled at ${ctx.fr} fps into stepped text documents (not smoothly interpolated)`);
+	const [f0, f1] = frameSpan(ctx, docProps.map((p) => tracks.get(p)));
+	const keys = [];
+	let prev;
+	for (let f = f0; f <= f1; f++) {
+		const s = textDocAt(node, fName, tracks, f / ctx.fr);
+		const sig = JSON.stringify(s);
+		if (sig === prev) continue;
+		keys.push({
+			t: f,
+			s
+		});
+		prev = sig;
+	}
+	return keys;
+}
+/** Warn (never silent) on the text features this MVP cannot represent, then drop them. */
+function warnTextUnsupported(ctx, node, tracks) {
+	if (tracks.has("reveal") || Number.isFinite(node.reveal())) ctx.warn(`${describe(node)}: typewriter 'reveal' is not exported (Lottie range selectors are a later phase) — dropped, full text shown`);
+	if (tracks.has("revealFraction") || !Number.isNaN(node.revealFraction())) ctx.warn(`${describe(node)}: 'revealFraction' is not exported — dropped, full text shown`);
+	if (tracks.has("fontAxes") || Object.keys(node.fontAxes()).length > 0 || node.fontVariationSettings !== void 0) ctx.warn(`${describe(node)}: variable-font axes (fontAxes/fontVariationSettings) have no Lottie text-document field — dropped`);
+	if (node.box !== void 0) ctx.warn(`${describe(node)}: box valign is approximated as baseline-anchored (no Lottie ink-box anchor) — vertical placement may shift`);
+	if (tracks.has("width") || node.width() > 0) ctx.warn(`${describe(node)}: wrap 'width' relies on the player's own line reflow — wrapping may diverge from glissade's`);
+}
+function buildTextLayer(ctx, node, ind, parentInd, tracks) {
+	const fName = registerFont(ctx, node);
+	warnTextUnsupported(ctx, node, tracks);
+	const t = {
+		d: { k: buildTextDocKeyframes(ctx, node, fName, tracks) },
+		a: []
+	};
+	return {
+		ty: 5,
+		nm: node.id ?? `text${ind}`,
+		ind,
+		ip: ctx.ip,
+		op: ctx.op,
+		ks: buildTransform(ctx, node, tracks),
+		t,
+		...parentInd !== void 0 ? { parent: parentInd } : {}
+	};
+}
 function buildGeometry(ctx, node, kind, tracks) {
 	if (kind === "path") return buildPathGeometry(ctx, node, tracks);
 	const paramNames = kind === "rect" ? [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/lottie",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "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.45.0",
-    "@glissade/scene": "0.45.0"
+    "@glissade/core": "0.46.0",
+    "@glissade/scene": "0.46.0"
   },
   "devDependencies": {
-    "@glissade/backend-skia": "0.45.0"
+    "@glissade/backend-skia": "0.46.0"
   },
   "repository": {
     "type": "git",