@glissade/core 0.8.1 → 0.9.0-pre.1

package/dist/sidecar.js

@@ -0,0 +1,1269 @@
+//#region src/color.ts
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB_RE = /^rgba?\(\s*([\d.]+)\s*[, ]\s*([\d.]+)\s*[, ]\s*([\d.]+)\s*(?:[,/]\s*([\d.]+%?)\s*)?\)$/i;
+var ColorParseError = class extends Error {
+	constructor(input) {
+		super(`cannot parse color '${input}' (supported: #rgb[a], #rrggbb[aa], rgb()/rgba())`);
+		this.name = "ColorParseError";
+	}
+};
+function parseColor(input) {
+	const hex = HEX_RE.exec(input);
+	if (hex) {
+		let h = hex[1];
+		if (h.length <= 4) h = [...h].map((c) => c + c).join("");
+		const n = parseInt(h, 16);
+		if (h.length === 6) return {
+			r: n >> 16,
+			g: n >> 8 & 255,
+			b: n & 255,
+			a: 1
+		};
+		return {
+			r: n >>> 24 & 255,
+			g: n >>> 16 & 255,
+			b: n >>> 8 & 255,
+			a: (n & 255) / 255
+		};
+	}
+	const rgb = RGB_RE.exec(input);
+	if (rgb) {
+		const alphaRaw = rgb[4];
+		const a = alphaRaw === void 0 ? 1 : alphaRaw.endsWith("%") ? parseFloat(alphaRaw) / 100 : parseFloat(alphaRaw);
+		return {
+			r: parseFloat(rgb[1]),
+			g: parseFloat(rgb[2]),
+			b: parseFloat(rgb[3]),
+			a
+		};
+	}
+	throw new ColorParseError(input);
+}
+function formatColor(c) {
+	const clampByte = (v) => Math.min(255, Math.max(0, Math.round(v)));
+	const hex = (v) => clampByte(v).toString(16).padStart(2, "0");
+	const base = `#${hex(c.r)}${hex(c.g)}${hex(c.b)}`;
+	const a = Math.min(1, Math.max(0, c.a));
+	return a >= 1 ? base : `${base}${hex(a * 255)}`;
+}
+function srgbToLinear(c) {
+	const v = c / 255;
+	return v <= .04045 ? v / 12.92 : ((v + .055) / 1.055) ** 2.4;
+}
+function linearToSrgb(v) {
+	return (v <= .0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - .055) * 255;
+}
+function rgbaToOklab(c) {
+	const r = srgbToLinear(c.r);
+	const g = srgbToLinear(c.g);
+	const b = srgbToLinear(c.b);
+	const l = Math.cbrt(.4122214708 * r + .5363325363 * g + .0514459929 * b);
+	const m = Math.cbrt(.2119034982 * r + .6806995451 * g + .1073969566 * b);
+	const s = Math.cbrt(.0883024619 * r + .2817188376 * g + .6299787005 * b);
+	return {
+		L: .2104542553 * l + .793617785 * m - .0040720468 * s,
+		a: 1.9779984951 * l - 2.428592205 * m + .4505937099 * s,
+		b: .0259040371 * l + .7827717662 * m - .808675766 * s,
+		alpha: c.a
+	};
+}
+function oklabToRgba(c) {
+	const l = (c.L + .3963377774 * c.a + .2158037573 * c.b) ** 3;
+	const m = (c.L - .1055613458 * c.a - .0638541728 * c.b) ** 3;
+	const s = (c.L - .0894841775 * c.a - 1.291485548 * c.b) ** 3;
+	return {
+		r: linearToSrgb(4.0767416621 * l - 3.3077115913 * m + .2309699292 * s),
+		g: linearToSrgb(-1.2684380046 * l + 2.6097574011 * m - .3413193965 * s),
+		b: linearToSrgb(-.0041960863 * l - .7034186147 * m + 1.707614701 * s),
+		a: c.alpha
+	};
+}
+/** Interpolate two CSS color strings in OKLab; t may extrapolate. */
+function lerpColor(from, to, t) {
+	const a = rgbaToOklab(parseColor(from));
+	const b = rgbaToOklab(parseColor(to));
+	const mix = (x, y) => x + (y - x) * t;
+	return formatColor(oklabToRgba({
+		L: mix(a.L, b.L),
+		a: mix(a.a, b.a),
+		b: mix(a.b, b.b),
+		alpha: mix(a.alpha, b.alpha)
+	}));
+}
+//#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).
+* `extrapolates` declares whether a type's lerp accepts easedT outside [0,1]
+* (spring overshoot); non-extrapolating types clamp.
+*/
+const registry = /* @__PURE__ */ new Map();
+function registerValueType(vt) {
+	registry.set(vt.id, vt);
+}
+var UnknownValueTypeError = class extends Error {
+	constructor(id) {
+		super(`unknown value type '${id}'; register it via registerValueType()`);
+		this.name = "UnknownValueTypeError";
+	}
+};
+function getValueType(id) {
+	const vt = registry.get(id);
+	if (!vt) throw new UnknownValueTypeError(id);
+	return vt;
+}
+const numberType = {
+	id: "number",
+	lerp: (a, b, t) => a + (b - a) * t,
+	extrapolates: true,
+	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,
+	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"
+};
+/** vec2 swept along a circular arc: polar lerp of radius + shortest-path angle (§2.2). */
+const vec2ArcType = {
+	id: "vec2-arc",
+	lerp: (a, b, t) => {
+		const ra = Math.hypot(a[0], a[1]);
+		const rb = Math.hypot(b[0], b[1]);
+		const angA = Math.atan2(a[1], a[0]);
+		let dAng = Math.atan2(b[1], b[0]) - angA;
+		while (dAng > Math.PI) dAng -= 2 * Math.PI;
+		while (dAng < -Math.PI) dAng += 2 * Math.PI;
+		const r = ra + (rb - ra) * t;
+		const ang = angA + dAng * t;
+		return [r * Math.cos(ang), r * Math.sin(ang)];
+	},
+	extrapolates: true,
+	equals: vec2Equals,
+	defaultHandoff: "blend-from-frozen"
+};
+const colorType = {
+	id: "color",
+	lerp: lerpColor,
+	extrapolates: true,
+	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) {
+	return {
+		id,
+		lerp: (a, b, t) => t >= 1 ? b : a,
+		extrapolates: false,
+		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";
+	} catch {
+		return "string";
+	}
+	throw new ValueTypeInferenceError(value);
+}
+registerValueType(numberType);
+registerValueType(vec2Type);
+registerValueType(vec2ArcType);
+registerValueType(colorType);
+registerValueType(stringType);
+registerValueType(booleanType);
+registerValueType(pathType);
+//#endregion
+//#region src/easing.ts
+const c1 = 1.70158;
+const c2 = c1 * 1.525;
+const c3 = 2.70158;
+const c4 = 2 * Math.PI / 3;
+const c5 = 2 * Math.PI / 4.5;
+function bounceOut(t) {
+	const n1 = 7.5625;
+	const d1 = 2.75;
+	if (t < 1 / d1) return n1 * t * t;
+	if (t < 2 / d1) return n1 * (t -= 1.5 / d1) * t + .75;
+	if (t < 2.5 / d1) return n1 * (t -= 2.25 / d1) * t + .9375;
+	return n1 * (t -= 2.625 / d1) * t + .984375;
+}
+const easings = {
+	linear: (t) => t,
+	easeInQuad: (t) => t * t,
+	easeOutQuad: (t) => 1 - (1 - t) * (1 - t),
+	easeInOutQuad: (t) => t < .5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2,
+	easeInCubic: (t) => t ** 3,
+	easeOutCubic: (t) => 1 - (1 - t) ** 3,
+	easeInOutCubic: (t) => t < .5 ? 4 * t ** 3 : 1 - (-2 * t + 2) ** 3 / 2,
+	easeInQuart: (t) => t ** 4,
+	easeOutQuart: (t) => 1 - (1 - t) ** 4,
+	easeInOutQuart: (t) => t < .5 ? 8 * t ** 4 : 1 - (-2 * t + 2) ** 4 / 2,
+	easeInQuint: (t) => t ** 5,
+	easeOutQuint: (t) => 1 - (1 - t) ** 5,
+	easeInOutQuint: (t) => t < .5 ? 16 * t ** 5 : 1 - (-2 * t + 2) ** 5 / 2,
+	easeInSine: (t) => 1 - Math.cos(t * Math.PI / 2),
+	easeOutSine: (t) => Math.sin(t * Math.PI / 2),
+	easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+	easeInExpo: (t) => t === 0 ? 0 : 2 ** (10 * t - 10),
+	easeOutExpo: (t) => t === 1 ? 1 : 1 - 2 ** (-10 * t),
+	easeInOutExpo: (t) => t === 0 ? 0 : t === 1 ? 1 : t < .5 ? 2 ** (20 * t - 10) / 2 : (2 - 2 ** (-20 * t + 10)) / 2,
+	easeInCirc: (t) => 1 - Math.sqrt(1 - t * t),
+	easeOutCirc: (t) => Math.sqrt(1 - (t - 1) * (t - 1)),
+	easeInOutCirc: (t) => t < .5 ? (1 - Math.sqrt(1 - (2 * t) ** 2)) / 2 : (Math.sqrt(1 - (-2 * t + 2) ** 2) + 1) / 2,
+	easeInBack: (t) => c3 * t ** 3 - c1 * t * t,
+	easeOutBack: (t) => 1 + c3 * (t - 1) ** 3 + c1 * (t - 1) ** 2,
+	easeInOutBack: (t) => t < .5 ? (2 * t) ** 2 * (3.5949095 * 2 * t - c2) / 2 : ((2 * t - 2) ** 2 * (3.5949095 * (t * 2 - 2) + c2) + 2) / 2,
+	easeInElastic: (t) => t === 0 ? 0 : t === 1 ? 1 : -(2 ** (10 * t - 10)) * Math.sin((t * 10 - 10.75) * c4),
+	easeOutElastic: (t) => t === 0 ? 0 : t === 1 ? 1 : 2 ** (-10 * t) * Math.sin((t * 10 - .75) * c4) + 1,
+	easeInOutElastic: (t) => t === 0 ? 0 : t === 1 ? 1 : t < .5 ? -(2 ** (20 * t - 10) * Math.sin((20 * t - 11.125) * c5)) / 2 : 2 ** (-20 * t + 10) * Math.sin((20 * t - 11.125) * c5) / 2 + 1,
+	easeInBounce: (t) => 1 - bounceOut(1 - t),
+	easeOutBounce: bounceOut,
+	easeInOutBounce: (t) => t < .5 ? (1 - bounceOut(1 - 2 * t)) / 2 : (1 + bounceOut(2 * t - 1)) / 2
+};
+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;
+/**
+* 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.
+*/
+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;
+	const ay = 3 * p1y - 3 * p2y + 1;
+	const by = 3 * p2y - 6 * p1y;
+	const cy = 3 * p1y;
+	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++) {
+			const err = sampleX(u) - x;
+			if (Math.abs(err) < 1e-7) return u;
+			const d = sampleDX(u);
+			if (Math.abs(d) < 1e-6) break;
+			u -= err / d;
+		}
+		let lo = 0;
+		let hi = 1;
+		u = x;
+		while (hi - lo > 1e-7) {
+			if (sampleX(u) < x) lo = u;
+			else hi = u;
+			u = (lo + hi) / 2;
+		}
+		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 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 {
+	constructor(name) {
+		super(`unknown easing '${name}'; register it via easings or use cubicBezier/spring`);
+		this.name = "UnknownEasingError";
+	}
+};
+function namedEasing(name) {
+	const fn = easings[name];
+	if (!fn) throw new UnknownEasingError(name);
+	return fn;
+}
+//#endregion
+//#region src/spring.ts
+const DEFAULT_SETTLE_TOLERANCE = .005;
+function params(cfg) {
+	const mass = cfg.mass ?? 1;
+	if (!(cfg.stiffness > 0) || !(cfg.damping > 0) || !(mass > 0)) throw new RangeError("spring stiffness, damping, and mass must all be > 0");
+	return {
+		w0: Math.sqrt(cfg.stiffness / mass),
+		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;
+	const { w0, zeta } = params(cfg);
+	if (Math.abs(zeta - 1) < 1e-9) return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+	if (zeta < 1) {
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		return 1 - Math.exp(-zeta * w0 * t) * (Math.cos(wd * t) + zeta * w0 / wd * Math.sin(wd * t));
+	}
+	const s = Math.sqrt(zeta * zeta - 1);
+	const r1 = -w0 * (zeta - s);
+	const r2 = -w0 * (zeta + s);
+	return 1 + (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r1 - r2);
+}
+/**
+* Settle duration: the earliest time after which |x - 1| stays within
+* settleTolerance. Closed-form via the decay envelope for the underdamped
+* case; bisection on the monotone tail otherwise. Deterministic.
+*/
+function duration(cfg, opts) {
+	const tol = opts?.settleTolerance ?? DEFAULT_SETTLE_TOLERANCE;
+	const { w0, zeta } = params(cfg);
+	if (zeta < 1) {
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		const amp = Math.sqrt(1 + (zeta * w0 / wd) ** 2);
+		return Math.log(amp / tol) / (zeta * w0);
+	}
+	let hi = 1 / w0;
+	while (1 - rawValue(cfg, hi) > tol) hi *= 2;
+	let lo = 0;
+	for (let i = 0; i < 64 && hi - lo > 1e-9; i++) {
+		const mid = (lo + hi) / 2;
+		if (1 - rawValue(cfg, mid) > tol) lo = mid;
+		else hi = mid;
+	}
+	return hi;
+}
+/**
+* Spring progress at local time t, affinely rescaled so value(duration) = 1
+* exactly — the raw form only approaches 1, and an unscaled curve would snap
+* at the key (§2.7 "endpoint continuity"). May exceed 1 (overshoot).
+*/
+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 {
+		kind: "spring",
+		stiffness: cfg.stiffness,
+		damping: cfg.damping,
+		mass: cfg.mass ?? 1
+	};
+}, {
+	duration,
+	value,
+	retarget
+});
+/**
+* Named spring feels (react-spring conventions, mass 1) — a vocabulary instead
+* of hand-tuned stiffness/damping. Use `spring(springPresets.wobbly)` or
+* `springTo(t, a, b, springPresets.gentle)`.
+*/
+const springPresets = {
+	default: {
+		stiffness: 170,
+		damping: 26
+	},
+	gentle: {
+		stiffness: 120,
+		damping: 14
+	},
+	wobbly: {
+		stiffness: 180,
+		damping: 12
+	},
+	stiff: {
+		stiffness: 210,
+		damping: 20
+	},
+	slow: {
+		stiffness: 280,
+		damping: 60
+	},
+	molasses: {
+		stiffness: 280,
+		damping: 120
+	}
+};
+/**
+* The spring as a normalized easing over a segment whose length must equal
+* spring.duration(cfg) (validated at the document layer, §2.7).
+*/
+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
+/**
+* Track & keyframe model (DESIGN.md §2.2) and sampling (§2.4): binary search
+* per track with a last-segment cursor — sanctioned memoization, semantics
+* identical to a cold search (property-tested).
+*/
+var TrackValidationError = class extends Error {
+	constructor(target, message) {
+		super(`track '${target}': ${message}`);
+		this.name = "TrackValidationError";
+	}
+};
+function validateTrack(track) {
+	const vt = getValueType(track.type);
+	if (track.keys.length === 0) throw new TrackValidationError(track.target, "must have at least one key");
+	if (vt.defaultHandoff === "cut") {
+		for (const k of track.keys) if (k.interp !== "hold") k.interp = "hold";
+	}
+	for (let i = 1; i < track.keys.length; i++) {
+		const prev = track.keys[i - 1];
+		const cur = track.keys[i];
+		if (cur.t <= prev.t) throw new TrackValidationError(track.target, `keys must be strictly increasing in t (key[${i}] at t=${cur.t} after t=${prev.t})`);
+	}
+	if (!/^[^/]+\/.+$/.test(track.target)) throw new TrackValidationError(track.target, "target must be '<nodeId>/<prop.path>' (e.g. 'circle/opacity')");
+}
+function key(t, value, easeOrOpts) {
+	if (easeOrOpts === void 0) return {
+		t,
+		value
+	};
+	if (typeof easeOrOpts === "string" || "kind" in easeOrOpts) return {
+		t,
+		value,
+		ease: easeOrOpts
+	};
+	const opts = easeOrOpts;
+	const k = {
+		t,
+		value
+	};
+	if (opts.ease !== void 0) k.ease = opts.ease;
+	if (opts.interp !== void 0) k.interp = opts.interp;
+	if (opts.id !== void 0) k.id = opts.id;
+	if (opts.derived !== void 0) k.derived = opts.derived;
+	return k;
+}
+/**
+* The settle-ON-the-beat helper: a spring key must sit at prev.t +
+* spring.duration(cfg) (§2.7), so beat-anchored authoring otherwise means
+* hand-computing the launch time. springTo returns the [launch, settle] key
+* pair with the arithmetic done — spread it into a raw track():
+*   track('x/width', 'number', [...springTo(beats.start('drop'), 0, 320, cfg)])
+*/
+function springTo(endT, from, to, cfg) {
+	const d = spring.duration(cfg);
+	if (endT - d < 0) throw new TrackValidationError("springTo", `this spring needs ${d.toFixed(3)}s to settle — endT must be ≥ its duration (got ${endT})`);
+	return [key(endT - d, from), key(endT, to, spring(cfg))];
+}
+/**
+* Cascade a set of tracks by shifting each one's key times — the classic
+* stagger for animating a list of nodes with a delay between them. `delay` is
+* the per-index gap in seconds, or a function of the index for non-linear
+* cascades. Pure: returns new tracks, leaving the inputs untouched.
+*
+*   stagger(items.map((it, i) => track(`${it.id}/opacity`, 'number',
+*     [key(0, 0), key(0.3, 1, 'easeOutCubic')])), 0.08)
+*/
+function stagger(tracks, delay) {
+	const at = typeof delay === "function" ? delay : (i) => i * delay;
+	return tracks.map((tr, i) => {
+		const d = at(i);
+		return {
+			...tr,
+			keys: tr.keys.map((k) => ({
+				...k,
+				t: k.t + d
+			}))
+		};
+	});
+}
+function track(target, type, keys, opts) {
+	const tr = {
+		target,
+		type,
+		keys
+	};
+	if (opts?.editable !== void 0) tr.editable = opts.editable;
+	validateTrack(tr);
+	return tr;
+}
+function resolveEase(spec) {
+	if (spec === void 0) return namedEasing("linear");
+	if (typeof spec === "string") return namedEasing(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 = 1 / 1024;
+		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);
+	if (!s) {
+		s = {
+			cursor: 1,
+			easeCache: new Array(tr.keys.length)
+		};
+		samplerStates.set(tr, s);
+	}
+	return s;
+}
+function easeFor(tr, s, i) {
+	let fn = s.easeCache[i];
+	if (!fn) {
+		fn = resolveEase(tr.keys[i].ease);
+		s.easeCache[i] = fn;
+	}
+	return fn;
+}
+/**
+* Find i such that keys[i-1].t <= t < keys[i].t, i.e. the index of the
+* arrival key of the segment containing t. Returns 0 if t < first key,
+* keys.length if t >= last key.
+*/
+function findSegment(keys, t, hint) {
+	const n = keys.length;
+	for (let i = Math.max(1, hint - 1); i <= Math.min(n - 1, hint + 1); i++) if (keys[i - 1].t <= t && t < keys[i].t) return i;
+	if (t < keys[0].t) return 0;
+	if (t >= keys[n - 1].t) return n;
+	let lo = 1;
+	let hi = n - 1;
+	while (lo < hi) {
+		const mid = lo + hi >> 1;
+		if (keys[mid].t <= t) lo = mid + 1;
+		else hi = mid;
+	}
+	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;
+	const n = keys.length;
+	const s = state(tr);
+	const i = findSegment(keys, t, s.cursor);
+	if (i === 0) return keys[0].value;
+	if (i >= n) return keys[n - 1].value;
+	s.cursor = i;
+	const arrival = keys[i];
+	const prev = keys[i - 1];
+	if (arrival.interp === "hold") return prev.value;
+	const vt = getValueType(tr.type);
+	const p = (t - prev.t) / (arrival.t - prev.t);
+	let easedT = easeFor(tr, s, i)(p);
+	if (!vt.extrapolates && (easedT < 0 || easedT > 1)) {
+		if (!s.warnedClamp) {
+			s.warnedClamp = true;
+			emitDevWarning(`track '${tr.target}' (type '${tr.type}') clamped an out-of-range eased value — non-extrapolating types can't overshoot, so a spring/overshooting ease on this track is flattened`);
+		}
+		easedT = Math.min(1, Math.max(0, easedT));
+	}
+	return vt.lerp(prev.value, arrival.value, easedT);
+}
+//#endregion
+//#region src/timeline.ts
+/**
+* The Timeline document (DESIGN.md §2.3) — the serializable animation source
+* of truth — and its compiler: child flattening (add/sync), same-target
+* coalescing (last-insertion-wins, §2.2), duration computation, validation.
+*/
+function timeline(init) {
+	const doc = {
+		version: 1,
+		tracks: init.tracks ?? []
+	};
+	if (init.duration !== void 0) doc.duration = init.duration;
+	if (init.editableDuration !== void 0) doc.editableDuration = init.editableDuration;
+	if (init.fps !== void 0) doc.fps = init.fps;
+	if (init.posterTime !== void 0) doc.posterTime = init.posterTime;
+	if (init.labels !== void 0) doc.labels = init.labels;
+	if (init.markers !== void 0) doc.markers = init.markers;
+	if (init.children !== void 0) doc.children = init.children;
+	if (init.audio !== void 0) doc.audio = init.audio;
+	if (init.assets !== void 0) doc.assets = init.assets;
+	return doc;
+}
+var TimelineValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TimelineValidationError";
+	}
+};
+/** Spring key rule (§2.7): a spring-eased key's t must equal prev.t + spring.duration(cfg). */
+function validateSpringKeys(tr) {
+	for (let i = 1; i < tr.keys.length; i++) {
+		const k = tr.keys[i];
+		if (k.ease && typeof k.ease === "object" && k.ease.kind === "spring") {
+			const expected = tr.keys[i - 1].t + spring.duration(k.ease);
+			if (Math.abs(k.t - expected) > 1e-6) throw new TimelineValidationError(`track '${tr.target}': spring-eased key at t=${k.t} must sit at prev.t + spring.duration (${expected.toFixed(6)}); the builder computes this automatically`);
+		}
+	}
+}
+/**
+* Sample-indexed clip offset — the single A/V-sync source of truth (§5.3),
+* `round(at * sampleRate)`. Both the CLI (FFmpeg) and the browser
+* (OfflineAudioContext) mixers derive their delay from this, so A/V offsets
+* agree across paths by construction rather than one rounding to milliseconds
+* and the other to raw float seconds. Default rate is the canonical mix grid.
+*/
+function audioOffsetSamples(at, sampleRate = 48e3) {
+	return Math.round(at * sampleRate);
+}
+function rebaseKeys(keys, at, timeScale) {
+	return keys.map((k) => ({
+		...k,
+		t: at + k.t / timeScale
+	}));
+}
+function flatten(doc, at, timeScale, unit, out, counter) {
+	for (const tr of doc.tracks) {
+		validateTrack(tr);
+		validateSpringKeys(tr);
+		out.push({
+			track: {
+				...tr,
+				keys: rebaseKeys(tr.keys, at, timeScale)
+			},
+			unit
+		});
+	}
+	for (const child of doc.children ?? []) {
+		const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
+		if (child.mode === "add" && child.timeScale !== void 0) throw new TimelineValidationError("timeScale is only valid on mode:'sync' children (§2.3)");
+		if (scale <= 0) throw new TimelineValidationError("sync timeScale must be > 0");
+		const childUnit = child.mode === "sync" ? ++counter.n : unit;
+		flatten(child.timeline, at + child.at / timeScale, timeScale * scale, childUnit, out, counter);
+	}
+}
+/**
+* Coalesce same-target tracks: later insertion wins where key ranges overlap
+* (§2.2/§2.6 decided rule), with a dev warning. Earlier keys inside the later
+* track's [first.t, last.t] span are dropped.
+*/
+function coalesce(entries) {
+	const byTarget = /* @__PURE__ */ new Map();
+	for (const { track: tr, unit } of entries) {
+		const existing = byTarget.get(tr.target);
+		if (!existing) {
+			byTarget.set(tr.target, {
+				track: {
+					...tr,
+					keys: [...tr.keys]
+				},
+				unit
+			});
+			continue;
+		}
+		if (existing.unit !== unit) throw new TimelineValidationError(`target '${tr.target}' is animated by a sync (opaque) child and another timeline unit; sync children must own disjoint targets (no last-writer-wins across the sync boundary, §2.3)`);
+		if (existing.track.type !== tr.type) throw new TimelineValidationError(`target '${tr.target}' has conflicting value types '${existing.track.type}' and '${tr.type}'`);
+		const start = tr.keys[0].t;
+		const end = tr.keys[tr.keys.length - 1].t;
+		const existingStart = existing.track.keys[0].t;
+		const existingEnd = existing.track.keys[existing.track.keys.length - 1].t;
+		const kept = existing.track.keys.filter((k) => k.t < start || k.t > end);
+		if (existingStart <= end && start <= existingEnd) emitDevWarning(`overlapping tracks for '${tr.target}' in [${start}, ${end}]: later insertion wins (${existing.track.keys.length - kept.length} earlier key(s) dropped)`);
+		existing.track.keys = [...kept, ...tr.keys].sort((a, b) => a.t - b.t);
+	}
+	const result = /* @__PURE__ */ new Map();
+	for (const [target, { track }] of byTarget) result.set(target, track);
+	return result;
+}
+/**
+* Studio reader (§6.2 rule 4): is this timeline's duration opted into editor
+* editing? Code-owned and read-only by default; `editableDuration()` flips it.
+*/
+function isDurationEditable(doc) {
+	return doc.editableDuration === true;
+}
+function childExtent(child) {
+	const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
+	return child.at + computeDuration(child.timeline) / scale;
+}
+function computeDuration(doc) {
+	if (doc.duration !== void 0) return doc.duration;
+	let max = 0;
+	for (const tr of doc.tracks) {
+		const last = tr.keys[tr.keys.length - 1];
+		if (last) max = Math.max(max, last.t);
+	}
+	for (const m of doc.markers ?? []) max = Math.max(max, m.t);
+	for (const child of doc.children ?? []) max = Math.max(max, childExtent(child));
+	return max;
+}
+function compileTimeline(doc) {
+	if (doc.version !== 1) throw new TimelineValidationError(`unsupported timeline document version ${String(doc.version)}`);
+	const flat = [];
+	flatten(doc, 0, 1, 0, flat, { n: 0 });
+	const tracks = coalesce(flat);
+	const labels = { ...doc.labels };
+	const markers = [...doc.markers ?? []];
+	const audio = [...doc.audio ?? []];
+	const visitChildren = (children, at, scale) => {
+		for (const child of children ?? []) {
+			const base = at + child.at / scale;
+			const childScale = scale * (child.mode === "sync" ? child.timeScale ?? 1 : 1);
+			for (const [name, t] of Object.entries(child.timeline.labels ?? {})) if (!(name in labels)) labels[name] = base + t / childScale;
+			for (const m of child.timeline.markers ?? []) markers.push({
+				...m,
+				t: base + m.t / childScale
+			});
+			for (const clip of child.timeline.audio ?? []) audio.push({
+				...clip,
+				at: base + clip.at / childScale,
+				...childScale !== 1 ? { playbackRate: (clip.playbackRate ?? 1) * childScale } : {}
+			});
+			visitChildren(child.timeline.children, base, childScale);
+		}
+	};
+	visitChildren(doc.children, 0, 1);
+	markers.sort((a, b) => a.t - b.t);
+	audio.sort((a, b) => a.at - b.at);
+	return {
+		duration: computeDuration(doc),
+		labels,
+		markers,
+		tracks,
+		audio
+	};
+}
+//#endregion
+//#region src/targetRef.ts
+/**
+* Target references (DESIGN.md §2.6): the builder accepts either a canonical
+* target string ('circle/opacity') or a property signal that carries its own
+* path — attached by the scene package at node construction via TARGET_PATH.
+*/
+const TARGET_PATH = Symbol.for("glissade.targetPath");
+var UnresolvableTargetError = class extends Error {
+	constructor(message) {
+		super(message ?? "tween target is not addressable: pass a target string (\"node/prop\") or a property signal of a node that has an explicit id (§3.1 — anonymous nodes cannot be track targets)");
+		this.name = "UnresolvableTargetError";
+	}
+};
+/** The node-id portion of a canonical `nodeId/prop.path` target. */
+function targetNodeId(target) {
+	const slash = target.indexOf("/");
+	return slash < 0 ? target : target.slice(0, slash);
+}
+/**
+* The single editable-host rule (§6.4 sub-decision, the 0.9 locked predicate):
+* only a node with an EXPLICIT, non-structural id can host an editable or
+* editor-created track. Structural fallback ids (`~Type.ordinal`, §6.5) are
+* inspection-only and reorder-fragile, so they are never editable nor valid
+* track targets. Lives here (the addressing module) so the builder guard, the
+* scene, and the studio host all share ONE definition.
+*/
+function isEditableNodeId(id) {
+	return typeof id === "string" && id.length > 0 && id !== "__root" && !id.startsWith("~");
+}
+function resolveTweenTarget(target) {
+	const path = typeof target === "string" ? target : target[TARGET_PATH];
+	if (typeof path !== "string") throw new UnresolvableTargetError();
+	if (targetNodeId(path).startsWith("~")) throw new UnresolvableTargetError(`'${path}': structural ids (~Type.ordinal) are inspection-only and cannot be track targets (§6.5) — give the node an explicit id`);
+	return path;
+}
+//#endregion
+//#region src/sidecar.ts
+/**
+* The editor sidecar (DESIGN.md §6.2): code declares scene structure and
+* programmatic tracks; the studio owns keyframe data persisted next to the
+* scene module and merged at track granularity. Versioned independently of the
+* API (§7.4) — breaking it orphans users' files, so v1 documents migrate.
+*
+* v2 namespaces edits by timeline id ('main' for the linear timeline; v2
+* machines add more), keys tracks by canonical target, records the code
+* baseline hash for drift detection, parks drifted tracks as `orphans`, and
+* gives keys stable `k<N>` ids.
+*/
+const MAIN = "main";
+var SidecarVersionError = class extends Error {
+	constructor(version) {
+		super(`unsupported sidecar version ${String(version)}; this build reads sidecarVersion 1 or 2`);
+		this.name = "SidecarVersionError";
+	}
+};
+function emptySidecar() {
+	return {
+		sidecarVersion: 2,
+		timelines: { [MAIN]: { tracks: {} } }
+	};
+}
+/** Lift a v1 (or already-v2) document to the v2 shape. Throws on unknown versions. */
+function migrateSidecar(doc) {
+	if (!doc) return null;
+	if (doc.sidecarVersion === 2) return doc;
+	if (doc.sidecarVersion === 1) {
+		const tracks = {};
+		for (const t of doc.tracks) tracks[t.target] = {
+			type: t.type,
+			baseHash: null,
+			keys: t.keys
+		};
+		const main = { tracks };
+		if (doc.labels) main.labels = doc.labels;
+		return {
+			sidecarVersion: 2,
+			timelines: { [MAIN]: main }
+		};
+	}
+	throw new SidecarVersionError(doc.sidecarVersion);
+}
+/** Stable hash of a code track's keys — the baseline an editor branch records. */
+function hashKeys(keys) {
+	const s = JSON.stringify(keys.map((k) => [
+		k.t,
+		k.value,
+		k.ease ?? null,
+		k.interp ?? null
+	]));
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(16);
+}
+/** Assign stable monotonic `k<N>` ids to keys lacking one; existing ids preserved. */
+function assignKeyIds(keys) {
+	let max = -1;
+	for (const k of keys) {
+		const m = k.id ? /^k(\d+)$/.exec(k.id) : null;
+		if (m) max = Math.max(max, Number(m[1]));
+	}
+	return keys.map((k) => k.id ? { ...k } : {
+		...k,
+		id: `k${++max}`
+	});
+}
+/**
+* Set one editable track's keys in the sidecar (§6.2) — the studio write path.
+* `codeBaselineKeys` is the code track this branches from (null = editor-created
+* with no baseline). Keys get stable `k<N>` ids. Returns a new document.
+*/
+function setSidecarTrack(doc, timelineId, target, type, keys, codeBaselineKeys) {
+	if (!isEditableNodeId(targetNodeId(target))) throw new TrackValidationError(target, "structural/un-id'd nodes cannot host editor tracks (§6.5) — only nodes with an explicit id");
+	const tl = doc.timelines[timelineId] ?? { tracks: {} };
+	const entry = {
+		type,
+		baseHash: codeBaselineKeys ? hashKeys(codeBaselineKeys) : null,
+		keys: assignKeyIds(keys)
+	};
+	return {
+		...doc,
+		timelines: {
+			...doc.timelines,
+			[timelineId]: {
+				...tl,
+				tracks: {
+					...tl.tracks,
+					[target]: entry
+				}
+			}
+		}
+	};
+}
+/**
+* Remove one editor-owned track from the sidecar (§6.2 rule 7 write-back): the
+* "extract edits to code" affordance deletes the sidecar entry after copying its
+* `key(...)` source to the clipboard. Source is never mutated — the user pastes
+* the generated calls themselves. A missing entry is a no-op (returns the input
+* unchanged); the document is never mutated in place.
+*/
+function deleteSidecarTrack(doc, timelineId, target) {
+	const tl = doc.timelines[timelineId];
+	if (!tl || !(target in tl.tracks)) return doc;
+	const { [target]: _removed, ...rest } = tl.tracks;
+	return {
+		...doc,
+		timelines: {
+			...doc.timelines,
+			[timelineId]: {
+				...tl,
+				tracks: rest
+			}
+		}
+	};
+}
+/**
+* Re-resolve `derived:true` leading keys against the merged track (§2.6): a
+* derived from-key duplicates the preceding key's held value, so an upstream
+* edit must flow into it or the segment pops at its start. Build-time derived
+* keys are already correct; this fixes the ones an edit moved beneath.
+*/
+function reresolveDerived(keys) {
+	if (!keys.some((k) => k.derived)) return keys;
+	return keys.map((k, i) => k.derived && i > 0 ? {
+		...k,
+		value: keys[i - 1].value
+	} : k);
+}
+/**
+* Merge with the full §6.2 report: the bindable Timeline, the list of targets
+* whose code baseline drifted, and the orphaned tracks (type-changed, or whose
+* code track vanished). Orphans are NEVER merged, so a drifted edit can't make
+* the whole overlay fail to bind — the good edits survive. Inputs unmutated.
+*/
+function mergeSidecarDetailed(code, sidecar) {
+	const doc = migrateSidecar(sidecar);
+	if (!doc) return {
+		timeline: code,
+		drift: [],
+		orphans: {}
+	};
+	const main = doc.timelines[MAIN] ?? { tracks: {} };
+	const overlay = new Map(Object.entries(main.tracks));
+	const drift = [];
+	const orphans = { ...main.orphans ?? {} };
+	const tracks = code.tracks.map((t) => {
+		const entry = overlay.get(t.target);
+		if (!entry) return t;
+		overlay.delete(t.target);
+		if (entry.type !== t.type) {
+			orphans[t.target] = {
+				type: entry.type,
+				keys: entry.keys,
+				reason: "type-changed"
+			};
+			return t;
+		}
+		if (entry.baseHash !== null && entry.baseHash !== hashKeys(t.keys)) drift.push(t.target);
+		return {
+			...t,
+			keys: reresolveDerived(entry.keys.map((k) => ({ ...k }))),
+			editable: true
+		};
+	});
+	for (const [target, entry] of overlay) if (entry.baseHash !== null) orphans[target] = {
+		type: entry.type,
+		keys: entry.keys,
+		reason: "prop-missing"
+	};
+	else tracks.push({
+		target,
+		type: entry.type,
+		keys: reresolveDerived(entry.keys.map((k) => ({ ...k }))),
+		editable: true
+	});
+	const merged = {
+		...code,
+		tracks
+	};
+	if (main.labels && Object.keys(main.labels).length > 0) {
+		const codeLabels = code.labels ?? {};
+		const shadowed = Object.keys(main.labels).filter((n) => n in codeLabels);
+		if (shadowed.length) emitDevWarning(`sidecar label(s) ${shadowed.join(", ")} collide with code labels; code wins (§6.2)`);
+		merged.labels = {
+			...main.labels,
+			...codeLabels
+		};
+	}
+	if (drift.length) emitDevWarning(`sidecar: code baseline changed beneath edits on ${drift.join(", ")} (§6.2)`);
+	return {
+		timeline: merged,
+		drift,
+		orphans
+	};
+}
+/** Merge the sidecar overlay onto the code baseline → a bindable Timeline (§6.2). */
+function mergeSidecar(code, sidecar) {
+	return mergeSidecarDetailed(code, sidecar).timeline;
+}
+/**
+* Editor-edit normalization (§2.7 invariant): a spring-eased key's t is
+* intrinsic — prev.t + spring.duration(cfg) — so after any retime, sort and
+* re-pin spring keys to their predecessors. Dragging a spring key itself
+* therefore snaps back; retiming its predecessor carries it along. Returns a
+* new array. Colliding keys are NUDGED apart (+1ms), never deleted — an editor
+* must not silently destroy keyframe data on an exact-t collision.
+*/
+function normalizeEditedKeys(keys) {
+	const out = keys.map((k) => ({ ...k })).sort((a, b) => a.t - b.t);
+	for (let pass = 0; pass < 2; pass++) {
+		for (let i = 1; i < out.length; i++) {
+			const ease = out[i].ease;
+			if (ease && typeof ease === "object" && ease.kind === "spring") out[i].t = out[i - 1].t + spring.duration(ease);
+		}
+		out.sort((a, b) => a.t - b.t);
+	}
+	for (let i = 1; i < out.length; i++) if (out[i].t <= out[i - 1].t) out[i].t = out[i - 1].t + .001;
+	return out;
+}
+//#endregion
+export { vec2Equals as $, velocityAt as A, easings as B, resolveEase as C, stagger as D, springTo as E, DEFAULT_EASE as F, colorType as G, UnknownValueTypeError as H, UnknownEasingError as I, numberType as J, getValueType as K, cubicBezier as L, springEasing as M, springEasingDerivative as N, track as O, springPresets as P, vec2ArcType as Q, cubicBezierDerivative as R, key as S, sampleTrack as T, ValueTypeInferenceError as U, namedEasing as V, booleanType as W, registerValueType as X, pathType as Y, stringType as Z, audioOffsetSamples as _, hashKeys as a, lerpColor as at, timeline as b, migrateSidecar as c, rgbaToOklab as ct, TARGET_PATH as d, vec2Type as et, UnresolvableTargetError as f, TimelineValidationError as g, targetNodeId as h, emptySidecar as i, formatColor as it, spring as j, validateTrack as k, normalizeEditedKeys as l, resolveTweenTarget as m, assignKeyIds as n, setDevWarning as nt, mergeSidecar as o, oklabToRgba as ot, isEditableNodeId as p, inferValueType as q, deleteSidecarTrack as r, ColorParseError as rt, mergeSidecarDetailed as s, parseColor as st, SidecarVersionError as t, emitDevWarning as tt, setSidecarTrack as u, compileTimeline as v, resolveEaseDerivative as w, TrackValidationError as x, isDurationEditable as y, easingDerivatives as z };