tensum 0.1.0

package/src/gsap/active-tracks.ts

@@ -0,0 +1,244 @@
+import type { SpringState } from '../types.js';
+
+export interface ActiveTrackState extends SpringState {
+  unit?: string;
+}
+
+export interface ActiveTrackHandoffState extends ActiveTrackState {
+  terminal?: true;
+}
+
+export interface ActiveTrackSource {
+  state(globalTime?: number): ActiveTrackState;
+  restore(): void;
+}
+
+export interface ActiveTrackRegistration {
+  isActive(): boolean;
+  isOwner(): boolean;
+  activate(): void;
+  /**
+   * Marks a normally completed track as terminal. A terminal owner remains as
+   * the handoff baseline while covered historical tracks are discarded.
+   */
+  retire(): boolean;
+  release(options?: { restore?: boolean }): boolean;
+}
+
+interface TrackEntry {
+  active: boolean;
+  discarded: boolean;
+  order: number;
+  source: ActiveTrackSource;
+  terminal: boolean;
+}
+
+type PropertyTracks = Map<string, TrackEntry[]>;
+
+const objectTracks = new WeakMap<object, PropertyTracks>();
+let nextTrackOrder = 0;
+
+function isObjectKey(target: unknown): target is object {
+  return (
+    (typeof target === 'object' && target !== null) ||
+    typeof target === 'function'
+  );
+}
+
+function tracksFor(
+  target: unknown,
+  create: boolean,
+): PropertyTracks | undefined {
+  if (!isObjectKey(target)) {
+    if (create) {
+      throw new TypeError('active spring tracks require an object target');
+    }
+    return undefined;
+  }
+
+  const existing = objectTracks.get(target);
+  if (existing || !create) return existing;
+  const tracks = new Map<string, TrackEntry[]>();
+  objectTracks.set(target, tracks);
+  return tracks;
+}
+
+function stackFor(
+  target: unknown,
+  property: string,
+  create: boolean,
+): TrackEntry[] | undefined {
+  const tracks = tracksFor(target, create);
+  if (!tracks) return undefined;
+  const existing = tracks.get(property);
+  if (existing || !create) return existing;
+  const stack: TrackEntry[] = [];
+  tracks.set(property, stack);
+  return stack;
+}
+
+function cleanup(target: unknown, property: string): void {
+  const tracks = tracksFor(target, false);
+  if (!tracks) return;
+  const stack = tracks.get(property);
+  if (stack?.length === 0) tracks.delete(property);
+  if (tracks.size !== 0) return;
+  if (isObjectKey(target)) objectTracks.delete(target);
+}
+
+export function activeTrackState(
+  target: unknown,
+  property: string,
+  globalTime?: number,
+): ActiveTrackHandoffState | undefined {
+  const owner = stackFor(target, property, false)?.at(-1);
+  if (!owner) return undefined;
+  return {
+    ...owner.source.state(globalTime),
+    ...(owner.terminal ? { terminal: true as const } : {}),
+  };
+}
+
+/**
+ * Invalidates a terminal handoff baseline after an external write. The whole
+ * property history is discarded so reversing an older tween cannot restore a
+ * value that no longer represents the target.
+ */
+function discardTerminalTrackHistory(
+  target: unknown,
+  property: string,
+): boolean {
+  const stack = stackFor(target, property, false);
+  if (!stack?.at(-1)?.terminal) return false;
+  for (const entry of stack) {
+    entry.active = false;
+    entry.discarded = true;
+    entry.terminal = false;
+  }
+  stack.length = 0;
+  cleanup(target, property);
+  return true;
+}
+
+function positionsMatch(first: number, second: number): boolean {
+  const floatingPointTolerance =
+    Number.EPSILON * Math.max(1, Math.abs(first), Math.abs(second)) * 8;
+  return Math.abs(first - second) <= Math.max(1e-9, floatingPointTolerance);
+}
+
+/**
+ * Preserves a live/unchanged handoff, but atomically invalidates terminal
+ * history when the target was externally changed after completion.
+ */
+export function reconcileActiveTrackHandoff(
+  target: unknown,
+  property: string,
+  inherited: ActiveTrackHandoffState | undefined,
+  actualPosition: number,
+  actualUnit: string | undefined,
+): ActiveTrackHandoffState | undefined {
+  if (
+    !inherited?.terminal ||
+    (positionsMatch(inherited.position, actualPosition) &&
+      inherited.unit === actualUnit)
+  ) {
+    return inherited;
+  }
+  discardTerminalTrackHistory(target, property);
+  return undefined;
+}
+
+export function registerActiveTrack(
+  target: unknown,
+  property: string,
+  source: ActiveTrackSource,
+): ActiveTrackRegistration {
+  const entry: TrackEntry = {
+    active: false,
+    discarded: false,
+    order: nextTrackOrder++,
+    source,
+    terminal: false,
+  };
+
+  const activate = (): void => {
+    if (entry.active || entry.discarded) return;
+    const stack = stackFor(target, property, true)!;
+    const nextIndex = stack.findIndex(
+      (candidate) => candidate.order > entry.order,
+    );
+    if (nextIndex < 0) stack.push(entry);
+    else stack.splice(nextIndex, 0, entry);
+    entry.active = true;
+  };
+
+  const release = (options: { restore?: boolean } = {}): boolean => {
+    if (!entry.active) return false;
+    const stack = stackFor(target, property, false);
+    if (!stack) {
+      entry.active = false;
+      entry.terminal = false;
+      return false;
+    }
+    const index = stack.indexOf(entry);
+    if (index < 0) {
+      entry.active = false;
+      entry.terminal = false;
+      return false;
+    }
+    const wasOwner = index === stack.length - 1;
+    stack.splice(index, 1);
+    entry.active = false;
+    entry.terminal = false;
+    const previous = wasOwner ? stack.at(-1) : undefined;
+    if (previous && options.restore !== false) previous.source.restore();
+    cleanup(target, property);
+    return previous !== undefined && options.restore !== false;
+  };
+
+  const retire = (): boolean => {
+    if (!entry.active || entry.discarded) return false;
+    const stack = stackFor(target, property, false);
+    if (!stack) {
+      entry.active = false;
+      entry.terminal = false;
+      return false;
+    }
+    const index = stack.indexOf(entry);
+    if (index < 0) {
+      entry.active = false;
+      entry.terminal = false;
+      return false;
+    }
+
+    if (index === stack.length - 1) {
+      const covered = stack.splice(0, index);
+      for (const candidate of covered) {
+        candidate.active = false;
+        candidate.terminal = false;
+      }
+      entry.terminal = true;
+      return true;
+    }
+
+    stack.splice(index, 1);
+    entry.active = false;
+    entry.terminal = false;
+    cleanup(target, property);
+    return true;
+  };
+
+  activate();
+  return Object.freeze({
+    isActive(): boolean {
+      return entry.active;
+    },
+    isOwner(): boolean {
+      if (!entry.active) return false;
+      return stackFor(target, property, false)?.at(-1) === entry;
+    },
+    activate,
+    retire,
+    release,
+  });
+}

