@glissade/core 0.12.1 → 0.13.0-pre.0

package/dist/clips.d.ts

@@ -111,4 +111,106 @@ declare function driftLoop(opts?: (DurationOpts & {
   amplitude?: number;
 })): Clip;
 //#endregion
-export { type ApplyOpts, type ApplyOpts as ClipApplyOpts, type ChannelOverride, type Clip, type ClipChannel, ClipError, type ClipListDelay, type ClipListOpts, type ClipResult, type ClipSpec, type ClipTarget, type DurationOpts, type SlideEdge, clip, clipList, driftLoop, popIn, pulse, slideIn };
+//#region src/morph.d.ts
+/** An axis-aligned box. `x`,`y` are the box CENTER (the Rect `position` convention). */
+interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/**
+ * The shared-element contract: `morphNode` is the ONE element that travels (its
+ * `position`+`scale` are FLIPped); `fromNode`/`toNode` (both optional) cross-fade
+ * their `opacity`. The explicit map IS the "shared morphId" — there is no scene
+ * query, the caller names the three roles.
+ */
+interface MorphTargets {
+  morphNode: TweenTarget;
+  fromNode?: TweenTarget;
+  toNode?: TweenTarget;
+}
+interface MorphOpts {
+  /** Wall-clock start second of the morph. */
+  at: number;
+  /** Total morph length in seconds (> 0). */
+  duration: number;
+  /** Arriving ease of position/scale and the cross-fade (default linear). */
+  ease?: EaseSpec;
+  /**
+   * The scale BASIS: `[base.w, base.h]` is the size at which `morphNode` renders
+   * at scale [1,1]. Defaults to `to` (the TO box), so the end scale is [1,1] when
+   * `morphNode` is authored at the document's size. `fromScale = from/base`,
+   * `toScale = to/base`.
+   */
+  base?: {
+    w: number;
+    h: number;
+  };
+  /**
+   * Cross-fade split in [0,1] (default 0.5): `fromNode` fades out over
+   * `duration*crossfade`; `toNode` fades in starting at `duration*(1-crossfade)`.
+   */
+  crossfade?: number;
+  /** v1 default `'transform'` (position+scale FLIP). `'size'` reserved/deferred. */
+  metric?: 'transform';
+}
+interface MorphResult {
+  tracks: ClipResult['tracks'];
+  /** Wall-clock end second (`at + duration`). */
+  end: number;
+}
+declare class MorphError extends Error {
+  constructor(message: string);
+}
+/**
+ * Compile a shared-element box-FLIP morph into hand-authored-equivalent tracks.
+ *
+ *   morph({ x: 80, y: 200, w: 120, h: 36 }, { x: 320, y: 200, w: 480, h: 280 },
+ *     { morphNode: 'morphFx', fromNode: 'chip', toNode: 'document' },
+ *     { at: 0.5, duration: 1.2 })
+ *
+ * Emits (via the clip path):
+ *   morphNode/position : vec2  [at]→from-center,         [at+dur]→to-center
+ *   morphNode/scale    : vec2  [at]→from/base,           [at+dur]→to/base
+ *   fromNode/opacity   : number[at]→1,                   [at+dur*crossfade]→0
+ *   toNode/opacity     : number[at+dur*(1-crossfade)]→0, [at+dur]→1
+ */
+declare function morph(from: Box, to: Box, targets: MorphTargets, opts: MorphOpts): MorphResult;
+//#endregion
+//#region src/presence.d.ts
+declare class PresenceError extends Error {
+  constructor(message: string);
+}
+interface PresenceOpts {
+  /** Wall-clock second the node ENTERS (becomes visible). */
+  show: number;
+  /** Wall-clock second the node has fully EXITED (the exit LANDS here). */
+  hide: number;
+  /** Entrance clip (default = a plain opacity fade-in 0→1, ~0.3s). */
+  enter?: Clip;
+  /** Exit clip (default = a plain opacity fade-out 1→0, ~0.3s). Back-timed to land on `hide`. */
+  exit?: Clip;
+  /** Forwarded to `enter.apply` (speed / per-channel overrides). */
+  enterOpts?: ApplyOpts;
+  /** Forwarded to `exit.apply` (speed / per-channel overrides). */
+  exitOpts?: ApplyOpts;
+}
+interface PresenceResult {
+  /** Reconciled tracks: the opacity guard (fused with enter/exit opacity keys) + any non-opacity channels. */
+  tracks: Track[];
+  /** The real exit second — siblings anchor here. Equals `hide`. */
+  end: number;
+  /** When the node became visible (= `show`). */
+  shownAt: number;
+  /** When the node finished exiting (= `hide`). */
+  hiddenAt: number;
+}
+/**
+ * Schedule a node's enter/exit presence. Emits keyed `Track[]` only.
+ *
+ *   presence('card', { show: 1, hide: 5 })  // fade in at 1, fade out to land on 5
+ */
+declare function presence(nodeId: TweenTarget, opts: PresenceOpts): PresenceResult;
+//#endregion
+export { type ApplyOpts, type ApplyOpts as ClipApplyOpts, type Box, type ChannelOverride, type Clip, type ClipChannel, ClipError, type ClipListDelay, type ClipListOpts, type ClipResult, type ClipSpec, type ClipTarget, type DurationOpts, MorphError, type MorphOpts, type MorphResult, type MorphTargets, PresenceError, type PresenceOpts, type PresenceResult, type SlideEdge, clip, clipList, driftLoop, morph, popIn, presence, pulse, slideIn };

