@pibbl/core 0.0.1

package/dist/lib/animation/playback.js

@@ -0,0 +1,932 @@
+import {
+  getSignalNode,
+  signal
+} from "../signals/graph.js";
+import {
+  queueBeginCommand,
+  queueCurrentFrameCommitAcknowledgement,
+  queueCurrentFrameCompletion,
+  queueCurrentFrameOrderedPlaybackCompletion,
+  recordSchedulerTrace,
+  registerAdvanceParticipant,
+  snapshotRealmScheduler
+} from "../scheduler/realm-scheduler.js";
+import { getDefinitionRecord } from "./definition.js";
+import { sampleSpring } from "./spring.js";
+import {
+  adoptProgramActivationFork,
+  evaluateProgram,
+  finishProgram,
+  forkProgramActivation,
+  getProgramActivationRecord,
+  preflightProgramActivation,
+  releaseProgramActivation,
+  seekProgram
+} from "./evaluate.js";
+import { getProgramRecord } from "./program.js";
+import {
+  acquireTransactionalProgramWriterLeases,
+  preflightProgramWriterLeaseAcquisition
+} from "./writer-leases.js";
+let nextPlaybackRegistrationOrder = 0;
+let activePlaybacks = 0;
+let createdPlaybacks = 0;
+let releasedPlaybacks = 0;
+let queuedCommands = 0;
+let queuedMilestones = 0;
+let outputStageAttempts = 0;
+let activePlaybackBeginContext;
+function animationPlaybackSnapshot() {
+  return Object.freeze({
+    activePlaybacks,
+    createdPlaybacks,
+    releasedPlaybacks,
+    queuedCommands,
+    queuedMilestones,
+    outputStageAttempts
+  });
+}
+function freezePath(path) {
+  return Object.freeze([...path]);
+}
+function playbackEvent(type, snapshot, programPath = [], iteration = 0, marker) {
+  return Object.freeze({
+    type,
+    logicalTime: snapshot.logicalTime,
+    frameId: snapshot.frameId,
+    programPath: freezePath(programPath),
+    iteration,
+    ...marker === void 0 ? {} : { marker }
+  });
+}
+function validateOptions(options) {
+  if (options.conflict !== void 0 && options.conflict !== "error" && options.conflict !== "replace") {
+    throw new TypeError('Pibbl animation playback conflict must be "error" or "replace".');
+  }
+  if (options.debugName !== void 0 && (typeof options.debugName !== "string" || options.debugName.length === 0)) {
+    throw new TypeError("Pibbl animation playback debugName must be nonempty when provided.");
+  }
+  if (options.onEvent !== void 0 && typeof options.onEvent !== "function") {
+    throw new TypeError("Pibbl animation playback onEvent must be a function.");
+  }
+  if (options.onError !== void 0 && typeof options.onError !== "function") {
+    throw new TypeError("Pibbl animation playback onError must be a function.");
+  }
+}
+function normalizeAnimationPlaybackCandidate(program, options = {}) {
+  getProgramRecord(program);
+  const normalizedOptions = Object.freeze({ ...options });
+  validateOptions(normalizedOptions);
+  return Object.freeze({ program, options: normalizedOptions });
+}
+function firstStepperName(program) {
+  const record = getProgramRecord(program);
+  if (record.kind === "track") {
+    const definition = getDefinitionRecord(record.definition);
+    return definition.kind === "stepper" ? definition.debugName : void 0;
+  }
+  for (const child of record.children) {
+    const name = firstStepperName(child);
+    if (name !== void 0) return name;
+  }
+  return void 0;
+}
+function unavailableControlError(program, control) {
+  const duration = getProgramRecord(program).duration;
+  if (duration.kind === "infinite") {
+    return new TypeError(
+      `Pibbl animation program is infinite; ${control} is unavailable.`
+    );
+  }
+  if (duration.kind === "unresolved-stepper") {
+    const name = firstStepperName(program);
+    const label = name === void 0 ? "Pibbl animation stateful program" : `Pibbl animation stepper "${name}"`;
+    return new TypeError(
+      `${label} terminal time is not discovered; ${control} is unavailable.`
+    );
+  }
+  return void 0;
+}
+function finiteDuration(duration) {
+  return duration.kind === "finite" ? duration.milliseconds : void 0;
+}
+function createAnimationPlaybackController(initialProgram, initialOptions = {}) {
+  const initialCandidate = normalizeAnimationPlaybackCandidate(
+    initialProgram,
+    initialOptions
+  );
+  let program = initialCandidate.program;
+  let options = initialCandidate.options;
+  let disposed = false;
+  let queuedGeneration = 0;
+  let run;
+  let storedPlaybackRate = 1;
+  let delivery;
+  let pendingRetarget;
+  const pendingCommands = /* @__PURE__ */ new Set();
+  const metadataWriter = Object.freeze({ name: "Pibbl playback metadata" });
+  const status = signal("idle", {
+    debugName: options.debugName === void 0 ? void 0 : `${options.debugName} status`
+  });
+  const currentTime = signal(0, {
+    debugName: options.debugName === void 0 ? void 0 : `${options.debugName} current time`
+  });
+  function debugName() {
+    return options.debugName;
+  }
+  function ensureDelivery(snapshot) {
+    if (delivery?.frameId === snapshot.frameId) return delivery;
+    const current = {
+      frameId: snapshot.frameId,
+      logicalTime: snapshot.logicalTime,
+      events: [],
+      errors: [],
+      terminalRuns: /* @__PURE__ */ new Set(),
+      writes: [],
+      commitApplied: false
+    };
+    delivery = current;
+    queueCurrentFrameCommitAcknowledgement((_snapshot, outcome) => {
+      current.commitApplied = outcome.applied;
+    });
+    queueCurrentFrameCompletion(() => {
+      if (delivery === current) delivery = void 0;
+      if (!current.commitApplied) {
+        queuedMilestones -= current.events.length;
+      } else {
+        for (const terminalRun of current.terminalRuns) releaseRun(terminalRun);
+        for (const write of current.writes) {
+          const node = getSignalNode(write.signal);
+          recordSchedulerTrace({
+            kind: "animation-write",
+            frameId: current.frameId,
+            logicalTime: current.logicalTime,
+            debugName: debugName(),
+            target: write.target,
+            outcome: node.version === write.version ? "equality-suppressed" : "staged"
+          });
+        }
+        for (const { event, registrationOrder } of current.events) {
+          queueCurrentFrameOrderedPlaybackCompletion(registrationOrder, () => {
+            queuedMilestones--;
+            if (!disposed) options.onEvent?.(event);
+          });
+        }
+      }
+      for (const { error, registrationOrder, commitRequired } of current.errors) {
+        if (commitRequired && !current.commitApplied) continue;
+        queueCurrentFrameOrderedPlaybackCompletion(registrationOrder, () => {
+          if (disposed) return;
+          if (options.onError) options.onError(error);
+          else throw error;
+        });
+      }
+    });
+    return current;
+  }
+  function queueEvent(snapshot, event, registrationOrder) {
+    const frame = ensureDelivery(snapshot);
+    frame.events.push({ event, registrationOrder });
+    queuedMilestones++;
+    recordSchedulerTrace({
+      kind: "animation-milestone",
+      frameId: snapshot.frameId,
+      logicalTime: snapshot.logicalTime,
+      debugName: debugName(),
+      event: event.type,
+      programPath: event.programPath,
+      iteration: event.iteration
+    });
+  }
+  function queueError(snapshot, error, registrationOrder, trace = true, commitRequired = true) {
+    ensureDelivery(snapshot).errors.push({ error, registrationOrder, commitRequired });
+    if (trace) {
+      recordSchedulerTrace({
+        kind: "animation-error",
+        frameId: snapshot.frameId,
+        logicalTime: snapshot.logicalTime,
+        debugName: debugName(),
+        error
+      });
+    }
+  }
+  function queueDiagnosticError(snapshot, error, registrationOrder) {
+    queueError(snapshot, error, registrationOrder, true, false);
+  }
+  function queuePendingStart(target, snapshot) {
+    if (!target.startPending || target.startQueuedFrameId === snapshot.frameId) return;
+    target.startQueuedFrameId = snapshot.frameId;
+    queueEvent(snapshot, playbackEvent("start", snapshot), target.registrationOrder);
+    queueCurrentFrameCommitAcknowledgement((_committedSnapshot, outcome) => {
+      if (outcome.applied && !target.released) target.startPending = false;
+    });
+  }
+  function stage(batch, snapshot, target, value, label) {
+    const node = getSignalNode(target);
+    ensureDelivery(snapshot).writes.push({
+      signal: target,
+      version: node.version,
+      target: label
+    });
+    batch.stage(target, value, metadataWriter);
+  }
+  function stageStatus(batch, snapshot, value) {
+    stage(batch, snapshot, status, value, "status");
+  }
+  function stageCurrentTime(batch, snapshot, value) {
+    stage(batch, snapshot, currentTime, value, "currentTime");
+  }
+  function releaseRun(target) {
+    if (target.released) return;
+    target.released = true;
+    target.unregisterAdvance?.();
+    target.unregisterAdvance = void 0;
+    target.lease.release();
+    releaseProgramActivation(target.activation);
+    activePlaybacks--;
+    releasedPlaybacks++;
+    if (run === target) run = void 0;
+  }
+  function scheduleTerminal(snapshot, target) {
+    ensureDelivery(snapshot).terminalRuns.add(target);
+  }
+  function cancelRun(target, snapshot, batch, releaseImmediately = false) {
+    if (target.status === "ending") return;
+    queuePendingStart(target, snapshot);
+    const previousStatus = target.status;
+    target.status = "ending";
+    stageStatus(batch, snapshot, "cancelled");
+    queueEvent(snapshot, playbackEvent("cancel", snapshot), target.registrationOrder);
+    if (releaseImmediately) {
+      target.unregisterAdvance?.();
+      target.unregisterAdvance = void 0;
+      scheduleTerminal(snapshot, target);
+      releaseRun(target);
+      return;
+    }
+    queueCurrentFrameCommitAcknowledgement((_committedSnapshot, outcome) => {
+      if (disposed || run !== target || target.released) return;
+      if (!outcome.applied) {
+        target.status = previousStatus;
+        enqueue("cancel", target.generation);
+        return;
+      }
+      target.unregisterAdvance?.();
+      target.unregisterAdvance = void 0;
+      scheduleTerminal(snapshot, target);
+    });
+  }
+  function beginRunReplacement(target, snapshot, batch) {
+    if (target.status === "ending" || target.released) {
+      throw new Error("Pibbl animation playback run is already ending.");
+    }
+    const previousStatus = target.status;
+    const previousStartPending = target.startPending;
+    const wasRegistered = target.unregisterAdvance !== void 0;
+    queuePendingStart(target, snapshot);
+    target.status = "ending";
+    target.unregisterAdvance?.();
+    target.unregisterAdvance = void 0;
+    stageStatus(batch, snapshot, "cancelled");
+    queueEvent(snapshot, playbackEvent("cancel", snapshot), target.registrationOrder);
+    let pending = true;
+    return Object.freeze({
+      commit() {
+        if (!pending) return;
+        pending = false;
+        scheduleTerminal(snapshot, target);
+      },
+      rollback() {
+        if (!pending) return;
+        pending = false;
+        if (target.released) return;
+        if (disposed) {
+          releaseRun(target);
+          return;
+        }
+        target.status = previousStatus;
+        target.startPending = previousStartPending;
+        if (wasRegistered) registerRun(target);
+      }
+    });
+  }
+  function queueEvaluationTraces(target, snapshot, result, stagedOutputs, sampledTime) {
+    recordSchedulerTrace({
+      kind: "animation-sample",
+      frameId: snapshot.frameId,
+      logicalTime: snapshot.logicalTime,
+      registrationOrder: target.registrationOrder,
+      debugName: debugName(),
+      localTime: sampledTime,
+      direction: target.direction
+    });
+    for (const output of stagedOutputs) {
+      ensureDelivery(snapshot).writes.push({
+        signal: output,
+        version: getSignalNode(output).version,
+        target: getSignalNode(output).debugName ?? "<unnamed signal>"
+      });
+    }
+    for (const trace of result.steppers) {
+      recordSchedulerTrace({
+        kind: "animation-stepper",
+        frameId: snapshot.frameId,
+        logicalTime: snapshot.logicalTime,
+        debugName: debugName(),
+        programPath: trace.programPath,
+        repeatIterations: trace.repeatIterations,
+        appliedSteps: trace.appliedSteps,
+        retainedRemainderMilliseconds: trace.retainedRemainderMilliseconds,
+        clampedElapsedMilliseconds: trace.clampedElapsedMilliseconds,
+        discardedElapsedMilliseconds: trace.discardedElapsedMilliseconds
+      });
+    }
+  }
+  function queueEvaluationMilestones(target, snapshot, result) {
+    for (const milestone of result.milestones) {
+      queueEvent(snapshot, playbackEvent(
+        milestone.kind,
+        snapshot,
+        milestone.programPath,
+        milestone.iteration,
+        milestone.kind === "marker" ? milestone.marker : void 0
+      ), target.registrationOrder);
+    }
+  }
+  function clampRunTime(target, candidate) {
+    const record = getProgramActivationRecord(target.activation);
+    const knownDuration = record.terminalDuration ?? finiteDuration(getProgramRecord(target.program).duration);
+    return Math.max(0, knownDuration === void 0 ? candidate : Math.min(candidate, knownDuration));
+  }
+  function registerRun(target) {
+    if (target.unregisterAdvance !== void 0 || target.released) return;
+    target.unregisterAdvance = registerAdvanceParticipant((snapshot, batch) => {
+      if (disposed || run !== target || target.released || target.status === "ending") return;
+      advanceRun(target, snapshot, batch);
+    }, "animation");
+  }
+  function advanceRun(target, snapshot, batch) {
+    queuePendingStart(target, snapshot);
+    const evaluationActivation = forkProgramActivation(target.activation);
+    const stagedOutputs = /* @__PURE__ */ new Set();
+    const evaluationBatch = {
+      read(value) {
+        return batch.read(value);
+      },
+      stage(value, nextValue, writer) {
+        batch.stage(value, nextValue, writer);
+        if (writer === target.token) {
+          outputStageAttempts++;
+          stagedOutputs.add(value);
+        }
+      },
+      discardWriter(writer) {
+        batch.discardWriter(writer);
+      },
+      registerLifecycle(writer, lifecycle) {
+        batch.registerLifecycle(writer, lifecycle);
+      },
+      commit() {
+        batch.commit();
+      },
+      clear() {
+        batch.clear();
+      }
+    };
+    const pending = target.pendingEvaluation;
+    let destination = pending?.kind === "seek" ? pending.time : target.anchorPosition + (target.direction === "forward" ? 1 : -1) * (snapshot.logicalTime - target.anchorLogicalTime) * target.playbackRate;
+    destination = clampRunTime(target, destination);
+    let result;
+    try {
+      if (pending?.kind === "finish") {
+        const staticDuration = finiteDuration(getProgramRecord(target.program).duration);
+        if (staticDuration === void 0) {
+          result = finishProgram(evaluationActivation, {
+            previousTime: target.previousTime,
+            frameId: snapshot.frameId,
+            writer: target.token,
+            batch: evaluationBatch
+          });
+        } else {
+          result = seekProgram(evaluationActivation, {
+            previousTime: target.previousTime,
+            time: staticDuration,
+            direction: "forward",
+            frameId: snapshot.frameId,
+            writer: target.token,
+            batch: evaluationBatch
+          });
+        }
+      } else if (pending?.kind === "seek") {
+        result = seekProgram(evaluationActivation, {
+          previousTime: target.previousTime,
+          time: destination,
+          direction: pending.direction ?? (destination < target.position ? "reverse" : "forward"),
+          frameId: snapshot.frameId,
+          writer: target.token,
+          batch: evaluationBatch
+        });
+      } else {
+        result = evaluateProgram(evaluationActivation, {
+          previousTime: target.previousTime,
+          time: destination,
+          direction: target.direction,
+          frameId: snapshot.frameId,
+          writer: target.token,
+          batch: evaluationBatch
+        });
+      }
+    } catch (error) {
+      releaseProgramActivation(evaluationActivation);
+      batch.discardWriter(target.token);
+      stageStatus(batch, snapshot, "cancelled");
+      recordSchedulerTrace({
+        kind: "animation-error",
+        frameId: snapshot.frameId,
+        logicalTime: snapshot.logicalTime,
+        debugName: debugName(),
+        error
+      });
+      queueCurrentFrameCommitAcknowledgement((_committedSnapshot, outcome) => {
+        if (!outcome.applied || disposed || run !== target || target.released) return;
+        target.status = "ending";
+        target.unregisterAdvance?.();
+        target.unregisterAdvance = void 0;
+        queueEvent(snapshot, playbackEvent("cancel", snapshot), target.registrationOrder);
+        queueError(snapshot, error, target.registrationOrder, false);
+        scheduleTerminal(snapshot, target);
+      });
+      return;
+    }
+    if (disposed || run !== target || target.released) {
+      releaseProgramActivation(evaluationActivation);
+      batch.discardWriter(target.token);
+      return;
+    }
+    const duration = result.terminal.duration;
+    const presentedTime = duration !== void 0 && Number.isFinite(duration) && result.terminal.atEnd ? duration : destination;
+    stageCurrentTime(batch, snapshot, presentedTime);
+    queueEvaluationTraces(target, snapshot, result, stagedOutputs, presentedTime);
+    const terminalReached = target.status === "running" && result.terminal.reached || pending?.kind === "finish";
+    if (terminalReached) {
+      stageStatus(batch, snapshot, "finished");
+    } else {
+      stageStatus(batch, snapshot, target.status === "paused" ? "paused" : "running");
+    }
+    queueCurrentFrameCommitAcknowledgement((_committedSnapshot, outcome) => {
+      if (!outcome.applied || disposed || run !== target || target.released) {
+        releaseProgramActivation(evaluationActivation);
+        return;
+      }
+      adoptProgramActivationFork(target.activation, evaluationActivation);
+      target.position = presentedTime;
+      target.previousTime = presentedTime;
+      if (pending?.kind === "seek") {
+        target.anchorPosition = presentedTime;
+        target.anchorLogicalTime = snapshot.logicalTime;
+      }
+      target.pendingEvaluation = void 0;
+      queueEvaluationMilestones(target, snapshot, result);
+      if (terminalReached) {
+        target.unregisterAdvance?.();
+        target.unregisterAdvance = void 0;
+        queueEvent(snapshot, playbackEvent("finish", snapshot), target.registrationOrder);
+        scheduleTerminal(snapshot, target);
+      } else if (target.status === "paused") {
+        target.unregisterAdvance?.();
+        target.unregisterAdvance = void 0;
+      }
+    });
+  }
+  function createRun(generation, snapshot, batch, conflict, ignoredToken) {
+    const registration = Object.freeze({});
+    const registrationOrder = ++nextPlaybackRegistrationOrder;
+    const token = Object.freeze({ registrationOrder });
+    let target;
+    try {
+      const lease = acquireTransactionalProgramWriterLeases(program, registration, {
+        token,
+        registrationOrder,
+        debugName: debugName(),
+        cancel() {
+          if (target !== void 0 && !target.released) {
+            const context = activePlaybackBeginContext;
+            if (context === void 0) releaseRun(target);
+            else cancelRun(target, context.snapshot, context.batch, true);
+          }
+        },
+        preflightReplacement() {
+          if (target === void 0 || target.released) {
+            throw new Error("Pibbl animation replacement owner is unavailable.");
+          }
+          if (activePlaybackBeginContext === void 0) {
+            throw new Error("Pibbl animation replacement must begin during Begin.");
+          }
+          if (target.status === "ending") {
+            throw new Error("Pibbl animation playback run is already ending.");
+          }
+        },
+        beginReplacement() {
+          if (target === void 0 || target.released) {
+            throw new Error("Pibbl animation replacement owner is unavailable.");
+          }
+          const context = activePlaybackBeginContext;
+          if (context === void 0) {
+            throw new Error("Pibbl animation replacement must begin during Begin.");
+          }
+          return beginRunReplacement(target, context.snapshot, context.batch);
+        }
+      }, { conflict, ignoredToken });
+      target = {
+        generation,
+        registration,
+        registrationOrder,
+        token,
+        lease,
+        activation: lease.activation,
+        program,
+        direction: "forward",
+        playbackRate: storedPlaybackRate,
+        position: 0,
+        anchorPosition: 0,
+        anchorLogicalTime: snapshot.logicalTime,
+        previousTime: void 0,
+        status: "running",
+        pendingEvaluation: void 0,
+        unregisterAdvance: void 0,
+        released: false,
+        startPending: false,
+        startQueuedFrameId: void 0
+      };
+    } catch (error) {
+      stageStatus(batch, snapshot, "cancelled");
+      queueDiagnosticError(snapshot, error, registrationOrder);
+      return void 0;
+    }
+    run = target;
+    activePlaybacks++;
+    createdPlaybacks++;
+    return target;
+  }
+  function settleProvisionalRun(target, previousRun, additionalReplacement) {
+    if (target.lease.replacedOwnerCount === 0 && additionalReplacement === void 0) return;
+    queueCurrentFrameCommitAcknowledgement((_snapshot, outcome) => {
+      if (outcome.applied) {
+        target.lease.commitReplacement();
+        additionalReplacement?.commit();
+        return;
+      }
+      const targetAlreadyReleased = target.released;
+      target.unregisterAdvance?.();
+      target.unregisterAdvance = void 0;
+      target.released = true;
+      if (run === target) run = previousRun;
+      if (previousRun !== void 0) queuedGeneration = previousRun.generation;
+      if (!targetAlreadyReleased) {
+        if (target.lease.replacedOwnerCount === 0) target.lease.release();
+        else target.lease.rollbackReplacement();
+      }
+      additionalReplacement?.rollback();
+      if (!targetAlreadyReleased) {
+        releaseProgramActivation(target.activation);
+        activePlaybacks--;
+        releasedPlaybacks++;
+      }
+    });
+  }
+  function acceptPlay(generation, conflict, snapshot, batch) {
+    try {
+      if (conflict === "error") {
+        preflightProgramWriterLeaseAcquisition(program, run?.token);
+      } else {
+        preflightProgramActivation(program);
+      }
+    } catch (error) {
+      if (run === void 0 || run.status === "ending") {
+        stageStatus(batch, snapshot, "cancelled");
+      } else if (queuedGeneration === generation) {
+        queuedGeneration = run.generation;
+      }
+      queueDiagnosticError(
+        snapshot,
+        error,
+        run?.registrationOrder ?? Number.MAX_SAFE_INTEGER
+      );
+      return;
+    }
+    const previousRun = run;
+    const target = createRun(
+      generation,
+      snapshot,
+      batch,
+      conflict,
+      previousRun?.token
+    );
+    if (target === void 0) return;
+    let additionalReplacement;
+    if (previousRun !== void 0 && !previousRun.released && previousRun.status !== "ending") {
+      additionalReplacement = beginRunReplacement(previousRun, snapshot, batch);
+    }
+    stageStatus(batch, snapshot, "scheduled");
+    stageCurrentTime(batch, snapshot, 0);
+    stageStatus(batch, snapshot, "running");
+    target.startPending = true;
+    queuePendingStart(target, snapshot);
+    registerRun(target);
+    settleProvisionalRun(target, previousRun, additionalReplacement);
+  }
+  function acceptFreshControl(generation, command, snapshot, batch, seekTime) {
+    if (command !== "seek") {
+      const error = unavailableControlError(program, command);
+      if (error !== void 0) {
+        queueDiagnosticError(snapshot, error, Number.MAX_SAFE_INTEGER);
+        return;
+      }
+    }
+    const target = createRun(
+      generation,
+      snapshot,
+      batch,
+      options.conflict ?? "error"
+    );
+    if (target === void 0) return;
+    target.status = command === "reverse" ? "running" : "paused";
+    if (command === "reverse") {
+      const duration = finiteDuration(getProgramRecord(target.program).duration);
+      target.direction = "reverse";
+      target.position = duration;
+      target.anchorPosition = duration;
+      target.pendingEvaluation = { kind: "seek", time: duration, direction: "reverse" };
+      stageStatus(batch, snapshot, "scheduled");
+      stageStatus(batch, snapshot, "running");
+      target.startPending = true;
+    } else if (command === "finish") {
+      target.status = "running";
+      target.pendingEvaluation = { kind: "finish" };
+      stageStatus(batch, snapshot, "scheduled");
+      stageStatus(batch, snapshot, "running");
+      target.startPending = true;
+    } else {
+      const staticDuration = finiteDuration(getProgramRecord(target.program).duration);
+      target.pendingEvaluation = {
+        kind: "seek",
+        time: Math.max(0, staticDuration === void 0 ? seekTime : Math.min(seekTime, staticDuration))
+      };
+      stageStatus(batch, snapshot, "paused");
+    }
+    queuePendingStart(target, snapshot);
+    registerRun(target);
+    settleProvisionalRun(target, void 0, void 0);
+  }
+  function enqueue(command, generation, argument) {
+    if (disposed) return void 0;
+    queuedCommands++;
+    let commandHandle;
+    commandHandle = queueBeginCommand((snapshot, batch, sequence) => {
+      pendingCommands.delete(commandHandle);
+      if (pendingRetarget === commandHandle) pendingRetarget = void 0;
+      queuedCommands--;
+      if (disposed || generation !== queuedGeneration) return;
+      recordSchedulerTrace({
+        kind: "animation-command",
+        frameId: snapshot.frameId,
+        logicalTime: snapshot.logicalTime,
+        sequence,
+        command,
+        debugName: debugName()
+      });
+      const previousContext = activePlaybackBeginContext;
+      activePlaybackBeginContext = { snapshot, batch };
+      try {
+        acceptCommandWithoutTrace(command, generation, snapshot, batch, argument);
+      } finally {
+        activePlaybackBeginContext = previousContext;
+      }
+    });
+    pendingCommands.add(commandHandle);
+    return commandHandle;
+  }
+  function acceptCommandWithoutTrace(command, generation, snapshot, batch, argument) {
+    if (command === "play") {
+      acceptPlay(generation, argument, snapshot, batch);
+      return;
+    }
+    const target = run?.generation === generation ? run : void 0;
+    if (target === void 0) {
+      if (command === "seek" || command === "reverse" || command === "finish") {
+        acceptFreshControl(
+          generation,
+          command,
+          snapshot,
+          batch,
+          command === "seek" ? argument : void 0
+        );
+      } else if (command === "cancel") {
+        stageStatus(batch, snapshot, "cancelled");
+      } else if (command === "setPlaybackRate") {
+        storedPlaybackRate = argument;
+      }
+      return;
+    }
+    if (target.status === "ending") {
+      if (command === "seek" || command === "reverse" || command === "finish") {
+        releaseRun(target);
+        acceptFreshControl(
+          generation,
+          command,
+          snapshot,
+          batch,
+          command === "seek" ? argument : void 0
+        );
+      } else if (command === "setPlaybackRate") {
+        storedPlaybackRate = argument;
+      }
+      return;
+    }
+    if (command === "pause") {
+      if (target.status !== "paused") {
+        const previousStatus = target.status;
+        target.status = "paused";
+        target.unregisterAdvance?.();
+        target.unregisterAdvance = void 0;
+        stageStatus(batch, snapshot, "paused");
+        queueCurrentFrameCommitAcknowledgement((_committedSnapshot, outcome) => {
+          if (outcome.applied || disposed || run !== target || target.released) return;
+          target.status = previousStatus;
+          registerRun(target);
+          enqueue("pause", target.generation);
+        });
+      }
+      return;
+    }
+    if (command === "resume") {
+      if (target.status === "paused") {
+        const previousAnchorPosition = target.anchorPosition;
+        const previousAnchorLogicalTime = target.anchorLogicalTime;
+        target.status = "running";
+        target.anchorPosition = target.position;
+        target.anchorLogicalTime = snapshot.logicalTime;
+        stageStatus(batch, snapshot, "running");
+        registerRun(target);
+        queueCurrentFrameCommitAcknowledgement((_committedSnapshot, outcome) => {
+          if (outcome.applied || disposed || run !== target || target.released) return;
+          target.status = "paused";
+          target.anchorPosition = previousAnchorPosition;
+          target.anchorLogicalTime = previousAnchorLogicalTime;
+          target.unregisterAdvance?.();
+          target.unregisterAdvance = void 0;
+          enqueue("resume", target.generation);
+        });
+      }
+      return;
+    }
+    if (command === "cancel") {
+      cancelRun(target, snapshot, batch);
+      return;
+    }
+    if (command === "seek") {
+      const staticDuration = finiteDuration(getProgramRecord(target.program).duration);
+      const time = Math.max(0, staticDuration === void 0 ? argument : Math.min(argument, staticDuration));
+      target.pendingEvaluation = { kind: "seek", time };
+      target.anchorPosition = time;
+      target.anchorLogicalTime = snapshot.logicalTime;
+      registerRun(target);
+      return;
+    }
+    if (command === "reverse") {
+      target.direction = target.direction === "forward" ? "reverse" : "forward";
+      target.anchorPosition = target.position;
+      target.anchorLogicalTime = snapshot.logicalTime;
+      if (target.status === "running") registerRun(target);
+      return;
+    }
+    if (command === "setPlaybackRate") {
+      storedPlaybackRate = argument;
+      target.playbackRate = storedPlaybackRate;
+      target.anchorPosition = target.position;
+      target.anchorLogicalTime = snapshot.logicalTime;
+      return;
+    }
+    const unavailable = unavailableControlError(target.program, "finish");
+    if (unavailable !== void 0 && getProgramActivationRecord(target.activation).terminalDuration === void 0) {
+      queueDiagnosticError(snapshot, unavailable, target.registrationOrder);
+      return;
+    }
+    target.pendingEvaluation = { kind: "finish" };
+    registerRun(target);
+  }
+  const handle = Object.freeze({
+    status: status.asReadonly(),
+    currentTime: currentTime.asReadonly(),
+    play(playOptions = {}) {
+      if (disposed) return;
+      const conflict = playOptions.conflict ?? options.conflict ?? "error";
+      if (conflict !== "error" && conflict !== "replace") {
+        throw new TypeError('Pibbl animation playback conflict must be "error" or "replace".');
+      }
+      const generation = ++queuedGeneration;
+      enqueue("play", generation, conflict);
+    },
+    pause() {
+      enqueue("pause", queuedGeneration);
+    },
+    resume() {
+      enqueue("resume", queuedGeneration);
+    },
+    cancel() {
+      enqueue("cancel", queuedGeneration);
+    },
+    finish() {
+      enqueue("finish", queuedGeneration);
+    },
+    seek(milliseconds) {
+      if (disposed) return;
+      if (!Number.isFinite(milliseconds)) {
+        throw new RangeError("Pibbl animation playback seek time must be finite.");
+      }
+      enqueue("seek", queuedGeneration, milliseconds);
+    },
+    reverse() {
+      enqueue("reverse", queuedGeneration);
+    },
+    setPlaybackRate(rate) {
+      if (disposed) return;
+      if (!Number.isFinite(rate) || rate <= 0) {
+        throw new RangeError(
+          "Pibbl animation playback rate must be finite and greater than zero."
+        );
+      }
+      enqueue("setPlaybackRate", queuedGeneration, rate);
+    }
+  });
+  return Object.freeze({
+    handle,
+    adopt(nextProgram, nextOptions = {}) {
+      if (disposed) return;
+      const candidate = normalizeAnimationPlaybackCandidate(nextProgram, nextOptions);
+      program = candidate.program;
+      options = candidate.options;
+    },
+    committedSpringSnapshot() {
+      const target = run;
+      if (disposed || target === void 0 || target.released) return void 0;
+      const programRecord = getProgramRecord(target.program);
+      if (programRecord.kind !== "track") return void 0;
+      const definitionRecord = getDefinitionRecord(programRecord.definition);
+      if (definitionRecord.kind !== "spring") return void 0;
+      return sampleSpring(definitionRecord, target.position / 1e3);
+    },
+    retarget(nextProgram, nextOptions = {}) {
+      if (disposed) return;
+      const candidate = normalizeAnimationPlaybackCandidate(nextProgram, nextOptions);
+      program = candidate.program;
+      options = candidate.options;
+      if (pendingRetarget !== void 0) {
+        pendingRetarget.cancel();
+        if (pendingCommands.delete(pendingRetarget)) queuedCommands--;
+      }
+      const generation = ++queuedGeneration;
+      pendingRetarget = enqueue("play", generation, "replace");
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      queuedGeneration++;
+      for (const commandHandle of pendingCommands) {
+        commandHandle.cancel();
+        queuedCommands--;
+      }
+      pendingCommands.clear();
+      pendingRetarget = void 0;
+      if (run !== void 0) releaseRun(run);
+      if (delivery !== void 0) {
+        queuedMilestones -= delivery.events.length;
+        delivery.events.length = 0;
+        delivery.errors.length = 0;
+        delivery.terminalRuns.clear();
+      }
+      const schedulerPhase = snapshotRealmScheduler().phase;
+      if (schedulerPhase !== "advance" && schedulerPhase !== "render") {
+        status.set("disposed");
+      } else {
+        queueBeginCommand((snapshot, batch) => {
+          batch.stage(status, "disposed", metadataWriter);
+          recordSchedulerTrace({
+            kind: "animation-write",
+            frameId: snapshot.frameId,
+            logicalTime: snapshot.logicalTime,
+            debugName: debugName(),
+            target: "status",
+            outcome: "staged"
+          });
+        });
+      }
+    }
+  });
+}
+export {
+  animationPlaybackSnapshot,
+  createAnimationPlaybackController,
+  normalizeAnimationPlaybackCandidate
+};
+//# sourceMappingURL=playback.js.map