@glissade/core 0.18.0 → 0.19.0-pre.1

package/dist/index.d.ts

@@ -242,9 +242,20 @@ interface TweenOpts<T = unknown> {
 }
 /** The shared tween shape applied to every staggered target (§2.6 stagger sugar). */
 interface StaggerSpec<T = unknown> {
-  to: T;
-  /** Explicit start value — routes each target through `fromTo` when present. */
-  from?: T;
+  /**
+   * The destination value. A plain `T` fans uniformly across every target; a
+   * function `(index, count) => T` resolves a PER-TARGET destination (a card
+   * flying to its own slot). Resolved by a runtime typeof branch — consistent
+   * with `each: number | fn` and scene `each()`; mildly lossy when `T` is itself
+   * callable (acceptable). Emits N ordinary tweens, byte-identical to hand-authored.
+   */
+  to: T | ((index: number, count: number) => T);
+  /**
+   * Explicit start value — routes each target through `fromTo` when present. A
+   * plain `T` fans uniformly; a function `(index, count) => T` resolves a
+   * per-target start (same runtime typeof branch as `to`).
+   */
+  from?: T | ((index: number, count: number) => T);
   duration?: number;
   ease?: EaseSpec;
 }
@@ -284,6 +295,16 @@ interface TimelineBuilder {
    * honestly to the cursor).
    */
   stagger<T>(targets: TweenTarget[], spec: StaggerSpec<T>, opts: StaggerOpts): TimelineBuilder;
+  /**
+   * Build-time bridge for the CLIP tier (Isuo8Gxn): inject pre-built `Track[]`
+   * (the `{ tracks }` returned by `presence`/`clip`/`each`/`morph` on
+   * `@glissade/core/clips`) straight into the document. The tracks carry their
+   * OWN absolute keyframe times — they land as ordinary track rows through the
+   * same finalize→coalesce path `add()` uses for child tracks (same-target rows
+   * coalesce, later wins). Scoped to raw absolute-time tracks: no cursor-offset
+   * or rebasing wrapper (deferred). Does NOT move the cursor.
+   */
+  tracks(tracks: Track[]): TimelineBuilder;
   /** Hold key: the value snaps at the resolved position (§2.6). */
   set<T>(target: TweenTarget, value: T, opts?: {
     at?: Position;

package/dist/index.js

@@ -580,6 +580,37 @@ var PositionError = class extends Error {
 		this.name = "PositionError";
 	}
 };
+/**
+* Reject UNKNOWN keys on a builder method's options object (k-g1zn). Each method
+* destructures only the keys it understands and historically SWALLOWED the rest
+* silently — a misspelled/wrong option vanished with no error. Validate against
+* an allow-list and THROW a `TimelineValidationError` naming the offending key(s)
+* and the method, matching the build-time-fail pattern (t<0 / non-finite each).
+* Mildly breaking: stray keys that were ignored now throw.
+*/
+function rejectUnknownOpts(method, opts, known) {
+	const allow = new Set(known);
+	const unknown = Object.keys(opts).filter((k) => !allow.has(k));
+	if (unknown.length > 0) throw new TimelineValidationError(`${method}: unknown option${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `'${k}'`).join(", ")} — known: ${known.map((k) => `'${k}'`).join(", ")}`);
+}
+const TO_OPTS_KEYS = [
+	"duration",
+	"ease",
+	"at",
+	"from"
+];
+const SET_OPTS_KEYS = ["at"];
+const STAGGER_SPEC_KEYS = [
+	"to",
+	"from",
+	"duration",
+	"ease"
+];
+const STAGGER_OPTS_KEYS = [
+	"each",
+	"anchor",
+	"at"
+];
 function peekBase(target) {
 	return typeof target !== "string" && typeof target.peek === "function" ? target.peek() : void 0;
 }
@@ -590,6 +621,7 @@ function getTimelineCallbacks(doc) {
 }
 function buildTimeline(build, init = {}) {
 	const insertions = [];
+	const injectedTracks = [];
 	const labels = { ...init.labels };
 	const children = [];
 	const markers = [];
@@ -616,6 +648,7 @@ function buildTimeline(build, init = {}) {
 	}
 	const builder = {
 		to(target, value, opts = {}) {
+			rejectUnknownOpts("to", opts, TO_OPTS_KEYS);
 			const ease = opts.ease ?? "easeInOutCubic";
 			const isSpring = typeof ease === "object" && ease.kind === "spring";
 			const duration = isSpring ? spring.duration(ease) : opts.duration ?? 1;
@@ -639,11 +672,14 @@ function buildTimeline(build, init = {}) {
 			return builder;
 		},
 		fromTo(target, from, to, opts = {}) {
+			rejectUnknownOpts("fromTo", opts, TO_OPTS_KEYS);
 			builder.to(target, to, opts);
 			insertions[insertions.length - 1].explicitFrom = from;
 			return builder;
 		},
 		stagger(targets, spec, opts) {
+			rejectUnknownOpts("stagger spec", spec, STAGGER_SPEC_KEYS);
+			rejectUnknownOpts("stagger opts", opts, STAGGER_OPTS_KEYS);
 			const n = targets.length;
 			const base = resolvePosition(opts.at);
 			const c = (n - 1) / 2;
@@ -678,8 +714,11 @@ function buildTimeline(build, init = {}) {
 				const start = base + d;
 				if (start < 0) throw new TimelineValidationError(`stagger: target would land at t=${start} (< 0); shift opts.at`);
 				const t = targets[i];
-				if (spec.from !== void 0) builder.fromTo(t, spec.from, spec.to, tweenOpts(d));
-				else builder.to(t, spec.to, tweenOpts(d));
+				const toVal = typeof spec.to === "function" ? spec.to(i, n) : spec.to;
+				if (spec.from !== void 0) {
+					const fromVal = typeof spec.from === "function" ? spec.from(i, n) : spec.from;
+					builder.fromTo(t, fromVal, toVal, tweenOpts(d));
+				} else builder.to(t, toVal, tweenOpts(d));
 			}
 			if (n > 0) {
 				prevStart = base + minDelay;
@@ -688,6 +727,7 @@ function buildTimeline(build, init = {}) {
 			return builder;
 		},
 		set(target, value, opts = {}) {
+			rejectUnknownOpts("set", opts, SET_OPTS_KEYS);
 			const start = resolvePosition(opts.at);
 			insertions.push({
 				kind: "set",
@@ -704,6 +744,10 @@ function buildTimeline(build, init = {}) {
 			prevEnd = start;
 			return builder;
 		},
+		tracks(tracks) {
+			for (const tr of tracks) injectedTracks.push(tr);
+			return builder;
+		},
 		label(name, at) {
 			labels[name] = at === void 0 ? prevEnd : resolvePosition(at);
 			return builder;
@@ -842,6 +886,7 @@ function buildTimeline(build, init = {}) {
 		if (editable) tr.editable = true;
 		tracks.push(tr);
 	}
+	for (const tr of injectedTracks) tracks.push(tr);
 	const doc = timeline$1({
 		...init,
 		tracks,

package/package.json

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