package/src/gsap/gsap-time.ts

@@ -0,0 +1,91 @@
+interface GlobalTimeAnimation {
+  globalTime(rawTime?: number): number;
+}
+
+function withGlobalTime(animation: gsap.core.Tween): GlobalTimeAnimation {
+  return animation as gsap.core.Tween & GlobalTimeAnimation;
+}
+
+export function globalTimeAt(
+  animation: gsap.core.Tween,
+  localTime: number,
+): number {
+  return withGlobalTime(animation).globalTime(localTime);
+}
+
+export function localTimeAt(
+  animation: gsap.core.Tween,
+  globalTime: number,
+): number {
+  if (animation.paused()) return animation.totalTime();
+  const globalStart = globalTimeAt(animation, 0);
+  const globalNextSecond = globalTimeAt(animation, 1);
+  const globalSecondsPerLocalSecond = globalNextSecond - globalStart;
+  if (
+    !Number.isFinite(globalSecondsPerLocalSecond) ||
+    globalSecondsPerLocalSecond === 0
+  ) {
+    return animation.time();
+  }
+  return Math.max(0, (globalTime - globalStart) / globalSecondsPerLocalSecond);
+}
+
+export interface LocalCycle {
+  time: number;
+  direction: 1 | 0 | -1;
+}
+
+function cycleAtTotalTime(
+  animation: gsap.core.Tween,
+  totalTime: number,
+): LocalCycle {
+  const duration = animation.duration();
+  const playbackDirection = animation.reversed() ? -1 : 1;
+  if (!(duration > 0)) return { time: 0, direction: playbackDirection };
+
+  const repeat = animation.repeat();
+  if (repeat === 0) {
+    return {
+      time: Math.min(totalTime, duration),
+      direction: playbackDirection,
+    };
+  }
+
+  const cycleDuration = duration + animation.repeatDelay();
+  if (!(cycleDuration > 0)) return { time: 0, direction: playbackDirection };
+
+  const finiteEnd = repeat >= 0 ? animation.totalDuration() : Infinity;
+  const boundedTotalTime = Math.min(totalTime, finiteEnd);
+  if (repeat >= 0 && boundedTotalTime >= finiteEnd) {
+    const yoyoReversed = animation.yoyo() && repeat % 2 === 1;
+    return {
+      time: yoyoReversed ? 0 : duration,
+      direction: (((yoyoReversed ? -1 : 1) * playbackDirection) as 1 | -1),
+    };
+  }
+
+  const cycle = Math.floor(boundedTotalTime / cycleDuration);
+  const yoyoReversed = animation.yoyo() && cycle % 2 === 1;
+  const cycleTime = boundedTotalTime - cycle * cycleDuration;
+  const forwardTime = Math.min(cycleTime, duration);
+  return {
+    time: yoyoReversed ? duration - forwardTime : forwardTime,
+    direction:
+      cycleTime > duration
+        ? 0
+        : (((yoyoReversed ? -1 : 1) * playbackDirection) as 1 | -1),
+  };
+}
+
+export function currentLocalCycle(animation: gsap.core.Tween): LocalCycle {
+  return cycleAtTotalTime(animation, animation.totalTime());
+}
+
+/** Maps a global instant to GSAP's cycle-local time, including repeat/yoyo. */
+export function localCycleAt(
+  animation: gsap.core.Tween,
+  globalTime: number,
+): LocalCycle {
+  const totalTime = localTimeAt(animation, globalTime);
+  return cycleAtTotalTime(animation, totalTime);
+}

