@glissade/core 0.6.0 → 0.7.0-pre.0

package/dist/index.d.ts

@@ -423,6 +423,14 @@ interface CompiledTimeline {
   /** Audio clips rebased to the root time axis (§5.3); sync timeScale scales playbackRate. */
   audio: AudioClip[];
 }
+/**
+ * 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.
+ */
+declare function audioOffsetSamples(at: number, sampleRate?: number): number;
 declare function compileTimeline(doc: Timeline): CompiledTimeline;
 //#endregion
 //#region src/targetRef.d.ts
@@ -567,7 +575,7 @@ interface SidecarDoc {
   sidecarVersion: 1;
   /** Editor-owned tracks, replacing same-target code tracks wholesale. */
   tracks: Track[];
-  /** Editor-owned labels; merged over code labels by name. */
+  /** Editor-created labels; code labels are authoritative and win on a name collision (§6.2). */
   labels?: Record<string, number>;
 }
 declare class SidecarVersionError extends Error {
@@ -595,4 +603,4 @@ declare function normalizeEditedKeys(keys: Key[]): Key[];
  */
 declare function mergeSidecar(code: Timeline, sidecar: SidecarDoc | null | undefined): Timeline;
 //#endregion
-export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type CompiledTimeline, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type GainEnvelope, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type OkLab, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type RetargetSpring, type Rgba, type Rng, type SidecarDoc, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Signal, WriteDuringEvaluationError, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { type AssetRef, type AudioClip, type BakeConfig, BakeError, type BindTarget, type BindableSignal, type BoundTimeline, type CheckpointedBakeConfig, type CheckpointedSim, type ChildEntry, CircularDependencyError, ColorParseError, type CompiledTimeline, type CurveSampler, DEFAULT_EASE, type DevWarning, type EaseSpec, type EasingFn, type Equals, type GainEnvelope, type HandoffKind, type Json, type Key, type KeyOpts, type Marker, type OkLab, type PathContour, type PathValue, type Playhead, type Position, PositionError, type ReadonlySignal, type RetargetSpring, type Rgba, type Rng, type SidecarDoc, SidecarVersionError, type Signal, type SignalOptions, type SpringConfig, type SpringEase, TARGET_PATH, type TargetCarrier, type Timeline, type TimelineBuilder, type TimelineInit, TimelineValidationError, type Track, TrackValidationError, type TweenOpts, type TweenTarget, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, type ValueType, type ValueTypeId, ValueTypeInferenceError, type Vec2, type Vec2Signal, WriteDuringEvaluationError, audioOffsetSamples, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/dist/index.js

@@ -865,8 +865,11 @@ var TrackValidationError = class extends Error {
 	}
 };
 function validateTrack(track) {
-	getValueType(track.type);
+	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];
@@ -960,7 +963,7 @@ function resolveEaseDerivative(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 = 1e-5;
+		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);
@@ -1048,7 +1051,13 @@ function sampleTrack(tr, t) {
 	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 = Math.min(1, Math.max(0, easedT));
+	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
@@ -1089,13 +1098,23 @@ function validateSpringKeys(tr) {
 		}
 	}
 }
+/**
+* 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, opaque, out) {
+function flatten(doc, at, timeScale, unit, out, counter) {
 	for (const tr of doc.tracks) {
 		validateTrack(tr);
 		validateSpringKeys(tr);
@@ -1104,14 +1123,15 @@ function flatten(doc, at, timeScale, opaque, out) {
 				...tr,
 				keys: rebaseKeys(tr.keys, at, timeScale)
 			},
-			opaque
+			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");
-		flatten(child.timeline, at + child.at / timeScale, timeScale * scale, opaque || child.mode === "sync", out);
+		const childUnit = child.mode === "sync" ? ++counter.n : unit;
+		flatten(child.timeline, at + child.at / timeScale, timeScale * scale, childUnit, out, counter);
 	}
 }
 /**
@@ -1121,25 +1141,31 @@ function flatten(doc, at, timeScale, opaque, out) {
 */
 function coalesce(entries) {
 	const byTarget = /* @__PURE__ */ new Map();
-	for (const { track: tr } of entries) {
+	for (const { track: tr, unit } of entries) {
 		const existing = byTarget.get(tr.target);
 		if (!existing) {
 			byTarget.set(tr.target, {
-				...tr,
-				keys: [...tr.keys]
+				track: {
+					...tr,
+					keys: [...tr.keys]
+				},
+				unit
 			});
 			continue;
 		}
-		if (existing.type !== tr.type) throw new TimelineValidationError(`target '${tr.target}' has conflicting value types '${existing.type}' and '${tr.type}'`);
+		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.keys[0].t;
-		const existingEnd = existing.keys[existing.keys.length - 1].t;
-		const kept = existing.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.keys.length - kept.length} earlier key(s) dropped)`);
-		existing.keys = [...kept, ...tr.keys].sort((a, b) => a.t - b.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);
 	}
-	return byTarget;
+	const result = /* @__PURE__ */ new Map();
+	for (const [target, { track }] of byTarget) result.set(target, track);
+	return result;
 }
 function childExtent(child) {
 	const scale = child.mode === "sync" ? child.timeScale ?? 1 : 1;
@@ -1159,7 +1185,7 @@ function computeDuration(doc) {
 function compileTimeline(doc) {
 	if (doc.version !== 1) throw new TimelineValidationError(`unsupported timeline document version ${String(doc.version)}`);
 	const flat = [];
-	flatten(doc, 0, 1, false, flat);
+	flatten(doc, 0, 1, 0, flat, { n: 0 });
 	const tracks = coalesce(flat);
 	const labels = { ...doc.labels };
 	const markers = [...doc.markers ?? []];
@@ -1667,11 +1693,16 @@ function mergeSidecar(code, sidecar) {
 		...code,
 		tracks
 	};
-	if (sidecar.labels && Object.keys(sidecar.labels).length > 0) merged.labels = {
-		...code.labels,
-		...sidecar.labels
-	};
+	if (sidecar.labels && Object.keys(sidecar.labels).length > 0) {
+		const codeLabels = code.labels ?? {};
+		const shadowed = Object.keys(sidecar.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 = {
+			...sidecar.labels,
+			...codeLabels
+		};
+	}
 	return merged;
 }
 //#endregion
-export { BakeError, CircularDependencyError, ColorParseError, DEFAULT_EASE, PositionError, SidecarVersionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };
+export { BakeError, CircularDependencyError, ColorParseError, DEFAULT_EASE, PositionError, SidecarVersionError, TARGET_PATH, TimelineValidationError, TrackValidationError, UnboundTargetError, UnknownEasingError, UnknownValueTypeError, UnresolvableTargetError, ValueTypeInferenceError, WriteDuringEvaluationError, audioOffsetSamples, bake, bakeCheckpointed, beginReadPhase, bindTimeline, booleanType, buildTimeline, colorType, compileTimeline, computed, createPlayhead, cubicBezier, cubicBezierDerivative, easingDerivatives, easings, emitDevWarning, emptySidecar, endReadPhase, evaluateAt, formatColor, getTimelineCallbacks, getValueType, inReadPhase, inferValueType, key, lerpColor, mergeSidecar, namedEasing, normalizeEditedKeys, numberType, oklabToRgba, parseColor, pathType, random, registerValueType, resolveEase, resolveEaseDerivative, resolveTweenTarget, rgbaToOklab, sampleTrack, setDevWarning, signal, spring, springEasing, springEasingDerivative, springPresets, springTo, stagger, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/package.json

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