@cardstack/boxel-cli 0.11.0-unstable.1 → 0.11.0-unstable.2

package/bundled-types/choreo/index.ts

@@ -11,10 +11,12 @@ export type { Arming, ArmingOptions, ArmingRegion } from './arming.ts';
 export { createArming } from './arming.ts';
 export { beacon } from './beacon.ts';
 export type { BeaconRef } from './beacons.ts';
+export { registerBeacon } from './beacons.ts';
 export type { Changeset } from './changeset.ts';
 export type { ChoreoContext } from './choreo.gts';
 export { Choreo } from './choreo.gts';
 export { easeIn, easeInAndOut, easeOut } from './easings.ts';
+export { registerSettle } from './far.ts';
 export type { GestureRef } from './gesture.ts';
 export {
   type ChoreoHost,

package/bundled-types/choreo/run.ts

@@ -184,6 +184,13 @@ interface RunOptions {
   inherit?: Velocities;
   /** where the prior run's ambient loops stood, to carry them on from */
   loops?: LoopPhases;
+  /**
+   * The most animation time, in ms, one painted frame may advance. Unset,
+   * a frame advances by the time since the last one (the frame loop caps
+   * that at 40 ms). Set, a run behind a long frame slows down rather than
+   * skipping: it lands later, and no frame jumps.
+   */
+  maxFrameStep?: number;
   /** a camera step landed or the run ended: the frame's new resting state */
   onCamera?(state: CameraState): void;
   /**
@@ -396,6 +403,18 @@ interface Track {
   wire?: SVGPathElement;
 }
 
+let warnedPrivateFields = false;
+/** @maxFrameStep reads motion-dom's private animation fields; say once when they are gone */
+function warnPrivateFieldsMoved() {
+  if (warnedPrivateFields) {
+    return;
+  }
+  warnedPrivateFields = true;
+  console.warn(
+    '@cardstack/choreo: motion-dom no longer exposes the animation fields @maxFrameStep reads (_animation, startTime, holdTime); a long frame will skip tweens ahead instead of slowing them',
+  );
+}
+
 export class ChoreoRun implements Run {
   cues: Cue[];
   velocities: Velocities = new Map();
@@ -454,6 +473,17 @@ export class ChoreoRun implements Run {
   private ended = false;
   private resolveFinished!: () => void;
   private ticking = false;
+  /**
+   * The next tick is the first since the clock started (or resumed): it
+   * paints the run where it stands and advances nothing. The frame loop's
+   * delta on that tick is the time since ITS last frame, up to 40 ms, so a
+   * run started by a render pass would otherwise open with that whole step
+   * on its own clock: every cue the clock starts, gates, or drives frame by
+   * frame (a camera, a wire, a later cue's start) would begin that far in.
+   */
+  private freshClock = false;
+  /** the frame timestamp holdBack saw last, while a maxFrameStep applies */
+  private lastStamp: number | undefined;
   private autoTimer: ReturnType<typeof setTimeout> | undefined;
 
   constructor(compiled: Compiled, options: RunOptions) {
@@ -895,6 +925,12 @@ export class ChoreoRun implements Run {
       return;
     }
     this.ticking = true;
+    this.freshClock = true;
+    this.lastStamp = undefined;
+    if (this.options.maxFrameStep) {
+      // read runs before update: the animations tick after the hold-back
+      frame.read(this.holdBack, true);
+    }
     frame.update(this.tick, true);
   }
 
@@ -902,15 +938,82 @@ export class ChoreoRun implements Run {
     if (this.ticking) {
       this.ticking = false;
       cancelFrame(this.tick);
+      cancelFrame(this.holdBack);
     }
   }
 
+  /**
+   * maxFrameStep for the animations themselves. The run's own clock is
+   * capped in tick; the tweens and springs it started run on motion-dom's
+   * frame clock, which takes the real time since their start, so a long
+   * frame would still skip that much of them. Before they update, each one
+   * driven on the main thread has its start moved on by the time past the
+   * cap: it resumes from where the last frame left it, plus one step.
+   * Animations on the compositor (WAAPI) kept playing through the long
+   * frame and are left alone.
+   */
+  private holdBack = (data: FrameData) => {
+    const step = this.options.maxFrameStep;
+    const last = this.lastStamp;
+    this.lastStamp = data.timestamp;
+    if (!step) {
+      return;
+    }
+    // The first frame: an animation the render pass started takes its start
+    // from motion-dom's clock, which holds one time for a whole task, so a
+    // pass late in a long render would date it back to the task's start and
+    // its first frame would skip that far. Its start moves to this frame.
+    // After that: the time past the cap since the last frame.
+    for (const t of this.tracks) {
+      for (const c of t.controls ?? []) {
+        // the wrapper's resolved animation, read without the getter that
+        // flushes pending keyframes. These are motion-dom's private fields
+        // (VENDORED.md lists them for a bump to check): past the first frame
+        // every control has resolved, so a control without them means the
+        // fields moved and the cap no longer reaches the tweens.
+        const inner = (c as unknown as { _animation?: object })._animation as
+          | { holdTime?: number | null; startTime?: number | null }
+          | undefined;
+        if (
+          last !== undefined &&
+          (!inner ||
+            (!('animation' in inner) &&
+              !('startTime' in inner && 'holdTime' in inner)))
+        ) {
+          warnPrivateFieldsMoved();
+        }
+        if (
+          !inner ||
+          'animation' in inner ||
+          typeof inner.startTime !== 'number' ||
+          inner.holdTime !== null
+        ) {
+          continue;
+        }
+        if (last === undefined) {
+          if (data.timestamp - inner.startTime > step) {
+            inner.startTime = data.timestamp;
+          }
+        } else if (data.timestamp - last > step) {
+          inner.startTime += data.timestamp - last - step;
+        }
+      }
+    }
+  };
+
   private tick = (data: FrameData) => {
     if (!this.playing || this.cancelled || this.ended) {
       this.stopTicking();
       return;
     }
-    const next = this.master + data.delta * this.rate;
+    const step = this.options.maxFrameStep;
+    const delta = this.freshClock
+      ? 0
+      : step
+        ? Math.min(data.delta, step)
+        : data.delta;
+    this.freshClock = false;
+    const next = this.master + delta * this.rate;
     const gate = this.gates.find(
       (g) => !g.opened && g.at >= this.master && g.at <= next,
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.11.0-unstable.1",
+  "version": "0.11.0-unstable.2",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",

package/bundled-test-harness/assets/choreo-B3Z9QhDH.js

@@ -1,2 +0,0 @@
-import { t as Choreo } from "./choreo-CJfBb_EY.js";
-export { Choreo, Choreo as default };

package/bundled-test-harness/assets/clip-BjcXuTwN.js

@@ -1,2 +0,0 @@
-import { t as Clip } from "./clip-C_pXjVvY.js";
-export { Clip };

package/bundled-test-harness/assets/film-DMDPP7ma.js

@@ -1,2 +0,0 @@
-import { r as TICK, t as Film } from "./film-D7vtJO5q.js";
-export { Film, TICK };

package/bundled-test-harness/assets/plate-66qnQ-M9.js

@@ -1,2 +0,0 @@
-import { t as Plate } from "./plate-CFvCDv2t.js";
-export { Plate };

package/bundled-test-harness/assets/player-pygg1PwA.js

@@ -1,2 +0,0 @@
-import { n as Menu, r as Player, t as Burst } from "./player-DzuYjrTU.js";
-export { Burst, Menu, Player };

package/bundled-test-harness/assets/titles-Ccpcl-jq.js

@@ -1,2 +0,0 @@
-import { n as Gate, t as EndCard } from "./titles-B1pTaIfP.js";
-export { EndCard, Gate };