@glissade/core 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -265,6 +265,14 @@ declare class TrackValidationError extends Error {
 declare function validateTrack(track: Track): void;
 type KeyOpts<T> = Partial<Omit<Key<T>, 't' | 'value'>>;
 declare function key<T>(t: number, value: T, easeOrOpts?: EaseSpec | KeyOpts<T>): Key<T>;
+/**
+ * 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)])
+ */
+declare function springTo<T>(endT: number, from: T, to: T, cfg: SpringConfig): [Key<T>, Key<T>];
 declare function track<T>(target: string, type: ValueTypeId, keys: Key<T>[], opts?: {
   editable?: boolean;
 }): Track<T>;
@@ -305,6 +313,14 @@ interface AssetRef {
   kind: 'font' | 'image' | 'audio' | 'video' | 'timeline';
   url: string;
 }
+/**
+ * A gain envelope: keys of linear gain multipliers on the clip's local time
+ * axis. A full Track satisfies it structurally, but its target/type carry no
+ * meaning here — `{ keys: [...] }` is all a clip needs.
+ */
+interface GainEnvelope {
+  keys: Key[];
+}
 /** Audio is timeline metadata, never a render product (§5.3). */
 interface AudioClip {
   asset: AssetRef;
@@ -315,8 +331,7 @@ interface AudioClip {
     start: number;
     end: number;
   };
-  /** gain envelope: a Track whose keys are linear gain multipliers */
-  gain?: Track;
+  gain?: GainEnvelope;
   playbackRate?: number;
 }
 interface ChildEntry {
@@ -539,4 +554,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 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, 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, 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, springTo, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/dist/index.js

@@ -864,6 +864,18 @@ function key(t, value, easeOrOpts) {
 	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))];
+}
 function track(target, type, keys, opts) {
 	const tr = {
 		target,
@@ -1609,4 +1621,4 @@ function mergeSidecar(code, sidecar) {
 	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, 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, 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, springTo, stringType, timeline, track, untracked, validateTrack, vec2Equals, vec2Signal, vec2Type, velocityAt };

package/package.json

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