package/dist/clips.js

@@ -1,4 +1,4 @@
-import { i as resolveTweenTarget, p as track, s as key, x as inferValueType } from "./targetRef.js";
+import { a as targetNodeId, i as resolveTweenTarget, p as track, s as key, t as TARGET_PATH, x as inferValueType } from "./targetRef.js";
 //#region src/clip.ts
 /**
 * Motion clips (DESIGN.md §2 build-time sugar): `clip()` captures a relative-time
@@ -66,11 +66,19 @@ function compileChannel(target, ch, startSec, speed, override) {
 	if (ch.keys.length === 0) throw new ClipError(`clip channel '${target}' has no keys`);
 	const type = ch.type ?? inferValueType(ch.keys[0].value);
 	const lastIdx = ch.keys.length - 1;
+	if (override && lastIdx === 0 && override.from !== void 0) throw new ClipError(override.to !== void 0 ? `clip override for '${target}' supplies both 'from' and 'to' on a single-key channel — ambiguous (both target the only key)` : `clip override for '${target}' supplies 'from' on a single-key channel — ambiguous (the only key already is the 'to' value)`);
 	return track(target, type, ch.keys.map((k, i) => {
 		let value = k.value;
+		let overridden = false;
 		if (override) {
-			if (i === 0 && override.from !== void 0) value = assertOverrideType(target, type, override.from);
-			if (i === lastIdx && override.to !== void 0) value = assertOverrideType(target, type, override.to);
+			if (i === 0 && override.from !== void 0) {
+				value = assertOverrideType(target, type, override.from);
+				overridden = true;
+			}
+			if (i === lastIdx && override.to !== void 0) {
+				value = assertOverrideType(target, type, override.to);
+				overridden = true;
+			}
 		}
 		const out = {
 			t: startSec + k.t / speed,
@@ -80,7 +88,8 @@ function compileChannel(target, ch, startSec, speed, override) {
 		if (ease !== void 0) out.ease = ease;
 		if (k.interp !== void 0) out.interp = k.interp;
 		if (k.id !== void 0) out.id = k.id;
-		if (k.derived !== void 0) out.derived = k.derived;
+		if (k.derived !== void 0 && !overridden) out.derived = k.derived;
+		if (k.from !== void 0) out.from = k.from;
 		return out;
 	}));
 }
@@ -227,4 +236,237 @@ function driftLoop(opts) {
 	} } });
 }
 //#endregion
-export { ClipError, clip, clipList, driftLoop, popIn, pulse, slideIn };
+//#region src/morph.ts
+/**
+* Shared-element box-FLIP morph (0.13 build-time sugar). `morph()` takes two
+* caller-supplied `Box` literals (a FROM rect and a TO rect, both with the Rect
+* CENTER convention for x,y) and a map of target nodes, and compiles a FLIP
+* (First-Last-Invert-Play) position+scale tween on ONE shared element plus an
+* optional opacity cross-fade between the from/to nodes.
+*
+* It is PURE CORE: the FLIP delta is plain arithmetic over the two boxes — no
+* Yoga, no worldMatrix, no signal evaluation, no scene query (a scene-side
+* `worldBoxOf(node)` convenience is a deferred 0.14 fast-follow). The emission
+* delegates to the validated `clip()` path (one track-emission codepath), so the
+* output is BYTE-INDISTINGUISHABLE from hand-authored `track(...)` — same
+* determinism contract as `clip`/`stagger`/`springTo`.
+*/
+var MorphError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MorphError";
+	}
+};
+function assertFiniteBox(label, b) {
+	for (const [k, v] of [
+		["x", b.x],
+		["y", b.y],
+		["w", b.w],
+		["h", b.h]
+	]) if (!Number.isFinite(v)) throw new MorphError(`morph ${label}.${k} must be finite (got ${v})`);
+	if (!(b.w > 0) || !(b.h > 0)) throw new MorphError(`morph ${label} must have w>0 and h>0 (got w=${b.w}, h=${b.h}); a zero/negative box yields a NaN/Infinity scale`);
+}
+/**
+* Resolve a node-level `TweenTarget` and append a prop suffix, producing the
+* `'<nodeId>/<prop>'` string the clip map form resolves (which re-runs the
+* structural/anonymous-id rejection via resolveTweenTarget). A string target is
+* a bare node id; a property-signal carrier exposes its node via TARGET_PATH.
+*/
+function nodeTarget(target, prop) {
+	const id = typeof target === "string" ? target : target[TARGET_PATH];
+	if (typeof id !== "string" || id.length === 0) return `${String(id)}/${prop}`;
+	return `${targetNodeId(id)}/${prop}`;
+}
+/**
+* Compile a shared-element box-FLIP morph into hand-authored-equivalent tracks.
+*
+*   morph({ x: 80, y: 200, w: 120, h: 36 }, { x: 320, y: 200, w: 480, h: 280 },
+*     { morphNode: 'morphFx', fromNode: 'chip', toNode: 'document' },
+*     { at: 0.5, duration: 1.2 })
+*
+* Emits (via the clip path):
+*   morphNode/position : vec2  [at]→from-center,         [at+dur]→to-center
+*   morphNode/scale    : vec2  [at]→from/base,           [at+dur]→to/base
+*   fromNode/opacity   : number[at]→1,                   [at+dur*crossfade]→0
+*   toNode/opacity     : number[at+dur*(1-crossfade)]→0, [at+dur]→1
+*/
+function morph(from, to, targets, opts) {
+	const { at, duration } = opts;
+	const ease = opts.ease;
+	const crossfade = opts.crossfade ?? .5;
+	const metric = opts.metric ?? "transform";
+	if (metric !== "transform") throw new MorphError(`morph metric '${metric}' is not supported in v1 (only 'transform')`);
+	assertFiniteBox("from", from);
+	assertFiniteBox("to", to);
+	if (!(duration > 0)) throw new MorphError(`morph duration must be > 0 (got ${duration})`);
+	if (!(crossfade >= 0 && crossfade <= 1)) throw new MorphError(`morph crossfade must be in [0,1] (got ${crossfade})`);
+	const base = opts.base ?? {
+		w: to.w,
+		h: to.h
+	};
+	assertFiniteBox("to", {
+		x: 0,
+		y: 0,
+		w: base.w,
+		h: base.h
+	});
+	const fromScale = [from.w / base.w, from.h / base.h];
+	const toScale = [to.w / base.w, to.h / base.h];
+	const fromCenter = [from.x, from.y];
+	const toCenter = [to.x, to.y];
+	const channels = {
+		position: {
+			path: "position",
+			type: "vec2",
+			keys: [key(0, fromCenter), key(duration, toCenter, ease)]
+		},
+		scale: {
+			path: "scale",
+			type: "vec2",
+			keys: [key(0, fromScale), key(duration, toScale, ease)]
+		}
+	};
+	const targetMap = {
+		position: nodeTarget(targets.morphNode, "position"),
+		scale: nodeTarget(targets.morphNode, "scale")
+	};
+	if (targets.fromNode !== void 0 && duration * crossfade > 0) {
+		channels["fromOpacity"] = {
+			path: "opacity",
+			type: "number",
+			keys: [key(0, 1), key(duration * crossfade, 0, ease)]
+		};
+		targetMap["fromOpacity"] = nodeTarget(targets.fromNode, "opacity");
+	}
+	if (targets.toNode !== void 0 && duration * (1 - crossfade) < duration) {
+		channels["toOpacity"] = {
+			path: "opacity",
+			type: "number",
+			keys: [key(duration * (1 - crossfade), 0), key(duration, 1, ease)]
+		};
+		targetMap["toOpacity"] = nodeTarget(targets.toNode, "opacity");
+	}
+	const { tracks } = clip({ channels }).apply(targetMap, at);
+	return {
+		tracks,
+		end: at + duration
+	};
+}
+//#endregion
+//#region src/presence.ts
+/**
+* Presence scheduling (the 0.13 enter/exit sugar): build-time sugar over `clip`
+* that schedules a node's ENTER on `show`, its EXIT to land exactly on `hide`,
+* and authors a real `<nodeId>/opacity` WINDOW GUARD so the node is culled
+* (opacity<=0, see scene/node.ts §3) outside the live window.
+*
+* Like `clip`/`springTo`/`stagger`, this is authoring SUGAR — it compiles to
+* ordinary keyed `Track[]` via `track()`, byte-INDISTINGUISHABLE from the
+* hand-authored form. There is NO runtime visibility flag and no non-track
+* document state: a presence is a pure function of its arguments. Back-timing
+* the exit is pure arithmetic; reconciling the enter/exit opacity keys with the
+* guard uses the builder's deterministic later-wins coincident-`t` dedup with a
+* fixed merge order, so goldens stay byte-identical.
+*
+* The canonical case is a "send-line agency moment": a node enters, lives, and
+* exits on a beat. Siblings anchor to the real exit via the returned `end`.
+*/
+var PresenceError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PresenceError";
+	}
+};
+/** The default enter/exit: a plain opacity fade over `DEFAULT_FADE` seconds. */
+const DEFAULT_FADE = .3;
+/** Plain opacity fade-in 0→1 (the default enter). */
+function defaultEnter() {
+	return clip({ channels: { opacity: {
+		path: "opacity",
+		keys: [key(0, 0), key(DEFAULT_FADE, 1)]
+	} } });
+}
+/** Plain opacity fade-out 1→0 (the default exit). */
+function defaultExit() {
+	return clip({ channels: { opacity: {
+		path: "opacity",
+		keys: [key(0, 1), key(DEFAULT_FADE, 0)]
+	} } });
+}
+/** Effective duration of a clip after a speed multiplier (`apply` divides every t by speed). */
+function effectiveDuration(c, opts) {
+	return c.duration / (opts?.speed ?? 1);
+}
+/**
+* Sort keys by `t`, breaking ties by original index (a STABLE sort, so that at a
+* coincident t the LATER-emitted key survives the later-wins dedup regardless of
+* the engine's `Array.sort` stability). Pure: returns a new array.
+*/
+function stableSortByT(keys) {
+	return keys.map((k, i) => [k, i]).sort((a, b) => a[0].t - b[0].t || a[1] - b[1]).map(([k]) => k);
+}
+/**
+* Pull the keys of the clip's OWN `<nodeId>/opacity` track out of an applied
+* result (if it authored one). Non-opacity tracks pass straight through.
+*/
+function partitionOpacity(tracks, opacityTarget) {
+	const rest = [];
+	let opacityKeys = [];
+	for (const tr of tracks) if (tr.target === opacityTarget) opacityKeys = tr.keys;
+	else rest.push(tr);
+	return {
+		opacityKeys,
+		rest
+	};
+}
+/**
+* Schedule a node's enter/exit presence. Emits keyed `Track[]` only.
+*
+*   presence('card', { show: 1, hide: 5 })  // fade in at 1, fade out to land on 5
+*/
+function presence(nodeId, opts) {
+	const { show, hide } = opts;
+	const baseTarget = resolveTweenTarget(typeof nodeId === "string" ? `${nodeId}/opacity` : nodeId);
+	const slash = baseTarget.indexOf("/");
+	const nodeIdStr = slash < 0 ? baseTarget : baseTarget.slice(0, slash);
+	const opacityTarget = `${nodeIdStr}/opacity`;
+	const enter = opts.enter ?? defaultEnter();
+	const exit = opts.exit ?? defaultExit();
+	const enterRes = enter.apply(nodeIdStr, show, opts.enterOpts);
+	const enterEnd = show + effectiveDuration(enter, opts.enterOpts);
+	const exitDur = effectiveDuration(exit, opts.exitOpts);
+	const exitStart = hide - exitDur;
+	if (exitStart < show) throw new PresenceError(`presence('${nodeIdStr}') exit needs ${exitDur.toFixed(3)}s but only ${(hide - show).toFixed(3)}s between show (${show}) and hide (${hide}) — widen the window or shorten/speed up the exit`);
+	const exitRes = exit.apply(nodeIdStr, exitStart, opts.exitOpts);
+	const { opacityKeys: enterOpacity, rest: enterRest } = partitionOpacity(enterRes.tracks, opacityTarget);
+	const { opacityKeys: exitOpacity, rest: exitRest } = partitionOpacity(exitRes.tracks, opacityTarget);
+	const bareGuard = [
+		key(0, 0, { interp: "hold" }),
+		key(enterEnd, 1, { interp: "hold" }),
+		key(hide, 0, { interp: "hold" })
+	];
+	const overlay = [];
+	if (enterOpacity.length > 0) for (const k of enterOpacity) overlay.push(k);
+	else overlay.push(key(show, 0), key(enterEnd, 1));
+	if (exitOpacity.length > 0) for (const k of exitOpacity) overlay.push(k);
+	else overlay.push(key(exitStart, 1), key(hide, 0));
+	const sorted = stableSortByT([...bareGuard, ...overlay]);
+	const deduped = [];
+	for (const k of sorted) {
+		const last = deduped[deduped.length - 1];
+		if (last && last.t === k.t) deduped[deduped.length - 1] = k;
+		else deduped.push(k);
+	}
+	return {
+		tracks: [
+			track(opacityTarget, "number", deduped),
+			...enterRest,
+			...exitRest
+		],
+		end: hide,
+		shownAt: show,
+		hiddenAt: hide
+	};
+}
+//#endregion
+export { ClipError, MorphError, PresenceError, clip, clipList, driftLoop, morph, popIn, presence, pulse, slideIn };