package/src/gsap/plugin-tween-coordinator.ts

@@ -0,0 +1,112 @@
+export interface PluginTweenTiming {
+  finiteDuration: number;
+  infinite: boolean;
+}
+
+export interface PluginTweenParticipant {
+  timing(): PluginTweenTiming;
+  dispose(): void;
+}
+
+export interface PluginTweenRegistration {
+  recompute(): void;
+  remove(): void;
+}
+
+export interface PluginTweenState {
+  tween: gsap.core.Tween;
+  baseDuration: number;
+  baseRepeat: number;
+  participants: Set<PluginTweenParticipant>;
+  generationTargets: Set<object>;
+}
+
+const states = new WeakMap<gsap.core.Tween, PluginTweenState>();
+function applyTiming(state: PluginTweenState): void {
+  let finiteDuration = 0;
+  let infinite = false;
+  for (const participant of state.participants) {
+    const timing = participant.timing();
+    finiteDuration = Math.max(finiteDuration, timing.finiteDuration);
+    infinite ||= timing.infinite;
+  }
+
+  if (infinite) {
+    state.tween.duration(1);
+    state.tween.repeat(-1);
+    return;
+  }
+
+  state.tween.repeat(state.baseRepeat);
+  state.tween.duration(
+    gsapSafeDuration(
+      state.participants.size === 0 ? state.baseDuration : finiteDuration,
+    ),
+  );
+}
+
+function disposeParticipants(state: PluginTweenState): void {
+  for (const participant of state.participants) participant.dispose();
+  state.participants.clear();
+}
+
+/**
+ * Starts one GSAP plugin init generation. Seeing the same target again marks a
+ * fresh generation after `invalidate()`, including stagger children whose
+ * source-array index isn't zero.
+ */
+export function beginPluginTweenInit(
+  tween: gsap.core.Tween,
+  target: object,
+  options: { baseDuration: number; baseRepeat: number },
+): PluginTweenState {
+  let state = states.get(tween);
+  if (!state) {
+    state = {
+      tween,
+      baseDuration: options.baseDuration,
+      baseRepeat: options.baseRepeat,
+      participants: new Set(),
+      generationTargets: new Set([target]),
+    };
+    states.set(tween, state);
+
+    const previousInterrupt = tween.eventCallback('onInterrupt');
+    tween.eventCallback('onInterrupt', () => {
+      disposeParticipants(state!);
+      previousInterrupt?.apply(
+        tween.vars.callbackScope ?? tween,
+        tween.vars.onInterruptParams ?? [],
+      );
+    });
+  } else if (state.generationTargets.has(target)) {
+    disposeParticipants(state);
+    applyTiming(state);
+    state.generationTargets.clear();
+  }
+  state.generationTargets.add(target);
+
+  return state;
+}
+
+export function registerPluginTweenParticipant(
+  state: PluginTweenState,
+  participant: PluginTweenParticipant,
+): PluginTweenRegistration {
+  state.participants.add(participant);
+  applyTiming(state);
+  let active = true;
+
+  return {
+    recompute(): void {
+      if (active) applyTiming(state);
+    },
+    remove(): void {
+      if (!active) return;
+      active = false;
+      state.participants.delete(participant);
+      applyTiming(state);
+    },
+  };
+}
+import { gsapSafeDuration } from './spring-track-policy.js';