package/dist/targetRef.js

@@ -602,6 +602,14 @@ const pathType = {
 };
 const lerpN = (a, b, t) => a + (b - a) * t;
 const lerpPt = (a, b, t) => [lerpN(a[0], b[0], t), lerpN(a[1], b[1], t)];
+/** Same hue at alpha 0 — a transparent stand-in so an appearing/disappearing
+* `bg` (mesh baseline) fades through alpha instead of popping at the boundary. */
+function transparentOf(color) {
+	return formatColor({
+		...parseColor(color),
+		a: 0
+	});
+}
 /** Lift a solid color to a uniform gradient matching `shape` (every stop = color),
 * so a color↔gradient tween fades smoothly instead of snapping. */
 function liftColor(color, shape) {
@@ -625,10 +633,10 @@ function liftColor(color, shape) {
 	};
 }
 let warnedPaintShape = false;
-function paintSnap(t, a, b) {
+function paintSnap(t, a, b, message = "paint lerp across mismatched gradient shapes (different kind or stop count): snapping instead of interpolating — match the kind + stop count on both keyframes (§2.2)") {
 	if (!warnedPaintShape) {
 		warnedPaintShape = true;
-		emitDevWarning("paint lerp across mismatched gradient shapes (different kind or stop count): snapping instead of interpolating — match the kind + stop count on both keyframes (§2.2)");
+		emitDevWarning(message);
 	}
 	return t >= 1 ? b : a;
 }
@@ -649,17 +657,20 @@ const paintType = {
 		};
 		if (a.kind === "mesh" && b.kind === "mesh") {
 			if (a.points.length !== b.points.length) return paintSnap(t, a, b);
+			if (a.interpolation !== b.interpolation) return paintSnap(t, a, b, `paint lerp across mismatched mesh interpolation modes ('${a.interpolation ?? "smooth"}' → '${b.interpolation ?? "smooth"}'): snapping instead of interpolating — the blend kernel is discrete, so it switches once at the boundary; match \`interpolation\` on both keyframes to morph the points (§3 Paint)`);
+			const points = a.points.map((pa, i) => {
+				const pb = b.points[i];
+				return {
+					pos: lerpPt(pa.pos, pb.pos, t),
+					color: lerpColor(pa.color, pb.color, t)
+				};
+			});
+			const bg = a.bg !== void 0 || b.bg !== void 0 ? { bg: lerpColor(a.bg ?? transparentOf(b.bg), b.bg ?? transparentOf(a.bg), t) } : {};
 			return {
 				kind: "mesh",
-				points: a.points.map((pa, i) => {
-					const pb = b.points[i];
-					return {
-						pos: lerpPt(pa.pos, pb.pos, t),
-						color: lerpColor(pa.color, pb.color, t)
-					};
-				}),
+				points,
 				...a.interpolation ? { interpolation: a.interpolation } : {},
-				...a.bg !== void 0 && b.bg !== void 0 ? { bg: lerpColor(a.bg, b.bg, t) } : a.bg !== void 0 ? { bg: a.bg } : {}
+				...bg
 			};
 		}
 		if (a.kind === "mesh" || b.kind === "mesh") return paintSnap(t, a, b);

package/package.json

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